@oscaner-skills/cdd-engine 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/package.json +4 -3
  4. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  5. package/src-next/__tests__/floor.guard.test.ts +69 -0
  6. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  7. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  8. package/src-next/__tests__/smoke.integration.test.ts +60 -77
  9. package/src-next/__tests__/support/strip-comments.ts +99 -0
  10. package/src-next/__tests__/zero-dep.test.ts +6 -46
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
  12. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
  16. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
  19. package/src-next/contract/__tests__/declare.test.ts +251 -12
  20. package/src-next/contract/__tests__/doc.test.ts +214 -45
  21. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  22. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  23. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  24. package/src-next/contract/__tests__/judge.test.ts +410 -172
  25. package/src-next/contract/__tests__/lint.test.ts +49 -39
  26. package/src-next/contract/__tests__/project.test.ts +60 -19
  27. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  28. package/src-next/contract/declare.ts +179 -91
  29. package/src-next/contract/doc.ts +227 -164
  30. package/src-next/contract/frontmatter.ts +233 -0
  31. package/src-next/contract/home-extractors.ts +397 -0
  32. package/src-next/contract/invariants.ts +214 -69
  33. package/src-next/contract/judge.ts +28 -19
  34. package/src-next/contract/lint.ts +5 -41
  35. package/src-next/contract/project.ts +103 -43
  36. package/src-next/contract/skill-anatomy.ts +39 -11
  37. package/src-next/face/__tests__/board-view.test.ts +318 -115
  38. package/src-next/face/__tests__/capsule.test.ts +49 -25
  39. package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
  40. package/src-next/face/__tests__/cli.test.ts +1091 -837
  41. package/src-next/face/__tests__/face.test.ts +5 -5
  42. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  43. package/src-next/face/__tests__/preview.test.ts +374 -0
  44. package/src-next/face/__tests__/projection.test.ts +5 -3
  45. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  46. package/src-next/face/__tests__/termination.test.ts +650 -0
  47. package/src-next/face/artifacts.ts +90 -37
  48. package/src-next/face/board-view.ts +128 -138
  49. package/src-next/face/capsule.ts +30 -16
  50. package/src-next/face/cli.ts +306 -97
  51. package/src-next/face/declare.ts +15 -18
  52. package/src-next/face/gate.ts +19 -18
  53. package/src-next/face/host.ts +6 -30
  54. package/src-next/face/lifecycle.ts +213 -188
  55. package/src-next/face/preview.ts +151 -0
  56. package/src-next/face/projection.ts +4 -1
  57. package/src-next/face/route-render.ts +39 -14
  58. package/src-next/face/termination.ts +573 -0
  59. package/src-next/face/words.ts +20 -2
  60. package/src-next/infra/__tests__/infra.test.ts +49 -3
  61. package/src-next/infra/__tests__/root.test.ts +56 -0
  62. package/src-next/infra/doc-roots.ts +29 -0
  63. package/src-next/infra/root.ts +73 -0
  64. package/src-next/infra/runtime.ts +12 -65
  65. package/src-next/infra/workspace.ts +95 -5
  66. package/src-next/render/__tests__/render.test.ts +92 -41
  67. package/src-next/render/__tests__/skeleton.test.ts +282 -64
  68. package/src-next/render/issue-body.ts +5 -2
  69. package/src-next/render/skeleton.ts +155 -90
  70. package/src-next/render/templates.ts +51 -56
  71. package/src-next/session/__tests__/graph.test.ts +11 -4
  72. package/src-next/session/__tests__/ledger.test.ts +3 -2
  73. package/src-next/session/__tests__/next.test.ts +100 -8
  74. package/src-next/session/__tests__/preflight.test.ts +79 -25
  75. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  76. package/src-next/session/__tests__/run.test.ts +140 -128
  77. package/src-next/session/__tests__/wave.test.ts +11 -4
  78. package/src-next/session/ledger.ts +96 -24
  79. package/src-next/session/next.ts +116 -15
  80. package/src-next/session/preflight.ts +41 -10
  81. package/src-next/session/round-naming.ts +84 -0
  82. package/src-next/session/run.ts +24 -20
  83. package/templates/report/issue-body.json +0 -46
  84. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
@@ -16,22 +16,40 @@ import type { Command } from "commander";
16
16
  import { declaredRegistries } from "../contract/declare.ts";
17
17
  import type { DocKey } from "../contract/project.ts";
18
18
  import { Projector } from "../contract/project.ts";
19
+ import type { RepoPath, RepoRoot } from "../infra/root.ts";
20
+ import type { Workspace } from "../infra/workspace.ts";
19
21
  import type { IssueBodyRenderer, IssueReportInput } from "../render/issue-body.ts";
20
22
  import { SkeletonAssembler } from "../render/skeleton.ts";
21
23
  import type { RunInput } from "./cli.ts";
24
+ import { ARGV_CHANNEL } from "./declare.ts";
22
25
  import type { CliIo } from "./lifecycle.ts";
23
26
 
24
27
  // ---------------------------------------------------------------------------
25
28
  // the pure artifact surfaces — the base artifact + the issue body
26
29
  // ---------------------------------------------------------------------------
27
30
 
31
+ /** The base's source value domain — the four-value enum (design spec §3.2 ⑪).
32
+ * Derived from the ONE declaration (the argv channel's `--source` domain,
33
+ * face/declare.ts:76), so the artifact's `source` field and the CLI's accepted
34
+ * values can never drift. */
35
+ export type BaseSource = (typeof ARGV_CHANNEL.source.values)[number];
36
+
37
+ /** The base artifact's declared field set, in canonical order — the runtime
38
+ * companion of `BaseArtifact` (the `base.md` documented schema's four fields,
39
+ * spec §3.2 ⑪). The cross-face gate (kairos suite) pins the `base.md` schema
40
+ * table's field set to THIS tuple, so the doc and the artifact can never drift. */
41
+ export const BASE_ARTIFACT_FIELDS = ["base", "source", "plan", "recordedAt"] as const;
42
+
28
43
  /** The base artifact schema — the sole CDD --plan target's read/write row (the
29
- * artifact file carries the `base` face: the base branch the plan's line rides). */
44
+ * artifact file carries the `base` face: the base branch the plan's line rides).
45
+ * The field set (`base`/`source`/`plan`/`recordedAt`) mirrors the `base.md`
46
+ * documented schema (spec §3.2 ⑪); `source` is narrowed to the declared enum
47
+ * `BaseSource` — never a bare `string` (the drifted face this gate closes). */
30
48
  export interface BaseArtifact {
31
49
  /** The base branch name. */
32
50
  base: string;
33
- /** The base's source channel (the engine-config source enum). */
34
- source: string;
51
+ /** The base's source channel (the declared `--source` enum). */
52
+ source: BaseSource;
35
53
  /** The plan path the artifact serves. */
36
54
  plan: string;
37
55
  /** The ISO write timestamp. */
@@ -77,14 +95,17 @@ export class CliArtifacts {
77
95
  * (the assembler never appends one — the written doc ends with exactly one
78
96
  * `\n`). The target is the engine-declared parameter of the skeleton render
79
97
  * face — the authoring scaffold lands in place, zero shell-redirection
80
- * indirection (the D19 `<path>` zero-constraint fix). The written path prints
81
- * to stdout. */
82
- runSchemaSkeleton(node: Command, type: string, target: string): number {
98
+ * indirection (the D19 `<path>` zero-constraint fix). The echoed path is the
99
+ * repoRoot-relative shape (D47 · §2.13: the branded `RepoPath` param on both the
100
+ * stdout line and the failure byte; `RepoRoot.resolve` feeds only the writeFileSync
101
+ * syscall). */
102
+ runSchemaSkeleton(node: Command, root: RepoRoot, type: string, target: RepoPath): number {
83
103
  const projection = this.#projector.skeleton()[type as DocKey];
84
104
  const date = this.#today();
85
105
  const file = `${new SkeletonAssembler(projection, date).render()}\n`;
106
+ const absolute = root.resolve(target);
86
107
  try {
87
- writeFileSync(target, file, "utf8");
108
+ writeFileSync(absolute, file, "utf8");
88
109
  } catch {
89
110
  this.#usage(node, `cannot write file: ${target}`);
90
111
  }
@@ -116,36 +137,54 @@ export class CliArtifacts {
116
137
  }
117
138
 
118
139
  /** The `set` body — base/source required, a different existing base refuses without
119
- * --force (the write-through artifact single-author). */
120
- baseSet(node: Command, parsed: RunInput, planPath: string, path: string): number {
140
+ * `--force` (the write-through artifact single-author). The write rides
141
+ * `Workspace.writeJson` (P11 · §4.2: the JSON write self-ensures, so `base set` on
142
+ * a fresh repo builds the workspace with no scene-side ensure); the read rides the
143
+ * same `Workspace.readJson` normalization path. The echoed path is the
144
+ * repoRoot-relative shape (D47 · the ONE basis), normalized through the threaded
145
+ * basis (F2). */
146
+ baseSet(
147
+ node: Command,
148
+ parsed: RunInput,
149
+ planPath: RepoPath,
150
+ workspace: Workspace,
151
+ root: RepoRoot,
152
+ ): number {
121
153
  const base = parsed.args.base;
122
154
  const source = parsed.args.source;
123
155
  if (base === undefined || source === undefined) {
124
156
  this.#usage(node, "cdd base set: required --base <branch> and --source <source>");
125
157
  }
126
- const existing = this.#readBase(path);
158
+ const existing = this.#readBase(workspace);
127
159
  if (existing !== null && existing.base !== base && parsed.args.force !== "true") {
128
160
  this.#usage(
129
161
  node,
130
162
  `cdd base set: base already set to ${existing.base} — pass --force to override`,
131
163
  );
132
164
  }
165
+ // The `--source` enum channel already validated the raw against the declared
166
+ // domain, so the value is narrowed to BaseSource here (single source: the
167
+ // channel's `values` array).
133
168
  const artifact: BaseArtifact = {
134
169
  base,
135
- source,
170
+ source: source as BaseSource,
136
171
  plan: planPath,
137
172
  recordedAt: new Date().toISOString(),
138
173
  };
139
- writeFileSync(path, `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
140
- this.#io.stdout(`${path}\n`);
174
+ workspace.writeJson("base.json", artifact);
175
+ this.#io.stdout(`${root.relativize(workspace.resolve("base.json"))}\n`);
141
176
  return 0;
142
177
  }
143
178
 
144
179
  /** The `get` body — read + validate + print the artifact JSON (exit 2 when the
145
- * artifact is missing or corrupt — the orchestrator's inference-chain input). */
146
- baseGet(path: string): number {
147
- const artifact = this.#readBase(path);
180
+ * artifact is missing or corrupt — the orchestrator's inference-chain input). A
181
+ * pure READ (P11 · §4.2): the workspace is never built here, so `cdd base get`
182
+ * leaves `.kairos/` absent on a fresh repo. The echoed path is the repoRoot-relative
183
+ * shape (D47), normalized through the threaded basis (F2). */
184
+ baseGet(workspace: Workspace, root: RepoRoot): number {
185
+ const artifact = this.#readBase(workspace);
148
186
  if (artifact === null) {
187
+ const path = root.relativize(workspace.resolve("base.json"));
149
188
  this.#io.stderr(`cdd base get: missing or corrupt base artifact at ${path}\n`);
150
189
  return 2;
151
190
  }
@@ -154,10 +193,16 @@ export class CliArtifacts {
154
193
  }
155
194
 
156
195
  /** Read a text file through the caller's command face; a missing/unreadable file is
157
- * the usage error of that face (the owning node's commander-native usage line). */
158
- readText(node: Command, file: string): string {
196
+ * the usage error of that face (the owning node's commander-native usage line). The
197
+ * path is a branded `RepoPath` (repoRoot-relative — T3 §2.3: a bare `string` never
198
+ * reaches this read) erased to the absolute syscall form through the ONE value
199
+ * object (`RepoRoot.resolve`), so the read reads the file the funnel named. The
200
+ * echoed path in the refusal byte is the repoRoot-relative shape (D47 · §2.13: the
201
+ * branded `RepoPath`; `RepoRoot.resolve` feeds only the readFileSync syscall). */
202
+ readText(node: Command, root: RepoRoot, file: RepoPath): string {
203
+ const absolute = root.resolve(file);
159
204
  try {
160
- return readFileSync(file, "utf8");
205
+ return readFileSync(absolute, "utf8");
161
206
  } catch {
162
207
  this.#usage(node, `cannot read file: ${file}`);
163
208
  }
@@ -172,24 +217,32 @@ export class CliArtifacts {
172
217
  return `${now.getFullYear()}-${month}-${day}`;
173
218
  }
174
219
 
175
- /** Read + validate the base artifact; null when missing or malformed. */
176
- #readBase(path: string): BaseArtifact | null {
177
- try {
178
- const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
179
- if (
180
- typeof parsed.base !== "string" ||
181
- typeof parsed.source !== "string" ||
182
- typeof parsed.plan !== "string"
183
- )
184
- return null;
185
- return {
186
- base: parsed.base,
187
- source: parsed.source,
188
- plan: parsed.plan,
189
- recordedAt: typeof parsed.recordedAt === "string" ? parsed.recordedAt : "",
190
- };
191
- } catch {
220
+ /** Read + validate the base artifact; null when missing or malformed — a total
221
+ * read (never a throw). The read rides `Workspace.readJson` (P11 · §4.2) — the
222
+ * read/write single normalization path, so a legacy absolute `plan` field reads
223
+ * back in the canonical repoRoot-relative shape (the retired migration's job is the
224
+ * read-time backstop). A non-object JSON payload (the literal `null`, a bare
225
+ * scalar/array) is malformed input, not a base artifact. The `source` field is
226
+ * narrowed to the declared enum domain (a value outside the four-value set is a
227
+ * schema-invalid artifact → null, never a fabricated source). */
228
+ #readBase(workspace: Workspace): BaseArtifact | null {
229
+ const read = workspace.readJson<unknown>("base.json");
230
+ if (read.kind !== "ok") return null;
231
+ const parsed = read.value;
232
+ if (parsed === null || typeof parsed !== "object") return null;
233
+ const record = parsed as Record<string, unknown>;
234
+ if (
235
+ typeof record.base !== "string" ||
236
+ typeof record.source !== "string" ||
237
+ typeof record.plan !== "string"
238
+ )
192
239
  return null;
193
- }
240
+ if (!(ARGV_CHANNEL.source.values as readonly string[]).includes(record.source)) return null;
241
+ return {
242
+ base: record.base,
243
+ source: record.source as BaseSource,
244
+ plan: record.plan,
245
+ recordedAt: typeof record.recordedAt === "string" ? record.recordedAt : "",
246
+ };
194
247
  }
195
248
  }