@oscaner-skills/cdd-engine 2.0.0 → 3.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/README.zh-CN.md +2 -2
- package/{src-next/bin.ts → dist/bin.js} +18 -21
- package/dist/contract/declare.js +998 -0
- package/dist/contract/doc.js +565 -0
- package/dist/contract/frontmatter.js +209 -0
- package/dist/contract/home-extractors.js +379 -0
- package/dist/contract/invariants.js +1030 -0
- package/dist/contract/judge.js +109 -0
- package/dist/contract/lint.js +206 -0
- package/dist/contract/project.js +371 -0
- package/dist/contract/skill-anatomy.js +156 -0
- package/dist/contract/translate.js +85 -0
- package/dist/face/artifacts.js +189 -0
- package/dist/face/board-view.js +522 -0
- package/dist/face/capsule.js +141 -0
- package/dist/face/cli.js +891 -0
- package/dist/face/declare.js +241 -0
- package/dist/face/gate.js +158 -0
- package/dist/face/graph-view.js +66 -0
- package/dist/face/host.js +211 -0
- package/dist/face/lifecycle.js +603 -0
- package/dist/face/preview.js +136 -0
- package/dist/face/projection.js +259 -0
- package/dist/face/route-render.js +162 -0
- package/dist/face/termination.js +482 -0
- package/dist/face/words.js +220 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/dist/infra/doc-roots.js +19 -0
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/dist/infra/root.js +62 -0
- package/dist/infra/runtime.js +85 -0
- package/dist/infra/workspace.js +276 -0
- package/dist/render/brief.js +82 -0
- package/dist/render/issue-body.js +129 -0
- package/dist/render/skeleton.js +434 -0
- package/dist/render/templates.js +520 -0
- package/dist/session/faces.js +38 -0
- package/dist/session/graph.js +309 -0
- package/dist/session/handoff-schema.js +295 -0
- package/dist/session/ledger.js +762 -0
- package/dist/session/next.js +211 -0
- package/dist/session/preflight.js +194 -0
- package/dist/session/round-naming.js +73 -0
- package/dist/session/run.js +441 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +8 -7
- package/templates/report/issue-body.json +0 -46
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/smoke.integration.test.ts +0 -202
- package/src-next/__tests__/zero-dep.test.ts +0 -134
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
- package/src-next/contract/__tests__/declare.test.ts +0 -242
- package/src-next/contract/__tests__/doc.test.ts +0 -358
- package/src-next/contract/__tests__/judge.test.ts +0 -873
- package/src-next/contract/__tests__/lint.test.ts +0 -314
- package/src-next/contract/__tests__/project.test.ts +0 -419
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -983
- package/src-next/contract/doc.ts +0 -753
- package/src-next/contract/invariants.ts +0 -1268
- package/src-next/contract/judge.ts +0 -142
- package/src-next/contract/lint.ts +0 -275
- package/src-next/contract/project.ts +0 -596
- package/src-next/contract/skill-anatomy.ts +0 -273
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -948
- package/src-next/face/__tests__/capsule.test.ts +0 -276
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
- package/src-next/face/__tests__/cli.test.ts +0 -4643
- package/src-next/face/__tests__/face.test.ts +0 -289
- package/src-next/face/__tests__/graph-view.test.ts +0 -61
- package/src-next/face/__tests__/host.test.ts +0 -24
- package/src-next/face/__tests__/negation.ts +0 -6
- package/src-next/face/__tests__/projection.test.ts +0 -301
- package/src-next/face/__tests__/sync-runner.test.ts +0 -70
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -195
- package/src-next/face/board-view.ts +0 -662
- package/src-next/face/capsule.ts +0 -149
- package/src-next/face/cli.ts +0 -819
- package/src-next/face/declare.ts +0 -326
- package/src-next/face/gate.ts +0 -170
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -326
- package/src-next/face/lifecycle.ts +0 -700
- package/src-next/face/projection.ts +0 -282
- package/src-next/face/route-render.ts +0 -160
- package/src-next/face/words.ts +0 -296
- package/src-next/infra/__tests__/infra.test.ts +0 -287
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -185
- package/src-next/infra/workspace.ts +0 -232
- package/src-next/render/__tests__/render.test.ts +0 -499
- package/src-next/render/__tests__/skeleton.test.ts +0 -466
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -159
- package/src-next/render/skeleton.ts +0 -437
- package/src-next/render/templates.ts +0 -650
- package/src-next/session/__tests__/graph.test.ts +0 -270
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
- package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
- package/src-next/session/__tests__/ledger.test.ts +0 -744
- package/src-next/session/__tests__/next.test.ts +0 -368
- package/src-next/session/__tests__/preflight.test.ts +0 -491
- package/src-next/session/__tests__/run.test.ts +0 -1014
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -469
- package/src-next/session/faces.ts +0 -110
- package/src-next/session/graph.ts +0 -411
- package/src-next/session/handoff-schema.ts +0 -373
- package/src-next/session/ledger.ts +0 -1004
- package/src-next/session/next.ts +0 -192
- package/src-next/session/preflight.ts +0 -240
- package/src-next/session/run.ts +0 -606
- package/src-next/session/state.ts +0 -30
- package/src-next/session/wave.ts +0 -139
package/src-next/face/cli.ts
DELETED
|
@@ -1,819 +0,0 @@
|
|
|
1
|
-
// packages/cdd-engine/src-next/face/cli.ts
|
|
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
|
|
6
|
-
// the new tree's composition root: the
|
|
7
|
-
// `Cli.create` static factory — the class face is the entry, the module carries zero
|
|
8
|
-
// bare functions (the composition root's deliberate class form) — wires the contract /
|
|
9
|
-
// session / face objects into the ONE CLI the bin thin entry boots. Task 3 (P1)
|
|
10
|
-
// 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
|
-
// channel), the declaration projection (face/projection.ts — the CommandTreeBuilder
|
|
13
|
-
// whose commander program OWNS the parse + help + validation pipeline), and the run
|
|
14
|
-
// face; the typed argv parse channel (face/argv.ts) was deleted at T6 — the parse
|
|
15
|
-
// handover to commander is total, and the domain-run error face's usage is
|
|
16
|
-
// commander's own byte.
|
|
17
|
-
//
|
|
18
|
-
// Task 8 (the split contract §6.2) slimmed this module to the COMPOSITION RESPONSIBILITY:
|
|
19
|
-
// wire + exit + parse, plus the work/pure command run bodies that ASSEMBLE the scene.
|
|
20
|
-
// The domain faces live in their own files and are composed through here —
|
|
21
|
-
// face/lifecycle.ts (CliLifecycle — the dispatch + readback + round-context plane:
|
|
22
|
-
// implement/review/fix dispatch, the read-back reconstruct, the round-context fact
|
|
23
|
-
// assembly; the pre-split HarnessDispatch member renamed, re-exported unchanged
|
|
24
|
-
// below), face/gate.ts (CliGate — the target/line gate family: the readiness
|
|
25
|
-
// judgments + the doc line's revision-aware BLOCK/pending-fix faces), face/artifacts.ts
|
|
26
|
-
// (CliArtifacts — the pure-command domain: schema get / issue / base runs). The root
|
|
27
|
-
// Cli holds the three instances and composes through them via its .action thin shells
|
|
28
|
-
// (zero bare functions; the seams it still assembles — the lifecycle dispatch seam's
|
|
29
|
-
// production default construction — stay here).
|
|
30
|
-
//
|
|
31
|
-
// · runArgv — parse through the commander program (face/projection.ts), dispatch
|
|
32
|
-
// each parsed command through an .action thin shell (the parseArg-normalized
|
|
33
|
-
// values ride into the domain run as its consumed values, zero rewriting) and
|
|
34
|
-
// normalize the exit-code surface from the thrown CommanderError (0 = help/OK ·
|
|
35
|
-
// 2 = usage (incl. the preAction conditional-required) · 1 = run failure).
|
|
36
|
-
// · the .action thin shells — the work commands (implement / review / fix)
|
|
37
|
-
// assemble the lifecycle (session/run), the capsule + words (face), the ledger
|
|
38
|
-
// (session/ledger) and the task graph (contract parse) and advance the
|
|
39
|
-
// requested phase; schema / issue / base run their pure artifact surfaces
|
|
40
|
-
// through the same assembled objects (the pure runs + the readiness gates
|
|
41
|
-
// 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
|
|
44
|
-
// bare functions (the composition root is the Cli class's static create factory).
|
|
45
|
-
|
|
46
|
-
import { readFileSync } from "node:fs";
|
|
47
|
-
import process from "node:process";
|
|
48
|
-
import { type Command, CommanderError } from "commander";
|
|
49
|
-
import { declaredRegistries } from "../contract/declare.ts";
|
|
50
|
-
import { PlanDocType } from "../contract/doc.ts";
|
|
51
|
-
import { Contract } from "../contract/judge.ts";
|
|
52
|
-
import type { DocKey } from "../contract/project.ts";
|
|
53
|
-
import { Projector } from "../contract/project.ts";
|
|
54
|
-
import { Translator } from "../contract/translate.ts";
|
|
55
|
-
import { ConfigLoader } from "../infra/config.ts";
|
|
56
|
-
import { GitClient } from "../infra/git.ts";
|
|
57
|
-
import { Workspace, WorkspaceRoot } from "../infra/workspace.ts";
|
|
58
|
-
import { BriefRenderer } from "../render/brief.ts";
|
|
59
|
-
import { IssueBodyRenderer } from "../render/issue-body.ts";
|
|
60
|
-
import { TemplateAssembler } from "../render/templates.ts";
|
|
61
|
-
import type { TargetFace, TargetType } from "../session/faces.ts";
|
|
62
|
-
import { targetFaces } from "../session/faces.ts";
|
|
63
|
-
import { TaskGraph } from "../session/graph.ts";
|
|
64
|
-
import type { RoundStatus } from "../session/ledger.ts";
|
|
65
|
-
import { Ledger } from "../session/ledger.ts";
|
|
66
|
-
import { NextStepRouter } from "../session/next.ts";
|
|
67
|
-
import type { PreFlightVerdict } from "../session/preflight.ts";
|
|
68
|
-
import { PreFlight } from "../session/preflight.ts";
|
|
69
|
-
import type { DispatchStep, RunState } from "../session/run.ts";
|
|
70
|
-
import { EMPTY_RUN_STATE, Lifecycle } from "../session/run.ts";
|
|
71
|
-
import { CliArtifacts } from "./artifacts.ts";
|
|
72
|
-
import { BoardView } from "./board-view.ts";
|
|
73
|
-
import { Capsule } from "./capsule.ts";
|
|
74
|
-
import { ARGV_CHANNEL, type CliLeafName, type CliVerb } from "./declare.ts";
|
|
75
|
-
import { CliGate } from "./gate.ts";
|
|
76
|
-
import { GraphView } from "./graph-view.ts";
|
|
77
|
-
import { HostDetect } from "./host.ts";
|
|
78
|
-
import {
|
|
79
|
-
type CliIo,
|
|
80
|
-
CliLifecycle,
|
|
81
|
-
type DispatchScene,
|
|
82
|
-
type SyncProcess,
|
|
83
|
-
SyncRunner,
|
|
84
|
-
} from "./lifecycle.ts";
|
|
85
|
-
import { CommandTreeBuilder } from "./projection.ts";
|
|
86
|
-
import { Words } from "./words.ts";
|
|
87
|
-
|
|
88
|
-
// ---------------------------------------------------------------------------
|
|
89
|
-
// the re-exported seams + the dispatch production default — the split contract's
|
|
90
|
-
// lifecycle face owns the dispatch/readback plane (face/lifecycle.ts) and the
|
|
91
|
-
// shared seams it rides; the composition root re-exports them here unchanged so
|
|
92
|
-
// the module's public surface never drifts (CliIo · SyncProcess · SyncRunner ·
|
|
93
|
-
// ProcessEnvLike · DispatchScene · BaseArtifact · HarnessDispatch).
|
|
94
|
-
// ---------------------------------------------------------------------------
|
|
95
|
-
|
|
96
|
-
export type { BaseArtifact } from "./artifacts.ts";
|
|
97
|
-
export type {
|
|
98
|
-
CliIo,
|
|
99
|
-
DispatchScene,
|
|
100
|
-
ProcessEnvLike,
|
|
101
|
-
SyncProcess,
|
|
102
|
-
} from "./lifecycle.ts";
|
|
103
|
-
export {
|
|
104
|
-
CliLifecycle as HarnessDispatch,
|
|
105
|
-
SyncRunner,
|
|
106
|
-
} from "./lifecycle.ts";
|
|
107
|
-
/** The composition options — every collaborator injectable (tests substitute the
|
|
108
|
-
* hermetic ones: io / dispatch / repoRoot / stdin); the production defaults wire
|
|
109
|
-
* the living process. */
|
|
110
|
-
export interface CliOptions {
|
|
111
|
-
io?: CliIo;
|
|
112
|
-
config?: ConfigLoader;
|
|
113
|
-
projector?: Projector;
|
|
114
|
-
words?: Words;
|
|
115
|
-
translator?: Translator;
|
|
116
|
-
git?: GitClient;
|
|
117
|
-
sync?: SyncProcess;
|
|
118
|
-
cwd?: string;
|
|
119
|
-
repoRoot?: string;
|
|
120
|
-
dryRun?: boolean;
|
|
121
|
-
dispatch?: DispatchStep | null;
|
|
122
|
-
preflight?: PreFlight;
|
|
123
|
-
template?: TemplateAssembler;
|
|
124
|
-
brief?: BriefRenderer;
|
|
125
|
-
stdinRead?: () => string;
|
|
126
|
-
}
|
|
127
|
-
|
|
128
|
-
/** One work command's assembled scene — the composition the run body advances. */
|
|
129
|
-
export interface WorkScene extends DispatchScene {
|
|
130
|
-
planText: string | null;
|
|
131
|
-
type: TargetType;
|
|
132
|
-
face: TargetFace;
|
|
133
|
-
target: { kind: "branch" } | { kind: "doc"; doc: string } | null;
|
|
134
|
-
state: RunState;
|
|
135
|
-
router: NextStepRouter;
|
|
136
|
-
}
|
|
137
|
-
|
|
138
|
-
/** The thin-shell → run-body input — the .action shell maps commander's parsed
|
|
139
|
-
* opts onto this consumption face (the parseArg-normalized values ride through
|
|
140
|
-
* verbatim, zero rewriting: int-list → the comma string · enum → the value · sha
|
|
141
|
-
* → the short form · the schema <type> → the parseTypeKey normalization). The
|
|
142
|
-
* CLI's parse-result face retired with the argv channel at T6 — commander owns
|
|
143
|
-
* the parse; this seam is the run face's own shape, never a parallel parse
|
|
144
|
-
* product. */
|
|
145
|
-
export interface RunInput {
|
|
146
|
-
/** The nested leaf word (schema get|gen · base set|get) — null on the verbs. */
|
|
147
|
-
leaf: CliLeafName | null;
|
|
148
|
-
/** The declared keys' values — normalized strings (undefined-flagged keys absent). */
|
|
149
|
-
args: Record<string, string>;
|
|
150
|
-
/** The positional values (the schema <type> — the parseTypeKey-normalized key). */
|
|
151
|
-
positionals: readonly string[];
|
|
152
|
-
/** The invocation's synthetic-dispatch scope (the --dry-run program flag). */
|
|
153
|
-
dryRun: boolean;
|
|
154
|
-
}
|
|
155
|
-
|
|
156
|
-
/**
|
|
157
|
-
* The Cli — the command face's parse/run surface over the assembled object graph.
|
|
158
|
-
* runArgv() parses through the commander program and rejects unknown flags (the
|
|
159
|
-
* unknown-flag semantics); run() dispatches to the command's run body — the work verbs
|
|
160
|
-
* compose the lifecycle/capsule/ledger/graph and advance the requested phase, the
|
|
161
|
-
* pure verbs run their artifact surfaces through the same assembled objects.
|
|
162
|
-
*/
|
|
163
|
-
export class Cli {
|
|
164
|
-
readonly #io: CliIo;
|
|
165
|
-
readonly #config: ConfigLoader;
|
|
166
|
-
readonly #projector: Projector;
|
|
167
|
-
readonly #words: Words;
|
|
168
|
-
readonly #git: GitClient;
|
|
169
|
-
readonly #sync: SyncProcess;
|
|
170
|
-
readonly #cwd: string;
|
|
171
|
-
readonly #repoRoot: string | null;
|
|
172
|
-
readonly #dryRun: boolean;
|
|
173
|
-
readonly #dispatch: DispatchStep | null;
|
|
174
|
-
readonly #template: TemplateAssembler;
|
|
175
|
-
readonly #brief: BriefRenderer;
|
|
176
|
-
readonly #stdinRead: () => string;
|
|
177
|
-
readonly #issue: IssueBodyRenderer;
|
|
178
|
-
readonly #translator: Translator;
|
|
179
|
-
/** The pre-flight board face (the blocked-dispatch wave hint). */
|
|
180
|
-
readonly #graphView: GraphView;
|
|
181
|
-
/** The lifecycle pre-flight seam (P4.1 T1) — the single dispatch gate the work
|
|
182
|
-
* commands consult before ANY child dispatch (tree-clean → graph → wave →
|
|
183
|
-
* doc-contract; the CLI orchestrates the call + the render, never a re-type). */
|
|
184
|
-
readonly #preflight: PreFlight;
|
|
185
|
-
/** The contract coordinator — the doc-contract judgment face the pre-flight's
|
|
186
|
-
* doc gate reads (the single interpreter entry; spec §12 · D34 retired the
|
|
187
|
-
* filename→type derivation — the doc type is now the declared header fact read
|
|
188
|
-
* through BoardView.readDocType). */
|
|
189
|
-
readonly #contract: Contract;
|
|
190
|
-
/** The commander command tree — the declaration projection (CommandTreeBuilder,
|
|
191
|
-
* face/projection.ts): the domain-run error face's usage byte is the command
|
|
192
|
-
* node's commander-native helpInformation() first line (the self-built usage
|
|
193
|
-
* corpus is retired; the T3 rebuild closes the parse face onto the same
|
|
194
|
-
* program). */
|
|
195
|
-
readonly #program: Command;
|
|
196
|
-
/** The target/line gate family (T8 — the split contract's gate face,
|
|
197
|
-
* face/gate.ts): the work commands' readiness judgments (line phase / review
|
|
198
|
-
* convergence BLOCKs) + the group/line helpers. */
|
|
199
|
-
readonly #gate: CliGate;
|
|
200
|
-
/** The pure-command domain (T8 — the split contract's artifacts face,
|
|
201
|
-
* face/artifacts.ts): the schema/issue/base run bodies. */
|
|
202
|
-
readonly #artifacts: CliArtifacts;
|
|
203
|
-
|
|
204
|
-
constructor(opts: CliOptions = {}) {
|
|
205
|
-
this.#io = opts.io ?? {
|
|
206
|
-
stdout: (t) => process.stdout.write(t),
|
|
207
|
-
stderr: (t) => process.stderr.write(t),
|
|
208
|
-
};
|
|
209
|
-
this.#config = opts.config ?? new ConfigLoader();
|
|
210
|
-
this.#words = opts.words ?? new Words();
|
|
211
|
-
this.#projector = opts.projector ?? new Projector(declaredRegistries);
|
|
212
|
-
this.#program = new CommandTreeBuilder().program;
|
|
213
|
-
this.#wireTreeOutput(this.#program);
|
|
214
|
-
this.#wireActions();
|
|
215
|
-
this.#git = opts.git ?? new GitClient();
|
|
216
|
-
this.#sync = opts.sync ?? new SyncRunner();
|
|
217
|
-
this.#cwd = opts.cwd ?? process.cwd();
|
|
218
|
-
this.#repoRoot = opts.repoRoot ?? null;
|
|
219
|
-
this.#dryRun = opts.dryRun ?? false;
|
|
220
|
-
this.#dispatch = opts.dispatch ?? null;
|
|
221
|
-
this.#template = opts.template ?? new TemplateAssembler();
|
|
222
|
-
this.#brief = opts.brief ?? new BriefRenderer();
|
|
223
|
-
this.#stdinRead = opts.stdinRead ?? (() => readFileSync(0, "utf8"));
|
|
224
|
-
this.#translator = opts.translator ?? new Translator(this.#words);
|
|
225
|
-
this.#issue = new IssueBodyRenderer(this.#words, this.#translator);
|
|
226
|
-
this.#graphView = new GraphView();
|
|
227
|
-
this.#contract = new Contract();
|
|
228
|
-
this.#preflight =
|
|
229
|
-
opts.preflight ??
|
|
230
|
-
new PreFlight({
|
|
231
|
-
git: this.#git,
|
|
232
|
-
contract: this.#contract,
|
|
233
|
-
words: this.#words,
|
|
234
|
-
});
|
|
235
|
-
this.#gate = new CliGate({ brief: this.#brief });
|
|
236
|
-
this.#artifacts = new CliArtifacts({
|
|
237
|
-
io: this.#io,
|
|
238
|
-
projector: this.#projector,
|
|
239
|
-
issue: this.#issue,
|
|
240
|
-
stdinRead: this.#stdinRead,
|
|
241
|
-
usage: (node, message) => this.#usage(node, message),
|
|
242
|
-
});
|
|
243
|
-
}
|
|
244
|
-
|
|
245
|
-
// ---------------------------------------------------------------------------
|
|
246
|
-
// the commander parse pipeline — the composition root parses through the
|
|
247
|
-
// projection's program (T3): the .action thin shells (below) dispatch the parsed
|
|
248
|
-
// command to its domain run; the exit-code discriminator maps the CommanderError
|
|
249
|
-
// surface (§3.1 — probe-verified v0.9): help exit 0 / helpDisplayed → 0 · help
|
|
250
|
-
// non-zero (bare run · missing subcommand · help <bogus>) + usage-class codes →
|
|
251
|
-
// 2 · an unexpected throw → 1.
|
|
252
|
-
// ---------------------------------------------------------------------------
|
|
253
|
-
|
|
254
|
-
/** runArgv(argv) — the CLI face: parse through the commander program, return the
|
|
255
|
-
* thin shell's domain-run exit code (0 = success/help · 2 = usage · 1 = run
|
|
256
|
-
* failure — the steady exit-code table). Every commander/normal usage error
|
|
257
|
-
* discriminates on the thrown CommanderError: the help display faces write
|
|
258
|
-
* themselves through the node's configured output (the CLI never re-types a
|
|
259
|
-
* help byte), the parse/usage rejections carry commander's own "error: " line
|
|
260
|
-
* (never double-written), and the preAction conditional-required rejection (the
|
|
261
|
-
* one commander throws unwritten) is surfaced by the run face. */
|
|
262
|
-
async runArgv(raw: readonly string[]): Promise<number> {
|
|
263
|
-
try {
|
|
264
|
-
this.#exitCode = 0;
|
|
265
|
-
await this.#program.parseAsync([...raw], { from: "user" });
|
|
266
|
-
return this.#exitCode;
|
|
267
|
-
} catch (err) {
|
|
268
|
-
return this.#normalizeExit(err);
|
|
269
|
-
}
|
|
270
|
-
}
|
|
271
|
-
|
|
272
|
-
/** The exit-code discriminator — the CommanderError surface (§3.1): the explicit
|
|
273
|
-
* help faces exit 0, the missing-command/missing-subcommand faces ride the help
|
|
274
|
-
* code's non-zero exit → 2, the usage-class codes (unknown option/command ·
|
|
275
|
-
* invalid argument (incl. the preAction conditional-required) · excess args ·
|
|
276
|
-
* missing required) → 2, an unexpected error → 1. */
|
|
277
|
-
#normalizeExit(err: unknown): number {
|
|
278
|
-
if (err instanceof CommanderError) {
|
|
279
|
-
if (err.code === "commander.help") return err.exitCode === 0 ? 0 : 2;
|
|
280
|
-
if (err.code === "commander.helpDisplayed") return 0;
|
|
281
|
-
// usage-class — commander's own error() already wrote its "error: ..." line
|
|
282
|
-
// (the parseArg/unknown surfaces); the preAction hook's InvalidArgumentError
|
|
283
|
-
// and the run bodies' #usage throw are both thrown unwritten — the run face
|
|
284
|
-
// surfaces them once.
|
|
285
|
-
if (!err.message.startsWith("error: ")) this.#io.stderr(`error: ${err.message}\n`);
|
|
286
|
-
return 2;
|
|
287
|
-
}
|
|
288
|
-
this.#io.stderr(`cdd: ${err instanceof Error ? err.message : String(err)}\n`);
|
|
289
|
-
return 1;
|
|
290
|
-
}
|
|
291
|
-
|
|
292
|
-
/** The domain-run usage error — a usage rejection raised inside a run body:
|
|
293
|
-
* commander's OWN CommanderError (never a second error type — the retired
|
|
294
|
-
* parse-channel error class is deleted at T6), which the normalizeExit
|
|
295
|
-
* discriminator above surfaces with the native "error:" byte and exit 2 (§3.1).
|
|
296
|
-
* The usage byte is the owning command node's commander-native
|
|
297
|
-
* helpInformation() first line (the declaration's help face — the self-built
|
|
298
|
-
* usage corpus never returned here); the throw carries only the message. */
|
|
299
|
-
#usage(node: Command, message: string): never {
|
|
300
|
-
const usageLine = node.helpInformation().split("\n")[0];
|
|
301
|
-
if (usageLine !== "") this.#io.stderr(`${usageLine}\n`);
|
|
302
|
-
throw new CommanderError(2, "cdd.usage-error", message);
|
|
303
|
-
}
|
|
304
|
-
|
|
305
|
-
/** The per-invocation exit code the thin shells capture (commander discards the
|
|
306
|
-
* action's return — parseAsync resolves with the program node, so the shell
|
|
307
|
-
* writes the domain-run's code here and runArgv reads it back). */
|
|
308
|
-
#exitCode = 0;
|
|
309
|
-
|
|
310
|
-
/** The .action thin shells — the parsed command → its domain run: build the
|
|
311
|
-
* run input from commander's parsed opts (parseArg-normalized values pass
|
|
312
|
-
* through as the domain's consumed values — no rewrite, §3.3) and dispatch to
|
|
313
|
-
* the domain run, capturing the exit code. */
|
|
314
|
-
#wireActions(): void {
|
|
315
|
-
const commandNode = (name: CliVerb) => this.#program.commands.find((c) => c.name() === name)!;
|
|
316
|
-
const leafNode = (parent: CliVerb, name: CliLeafName) =>
|
|
317
|
-
commandNode(parent).commands.find((c) => c.name() === name)!;
|
|
318
|
-
|
|
319
|
-
// the work verbs — implement / review / fix compose the domain run
|
|
320
|
-
for (const verb of ["implement", "review", "fix"] as const) {
|
|
321
|
-
commandNode(verb).action(async (_opts: unknown, command: Command) => {
|
|
322
|
-
this.#exitCode = await this.#runWork(verb, command, this.#runInput(null, command));
|
|
323
|
-
});
|
|
324
|
-
}
|
|
325
|
-
// the pure commands' leaves — schema get · base set/get · issue render
|
|
326
|
-
leafNode("schema", "get").action(
|
|
327
|
-
async (_type: unknown, _target: unknown, _opts: unknown, command: Command) => {
|
|
328
|
-
this.#exitCode = await this.#runSchema(command, this.#runInput("get", command));
|
|
329
|
-
},
|
|
330
|
-
);
|
|
331
|
-
leafNode("base", "set").action(async (_opts: unknown, command: Command) => {
|
|
332
|
-
this.#exitCode = await this.#runBase(command, this.#runInput("set", command));
|
|
333
|
-
});
|
|
334
|
-
leafNode("base", "get").action(async (_opts: unknown, command: Command) => {
|
|
335
|
-
this.#exitCode = await this.#runBase(command, this.#runInput("get", command));
|
|
336
|
-
});
|
|
337
|
-
leafNode("issue", "render").action(async () => {
|
|
338
|
-
this.#exitCode = this.#artifacts.runIssue();
|
|
339
|
-
});
|
|
340
|
-
// the board observability command — a pure read (no preflight gate)
|
|
341
|
-
commandNode("board").action(async (_slug: unknown, _opts: unknown, command: Command) => {
|
|
342
|
-
this.#exitCode = await this.#runBoard(command, this.#runInput(null, command));
|
|
343
|
-
});
|
|
344
|
-
}
|
|
345
|
-
|
|
346
|
-
/** `cdd board <slug>` — the slug progress board (spec §5 · §2.2): a PURE READ —
|
|
347
|
-
* zero preflight gate, zero tree writes, zero ledger writes, zero child dispatch.
|
|
348
|
-
* The slug (the one positional) resolves the repo root, assembles the node tree
|
|
349
|
-
* and renders the phase/program board + the `next:` derivation to stdout. A
|
|
350
|
-
* missing slug is a usage error (exit 2, commander's own byte); a slug matching
|
|
351
|
-
* nothing on disk renders the not-found face and exits 2; a present doc line
|
|
352
|
-
* carrying no `- **Doc type**:` declaration renders its BLOCKED marker and exits 2
|
|
353
|
-
* (spec §12 · D34). The host is detected once for the pipeline-entry ref render
|
|
354
|
-
* (REFS[ref][host], the same judgment the capsule injects — never hard-coded). */
|
|
355
|
-
async #runBoard(node: Command, parsed: RunInput): Promise<number> {
|
|
356
|
-
const slug = parsed.positionals[0];
|
|
357
|
-
if (slug === undefined) this.#usage(node, "cdd board: missing <slug>");
|
|
358
|
-
const repoRoot = await this.#repoRootOf(parsed);
|
|
359
|
-
if (!BoardView.hasNode(slug, repoRoot)) {
|
|
360
|
-
this.#io.stderr(`cdd board: no docs match slug ${slug}\n`);
|
|
361
|
-
return 2;
|
|
362
|
-
}
|
|
363
|
-
const host = HostDetect.detect(process.env);
|
|
364
|
-
const board = BoardView.render(slug, repoRoot, this.#words, host, ARGV_CHANNEL);
|
|
365
|
-
for (const line of board.lines) this.#io.stdout(`${line}\n`);
|
|
366
|
-
return board.exitCode;
|
|
367
|
-
}
|
|
368
|
-
|
|
369
|
-
/** The thin shell's run input — commander's parsed opts mapped to the domain
|
|
370
|
-
* run's consumption face (the parseArg-normalized values ride through verbatim:
|
|
371
|
-
* int-list → the comma string · enum → the value · sha → the short form · the
|
|
372
|
-
* schema <type> → the parseTypeKey normalization), plus the positionals
|
|
373
|
-
* (processedArgs) and the program-scope dry-run (optsWithGlobals — the flag
|
|
374
|
-
* lives on the program node, merged here). The args read GLOBALS too: a flag
|
|
375
|
-
* declared on the parent command (schema's --plan) is consumed by that node —
|
|
376
|
-
* the leaf's own opts would miss it. */
|
|
377
|
-
#runInput(leaf: CliLeafName | null, command: Command): RunInput {
|
|
378
|
-
const globals = command.optsWithGlobals() as Record<string, unknown>;
|
|
379
|
-
const args: Record<string, string> = {};
|
|
380
|
-
for (const [key, value] of Object.entries(globals)) {
|
|
381
|
-
if (value === undefined) continue;
|
|
382
|
-
args[key] = typeof value === "boolean" ? (value ? "true" : "false") : String(value);
|
|
383
|
-
}
|
|
384
|
-
return {
|
|
385
|
-
leaf,
|
|
386
|
-
args,
|
|
387
|
-
positionals: command.processedArgs as string[],
|
|
388
|
-
dryRun: this.#dryRun || globals.dryRun === true,
|
|
389
|
-
};
|
|
390
|
-
}
|
|
391
|
-
|
|
392
|
-
/** Configure every node's output into the injected io (commander writes its
|
|
393
|
-
* help/error bytes through the node that produced them — a subcommand's help
|
|
394
|
-
* uses the subcommand's own output configuration, so the whole tree must be
|
|
395
|
-
* wired, never just the program). */
|
|
396
|
-
#wireTreeOutput(node: Command): void {
|
|
397
|
-
node.configureOutput({
|
|
398
|
-
writeOut: (text) => this.#io.stdout(text),
|
|
399
|
-
writeErr: (text) => this.#io.stderr(text),
|
|
400
|
-
});
|
|
401
|
-
for (const child of node.commands) this.#wireTreeOutput(child);
|
|
402
|
-
}
|
|
403
|
-
|
|
404
|
-
// ---------------------------------------------------------------------------
|
|
405
|
-
// the work commands — lifecycle/capsule/ledger composition + the phase advance
|
|
406
|
-
// ---------------------------------------------------------------------------
|
|
407
|
-
|
|
408
|
-
/** One work command's run — assemble the scene, advance the requested phase (the
|
|
409
|
-
* lifecycle's single dispatch step per frame), render the capsule lines. */
|
|
410
|
-
async #runWork(verb: CliVerb, node: Command, parsed: RunInput): Promise<number> {
|
|
411
|
-
const type = (parsed.args.type ?? "wave") as TargetType;
|
|
412
|
-
if (type === "wave" && parsed.args.tasks === undefined) {
|
|
413
|
-
this.#usage(node, `cdd ${verb} --type wave: missing required --tasks <n|n,n,…>`);
|
|
414
|
-
}
|
|
415
|
-
const scene = await this.#sceneOf(verb, type, node, parsed);
|
|
416
|
-
|
|
417
|
-
// THE pre-flight seam (P4.1 T1 · design §1): the single dispatch gate —
|
|
418
|
-
// tree-clean → graph → wave → doc-contract — ONE call, the whole sequence
|
|
419
|
-
// lives in the seam (session/preflight.ts), the CLI only orchestrates the call
|
|
420
|
-
// + the verdict render (zero re-implemented gate here). A refused verdict
|
|
421
|
-
// returns before any brief/lifecycle: no child dispatch ever runs. The
|
|
422
|
-
// dirty-tree / doc-contract refusals ride the CDD_BLOCKED channel; the
|
|
423
|
-
// graph / wave refusals keep the pre-existing refusal face.
|
|
424
|
-
const docPath = scene.target !== null && scene.target.kind === "doc" ? scene.target.doc : "";
|
|
425
|
-
const preflight = await this.#preflight.vet({
|
|
426
|
-
verb: verb as "implement" | "review" | "fix",
|
|
427
|
-
type,
|
|
428
|
-
repoRoot: scene.workspace.root.repoRoot,
|
|
429
|
-
planText: scene.planText,
|
|
430
|
-
tasks: type === "wave" ? new Set(this.#gate.tasksOf(parsed)) : null,
|
|
431
|
-
ledger: scene.ledger,
|
|
432
|
-
doc:
|
|
433
|
-
type === "spec" || type === "plan"
|
|
434
|
-
? {
|
|
435
|
-
// The ONE declaration reading face (spec §12 · D34) — both the spec and
|
|
436
|
-
// the plan dispatch read the doc's `- **Doc type**:` header declaration;
|
|
437
|
-
// a declaration-less doc reads null and the seam BLOCKs (zero command-type
|
|
438
|
-
// carve-out, zero filename-suffix fallback).
|
|
439
|
-
docKey: BoardView.readDocType(docPath),
|
|
440
|
-
path: docPath,
|
|
441
|
-
}
|
|
442
|
-
: null,
|
|
443
|
-
});
|
|
444
|
-
if (!preflight.ok) {
|
|
445
|
-
this.#renderPreflightBlocked(verb, preflight, scene);
|
|
446
|
-
return 1;
|
|
447
|
-
}
|
|
448
|
-
|
|
449
|
-
// The unconditional extract (§4.1): every wave-face dispatch re-renders the
|
|
450
|
-
// brief from the CURRENT plan text — implement, review and fix alike (a
|
|
451
|
-
// mid-run plan amendment reflects into the next dispatch; no "exists → leave
|
|
452
|
-
// it" reuse). The doc/branch faces carry no wave brief (planText is null there).
|
|
453
|
-
if (type === "wave" && scene.planText !== null)
|
|
454
|
-
scene.briefPath = this.#gate.renderBrief(scene, parsed);
|
|
455
|
-
const expected =
|
|
456
|
-
verb === "implement" ? "implement" : verb === "fix" ? "fix" : scene.face.product.reviewLead;
|
|
457
|
-
|
|
458
|
-
// The per-invocation batch cursor: the in-memory done set mirrors the on-disk
|
|
459
|
-
// ledger's closed waves (the C5 closure single face) — NOT a "every non-group
|
|
460
|
-
// task pre-done" shortcut. The old shortcut made the frontier yield exactly the
|
|
461
|
-
// requested group, but it also emptied readyBatch() at every closure: a mid-run
|
|
462
|
-
// wave's fix rendered `next: done` instead of the next wave (the {16,22,24} →
|
|
463
|
-
// {25,26,27} bug — the closure routing judged a per-invocation cursor, not the
|
|
464
|
-
// plan's real remaining frontier). The ledger mirror keeps the progress face
|
|
465
|
-
// cross-invocation: the dispatched group's own closure marks in #markTerminal
|
|
466
|
-
// as the loop advances, and the next wave surfaces from the live closed set.
|
|
467
|
-
let group: Set<number> | null = null;
|
|
468
|
-
if (type === "wave") {
|
|
469
|
-
group = new Set(this.#gate.tasksOf(parsed));
|
|
470
|
-
const planIds =
|
|
471
|
-
scene.planText !== null
|
|
472
|
-
? new PlanDocType("plan")
|
|
473
|
-
.parse(scene.planText.split("\n"))
|
|
474
|
-
.taskBlocks.map((block) => block.id)
|
|
475
|
-
: [];
|
|
476
|
-
for (const id of group) {
|
|
477
|
-
if (!planIds.includes(id)) {
|
|
478
|
-
this.#usage(node, `cdd ${verb}: task ${id} not found in the plan`);
|
|
479
|
-
}
|
|
480
|
-
}
|
|
481
|
-
for (const id of scene.ledger.closedWaves()) scene.state.markDone(id);
|
|
482
|
-
}
|
|
483
|
-
|
|
484
|
-
const statuses: (RoundStatus | null)[] = [];
|
|
485
|
-
const dispatch: DispatchStep = this.#dispatchOf(scene, parsed);
|
|
486
|
-
const run = new Lifecycle({
|
|
487
|
-
face: scene.face,
|
|
488
|
-
state: scene.state,
|
|
489
|
-
ledger: scene.ledger,
|
|
490
|
-
router: scene.router,
|
|
491
|
-
// The dispatch-entry pre-flight wiring (P4.1 T1): the single seam verdict the
|
|
492
|
-
// work command computed rides the lifecycle's gate — a refused frame is
|
|
493
|
-
// structurally never passed to the child (the lifecycle's hard "child zero-dispatch"
|
|
494
|
-
// guarantee; the CLI already returned above when the seam refused).
|
|
495
|
-
preflight: { gate: () => (preflight.ok ? null : preflight) },
|
|
496
|
-
dispatch: (frame) => {
|
|
497
|
-
const outcome = dispatch(frame);
|
|
498
|
-
statuses.push(outcome.status ?? null);
|
|
499
|
-
return outcome;
|
|
500
|
-
},
|
|
501
|
-
target: scene.target ?? undefined,
|
|
502
|
-
capsule: new Capsule(
|
|
503
|
-
this.#words,
|
|
504
|
-
ARGV_CHANNEL,
|
|
505
|
-
HostDetect.detect(process.env),
|
|
506
|
-
scene.workspace.root.repoRoot,
|
|
507
|
-
),
|
|
508
|
-
planPath: scene.planPath,
|
|
509
|
-
});
|
|
510
|
-
|
|
511
|
-
// The requested-phase gate — the line faces (branch/spec/plan) keep the
|
|
512
|
-
// line-phase readiness check; the task face needs no second gate (the WaveGate's
|
|
513
|
-
// wrong-phase verdict above IS the phase authority for the requested wave).
|
|
514
|
-
if (group === null) {
|
|
515
|
-
const { phase: open, verdict, reviewed } = this.#gate.lineGate(scene);
|
|
516
|
-
if (open !== expected) {
|
|
517
|
-
const pendingBlock =
|
|
518
|
-
verdict === "pending-fix" ? this.#gate.pendingFixBlock(scene, reviewed) : null;
|
|
519
|
-
const docBlock = open === null ? this.#gate.docLineBlock(scene, reviewed) : null;
|
|
520
|
-
this.#io.stderr(
|
|
521
|
-
`cdd ${verb}: cannot dispatch a ${expected} round — ${pendingBlock ?? docBlock ?? (open === null ? "the line holds no open round" : `the next round is ${open}${this.#phaseHint(open)}`)}\n`,
|
|
522
|
-
);
|
|
523
|
-
return 1;
|
|
524
|
-
}
|
|
525
|
-
}
|
|
526
|
-
|
|
527
|
-
// Advance the requested phase across the wave (one dispatch per frame — the
|
|
528
|
-
// lifecycle's "one dispatch, one advance" step), keeping only the LAST step's
|
|
529
|
-
// capsule for the invocation's single stdout face (the per-step intermediate
|
|
530
|
-
// next-wave lines stay in the router, never on the CLI face). The loop PEEKS
|
|
531
|
-
// before every advance: advance() dispatches on entry, so an expected-phase
|
|
532
|
-
// mismatch must be judged against the next frame BEFORE it spends the round —
|
|
533
|
-
// the {16,22,24} bug's lookahead-after-dispatch consumed the next wave's round
|
|
534
|
-
// in the same invocation (implement 1 silently closed wave 1's review round).
|
|
535
|
-
let dispatched = 0;
|
|
536
|
-
let latest: readonly string[] = [];
|
|
537
|
-
let lastStatus: RoundStatus | null = null;
|
|
538
|
-
for (;;) {
|
|
539
|
-
const frame = run.peekNext();
|
|
540
|
-
if (frame === null) break;
|
|
541
|
-
const waveTasks = frame.target.kind === "wave" ? frame.target.tasks : null;
|
|
542
|
-
const mismatch =
|
|
543
|
-
frame.phase !== expected ||
|
|
544
|
-
(group !== null && (waveTasks === null || !waveTasks.every((id) => group!.has(id))));
|
|
545
|
-
if (mismatch) {
|
|
546
|
-
if (dispatched === 0) {
|
|
547
|
-
this.#io.stderr(
|
|
548
|
-
`cdd ${verb}: cannot dispatch a ${expected} round — the next round is ${frame.phase}${waveTasks !== null ? ` for wave ${waveTasks.join(",")}` : ""}${this.#phaseHint(frame.phase)}\n`,
|
|
549
|
-
);
|
|
550
|
-
return 1;
|
|
551
|
-
}
|
|
552
|
-
break;
|
|
553
|
-
}
|
|
554
|
-
const step = run.advance();
|
|
555
|
-
if (step === null) break;
|
|
556
|
-
// The dispatch-entry gate's refusal (the lifecycle's hard child zero-dispatch wiring —
|
|
557
|
-
// structurally unreachable here: the seam already returned above on refusal).
|
|
558
|
-
if (step.preflight !== undefined) {
|
|
559
|
-
this.#renderPreflightBlocked(verb, step.preflight, scene);
|
|
560
|
-
return 1;
|
|
561
|
-
}
|
|
562
|
-
dispatched += 1;
|
|
563
|
-
latest = step.capsuleLines;
|
|
564
|
-
lastStatus = statuses[statuses.length - 1] ?? null;
|
|
565
|
-
// NO manual done-marking here: the lifecycle's markTerminal is the single
|
|
566
|
-
// closure gate (C5) — a dispatched wave advances the frontier only through
|
|
567
|
-
// its concluded round's route. The old dispatch-then-markDone shortcut drove
|
|
568
|
-
// the loop across waves without a closure verdict: after implement of wave 1
|
|
569
|
-
// it marked wave 1 done, so the loop dispatched wave 2 in the same call
|
|
570
|
-
// (dry-run) and rendered every mid-run closure as `next: done` (the per-step
|
|
571
|
-
// next was already consumed). The ledger-mirrored cursor above + markTerminal
|
|
572
|
-
// together keep one wave phase per invocation.
|
|
573
|
-
if (lastStatus === "BLOCKED" || lastStatus === "TIMEOUT") {
|
|
574
|
-
for (const line of latest) this.#io.stdout(`${line}\n`);
|
|
575
|
-
return 1;
|
|
576
|
-
}
|
|
577
|
-
// The no-next hard error (v1.20): a completed non-failed round must produce a
|
|
578
|
-
// `next:` line — null after a passed BLOCKED/TIMEOUT check is an abnormal
|
|
579
|
-
// completion, never a silent approved-without-next.
|
|
580
|
-
if (step.route === null) {
|
|
581
|
-
for (const line of latest) this.#io.stdout(`${line}\n`);
|
|
582
|
-
this.#io.stderr(
|
|
583
|
-
`${this.#words.station("blocked")} the round concluded ${lastStatus ?? "APPROVED"} with no next: line — a completed non-failed round must yield a next-hop route (re-run the same command to continue)\n`,
|
|
584
|
-
);
|
|
585
|
-
return 1;
|
|
586
|
-
}
|
|
587
|
-
}
|
|
588
|
-
if (dispatched === 0) {
|
|
589
|
-
this.#io.stderr(`cdd ${verb}: nothing to dispatch — the line holds no open frame\n`);
|
|
590
|
-
return 1;
|
|
591
|
-
}
|
|
592
|
-
for (const line of latest) this.#io.stdout(`${line}\n`);
|
|
593
|
-
return 0;
|
|
594
|
-
}
|
|
595
|
-
|
|
596
|
-
/** The dispatch seam — the injected override, else the dry-run synthetic approval,
|
|
597
|
-
* else the harness production default. */
|
|
598
|
-
#dispatchOf(scene: WorkScene, parsed: RunInput): DispatchStep {
|
|
599
|
-
if (this.#dispatch !== null) return this.#dispatch;
|
|
600
|
-
if (parsed.dryRun || this.#dryRun) {
|
|
601
|
-
return () => ({ status: "APPROVED", findings: [] });
|
|
602
|
-
}
|
|
603
|
-
const harness = new CliLifecycle({
|
|
604
|
-
env: process.env,
|
|
605
|
-
cwd: this.#cwd,
|
|
606
|
-
sync: this.#sync,
|
|
607
|
-
config: this.#config,
|
|
608
|
-
template: this.#template,
|
|
609
|
-
io: this.#io,
|
|
610
|
-
scene: {
|
|
611
|
-
workspace: scene.workspace,
|
|
612
|
-
ledger: scene.ledger,
|
|
613
|
-
planPath: scene.planPath,
|
|
614
|
-
briefPath: scene.briefPath,
|
|
615
|
-
baseBranch: this.#baseBranchOf(scene),
|
|
616
|
-
},
|
|
617
|
-
findings: parsed.args.findings ?? null,
|
|
618
|
-
});
|
|
619
|
-
return harness.step();
|
|
620
|
-
}
|
|
621
|
-
|
|
622
|
-
/** The branch scope anchor (BASE_BRANCH) — the base artifact's branch name read
|
|
623
|
-
* from the line's own workspace (`base.json`, the same `base get` source the CLI
|
|
624
|
-
* writes). "" when the artifact is absent or malformed (the slot stays empty and
|
|
625
|
-
* the assembler drops it — the wave/branch review then judges the live tree). */
|
|
626
|
-
#baseBranchOf(scene: WorkScene): string {
|
|
627
|
-
const read = scene.workspace.readJson<{ base?: unknown }>("base.json");
|
|
628
|
-
const artifact = read.kind === "ok" ? read.value : null;
|
|
629
|
-
return typeof artifact?.base === "string" ? artifact.base : "";
|
|
630
|
-
}
|
|
631
|
-
|
|
632
|
-
/** The phase-mismatch hint — what to run instead. */
|
|
633
|
-
#phaseHint(phase: string): string {
|
|
634
|
-
switch (phase) {
|
|
635
|
-
case "implement":
|
|
636
|
-
return " — run cdd implement first";
|
|
637
|
-
case "review":
|
|
638
|
-
case "branch-review":
|
|
639
|
-
return " — run cdd review first";
|
|
640
|
-
default:
|
|
641
|
-
return " — run cdd fix first";
|
|
642
|
-
}
|
|
643
|
-
}
|
|
644
|
-
|
|
645
|
-
/** Render a refused pre-flight verdict — the work command's BLOCK face (P4.1 T1).
|
|
646
|
-
* The dirty-tree / doc-contract refusals ride the CDD_BLOCKED channel (the
|
|
647
|
-
* commit/discard guidance + the named structural findings); the graph / wave
|
|
648
|
-
* refusals keep the pre-existing refusal face (the wave-board hint renders for the
|
|
649
|
-
* wave gate's split row — its done face rides the SAME closedWaves() read the gate
|
|
650
|
-
* judged, one closed set, one source). */
|
|
651
|
-
#renderPreflightBlocked(verb: CliVerb, verdict: PreFlightVerdict, scene: WorkScene): void {
|
|
652
|
-
if (verdict.gate === "tree-clean" || verdict.gate === "doc-contract") {
|
|
653
|
-
this.#io.stderr(`${this.#words.station("blocked")} ${verdict.message ?? ""}\n`);
|
|
654
|
-
for (const detail of verdict.details ?? []) this.#io.stderr(` ${detail}\n`);
|
|
655
|
-
return;
|
|
656
|
-
}
|
|
657
|
-
this.#io.stderr(`cdd ${verb}: ${verdict.message ?? "the dispatch gate refused the request"}\n`);
|
|
658
|
-
for (const detail of verdict.details ?? []) this.#io.stderr(` ${detail}\n`);
|
|
659
|
-
if (verdict.gate === "wave" && verdict.reason === "split" && scene.planText !== null) {
|
|
660
|
-
const graph = new TaskGraph(new PlanDocType("plan").parse(scene.planText.split("\n")));
|
|
661
|
-
const closed = scene.ledger.closedWaves();
|
|
662
|
-
for (const line of this.#graphView
|
|
663
|
-
.render(graph.report(closed), `graph: ${scene.planPath ?? ""}`)
|
|
664
|
-
.split("\n"))
|
|
665
|
-
this.#io.stderr(` ${line}\n`);
|
|
666
|
-
}
|
|
667
|
-
}
|
|
668
|
-
|
|
669
|
-
// ---------------------------------------------------------------------------
|
|
670
|
-
// the work scene — the composition of contract/session/face objects
|
|
671
|
-
// ---------------------------------------------------------------------------
|
|
672
|
-
|
|
673
|
-
/** Assemble one work command's scene: the workspace (repo root + the plan/spec
|
|
674
|
-
* slug), the ledger, the run state (TaskGraph from the plan parse for the task
|
|
675
|
-
* face, the empty single-target state otherwise), the fixed target. */
|
|
676
|
-
async #sceneOf(
|
|
677
|
-
verb: CliVerb,
|
|
678
|
-
type: TargetType,
|
|
679
|
-
node: Command,
|
|
680
|
-
parsed: RunInput,
|
|
681
|
-
): Promise<WorkScene> {
|
|
682
|
-
const config = this.#config;
|
|
683
|
-
const face = targetFaces[type];
|
|
684
|
-
const repoRoot = await this.#repoRootOf(parsed);
|
|
685
|
-
const root = new WorkspaceRoot(repoRoot, config.handoffNamespace().workspaceRoot);
|
|
686
|
-
const planPath = parsed.args.plan ?? null;
|
|
687
|
-
const specPath = parsed.args.spec ?? null;
|
|
688
|
-
|
|
689
|
-
let slug: string;
|
|
690
|
-
let planText: string | null = null;
|
|
691
|
-
let target: WorkScene["target"] = null;
|
|
692
|
-
switch (type) {
|
|
693
|
-
case "wave": {
|
|
694
|
-
if (planPath === null)
|
|
695
|
-
this.#usage(node, `cdd ${verb} --type wave: missing required --plan <path>`);
|
|
696
|
-
slug = Workspace.slugFromDoc(planPath);
|
|
697
|
-
planText = this.#artifacts.readText(node, planPath);
|
|
698
|
-
break;
|
|
699
|
-
}
|
|
700
|
-
case "spec": {
|
|
701
|
-
if (specPath === null)
|
|
702
|
-
this.#usage(node, `cdd ${verb} --type spec: missing required --spec <path>`);
|
|
703
|
-
slug = Workspace.slugFromDoc(specPath);
|
|
704
|
-
target = { kind: "doc", doc: specPath };
|
|
705
|
-
break;
|
|
706
|
-
}
|
|
707
|
-
case "plan": {
|
|
708
|
-
if (planPath === null)
|
|
709
|
-
this.#usage(node, `cdd ${verb} --type plan: missing required --plan <path>`);
|
|
710
|
-
slug = Workspace.slugFromDoc(planPath);
|
|
711
|
-
planText = this.#artifacts.readText(node, planPath);
|
|
712
|
-
target = { kind: "doc", doc: planPath };
|
|
713
|
-
break;
|
|
714
|
-
}
|
|
715
|
-
case "branch": {
|
|
716
|
-
// The branch line carries no commit identity: the audit target is the
|
|
717
|
-
// branch itself, its workspace identity is the plan path (a required
|
|
718
|
-
// fact — the branch review/fix faces carry `--plan`), and the review's
|
|
719
|
-
// scope anchor (BASE_BRANCH) is engine-injected from the base artifact.
|
|
720
|
-
if (planPath === null)
|
|
721
|
-
this.#usage(node, `cdd ${verb} --type branch: missing required --plan <path>`);
|
|
722
|
-
slug = Workspace.slugFromDoc(planPath);
|
|
723
|
-
target = { kind: "branch" };
|
|
724
|
-
break;
|
|
725
|
-
}
|
|
726
|
-
}
|
|
727
|
-
|
|
728
|
-
const workspace = new Workspace(root, slug).ensure();
|
|
729
|
-
const ledger = new Ledger(workspace, config);
|
|
730
|
-
const state =
|
|
731
|
-
type === "wave"
|
|
732
|
-
? new TaskGraph(new PlanDocType("plan").parse(planText!.split("\n")))
|
|
733
|
-
: EMPTY_RUN_STATE;
|
|
734
|
-
return {
|
|
735
|
-
workspace,
|
|
736
|
-
ledger,
|
|
737
|
-
planPath,
|
|
738
|
-
planText,
|
|
739
|
-
type,
|
|
740
|
-
face,
|
|
741
|
-
target,
|
|
742
|
-
state,
|
|
743
|
-
router: new NextStepRouter(),
|
|
744
|
-
briefPath: null,
|
|
745
|
-
};
|
|
746
|
-
}
|
|
747
|
-
|
|
748
|
-
/** The repo root — the --root override, else the injected root, else the git top
|
|
749
|
-
* level, else the cwd. */
|
|
750
|
-
async #repoRootOf(parsed?: RunInput): Promise<string> {
|
|
751
|
-
const override = parsed?.args.root;
|
|
752
|
-
return override ?? this.#repoRoot ?? (await this.#git.topLevel(this.#cwd)) ?? this.#cwd;
|
|
753
|
-
}
|
|
754
|
-
|
|
755
|
-
// ---------------------------------------------------------------------------
|
|
756
|
-
// the pure commands — schema / issue / base
|
|
757
|
-
// ---------------------------------------------------------------------------
|
|
758
|
-
|
|
759
|
-
/** `cdd schema get <type> [--output json|skeleton] [<target>]` — the merged D19
|
|
760
|
-
* single leaf: the json render face (the default — the derived doc-structure
|
|
761
|
-
* schema JSON to stdout, no target) and the skeleton render face (`--output
|
|
762
|
-
* skeleton` — the derived doc skeleton written DIRECTLY into the target
|
|
763
|
-
* document, the target required). The type vocabulary = the one shared
|
|
764
|
-
* schema-type table (`SCHEMA_TYPE_KEYS` in face/declare.ts: the primary DocKey
|
|
765
|
-
* spellings + the legacy alias normalized to kebab, spec §5.3). */
|
|
766
|
-
async #runSchema(node: Command, parsed: RunInput): Promise<number> {
|
|
767
|
-
const [type, target] = parsed.positionals;
|
|
768
|
-
if (type === undefined) this.#usage(node, "cdd schema get: missing <type>");
|
|
769
|
-
const output = parsed.args.output ?? "json";
|
|
770
|
-
if (output === "skeleton") {
|
|
771
|
-
// The skeleton render face — the engine-declared target (D19): the authoring
|
|
772
|
-
// scaffold lands in the target document, zero shell-redirection indirection.
|
|
773
|
-
if (target === undefined) {
|
|
774
|
-
this.#usage(node, "cdd schema get --output skeleton: missing <target>");
|
|
775
|
-
}
|
|
776
|
-
return this.#artifacts.runSchemaSkeleton(node, type, target);
|
|
777
|
-
}
|
|
778
|
-
if (target !== undefined) {
|
|
779
|
-
this.#usage(
|
|
780
|
-
node,
|
|
781
|
-
"cdd schema get: unexpected <target> — the json render takes no target (use --output skeleton <target> to render the scaffold into a document)",
|
|
782
|
-
);
|
|
783
|
-
}
|
|
784
|
-
this.#io.stdout(`${JSON.stringify(this.#projector.schema()[type as DocKey], null, 2)}\n`);
|
|
785
|
-
return 0;
|
|
786
|
-
}
|
|
787
|
-
|
|
788
|
-
/** `cdd base <set|get> --plan <path>` — the base artifact read/write (T20: the
|
|
789
|
-
* command face `base`; the artifact file carries the base face too). */
|
|
790
|
-
async #runBase(node: Command, parsed: RunInput): Promise<number> {
|
|
791
|
-
const planPath = parsed.args.plan;
|
|
792
|
-
if (planPath === undefined) {
|
|
793
|
-
this.#usage(node, "cdd base: missing --plan — the sole target is --plan <path>");
|
|
794
|
-
}
|
|
795
|
-
const workspace = new Workspace(
|
|
796
|
-
new WorkspaceRoot(
|
|
797
|
-
await this.#repoRootOf(parsed),
|
|
798
|
-
this.#config.handoffNamespace().workspaceRoot,
|
|
799
|
-
),
|
|
800
|
-
Workspace.slugFromDoc(planPath),
|
|
801
|
-
).ensure();
|
|
802
|
-
const path = workspace.resolve("base.json");
|
|
803
|
-
if (parsed.leaf === "set") return this.#artifacts.baseSet(node, parsed, planPath, path);
|
|
804
|
-
if (parsed.leaf === "get") return this.#artifacts.baseGet(path);
|
|
805
|
-
this.#usage(node, "cdd base: missing <set|get> subcommand");
|
|
806
|
-
}
|
|
807
|
-
|
|
808
|
-
/**
|
|
809
|
-
* Cli.create(opts?) — the composition root's static factory: wires the engine's
|
|
810
|
-
* object graph (contract: the projector over the declared registries · session: the
|
|
811
|
-
* ledger + lifecycle + task graph + next router · face: the words + capsule ·
|
|
812
|
-
* infra: the config loader + git + the sync process seam) into the ONE Cli the bin
|
|
813
|
-
* thin entry boots. Every collaborator is overridable for the hermetic test face
|
|
814
|
-
* (io / dispatch / repoRoot); the defaults bind the living process.
|
|
815
|
-
*/
|
|
816
|
-
static create(opts: CliOptions = {}): Cli {
|
|
817
|
-
return new Cli(opts);
|
|
818
|
-
}
|
|
819
|
-
}
|