91 lines
2.6 KiB
Markdown
91 lines
2.6 KiB
Markdown
# 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.
|