@oscaner-skills/cdd-engine 4.2.0 → 4.4.0

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 (58) hide show
  1. package/README.md +38 -9
  2. package/README.zh-CN.md +44 -10
  3. package/dist/contract/completion-criterion.js +351 -0
  4. package/dist/contract/declare.js +181 -43
  5. package/dist/contract/doc.js +84 -271
  6. package/dist/contract/frontmatter.js +2 -1
  7. package/dist/contract/home-extractors.js +49 -316
  8. package/dist/contract/invariants.js +400 -296
  9. package/dist/contract/judge.js +74 -49
  10. package/dist/contract/lint.js +3 -2
  11. package/dist/contract/liveness-signal.js +103 -0
  12. package/dist/contract/markdown-document.js +410 -0
  13. package/dist/contract/markdown-tree-types.js +6 -0
  14. package/dist/contract/markdown-tree.js +137 -0
  15. package/dist/contract/project.js +1 -1
  16. package/dist/contract/rules.js +106 -0
  17. package/dist/contract/selector-engine.js +332 -0
  18. package/dist/contract/selector-spec.js +74 -0
  19. package/dist/contract/skill-anatomy.js +29 -1
  20. package/dist/contract/task-block-grammar.js +285 -0
  21. package/dist/contract/task-blocks.js +65 -0
  22. package/dist/contract/translate.js +21 -0
  23. package/dist/contract/wave-width.js +15 -0
  24. package/dist/face/board-view.js +382 -172
  25. package/dist/face/capsule.js +73 -88
  26. package/dist/face/cli.js +152 -38
  27. package/dist/face/declare.js +42 -19
  28. package/dist/face/gate.js +119 -40
  29. package/dist/face/init.js +84 -25
  30. package/dist/face/lifecycle.js +540 -123
  31. package/dist/face/plugins.js +70 -2
  32. package/dist/face/preview.js +69 -18
  33. package/dist/face/route-render.js +60 -21
  34. package/dist/face/termination.js +135 -261
  35. package/dist/face/words.js +139 -13
  36. package/dist/infra/atomic.js +15 -0
  37. package/dist/infra/git.js +25 -0
  38. package/dist/infra/proc.js +150 -0
  39. package/dist/infra/round-log.js +104 -0
  40. package/dist/infra/runtime.js +16 -4
  41. package/dist/infra/workspace.js +7 -2
  42. package/dist/render/brief.js +15 -17
  43. package/dist/render/skeleton.js +41 -28
  44. package/dist/render/templates.js +128 -84
  45. package/dist/session/faces.js +47 -20
  46. package/dist/session/graph.js +13 -37
  47. package/dist/session/handoff-schema.js +16 -8
  48. package/dist/session/inflight.js +282 -0
  49. package/dist/session/ledger.js +603 -145
  50. package/dist/session/line-identity.js +33 -0
  51. package/dist/session/next.js +140 -80
  52. package/dist/session/pipeline.js +247 -0
  53. package/dist/session/preflight.js +276 -68
  54. package/dist/session/reviewed-identity.js +54 -0
  55. package/dist/session/round-naming.js +56 -8
  56. package/dist/session/run.js +364 -80
  57. package/dist/session/wave.js +94 -14
  58. package/package.json +13 -3
@@ -20,6 +20,7 @@
20
20
  // bare functions (the plan's zero-bare-function discipline); the projection
21
21
  // algorithm lives in the single CommandTreeBuilder class (face/projection.ts).
22
22
  import { InvalidArgumentError } from "commander";
23
+ import { MAX_TASKS_PER_WAVE } from "../contract/wave-width.js";
23
24
  import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
24
25
  import { HOST_IDS } from "./host.js";
25
26
  /** The argv channel table — the CLI flag/type/enum single source (the engine-config
@@ -29,7 +30,11 @@ import { HOST_IDS } from "./host.js";
29
30
  * text per key, shared by every command that declares it). */
30
31
  export const ARGV_CHANNEL = {
31
32
  plan: { flag: "--plan", type: "path", help: "the CDD plan document path" },
32
- spec: { flag: "--spec", type: "path", help: "the design-spec document path" },
33
+ spec: {
34
+ flag: "--spec",
35
+ type: "path",
36
+ help: "the document under review — a phase-spec, an overall charter or a single-spec",
37
+ },
33
38
  reviews: {
34
39
  flag: "--reviews",
35
40
  type: "path",
@@ -38,12 +43,12 @@ export const ARGV_CHANNEL = {
38
43
  tasks: {
39
44
  flag: "--tasks",
40
45
  type: "int-list",
41
- help: "the task ids of the wave group (comma-separated)",
46
+ help: `the task ids of the wave group (comma-separated) — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
42
47
  },
43
48
  type: {
44
49
  flag: "--type",
45
50
  type: "enum",
46
- values: ["wave", "branch", "spec", "plan"],
51
+ values: ["wave", "branch", "phase-spec", "overall", "plan", "single-spec"],
47
52
  help: "the target face of the round",
48
53
  },
49
54
  base: { flag: "--base", type: "string", help: "the base artifact branch name" },
@@ -55,6 +60,11 @@ export const ARGV_CHANNEL = {
55
60
  help: "the base artifact's source channel",
56
61
  },
57
62
  force: { flag: "--force", type: "bool", help: "override the existing base artifact" },
63
+ stealStale: {
64
+ flag: "--steal-stale",
65
+ type: "bool",
66
+ help: "take over a standing in-flight record whose holder is dead (the only takeover path)",
67
+ },
58
68
  harness: {
59
69
  flag: "--harness",
60
70
  type: "enum",
@@ -66,6 +76,11 @@ export const ARGV_CHANNEL = {
66
76
  type: "bool",
67
77
  help: "update the installed plugin set instead of installing it",
68
78
  },
79
+ includeRecommends: {
80
+ flag: "--include-recommends",
81
+ type: "bool",
82
+ help: "also install/update the recommended pi capability packages",
83
+ },
69
84
  dryRun: {
70
85
  flag: "--dry-run",
71
86
  type: "bool",
@@ -129,28 +144,30 @@ export const VALUE_SHAPES = {
129
144
  export const CLI_COMMANDS = [
130
145
  {
131
146
  name: "implement",
132
- description: "run the task implement phase",
147
+ description: `run the task implement phase — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
133
148
  example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
134
149
  keys: [
135
150
  { key: "tasks", required: true },
136
151
  { key: "plan", required: true },
152
+ { key: "stealStale" },
137
153
  ],
138
154
  },
139
155
  {
140
156
  name: "review",
141
- description: "run a review — task | branch | spec | plan",
142
- example: `cdd review --type spec --spec ${ENGINE_DOC_ROOTS.specs}/p3-design.md`,
157
+ description: "run a review — wave | branch | phase-spec | overall | plan | single-spec",
158
+ example: `cdd review --type phase-spec --spec ${ENGINE_DOC_ROOTS.specs}/p3-design.md`,
143
159
  keys: [
144
160
  { key: "type", required: true },
145
161
  { key: "tasks" },
146
162
  { key: "plan" },
147
163
  { key: "spec" },
148
164
  { key: "round" },
165
+ { key: "stealStale" },
149
166
  ],
150
167
  },
151
168
  {
152
169
  name: "fix",
153
- description: "fix review findings — task | branch | spec | plan",
170
+ description: "fix review findings — wave | branch | phase-spec | overall | plan | single-spec",
154
171
  example: "cdd fix --type wave --tasks 1 --reviews tasks-1-review-1.json",
155
172
  keys: [
156
173
  { key: "type", required: true },
@@ -158,6 +175,7 @@ export const CLI_COMMANDS = [
158
175
  { key: "reviews" },
159
176
  { key: "spec" },
160
177
  { key: "plan" },
178
+ { key: "stealStale" },
161
179
  ],
162
180
  },
163
181
  {
@@ -212,7 +230,7 @@ export const CLI_COMMANDS = [
212
230
  },
213
231
  {
214
232
  name: "board",
215
- description: "render the progress board from a --plan or --spec entry (overall/spec/plan/wave/branch)",
233
+ description: "render the progress board from a --plan or --spec entry (overall/phase-spec/single-spec/plan/wave/branch)",
216
234
  example: `cdd board --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
217
235
  keys: [{ key: "plan" }, { key: "spec" }],
218
236
  },
@@ -220,7 +238,7 @@ export const CLI_COMMANDS = [
220
238
  name: "init",
221
239
  description: "install or update the kairos plugin set for a harness",
222
240
  example: "cdd init --harness=claude",
223
- keys: [{ key: "harness", required: true }, { key: "update" }],
241
+ keys: [{ key: "harness", required: true }, { key: "update" }, { key: "includeRecommends" }],
224
242
  },
225
243
  ];
226
244
  /** The schema `<type>` vocabulary — the get leaf's ONE table (spec §5.3): the
@@ -236,23 +254,28 @@ export const SCHEMA_TYPE_KEYS = {
236
254
  phaseSpec: "phase-spec",
237
255
  };
238
256
  /** The conditional required group per work verb + target type — the preAction hook's
239
- * data face (spec §4.2): review `{plan}` / `{spec}` / `{plan}` · fix `{plan}` /
240
- * `{spec}` / `{findings, plan}` — every branch face carries the `--plan` workspace
241
- * identity (the branch line holds no commit ref: the review judges the live tree,
242
- * the scope anchor BASE_BRANCH is engine-injected at dispatch). Keyed by declared
243
- * flag spelling; non-exclusive — a round declaring both `--plan` and `--spec`
244
- * stays accepted (no mutual-exclusion rejection). */
257
+ * data face (spec §4.2): one row per `--type` value, keyed by the declared flag
258
+ * spelling. The doc shapes carry the `--spec` document (their declared `doc-type:`
259
+ * picks the contract the pre-flight judges); the wave/plan faces carry `--plan`, and
260
+ * every branch face carries the `--plan` workspace identity (the branch line holds
261
+ * no commit ref: the review judges the live tree, the scope anchor BASE_BRANCH is
262
+ * engine-injected at dispatch). Non-exclusive — a round declaring both `--plan` and
263
+ * `--spec` stays accepted (no mutual-exclusion rejection). */
245
264
  export const REQUIRED_GROUPS = {
246
265
  review: {
247
266
  wave: ["--plan"],
248
- spec: ["--spec"],
249
- plan: ["--plan"],
250
267
  branch: ["--plan"],
268
+ "phase-spec": ["--spec"],
269
+ overall: ["--spec"],
270
+ plan: ["--plan"],
271
+ "single-spec": ["--spec"],
251
272
  },
252
273
  fix: {
253
274
  wave: ["--plan"],
254
- spec: ["--spec"],
255
- plan: ["--plan"],
256
275
  branch: ["--reviews", "--plan"],
276
+ "phase-spec": ["--spec"],
277
+ overall: ["--spec"],
278
+ plan: ["--plan"],
279
+ "single-spec": ["--spec"],
257
280
  },
258
281
  };
package/dist/face/gate.js CHANGED
@@ -1,16 +1,22 @@
1
1
  // packages/cdd-engine/src-next/face/gate.ts
2
2
  // T8 — the split contract's gate face (§6.2: face/gate.ts — the target/line gate
3
3
  // family). The work commands' readiness gates — the single-target line's phase
4
- // derivation (#lineGate/#linePhase/#lineKey/#lineParams/#lineRoundRoute/#lineFixRoute),
5
- // the doc line's revision-aware BLOCK + pending-fix faces (#docLineBlock/
6
- // #pendingFixBlock/#docContent/#docVersionOf) and the group/line helpers
7
- // (#tasksOf/#renderBrief/#refFromHandoff). The method bodies are the pre-split Cli
8
- // members moved verbatim — behavior bytes identical; the root Cli holds the gate
9
- // instance and composes through it via its .action thin shells (zero bare functions).
4
+ // derivation (lineGate/#linePhase/#lineKey), the doc line's revision-aware BLOCK +
5
+ // pending-fix faces (#docLineBlock/#pendingFixBlock/#docContent/#docVersionOf), the
6
+ // ONE line-hop object the CLI refusal renders (lineHop + lineHopMessage, P22 §5.2)
7
+ // and the group/line helpers (#tasksOf/#renderBrief). The method bodies are the
8
+ // pre-split Cli members moved verbatim — behavior bytes identical; the root Cli
9
+ // holds the gate instance and composes through it via its .action thin shells (zero
10
+ // bare functions).
10
11
  import { readFileSync } from "node:fs";
12
+ import process from "node:process";
11
13
  import { FrontMatterExtractor } from "../contract/frontmatter.js";
12
14
  import { BriefRenderer } from "../render/brief.js";
13
15
  import { RoundNaming } from "../session/round-naming.js";
16
+ import { BoardView } from "./board-view.js";
17
+ import { ARGV_CHANNEL } from "./declare.js";
18
+ import { HostDetect } from "./host.js";
19
+ import { RouteRenderer } from "./route-render.js";
14
20
  /**
15
21
  * CliGate — the target/line gate family (the split contract's gate face): the
16
22
  * readiness judgments the work commands consult before dispatching a round. The
@@ -29,40 +35,54 @@ export class CliGate {
29
35
  * only the derived pending face, never a recomputed one. The task face holds no
30
36
  * separate gate here: the WaveGate's wrong-phase verdict (the pre-flight) IS the
31
37
  * task-face phase authority — the wave gate is the single phase authority. A
32
- * doc line's gate is the reviewGate method family (T8 · §3.5 · judgment order =
33
- * doc revision FIRST, shared by the lifecycle's frame phase so an opened gate
34
- * dispatches): a moved doc opens the review lead whatever the round/route state
35
- * says (fix after · backfill after · user-decision after are the SAME case — the
36
- * stuck "next round is fix after an aborted fix" never freezes a revised doc),
37
- * an unchanged doc yields the gate's "same" verdict — the pending fix DERIVED
38
- * from the latest review's non-APPROVED conclusion opens only the fix phase,
39
- * while the no-pending face falls back to the legacy rounds/routes judgment: a
40
- * completed-fix line reopens the review lead through its fix round's C5-1 route
41
- * (the lifecycle's own fall-through — an open gate and a dispatchable frame
42
- * agree), a truly closed line keeps the revision-aware BLOCK. An unbound line
43
- * (no identity on record / an unreadable doc) keeps the legacy round/route
44
- * judgment + the generic closed message (only present facts land). */
38
+ * doc line's gate is the reviewGate method family (T8 · §3.5), shared by the
39
+ * lifecycle's frame phase so an opened gate dispatches: a moved doc reopens the
40
+ * review lead on a line whose C5 hop is on the EXIT side (a closed line, `null`,
41
+ * or a face-to-face station — the ONE `Ledger#docReopens` judgment), while a
42
+ * still-pending fix keeps its hop (drift never outranks it, §5.5 ②) so the gate
43
+ * never refuses the round the ONE derivation names. An unchanged doc yields the
44
+ * gate's "same" verdict — the pending fix DERIVED from the latest review's
45
+ * non-APPROVED conclusion opens only the fix phase, while the no-pending face
46
+ * falls back to the legacy rounds/routes judgment: a completed-fix line reopens
47
+ * the review lead through its fix round's C5-1 route (the lifecycle's own
48
+ * fall-through — an open gate and a dispatchable frame agree), a truly closed line
49
+ * keeps the revision-aware BLOCK. An unbound line (no identity on record / an
50
+ * unreadable doc) keeps the legacy round/route judgment + the generic closed
51
+ * message (only present facts land).
52
+ *
53
+ * The branch line rides the SAME drift leg (its identity document is the PLAN,
54
+ * P21 §3/§4.1 — the very document a branch re-review judges): a plan revision
55
+ * moved past the bound one reopens the branch face onto its `branch-review`
56
+ * lead, so the `next:` a closure hands the user is never a command this gate
57
+ * refuses. An unchanged plan falls through to the SAME derived faces the doc lines
58
+ * reach: a branch review that left findings yields the derived `fix` face
59
+ * (`pending-fix` — no doc-class BLOCK message binds the branch face, so the refusal
60
+ * renders through the ONE line hop), while only a fully closed, drift-free branch
61
+ * line keeps the generic `face-closed` row. */
45
62
  lineGate(scene) {
46
- if (scene.target?.kind === "plan" || scene.target?.kind === "spec") {
47
- const key = this.#lineKey(scene);
48
- if (key === null)
49
- return { phase: null, verdict: null, reviewed: null };
50
- const verdict = scene.ledger.reviewGate(key, scene.target.doc, scene.face.type);
51
- if (verdict.kind === "open") {
52
- return { phase: scene.face.product.reviewLead, verdict: null, reviewed: null };
53
- }
54
- if (verdict.kind === "same") {
55
- if (verdict.pending) {
56
- return { phase: "fix", verdict: "pending-fix", reviewed: verdict.reviewed };
57
- }
58
- // same + no pending fix — the legacy rounds/routes judgment (the lifecycle's
59
- // own fall-through): a completed-fix line reopens the review lead through its
60
- // fix round's C5-1 route; a truly closed line keeps the revision-aware BLOCK.
61
- const open = this.#linePhase(scene);
62
- return open !== null
63
- ? { phase: open, verdict: null, reviewed: null }
64
- : { phase: null, verdict: "same", reviewed: verdict.reviewed };
63
+ const key = this.#lineKey(scene);
64
+ const doc = this.#docOf(scene);
65
+ const verdict = key !== null && doc !== null ? scene.ledger.reviewGate(key, doc, scene.face.type) : null;
66
+ // The drift leg reads the ONE reopen judgment (exit-side routes only): a moved doc
67
+ // reopens the review lead on a line whose C5 hop is gone, while a still-pending
68
+ // fix keeps its own hop — drift never outranks it (§5.1 · §5.5 ②), so this gate
69
+ // always accepts the round the ONE derivation names.
70
+ if (key !== null &&
71
+ verdict !== null &&
72
+ scene.ledger.docReopens(key, scene.face.type, verdict)) {
73
+ return { phase: scene.face.product.reviewLead, verdict: null, reviewed: null };
74
+ }
75
+ if (verdict !== null && verdict.kind === "same") {
76
+ if (verdict.pending) {
77
+ return { phase: "fix", verdict: "pending-fix", reviewed: verdict.reviewed };
65
78
  }
79
+ // same + no pending fix — the legacy rounds/routes judgment (the lifecycle's
80
+ // own fall-through): a completed-fix line reopens the review lead through its
81
+ // fix round's C5-1 route; a truly closed line keeps the revision-aware BLOCK.
82
+ const open = this.#linePhase(scene);
83
+ return open !== null
84
+ ? { phase: open, verdict: null, reviewed: null }
85
+ : { phase: null, verdict: "same", reviewed: verdict.reviewed };
66
86
  }
67
87
  const open = this.#linePhase(scene);
68
88
  return { phase: open, verdict: null, reviewed: null };
@@ -92,6 +112,64 @@ export class CliGate {
92
112
  return null;
93
113
  return `the pending fix applies to the unchanged doc (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — run cdd fix first`;
94
114
  }
115
+ /** lineHop(scene) — this LINE's next-hop object (§5.2), the LINE FRONTIER's
116
+ * assembly: built from this line's facts through `Ledger#nextHopOf` (the ONE
117
+ * derivation entry: the drift gate + the declaration read). The capsule and the
118
+ * board render the PIPELINE frontier's assembly (`PipelineFrontier#hopOf`) instead,
119
+ * a different reader over a different input; this one serves the CLI rejection
120
+ * message, which renders THIS object's `reason` + hop/station
121
+ * — never a second judgment, never a second shape. The doc-class
122
+ * discrimination is ROOTED in the workspace's own repo basis (the same basis the
123
+ * lifecycle injects), so an engine invoked from a subdirectory reads the
124
+ * same declared `doc-type:` the board does. Null when the scene holds no
125
+ * registered line (no fixed target → there is no line to name). */
126
+ lineHop(scene) {
127
+ const key = this.#lineKey(scene);
128
+ const target = this.#routeTargetOf(scene);
129
+ if (key === null || target === null)
130
+ return null;
131
+ const basis = scene.workspace.root.basis;
132
+ return scene.ledger.nextHopOf({
133
+ type: scene.face.type,
134
+ key,
135
+ route: scene.ledger.lineRoute(key, scene.face.type),
136
+ target,
137
+ doc: this.#docOf(scene),
138
+ docClassOf: (candidate) => BoardView.docClassOf(basis, candidate),
139
+ });
140
+ }
141
+ /** lineHopMessage(scene, hop, words) — the CLI rejection prose of one `NextHop`
142
+ * (P22 §5.2, the ONE message shape): a hop names its verb, a closed face names
143
+ * its handoff station (rendered through the SAME route renderer the `next:` line
144
+ * uses), and neither renders an invented verb slot. */
145
+ lineHopMessage(scene, hop, words) {
146
+ if (hop === null)
147
+ return "the line holds no open round";
148
+ const renderer = new RouteRenderer(words, ARGV_CHANNEL, HostDetect.detect(process.env), scene.workspace.root.basis);
149
+ return scene.router.message(hop, (entry) => renderer.render({ kind: "handoff", entry }, hop.target));
150
+ }
151
+ /** The line's judged document — the doc line's own path, the branch line's plan
152
+ * (its identity document, P21 §4.1); null off the doc faces. */
153
+ #docOf(scene) {
154
+ if (scene.target?.kind === "plan" || scene.target?.kind === "spec")
155
+ return scene.target.doc;
156
+ if (scene.target?.kind === "branch")
157
+ return scene.planPath;
158
+ return null;
159
+ }
160
+ /** The dispatch frame's own render target (§5.2's `target` cell) — the fixed
161
+ * line's type + stable key (+ the plan fact the branch literal needs). A doc shape
162
+ * (the `--spec` channel: phase-spec / overall / single-spec) renders its OWN
163
+ * target-type word, never a folded `spec` spelling. */
164
+ #routeTargetOf(scene) {
165
+ if (scene.target?.kind === "branch")
166
+ return { type: "branch", id: "branch", plan: scene.planPath ?? undefined };
167
+ if (scene.target?.kind === "spec")
168
+ return { type: scene.face.type, id: scene.target.doc };
169
+ if (scene.target?.kind === "plan")
170
+ return { type: "plan", id: scene.target.doc };
171
+ return null;
172
+ }
95
173
  /** The requested group ints — the normalized tasks value split. */
96
174
  tasksOf(parsed) {
97
175
  return (parsed.args.tasks ?? "").split(",").map((part) => Number(part));
@@ -120,8 +198,9 @@ export class CliGate {
120
198
  return scene.ledger.linePhase(key, scene.face.type);
121
199
  }
122
200
  /** The line key of a fixed-target face — the line's STABLE key (find #9 · spec
123
- * §6.5/§3.7 — `"branch"` per workspace for the branch line; the doc line keys by
124
- * its line-type constant `"spec"`/`"plan"` — never the argv path: a moved argv
201
+ * §6.5/§3.7 — `"branch"` per workspace for the branch line; a doc line keys by
202
+ * its target-type word (`"phase-spec"` / `"overall"` / `"plan"` / `"single-spec"`)
203
+ * — never the argv path: a moved argv
125
204
  * string must not fork the same line into two ledger rows, resetting its round),
126
205
  * the lifecycle's own key derivation (run.ts #lineKey). */
127
206
  #lineKey(scene) {
package/dist/face/init.js CHANGED
@@ -23,7 +23,7 @@
23
23
  // a step is spawned.
24
24
  //
25
25
  // The dispatch execution machine (`face/termination.ts` — timeout / budget / group
26
- // kill / heartbeat / stall judge) is never shared: a bootstrap step has no round,
26
+ // kill / sampling trail / stall judge) is never shared: a bootstrap step has no round,
27
27
  // no ceiling and no session state.
28
28
  //
29
29
  // Module-level exports are types / declared constants / classes — zero
@@ -62,47 +62,106 @@ export class CliInit {
62
62
  this.#runner = opts.runner;
63
63
  this.#header = opts.header;
64
64
  }
65
- /** The ordered step plan for one harness + shape — the ONE flatten source the
66
- * preview and the real run both read. The only branch point between them is
67
- * whether `StepRunner` is called, so a preview can never drift from the run. */
68
- #stepsOf(host, update) {
65
+ /** The ordered step plan for one request — the ONE flatten source the preview and
66
+ * the real run both read. A `recommended === false` request takes the `core` rows
67
+ * only, which is the flag-less face's byte-identical plan; `true` takes the whole
68
+ * table in roster order (the recommended rows carry zero claude commands, so a
69
+ * claude request cannot grow beyond its core span). The only branch point between
70
+ * preview and run is whether `StepRunner` is called, so a preview can never drift
71
+ * from the run. */
72
+ #stepsOf(request) {
69
73
  const steps = [];
70
74
  for (const row of PLUGINS) {
71
- for (const argv of update ? row[host].update : row[host].install) {
72
- steps.push({ packageName: row.name, argv });
75
+ if (!request.recommended && row.tier !== "core")
76
+ continue;
77
+ const column = row[request.host];
78
+ for (const argv of request.shape === "update" ? column.update : column.install) {
79
+ steps.push({ packageName: row.name, argv, tier: row.tier });
73
80
  }
74
81
  }
75
82
  return steps;
76
83
  }
84
+ /** The tier split of one flattened plan — counted off each step's own `tier`.
85
+ * The tier fact travels with the step (§4.1), so no surface below re-reads the
86
+ * roster: `#stepsOf` is the only tier judge in this face. */
87
+ #tierCountsOf(steps) {
88
+ let core = 0;
89
+ for (const step of steps)
90
+ if (step.tier === "core")
91
+ core += 1;
92
+ return { core, recommended: steps.length - core };
93
+ }
94
+ /** The summary line — the flag-less bytes, plus the tier split only when the
95
+ * recommended tier was requested (§5.2). `ok` selects the run face's `ok` word;
96
+ * the preview face adds its dry-run tail instead. */
97
+ #summaryOf(steps, request, ok) {
98
+ const { core, recommended } = this.#tierCountsOf(steps);
99
+ const head = ok ? `init: ${steps.length} steps ok` : `init: ${steps.length} steps`;
100
+ const tier = request.recommended ? ` · ${core} core + ${recommended} recommended` : "";
101
+ const tail = ok ? "" : " — dry run, nothing executed";
102
+ return `${head} (${request.host} · ${request.shape}${tier})${tail}`;
103
+ }
104
+ /** The empty-tier info line — written only when the flag was requested and the
105
+ * flattened plan carries zero recommended steps (today: claude). A silent no-op
106
+ * would read as "installed", so the line is a hard requirement (§5.2). */
107
+ #emptyTierLinesOf(steps, request) {
108
+ if (!request.recommended || this.#tierCountsOf(steps).recommended > 0)
109
+ return [];
110
+ return [`init: no recommended packages for ${request.host}`];
111
+ }
112
+ /** The recommended-tier failure line — one wording per command shape (§5.3): the
113
+ * install form states the core set is already in place, the update form points at
114
+ * the install run instead of repeating the update that just failed. */
115
+ #recommendedFailureOf(step, request) {
116
+ const head = `init: ${step.packageName} is a recommended package — `;
117
+ return request.shape === "update"
118
+ ? `${head}run cdd init --harness=${request.host} --include-recommends without --update first`
119
+ : `${head}the core plugin set is already installed`;
120
+ }
121
+ /** The first-failure report — the pinned failure line, then the recommended-tier
122
+ * line (recommended steps only), then the unchanged update hint. Always exits 1. */
123
+ #reportFailure(steps, index, code, request) {
124
+ const step = steps[index];
125
+ this.#io.stderr(`init[${index + 1}/${steps.length}] · ${step.argv.join(" ")} · exit ${code}\n`);
126
+ if (step.tier === "recommended") {
127
+ this.#io.stderr(`${this.#recommendedFailureOf(step, request)}\n`);
128
+ }
129
+ // The hint is conditional wording — the engine parses zero harness output,
130
+ // so it cannot know whether "not installed" caused this failure.
131
+ if (request.shape === "update") {
132
+ this.#io.stderr(`if the package is not installed, run cdd init --harness=${request.host} without --update first\n`);
133
+ }
134
+ return 1;
135
+ }
136
+ /** The green close — the summary line, then the empty-tier info line when the flag
137
+ * was requested and nothing recommended was planned (§5.2 order: summary first). */
138
+ #writeGreenSummary(steps, request) {
139
+ this.#header(this.#summaryOf(steps, request, true));
140
+ for (const line of this.#emptyTierLinesOf(steps, request))
141
+ this.#header(line);
142
+ }
77
143
  /** Render the step plan the run would execute — one `would run: <argv join>` line
78
144
  * per step, then the summary. Zero spawn, zero write: the runner is never
79
145
  * reached on this path (a preview is a rendering, not an execution). */
80
- preview(host, update) {
81
- const steps = this.#stepsOf(host, update);
146
+ preview(request) {
147
+ const steps = this.#stepsOf(request);
82
148
  return [
83
149
  ...steps.map((step) => `would run: ${step.argv.join(" ")}`),
84
- `init: ${steps.length} steps (${host} · ${update ? "update" : "install"}) — dry run, nothing executed`,
150
+ this.#summaryOf(steps, request, false),
151
+ ...this.#emptyTierLinesOf(steps, request),
85
152
  ];
86
153
  }
87
- /** Run the harness's sequence — 0 all green, 1 the first failed step. */
88
- async run(host, update) {
89
- const steps = this.#stepsOf(host, update);
90
- const total = steps.length;
154
+ /** Run one request — 0 all green, 1 the first failed step. */
155
+ async run(request) {
156
+ const steps = this.#stepsOf(request);
91
157
  for (const [index, step] of steps.entries()) {
92
158
  const ordinal = index + 1;
93
- this.#header(`init[${ordinal}/${total}] ${host} · ${step.packageName} · ${step.argv.slice(1).join(" ")}`);
159
+ this.#header(`init[${ordinal}/${steps.length}] ${request.host} · ${step.packageName} · ${step.argv.slice(1).join(" ")}`);
94
160
  const code = await this.#runner.run(step.argv);
95
- if (code !== 0) {
96
- this.#io.stderr(`init[${ordinal}/${total}] · ${step.argv.join(" ")} · exit ${code}\n`);
97
- // The hint is conditional wording — the engine parses zero harness output,
98
- // so it cannot know whether "not installed" caused this failure.
99
- if (update) {
100
- this.#io.stderr(`if the package is not installed, run cdd init --harness=${host} without --update first\n`);
101
- }
102
- return 1;
103
- }
161
+ if (code !== 0)
162
+ return this.#reportFailure(steps, index, code, request);
104
163
  }
105
- this.#header(`init: ${total} steps ok (${host} · ${update ? "update" : "install"})`);
164
+ this.#writeGreenSummary(steps, request);
106
165
  return 0;
107
166
  }
108
167
  }