@oscaner-skills/cdd-engine 3.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.
Files changed (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +141 -0
  15. package/dist/face/cli.js +891 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +603 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +482 -0
  25. package/dist/face/words.js +220 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +441 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -0,0 +1,189 @@
1
+ // packages/cdd-engine/src-next/face/artifacts.ts
2
+ // T8 — the split contract's artifacts face (§6.2: face/artifacts.ts — the pure-command
3
+ // domain). The pure artifact surfaces run through this class: the schema skeleton
4
+ // (#runSchemaSkeleton/#today), the issue render (#runIssue) and the base artifact
5
+ // read/write (#baseSet/#baseGet/#readBase) plus the doc read/usage face (#readText).
6
+ // The method bodies are the pre-split Cli members moved verbatim — behavior bytes
7
+ // identical; the root Cli holds the artifacts instance and composes through it via its
8
+ // .action thin shells. The root's commander usage throw (#usage — the composition-
9
+ // root exit face, never re-implemented here) is injected as the usage seam; the BaseArtifact
10
+ // row (the CDD --plan target's read/write face) is declared here and re-exported by
11
+ // face/cli.ts so the public surface never drifts.
12
+ import { readFileSync, writeFileSync } from "node:fs";
13
+ import process from "node:process";
14
+ import { declaredRegistries } from "../contract/declare.js";
15
+ import { Projector } from "../contract/project.js";
16
+ import { SkeletonAssembler } from "../render/skeleton.js";
17
+ import { ARGV_CHANNEL } from "./declare.js";
18
+ /** The base artifact's declared field set, in canonical order — the runtime
19
+ * companion of `BaseArtifact` (the `base.md` documented schema's four fields,
20
+ * spec §3.2 ⑪). The cross-face gate (kairos suite) pins the `base.md` schema
21
+ * table's field set to THIS tuple, so the doc and the artifact can never drift. */
22
+ export const BASE_ARTIFACT_FIELDS = ["base", "source", "plan", "recordedAt"];
23
+ /**
24
+ * CliArtifacts — the pure-command domain (the split contract's artifacts face): the
25
+ * schema/issue/base run bodies. The instance holds the pure-domain renderers + the
26
+ * root-injected seam faces (io / the usage throw); the root composes the command
27
+ * scenes and delegates the pure runs here.
28
+ */
29
+ export class CliArtifacts {
30
+ #io;
31
+ #projector;
32
+ #issue;
33
+ #stdinRead;
34
+ /** The composition-root usage throw — commander's OWN CommanderError (the root's
35
+ * exit-normalization face; the split never re-implements the usage byte). */
36
+ #usage;
37
+ constructor(opts) {
38
+ this.#io = opts.io ?? {
39
+ stdout: (t) => process.stdout.write(t),
40
+ stderr: (t) => process.stderr.write(t),
41
+ };
42
+ this.#projector = opts.projector ?? new Projector(declaredRegistries);
43
+ this.#issue = opts.issue;
44
+ this.#stdinRead = opts.stdinRead;
45
+ this.#usage = opts.usage;
46
+ }
47
+ /** `cdd schema get <type> --output skeleton <target>` — the derived doc skeleton
48
+ * rendered DIRECTLY into the target document (the D19 merged leaf's skeleton
49
+ * face): the normalized DocType key → the projector's skeleton projection → the
50
+ * SkeletonAssembler bytes → the single appended newline written to <target>
51
+ * (the assembler never appends one — the written doc ends with exactly one
52
+ * `\n`). The target is the engine-declared parameter of the skeleton render
53
+ * face — the authoring scaffold lands in place, zero shell-redirection
54
+ * indirection (the D19 `<path>` zero-constraint fix). The echoed path is the
55
+ * repoRoot-relative shape (D47 · §2.13: the branded `RepoPath` param on both the
56
+ * stdout line and the failure byte; `RepoRoot.resolve` feeds only the writeFileSync
57
+ * syscall). */
58
+ runSchemaSkeleton(node, root, type, target) {
59
+ const projection = this.#projector.skeleton()[type];
60
+ const date = this.#today();
61
+ const file = `${new SkeletonAssembler(projection, date).render()}\n`;
62
+ const absolute = root.resolve(target);
63
+ try {
64
+ writeFileSync(absolute, file, "utf8");
65
+ }
66
+ catch {
67
+ this.#usage(node, `cannot write file: ${target}`);
68
+ }
69
+ this.#io.stdout(`${target}\n`);
70
+ return 0;
71
+ }
72
+ /** `cdd issue render` — stdin findings JSON → the aggregate body → stdout (the
73
+ * renderer's only CLI entry; a bare call, no flags). */
74
+ runIssue() {
75
+ let input;
76
+ try {
77
+ input = JSON.parse(this.#stdinRead());
78
+ }
79
+ catch (err) {
80
+ this.#io.stderr(`cdd issue render: invalid input JSON — ${err instanceof Error ? err.message : String(err)}\n`);
81
+ return 1;
82
+ }
83
+ const violations = this.#issue.validateInput(input);
84
+ if (violations.length > 0) {
85
+ this.#io.stderr(`cdd issue render: invalid input:\n${violations.map((v) => ` ${v}`).join("\n")}\n`);
86
+ return 1;
87
+ }
88
+ this.#io.stdout(`${this.#issue.renderBody(input)}\n`);
89
+ return 0;
90
+ }
91
+ /** The `set` body — base/source required, a different existing base refuses without
92
+ * `--force` (the write-through artifact single-author). The write rides
93
+ * `Workspace.writeJson` (P11 · §4.2: the JSON write self-ensures, so `base set` on
94
+ * a fresh repo builds the workspace with no scene-side ensure); the read rides the
95
+ * same `Workspace.readJson` normalization path. The echoed path is the
96
+ * repoRoot-relative shape (D47 · the ONE basis), normalized through the threaded
97
+ * basis (F2). */
98
+ baseSet(node, parsed, planPath, workspace, root) {
99
+ const base = parsed.args.base;
100
+ const source = parsed.args.source;
101
+ if (base === undefined || source === undefined) {
102
+ this.#usage(node, "cdd base set: required --base <branch> and --source <source>");
103
+ }
104
+ const existing = this.#readBase(workspace);
105
+ if (existing !== null && existing.base !== base && parsed.args.force !== "true") {
106
+ this.#usage(node, `cdd base set: base already set to ${existing.base} — pass --force to override`);
107
+ }
108
+ // The `--source` enum channel already validated the raw against the declared
109
+ // domain, so the value is narrowed to BaseSource here (single source: the
110
+ // channel's `values` array).
111
+ const artifact = {
112
+ base,
113
+ source: source,
114
+ plan: planPath,
115
+ recordedAt: new Date().toISOString(),
116
+ };
117
+ workspace.writeJson("base.json", artifact);
118
+ this.#io.stdout(`${root.relativize(workspace.resolve("base.json"))}\n`);
119
+ return 0;
120
+ }
121
+ /** The `get` body — read + validate + print the artifact JSON (exit 2 when the
122
+ * artifact is missing or corrupt — the orchestrator's inference-chain input). A
123
+ * pure READ (P11 · §4.2): the workspace is never built here, so `cdd base get`
124
+ * leaves `.kairos/` absent on a fresh repo. The echoed path is the repoRoot-relative
125
+ * shape (D47), normalized through the threaded basis (F2). */
126
+ baseGet(workspace, root) {
127
+ const artifact = this.#readBase(workspace);
128
+ if (artifact === null) {
129
+ const path = root.relativize(workspace.resolve("base.json"));
130
+ this.#io.stderr(`cdd base get: missing or corrupt base artifact at ${path}\n`);
131
+ return 2;
132
+ }
133
+ this.#io.stdout(`${JSON.stringify(artifact, null, 2)}\n`);
134
+ return 0;
135
+ }
136
+ /** Read a text file through the caller's command face; a missing/unreadable file is
137
+ * the usage error of that face (the owning node's commander-native usage line). The
138
+ * path is a branded `RepoPath` (repoRoot-relative — T3 §2.3: a bare `string` never
139
+ * reaches this read) erased to the absolute syscall form through the ONE value
140
+ * object (`RepoRoot.resolve`), so the read reads the file the funnel named. The
141
+ * echoed path in the refusal byte is the repoRoot-relative shape (D47 · §2.13: the
142
+ * branded `RepoPath`; `RepoRoot.resolve` feeds only the readFileSync syscall). */
143
+ readText(node, root, file) {
144
+ const absolute = root.resolve(file);
145
+ try {
146
+ return readFileSync(absolute, "utf8");
147
+ }
148
+ catch {
149
+ this.#usage(node, `cannot read file: ${file}`);
150
+ }
151
+ }
152
+ /** The run date in `YYYY-MM-DD` — the skeleton's version-row date truth (the
153
+ * local day; the skeleton carries no date parameter face). */
154
+ #today() {
155
+ const now = new Date();
156
+ const month = String(now.getMonth() + 1).padStart(2, "0");
157
+ const day = String(now.getDate()).padStart(2, "0");
158
+ return `${now.getFullYear()}-${month}-${day}`;
159
+ }
160
+ /** Read + validate the base artifact; null when missing or malformed — a total
161
+ * read (never a throw). The read rides `Workspace.readJson` (P11 · §4.2) — the
162
+ * read/write single normalization path, so a legacy absolute `plan` field reads
163
+ * back in the canonical repoRoot-relative shape (the retired migration's job is the
164
+ * read-time backstop). A non-object JSON payload (the literal `null`, a bare
165
+ * scalar/array) is malformed input, not a base artifact. The `source` field is
166
+ * narrowed to the declared enum domain (a value outside the four-value set is a
167
+ * schema-invalid artifact → null, never a fabricated source). */
168
+ #readBase(workspace) {
169
+ const read = workspace.readJson("base.json");
170
+ if (read.kind !== "ok")
171
+ return null;
172
+ const parsed = read.value;
173
+ if (parsed === null || typeof parsed !== "object")
174
+ return null;
175
+ const record = parsed;
176
+ if (typeof record.base !== "string" ||
177
+ typeof record.source !== "string" ||
178
+ typeof record.plan !== "string")
179
+ return null;
180
+ if (!ARGV_CHANNEL.source.values.includes(record.source))
181
+ return null;
182
+ return {
183
+ base: record.base,
184
+ source: record.source,
185
+ plan: record.plan,
186
+ recordedAt: typeof record.recordedAt === "string" ? record.recordedAt : "",
187
+ };
188
+ }
189
+ }