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

Files

T

Michał Pierzchała bf26ab14d6 refactor(commands): one audience table for common input fields (#2074 )

"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

2026-08-27 14:03:09 +02:00

3.3 KiB

Raw Permalink Blame History

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.

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.
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/.
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.

3.3 KiB Raw Permalink Blame History

Adding a CLI Flag

Where CLI help and schema live

3.3 KiB

Raw Permalink Blame History