AGENTS.md

1# AGENTS.md — `src/commands/`
2 
3Per-command agent-optimized usage and structure guide.
4 
5## Command folder convention
6 
7Every command is a folder. `index.ts` is the command class file. All related
8code — business logic, helpers, tests, and optional agent guide — colocates inside
9the folder. Subcommands are subfolders.
10 
11```
12src/commands/
13  <topic>/
14    <verb>/
15      index.ts        ← command class (extends DifyCommand; the ONLY file the registry discovers)
16      run.ts          ← optional behavior owner (not a command, invisible to the registry)
17      handlers.ts     ← helpers
18      guide.ts        ← agent guide string (optional)
19      *.test.ts       ← tests
20    <nested-verb>/    ← subcommand (e.g. auth/devices/list/)
21      index.ts
22    _shared/          ← intra-topic shared code (only when needed by 2+ siblings)
23      <shared>.ts
24```
25 
26The registry generator (`pnpm tree:gen` → `src/commands/tree.generated.ts`) discovers
27commands only via `**/index.+(js|cjs|mjs|ts)`. All other files in command
28folders are invisible to the registry — add freely without glob exclusions.
29Folders prefixed with `_` (e.g. `_shared/`, `_strategies/`) are excluded from
30registry discovery and from coverage checks.
31 
32## Adding a new command
33 
341. Create `src/commands/<topic>/<verb>/index.ts` extending `DifyCommand`.
351. Keep small owner-local behavior in `index.ts`; extract sibling modules such as `run.ts` or `handlers.ts` when logic needs independent tests, reuse, or a clearer owner.
361. Run `pnpm tree:gen` to regenerate the command tree (also runs implicitly via `prebuild`/`predev`/`pretest`).
371. Run `pnpm test` to verify coverage.
38 
39## Adding an agent guide
40 
41<!-- prettier-ignore -->
421. Create `src/commands/<topic>/<verb>/guide.ts` exporting a plain string:
43```ts
44   export const agentGuide = `
45   WORKFLOW
46     1. ...
47
48   ERROR RECOVERY
49     ...
50   `
51```
521. Import and assign in `index.ts`:
53```ts
54   import { agentGuide } from './guide.js'
55 
56   export default class MyCmd extends DifyCommand {
57     override agentGuide(): string {
58       return agentGuide
59     }
60   }
61```
621. The guide appears at the bottom of `difyctl <cmd> --help` automatically.
631. Agents call `difyctl <cmd> --help` to read both structural help and workflow guidance.
64 
65## Shared utilities
66 
67Code used by two or more commands lives in `src/<domain>/` (e.g. `src/auth/`,
68`src/api/`, `src/errors/`). Do not put broadly shared code inside a command folder.
69Intra-topic shared code (used only within one topic's commands) uses `_shared/`
70within that topic folder.
71