cli AGENTS.md

Agent Guide for @photon-ai/cli

Mission

You're updating this CLI in response to upstream API changes in @photon-ai/dashboard-api. The API type contract arrives as a version bump of that dependency (in package.json/bun.lock). Your job: make bun run check pass.

Hard Rules (CI will fail if violated)

1. Use Bun exclusively — never Node, npm, pnpm, yarn
2. Never hand-edit API types — they come from the @photon-ai/dashboard-api dependency; update them by bumping its version
3. Never add forbidden dependencies: axios, chalk, zod, jest, vitest, ts-node, ws, express, dotenv, ioredis, pg, better-sqlite3
4. Every command must use getApi() from ~/lib/api.ts + Eden treaty pattern — never raw fetch()
5. Destructure Eden responses as { data, error, status } — check error before using data
6. Handle 401 by throwing SessionExpiredError (caught centrally in handleTopLevelError)
7. Never delete or rewrite snapshot files without justification in PR body under "## Snapshot changes"
8. One PR = one upstream version bump — don't bundle refactors
9. Never modify files in .github/workflows/ or scripts/agent-flow/

Soft Rules (reviewer will flag)

• Match the style in src/commands/projects.ts: same option ordering (--api-host, -t/--token, --json), same error handling
• New DTOs go in src/lib/types.ts, cast at the API boundary
• Prefer adding fields to existing DTOs over creating parallel types
• All user-facing output uses c.dim(), c.success(), c.error() from ~/lib/output.ts
• Comments only when intent isn't obvious from the code

Anti-patterns (we've seen AI do these — don't)

• Splitting the Project DTO into one type per command
• Adding try/catch around every getApi() call (handled centrally in src/index.ts#handleTopLevelError)
• Using console.log(JSON.stringify(...)) instead of the output helpers
• Replacing picocolors with chalk
• Using node:fs instead of Bun.file
• Adding dotenv (Bun auto-loads .env)
• Importing from @elysiajs/eden directly instead of using getApi()