Skip to content

Commit b1c068d

Browse files
authored
refactor(cli-schema): orient the schema layer above commands (#2543 step 3) (#2590)
* refactor(cli-schema): move command schema types down, orient layer above commands (#2543) Move CommandSchema/CommandSchemaOverride from src/cli-schema/types.ts into packages/command-registry beside the flag grammar they import, retiring 22 forward type-only commands -> cli-schema edges. Take projectConfigFlagKeys directly from the registry in cli-config. Relocate command-explain.ts up into the cli zone (it renders the schema and already type-depends on the daemon route union), retiring the last commands -> cli-schema value edges. commands -> cli-schema is now 0 of any kind; cli-schema -> commands (the facet aggregate) is the honest direction: the schema layer renders what the facets author. * chore(gates): declare commands below cli-schema via R2 commands-floor (#2543) Add the from:commands to:cli-schema policy so the declared direction (cli-schema reads the command facets; commands never imports cli-schema) cannot regress. R6 4 -> 3 (command-explain moved above daemon-server). Update the R2 hint, the check spine comment, and the surviving-inversion notes in the findings doc.
1 parent 730b201 commit b1c068d

35 files changed

Lines changed: 79 additions & 44 deletions

‎docs/dependency-graph-findings.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ with `command`/`positionals` `Pick`ed from the wire so they cannot drift from it
111111
resolver already read only those three, in two spellings (the full type and a `Pick` of it); one
112112
narrow name replaced both.
113113

114-
**The remaining 5 are positions, not debt** — each for a mechanical reason, not an appeal to an ADR:
114+
**The remaining 4 are positions, not debt** — each for a mechanical reason, not an appeal to an ADR:
115115

116116
- **4 × `AgentDeviceClient`** (`commands/command-contract.ts`, `commands/command-surface.ts`,
117117
`commands/family/types.ts`, `mcp/command-tools.ts`). The zone-level type cycle this bullet used to
@@ -120,11 +120,13 @@ narrow name replaced both.
120120
facade above `commands/` is the remaining argument: a narrower port does not exist — 4 files
121121
*name* the facade, but 26 call sites use methods across 13 of its namespaces, so any port would
122122
re-declare it.
123-
- **1 × `DaemonCommandRoute`** (`commands/command-explain.ts`). The union lives in core so
124-
descriptors can name a route without importing the daemon, and the handler table covers it with
125-
`satisfies Record<DaemonCommandRoute, …>`. `command-explain.ts` still type-imports the re-export
126-
from `daemon-command-registry.ts` to key an exhaustive owner-file map; that remaining inversion
127-
is the commands-zone consumer, not a second source of truth for the union.
123+
124+
Retired by #2543: the **1 × `DaemonCommandRoute`** inversion whose only commands-zone consumer was
125+
`command-explain.ts`. The union lives in core so descriptors can name a route without importing the
126+
daemon; the explainer only type-imported the `daemon-command-registry.ts` re-export to key an
127+
exhaustive owner-file map. #2543 relocated `command-explain.ts` to the `cli/` zone — above
128+
`daemon-server` — so that consumer's type import no longer outranks its target, and the
129+
`commands -> daemon-server` R6 pair fell to zero.
128130

129131
All remaining inversions are argued here. R6 (`scripts/layering/type-inversion-ratchet.ts`) records
130132
no numbers of its own: its reference is the same count taken at the merge-base with `origin/main`,

‎packages/command-registry/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,10 @@
8787
"types": "./src/command-text.ts",
8888
"default": "./src/command-text.ts"
8989
},
90+
"./command-schema": {
91+
"types": "./src/command-schema.ts",
92+
"default": "./src/command-schema.ts"
93+
},
9094
"./cli-command-aliases": {
9195
"types": "./src/cli-command-aliases.ts",
9296
"default": "./src/cli-command-aliases.ts"

src/cli-schema/types.ts renamed to packages/command-registry/src/command-schema.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import type { FlagKey } from '@agent-device/command-registry/flag-types';
2-
import type { CommandText } from '@agent-device/command-registry/command-text';
1+
import type { FlagKey } from './flag-types.ts';
2+
import type { CommandText } from './command-text.ts';
33

44
/**
55
* Command grammar plus its resolved text. Prose lives entirely in `text`; everything else here

‎scripts/explain-command.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import fs from 'node:fs';
22
import path from 'node:path';
33
import { fileURLToPath } from 'node:url';
4-
import { explainCommand, formatCommandExplanation } from '../src/commands/command-explain.ts';
4+
import { explainCommand, formatCommandExplanation } from '../src/cli/command-explain.ts';
55
import { getDaemonRouteOwnerFiles } from '../src/daemon/route-owner-files.ts';
66

77
const repoRoot = path.resolve(import.meta.dirname, '..');

‎scripts/layering/check.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77
// ◄ { client, daemon-server } ◄ daemon-client ◄ cli
88
// (authoritative ranks: `TARGET_DAG_RANK` in model.ts. The former rank-0 kernel
99
// zone lives in packages/kernel since #1490 W0; R11 owns its boundary.)
10+
// `commands` and `cli-schema` share a rank, so the spine cannot order them; R2 declares the
11+
// direction instead — cli-schema renders the command facets and reads them, commands never
12+
// imports cli-schema (#2543).
1013
//
1114
// This gate enforces five things, across four scopes:
1215
// - GLOBALLY, across every production source file: the remaining R2 move rule and

‎scripts/layering/zone-policy.test.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,22 @@ test('R2 commands-floor closes the remaining zones below the command surface, wh
4444
assert.deepEqual(firing(edge('src/mcp/tools.ts', 'mcp', 'commands')), []);
4545
});
4646

47+
test('R2 commands-floor places commands below the cli-schema layer, whatever the kind', () => {
48+
// #2543: cli-schema renders the facets commands authors, so it reads commands and commands never
49+
// reads it back. The direction holds for value, type-only, and dynamic forms alike.
50+
for (const kind of [{}, { typeOnly: true }, { dynamic: true }]) {
51+
assert.ok(
52+
firing(edge('src/commands/thing.ts', 'commands', 'cli-schema', kind)).includes(
53+
'R2 commands-floor',
54+
),
55+
`commands -> cli-schema ${JSON.stringify(kind)} must violate R2`,
56+
);
57+
}
58+
59+
// The declared direction — cli-schema reading the facets — must stay silent.
60+
assert.deepEqual(firing(edge('src/cli-schema/command-schema.ts', 'cli-schema', 'commands')), []);
61+
});
62+
4763
test('the retired R3 platforms seam has no zone-policy declaration', () => {
4864
assert.equal(
4965
ZONE_POLICIES.some(({ rule }) => rule === 'R3 platforms-seam'),

‎scripts/layering/zone-policy.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ export type ZonePolicy = {
4343
* R1 kernel-sink retired 2026-07-30 (#1490 W0): the kernel moved to
4444
* packages/kernel, where package resolution and R11 package-boundaries enforce
4545
* the sink property physically — a package cannot import root src at all.
46+
*
47+
* The two rows share `R2 commands-floor`: both state that commands sits at a floor and is read
48+
* from above. The first keeps `core`/`daemon` below it; the second places `cli-schema` above it,
49+
* so commands may not import the schema layer that renders its facets (#2543 declared the
50+
* direction after the shared schema grammar moved down to the command registry).
4651
*/
4752
export const ZONE_POLICIES: readonly ZonePolicy[] = [
4853
{
@@ -53,6 +58,15 @@ export const ZONE_POLICIES: readonly ZonePolicy[] = [
5358
'commands/ is the command surface, above these zones. Depend on shared kernel/contracts ' +
5459
'instead; if two zones need the same rule, put the rule below both of them.',
5560
},
61+
{
62+
rule: 'R2 commands-floor',
63+
from: ['commands'],
64+
to: ['cli-schema'],
65+
hint:
66+
'cli-schema is the CLI/MCP schema layer that renders the command facets, so it sits above ' +
67+
'commands and reads them; commands must not import it back. The shared CommandSchema type and ' +
68+
'flag grammar live in @agent-device/command-registry, below both zones.',
69+
},
5670
];
5771

5872
function kindOf(imp: ImportEdge): 'type-only' | 'dynamic' | 'value' {

‎src/cli-schema/cli-config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import path from 'node:path';
44
import { AppError } from '@agent-device/kernel/errors';
55
import { mergeDefinedFlags } from './merge-flags.ts';
66
import { type FlagKey } from '@agent-device/command-registry/flag-types';
7-
import { projectConfigFlagKeys } from './command-schema.ts';
7+
import { projectConfigFlagKeys } from '@agent-device/command-registry/flag-registry';
88
import { expandUserHomePath, resolveUserPath } from '@agent-device/host-kit/file';
99
import {
1010
getConfigurableOptionSpecs,

‎src/cli-schema/command-overrides.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import type { CommandName } from '../commands/command-metadata.ts';
22
import { listCommandFamilyCliSchemas } from '../commands/family/registry.ts';
33
import type { LocalCliCommandName } from '@agent-device/command-registry/catalog';
4-
import type { CommandSchema } from './types.ts';
4+
import type { CommandSchema } from '@agent-device/command-registry/command-schema';
55
import {
66
COMMON_COMMAND_SUPPORTED_FLAG_KEYS,
77
METRO_PREPARE_FLAGS,

‎src/cli-schema/command-schema.ts‎

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
import type { CliCommandName } from '@agent-device/command-registry/catalog';
22
import { listCommandMetadata } from '../commands/command-metadata.ts';
3-
import type { CommandSchema } from './types.ts';
3+
import type { CommandSchema } from '@agent-device/command-registry/command-schema';
44
import { getCliCommandOverride, getSchemaOnlyCliCommandSchema } from './command-overrides.ts';
55
import {
66
getFlagDefinition,
77
getFlagDefinitions,
8-
projectConfigFlagKeys,
98
} from '@agent-device/command-registry/flag-registry';
109
import {
1110
COMMON_COMMAND_SUPPORTED_FLAG_KEYS,
@@ -17,13 +16,7 @@ import { AppError } from '@agent-device/kernel/errors';
1716

1817
export type { FlagDefinition, FlagKey };
1918
export type { CommandSchema };
20-
export {
21-
DEVICE_SELECTION_FLAG_KEYS,
22-
getFlagDefinition,
23-
getFlagDefinitions,
24-
GLOBAL_FLAG_KEYS,
25-
projectConfigFlagKeys,
26-
};
19+
export { DEVICE_SELECTION_FLAG_KEYS, getFlagDefinition, getFlagDefinitions, GLOBAL_FLAG_KEYS };
2720

2821
// Bases hold only the flags every command supports; prose arrives with the facet's schema,
2922
// which always carries a complete `text`.

0 commit comments

Comments
 (0)