@oscaner-skills/cdd-engine 4.0.1 → 4.2.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.
package/README.md CHANGED
@@ -22,7 +22,7 @@ npm install @oscaner-skills/cdd-engine
22
22
 
23
23
  ## CLI
24
24
 
25
- Global option: `--dry-run` — preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix only).
25
+ Global option: `--dry-run` — preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix/init).
26
26
 
27
27
  | Subcommand | Usage | Purpose |
28
28
  |------------|-------|---------|
@@ -33,6 +33,7 @@ Global option: `--dry-run` — preview the next dispatch step and its expected a
33
33
  | `schema` | `cdd schema get <type>` | Print the canonical doc-structure schema (discovery-only, zero enforcement) |
34
34
  | `issue` | `cdd issue render` | Render an aggregate issue body from stdin findings (pure rendering, zero enforcement) |
35
35
  | `board` | `cdd board --plan <path> / --spec <path>` | Render the entry document's progress board (overall/spec/plan/wave/branch; pure read, zero enforcement) |
36
+ | `init` | `cdd init --harness=<claude\|pi> [--update]` | Install or update the kairos plugin set for a harness (repo-independent, streams inherited) |
36
37
 
37
38
  Use `cdd <command> --help` for a command's full option list (for example `cdd review --tasks` / `--spec` / `--plan` / `--round`).
38
39
 
package/README.zh-CN.md CHANGED
@@ -24,7 +24,7 @@ npm install @oscaner-skills/cdd-engine
24
24
 
25
25
  ## CLI
26
26
 
27
- 全局选项:`--dry-run`——预览下一步派发及其预期产物 — 对 repo 零写入、不占轮次(仅限 implement/review/fix)。
27
+ 全局选项:`--dry-run`——预览下一步派发及其预期产物 — 对 repo 零写入、不占轮次(仅限 implement/review/fix/init)。
28
28
 
29
29
  | 子命令 | 用法 | 用途 |
30
30
  |--------|------|------|
@@ -35,6 +35,7 @@ npm install @oscaner-skills/cdd-engine
35
35
  | `schema` | `cdd schema get <type>` | 打印 canonical 文档结构 schema(发现型、零执法) |
36
36
  | `issue` | `cdd issue render` | 依据 stdin 发现渲染聚合 issue 正文(纯渲染、零执法) |
37
37
  | `board` | `cdd board --plan <path> / --spec <path>` | 渲染入口文档的进度板(overall/spec/plan/wave/branch;纯读、零执法) |
38
+ | `init` | `cdd init --harness=<claude\|pi> [--update]` | 为指定 harness 安装或更新 kairos 插件集(与 repo 无关,三流继承) |
38
39
 
39
40
  用 `cdd <command> --help` 查看某命令的完整选项列表(例如 `cdd review --tasks` / `--spec` / `--plan` / `--round`)。
40
41
 
package/dist/face/cli.js CHANGED
@@ -1,14 +1,15 @@
1
1
  // packages/cdd-engine/src-next/face/cli.ts
2
2
  // T11 + T8 — the command face + composition root (design spec §3.3: the cdd CLI
3
- // command surface — implement / review / fix / schema / issue / base / board — is
4
- // kept as a steady word face; T20 converges the base command face to `base` and T5
5
- // adds the board observability command — the seven-command surface). This module is
3
+ // command surface — implement / review / fix / base / schema / issue / board / init —
4
+ // is kept as a steady word face; T20 converges the base command face to `base`, T5
5
+ // adds the board observability command and P20 adds the repo-independent init
6
+ // bootstrap — the eight-command surface). This module is
6
7
  // the new tree's composition root: the
7
8
  // `Cli.create` static factory — the class face is the entry, the module carries zero
8
9
  // bare functions (the composition root's deliberate class form) — wires the contract /
9
10
  // session / face objects into the ONE CLI the bin thin entry boots. Task 3 (P1)
10
11
  // reorganized the face into one boundary per responsibility — the CLI declaration
11
- // single surface (face/declare.ts, §2.4 — the seven subcommand rows + the argv
12
+ // single surface (face/declare.ts, §2.4 — the eight subcommand rows + the argv
12
13
  // channel), the declaration projection (face/projection.ts — the CommandTreeBuilder
13
14
  // whose commander program OWNS the parse + help + validation pipeline), and the run
14
15
  // face; the typed argv parse channel (face/argv.ts) was deleted at T6 — the parse
@@ -41,7 +42,7 @@
41
42
  // delegate to the split faces above — the root orchestrates, never re-types).
42
43
  // Module-level exports are types / constant data / classes — zero behavior-carrying
43
44
  // bare functions (the composition root is the Cli class's static create factory).
44
- import { existsSync, readFileSync } from "node:fs";
45
+ import { existsSync, readFileSync, writeSync } from "node:fs";
45
46
  import path from "node:path";
46
47
  import process from "node:process";
47
48
  import { CommanderError } from "commander";
@@ -71,7 +72,8 @@ import { Capsule } from "./capsule.js";
71
72
  import { ARGV_CHANNEL } from "./declare.js";
72
73
  import { CliGate } from "./gate.js";
73
74
  import { GraphView } from "./graph-view.js";
74
- import { HostDetect } from "./host.js";
75
+ import { HOST_IDS, HostDetect } from "./host.js";
76
+ import { CliInit, ExecaStepRunner } from "./init.js";
75
77
  import { CliLifecycle } from "./lifecycle.js";
76
78
  import { Preview } from "./preview.js";
77
79
  import { CommandTreeBuilder } from "./projection.js";
@@ -123,6 +125,13 @@ export class Cli {
123
125
  /** The pure-command domain (T8 — the split contract's artifacts face,
124
126
  * face/artifacts.ts): the schema/issue/base run bodies. */
125
127
  #artifacts;
128
+ /** The harness plugin bootstrap (P20 — face/init.ts): the repo-independent
129
+ * install/update sequence face. */
130
+ #init;
131
+ /** The bootstrap's synchronous line writer — the step headers of a real run and
132
+ * the `would run:` lines of a `--dry-run` preview ride the SAME seam (one writer,
133
+ * so a preview and a run never format the same plan differently). */
134
+ #initHeader;
126
135
  constructor(opts = {}) {
127
136
  this.#io = opts.io ?? {
128
137
  stdout: (t) => process.stdout.write(t),
@@ -160,6 +169,14 @@ export class Cli {
160
169
  stdinRead: this.#stdinRead,
161
170
  usage: (node, message) => this.#usage(node, message),
162
171
  });
172
+ // The synchronous writer — the step header must land before the spawned
173
+ // child writes to the same fd (a piped log would otherwise reorder them).
174
+ this.#initHeader = opts.initHeader ?? ((line) => writeSync(1, `${line}\n`));
175
+ this.#init = new CliInit({
176
+ io: this.#io,
177
+ runner: opts.initRunner ?? new ExecaStepRunner(),
178
+ header: this.#initHeader,
179
+ });
163
180
  }
164
181
  // ---------------------------------------------------------------------------
165
182
  // the commander parse pipeline — the composition root parses through the
@@ -257,6 +274,27 @@ export class Cli {
257
274
  commandNode("board").action(async (_opts, command) => {
258
275
  this.#exitCode = await this.#runBoard(command, this.#runInput(null, command));
259
276
  });
277
+ // the repo-independent bootstrap — zero #rootOf(), zero workspace writes. The
278
+ // preview flag renders the step plan through the same header seam and returns
279
+ // before the first spawn (spec §2.7): a preview must never install packages.
280
+ commandNode("init").action(async (_opts, command) => {
281
+ const dryRun = this.#dryRunOf(command);
282
+ const parsed = this.#runInput(null, command);
283
+ // The declaration marks --harness as requiredOption, so commander rejects a
284
+ // missing flag before this shell; the guard keeps the run input's narrowed
285
+ // type honest (the usage face belongs to the root's private surface, so it
286
+ // stays here rather than sinking into CliInit).
287
+ if (parsed.harness === undefined)
288
+ this.#usage(command, "cdd init: missing --harness");
289
+ const update = parsed.update ?? false;
290
+ if (dryRun) {
291
+ for (const line of this.#init.preview(parsed.harness, update))
292
+ this.#initHeader(line);
293
+ this.#exitCode = 0;
294
+ return;
295
+ }
296
+ this.#exitCode = await this.#init.run(parsed.harness, update);
297
+ });
260
298
  }
261
299
  /** `cdd board --plan <path> / --spec <path>` — the entry document's progress board
262
300
  * (spec §3.1): a PURE READ — zero preflight gate, zero tree writes, zero ledger
@@ -343,6 +381,7 @@ export class Cli {
343
381
  continue;
344
382
  args[key] = typeof value === "boolean" ? (value ? "true" : "false") : String(value);
345
383
  }
384
+ const harnessToken = typeof globals.harness === "string" ? globals.harness : "";
346
385
  return {
347
386
  leaf,
348
387
  args,
@@ -351,6 +390,11 @@ export class Cli {
351
390
  paths: { plan: null, spec: null, reviews: null },
352
391
  positionals: command.processedArgs,
353
392
  dryRun: this.#dryRunOf(command),
393
+ // The harness word is narrowed through the ONE host vocabulary (a cast would
394
+ // let a foreign token ride into the roster index); `--update` is the parsed
395
+ // boolean, never a truthy string.
396
+ harness: HOST_IDS.find((id) => id === harnessToken),
397
+ update: globals.update === true,
354
398
  };
355
399
  }
356
400
  /** The invocation's `--dry-run` scope — the constructor flag OR the program-scope
@@ -361,16 +405,17 @@ export class Cli {
361
405
  const globals = command.optsWithGlobals();
362
406
  return this.#dryRun || globals.dryRun === true;
363
407
  }
364
- /** The `--dry-run` scope guard (P11 T5 · §3.5) — the preview semantics belong to
365
- * the three work verbs alone. A pure command carrying the program flag is a usage
366
- * rejection (exit 2), never a silently ignored flag: a no-op flag the consumer has
367
- * to remember to skip is a mind-share defect, not a convenience. The usage byte is
368
- * the owning node's commander-native usage line (the same `#usage` face every run
369
- * body's rejection rides). */
408
+ /** The `--dry-run` scope guard (P11 T5 · §3.5) — the pure commands' rejection face
409
+ * alone: a pure command carrying the program flag is a usage rejection (exit 2),
410
+ * never a silently ignored flag — a no-op flag the consumer has to remember to
411
+ * skip is a mind-share defect, not a convenience. The four preview-capable faces
412
+ * (implement / review / fix / init) never reach this guard; `init`'s preview is
413
+ * `CliInit.preview`. The usage byte is the owning node's commander-native usage
414
+ * line (the same `#usage` face every run body's rejection rides). */
370
415
  #assertDryRunScope(node, dryRun) {
371
416
  if (!dryRun)
372
417
  return;
373
- this.#usage(node, "--dry-run previews the next dispatch step and its expected artifacts — it applies to implement / review / fix only");
418
+ this.#usage(node, "--dry-run previews the next dispatch step and its expected artifacts — it applies to implement / review / fix / init only");
374
419
  }
375
420
  /** Configure every node's output into the injected io (commander writes its
376
421
  * help/error bytes through the node that produced them — a subcommand's help
@@ -1,5 +1,5 @@
1
1
  // packages/cdd-engine/src-next/face/declare.ts
2
- // §2.4 — the CLI declaration single surface: the argv channel table, the seven-command
2
+ // §2.4 — the CLI declaration single surface: the argv channel table, the eight-command
3
3
  // declarations, every CLI face type and the conditional-required group table cohere
4
4
  // in ONE file (the user ruling 2026-10-11: the declaration was scattered across
5
5
  // runtime/registry/argv → one surface). The migration converges:
@@ -21,6 +21,7 @@
21
21
  // algorithm lives in the single CommandTreeBuilder class (face/projection.ts).
22
22
  import { InvalidArgumentError } from "commander";
23
23
  import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
24
+ import { HOST_IDS } from "./host.js";
24
25
  /** The argv channel table — the CLI flag/type/enum single source (the engine-config
25
26
  * argv channel verbatim: flag spellings, value types and enum domains ride these
26
27
  * rows, and the command declarations + the channel audit read them from here). The
@@ -54,11 +55,22 @@ export const ARGV_CHANNEL = {
54
55
  help: "the base artifact's source channel",
55
56
  },
56
57
  force: { flag: "--force", type: "bool", help: "override the existing base artifact" },
58
+ harness: {
59
+ flag: "--harness",
60
+ type: "enum",
61
+ values: HOST_IDS,
62
+ help: "the harness whose plugin set is installed or updated",
63
+ },
64
+ update: {
65
+ flag: "--update",
66
+ type: "bool",
67
+ help: "update the installed plugin set instead of installing it",
68
+ },
57
69
  dryRun: {
58
70
  flag: "--dry-run",
59
71
  type: "bool",
60
72
  scope: "program",
61
- help: "preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix only)",
73
+ help: "preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix/init)",
62
74
  },
63
75
  help: {
64
76
  flag: "--help",
@@ -111,9 +123,9 @@ export const VALUE_SHAPES = {
111
123
  },
112
124
  },
113
125
  };
114
- /** The seven subcommand declarations — implement, review, fix (the lifecycle work
115
- * commands) plus the pure base / schema / issue artifact commands and the board
116
- * observability command. */
126
+ /** The eight subcommand declarations — implement, review, fix (the lifecycle work
127
+ * commands) plus the pure base / schema / issue artifact commands, the board
128
+ * observability command and the repo-independent init bootstrap. */
117
129
  export const CLI_COMMANDS = [
118
130
  {
119
131
  name: "implement",
@@ -204,6 +216,12 @@ export const CLI_COMMANDS = [
204
216
  example: `cdd board --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
205
217
  keys: [{ key: "plan" }, { key: "spec" }],
206
218
  },
219
+ {
220
+ name: "init",
221
+ description: "install or update the kairos plugin set for a harness",
222
+ example: "cdd init --harness=claude",
223
+ keys: [{ key: "harness", required: true }, { key: "update" }],
224
+ },
207
225
  ];
208
226
  /** The schema `<type>` vocabulary — the get leaf's ONE table (spec §5.3): the
209
227
  * primary DocKey spellings (overall | plan | phase-spec | single-spec) plus
package/dist/face/host.js CHANGED
@@ -5,7 +5,7 @@
5
5
  // imported, never parsed:
6
6
  //
7
7
  // · HOSTS — the per-harness rows (cli / invoke / promptForm / output / ship /
8
- // detect / install). The host-marker closure is single-sourced HERE: the
8
+ // detect / env). The host-marker closure is single-sourced HERE: the
9
9
  // detect rows are the only copy of the marker env keys (the channel audit derives
10
10
  // the env whitelist from them — never a second declaration). The promptForm
11
11
  // column (§3.5) is the prompt-position semantics data contract — how the
@@ -14,7 +14,7 @@
14
14
  // to. M1 supersede (P5): the implement slot names the upstream
15
15
  // `mattpocock-skills:implement` skill; the fix face carries no skill ref (its
16
16
  // fix discipline lives as the FIX_SHELL typed instructions).
17
- // · REFS — the per-harness slash reference forms (claude/cursor use the
17
+ // · REFS — the per-harness slash reference forms (claude uses the
18
18
  // `/namespace:skill` form; pi the flat `/skill:<bare>` form — the pi flat
19
19
  // namespace has no namespace-qualification syntax).
20
20
  // · HostDetect — the module-level host judgment (the detection's single home):
@@ -29,31 +29,12 @@
29
29
  //
30
30
  // Module-level exports are types / the declared constant data — zero behavior-
31
31
  // carrying bare functions (the plan's zero-bare-function discipline).
32
- /** The per-harness install banners — the kairos self-install + the upstream plugin
33
- * install commands. The `packages/kairos/README.md` upstream dependency table (and
34
- * its zh mirror) renders from these rows; the engine-suite gate
35
- * (face/__tests__/install-rows.guard.test.ts) pins each README row's Claude Code cell
36
- * to `INSTALL_ROWS[key].join(";")` and the row key set to these keys — a README
37
- * install-command drift fails there, never silently. */
38
- export const INSTALL_ROWS = {
39
- kairos: [
40
- "claude plugin marketplace add oscaner/skills",
41
- "claude plugin install kairos@oscaner-skills",
42
- ],
43
- superpowers: [
44
- "claude plugin marketplace add obra/superpowers-marketplace",
45
- "claude plugin install superpowers@superpowers-marketplace",
46
- ],
47
- "mattpocock-skills": [
48
- "claude plugin marketplace add mattpocock/skills",
49
- "claude plugin install mattpocock-skills@mattpocock",
50
- ],
51
- impeccable: [
52
- "claude plugin marketplace add pbakaus/impeccable",
53
- "claude plugin install impeccable@impeccable",
54
- ],
55
- };
56
- /** The per-harness host rows — claude / cursor / pi adaptation facts. */
32
+ /** The harness ids the contract adapts — the runtime companion of `HostId` and the
33
+ * single source of the host vocabulary: `HostId` derives from it, the `HOSTS` key
34
+ * set closes over it, and the `--harness` value range plus the detect walk read it
35
+ * (the production face carries no second copy of the host literal list). */
36
+ export const HOST_IDS = ["claude", "pi"];
37
+ /** The per-harness host rows — claude / pi adaptation facts. */
57
38
  export const HOSTS = {
58
39
  claude: {
59
40
  promptForm: "ref-prefixed",
@@ -62,23 +43,8 @@ export const HOSTS = {
62
43
  output: "text",
63
44
  ship: "full",
64
45
  detect: { env: "CLAUDE_CODE_SESSION_ID", aiAgentPrefix: "claude-code" },
65
- install: INSTALL_ROWS,
66
46
  capabilities: { parallel: true },
67
- },
68
- cursor: {
69
- promptForm: "ref-prefixed",
70
- cli: "cursor-agent",
71
- invoke: "--print --output-format text --force",
72
- output: "text",
73
- ship: "full",
74
- detect: { env: "CURSOR_TRACE_ID" },
75
- install: {
76
- kairos: "pending",
77
- superpowers: "pending",
78
- "mattpocock-skills": "pending",
79
- impeccable: "pending",
80
- },
81
- capabilities: { parallel: "pending" },
47
+ env: { FORCE_PROMPT_CACHING_5M: "1" },
82
48
  },
83
49
  pi: {
84
50
  promptForm: "ref-prefixed",
@@ -87,13 +53,8 @@ export const HOSTS = {
87
53
  output: "text",
88
54
  ship: "full",
89
55
  detect: { env: "AI_AGENT", value: "pi" },
90
- install: {
91
- kairos: ["pi install npm:@oscaner-skills/kairos"],
92
- superpowers: ["pi install git:github.com/obra/superpowers"],
93
- "mattpocock-skills": ["pi install git:github.com/mattpocock/skills"],
94
- impeccable: ["npx impeccable install --providers=pi --scope=global -y"],
95
- },
96
56
  capabilities: { parallel: "pending" },
57
+ env: { PI_CACHE_RETENTION: "short" },
97
58
  },
98
59
  };
99
60
  /** The dispatch table — the phase/type → skill-ref resolution. The implement slot
@@ -111,64 +72,53 @@ export const DISPATCH = {
111
72
  },
112
73
  };
113
74
  /** The reference table — every `<pkg>:<skill>` cross-skill reference key and its
114
- * per-harness slash form: claude/cursor use `/namespace:skill`, pi the flat
75
+ * per-harness slash form: claude uses `/namespace:skill`, pi the flat
115
76
  * `/skill:<bare>` form. The `mattpocock-skills:implement` key is registered here
116
77
  * (P5 — the implement dispatch's first-class refs-domain entry). */
117
78
  export const REFS = {
118
79
  "superpowers:brainstorming": {
119
80
  claude: "/superpowers:brainstorming",
120
- cursor: "/superpowers:brainstorming",
121
81
  pi: "/skill:brainstorming",
122
82
  },
123
83
  "superpowers:writing-plans": {
124
84
  claude: "/superpowers:writing-plans",
125
- cursor: "/superpowers:writing-plans",
126
85
  pi: "/skill:writing-plans",
127
86
  },
128
87
  "superpowers:finishing-a-development-branch": {
129
88
  claude: "/superpowers:finishing-a-development-branch",
130
- cursor: "/superpowers:finishing-a-development-branch",
131
89
  pi: "/skill:finishing-a-development-branch",
132
90
  },
133
91
  "mattpocock-skills:implement": {
134
92
  claude: "/mattpocock-skills:implement",
135
- cursor: "/mattpocock-skills:implement",
136
93
  pi: "/skill:implement",
137
94
  },
138
95
  "mattpocock-skills:code-review": {
139
96
  claude: "/mattpocock-skills:code-review",
140
- cursor: "/mattpocock-skills:code-review",
141
97
  pi: "/skill:code-review",
142
98
  },
143
99
  "mattpocock-skills:grilling": {
144
100
  claude: "/mattpocock-skills:grilling",
145
- cursor: "/mattpocock-skills:grilling",
146
101
  pi: "/skill:grilling",
147
102
  },
148
103
  "kairos:cdd-design": {
149
104
  claude: "/kairos:cdd-design",
150
- cursor: "/kairos:cdd-design",
151
105
  pi: "/skill:cdd-design",
152
106
  },
153
107
  "kairos:cdd-spec-writer": {
154
108
  claude: "/kairos:cdd-spec-writer",
155
- cursor: "/kairos:cdd-spec-writer",
156
109
  pi: "/skill:cdd-spec-writer",
157
110
  },
158
111
  "kairos:cdd-plan": {
159
112
  claude: "/kairos:cdd-plan",
160
- cursor: "/kairos:cdd-plan",
161
113
  pi: "/skill:cdd-plan",
162
114
  },
163
- "kairos:cdd-dev": { claude: "/kairos:cdd-dev", cursor: "/kairos:cdd-dev", pi: "/skill:cdd-dev" },
115
+ "kairos:cdd-dev": { claude: "/kairos:cdd-dev", pi: "/skill:cdd-dev" },
164
116
  "kairos:cdd-close": {
165
117
  claude: "/kairos:cdd-close",
166
- cursor: "/kairos:cdd-close",
167
118
  pi: "/skill:cdd-close",
168
119
  },
169
120
  "kairos:cdd-report": {
170
121
  claude: "/kairos:cdd-report",
171
- cursor: "/kairos:cdd-report",
172
122
  pi: "/skill:cdd-report",
173
123
  },
174
124
  };
@@ -184,13 +134,13 @@ export const HOST_CONTRACT = {
184
134
  * must stay import-clean toward the dispatch face). */
185
135
  // biome-ignore lint/complexity/noStaticOnlyClass: the module-level host-detect surface — the zero-bare-function discipline admits no standalone predicate functions.
186
136
  export class HostDetect {
187
- /** detect(env) — the first host detect row that matches, in the pinned order
188
- * `claude` → `cursor` → `pi` (specific markers first, the generic AI_AGENT
137
+ /** detect(env) — the first host detect row that matches, in the pinned `HOST_IDS`
138
+ * order `claude` → `pi` (specific markers first, the generic AI_AGENT
189
139
  * last). One row detects by its primary marker (a session env, presence/enum —
190
140
  * a UUID CLAUDE_CODE_SESSION_ID is claude by presence) or by the AI_AGENT
191
141
  * prefix (AI_AGENT=claude-code-…); no match returns `""`. */
192
142
  static detect(env) {
193
- for (const id of ["claude", "cursor", "pi"]) {
143
+ for (const id of HOST_IDS) {
194
144
  const detect = HOSTS[id].detect;
195
145
  if (detect.env !== undefined && detect.env !== "") {
196
146
  const marker = env[detect.env];
@@ -0,0 +1,108 @@
1
+ // packages/cdd-engine/src-next/face/init.ts
2
+ // P20 — the harness plugin bootstrap (`cdd init`): the eighth top-level verb, a
3
+ // repo-independent face that spawns the harness's own install / update sequence.
4
+ //
5
+ // The data plane is the roster (`face/plugins.ts`): one row per package, one column
6
+ // per harness id, two command shapes per column. This module declares zero command
7
+ // bytes — it flattens the requested column in roster order and runs it serially.
8
+ //
9
+ // · StepRunner — the narrow execution seam: one structured argv in, the child's
10
+ // own exit code out (fail-open — a spawn failure is a code, never a throw).
11
+ // · ExecaStepRunner — the production runner: `stdio: "inherit"` on all three
12
+ // standard streams, so the child holds the real terminal (the harness's
13
+ // interactive prompts and TTY judgment see what the human sees) and the
14
+ // consumer watches the harness output live. A missing / non-executable binary
15
+ // rides `SPAWN_FAILURE_CODE` (the shell's command-not-found convention) into
16
+ // the same failure face — zero special-case probing.
17
+ // · CliInit — the face class: per-step header before the spawn (the header seam
18
+ // is the composition root's synchronous writer, so a piped log cannot reorder
19
+ // the header behind the child's own output), first non-zero exit stops the
20
+ // sequence, and a green run closes with one summary line. Its `--dry-run`
21
+ // preview renders the same flattened plan as `would run:` lines and touches no
22
+ // step runner at all — the flatten is single-source, the only branch is whether
23
+ // a step is spawned.
24
+ //
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,
27
+ // no ceiling and no session state.
28
+ //
29
+ // Module-level exports are types / declared constants / classes — zero
30
+ // behavior-carrying bare functions (the zero-bare-function discipline).
31
+ import { execa } from "execa";
32
+ import { PLUGINS } from "./plugins.js";
33
+ /** The one stdio face of an install step — all three standard streams inherited
34
+ * from the parent process. */
35
+ export const STDIO = "inherit";
36
+ /** The spawn-failure code — the shell's command-not-found convention; a missing
37
+ * harness binary (or any non-executable argv[0]) reports this code through the
38
+ * ordinary failure face. */
39
+ export const SPAWN_FAILURE_CODE = 127;
40
+ /** The production step runner — execa's asynchronous face over the inherited
41
+ * standard streams. */
42
+ export class ExecaStepRunner {
43
+ async run(argv) {
44
+ const [binary = "", ...args] = argv;
45
+ const result = await execa(binary, args, { stdio: STDIO, reject: false });
46
+ // Zero exit codes only exist for a spawned child — an undefined code is the
47
+ // spawn-failure face (ENOENT / EACCES), never a success.
48
+ return result.exitCode ?? SPAWN_FAILURE_CODE;
49
+ }
50
+ }
51
+ /**
52
+ * CliInit — the `cdd init --harness=<id> [--update]` run face. Repo-independent:
53
+ * zero workspace writes, zero ledger, zero document reads — the harness's own
54
+ * command sequence is the only side effect.
55
+ */
56
+ export class CliInit {
57
+ #io;
58
+ #runner;
59
+ #header;
60
+ constructor(opts) {
61
+ this.#io = opts.io;
62
+ this.#runner = opts.runner;
63
+ this.#header = opts.header;
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) {
69
+ const steps = [];
70
+ for (const row of PLUGINS) {
71
+ for (const argv of update ? row[host].update : row[host].install) {
72
+ steps.push({ packageName: row.name, argv });
73
+ }
74
+ }
75
+ return steps;
76
+ }
77
+ /** Render the step plan the run would execute — one `would run: <argv join>` line
78
+ * per step, then the summary. Zero spawn, zero write: the runner is never
79
+ * reached on this path (a preview is a rendering, not an execution). */
80
+ preview(host, update) {
81
+ const steps = this.#stepsOf(host, update);
82
+ return [
83
+ ...steps.map((step) => `would run: ${step.argv.join(" ")}`),
84
+ `init: ${steps.length} steps (${host} · ${update ? "update" : "install"}) — dry run, nothing executed`,
85
+ ];
86
+ }
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;
91
+ for (const [index, step] of steps.entries()) {
92
+ const ordinal = index + 1;
93
+ this.#header(`init[${ordinal}/${total}] ${host} · ${step.packageName} · ${step.argv.slice(1).join(" ")}`);
94
+ 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
+ }
104
+ }
105
+ this.#header(`init: ${total} steps ok (${host} · ${update ? "update" : "install"})`);
106
+ return 0;
107
+ }
108
+ }
@@ -71,7 +71,7 @@ export class CliLifecycle {
71
71
  };
72
72
  this.#reviews = opts.reviews ?? null;
73
73
  }
74
- /** The host-harness id detected from the env — "claude" | "cursor" | "pi" | "" —
74
+ /** The host-harness id detected from the env — "claude" | "pi" | "" —
75
75
  * a delegation to the module-level judgment (HostDetect.detect, face/host.ts —
76
76
  * the detection's single home; this instance method is the injectable-env
77
77
  * adapter the lifecycle face rides, behavior unchanged). */
@@ -112,6 +112,9 @@ export class CliLifecycle {
112
112
  cwd: this.#scene.workspace.root.repoRoot,
113
113
  heartbeatPath: this.#scene.workspace.resolve("liveness.json"),
114
114
  policy: TerminationPolicy.of(frame.phase),
115
+ // The host row's own child env — the TTL pin the terminator layers over the
116
+ // inherited env at spawn (the host difference is data, never a dispatcher branch).
117
+ env: row.env,
115
118
  });
116
119
  // The child's stdout rides the diagnostic channel — #reject reads it into the
117
120
  // crash record on either failure face. Child Return is prose: the engine never
@@ -0,0 +1,73 @@
1
+ // packages/cdd-engine/src-next/face/plugins.ts
2
+ // The plugin roster — the package-axis single table of "what gets installed into a
3
+ // harness". One row per package, one column per harness id, two command shapes per
4
+ // column (install / update). Everything the install face runs, and everything the
5
+ // consumer README table renders, is this data: the README is a rendering surface
6
+ // plus a gate, never a second source.
7
+ //
8
+ // Row order is a first-class fact — the array order IS the execution order and the
9
+ // README row order (upstream dependencies first, kairos last). Object key order
10
+ // would not carry that promise, so the roster is an array of rows, not an object.
11
+ //
12
+ // The host vocabulary stays single-sourced in `face/host.ts`: this module declares
13
+ // no host id list — the row's column set closes over `HostId` (a missing column, or
14
+ // a new host without its column, is a type error), and the `claude` / `pi` tokens
15
+ // inside the argv tuples are the command literals themselves (the README table
16
+ // hands them to humans to copy verbatim), not a vocabulary copy.
17
+ //
18
+ // Module-level exports are types and declared constant data — zero behavior-carrying
19
+ // bare functions (the zero-bare-function discipline).
20
+ /** The plugin roster — row order is execution order (upstream first, kairos last). */
21
+ export const PLUGINS = [
22
+ {
23
+ name: "superpowers",
24
+ claude: {
25
+ install: [
26
+ ["claude", "plugin", "marketplace", "add", "obra/superpowers-marketplace"],
27
+ ["claude", "plugin", "install", "superpowers@superpowers-marketplace"],
28
+ ],
29
+ update: [
30
+ ["claude", "plugin", "marketplace", "update", "superpowers-marketplace"],
31
+ ["claude", "plugin", "update", "superpowers@superpowers-marketplace"],
32
+ ],
33
+ },
34
+ pi: {
35
+ install: [["pi", "install", "git:github.com/obra/superpowers"]],
36
+ update: [["pi", "update", "git:github.com/obra/superpowers"]],
37
+ },
38
+ },
39
+ {
40
+ name: "mattpocock-skills",
41
+ claude: {
42
+ install: [
43
+ ["claude", "plugin", "marketplace", "add", "mattpocock/skills"],
44
+ ["claude", "plugin", "install", "mattpocock-skills@mattpocock"],
45
+ ],
46
+ update: [
47
+ ["claude", "plugin", "marketplace", "update", "mattpocock"],
48
+ ["claude", "plugin", "update", "mattpocock-skills@mattpocock"],
49
+ ],
50
+ },
51
+ pi: {
52
+ install: [["pi", "install", "git:github.com/mattpocock/skills"]],
53
+ update: [["pi", "update", "git:github.com/mattpocock/skills"]],
54
+ },
55
+ },
56
+ {
57
+ name: "kairos",
58
+ claude: {
59
+ install: [
60
+ ["claude", "plugin", "marketplace", "add", "oscaner/skills"],
61
+ ["claude", "plugin", "install", "kairos@oscaner-skills"],
62
+ ],
63
+ update: [
64
+ ["claude", "plugin", "marketplace", "update", "oscaner-skills"],
65
+ ["claude", "plugin", "update", "kairos@oscaner-skills"],
66
+ ],
67
+ },
68
+ pi: {
69
+ install: [["pi", "install", "npm:@oscaner-skills/kairos"]],
70
+ update: [["pi", "update", "npm:@oscaner-skills/kairos"]],
71
+ },
72
+ },
73
+ ];
@@ -1,9 +1,9 @@
1
1
  // packages/cdd-engine/src-next/face/projection.ts
2
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
3
+ // — the argv channel + the eight-command rows + REQUIRED_GROUPS) assembles the
4
4
  // commander command tree, ENTIRELY in the constructor (the constructor-is-the-
5
5
  // assembly stance · §2.1/§2.3):
6
- // the top-level `cdd` program · the seven commands with their descriptions · the
6
+ // the top-level `cdd` program · the eight commands with their descriptions · the
7
7
  // nested leaves (base set|get · schema get|gen · issue render) · the binding rules
8
8
  // (command keys → .option()/.requiredOption() · positionals → .argument() ·
9
9
  // bool rows single-spelling · the program scope merged into every node · the help
@@ -55,7 +55,7 @@ export class CommandTreeBuilder {
55
55
  // same thrown errors.
56
56
  this.program.exitOverride();
57
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)");
58
+ this.program.addHelpText("afterAll", "program flags (accepted at any position): --dry-run (implement/review/fix/init)");
59
59
  this.#bindProgramScopes(this.program);
60
60
  this.#injectProgramExamples();
61
61
  for (const spec of CLI_COMMANDS)
@@ -8,7 +8,8 @@
8
8
  // The seam's two ends are value objects, so the whole child lifecycle speaks one
9
9
  // shape:
10
10
  // · `ChildRun` — one dispatch's full context (command/args/cwd + the heartbeat
11
- // path the sampler writes + the termination policy of the phase);
11
+ // path the sampler writes + the termination policy of the phase + the per-host
12
+ // dispatch env);
12
13
  // · `ChildOutcome` — the child's result (its own exit code, verbatim streams)
13
14
  // plus the `termination` fact: non-null ⟺ the round was cut short. The
14
15
  // terminated round's downstream judgments all read that one fact, never the
@@ -392,6 +393,10 @@ export class Terminator {
392
393
  cwd: run.cwd,
393
394
  reject: false,
394
395
  stripFinalNewline: false,
396
+ // The dispatch env is layered over the inherited one — the engine's per-host
397
+ // values win, the parent environment supplies the rest (the single merge point;
398
+ // the dispatcher carries zero host branches).
399
+ env: { ...process.env, ...run.env },
395
400
  // fd 0 on /dev/null: a child that reads stdin sees EOF at once, never a pipe nobody closes.
396
401
  stdin: "ignore",
397
402
  killDescendants: true,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.0.1",
3
+ "version": "4.2.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -20,7 +20,7 @@
20
20
  },
21
21
  "dependencies": {
22
22
  "commander": "^15.0.0",
23
- "execa": "^10.1.1",
23
+ "execa": "^10.2.0",
24
24
  "jsonc-parser": "^3.3.1",
25
25
  "simple-git": "^4.0.2",
26
26
  "yaml": "^2.9.1"
@@ -1,22 +0,0 @@
1
- // packages/cdd-engine/src-next/infra/process.ts
2
- // T12 — ProcessRunner: the new tree's process seam. Subprocess invocations are
3
- // async instance methods over the node:child_process execFile — a fail-open run
4
- // returns a { code, stdout, stderr } result (a missing binary or a non-zero exit
5
- // rides the code, never a thrown exception across the seam).
6
- import { execFile } from "node:child_process";
7
- /** ProcessRunner — the subprocess adapter. Stateless and fail-open. */
8
- export class ProcessRunner {
9
- /** Run a command with args in an optional working directory. */
10
- run(command, args, cwd) {
11
- return new Promise((resolve) => {
12
- execFile(command, [...args], { cwd }, (error, stdout, stderr) => {
13
- if (error === null) {
14
- resolve({ code: 0, stdout, stderr });
15
- return;
16
- }
17
- const code = typeof error.code === "number" ? error.code : 1;
18
- resolve({ code, stdout, stderr });
19
- });
20
- });
21
- }
22
- }