# CLI Integration Standard (API Passthrough)

Standard for exposing reliable CLI access to a web app without duplicating business logic.

## Core rule

- API/server is the single source of truth for domain logic.
- CLI is a client of that API.
- CLI must not call the database directly.

If behavior is missing for CLI, add endpoint/service logic in API first, then call it from CLI.

## Required project structure

```text
project-root/
├── src/app/api/...            # API routes
├── src/lib/server/...         # business/domain logic
├── scripts/
│   ├── lib/
│   │   └── api_client.sh      # shared transport helper
│   ├── <resource>.sh          # task/project/sprint style command groups
│   ├── <wrapper>.sh           # optional umbrella script
│   ├── README.md              # command docs
│   └── tests/
│       ├── *.test.ts          # unit tests for shared logic
│       └── *.sh               # mocked CLI contract tests
└── README.md
```

## CLI responsibilities

- Parse args and flags.
- Resolve user-friendly names to IDs (via API calls).
- Call API endpoints.
- Format output and errors.

Do not implement:

- status/sprint/date/business transition logic
- server-side validation rules
- persistence logic
- auth policy logic

## Configuration

Preferred runtime variables:

- `API_URL` (for example `http://localhost:3000/api`)
- `GANTT_COOKIE_FILE` (or equivalent session cookie path)

Do not require service-role DB keys in CLI scripts.

## Testing requirements

Every CLI-enabled project must include:

1. API/domain unit tests
2. API route/integration tests
3. CLI contract tests with mocked transport

## CLI contract mock pattern

For shell CLIs:

- mock `curl` via `PATH` override
- log `METHOD URL PAYLOAD`
- return fixture JSON + HTTP codes
- fail on unhandled endpoint calls
- assert expected endpoint calls were made

Also assert no direct DB references remain in `scripts/` (for example `rest/v1`, service keys).

## Verification checklist

- [ ] CLI scripts only call API
- [ ] No direct DB credentials/queries in CLI
- [ ] Missing CLI behavior added to API first
- [ ] Tests added/updated (unit + mocked contract)
- [ ] Refactor suite runs in CI
- [ ] `scripts/README.md` and root `README.md` are updated

## Migration guide (direct DB CLI -> API passthrough CLI)

1. Inventory commands and duplicated logic.
2. Implement needed behavior in API/server modules.
3. Replace CLI DB calls with `api_call` helper.
4. Add mocked contract tests that cover all command families.
5. Remove old DB code and env vars from scripts.
6. Update docs and CI gates.