@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 +2 -1
- package/README.zh-CN.md +2 -1
- package/dist/face/cli.js +58 -13
- package/dist/face/declare.js +23 -5
- package/dist/face/host.js +15 -65
- package/dist/face/init.js +108 -0
- package/dist/face/lifecycle.js +4 -1
- package/dist/face/plugins.js +73 -0
- package/dist/face/projection.js +3 -3
- package/dist/face/termination.js +6 -1
- package/package.json +2 -2
- package/dist/infra/process.js +0 -22
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
|
|
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 /
|
|
4
|
-
// kept as a steady word face; T20 converges the base command face to `base
|
|
5
|
-
// adds the board observability command
|
|
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
|
|
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
|
|
365
|
-
*
|
|
366
|
-
*
|
|
367
|
-
*
|
|
368
|
-
*
|
|
369
|
-
*
|
|
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
|
package/dist/face/declare.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
115
|
-
* commands) plus the pure base / schema / issue artifact commands
|
|
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 /
|
|
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
|
|
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
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
* (face
|
|
36
|
-
|
|
37
|
-
|
|
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
|
|
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",
|
|
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
|
|
188
|
-
* `claude` → `
|
|
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
|
|
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
|
+
}
|
package/dist/face/lifecycle.js
CHANGED
|
@@ -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" | "
|
|
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
|
+
];
|
package/dist/face/projection.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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)
|
package/dist/face/termination.js
CHANGED
|
@@ -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
|
|
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.
|
|
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"
|
package/dist/infra/process.js
DELETED
|
@@ -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
|
-
}
|