Skip to content

Commit 18d1058

Browse files
thymikeeclaude
andauthored
refactor: extract command surface and separate CLI presentation (#4100)
* refactor(command-surface): extract command declarations into a package Move the command metadata, input schemas, CLI grammar, request projection, MCP output schemas and the client port out of `src/commands` into the private `@agent-device/command-surface` package, which exposes one named entry. Command facets no longer carry a CLI output formatter. Formatters stay in the root, keyed by `CommandName` in `src/commands/cli-output.ts` with a duplicate guard, so the SDK and request projection load no CLI presentation. The `AgentDeviceClient` and `AgentDeviceCommandClient` declarations now live in the package, and `src/client/client-types.ts` re-exports exactly those two names. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs(command-surface): record the declaration and presentation split Amend ADR 0008 and the agent ownership and CLI flag guides for the `@agent-device/command-surface` package and the root presentation layer. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(command-surface): follow the replay declaration to the package in the startup closure guard Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(command-surface): narrow projection names and pin formatter bindings * Address command surface review feedback * docs(command-surface): state config defaults precisely and align fold hinge-angle wording Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs: keep ownership guidance within budget * test(command-surface): pin batch names to daemon writers --------- Co-authored-by: Claude Sonnet 5.5 <[email protected]>
1 parent 65ec68b commit 18d1058

222 files changed

Lines changed: 1853 additions & 1431 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.fallowrc.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -289,7 +289,7 @@
289289
"exports": ["IS_PREDICATE_USAGE_HINT"]
290290
},
291291
{
292-
// Workspace-package symbols whose only consumers are test-tree files, which --production analysis does not see. Each import is the package specifier, so the façade entry is load-bearing: parseTargetAnnotationV1Payload from packages/selectors/src/target-evidence.test.ts, MAESTRO_COMPAT_* from src/cli/parser/__tests__/maestro-support-matrix.test.ts, SCRIPT_FLAG_COMMANDS/scriptFlagEntries from src/commands/replay/script-flag-admission.test.ts (the #3197 two-way drift guard between the .ad grammar and the CLI schema).
292+
// Workspace-package symbols whose only consumers are test-tree files, which --production analysis does not see. Each import is the package specifier, so the façade entry is load-bearing: parseTargetAnnotationV1Payload from packages/selectors/src/target-evidence.test.ts, MAESTRO_COMPAT_* from src/cli/parser/__tests__/maestro-support-matrix.test.ts, SCRIPT_FLAG_COMMANDS/scriptFlagEntries from packages/command-surface/src/replay/script-flag-admission.test.ts (the #3197 two-way drift guard between the .ad grammar and the CLI schema).
293293
"file": "packages/{ad-script,maestro,capture-kit}/src/index.ts",
294294
"exports": [
295295
"parseTargetAnnotationV1Payload",

‎docs/adr/0008-command-descriptor-registry.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Amended by [ADR 0019](0019-request-bound-platform-runtime.md): device capability
1111
- Declare each command once in the descriptor registry. Compose the declaration from facets owned by their domains. No second table declares the same traits.
1212
- Derive every shared consumer table as a pure projection. Do not copy a derived classification back into a consumer as a hand-authored set.
1313
- Keep a narrow fact on the descriptor when several projections consume it: `timeoutPolicy`, `recordingEffect`, `postActionObservation`.
14-
- Keep grammar, decoding, executable surface metadata, and client invocation in `src/commands/**`. Keep shared option and result data in domain contracts. Keep the client facade in the client layer.
14+
- Keep grammar, decoding, executable surface metadata, request projection, and client invocation in `@agent-device/command-surface`. Keep CLI output formatters, help, and progress in `src/commands/`. A command facet declares no formatter. Keep shared option and result data in domain contracts. The package declares the client port once. The client layer re-exports it.
1515
- Declare daemon route and request policy in the separately typed `daemon` facet. Derive the daemon registry from it. Expose request-policy predicates only through the daemon registry.
1616
- Request modules consume named predicates. Handler modules own execution logic only. Neither recreates command sets or coverage tables.
1717
- Public grammar, client options, MCP schemas, help, and capability contracts must not derive from daemon-only traits. A diagnostic display, such as `command explain`, may show them.
@@ -32,7 +32,11 @@ Keep a narrow fact on the descriptor when more than one projection consumes it.
3232

3333
### Domain-owned surfaces
3434

35-
Keep CLI grammar, input decoding, executable surface metadata, and client-backed invocation in `src/commands/**`. Keep shared option and result shapes in domain contracts under `packages/contracts/src`: both surfaces need that vocabulary, so a shared shape sits below both. A type-only dependency on the `AgentDeviceClient` facade from a command module is an accepted ratchet-bounded position, not shared data that must move to contracts. The facade declares its signatures in that vocabulary. Add a type projection only when it removes real duplication across consumers.
35+
Keep CLI grammar, input decoding, executable surface metadata, request projection, and client-backed invocation in `@agent-device/command-surface`. The package exposes one entry, `.`, that names its exports. Keep shared option and result shapes in domain contracts under `packages/contracts/src`: both surfaces need that vocabulary, so a shared shape sits below both.
36+
37+
The package declares the client port, `AgentDeviceClient` and `AgentDeviceCommandClient`, once, in contracts and command-registry vocabulary. The command definitions invoke that port. `src/client/client-types.ts` re-exports exactly those two port names from the package. Its other published vocabulary is unchanged, so the published SDK types do not change and the package has no edge into the client layer. Add a type projection only when it removes real duplication across consumers.
38+
39+
Keep CLI presentation in `src/commands/`: output formatters, the warning dispatcher, help, and progress. A formatter is keyed by `CommandName` in `src/commands/cli-output.ts`, and a duplicate key throws when the table builds. The package reaches no root module, so request projection and the SDK load no presentation.
3640

3741
The client `invoke` seam is cross-process; the daemon `execute` seam runs the platform handler inside the daemon process. The process boundary is never collapsed.
3842

@@ -74,4 +78,5 @@ About ten hand-maintained tables once repeated command identity, route membershi
7478

7579
## Decision history
7680

81+
- 2026-10-30 — the command declaration surface moved to `@agent-device/command-surface`. Formatters left the facets for a `CommandName`-keyed table in `src/commands/cli-output.ts`, so the SDK no longer evaluates CLI presentation. The client port is declared in the package and re-exported by the client layer.
7782
- 2026-09-05 — [#2294](https://github.com/callstack/agent-device/pull/2294) removed the navigation-only phantom-type projection: direct signatures were simpler and preserved the published contract.

‎docs/adr/0012-interactive-replay.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1284,7 +1284,7 @@ After bounded expiry, the tombstone disappears and the key is free.
12841284
> The flags retain their different scopes:
12851285
>
12861286
> - Common `--no-record` belongs to `COMMON_COMMAND_SUPPORTED_FLAG_KEYS`.
1287-
> Every recordable reader forwards it with `noRecordInputFromFlags` (`src/commands/cli-grammar/common.ts`, #1304).
1287+
> Every recordable reader forwards it with `noRecordInputFromFlags` (`packages/command-surface/src/cli-grammar/common.ts`, #1304).
12881288
> - Scoped `--record` is not common.
12891289
> Only `snapshot`/`get`/`is` and dynamically validated `find` permit it.
12901290
> Only their readers use `observationRecordInputFromFlags`.
@@ -1295,10 +1295,10 @@ After bounded expiry, the tombstone disappears and the key is free.
12951295
> That fail-open is what the split prevents.
12961296
> Both flags then use the ordinary typed path:
12971297
>
1298-
> - Node forwards them through `buildRequestFlags`/`buildFlags` in `src/commands/command-flags.ts`.
1298+
> - Node forwards them through `buildRequestFlags`/`buildFlags` in `packages/command-surface/src/command-flags.ts`.
12991299
> Sources are `InternalRequestOptions`, `GetOptions`, `IsOptions`, `FindOptions`, and `CaptureSnapshotOptions`.
13001300
> - MCP exposes `record`/`noRecord` on `get`/`is`/`find`/`snapshot` tools.
1301-
> `src/commands/interaction/metadata.ts` and `src/commands/capture/snapshot.ts` use `CommandMetadata.inputSchema` plus `readMetadataCommandFlags`, as for other typed fields.
1301+
> `packages/command-surface/src/interaction/metadata.ts` and `packages/command-surface/src/capture/snapshot.ts` use `CommandMetadata.inputSchema` plus `readMetadataCommandFlags`, as for other typed fields.
13021302
>
13031303
> There is no separate per-surface recording contract.
13041304
>

‎docs/agents/cli-flags.md‎

Lines changed: 10 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,50 +6,43 @@ Pass a flag only through layers that consume it:
66
Add its definition to the owner in `packages/command-registry/src/flag-definitions-*.ts`.
77
Add it to the applicable group in `packages/command-registry/src/flag-groups.ts`, for example `SNAPSHOT_FLAGS`.
88
Update the command family metadata/schema that exposes the flag.
9-
To find the owner, run `rg -n "<command>|helpDescription|summary|supportedFlags|allowedFlags" src/commands src/cli/parser`.
10-
For schema-only CLI commands, use `SCHEMA_ONLY_CLI_COMMAND_SCHEMAS` in `src/commands/schema/command-overrides.ts`.
9+
To find the owner, run `rg -n "<command>|helpDescription|summary|supportedFlags|allowedFlags" packages/command-surface/src src/commands src/cli/parser`.
10+
For schema-only CLI commands, use `SCHEMA_ONLY_CLI_COMMAND_SCHEMAS` in `packages/command-surface/src/schema/command-overrides.ts`.
1111
Each flag declaration requires `projectConfig` and `recorded`.
1212
`projectConfig` permits a project `agent-device.json` to set the flag.
1313
`recorded` makes the session recorder copy it into `SessionAction.flags`.
14-
Compilation enforces completeness, without an allowlist. A declaration without either field does not compile.
1514
Only when repository control is safe, set `projectConfig: true`. Otherwise, a new flag is operator-only.
1615
Only when a `.ad` recording must carry the flag, set `recorded: true`.
17-
2. In `src/commands/cli-grammar/*`, read the CLI flag into command input.
16+
2. In `packages/command-surface/src/cli-grammar/*`, read the CLI flag into command input.
1817
3. If the flag affects daemon execution, write the input into the daemon request.
19-
Use `src/commands/command-projection.ts` and the command-family projection helpers.
18+
Use `packages/command-surface/src/index.ts` (`prepareDaemonCommandRequest`) and the command-family projection helpers.
2019
4. If Node.js or MCP should expose structured input, add a field to the command's field map. `defineFieldCommandMetadata` generates `inputSchema` and the audience.
21-
For a credential, its destination endpoint, or operator infrastructure, declare the input key with `operatorField(...)` (`src/commands/command-input.ts`).
20+
For a credential, its destination endpoint, or operator infrastructure, declare the input key with `operatorField(...)` (`packages/command-surface/src/command-input.ts`).
2221
MCP and AI SDK tool schemas thus exclude parameters for the model to write that input.
23-
For a shared common key, declare the same audience in its `src/commands/common-input-fields.ts` row instead.
24-
5. If Node.js exposes the option, update the public typed client option in `src/client/client-types.ts`.
22+
For a shared common key, declare the same audience in its `packages/command-surface/src/common-input-fields.ts` row instead.
23+
5. If Node.js exposes the option, update the public typed client option in the owning `packages/contracts/src/client-*.ts` type.
2524
6. If the request still needs public-to-internal translation, update daemon flag normalization in `src/client/client-normalizers.ts`.
2625
7. If the field enters platform dispatch, add it to `packages/daemon/src/core/context.ts` and `packages/daemon/src/core/dispatch-context.ts`.
2726
8. Only after the command surface, grammar, and projection prove applicability, pass the option through handler/platform modules.
2827
9. In `scripts/integration-progress-model.ts`, classify the flag as device-observable or intentionally-outside.
29-
In CI, the architecture-progress gate fails on unclassified public flags.
3028
10. If the flag changes interaction semantics, examine the affected cells in `packages/contracts/src/interaction-guarantees.ts` again.
3129
If only some commands have the flag, use `appliesTo` to limit its scope.
3230

33-
Command-only flags that never reach the platform layer usually stop at steps 1–3, plus step 9.
34-
An example is `find --first`.
35-
3631
## Where CLI help and schema live
3732

3833
- Long help prose is in `src/commands/schema/cli-help.ts`.
39-
CLI input readers are in `src/commands/cli-grammar/`.
34+
CLI input readers are in `packages/command-surface/src/cli-grammar/`.
4035
- `src/commands/schema/usage.ts` generates the synopsis `[label]` flag tail from `allowedFlags`.
41-
A new option reaches `--help` without a synopsis edit.
4236
Only when the command synopsis names fewer options, declare `usageFlags`.
4337
For pure grammar or grammar with its own mutually-exclusive brackets, use `[]`.
4438
Otherwise, use the subset it names. `Command flags:` always lists all of `allowedFlags`.
4539
For an opt-in across commands, set `usageHidden: true` on its flag definition. This excludes it from every synopsis.
46-
`src/commands/schema/usage.test.ts` rejects tail options that the command does not accept or the handwritten grammar already includes.
4740
- If the first positional selects an action, declare `flagsByAction` on the CLI schema.
4841
Map each action to the options it reads. Derive `allowedFlags` from that table.
4942
From caller-supplied keys, the parser rejects typed options that the action never reads.
50-
Config, env, and remote-config defaults populate `flags` without becoming a request. Thus, `AGENT_DEVICE_FPS=30` never breaks `record stop`.
43+
Options the selected action ignores stay out of its request, even when config, env, or remote-config defaults set them. Thus, `AGENT_DEVICE_FPS=30` never breaks `record stop`.
5144
Exclude options that every action reads from the table.
5245
The parser rejects only options in rows. If it rejected `--json`, it would reject the command.
5346
- Keep command-specific usage/flag metadata with the command family metadata that owns the command.
5447
- Keep argument parsing in `src/cli/parser/`. Keep help rendering in `src/commands/schema/`.
55-
Command schema metadata derives from command metadata, family declarations, and the schema-only merge in `src/commands/schema/command-overrides.ts`.
48+
Command schema metadata derives from command metadata, family declarations, and the schema-only merge in `packages/command-surface/src/schema/command-overrides.ts`.

‎docs/agents/code-ownership.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,30 @@
11
# Code ownership
22

3-
Before you edit a module with many callers, run `pnpm depgraph affected <path>` to identify callers and guarantees.
3+
Before you edit a module with many callers, run `pnpm depgraph affected <path>`.
44

55
## Declarations
66

77
| Question | Owner |
88
| --- | --- |
99
| Command names | `packages/command-registry/src/catalog.ts` |
10-
| Command declarations | `packages/command-registry/src/`: `registry.ts`, `descriptor-*.ts`, `descriptors/` |
10+
| Command descriptors | `packages/command-registry/src/`: `registry.ts`, `descriptor-*.ts`, `descriptors/` |
1111
| Daemon request-policy predicates | `packages/daemon/src/core/daemon-command-registry.ts` |
1212
| Interaction guarantees | `packages/contracts/src/interaction-guarantees.ts` |
1313
| Runtime-fact admission | `packages/daemon/src/core/runtime-admission.ts`, `src/platform-runtime-gateway.ts` |
14-
| Input fields and audiences | `src/commands/common-input-fields.ts`, `src/commands/input-audience.ts` |
14+
| Command facets, metadata, schemas, CLI grammar, request projection, and client port | `packages/command-surface/src/` |
15+
| CLI output formatters, help, and progress | `src/commands/` |
16+
| Input fields and audiences | `packages/command-surface/src/common-input-fields.ts`, `packages/command-surface/src/input-audience.ts` |
1517
| Released SDK default hosts | `src/sdk/host.ts` |
16-
| Apple runner host port and its one binding | `packages/apple-runner/src/host.ts`, `packages/platform-apple/src/core/runner-client.ts` |
18+
| Apple runner host port and binding | `packages/apple-runner/src/host.ts`, `packages/platform-apple/src/core/runner-client.ts` |
1719

1820
For SDK entries `android-adb`, `artifacts`, `limrun`, `metro`, and `remote-config`, use `captureSdkHost` for defaults.
1921
For command-host readers, use `withSdkHost`.
2022
Keep provider callbacks on their supplied host.
2123
Request cancellation and progress belong in `@agent-device/host-kit/request`.
2224
Per-call abort guards belong beside transports in `src/daemon-client/daemon-client-transport.ts`.
2325
Contracts shared across layers belong in `packages/contracts/src`.
24-
Schema composition belongs in `src/commands/schema`.
26+
Schema composition belongs in `packages/command-surface/src/schema`.
27+
A command facet declares no output formatter. Register the formatter in `src/commands/cli-output.ts`.
2528
Build interaction data through `buildInteractionResponseData`.
2629
Change cross-language rules through `contracts/fixtures/` golden tables.
2730

‎examples/sdk/tsconfig.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
{ "path": "../../packages/apple-runner" },
4040
{ "path": "../../packages/capture-kit" },
4141
{ "path": "../../packages/command-registry" },
42+
{ "path": "../../packages/command-surface" },
4243
{ "path": "../../packages/contracts" },
4344
{ "path": "../../packages/daemon" },
4445
{ "path": "../../packages/daemon-contracts" },

‎fallow-baselines/health.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
"count": 1
66
}
77
},
8-
"src/commands/schema/option-schema.ts": {
8+
"packages/command-surface/src/schema/option-schema.ts": {
99
"complexity_moderate": {
1010
"count": 1
1111
}
@@ -87,7 +87,7 @@
8787
"packages/selectors/src/internal/predicates.ts:high impact",
8888
"packages/provision-kit/src/boot-diagnostics.ts:complexity",
8989
"packages/daemon/src/sessions/session-routing.ts:high impact",
90-
"src/commands/cli-grammar/common.ts:high impact",
90+
"packages/command-surface/src/cli-grammar/common.ts:high impact",
9191
"packages/kernel/src/success-text.ts:high impact",
9292
"src/cli.ts:complexity",
9393
"src/commands/interaction/output.ts:high impact",
@@ -108,7 +108,7 @@
108108
"packages/selectors/src/interaction-targeting.ts:high impact",
109109
"packages/maestro/src/internal/runtime-targets.ts:high impact",
110110
"packages/kernel/src/source-value.ts:high impact",
111-
"src/commands/interaction/selectors.ts:untested risk",
111+
"packages/command-surface/src/interaction/selectors.ts:untested risk",
112112
"packages/selectors/src/internal/build.ts:high impact",
113113
"packages/provider-webdriver/src/webdriver-utils.ts:high impact",
114114
"packages/kernel/src/keyed-lock.ts:high impact",

‎oxlint.config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ const TOOLCHAIN_IDENTITY_EXEC_MESSAGE =
3737
'Read the toolchain identity from the selected Xcode files; an exec here can stall the runner cache decision.';
3838

3939
const CHILD_PROCESS_BAN_ROOTS = ['src', 'packages/host-kit/src'];
40-
const PROVIDER_BAN_ROOTS = ['src/commands', 'src/cli/commands'];
40+
const PROVIDER_BAN_ROOTS = ['src/commands', 'packages/command-surface/src', 'src/cli/commands'];
4141

4242
const MAX_FILE_LINES = 1000;
4343

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -304,6 +304,7 @@
304304
"@agent-device/apple-runner": "workspace:*",
305305
"@agent-device/capture-kit": "workspace:*",
306306
"@agent-device/command-registry": "workspace:*",
307+
"@agent-device/command-surface": "workspace:*",
307308
"@agent-device/contracts": "workspace:*",
308309
"@agent-device/daemon": "workspace:*",
309310
"@agent-device/daemon-contracts": "workspace:*",

‎packages/ad-script/src/internal/script-utils.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -111,8 +111,9 @@ export const SCRIPT_FLAG_COMMANDS = Object.keys(SCRIPT_FLAG_MAPS) as readonly Sc
111111

112112
/**
113113
* The script flag tokens one command's line reads, with their value kinds and flag keys
114-
* (#3197). Exported for the root admission test
115-
* (`src/commands/replay/script-flag-admission.test.ts`), which proves the tables and the
114+
* (#3197). Exported for the command-surface admission test
115+
* (`packages/command-surface/src/replay/script-flag-admission.test.ts`), which proves the
116+
* tables and the
116117
* flag declarations admit the same keys in both directions — the invariant that keeps the
117118
* script grammar and the flag declarations from diverging the way `--until` and
118119
* `wait --raw` did.

0 commit comments

Comments
 (0)