@oscaner-skills/cdd-engine 2.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/{src-next/bin.ts → dist/bin.js} +18 -21
  4. package/dist/contract/declare.js +998 -0
  5. package/dist/contract/doc.js +565 -0
  6. package/dist/contract/frontmatter.js +209 -0
  7. package/dist/contract/home-extractors.js +379 -0
  8. package/dist/contract/invariants.js +1030 -0
  9. package/dist/contract/judge.js +109 -0
  10. package/dist/contract/lint.js +206 -0
  11. package/dist/contract/project.js +371 -0
  12. package/dist/contract/skill-anatomy.js +156 -0
  13. package/dist/contract/translate.js +85 -0
  14. package/dist/face/artifacts.js +189 -0
  15. package/dist/face/board-view.js +522 -0
  16. package/dist/face/capsule.js +141 -0
  17. package/dist/face/cli.js +891 -0
  18. package/dist/face/declare.js +241 -0
  19. package/dist/face/gate.js +158 -0
  20. package/dist/face/graph-view.js +66 -0
  21. package/dist/face/host.js +211 -0
  22. package/dist/face/lifecycle.js +603 -0
  23. package/dist/face/preview.js +136 -0
  24. package/dist/face/projection.js +259 -0
  25. package/dist/face/route-render.js +162 -0
  26. package/dist/face/termination.js +482 -0
  27. package/dist/face/words.js +220 -0
  28. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  29. package/dist/infra/doc-roots.js +19 -0
  30. package/dist/infra/git.js +37 -0
  31. package/dist/infra/process.js +22 -0
  32. package/dist/infra/root.js +62 -0
  33. package/dist/infra/runtime.js +85 -0
  34. package/dist/infra/workspace.js +276 -0
  35. package/dist/render/brief.js +82 -0
  36. package/dist/render/issue-body.js +129 -0
  37. package/dist/render/skeleton.js +434 -0
  38. package/dist/render/templates.js +520 -0
  39. package/dist/session/faces.js +38 -0
  40. package/dist/session/graph.js +309 -0
  41. package/dist/session/handoff-schema.js +295 -0
  42. package/dist/session/ledger.js +762 -0
  43. package/dist/session/next.js +211 -0
  44. package/dist/session/preflight.js +194 -0
  45. package/dist/session/round-naming.js +73 -0
  46. package/dist/session/run.js +441 -0
  47. package/dist/session/state.js +8 -0
  48. package/dist/session/wave.js +92 -0
  49. package/package.json +8 -7
  50. package/templates/report/issue-body.json +0 -46
  51. package/src-next/__tests__/bin.test.ts +0 -128
  52. package/src-next/__tests__/smoke.integration.test.ts +0 -202
  53. package/src-next/__tests__/zero-dep.test.ts +0 -134
  54. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
  55. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
  58. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
  59. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
  62. package/src-next/contract/__tests__/declare.test.ts +0 -242
  63. package/src-next/contract/__tests__/doc.test.ts +0 -358
  64. package/src-next/contract/__tests__/judge.test.ts +0 -873
  65. package/src-next/contract/__tests__/lint.test.ts +0 -314
  66. package/src-next/contract/__tests__/project.test.ts +0 -419
  67. package/src-next/contract/__tests__/translate.test.ts +0 -96
  68. package/src-next/contract/declare.ts +0 -983
  69. package/src-next/contract/doc.ts +0 -753
  70. package/src-next/contract/invariants.ts +0 -1268
  71. package/src-next/contract/judge.ts +0 -142
  72. package/src-next/contract/lint.ts +0 -275
  73. package/src-next/contract/project.ts +0 -596
  74. package/src-next/contract/skill-anatomy.ts +0 -273
  75. package/src-next/contract/translate.ts +0 -113
  76. package/src-next/face/__tests__/board-view.test.ts +0 -948
  77. package/src-next/face/__tests__/capsule.test.ts +0 -276
  78. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
  79. package/src-next/face/__tests__/cli.test.ts +0 -4643
  80. package/src-next/face/__tests__/face.test.ts +0 -289
  81. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  82. package/src-next/face/__tests__/host.test.ts +0 -24
  83. package/src-next/face/__tests__/negation.ts +0 -6
  84. package/src-next/face/__tests__/projection.test.ts +0 -301
  85. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
  86. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  87. package/src-next/face/artifacts.ts +0 -195
  88. package/src-next/face/board-view.ts +0 -662
  89. package/src-next/face/capsule.ts +0 -149
  90. package/src-next/face/cli.ts +0 -819
  91. package/src-next/face/declare.ts +0 -326
  92. package/src-next/face/gate.ts +0 -170
  93. package/src-next/face/graph-view.ts +0 -74
  94. package/src-next/face/host.ts +0 -326
  95. package/src-next/face/lifecycle.ts +0 -700
  96. package/src-next/face/projection.ts +0 -282
  97. package/src-next/face/route-render.ts +0 -160
  98. package/src-next/face/words.ts +0 -296
  99. package/src-next/infra/__tests__/infra.test.ts +0 -287
  100. package/src-next/infra/git.ts +0 -39
  101. package/src-next/infra/process.ts +0 -34
  102. package/src-next/infra/runtime.ts +0 -185
  103. package/src-next/infra/workspace.ts +0 -232
  104. package/src-next/render/__tests__/render.test.ts +0 -499
  105. package/src-next/render/__tests__/skeleton.test.ts +0 -466
  106. package/src-next/render/brief.ts +0 -121
  107. package/src-next/render/issue-body.ts +0 -159
  108. package/src-next/render/skeleton.ts +0 -437
  109. package/src-next/render/templates.ts +0 -650
  110. package/src-next/session/__tests__/graph.test.ts +0 -270
  111. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  112. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  113. package/src-next/session/__tests__/ledger.test.ts +0 -744
  114. package/src-next/session/__tests__/next.test.ts +0 -368
  115. package/src-next/session/__tests__/preflight.test.ts +0 -491
  116. package/src-next/session/__tests__/run.test.ts +0 -1014
  117. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  118. package/src-next/session/__tests__/wave.test.ts +0 -469
  119. package/src-next/session/faces.ts +0 -110
  120. package/src-next/session/graph.ts +0 -411
  121. package/src-next/session/handoff-schema.ts +0 -373
  122. package/src-next/session/ledger.ts +0 -1004
  123. package/src-next/session/next.ts +0 -192
  124. package/src-next/session/preflight.ts +0 -240
  125. package/src-next/session/run.ts +0 -606
  126. package/src-next/session/state.ts +0 -30
  127. package/src-next/session/wave.ts +0 -139
@@ -0,0 +1,136 @@
1
+ // packages/cdd-engine/src-next/face/preview.ts
2
+ // P11 T5 — the `--dry-run` preview renderer (spec §3.3): the read-only next-step
3
+ // forecast becomes ONE renderer class instead of a simulated run. The preview states
4
+ // the step the next real invocation would dispatch, the artifacts it would write and
5
+ // the ledger writes it would record — and nothing else: zero repo writes, no round
6
+ // consumed, no child spawned. The retired synthetic dispatch (`() => ({ status:
7
+ // "APPROVED", findings: [] })`) is gone with it — a preview never fabricates a
8
+ // conclusion, so no `status:` / `next:` line is ever printed.
9
+ //
10
+ // The renderer reads the assembled scene (the same DispatchScene the lifecycle
11
+ // dispatch reads — one scene shape, never a second) and names every artifact through
12
+ // RoundNaming (session/round-naming.ts), the ONE naming source the lifecycle's
13
+ // write-back and read-back share (T4): the preview and the real dispatch name the
14
+ // same files by one rule. The `child:` row is the harness contract's own data
15
+ // (face/host.ts) — the host id + the row's invoke argument string — never a
16
+ // detection-dependent spawn.
17
+ //
18
+ // Module-level exports are the class — zero behavior-carrying bare functions.
19
+ import process from "node:process";
20
+ import { RoundNaming } from "../session/round-naming.js";
21
+ import { HOSTS, HostDetect } from "./host.js";
22
+ /** The preview row's label column width — ` ` + the label padded to this width +
23
+ * one space places every value at the same column (`would record:` — the longest
24
+ * label — overflows by its own one character, exactly as the §3.3 block reads). */
25
+ const LABEL_WIDTH = 12;
26
+ /**
27
+ * Preview — the `--dry-run` read-only preview renderer. One instance renders one
28
+ * invocation's block over the scene the work command already assembled; the host is
29
+ * detected once at construction (the injectable-env adapter over the harness
30
+ * contract's own judgment). Nothing in this class writes, dispatches or records.
31
+ */
32
+ export class Preview {
33
+ #scene;
34
+ /** The round-naming single source (P11 T4) — the same derivations the lifecycle's
35
+ * write-back and read-back read, so the preview never invents a name. */
36
+ #naming;
37
+ /** The detected host id ("" when no harness marker matched) — read by the `child:`
38
+ * row only. */
39
+ #host;
40
+ constructor(opts) {
41
+ this.#scene = opts.scene;
42
+ this.#naming = new RoundNaming(opts.scene.workspace);
43
+ this.#host = HostDetect.detect(opts.env ?? process.env);
44
+ }
45
+ /** The invocation's stdout block — the header plus the five rows (§3.3). Every
46
+ * path token is repoRoot-relative (D47's ONE shape — the same basis the round
47
+ * context speaks). No `status:` / `next:` line is emitted: the round's conclusion
48
+ * is not yet decided (printing one would fabricate it) and the cross-round next
49
+ * hop belongs to `cdd board <slug>`. */
50
+ render(verb, frame) {
51
+ const rows = [
52
+ ["step:", this.#stepOf(frame)],
53
+ ["reads:", this.#readsOf(frame)],
54
+ ["would write:", this.#writesOf(frame)],
55
+ ["would record:", this.#recordsOf(frame)],
56
+ ["child:", this.#childOf()],
57
+ ];
58
+ return [
59
+ `cdd ${verb}: preview (no repo changes)`,
60
+ ...rows.map(([label, value]) => ` ${label.padEnd(LABEL_WIDTH)} ${value}`),
61
+ ];
62
+ }
63
+ /** The next dispatch step's identity — `<phase> round <round> — <target>`, the
64
+ * target being the wave unit (`wave 1,2`) or the line's own type word. */
65
+ #stepOf(frame) {
66
+ return `${frame.phase} round ${frame.round} — ${this.#targetOf(frame)}`;
67
+ }
68
+ /** The step's target word — the wave-unitary unit (the whole ready batch) on the
69
+ * task face, the line type elsewhere. */
70
+ #targetOf(frame) {
71
+ return frame.target.kind === "wave" ? `wave ${frame.target.tasks.join(",")}` : frame.type;
72
+ }
73
+ /** The round's read input — the wave face's brief (the ONE engine-rendered brief
74
+ * the real dispatch re-extracts from the CURRENT plan; the preview does not render
75
+ * it, so the row states what that render would produce) and the doc/branch faces'
76
+ * judged document. */
77
+ #readsOf(frame) {
78
+ if (frame.target.kind === "wave") {
79
+ const brief = this.#rel(this.#naming.brief(frame.target.tasks.join(",")));
80
+ return `${brief} (would re-render from the current plan)`;
81
+ }
82
+ if (frame.target.kind === "plan" || frame.target.kind === "spec")
83
+ return this.#rel(frame.target.doc);
84
+ return this.#rel(this.#scene.planPath ?? "");
85
+ }
86
+ /** The artifacts the round would write — the frame's prescribed output set (the
87
+ * handoff carrier, the round report and the work faces' test evidence), named by
88
+ * the ONE naming source. A slot the frame's family does not consume (a review
89
+ * round prescribes no evidence file) is dropped, never rendered blank. */
90
+ #writesOf(frame) {
91
+ return [
92
+ this.#scene.ledger.handoffPath(this.#naming.op(frame), frame.type, frame.params),
93
+ this.#naming.report(frame),
94
+ this.#naming.evidence(frame),
95
+ ]
96
+ .filter((artifact) => artifact !== "")
97
+ .map((artifact) => this.#rel(artifact))
98
+ .join(" · ");
99
+ }
100
+ /** The ledger writes the round would record — the progress cycle (the frame's OWN
101
+ * round identity, never a flattened ordinal) plus, on a completed review, the
102
+ * reviewed-revision write-back. The three legs are `#bookkeep`'s own: the doc line
103
+ * binds its document's revision, the wave line its RENDERED brief's, and the
104
+ * branch line binds none (its review judges the live tree). */
105
+ #recordsOf(frame) {
106
+ const parts = [`progress.waves["${frame.key}"].rounds.${frame.phase} += [${frame.round}]`];
107
+ if (frame.phase === "review") {
108
+ if (frame.target.kind === "wave")
109
+ parts.push("reviewedRevision(brief)");
110
+ else if (frame.target.kind === "plan" || frame.target.kind === "spec")
111
+ parts.push("reviewedRevision(doc)");
112
+ }
113
+ return parts.join(" · ");
114
+ }
115
+ /** The child invocation the real run would spawn — `<HostId> <invoke>`: the host
116
+ * id then the harness row's invoke argument string verbatim (the binary name is a
117
+ * separate row column and never rides the invoke value). With no host detected the
118
+ * real run would BLOCK before any spawn — the row states that literal rather than
119
+ * indexing an absent host row. */
120
+ #childOf() {
121
+ if (this.#host === "")
122
+ return "(no host detected — real run would BLOCK)";
123
+ return `${this.#host} ${HOSTS[this.#host].invoke}`;
124
+ }
125
+ /** The repoRoot-relative form of one path token (D47). The empty value stays
126
+ * empty — a dropped slot is never rendered as the repo root. */
127
+ #rel(value) {
128
+ return value === "" ? "" : this.#repoRootValue().relativize(value);
129
+ }
130
+ /** The repo-basis value object of this scene — the ONE conversion entry every path
131
+ * token normalizes through (the workspace root's OWN value object, never
132
+ * re-wrapped here). */
133
+ #repoRootValue() {
134
+ return this.#scene.workspace.root.basis;
135
+ }
136
+ }
@@ -0,0 +1,259 @@
1
+ // packages/cdd-engine/src-next/face/projection.ts
2
+ // §2.1 — the single projection class: the declare single surface (face/declare.ts
3
+ // — the argv channel + the seven-command rows + REQUIRED_GROUPS) assembles the
4
+ // commander command tree, ENTIRELY in the constructor (the constructor-is-the-
5
+ // assembly stance · §2.1/§2.3):
6
+ // the top-level `cdd` program · the seven commands with their descriptions · the
7
+ // nested leaves (base set|get · schema get|gen · issue render) · the binding rules
8
+ // (command keys → .option()/.requiredOption() · positionals → .argument() ·
9
+ // bool rows single-spelling · the program scope merged into every node · the help
10
+ // channel row un-projected — the built-in helpOption) · the parseArg value-domain
11
+ // validation (commander.InvalidArgumentError · §4.1 · the retired validator) ·
12
+ // the program-level preAction conditional-required hook (REQUIRED_GROUPS · §4.2)
13
+ // · the help injections (§5.1 — Examples + the --dry-run tail note).
14
+ //
15
+ // The class's one exit is `readonly program: Command` — the T3 composition root
16
+ // parses through it and Its help/usage bytes are the commander-native product (the
17
+ // self-built usage corpus never existed here). Zero module-level behavior-
18
+ // carrying bare functions — the projection algorithm lives in the single
19
+ // CommandTreeBuilder class; the value-domain rules are declaration data
20
+ // (declare.ts VALUE_SHAPES), read by the builder's one table-driven executor
21
+ // (the plan's zero-bare-function discipline).
22
+ import { Command, InvalidArgumentError } from "commander";
23
+ import { ARGV_CHANNEL, CLI_COMMANDS, REQUIRED_GROUPS, SCHEMA_TYPE_KEYS, VALUE_SHAPES, } from "./declare.js";
24
+ /** The primary schema <type> spellings — the self-mapping vocabulary rows (the
25
+ * argument description's value list; derived from the one table, never a
26
+ * hand-written second list). */
27
+ const SCHEMA_PRIMARY_KEYS = Object.entries(SCHEMA_TYPE_KEYS)
28
+ .filter(([spelling, key]) => spelling === key)
29
+ .map(([spelling]) => spelling);
30
+ /** The channel table widened to its record face — the literal const stays the
31
+ * declaration's data source (its `satisfies` pins the row type at declare.ts);
32
+ * the projection indexes it by declared key at runtime. */
33
+ const CHANNEL_TABLE = ARGV_CHANNEL;
34
+ /** The value-domain table widened to its lookup face — the literal const stays
35
+ * the declaration's data source; the projection indexes it by the row's
36
+ * declared type and absence (the string/path/bool faces) registers no parser. */
37
+ const SHAPE_TABLE = VALUE_SHAPES;
38
+ /**
39
+ * CommandTreeBuilder — the declaration → commander projection. The constructor
40
+ * performs the whole assembly; `program` is the complete tree (parse + help +
41
+ * validation + the preAction groups all wired). The value-domain rejections throw
42
+ * commander.InvalidArgumentError (the composed pipeline names the option + value
43
+ * with the commander-native bytes — the usage domain's exit 2 is the run face's
44
+ * normalization, §3.1).
45
+ */
46
+ export class CommandTreeBuilder {
47
+ /** The assembled commander program — the composition root's parse + help face. */
48
+ program;
49
+ constructor() {
50
+ this.program = new Command("cdd");
51
+ // The exit override is wired FIRST — every .command() copies the inherited
52
+ // settings (incl. the callback), so a parse rejection anywhere in the tree
53
+ // throws the CommanderError instead of process.exit (the discrimination face
54
+ // of §3.1: err.code + err.exitCode). The projection tests assert through the
55
+ // same thrown errors.
56
+ this.program.exitOverride();
57
+ this.program.description("the CDD engine's command line");
58
+ this.program.addHelpText("afterAll", "program flags (accepted at any position): --dry-run (implement/review/fix only)");
59
+ this.#bindProgramScopes(this.program);
60
+ this.#injectProgramExamples();
61
+ for (const spec of CLI_COMMANDS)
62
+ this.#projectCommand(spec);
63
+ this.program.hook("preAction", (_thisCommand, actionCommand) => this.#assertRequiredGroups(actionCommand));
64
+ }
65
+ // ---------------------------------------------------------------------------
66
+ // the command-tree projection
67
+ // ---------------------------------------------------------------------------
68
+ /** One command node — the description + the option/argument binding + the
69
+ * program scopes + the Examples injection + the nested leaves. */
70
+ #projectCommand(spec) {
71
+ const node = this.program.command(spec.name);
72
+ node.description(spec.description);
73
+ this.#bindOptions(node, spec.keys);
74
+ this.#bindArguments(node, spec.positionals);
75
+ this.#bindProgramScopes(node);
76
+ if (spec.example !== undefined) {
77
+ node.addHelpText("after", `Examples:\n ${spec.example}`);
78
+ }
79
+ for (const leaf of spec.leaves ?? [])
80
+ this.#projectLeaf(node, leaf);
81
+ }
82
+ /** One leaf node (base set|get · schema get|gen · issue render) — the leaf
83
+ * granularity is structural: each leaf binds its OWN declared keys (the §5.3
84
+ * did-you-mean candidate sets follow the errored node, never a sibling's). */
85
+ #projectLeaf(parent, leaf) {
86
+ const node = parent.command(leaf.name);
87
+ node.description(leaf.description);
88
+ this.#bindOptions(node, leaf.keys);
89
+ this.#bindArguments(node, leaf.positionals);
90
+ this.#bindProgramScopes(node);
91
+ }
92
+ /** The option binding — the surface's declared keys → .option() /
93
+ * .requiredOption() (the row's flag + the value-domain token + the channel
94
+ * help text; the required rows ride .requiredOption()). */
95
+ #bindOptions(node, keys) {
96
+ for (const declared of keys) {
97
+ const row = CHANNEL_TABLE[declared.key];
98
+ // The channel audit (guard §2.2) closes every declared key — an absent row
99
+ // here is structurally unreachable; the guard stays the single check.
100
+ if (row === undefined)
101
+ continue;
102
+ this.#registerOption(node, declared, row);
103
+ }
104
+ }
105
+ /** One option registration on a node — the flags string (the value-domain token
106
+ * rides the option's own suffix, §5.2), the channel description (+ the
107
+ * required marker) and the value-domain parseArg (when the type validates). */
108
+ #registerOption(node, declared, row) {
109
+ const token = this.#valueToken(row, declared.valueType);
110
+ const flags = `${row.flag}${token === "" ? "" : ` ${token}`}`;
111
+ const help = `${this.#optionHelp(row, declared.valueType)}${declared.required === true ? " (required)" : ""}`;
112
+ const parseArg = this.#parseArgOf(row, declared.valueType);
113
+ if (declared.required === true) {
114
+ if (parseArg === undefined)
115
+ node.requiredOption(flags, help);
116
+ else
117
+ node.requiredOption(flags, help, parseArg);
118
+ }
119
+ else if (parseArg === undefined) {
120
+ node.option(flags, help);
121
+ }
122
+ else {
123
+ node.option(flags, help, parseArg);
124
+ }
125
+ }
126
+ /** The positional binding — one .argument() per declared positional (required →
127
+ * `<name>`, optional → `[name]`; the schema <type> argument validates through
128
+ * the typeKey vocabulary). */
129
+ #bindArguments(node, positionals) {
130
+ for (const positional of positionals ?? []) {
131
+ const raw = positional.key;
132
+ const bracket = positional.required === true ? `<${raw}>` : `[${raw}]`;
133
+ const description = this.#argumentDescription(raw);
134
+ const parseArg = raw === "type" ? (value) => this.#parseTypeKey(value) : undefined;
135
+ if (parseArg === undefined) {
136
+ if (description === "")
137
+ node.argument(bracket);
138
+ else
139
+ node.argument(bracket, description);
140
+ }
141
+ else {
142
+ node.argument(bracket, description, parseArg);
143
+ }
144
+ }
145
+ }
146
+ /** The program-scope merge — every `scope: "program"` channel row registers on
147
+ * the node (the any-position program-flag semantics, §2.1 cli.test.ts pins
148
+ * 494/698); the help row is skipped (the built-in helpOption face — never
149
+ * re-registered). Each node registers its own copy once (never re-registered). */
150
+ #bindProgramScopes(node) {
151
+ for (const [key, row] of Object.entries(CHANNEL_TABLE)) {
152
+ if (row.scope !== "program")
153
+ continue;
154
+ if (key === "help")
155
+ continue;
156
+ this.#registerOption(node, { key, required: false }, row);
157
+ }
158
+ }
159
+ // ---------------------------------------------------------------------------
160
+ // the value-domain validation (parseArg · commander.InvalidArgumentError · §4.1)
161
+ // ---------------------------------------------------------------------------
162
+ /** The value-domain token of one option — the display suffix (`<path>` ·
163
+ * `<n|n,n,…>` · `<a|b|c>` · `<n>`); the branch value-type override carries its
164
+ * own domain, the bool/string faces carry none. */
165
+ #valueToken(row, override) {
166
+ if (override === "branch")
167
+ return "<branch>";
168
+ switch (row.type) {
169
+ case "path":
170
+ return "<path>";
171
+ case "int-list":
172
+ return "<n|n,n,…>";
173
+ case "enum":
174
+ return `<${[...(row.values ?? [])].join("|")}>`;
175
+ case "int":
176
+ return "<n>";
177
+ default:
178
+ // bool / string — the flag alone carries the value domain face.
179
+ return "";
180
+ }
181
+ }
182
+ /** The option's help text — the channel row's single-source flag-level line;
183
+ * the branch value-type override swaps it for its own domain (the base-set
184
+ * face names the branch — the same override family as #valueToken's `<branch>`
185
+ * token). */
186
+ #optionHelp(row, override) {
187
+ if (override === "branch")
188
+ return "the base branch name";
189
+ return row.help ?? "";
190
+ }
191
+ /** The option's custom parser — the value-domain check of the validated
192
+ * types, table-driven from the declaration's VALUE_SHAPES (the branch
193
+ * override and the string/path/bool faces register none — a row without a
194
+ * shape gets no parser; absence is the registered face). */
195
+ #parseArgOf(row, override) {
196
+ if (override === "branch")
197
+ return undefined;
198
+ const shape = SHAPE_TABLE[row.type];
199
+ if (shape === undefined)
200
+ return undefined;
201
+ return (value) => shape.parse(value, row);
202
+ }
203
+ /** The schema `<type>` vocabulary check — the primary spellings validate and
204
+ * normalize to themselves, the legacy `phaseSpec` alias normalizes to the kebab
205
+ * key, an out-of-vocabulary type rejects (spec §5.3). */
206
+ #parseTypeKey(raw) {
207
+ const key = SCHEMA_TYPE_KEYS[raw];
208
+ if (key === undefined) {
209
+ throw new InvalidArgumentError(`unknown schema type: ${raw} (available: ${SCHEMA_PRIMARY_KEYS.join(", ")})`);
210
+ }
211
+ return key;
212
+ }
213
+ /** The argument's help description — the schema <type> face names its primary
214
+ * vocabulary (single-sourced at SCHEMA_TYPE_KEYS). */
215
+ #argumentDescription(raw) {
216
+ if (raw === "type")
217
+ return `the schema type — ${SCHEMA_PRIMARY_KEYS.join(" | ")}`;
218
+ return "";
219
+ }
220
+ // ---------------------------------------------------------------------------
221
+ // the conditional-required groups (preAction · §4.2)
222
+ // ---------------------------------------------------------------------------
223
+ /** The preAction assertion — the review/fix work commands' REQUIRED_GROUPS
224
+ * data: the target type's required face must be present on the action command's
225
+ * opts; a missing face throws the same InvalidArgumentError pipeline as a
226
+ * parseArg rejection (the run face normalizes it into the usage domain's exit
227
+ * 2). Non-exclusive — both `--plan` and `--spec` stay accepted together
228
+ * (no mutual-exclusion rejection). */
229
+ #assertRequiredGroups(actionCommand) {
230
+ const verb = actionCommand.name();
231
+ if (verb !== "review" && verb !== "fix")
232
+ return;
233
+ const type = actionCommand.opts().type;
234
+ if (type === undefined)
235
+ return;
236
+ const group = REQUIRED_GROUPS[verb][type];
237
+ if (group === undefined)
238
+ return;
239
+ const missing = group.filter((flag) => actionCommand.opts()[flag.slice(2)] === undefined);
240
+ if (missing.length > 0) {
241
+ throw new InvalidArgumentError(`${missing.join(" ")} required when --type ${type}`);
242
+ }
243
+ }
244
+ // ---------------------------------------------------------------------------
245
+ // the help injections (§5.1 — Examples + the --dry-run tail note)
246
+ // ---------------------------------------------------------------------------
247
+ /** The program face's Examples section — the rows' example lines (the P1
248
+ * sentences, single-sourced at the CLI_COMMANDS `example` fields). */
249
+ #injectProgramExamples() {
250
+ const examples = [];
251
+ for (const spec of CLI_COMMANDS) {
252
+ if (spec.example !== undefined)
253
+ examples.push(` ${spec.example}`);
254
+ }
255
+ if (examples.length > 0) {
256
+ this.program.addHelpText("after", `Examples:\n${examples.join("\n")}`);
257
+ }
258
+ }
259
+ }
@@ -0,0 +1,162 @@
1
+ // packages/cdd-engine/src-next/face/route-render.ts
2
+ // D40 — the ONE route → `next:` literal renderer (the shared render point): both
3
+ // the Capsule (a round's own line) and the board (a line's frontier) render the
4
+ // exact same Route into the exact same literal through this single class, so the
5
+ // board's `next:` and the engine's `next:` are byte-identical by construction
6
+ // (the retired board `#entryText` / capsule `#doneText` pair — one renderer now).
7
+ //
8
+ // · an active C5 hop (`implement` / `review` / `fix` / `soft-cap`) renders the
9
+ // complete executable argv composed from the frame facts (the RouteTarget's
10
+ // type + id + plan) through the argv-channel flag spellings — the same channel
11
+ // the CLI parse reads (never a second hard-coded format string);
12
+ // · the face-to-face `handoff` renders the pipeline entry: a `ref` resolves
13
+ // REFS[ref][host] (the `""` host falls back to the claude form — never a bare
14
+ // plugin guess), a `literal` fills its `<plan>` slot, a `done` entry the bare
15
+ // terminal word;
16
+ // · the bare `done` is the terminal word (its no-target face).
17
+ //
18
+ // The route-borne prose (the fix readback suffix · the soft-cap message) rides
19
+ // declared constants from session/next.ts, rendered by reference, never restated.
20
+ // Module-level exports are the class — zero behavior-carrying bare functions.
21
+ import { FIX_READBACK_SUFFIX } from "../session/next.js";
22
+ import { REFS } from "./host.js";
23
+ /**
24
+ * RouteRenderer — the single route → `next:` literal face (D40). One instance holds
25
+ * the render facts the literal needs (the word table · the argv-channel spellings ·
26
+ * the host harness id); render() turns a Route (+ the frame's own RouteTarget) into
27
+ * the `next:` value. The Capsule and the board both delegate here — no second
28
+ * renderer.
29
+ */
30
+ export class RouteRenderer {
31
+ /** The single word table — the literal's whole vocabulary source. */
32
+ #words;
33
+ /** The argv-channel flag spellings — the declared render source (parse's own). */
34
+ #channels;
35
+ /** The host harness id — the skill-ref resolution key of the handoff/`done`
36
+ * pipeline lookup (REFS[ref][host]; `""` falls back to the claude form). */
37
+ #host;
38
+ /** The repo-basis value object the literal's embedded path values normalize
39
+ * through (T1 `RepoRoot` · D47) — the ONE conversion exit; `null` (the
40
+ * hermetic-test default) passes values through unchanged. */
41
+ #root;
42
+ constructor(words, channels = {}, host = "", root = null) {
43
+ this.#words = words;
44
+ this.#channels = channels;
45
+ this.#host = host;
46
+ this.#root = root;
47
+ }
48
+ /** One embedded path value in the literal — normalized to the repoRoot-relative
49
+ * shape through the ONE value object (D47 · the ONE basis; a `null` root — the
50
+ * hermetic default — short-circuits). Every `--plan`/`--reviews`/doc-id in the
51
+ * rendered argv passes through here, so the board's `next:` and the engine's
52
+ * `next:` are byte-identical by construction. */
53
+ #rel(value) {
54
+ return this.#root === null ? value : this.#root.relativize(value);
55
+ }
56
+ /** render(route, target) → the `next:` value: the complete executable command (a
57
+ * C5 hop), the pipeline entry (a `handoff`), or the bare terminal word (`done`).
58
+ * The additive optional RouteTarget supplies the frame's own type + id + plan for
59
+ * the executable literal; without it the route renders its bare classifier
60
+ * fallbacks. */
61
+ render(route, target) {
62
+ switch (route.kind) {
63
+ case "done":
64
+ return this.#words.routeWord("done");
65
+ case "handoff":
66
+ return this.#handoffText(route, target);
67
+ case "next-wave":
68
+ return `${this.#words.routeWord("implement")} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("tasks")} ${route.tasks}`;
69
+ case "review":
70
+ return this.#reviewText(target);
71
+ case "fix":
72
+ return this.#fixText(route, target);
73
+ case "soft-cap":
74
+ return route.message;
75
+ }
76
+ }
77
+ /** The declared flag spelling of one channel key — the argv channel the CLI parse
78
+ * itself resolves (never a hard-coded format string; `--<key>` for a row-less key). */
79
+ #flag(key) {
80
+ return this.#channels[key]?.flag ?? `--${key}`;
81
+ }
82
+ /** The plan path of the literal — the frame's plan fact (the implement literal's
83
+ * required `--plan`), normalized to the repoRoot-relative shape (D47); the
84
+ * `<plan>` placeholder when the fact is absent (the bare fallback face — the
85
+ * mirror of the crash-resume's `<plan>` seed). */
86
+ #planOf(target) {
87
+ return target?.plan === undefined ? "<plan>" : this.#rel(target.plan);
88
+ }
89
+ /** The review hop's literal — `review --type <wave|spec|plan|branch> <type-arg>`
90
+ * (`--type` renders only where the verb's type discriminates — review/fix are
91
+ * multi-type, so they always carry it; absent target → the bare verb). */
92
+ #reviewText(target) {
93
+ const verb = this.#words.routeWord("review");
94
+ const type = target?.type ?? null;
95
+ if (type === "wave") {
96
+ // The wave review literal carries its runtime-required `--plan` — the same
97
+ // assembly the implement/next-wave and fix→wave branches share (a missing flag
98
+ // parses green yet refuses the dispatch at run time).
99
+ return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${target.id} ${this.#flag("plan")} ${this.#planOf(target)}`;
100
+ }
101
+ if (type === "spec") {
102
+ return `${verb} ${this.#flag("type")} spec ${this.#flag("spec")} ${this.#rel(target.id)}`;
103
+ }
104
+ if (type === "plan") {
105
+ return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${this.#rel(target.id)}`;
106
+ }
107
+ if (type === "branch") {
108
+ // The branch re-review literal carries only the workspace-identity `--plan` —
109
+ // the review judges the live tree, so no range rides the command (the scope
110
+ // anchor BASE_BRANCH is engine-injected at dispatch).
111
+ return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)}`;
112
+ }
113
+ return verb;
114
+ }
115
+ /** The one-way fix hop's literal — `fix --type <type> <type-arg> --reviews <path>
116
+ * <readback>` (the readback suffix the declared constant, rendered by reference).
117
+ * Every embedded path value (the doc-id for the spec/plan faces · `--reviews`)
118
+ * is normalized to the repoRoot-relative shape (D47); the wave face's `<type-arg>`
119
+ * is a task key, not a path — passed through as-is. */
120
+ #fixText(route, target) {
121
+ if (route.reviews === undefined)
122
+ return this.#words.routeWord("fix");
123
+ const verb = this.#words.routeWord("fix");
124
+ const type = target?.type ?? null;
125
+ const id = target?.id ?? "";
126
+ const reviews = this.#rel(route.reviews);
127
+ if (type === "wave") {
128
+ return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${id} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
129
+ }
130
+ if (type === "spec") {
131
+ return `${verb} ${this.#flag("type")} spec ${this.#flag("spec")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
132
+ }
133
+ if (type === "plan") {
134
+ return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
135
+ }
136
+ if (type === "branch") {
137
+ // The branch fix literal carries the workspace-identity `--plan` (isomorphic
138
+ // with the wave fix branch — a plan-less target resolves to the empty
139
+ // ref.short() directory, the workspace double identity).
140
+ return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
141
+ }
142
+ return `${verb} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
143
+ }
144
+ /** The face-to-face handoff render — the pipeline entry: a `ref` resolves
145
+ * REFS[ref][host] (the `""` host falls back to the claude form), a `literal`
146
+ * fills its `<plan>` slot with the frame's plan fact, a `done` entry renders the
147
+ * bare word. Never a hard-coded plugin spelling. */
148
+ #handoffText(route, target) {
149
+ const entry = route.entry;
150
+ if (entry.kind === "done")
151
+ return this.#words.routeWord("done");
152
+ if (entry.kind === "literal")
153
+ return entry.literal.replace("<plan>", this.#planOf(target));
154
+ // The ref table read over a dynamic ref key — the local's shape (`string → per-host
155
+ // form`) is the HostReferenceTable contract, so the lookup needs no key cast.
156
+ const table = REFS;
157
+ const row = table[entry.ref];
158
+ if (row === undefined)
159
+ return this.#words.routeWord("done");
160
+ return row[this.#host] ?? row.claude ?? this.#words.routeWord("done");
161
+ }
162
+ }