gantt-board/docs/API_CLI_PASSTHROUGH_PATTERN.md

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

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.