mirror of
https://github.com/callstack/agent-device.git
synced 2026-09-14 20:06:34 +08:00
Michał Pierzchała
bf26ab14d6
"Who may write this input field, on which surface" was expressed three times,
each a separate name-keyed mechanism: `retiredField()` in the command field
maps, `ALWAYS_HIDDEN_FIELDS` in the AI SDK adapter, and
`OPERATOR_INPUT_GUIDANCE` / `CONFIG_LOADER_GUIDANCE` at the MCP admission
boundary -- twelve hand-written refusal sentences keyed by name, far from the
fields they govern.
The root cause was that the ~19 shared common fields existed only as parallel
enumerations by name -- `commonProperties()`, `readCommonInput()`,
`commonToClientOptions()`, and the `CommonCommandInput` type -- carrying no
metadata, so any policy about a field forced a new name-keyed map elsewhere.
Declare each common field once, in `commands/common-input-fields.ts`, keyed by
its input key and carrying `{ schema?, read?, clientKey?, audience? }`. The JSON
schema, the readers, the client-options projection, and the model-facing
audience boundary all derive from that one table, and `satisfies Record<keyof
CommonCommandInput | 'target', ...>` makes a row without a field, or a field
without a row, a type error in both directions.
`audience` is the unified vocabulary (`commands/input-audience.ts`): `operator`
keys stay in the CLI and Node schemas but are hidden from and refused by every
model-facing tool schema; `retired` keys are absent from every schema yet still
recognized, so they answer with migration guidance. `retiredField()` now sets
`audience: 'retired'`, metro's `bearerToken`/`proxyBaseUrl` declare
`audience: 'operator'` at the field, and `stateDir` declares it in the new
`mcp/tool-control-fields.ts` beside the other MCP-only tool arguments. Refusal
guidance is rendered from each declaration's operator path -- env var names via
`buildPrimaryEnvVarName`, the operator config file, or an explicit sentence --
rather than hand-written per key, and `OperatorInputSource` is shaped so a
declaration naming no path at all does not typecheck.
`#2076`'s nested-step admission recurses through the same derived
`findInadmissibleInput`, so a batch step's refusals come from this audience map
rather than a second filter; its suite passes against this unchanged.
A field-level audience only reaches the boundaries through its command's
metadata, so that wiring is closed structurally rather than by convention:
`inputAudience` is required on `CommandMetadata`, and
`defineFieldCommandMetadata` -- which now takes an optional custom reader, so
`batch` and `gesture` go through it too -- is the only construction path for a
field-map command. At the boundary, a command's own audiences merge before the
global operator classifications, so an `operator` key outranks a colliding
per-command `retired` one and a name collision fails closed.
`command-input.ts` was 705 lines and over the 300-line target; the record
readers move to `commands/input-readers.ts` so the table can use them without an
import cycle. `click`/`press`/`fill` move onto `defineFieldCommandMetadata` --
they were that helper inlined.
`COMMON_COMMAND_SUPPORTED_FLAG_KEYS` stays hand-maintained: it is the CLI
parser's axis, and 25 of its 42 keys never become structured command input while
the table's `cwd` and `debug` are not flags. The reasoning is recorded above the
constant.
Purely internal: `listCommandTools()`, the CLI command schemas, and every
command `inputSchema` are byte-identical, verified by diffing the serialized
surfaces before and after.
Refs #2027
50 lines
3.3 KiB
Markdown
50 lines
3.3 KiB
Markdown
# Adding a CLI Flag
|
|
|
|
A new flag touches only the layers that need to understand it. Stop at the layer where it stops
|
|
mattering — threading it further is the common failure, not stopping too early.
|
|
|
|
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 (`cdp`, `auth`, `connect`, `proxy`, `react-devtools`, `web`) the owner is
|
|
`SCHEMA_ONLY_CLI_COMMAND_SCHEMAS` in `src/cli-schema/command-overrides.ts`. New flags are
|
|
operator-only by default. Add a flag to `PROJECT_CONFIG_FLAG_KEYS` in
|
|
`src/cli-schema/cli-config.ts` only when repository control is safe; this positive allowlist is
|
|
the completeness gate.
|
|
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/`.
|
|
- 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`.
|