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