Skip to content

Commit 8bbf7c6

Browse files
thymikeeclaude
andauthored
refactor(cli): fold cli-schema into commands/schema, move batch-steps into commands/batch (#2679) (#2678)
* refactor(cli): fold cli-schema into commands/schema, move batch-steps into commands/batch Implements move 1 (+ batch-steps.ts) from the collocation plan in #2677: cli-schema was a rank-0.0003-modularity, 37.5%-legible eight-file zone that existed only to render the command facets commands/ already owns, and batch-steps.ts's only relative import and only importer both already live under commands/. Folding both in removes a family the coupling/legibility measures called out as a clear placement miss, without changing behaviour. - git mv src/cli-schema/* -> src/commands/schema/* - git mv src/cli/batch-steps.ts -> src/commands/batch/batch-steps.ts - update every import site, the literal command-explain.ts owner-files path, the layering model's now-absorbed cli-schema rank entry (folded files resolve to the commands zone by directory), fallow-baselines/ health.json's path-keyed findings, and the AGENTS.md / cli-flags.md pointers Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01EmJYA9V4uKcAGBqedwXbwD * fix(layering): re-enforce commands-schema-floor after cli-schema folded into it Review on #2678 found a real enforcement gap: folding cli-schema into commands/schema/ put both sides of the #2543 "commands never imports cli-schema back" direction into the same commands zone, which checkLayeringRules's ZONE_POLICIES table cannot see (it skips every same-zone edge before the table ever runs). The R2 zone-policy row that used to declare the direction became silently unenforceable, not just harmlessly dead like the daemon-side check. - add scripts/layering/commands-schema-boundary.ts: a folder-scoped check (commands outside schema/ must not import commands/schema/) wired into check.ts's rule registry, replacing the lost R2 row - drop the now-unenforceable R2 row from zone-policy.ts's table and its test, and the header comments that described it - delete the actually-dead checkDaemonCliSchemaBoundary from daemon-modularity.ts (the daemon side stays covered generically by R2's daemon/core -> commands row) and its tests Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01EmJYA9V4uKcAGBqedwXbwD --------- Co-authored-by: Claude <[email protected]>
1 parent 16d4cfc commit 8bbf7c6

52 files changed

Lines changed: 184 additions & 153 deletions

Some content is hidden

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

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ Read the declaration rather than maintaining a prose copy:
5757

5858
Shared selector parsing and matching belongs in `@agent-device/selectors`; request cancellation
5959
and progress in `@agent-device/host-kit/request`; cross-layer contracts in `packages/contracts/src`;
60-
CLI flags in `src/commands/cli-grammar`; cross-surface schema composition in `src/cli-schema`.
60+
CLI flags in `src/commands/cli-grammar`; cross-surface schema composition in `src/commands/schema`.
6161

6262
Resolve registry completeness failures at the missing declaration. Diagnose other gate failures
6363
at their reported invariant; do not suppress them or add an allowlist to get a pass. Build interaction

‎docs/agents/cli-flags.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ Thread a flag only through the layers that consume it:
77
`packages/command-registry/src/flag-groups.ts`
88
(for example `SNAPSHOT_FLAGS`). Then update the command family metadata/schema that exposes the
99
flag; find the owner with
10-
`rg -n "<command>|supportedFlags|allowedFlags" src/commands src/cli-schema src/cli/parser`. For
10+
`rg -n "<command>|supportedFlags|allowedFlags" src/commands src/cli/parser`. For
1111
schema-only CLI commands, the owner is `SCHEMA_ONLY_CLI_COMMAND_SCHEMAS` in
12-
`src/cli-schema/command-overrides.ts`. Every flag declaration states `projectConfig`
12+
`src/commands/schema/command-overrides.ts`. Every flag declaration states `projectConfig`
1313
(may be set from a project `agent-device.json`) and `recorded` (the session recorder
1414
copies it into `SessionAction.flags`). Both are required, so a new declaration that
1515
omits either does not compile — that, not an allowlist, is the completeness gate. Set
@@ -43,16 +43,16 @@ steps 1-3, plus step 9.
4343

4444
## Where CLI help and schema live
4545

46-
- Long help prose: `src/cli-schema/cli-help.ts`. Flag definitions: `src/commands/cli-grammar/`.
47-
- Synopsis: `src/cli-schema/usage.ts` generates the `[label]` flag tail from `allowedFlags`, so a
46+
- Long help prose: `src/commands/schema/cli-help.ts`. Flag definitions: `src/commands/cli-grammar/`.
47+
- Synopsis: `src/commands/schema/usage.ts` generates the `[label]` flag tail from `allowedFlags`, so a
4848
new option reaches `--help` without any synopsis edit. Declare `usageFlags` on the command only
4949
when its synopsis names fewer options: `[]` for a synopsis that is pure grammar (or writes its own
5050
mutually-exclusive brackets), otherwise the subset it names. `Command flags:` always lists
5151
everything in `allowedFlags`. Keep a cross-cutting opt-in out of every synopsis with
52-
`usageHidden: true` on its flag definition. `src/cli-schema/usage.test.ts` fails a tail that names
52+
`usageHidden: true` on its flag definition. `src/commands/schema/usage.test.ts` fails a tail that names
5353
an option the command does not accept, or one the hand-written grammar already wrote.
5454
- Command-specific usage/flag metadata lives with the command family metadata that owns the command.
5555
- Parser/help *rendering* stays in `src/cli/parser/`; command schema metadata is derived from command
5656
metadata, family declarations, and the schema-only merge path in
57-
`src/cli-schema/command-overrides.ts`. Keep the two separate.
58-
- Locating an owner: `rg -n "helpDescription|summary|supportedFlags|allowedFlags" src/commands src/cli/parser src/cli-schema`.
57+
`src/commands/schema/command-overrides.ts`. Keep the two separate.
58+
- Locating an owner: `rg -n "helpDescription|summary|supportedFlags|allowedFlags" src/commands src/cli/parser`.

‎fallow-baselines/health.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,12 @@
2323
"count": 1
2424
}
2525
},
26-
"src/cli-schema/cli-config.ts": {
26+
"src/commands/schema/cli-config.ts": {
2727
"crap_moderate": {
2828
"count": 1
2929
}
3030
},
31-
"src/cli-schema/option-schema.ts": {
31+
"src/commands/schema/option-schema.ts": {
3232
"complexity_moderate": {
3333
"count": 1
3434
},

‎scripts/__tests__/help-conformance-topic-coverage.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 { test } from 'vitest';
33
import { CASES } from '../help-conformance-cases.mjs';
4-
import { helpTopicIds } from '../../src/cli-schema/cli-help.ts';
4+
import { helpTopicIds } from '../../src/commands/schema/cli-help.ts';
55

66
// "What enumerates N": benchmark cases are keyed to help topics, and this gate
77
// keys the case list to the topic registry itself. A new help topic must gain

‎scripts/fuzz/targets.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
import { parseArgs } from '../../src/cli/parser/args.ts';
1111
import { validateSelectorExpression } from '@agent-device/selectors';
1212
import { parseReplayScriptDetailed } from '@agent-device/ad-script';
13-
import { readCliBatchStepsJson } from '../../src/cli/batch-steps.ts';
13+
import { readCliBatchStepsJson } from '../../src/commands/batch/batch-steps.ts';
1414
import { inspectMaestroFlow } from '@agent-device/maestro';
1515
import type { FuzzTarget } from './target-types.ts';
1616
import { acceptCase, makeValidationCheck, rejectCase } from './validation-case.ts';

‎scripts/fuzz/validation-arbitraries-cli.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
import fc from 'fast-check';
1010
import { describe, expect, it, vi } from 'vitest';
1111
import { listCliCommandNames } from '@agent-device/command-registry/catalog';
12-
import { getFlagDefinitions } from '../../src/cli-schema/command-schema.ts';
12+
import { getFlagDefinitions } from '../../src/commands/schema/command-schema.ts';
1313
import { getFuzzTarget } from './registry.ts';
1414
import { decodeValidationCase } from './validation-case.ts';
1515
import { describeGeneratorContract } from './validation-generator-contract.ts';

‎scripts/fuzz/validation-arbitraries-cli.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ import {
1313
getCliCommandSchema,
1414
getFlagDefinitions,
1515
type FlagDefinition,
16-
} from '../../src/cli-schema/command-schema.ts';
17-
import { isFlagSupportedForCommand } from '../../src/cli-schema/option-schema.ts';
16+
} from '../../src/commands/schema/command-schema.ts';
17+
import { isFlagSupportedForCommand } from '../../src/commands/schema/option-schema.ts';
1818
import { encodeValidationCase, type ValidationCase } from './validation-case.ts';
1919
import { ACCEPT, SAFE_VALUES } from './validation-values.ts';
2020

‎scripts/layering/check.ts‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,14 @@
33
//
44
// Ranked target spine, as rank groups lowest to highest. `A ◄ B` means B may not
55
// be outranked by A (the back-edge order the gate rejects), NOT that every displayed import exists:
6-
// { contracts, request, selectors } ◄ core ◄ { commands, cli-schema }
6+
// { contracts, request, selectors } ◄ core ◄ commands
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).
10+
// `commands/schema/` renders the rest of commands/'s facets and reads them; commands never
11+
// imports it back (#2543). It shares the commands zone (#2679 folded the standalone
12+
// cli-schema zone into it), so the ranked spine and the R2 zone-policy table cannot see the
13+
// edge — `commands-schema-boundary.ts` enforces the direction as a folder-scoped rule instead.
1314
//
1415
// This gate enforces five things, across four scopes:
1516
// - GLOBALLY, across every production source file: the remaining R2 move rule and
@@ -103,6 +104,7 @@ import {
103104
readTrackedPlatformPackageDeclarations,
104105
} from './platform-package-repository.ts';
105106
import { policyLead, policyViolation, ZONE_POLICIES } from './zone-policy.ts';
107+
import { checkCommandsSchemaBoundary } from './commands-schema-boundary.ts';
106108
import { contractsImplementationAuthorityViolations } from './contracts-implementation-policy.ts';
107109
import { substrateDomainShapeViolations } from './substrate-domain-shape.ts';
108110
import { selectorPipelineOwnershipViolations } from './selector-pipeline-ownership.ts';
@@ -436,6 +438,7 @@ export type LayeringRule = (context: LayeringContext) => LayeringViolation[];
436438
*/
437439
export const LAYERING_RULE_IDS = [
438440
'zone-policies',
441+
'commands-schema-boundary',
439442
'value-import-cycles',
440443
'runtime-execution-integrity',
441444
'source-execution-compatibility',
@@ -468,6 +471,7 @@ export type LayeringRuleId = (typeof LAYERING_RULE_IDS)[number];
468471

469472
export const LAYERING_RULES: Readonly<Record<LayeringRuleId, LayeringRule>> = {
470473
'zone-policies': (context) => checkLayeringRules(context.edges),
474+
'commands-schema-boundary': (context) => checkCommandsSchemaBoundary(context.edges),
471475
'value-import-cycles': (context) => checkCycles(context.edges),
472476
'runtime-execution-integrity': (context) => runtimeExecutionIntegrityViolations(context.sources),
473477
'source-execution-compatibility': (context) =>
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'node:test';
3+
import { checkCommandsSchemaBoundary } from './commands-schema-boundary.ts';
4+
import { targetDagZone, type ResolvedImportEdge } from './model.ts';
5+
6+
function importEdge(
7+
file: string,
8+
target: string,
9+
overrides: Partial<ResolvedImportEdge> = {},
10+
): ResolvedImportEdge {
11+
return {
12+
file,
13+
target,
14+
spec: target,
15+
line: 1,
16+
dynamic: false,
17+
typeOnly: false,
18+
symbols: [],
19+
bindingResidue: false,
20+
fromZone: targetDagZone(file),
21+
toZone: targetDagZone(target),
22+
...overrides,
23+
};
24+
}
25+
26+
test('commands outside schema/ must not import commands/schema/', () => {
27+
const edge = importEdge('src/commands/capture/wait.ts', 'src/commands/schema/command-schema.ts');
28+
const violations = checkCommandsSchemaBoundary([edge]);
29+
assert.equal(violations.length, 1);
30+
assert.equal(violations[0]!.rule, 'R2 commands-floor');
31+
assert.match(violations[0]!.message, /must not import src\/commands\/schema\/command-schema\.ts/);
32+
});
33+
34+
test('holds for value, type-only, and dynamic imports alike', () => {
35+
for (const overrides of [{}, { typeOnly: true }, { dynamic: true }]) {
36+
const edge = importEdge(
37+
'src/commands/capture/wait.ts',
38+
'src/commands/schema/command-schema.ts',
39+
overrides,
40+
);
41+
assert.equal(checkCommandsSchemaBoundary([edge]).length, 1);
42+
}
43+
});
44+
45+
test('the declared direction — schema reading the rest of commands — stays silent', () => {
46+
const edge = importEdge(
47+
'src/commands/schema/command-schema.ts',
48+
'src/commands/command-metadata.ts',
49+
);
50+
assert.deepEqual(checkCommandsSchemaBoundary([edge]), []);
51+
});
52+
53+
test('schema importing its own sibling files stays silent', () => {
54+
const edge = importEdge(
55+
'src/commands/schema/cli-help.ts',
56+
'src/commands/schema/command-schema.ts',
57+
);
58+
assert.deepEqual(checkCommandsSchemaBoundary([edge]), []);
59+
});
60+
61+
test('a non-commands zone importing commands/schema/ is not this rule’s concern', () => {
62+
const edge = importEdge('src/mcp/server-guide.ts', 'src/commands/schema/cli-help.ts');
63+
assert.deepEqual(checkCommandsSchemaBoundary([edge]), []);
64+
});
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
// Catches: a file under src/commands/ (outside commands/schema/) importing back into
2+
// commands/schema/ — the render-the-facets direction #2543 declared (cli-schema reads
3+
// commands, commands never reads cli-schema back). #2679 folded the standalone cli-schema
4+
// zone into commands/schema/, so the two now share one zone and the ranked-spine / R2
5+
// zone-policy table can no longer see the edge at all: checkLayeringRules in check.ts skips
6+
// every same-zone edge before ZONE_POLICIES ever runs. This is the folder-scoped
7+
// replacement for that lost R2 row.
8+
// Evidence: #2543 declared the direction as the second R2 commands-floor row in
9+
// zone-policy.ts; #2679 moved src/cli-schema/* into src/commands/schema/* and found the
10+
// direction unenforced on the merged tree.
11+
// Cost: ~30 LOC (rule + test).
12+
// Kill criterion: none enforced today; retire only by maintainer decision that commands/
13+
// reading its own schema layer back is fine, or that commands/schema/ should move out of
14+
// the commands zone entirely (at which point the ranked-spine R2 table can express the
15+
// direction again).
16+
17+
import { matchesDeclaredRoot } from './architecture-ownership.ts';
18+
import type { LayeringViolation, ResolvedImportEdge } from './model.ts';
19+
20+
const COMMANDS_SCHEMA_ROOT = 'src/commands/schema/';
21+
const COMMANDS_ROOT = 'src/commands/';
22+
23+
export function checkCommandsSchemaBoundary(
24+
edges: readonly ResolvedImportEdge[],
25+
): LayeringViolation[] {
26+
return edges
27+
.filter(
28+
(edge) =>
29+
matchesDeclaredRoot(edge.file, COMMANDS_ROOT) &&
30+
!matchesDeclaredRoot(edge.file, COMMANDS_SCHEMA_ROOT) &&
31+
matchesDeclaredRoot(edge.target, COMMANDS_SCHEMA_ROOT),
32+
)
33+
.map((edge) => ({
34+
rule: 'R2 commands-floor',
35+
file: edge.file,
36+
line: edge.line,
37+
message:
38+
`${edge.file} must not import ${edge.target}: commands/schema/ is the CLI/MCP schema ` +
39+
'layer that renders the command facets, so it sits above the rest of commands/ and ' +
40+
'reads them; commands must not import it back (#2543). The shared CommandSchema type ' +
41+
'and flag grammar live in @agent-device/command-registry, below both.',
42+
}));
43+
}

0 commit comments

Comments
 (0)