126 lines
3.7 KiB
Markdown
126 lines
3.7 KiB
Markdown
# API-Centric CLI Pattern (Skill Blueprint)
|
|
|
|
## Goal
|
|
|
|
Define one final implementation path for product logic:
|
|
|
|
- API = single source of truth for business logic
|
|
- CLI = passthrough client to API only
|
|
- Tests = mandatory, with mocks, for both API behavior and CLI contracts
|
|
|
|
Use this pattern when building or refactoring any web app that exposes both a UI and CLI.
|
|
|
|
## Non-Negotiable Rules
|
|
|
|
1. All business logic lives in API/server code.
|
|
2. CLI scripts must not implement decision logic, validation rules, or data model behavior.
|
|
3. CLI scripts only:
|
|
- parse args
|
|
- resolve user-friendly identifiers (if needed)
|
|
- call API endpoints
|
|
- format output/errors
|
|
4. If CLI needs behavior that API does not expose, add it to API first.
|
|
5. No direct DB calls from CLI.
|
|
6. Every change requires tests.
|
|
7. Every CLI test suite must run against a mocked API transport.
|
|
|
|
## Architecture Contract
|
|
|
|
## Source of truth
|
|
|
|
- Domain rules: API
|
|
- State transitions: API
|
|
- Date/sprint logic: API/shared server module
|
|
- Persistence: API + data layer
|
|
- Auth/session policy: API
|
|
|
|
## Client responsibilities
|
|
|
|
- Web UI: call API, render state
|
|
- CLI: call API, render terminal output
|
|
- Both are clients of the same backend contract
|
|
|
|
## Refactor Pattern (DB-calling CLI -> API passthrough CLI)
|
|
|
|
1. Inventory CLI commands and all direct DB access.
|
|
2. Create/confirm matching API endpoints.
|
|
3. Move duplicated logic into API modules.
|
|
4. Rewrite CLI commands to call API endpoints only.
|
|
5. Keep one shared API client helper in CLI (`api_call`).
|
|
6. Remove DB env vars/credentials from CLI.
|
|
7. Add regression tests before removing old paths.
|
|
8. Delete dead logic after tests pass.
|
|
|
|
## Testing Standard
|
|
|
|
## Required layers
|
|
|
|
1. API unit tests
|
|
- domain logic (date windows, status transitions, validation, selectors)
|
|
2. API route/integration tests
|
|
- request/response shape, status codes, error handling
|
|
3. CLI contract tests with mocked API transport
|
|
- assert commands hit correct endpoints/methods/payload paths
|
|
- assert cookie/session handling
|
|
- assert no direct DB references remain
|
|
|
|
## Mock requirements for CLI tests
|
|
|
|
- Replace network transport (for shell CLIs, mock `curl` in `PATH`).
|
|
- Log request triples: `METHOD URL PAYLOAD`.
|
|
- Return deterministic fixtures per endpoint.
|
|
- Fail test on unhandled endpoint calls.
|
|
- Assert expected calls occurred.
|
|
|
|
## Definition of done for a refactor
|
|
|
|
- All CLI commands route through API.
|
|
- No direct DB references in CLI codebase.
|
|
- Shared business logic exists in API/server modules only.
|
|
- Tests pass locally and in CI.
|
|
- API contract changes are documented.
|
|
|
|
## Anti-Patterns to Block
|
|
|
|
- CLI reads DB tables directly "for convenience"
|
|
- CLI re-implements sprint/task/business status logic
|
|
- API and CLI each have separate versions of the same selector/validator
|
|
- "Temporary" bypasses that never get removed
|
|
|
|
## Recommended Repository Layout
|
|
|
|
```text
|
|
src/
|
|
app/api/...
|
|
lib/server/domain/...
|
|
scripts/
|
|
lib/api_client.sh
|
|
task.sh
|
|
project.sh
|
|
sprint.sh
|
|
tests/
|
|
refactor-cli-api.sh
|
|
*.test.ts
|
|
```
|
|
|
|
## PR Checklist (copy/paste)
|
|
|
|
- [ ] No business logic added to CLI.
|
|
- [ ] Needed behavior implemented in API first.
|
|
- [ ] CLI commands call API endpoints only.
|
|
- [ ] Direct DB access removed from CLI.
|
|
- [ ] Unit tests added/updated for moved logic.
|
|
- [ ] CLI mock-contract tests added/updated.
|
|
- [ ] Unhandled endpoint calls fail tests.
|
|
- [ ] CI includes the refactor test suite.
|
|
|
|
## Skill Conversion Notes
|
|
|
|
If converting this into a reusable skill:
|
|
|
|
1. Skill name suggestion: `api-cli-passthrough`.
|
|
2. Put these rules in `SKILL.md`.
|
|
3. Include reusable test harness scripts under `scripts/`.
|
|
4. Include endpoint/contract references under `references/`.
|
|
5. Trigger when user asks to build/refactor web API + CLI with no logic duplication.
|