@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.
Files changed (127) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/{src-next/bin.ts → dist/bin.js} +18 -21
  4. package/dist/contract/declare.js +998 -0
  5. package/dist/contract/doc.js +565 -0
  6. package/dist/contract/frontmatter.js +209 -0
  7. package/dist/contract/home-extractors.js +379 -0
  8. package/dist/contract/invariants.js +1030 -0
  9. package/dist/contract/judge.js +109 -0
  10. package/dist/contract/lint.js +206 -0
  11. package/dist/contract/project.js +371 -0
  12. package/dist/contract/skill-anatomy.js +156 -0
  13. package/dist/contract/translate.js +85 -0
  14. package/dist/face/artifacts.js +189 -0
  15. package/dist/face/board-view.js +522 -0
  16. package/dist/face/capsule.js +141 -0
  17. package/dist/face/cli.js +891 -0
  18. package/dist/face/declare.js +241 -0
  19. package/dist/face/gate.js +158 -0
  20. package/dist/face/graph-view.js +66 -0
  21. package/dist/face/host.js +211 -0
  22. package/dist/face/lifecycle.js +603 -0
  23. package/dist/face/preview.js +136 -0
  24. package/dist/face/projection.js +259 -0
  25. package/dist/face/route-render.js +162 -0
  26. package/dist/face/termination.js +482 -0
  27. package/dist/face/words.js +220 -0
  28. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  29. package/dist/infra/doc-roots.js +19 -0
  30. package/dist/infra/git.js +37 -0
  31. package/dist/infra/process.js +22 -0
  32. package/dist/infra/root.js +62 -0
  33. package/dist/infra/runtime.js +85 -0
  34. package/dist/infra/workspace.js +276 -0
  35. package/dist/render/brief.js +82 -0
  36. package/dist/render/issue-body.js +129 -0
  37. package/dist/render/skeleton.js +434 -0
  38. package/dist/render/templates.js +520 -0
  39. package/dist/session/faces.js +38 -0
  40. package/dist/session/graph.js +309 -0
  41. package/dist/session/handoff-schema.js +295 -0
  42. package/dist/session/ledger.js +762 -0
  43. package/dist/session/next.js +211 -0
  44. package/dist/session/preflight.js +194 -0
  45. package/dist/session/round-naming.js +73 -0
  46. package/dist/session/run.js +441 -0
  47. package/dist/session/state.js +8 -0
  48. package/dist/session/wave.js +92 -0
  49. package/package.json +8 -7
  50. package/templates/report/issue-body.json +0 -46
  51. package/src-next/__tests__/bin.test.ts +0 -128
  52. package/src-next/__tests__/smoke.integration.test.ts +0 -202
  53. package/src-next/__tests__/zero-dep.test.ts +0 -134
  54. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
  55. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
  58. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
  59. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
  62. package/src-next/contract/__tests__/declare.test.ts +0 -242
  63. package/src-next/contract/__tests__/doc.test.ts +0 -358
  64. package/src-next/contract/__tests__/judge.test.ts +0 -873
  65. package/src-next/contract/__tests__/lint.test.ts +0 -314
  66. package/src-next/contract/__tests__/project.test.ts +0 -419
  67. package/src-next/contract/__tests__/translate.test.ts +0 -96
  68. package/src-next/contract/declare.ts +0 -983
  69. package/src-next/contract/doc.ts +0 -753
  70. package/src-next/contract/invariants.ts +0 -1268
  71. package/src-next/contract/judge.ts +0 -142
  72. package/src-next/contract/lint.ts +0 -275
  73. package/src-next/contract/project.ts +0 -596
  74. package/src-next/contract/skill-anatomy.ts +0 -273
  75. package/src-next/contract/translate.ts +0 -113
  76. package/src-next/face/__tests__/board-view.test.ts +0 -948
  77. package/src-next/face/__tests__/capsule.test.ts +0 -276
  78. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
  79. package/src-next/face/__tests__/cli.test.ts +0 -4643
  80. package/src-next/face/__tests__/face.test.ts +0 -289
  81. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  82. package/src-next/face/__tests__/host.test.ts +0 -24
  83. package/src-next/face/__tests__/negation.ts +0 -6
  84. package/src-next/face/__tests__/projection.test.ts +0 -301
  85. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
  86. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  87. package/src-next/face/artifacts.ts +0 -195
  88. package/src-next/face/board-view.ts +0 -662
  89. package/src-next/face/capsule.ts +0 -149
  90. package/src-next/face/cli.ts +0 -819
  91. package/src-next/face/declare.ts +0 -326
  92. package/src-next/face/gate.ts +0 -170
  93. package/src-next/face/graph-view.ts +0 -74
  94. package/src-next/face/host.ts +0 -326
  95. package/src-next/face/lifecycle.ts +0 -700
  96. package/src-next/face/projection.ts +0 -282
  97. package/src-next/face/route-render.ts +0 -160
  98. package/src-next/face/words.ts +0 -296
  99. package/src-next/infra/__tests__/infra.test.ts +0 -287
  100. package/src-next/infra/git.ts +0 -39
  101. package/src-next/infra/process.ts +0 -34
  102. package/src-next/infra/runtime.ts +0 -185
  103. package/src-next/infra/workspace.ts +0 -232
  104. package/src-next/render/__tests__/render.test.ts +0 -499
  105. package/src-next/render/__tests__/skeleton.test.ts +0 -466
  106. package/src-next/render/brief.ts +0 -121
  107. package/src-next/render/issue-body.ts +0 -159
  108. package/src-next/render/skeleton.ts +0 -437
  109. package/src-next/render/templates.ts +0 -650
  110. package/src-next/session/__tests__/graph.test.ts +0 -270
  111. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  112. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  113. package/src-next/session/__tests__/ledger.test.ts +0 -744
  114. package/src-next/session/__tests__/next.test.ts +0 -368
  115. package/src-next/session/__tests__/preflight.test.ts +0 -491
  116. package/src-next/session/__tests__/run.test.ts +0 -1014
  117. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  118. package/src-next/session/__tests__/wave.test.ts +0 -469
  119. package/src-next/session/faces.ts +0 -110
  120. package/src-next/session/graph.ts +0 -411
  121. package/src-next/session/handoff-schema.ts +0 -373
  122. package/src-next/session/ledger.ts +0 -1004
  123. package/src-next/session/next.ts +0 -192
  124. package/src-next/session/preflight.ts +0 -240
  125. package/src-next/session/run.ts +0 -606
  126. package/src-next/session/state.ts +0 -30
  127. 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
+ }