Skip to content

Commit 8ef4e73

Browse files
authored
refactor: derive command exposure lists from descriptors (#1137)
1 parent 5c5fa01 commit 8ef4e73

9 files changed

Lines changed: 114 additions & 66 deletions

File tree

‎CONTEXT.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -69,10 +69,11 @@ guarantees are whole-matrix decisions, not local edits.
6969
The perfect-shape refactor is complete and merged. Its end-state:
7070

7171
- Two derivation registries. One `CommandDescriptor` per command
72-
(`src/core/command-descriptor/registry.ts`) is the single declaration site from which the public
73-
catalog, capability matrix, daemon command registry, batch allowlist, MCP tools, CLI schema, and
74-
the Node client surface are *derived* by parity-tested projection; the dispatch `switch` became a
75-
total map keyed on the command-name union (a missing handler is a compile error). One
72+
(`src/core/command-descriptor/registry.ts`) is the single declaration site from which the
73+
capability matrix, daemon command registry, batch allowlist, timeout policy, MCP exposure list, and
74+
capability-checked CLI command list are *derived* by parity-tested projection. The command catalog
75+
still owns identity, command families still own surface metadata/CLI schema, and the Node client
76+
surface remains a deferred derivation target. One
7677
`PlatformPlugin` per platform family (`src/core/platform-plugin/`) stops core/daemon from branching
7778
on platform, with the Apple plugin the first instance. See
7879
[ADR 0008](docs/adr/0008-command-descriptor-registry.md).

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,11 @@ Each derived table must be asserted **byte-for-byte equivalent** to the hand-aut
7272
**before** the hand table is deleted. The principal risk is the import-cycle inversion: `command-catalog.ts`
7373
has ~95 importers and the family facet currently imports `AgentDeviceClient`, so the descriptor module must
7474
own the `Input`/`Result` types and the client must be derived as a view type, enforced by a lint boundary.
75-
Until this lands and the registry tests pin it, the hand-authored tables remain the source of truth.
75+
As of 2026-07, the descriptor is live for the daemon registry, capability matrix, structured-batch
76+
allowlist, daemon-client timeout policy, MCP exposure list, and capability-checked CLI command list.
77+
The catalog still owns command identity and the command family facet still owns surface metadata, so
78+
future migration steps should keep deleting one live hand-maintained table at a time rather than
79+
introducing a parallel manifest.
7680

7781
This ADR owns the decision and its constraints; the roadmap that prototyped it has been retired, with
7882
the delivered end-state recorded in [CONTEXT.md](../../CONTEXT.md) (Architecture).

‎src/command-catalog.ts‎

Lines changed: 0 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -98,49 +98,6 @@ export type ClientBackedCliCommandName =
9898
| typeof LOCAL_CLI_COMMANDS.metro
9999
| typeof LOCAL_CLI_COMMANDS.session;
100100

101-
const MCP_UNEXPOSED_CLI_COMMANDS = commandSet(
102-
LOCAL_CLI_COMMANDS.auth,
103-
LOCAL_CLI_COMMANDS.cdp,
104-
LOCAL_CLI_COMMANDS.connect,
105-
LOCAL_CLI_COMMANDS.connection,
106-
LOCAL_CLI_COMMANDS.disconnect,
107-
LOCAL_CLI_COMMANDS.mcp,
108-
LOCAL_CLI_COMMANDS.proxy,
109-
LOCAL_CLI_COMMANDS.reactDevtools,
110-
LOCAL_CLI_COMMANDS.web,
111-
PUBLIC_COMMANDS.prepare,
112-
);
113-
114-
const CAPABILITY_EXEMPT_CLI_COMMANDS = commandSet(
115-
LOCAL_CLI_COMMANDS.auth,
116-
LOCAL_CLI_COMMANDS.cdp,
117-
LOCAL_CLI_COMMANDS.connect,
118-
LOCAL_CLI_COMMANDS.connection,
119-
LOCAL_CLI_COMMANDS.debug,
120-
LOCAL_CLI_COMMANDS.disconnect,
121-
LOCAL_CLI_COMMANDS.mcp,
122-
LOCAL_CLI_COMMANDS.metro,
123-
LOCAL_CLI_COMMANDS.proxy,
124-
LOCAL_CLI_COMMANDS.reactDevtools,
125-
LOCAL_CLI_COMMANDS.session,
126-
LOCAL_CLI_COMMANDS.web,
127-
PUBLIC_COMMANDS.artifacts,
128-
PUBLIC_COMMANDS.appState,
129-
PUBLIC_COMMANDS.prepare,
130-
PUBLIC_COMMANDS.batch,
131-
PUBLIC_COMMANDS.capabilities,
132-
PUBLIC_COMMANDS.devices,
133-
PUBLIC_COMMANDS.doctor,
134-
PUBLIC_COMMANDS.gesture,
135-
PUBLIC_COMMANDS.replay,
136-
PUBLIC_COMMANDS.test,
137-
PUBLIC_COMMANDS.trace,
138-
);
139-
140-
function commandSet(...commands: readonly string[]): ReadonlySet<string> {
141-
return new Set(commands);
142-
}
143-
144101
export function listCliCommandNames(): CliCommandName[] {
145102
return [...Object.values(PUBLIC_COMMANDS), ...Object.values(LOCAL_CLI_COMMANDS)].sort();
146103
}
@@ -161,11 +118,3 @@ export function isClientBackedCliCommandName(
161118
command === LOCAL_CLI_COMMANDS.session
162119
);
163120
}
164-
165-
export function listMcpExposedCommandNames(): CliCommandName[] {
166-
return listCliCommandNames().filter((command) => !MCP_UNEXPOSED_CLI_COMMANDS.has(command));
167-
}
168-
169-
export function listCapabilityCheckedCommandNames(): CliCommandName[] {
170-
return listCliCommandNames().filter((command) => !CAPABILITY_EXEMPT_CLI_COMMANDS.has(command));
171-
}

‎src/commands/__tests__/command-surface-metadata.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import assert from 'node:assert/strict';
22
import { test } from 'vitest';
3-
import { listMcpExposedCommandNames } from '../../command-catalog.ts';
3+
import { listMcpExposedCommandNames } from '../../core/command-descriptor/registry.ts';
44
import {
55
listCommandMetadata,
66
listCommandMetadataNames,

‎src/commands/command-metadata.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { listMcpExposedCommandNames } from '../command-catalog.ts';
1+
import { listMcpExposedCommandNames } from '../core/command-descriptor/registry.ts';
22
import type { CommandMetadata } from './command-contract.ts';
33
import { listCommandFamilyMetadata, type CommandFamilyCommandName } from './family/registry.ts';
44

‎src/core/command-descriptor/__tests__/parity.test.ts‎

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,19 @@
11
import assert from 'node:assert/strict';
22
import { test } from 'vitest';
33
import { STRUCTURED_BATCH_COMMAND_NAMES } from '../../../batch-policy.ts';
4-
import { PUBLIC_COMMANDS } from '../../../command-catalog.ts';
4+
import { listCliCommandNames, PUBLIC_COMMANDS } from '../../../command-catalog.ts';
55
import { BASE_COMMAND_CAPABILITY_MATRIX } from '../../capabilities.ts';
66
import {
77
DAEMON_COMMAND_DESCRIPTORS,
88
type DaemonCommandDescriptor,
99
} from '../../../daemon/daemon-command-registry.ts';
1010
import type { DaemonRequest } from '../../../daemon/types.ts';
1111
import { deriveDaemonCommandDescriptors, deriveStructuredBatchCommandNames } from '../derive.ts';
12-
import { commandDescriptors } from '../registry.ts';
12+
import {
13+
commandDescriptors,
14+
listCapabilityCheckedCommandNames,
15+
listMcpExposedCommandNames,
16+
} from '../registry.ts';
1317

1418
// Function-valued traits cannot be deep-equaled across re-authored closures, so
1519
// (mirroring daemon-command-registry.test.ts) they are compared by presence and
@@ -174,3 +178,40 @@ test('structured-batch allowlist is built from descriptors', () => {
174178
assert.ok(!batchable.has(excluded), `${excluded} is not batchable`);
175179
}
176180
});
181+
182+
test('MCP exposure list is built from descriptors', () => {
183+
const cliCommands = new Set<string>(listCliCommandNames());
184+
const expected = commandDescriptors
185+
.filter((descriptor) => descriptor.mcpExposed && cliCommands.has(descriptor.name))
186+
.map((descriptor) => descriptor.name)
187+
.sort();
188+
const expectedNames = new Set<string>(expected);
189+
190+
assert.deepEqual(listMcpExposedCommandNames(), expected);
191+
assert.ok(expectedNames.has('debug'), 'local debug command stays MCP-exposed');
192+
assert.ok(expectedNames.has('metro'), 'local metro command stays MCP-exposed');
193+
assert.ok(expectedNames.has('session'), 'local session command stays MCP-exposed');
194+
assert.equal(expectedNames.has(PUBLIC_COMMANDS.prepare), false, 'prepare stays out of MCP');
195+
assert.equal(expectedNames.has('auth'), false, 'schema-only auth command stays out of MCP');
196+
});
197+
198+
test('capability-checked command list is built from descriptor capabilities', () => {
199+
const cliCommands = new Set<string>(listCliCommandNames());
200+
const expected = commandDescriptors
201+
.filter(
202+
(descriptor) =>
203+
'capability' in descriptor && descriptor.capability && cliCommands.has(descriptor.name),
204+
)
205+
.map((descriptor) => descriptor.name)
206+
.sort();
207+
const expectedNames = new Set<string>(expected);
208+
209+
assert.deepEqual(listCapabilityCheckedCommandNames(), expected);
210+
assert.ok(expectedNames.has(PUBLIC_COMMANDS.snapshot), 'snapshot remains capability-checked');
211+
assert.equal(
212+
expectedNames.has(PUBLIC_COMMANDS.capabilities),
213+
false,
214+
'control-plane capabilities command stays capability-exempt',
215+
);
216+
assert.equal(expectedNames.has('debug'), false, 'local debug command stays capability-exempt');
217+
});

‎src/core/command-descriptor/registry.ts‎

Lines changed: 57 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import {
22
INTERNAL_COMMANDS,
3-
listMcpExposedCommandNames,
3+
listCliCommandNames,
4+
type CliCommandName,
45
PUBLIC_COMMANDS,
56
} from '../../command-catalog.ts';
67
import type { CommandCapability } from '../capabilities.ts';
@@ -15,6 +16,10 @@ import { resolvePostActionObservationSupport } from './post-action-observation.t
1516
import type { PostActionObservationSupport } from './post-action-observation.ts';
1617
import type { CommandDescriptor, CommandTimeoutPolicy } from './types.ts';
1718

19+
type RawCommandDescriptor = Omit<CommandDescriptor, 'mcpExposed'> & {
20+
mcpExposed?: boolean;
21+
};
22+
1823
// ---------------------------------------------------------------------------
1924
// Daemon request-policy trait bundles — copied VERBATIM from
2025
// src/daemon/daemon-command-registry.ts (DAEMON_COMMAND_DESCRIPTORS).
@@ -396,6 +401,7 @@ const RAW_COMMAND_DESCRIPTORS = [
396401
onTimeout: 'reset-daemon',
397402
},
398403
batchable: false,
404+
mcpExposed: false,
399405
},
400406
{
401407
name: PUBLIC_COMMANDS.batch,
@@ -694,9 +700,26 @@ const RAW_COMMAND_DESCRIPTORS = [
694700
timeoutPolicy: DEFAULT_TIMEOUT_POLICY,
695701
batchable: true,
696702
},
697-
] as const satisfies readonly Omit<CommandDescriptor, 'mcpExposed'>[];
698703

699-
const MCP_EXPOSED_COMMAND_NAMES = new Set<string>(listMcpExposedCommandNames());
704+
// -- local client-backed CLI/MCP commands (no daemon route/capability) --
705+
{
706+
name: 'debug',
707+
timeoutPolicy: DEFAULT_TIMEOUT_POLICY,
708+
batchable: false,
709+
},
710+
{
711+
name: 'metro',
712+
timeoutPolicy: DEFAULT_TIMEOUT_POLICY,
713+
batchable: false,
714+
},
715+
{
716+
name: 'session',
717+
timeoutPolicy: DEFAULT_TIMEOUT_POLICY,
718+
batchable: false,
719+
},
720+
] as const satisfies readonly RawCommandDescriptor[];
721+
722+
const CLI_COMMAND_NAMES = new Set<string>(listCliCommandNames());
700723

701724
/**
702725
* The additive single source of truth (ADR-0008, Phase 1 step 1). Proven
@@ -708,16 +731,46 @@ const MCP_EXPOSED_COMMAND_NAMES = new Set<string>(listMcpExposedCommandNames());
708731
*/
709732
export const commandDescriptors = RAW_COMMAND_DESCRIPTORS.map((descriptor) => ({
710733
...descriptor,
711-
mcpExposed: MCP_EXPOSED_COMMAND_NAMES.has(descriptor.name),
734+
mcpExposed: resolveMcpExposure(descriptor),
712735
})) satisfies readonly CommandDescriptor[];
713736

714737
/** The literal union of every registered command name. */
715738
export type Command = (typeof commandDescriptors)[number]['name'];
716739

740+
export function listMcpExposedCommandNames(): CliCommandName[] {
741+
return commandDescriptors
742+
.filter((descriptor) => isMcpExposedCliCommand(descriptor))
743+
.map((descriptor) => descriptor.name as CliCommandName)
744+
.sort();
745+
}
746+
747+
export function listCapabilityCheckedCommandNames(): CliCommandName[] {
748+
return commandDescriptors
749+
.filter((descriptor) => isCapabilityCheckedCliCommand(descriptor))
750+
.map((descriptor) => descriptor.name as CliCommandName)
751+
.sort();
752+
}
753+
717754
const COMMAND_DESCRIPTOR_BY_NAME: ReadonlyMap<string, CommandDescriptor> = new Map(
718755
commandDescriptors.map((descriptor) => [descriptor.name, descriptor]),
719756
);
720757

758+
function isCliCommandName(command: string): command is CliCommandName {
759+
return CLI_COMMAND_NAMES.has(command);
760+
}
761+
762+
function resolveMcpExposure(descriptor: RawCommandDescriptor): boolean {
763+
return descriptor.mcpExposed ?? CLI_COMMAND_NAMES.has(descriptor.name);
764+
}
765+
766+
function isMcpExposedCliCommand(descriptor: CommandDescriptor): boolean {
767+
return descriptor.mcpExposed && isCliCommandName(descriptor.name);
768+
}
769+
770+
function isCapabilityCheckedCliCommand(descriptor: CommandDescriptor): boolean {
771+
return Boolean(descriptor.capability) && isCliCommandName(descriptor.name);
772+
}
773+
721774
const TIMEOUT_POLICY_BY_COMMAND: ReadonlyMap<string, CommandTimeoutPolicy> = new Map(
722775
commandDescriptors.map((descriptor) => [descriptor.name, descriptor.timeoutPolicy]),
723776
);

‎src/mcp/__tests__/router.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import assert from 'node:assert/strict';
22
import { setImmediate } from 'node:timers/promises';
33
import { test } from 'vitest';
4-
import { listMcpExposedCommandNames } from '../../command-catalog.ts';
4+
import { listMcpExposedCommandNames } from '../../core/command-descriptor/registry.ts';
55
import { handleMcpMessage } from '../router.ts';
66
import { createMcpPayloadQueue, handleMcpPayload } from '../server.ts';
77

‎src/utils/__tests__/command-schema-guards.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ import { listCapabilityCommands } from '../../core/capabilities.ts';
88
import {
99
INTERNAL_COMMANDS,
1010
isKnownCliCommandName,
11-
listCapabilityCheckedCommandNames,
1211
listCliCommandNames,
1312
SPECIAL_CLI_COMMANDS,
1413
} from '../../command-catalog.ts';
14+
import { listCapabilityCheckedCommandNames } from '../../core/command-descriptor/registry.ts';
1515
import { getCliCommandSchema } from '../command-schema.ts';
1616

1717
test('every public capability command has a parser schema entry', () => {

0 commit comments

Comments
 (0)