@oscaner-skills/cdd-engine 4.1.0 → 4.3.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 +39 -9
- package/README.zh-CN.md +44 -9
- package/dist/contract/completion-criterion.js +351 -0
- package/dist/contract/declare.js +181 -43
- package/dist/contract/doc.js +84 -271
- package/dist/contract/frontmatter.js +2 -1
- package/dist/contract/home-extractors.js +49 -316
- package/dist/contract/invariants.js +400 -296
- package/dist/contract/judge.js +74 -49
- package/dist/contract/lint.js +3 -2
- package/dist/contract/liveness-signal.js +103 -0
- package/dist/contract/markdown-document.js +410 -0
- package/dist/contract/markdown-tree-types.js +6 -0
- package/dist/contract/markdown-tree.js +137 -0
- package/dist/contract/project.js +1 -1
- package/dist/contract/rules.js +106 -0
- package/dist/contract/selector-engine.js +332 -0
- package/dist/contract/selector-spec.js +74 -0
- package/dist/contract/skill-anatomy.js +29 -1
- package/dist/contract/task-block-grammar.js +285 -0
- package/dist/contract/task-blocks.js +65 -0
- package/dist/contract/translate.js +21 -0
- package/dist/contract/wave-width.js +15 -0
- package/dist/face/board-view.js +401 -131
- package/dist/face/capsule.js +66 -89
- package/dist/face/cli.js +174 -48
- package/dist/face/declare.js +59 -23
- package/dist/face/gate.js +117 -40
- package/dist/face/host.js +9 -35
- package/dist/face/init.js +108 -0
- package/dist/face/lifecycle.js +540 -123
- package/dist/face/plugins.js +73 -0
- package/dist/face/preview.js +43 -10
- package/dist/face/projection.js +3 -3
- package/dist/face/route-render.js +51 -21
- package/dist/face/termination.js +135 -261
- package/dist/face/words.js +134 -12
- package/dist/infra/atomic.js +15 -0
- package/dist/infra/git.js +25 -0
- package/dist/infra/proc.js +150 -0
- package/dist/infra/round-log.js +104 -0
- package/dist/infra/runtime.js +16 -4
- package/dist/infra/workspace.js +7 -2
- package/dist/render/brief.js +15 -17
- package/dist/render/skeleton.js +41 -28
- package/dist/render/templates.js +128 -84
- package/dist/session/faces.js +47 -20
- package/dist/session/graph.js +13 -37
- package/dist/session/handoff-schema.js +16 -8
- package/dist/session/inflight.js +282 -0
- package/dist/session/ledger.js +581 -136
- package/dist/session/line-identity.js +33 -0
- package/dist/session/next.js +138 -80
- package/dist/session/preflight.js +276 -68
- package/dist/session/round-naming.js +56 -8
- package/dist/session/run.js +317 -78
- package/dist/session/wave.js +94 -14
- package/package.json +13 -3
- package/dist/infra/process.js +0 -22
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:
|
|
@@ -20,7 +20,9 @@
|
|
|
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";
|
|
25
|
+
import { HOST_IDS } from "./host.js";
|
|
24
26
|
/** The argv channel table — the CLI flag/type/enum single source (the engine-config
|
|
25
27
|
* argv channel verbatim: flag spellings, value types and enum domains ride these
|
|
26
28
|
* rows, and the command declarations + the channel audit read them from here). The
|
|
@@ -28,7 +30,11 @@ import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
|
|
|
28
30
|
* text per key, shared by every command that declares it). */
|
|
29
31
|
export const ARGV_CHANNEL = {
|
|
30
32
|
plan: { flag: "--plan", type: "path", help: "the CDD plan document path" },
|
|
31
|
-
spec: {
|
|
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
|
+
},
|
|
32
38
|
reviews: {
|
|
33
39
|
flag: "--reviews",
|
|
34
40
|
type: "path",
|
|
@@ -37,12 +43,12 @@ export const ARGV_CHANNEL = {
|
|
|
37
43
|
tasks: {
|
|
38
44
|
flag: "--tasks",
|
|
39
45
|
type: "int-list",
|
|
40
|
-
help:
|
|
46
|
+
help: `the task ids of the wave group (comma-separated) — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
|
|
41
47
|
},
|
|
42
48
|
type: {
|
|
43
49
|
flag: "--type",
|
|
44
50
|
type: "enum",
|
|
45
|
-
values: ["wave", "branch", "spec", "plan"],
|
|
51
|
+
values: ["wave", "branch", "phase-spec", "overall", "plan", "single-spec"],
|
|
46
52
|
help: "the target face of the round",
|
|
47
53
|
},
|
|
48
54
|
base: { flag: "--base", type: "string", help: "the base artifact branch name" },
|
|
@@ -54,11 +60,27 @@ export const ARGV_CHANNEL = {
|
|
|
54
60
|
help: "the base artifact's source channel",
|
|
55
61
|
},
|
|
56
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
|
+
},
|
|
68
|
+
harness: {
|
|
69
|
+
flag: "--harness",
|
|
70
|
+
type: "enum",
|
|
71
|
+
values: HOST_IDS,
|
|
72
|
+
help: "the harness whose plugin set is installed or updated",
|
|
73
|
+
},
|
|
74
|
+
update: {
|
|
75
|
+
flag: "--update",
|
|
76
|
+
type: "bool",
|
|
77
|
+
help: "update the installed plugin set instead of installing it",
|
|
78
|
+
},
|
|
57
79
|
dryRun: {
|
|
58
80
|
flag: "--dry-run",
|
|
59
81
|
type: "bool",
|
|
60
82
|
scope: "program",
|
|
61
|
-
help: "preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix
|
|
83
|
+
help: "preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix/init)",
|
|
62
84
|
},
|
|
63
85
|
help: {
|
|
64
86
|
flag: "--help",
|
|
@@ -111,34 +133,36 @@ export const VALUE_SHAPES = {
|
|
|
111
133
|
},
|
|
112
134
|
},
|
|
113
135
|
};
|
|
114
|
-
/** The
|
|
115
|
-
* commands) plus the pure base / schema / issue artifact commands
|
|
116
|
-
* observability command. */
|
|
136
|
+
/** The eight subcommand declarations — implement, review, fix (the lifecycle work
|
|
137
|
+
* commands) plus the pure base / schema / issue artifact commands, the board
|
|
138
|
+
* observability command and the repo-independent init bootstrap. */
|
|
117
139
|
export const CLI_COMMANDS = [
|
|
118
140
|
{
|
|
119
141
|
name: "implement",
|
|
120
|
-
description:
|
|
142
|
+
description: `run the task implement phase — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
|
|
121
143
|
example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
|
|
122
144
|
keys: [
|
|
123
145
|
{ key: "tasks", required: true },
|
|
124
146
|
{ key: "plan", required: true },
|
|
147
|
+
{ key: "stealStale" },
|
|
125
148
|
],
|
|
126
149
|
},
|
|
127
150
|
{
|
|
128
151
|
name: "review",
|
|
129
|
-
description: "run a review —
|
|
130
|
-
example: `cdd review --type spec --spec ${ENGINE_DOC_ROOTS.specs}/p3-design.md`,
|
|
152
|
+
description: "run a review — wave | branch | phase-spec | overall | plan | single-spec",
|
|
153
|
+
example: `cdd review --type phase-spec --spec ${ENGINE_DOC_ROOTS.specs}/p3-design.md`,
|
|
131
154
|
keys: [
|
|
132
155
|
{ key: "type", required: true },
|
|
133
156
|
{ key: "tasks" },
|
|
134
157
|
{ key: "plan" },
|
|
135
158
|
{ key: "spec" },
|
|
136
159
|
{ key: "round" },
|
|
160
|
+
{ key: "stealStale" },
|
|
137
161
|
],
|
|
138
162
|
},
|
|
139
163
|
{
|
|
140
164
|
name: "fix",
|
|
141
|
-
description: "fix review findings —
|
|
165
|
+
description: "fix review findings — wave | branch | phase-spec | overall | plan | single-spec",
|
|
142
166
|
example: "cdd fix --type wave --tasks 1 --reviews tasks-1-review-1.json",
|
|
143
167
|
keys: [
|
|
144
168
|
{ key: "type", required: true },
|
|
@@ -146,6 +170,7 @@ export const CLI_COMMANDS = [
|
|
|
146
170
|
{ key: "reviews" },
|
|
147
171
|
{ key: "spec" },
|
|
148
172
|
{ key: "plan" },
|
|
173
|
+
{ key: "stealStale" },
|
|
149
174
|
],
|
|
150
175
|
},
|
|
151
176
|
{
|
|
@@ -200,10 +225,16 @@ export const CLI_COMMANDS = [
|
|
|
200
225
|
},
|
|
201
226
|
{
|
|
202
227
|
name: "board",
|
|
203
|
-
description: "render the progress board from a --plan or --spec entry (overall/spec/plan/wave/branch)",
|
|
228
|
+
description: "render the progress board from a --plan or --spec entry (overall/phase-spec/single-spec/plan/wave/branch)",
|
|
204
229
|
example: `cdd board --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
|
|
205
230
|
keys: [{ key: "plan" }, { key: "spec" }],
|
|
206
231
|
},
|
|
232
|
+
{
|
|
233
|
+
name: "init",
|
|
234
|
+
description: "install or update the kairos plugin set for a harness",
|
|
235
|
+
example: "cdd init --harness=claude",
|
|
236
|
+
keys: [{ key: "harness", required: true }, { key: "update" }],
|
|
237
|
+
},
|
|
207
238
|
];
|
|
208
239
|
/** The schema `<type>` vocabulary — the get leaf's ONE table (spec §5.3): the
|
|
209
240
|
* primary DocKey spellings (overall | plan | phase-spec | single-spec) plus
|
|
@@ -218,23 +249,28 @@ export const SCHEMA_TYPE_KEYS = {
|
|
|
218
249
|
phaseSpec: "phase-spec",
|
|
219
250
|
};
|
|
220
251
|
/** The conditional required group per work verb + target type — the preAction hook's
|
|
221
|
-
* data face (spec §4.2):
|
|
222
|
-
*
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
*
|
|
226
|
-
*
|
|
252
|
+
* data face (spec §4.2): one row per `--type` value, keyed by the declared flag
|
|
253
|
+
* spelling. The doc shapes carry the `--spec` document (their declared `doc-type:`
|
|
254
|
+
* picks the contract the pre-flight judges); the wave/plan faces carry `--plan`, and
|
|
255
|
+
* every branch face carries the `--plan` workspace identity (the branch line holds
|
|
256
|
+
* no commit ref: the review judges the live tree, the scope anchor BASE_BRANCH is
|
|
257
|
+
* engine-injected at dispatch). Non-exclusive — a round declaring both `--plan` and
|
|
258
|
+
* `--spec` stays accepted (no mutual-exclusion rejection). */
|
|
227
259
|
export const REQUIRED_GROUPS = {
|
|
228
260
|
review: {
|
|
229
261
|
wave: ["--plan"],
|
|
230
|
-
spec: ["--spec"],
|
|
231
|
-
plan: ["--plan"],
|
|
232
262
|
branch: ["--plan"],
|
|
263
|
+
"phase-spec": ["--spec"],
|
|
264
|
+
overall: ["--spec"],
|
|
265
|
+
plan: ["--plan"],
|
|
266
|
+
"single-spec": ["--spec"],
|
|
233
267
|
},
|
|
234
268
|
fix: {
|
|
235
269
|
wave: ["--plan"],
|
|
236
|
-
spec: ["--spec"],
|
|
237
|
-
plan: ["--plan"],
|
|
238
270
|
branch: ["--reviews", "--plan"],
|
|
271
|
+
"phase-spec": ["--spec"],
|
|
272
|
+
overall: ["--spec"],
|
|
273
|
+
plan: ["--plan"],
|
|
274
|
+
"single-spec": ["--spec"],
|
|
239
275
|
},
|
|
240
276
|
};
|
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 (
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
// (#tasksOf/#renderBrief
|
|
8
|
-
// members moved verbatim — behavior bytes identical; the root Cli
|
|
9
|
-
// instance and composes through it via its .action thin shells (zero
|
|
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
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
* (no identity on record / an
|
|
44
|
-
*
|
|
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
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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,62 @@ 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) — the line's ONE next-hop object (§5.2): the SAME derivation
|
|
116
|
+
* the capsule, the board and the lifecycle frontier read, built from this line's
|
|
117
|
+
* facts through `Ledger#nextHopOf` (the ONE assembly entry: the drift gate + the
|
|
118
|
+
* declaration read). The CLI rejection message renders THIS object's `reason` +
|
|
119
|
+
* hop/station — never a second judgment, never a second shape. The doc-class
|
|
120
|
+
* discrimination is ROOTED in the workspace's own repo basis (the same basis the
|
|
121
|
+
* lifecycle frontier injects), so an engine invoked from a subdirectory reads the
|
|
122
|
+
* same declared `doc-type:` the board does. Null when the scene holds no
|
|
123
|
+
* registered line (no fixed target → there is no line to name). */
|
|
124
|
+
lineHop(scene) {
|
|
125
|
+
const key = this.#lineKey(scene);
|
|
126
|
+
const target = this.#routeTargetOf(scene);
|
|
127
|
+
if (key === null || target === null)
|
|
128
|
+
return null;
|
|
129
|
+
const basis = scene.workspace.root.basis;
|
|
130
|
+
return scene.ledger.nextHopOf({
|
|
131
|
+
type: scene.face.type,
|
|
132
|
+
key,
|
|
133
|
+
route: scene.ledger.lineRoute(key, scene.face.type),
|
|
134
|
+
target,
|
|
135
|
+
doc: this.#docOf(scene),
|
|
136
|
+
docClassOf: (candidate) => BoardView.docClassOf(basis, candidate),
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
/** lineHopMessage(scene, hop, words) — the CLI rejection prose of one `NextHop`
|
|
140
|
+
* (P22 §5.2, the ONE message shape): a hop names its verb, a closed face names
|
|
141
|
+
* its handoff station (rendered through the SAME route renderer the `next:` line
|
|
142
|
+
* uses), and neither renders an invented verb slot. */
|
|
143
|
+
lineHopMessage(scene, hop, words) {
|
|
144
|
+
if (hop === null)
|
|
145
|
+
return "the line holds no open round";
|
|
146
|
+
const renderer = new RouteRenderer(words, ARGV_CHANNEL, HostDetect.detect(process.env), scene.workspace.root.basis);
|
|
147
|
+
return scene.router.message(hop, (entry) => renderer.render({ kind: "handoff", entry }, hop.target));
|
|
148
|
+
}
|
|
149
|
+
/** The line's judged document — the doc line's own path, the branch line's plan
|
|
150
|
+
* (its identity document, P21 §4.1); null off the doc faces. */
|
|
151
|
+
#docOf(scene) {
|
|
152
|
+
if (scene.target?.kind === "plan" || scene.target?.kind === "spec")
|
|
153
|
+
return scene.target.doc;
|
|
154
|
+
if (scene.target?.kind === "branch")
|
|
155
|
+
return scene.planPath;
|
|
156
|
+
return null;
|
|
157
|
+
}
|
|
158
|
+
/** The dispatch frame's own render target (§5.2's `target` cell) — the fixed
|
|
159
|
+
* line's type + stable key (+ the plan fact the branch literal needs). A doc shape
|
|
160
|
+
* (the `--spec` channel: phase-spec / overall / single-spec) renders its OWN
|
|
161
|
+
* target-type word, never a folded `spec` spelling. */
|
|
162
|
+
#routeTargetOf(scene) {
|
|
163
|
+
if (scene.target?.kind === "branch")
|
|
164
|
+
return { type: "branch", id: "branch", plan: scene.planPath ?? undefined };
|
|
165
|
+
if (scene.target?.kind === "spec")
|
|
166
|
+
return { type: scene.face.type, id: scene.target.doc };
|
|
167
|
+
if (scene.target?.kind === "plan")
|
|
168
|
+
return { type: "plan", id: scene.target.doc };
|
|
169
|
+
return null;
|
|
170
|
+
}
|
|
95
171
|
/** The requested group ints — the normalized tasks value split. */
|
|
96
172
|
tasksOf(parsed) {
|
|
97
173
|
return (parsed.args.tasks ?? "").split(",").map((part) => Number(part));
|
|
@@ -120,8 +196,9 @@ export class CliGate {
|
|
|
120
196
|
return scene.ledger.linePhase(key, scene.face.type);
|
|
121
197
|
}
|
|
122
198
|
/** 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;
|
|
124
|
-
* its
|
|
199
|
+
* §6.5/§3.7 — `"branch"` per workspace for the branch line; a doc line keys by
|
|
200
|
+
* its target-type word (`"phase-spec"` / `"overall"` / `"plan"` / `"single-spec"`)
|
|
201
|
+
* — never the argv path: a moved argv
|
|
125
202
|
* string must not fork the same line into two ledger rows, resetting its round),
|
|
126
203
|
* the lifecycle's own key derivation (run.ts #lineKey). */
|
|
127
204
|
#lineKey(scene) {
|
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
|
|
@@ -29,30 +29,11 @@
|
|
|
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
|
-
* 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
|
-
};
|
|
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"];
|
|
56
37
|
/** The per-harness host rows — claude / pi adaptation facts. */
|
|
57
38
|
export const HOSTS = {
|
|
58
39
|
claude: {
|
|
@@ -62,7 +43,6 @@ 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
47
|
env: { FORCE_PROMPT_CACHING_5M: "1" },
|
|
68
48
|
},
|
|
@@ -73,12 +53,6 @@ export const HOSTS = {
|
|
|
73
53
|
output: "text",
|
|
74
54
|
ship: "full",
|
|
75
55
|
detect: { env: "AI_AGENT", value: "pi" },
|
|
76
|
-
install: {
|
|
77
|
-
kairos: ["pi install npm:@oscaner-skills/kairos"],
|
|
78
|
-
superpowers: ["pi install git:github.com/obra/superpowers"],
|
|
79
|
-
"mattpocock-skills": ["pi install git:github.com/mattpocock/skills"],
|
|
80
|
-
impeccable: ["npx impeccable install --providers=pi --scope=global -y"],
|
|
81
|
-
},
|
|
82
56
|
capabilities: { parallel: "pending" },
|
|
83
57
|
env: { PI_CACHE_RETENTION: "short" },
|
|
84
58
|
},
|
|
@@ -160,13 +134,13 @@ export const HOST_CONTRACT = {
|
|
|
160
134
|
* must stay import-clean toward the dispatch face). */
|
|
161
135
|
// biome-ignore lint/complexity/noStaticOnlyClass: the module-level host-detect surface — the zero-bare-function discipline admits no standalone predicate functions.
|
|
162
136
|
export class HostDetect {
|
|
163
|
-
/** detect(env) — the first host detect row that matches, in the pinned
|
|
164
|
-
* `claude` → `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
|
|
165
139
|
* last). One row detects by its primary marker (a session env, presence/enum —
|
|
166
140
|
* a UUID CLAUDE_CODE_SESSION_ID is claude by presence) or by the AI_AGENT
|
|
167
141
|
* prefix (AI_AGENT=claude-code-…); no match returns `""`. */
|
|
168
142
|
static detect(env) {
|
|
169
|
-
for (const id of
|
|
143
|
+
for (const id of HOST_IDS) {
|
|
170
144
|
const detect = HOSTS[id].detect;
|
|
171
145
|
if (detect.env !== undefined && detect.env !== "") {
|
|
172
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 / sampling trail / 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
|
+
}
|