mirror of
https://github.com/callstack/agent-device.git
synced 2026-09-14 20:06:34 +08:00
Michał Pierzchała
da76aa4f1e
* refactor(commands): declare project-config admission and recorder sanitization on the flag declaration Move the two fail-closed flag properties — may a key be set from a project `agent-device.json`, and does the session recorder copy it into `SessionAction.flags` — off the hand-maintained allowlists and onto each `FlagDefinition` as required `projectConfig` / `recorded` fields. Omitting either is now a type error, so the compiler holds the fail-closed property a list held by omission. - 156 declarations carry both fields; the 6 screenshot-specific definitions carry them too. Populated to match the old sets exactly (one-off diff empty: 85 project-config and 39 recorded keys, byte-for-byte). - `cli-config.ts` and `session-action-recorder.ts` derive their sets from the registry and no longer list keys; `RECORDED`/`PROJECT_CONFIG` derivations recomputed per call so a consumer builds its set at its own module load. Recorder reaches the derivation through the `cli-schema/command-schema.ts` seam (daemon may not import `commands/`). - Planted-divergence tests, per #2421: flipping one declaration's field moves the admission/sanitization outcome through the production derivation, plus a compile-time pin that an incomplete declaration does not build. - `docs/agents/cli-flags.md` now points at the declaration fields, not the allowlist. Refs #2445 * refactor(commands): return the recorded keys as a set, matching project-config Both derivations answer the same question — the set of flag keys a surface admits — so both return ReadonlySet<FlagKey>. Drops a needless set-then-spread on the recorder path; consumers already iterate the value. Refs #2445 * fix(commands): keep the CommandFlags guard on recorded flag declarations The deleted `SANITIZED_FLAG_KEYS` was `satisfies readonly (keyof CommandFlags)[]`, so every recorded key had to be a `CommandFlags` key. The derived set returns `FlagKey` and the recorder indexed it through a cast, so `recorded: true` on a CLI-only key (`daemonAuthToken`, `help`, …) compiled and could leak an uncarrable value into a recorded action. State the constraint on the declaration: `FlagDefinition` is a union that locks `recorded` to `false` for a `NonRecordableFlagKey = Exclude<FlagKey, keyof CommandFlags>`. `recordedFlagKeys()` returns `ReadonlySet<RecordableFlagKey>` via a narrowing predicate, so `sanitizeFlags` drops its cast. Adds a `@ts-expect-error` test that a CLI-only key cannot opt into recording. Refs #2445
58 lines
4.1 KiB
Markdown
58 lines
4.1 KiB
Markdown
# Adding a CLI Flag
|
|
|
|
Thread a flag only through the layers that consume it:
|
|
|
|
1. `packages/contracts/src/cli-flags.ts`: add to `CliFlags`; add the definition to the matching
|
|
`src/commands/cli-grammar/flag-definitions-*.ts` owner and the relevant group in `flag-groups.ts`
|
|
(for example `SNAPSHOT_FLAGS`). Then update the command family metadata/schema that exposes the
|
|
flag; find the owner with
|
|
`rg -n "<command>|supportedFlags|allowedFlags" src/commands src/cli-schema src/cli/parser`. For
|
|
schema-only CLI commands, the owner is `SCHEMA_ONLY_CLI_COMMAND_SCHEMAS` in
|
|
`src/cli-schema/command-overrides.ts`. Every flag declaration states `projectConfig`
|
|
(may be set from a project `agent-device.json`) and `recorded` (the session recorder
|
|
copies it into `SessionAction.flags`). Both are required, so a new declaration that
|
|
omits either does not compile — that, not an allowlist, is the completeness gate. Set
|
|
`projectConfig: true` only when repository control is safe; a new flag is otherwise
|
|
operator-only. Set `recorded: true` only when a `.ad` recording must carry the flag.
|
|
2. `src/commands/cli-grammar/*`: read the CLI flag into command input.
|
|
3. `src/commands/command-projection.ts` and command-family projection helpers: write the input into
|
|
the daemon request only if the flag affects daemon execution.
|
|
4. `src/commands/*-command-contracts.ts`: add to the command input schema only if the option should
|
|
be available through Node.js or MCP as structured input. An input key that names a credential,
|
|
an endpoint a credential is sent to, or operator infrastructure declares `operatorField(...)`
|
|
(`src/commands/command-input.ts`), which is what keeps the MCP and AI SDK tool schemas from
|
|
offering the model a parameter to write it into. One of the shared common keys declares the same
|
|
audience in its `src/commands/common-input-fields.ts` row instead.
|
|
5. `src/client/client-types.ts`: update the public typed client option only when the Node.js
|
|
interface exposes it.
|
|
6. `src/client/client-normalizers.ts`: update daemon flag normalization only when the request still
|
|
needs a public-to-internal translation.
|
|
7. `src/daemon/context.ts` and `src/core/dispatch-context.ts`: add the field only when it flows into
|
|
platform dispatch.
|
|
8. Handler/platform modules: thread the option only after the command surface, grammar, and
|
|
projection prove it belongs there.
|
|
9. `scripts/integration-progress-model.ts`: classify the flag (device-observable vs
|
|
intentionally-outside). The architecture-progress gate fails CI on unclassified public flags.
|
|
10. If the flag changes interaction semantics, revisit the affected cells in
|
|
`packages/contracts/src/interaction-guarantees.ts` (scope with `appliesTo` when the flag exists only on
|
|
some commands).
|
|
|
|
Command-only flags (like `find --first`) that never reach the platform layer usually stop at
|
|
steps 1-3, plus step 9.
|
|
|
|
## Where CLI help and schema live
|
|
|
|
- Long help prose: `src/cli-schema/cli-help.ts`. Flag definitions: `src/commands/cli-grammar/`.
|
|
- Synopsis: `src/cli-schema/usage.ts` generates the `[label]` flag tail from `allowedFlags`, so a
|
|
new option reaches `--help` without any synopsis edit. Declare `usageFlags` on the command only
|
|
when its synopsis names fewer options: `[]` for a synopsis that is pure grammar (or writes its own
|
|
mutually-exclusive brackets), otherwise the subset it names. `Command flags:` always lists
|
|
everything in `allowedFlags`. Keep a cross-cutting opt-in out of every synopsis with
|
|
`usageHidden: true` on its flag definition. `src/cli-schema/usage.test.ts` fails a tail that names
|
|
an option the command does not accept, or one the hand-written grammar already wrote.
|
|
- Command-specific usage/flag metadata lives with the command family metadata that owns the command.
|
|
- Parser/help *rendering* stays in `src/cli/parser/`; command schema metadata is derived from command
|
|
metadata, family declarations, and the schema-only merge path in
|
|
`src/cli-schema/command-overrides.ts`. Keep the two separate.
|
|
- Locating an owner: `rg -n "helpDescription|summary|supportedFlags|allowedFlags" src/commands src/cli/parser src/cli-schema`.
|