mirror of https://github.com/callstack/agent-device.git synced 2026-09-14 20:06:34 +08:00

Files

T

Michał Pierzchała da76aa4f1e refactor(commands): declare project-config admission and recorder sanitization on the flag declaration (#2453 )

* 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

2026-09-10 17:04:32 +02:00

4.1 KiB

Raw Permalink Blame History

Adding a CLI Flag

Thread a flag only through the layers that consume it:

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.
src/commands/cli-grammar/*: read the CLI flag into command input.
src/commands/command-projection.ts and command-family projection helpers: write the input into the daemon request only if the flag affects daemon execution.
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.
src/client/client-types.ts: update the public typed client option only when the Node.js interface exposes it.
src/client/client-normalizers.ts: update daemon flag normalization only when the request still needs a public-to-internal translation.
src/daemon/context.ts and src/core/dispatch-context.ts: add the field only when it flows into platform dispatch.
Handler/platform modules: thread the option only after the command surface, grammar, and projection prove it belongs there.
scripts/integration-progress-model.ts: classify the flag (device-observable vs intentionally-outside). The architecture-progress gate fails CI on unclassified public flags.
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.

4.1 KiB Raw Permalink Blame History

Adding a CLI Flag

Where CLI help and schema live

4.1 KiB

Raw Permalink Blame History