@oscaner-skills/cdd-engine 1.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.
@@ -0,0 +1,184 @@
1
+ import { O as ConfigLoader, j as CddExitError, Q as resolvePackageRoot, V as DEFAULT_IDLE_WINDOW_MS, W as DEFAULT_SAMPLE_INTERVAL_MS, X as spawnManaged, Y as markAllDispatchesDone, i as invariant } from '../cli.mjs';
2
+ import { readFileSync, statSync, existsSync } from 'node:fs';
3
+ import path from 'node:path';
4
+ import { fileURLToPath } from 'node:url';
5
+
6
+ function loadContract() {
7
+ return new ConfigLoader().contextContract();
8
+ }
9
+
10
+ function resolveRegistryPath(fromDir = path.dirname(fileURLToPath(import.meta.url))) {
11
+ const root = resolvePackageRoot(fromDir);
12
+ const published = path.join(root, "dist", "resources", "harness-registry.json");
13
+ if (existsSync(published)) return published;
14
+ return path.join(root, "src", "infra", "harness-registry.json");
15
+ }
16
+ const REG_PATH = resolveRegistryPath();
17
+ class CddBlockedError extends CddExitError {
18
+ constructor(message, { exitCode = 1, kind = "blocked" } = {}) {
19
+ super(message, { exitCode, kind });
20
+ this.name = "CddBlockedError";
21
+ }
22
+ }
23
+ class Registry {
24
+ /** Parse the shipped registry JSON (regPath default = the canonical REG_PATH). */
25
+ load(regPath) {
26
+ return JSON.parse(readFileSync(regPath, "utf8"));
27
+ }
28
+ field(reg, harness, field) {
29
+ const entry = reg?.[harness];
30
+ if (!entry) return "";
31
+ return entry[field] ?? "";
32
+ }
33
+ #resolveInjectionField(entry, field, op, type) {
34
+ const v = entry?.[field]?.[op] ?? "";
35
+ if (v && typeof v === "object") return type ? v[type] ?? "" : "";
36
+ return typeof v === "string" ? v : "";
37
+ }
38
+ resolveInjection(entry, op, type) {
39
+ return this.#resolveInjectionField(entry, "prefix", op, type);
40
+ }
41
+ resolveSuffix(entry, op, type) {
42
+ return this.#resolveInjectionField(entry, "suffix", op, type);
43
+ }
44
+ cliInPath(cli) {
45
+ const pathDirs = (process.env.PATH ?? "").split(path.delimiter);
46
+ for (const dir of pathDirs) {
47
+ if (!dir) continue;
48
+ try {
49
+ const st = statSync(path.join(dir, cli));
50
+ if (st.isFile() && (st.mode & 73) !== 0) return true;
51
+ } catch {
52
+ }
53
+ }
54
+ return false;
55
+ }
56
+ checkHarness(reg, harness, opts = {}) {
57
+ const { dryRun = false } = opts ?? {};
58
+ const entry = reg?.[harness];
59
+ if (!entry) throw new CddBlockedError(`unknown harness: ${harness}`, { exitCode: 1 });
60
+ if (entry.ship !== "full")
61
+ throw new CddBlockedError(`harness not supported: ${harness}`, { exitCode: 1 });
62
+ const cli = entry.cli;
63
+ if (!cli) throw new CddBlockedError(`unknown harness: ${harness}`, { exitCode: 1 });
64
+ if (!dryRun && !this.cliInPath(cli)) {
65
+ throw new CddBlockedError(`${cli} not found in PATH`, { exitCode: 2, kind: "cli-missing" });
66
+ }
67
+ return entry;
68
+ }
69
+ // ---- spec D-3 C7: per-harness cache profile (capability as data) ----
70
+ // The `cache` profile rides the registry row (mechanism / minTokens / readMultiplier /
71
+ // writeMultiplier / ttlMinutes / observable), validated against templates/schema/
72
+ // cache-profile-schema.json — adding a harness = one registry row, contract unchanged.
73
+ cacheProfileFor(entry) {
74
+ return entry?.cache ?? null;
75
+ }
76
+ }
77
+
78
+ const CONTRACT = loadContract();
79
+ const DEFAULT_TIMEOUTS = CONTRACT.timeouts.defaults;
80
+ const LIVENESS_DEFAULTS = CONTRACT.timeouts.liveness ?? {};
81
+ class EngineInvoker {
82
+ #registry;
83
+ constructor(registry = new Registry()) {
84
+ this.#registry = registry;
85
+ }
86
+ /** resolveTerminationConfig — the single resolver for the unified termination param (T26:
87
+ * replaces resolveTimeoutMs + resolveLivenessConfig). Returns the full TerminationConfig the
88
+ * three dispatch islands (task / docs / branch) thread into invokeCli/spawnManaged:
89
+ * budgetMs = overrides?.budgetMs ?? canonical default for mode (no env reads);
90
+ * progressPath = overrides?.progressPath ?? progressPath arg (the workspace tree signal);
91
+ * sampleInterval = overrides?.sampleIntervalMs ?? canonical timeouts.liveness;
92
+ * idleWindowMs = overrides?.idleWindowMs ?? canonical timeouts.liveness. */
93
+ resolveTerminationConfig(mode, overrides = void 0, progressPath = void 0) {
94
+ return {
95
+ budgetMs: overrides?.budgetMs ?? DEFAULT_TIMEOUTS[mode],
96
+ progressPath: overrides?.progressPath ?? progressPath,
97
+ sampleIntervalMs: overrides?.sampleIntervalMs ?? LIVENESS_DEFAULTS.sampleIntervalMs ?? DEFAULT_SAMPLE_INTERVAL_MS,
98
+ idleWindowMs: overrides?.idleWindowMs ?? LIVENESS_DEFAULTS.idleWindowMs ?? DEFAULT_IDLE_WINDOW_MS
99
+ };
100
+ }
101
+ // Credentials stripping lives at the single spawn choke point in proc.ts (spawnManaged) — invoke.ts
102
+ // keeps no duplicate cleanEnv (branch-review warn 1 of the .mjs era: double stripping is dead code).
103
+ /** [registry prefix, prompt, suffix] joined on newlines (C1: prefix precedes the prompt). */
104
+ promptArgText(prefix, prompt, suffix) {
105
+ return [prefix, prompt, suffix].filter(Boolean).join("\n");
106
+ }
107
+ /** invoke-spec words + the prompt arg last (the exact legacy args shape). */
108
+ buildInvokeArgs(invokeSpec, promptArg) {
109
+ return [...invokeSpec.split(/\s+/).filter(Boolean), promptArg];
110
+ }
111
+ /** Resolve the op×type prefix/suffix and compose the full dispatch set. */
112
+ composeDispatchSet(entry, params, prompt, cwd, env) {
113
+ const paramsObj = typeof params === "string" ? { op: params } : params ?? {};
114
+ const { op, type } = paramsObj;
115
+ const p = this.#registry.resolveInjection(entry, op, type);
116
+ const s = this.#registry.resolveSuffix(entry, op, type);
117
+ const promptArg = this.promptArgText(p, prompt, s);
118
+ return { cli: entry.cli, args: this.buildInvokeArgs(entry.invoke, promptArg), cwd, env };
119
+ }
120
+ // Invoke CLI: build args from entry, handle stream-json output mode.
121
+ // params = { op, type? } — operation×type injection replaces the positional mode arg. op:
122
+ // implement|review|fix (review carries type: task|branch|spec|plan). Resolution happens in
123
+ // registry.ts resolveInjection/resolveSuffix (entry.{prefix,suffix}[op][type?]), never inlined here.
124
+ // Legacy compat: a flat string mode key hits directly through the same resolver.
125
+ async invokeCli(entry, prompt, params, env, cwd, termination) {
126
+ const set = this.composeDispatchSet(entry, params, prompt, cwd, env);
127
+ const res = await spawnManaged(set.cli, set.args, { cwd: set.cwd, env: set.env, termination });
128
+ markAllDispatchesDone();
129
+ if (res.ok && entry.output === "stream-json") {
130
+ const finalText = extractStreamJsonFinal(res.stdout);
131
+ if (!finalText) {
132
+ return {
133
+ ok: false,
134
+ code: 1,
135
+ stdout: res.stdout,
136
+ stderr: "stream-json produced no completion finalText",
137
+ timedOut: res.timedOut === true,
138
+ cause: res.cause
139
+ };
140
+ }
141
+ return {
142
+ ok: true,
143
+ code: 0,
144
+ stdout: finalText,
145
+ stderr: res.stderr,
146
+ timedOut: res.timedOut === true,
147
+ cause: res.cause
148
+ };
149
+ }
150
+ return res;
151
+ }
152
+ // Transient retry wrapper for invokeCli (#109 fix). Retries only overloaded/rate_limit/529 stderr,
153
+ // never on timeout. params { op, type? } threads the same signature as invokeCli.
154
+ async invokeCliWithRetry(entry, prompt, params, env, cwd, termination) {
155
+ const MAX_RETRIES = RETRY_DELAYS_MS.length;
156
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
157
+ const result = await this.invokeCli(entry, prompt, params, env, cwd, termination);
158
+ if (result.ok || result.timedOut) return result;
159
+ const isTransient = /overloaded|rate_limit|529/.test(result.stderr ?? "");
160
+ if (isTransient && attempt < MAX_RETRIES) {
161
+ await new Promise((r) => setTimeout(r, RETRY_DELAYS_MS[attempt]));
162
+ continue;
163
+ }
164
+ return result;
165
+ }
166
+ invariant(false, "unreachable: retry loop always returns");
167
+ }
168
+ }
169
+ const RETRY_DELAYS_MS = [5e3, 15e3];
170
+ function extractStreamJsonFinal(raw) {
171
+ let last = null;
172
+ for (const line of String(raw).split("\n")) {
173
+ const trimmed = line.trim();
174
+ if (!trimmed) continue;
175
+ try {
176
+ const ev = JSON.parse(trimmed);
177
+ if (ev.type === "completion" && ev.finalText != null) last = ev.finalText;
178
+ } catch {
179
+ }
180
+ }
181
+ return last;
182
+ }
183
+
184
+ export { CddBlockedError as C, EngineInvoker as E, Registry as R, REG_PATH as a };
package/package.json ADDED
@@ -0,0 +1,51 @@
1
+ {
2
+ "name": "@oscaner-skills/cdd-engine",
3
+ "version": "1.0.0",
4
+ "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
+ "type": "module",
6
+ "engines": {
7
+ "node": ">=22.12.0"
8
+ },
9
+ "files": [
10
+ "dist/",
11
+ "templates/"
12
+ ],
13
+ "main": "./dist/cli.mjs",
14
+ "exports": {
15
+ ".": "./dist/cli.mjs",
16
+ "./package.json": "./package.json"
17
+ },
18
+ "bin": {
19
+ "cdd": "./dist/cli.mjs"
20
+ },
21
+ "dependencies": {
22
+ "ajv": "^8.20.0",
23
+ "citty": "^0.2.2",
24
+ "consola": "^3.4.2",
25
+ "execa": "^10.0.1",
26
+ "handlebars": "^4.7.9",
27
+ "hookable": "^6.1.2",
28
+ "semver": "^7.8.5",
29
+ "simple-git": "^3.36.0",
30
+ "tinyglobby": "^0.2.17"
31
+ },
32
+ "devDependencies": {
33
+ "@types/node": "^26.6.2",
34
+ "@typescript/typescript6": "^6.0.2",
35
+ "typescript": "^7.0.2",
36
+ "unbuild": "^3.6.1",
37
+ "vitest": "^5.0.1"
38
+ },
39
+ "repository": {
40
+ "type": "git",
41
+ "url": "https://github.com/Oscaner/skills",
42
+ "directory": "packages/cdd-engine"
43
+ },
44
+ "license": "MIT",
45
+ "scripts": {
46
+ "build": "unbuild",
47
+ "dev:stub": "unbuild --stub",
48
+ "test": "vitest run",
49
+ "test:watch": "vitest"
50
+ }
51
+ }
@@ -0,0 +1,302 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "$version": 1,
4
+ "contextContract": {
5
+ "channels": {
6
+ "argv": {
7
+ "plan": {
8
+ "flag": "--plan",
9
+ "type": "path"
10
+ },
11
+ "spec": {
12
+ "flag": "--spec",
13
+ "type": "path"
14
+ },
15
+ "findings": {
16
+ "flag": "--findings",
17
+ "type": "path"
18
+ },
19
+ "tasks": {
20
+ "flag": "--tasks",
21
+ "type": "int-list"
22
+ },
23
+ "type": {
24
+ "flag": "--type",
25
+ "type": "enum",
26
+ "values": [
27
+ "task",
28
+ "branch",
29
+ "spec",
30
+ "plan"
31
+ ]
32
+ },
33
+ "base": {
34
+ "flag": "--base",
35
+ "type": "sha"
36
+ },
37
+ "head": {
38
+ "flag": "--head",
39
+ "type": "sha"
40
+ },
41
+ "round": {
42
+ "flag": "--round",
43
+ "type": "int"
44
+ },
45
+ "source": {
46
+ "flag": "--source",
47
+ "type": "enum",
48
+ "values": [
49
+ "plan-field",
50
+ "branch-upstream",
51
+ "conversation-context",
52
+ "user-confirmed"
53
+ ]
54
+ },
55
+ "force": {
56
+ "flag": "--force",
57
+ "type": "bool"
58
+ },
59
+ "dryRun": {
60
+ "flag": "--dry-run",
61
+ "type": "bool",
62
+ "scope": "program"
63
+ },
64
+ "help": {
65
+ "flag": "--help",
66
+ "alias": "-h",
67
+ "type": "bool",
68
+ "scope": "program"
69
+ }
70
+ },
71
+ "git": {
72
+ "root": {
73
+ "derivation": "gitToplevel(cwd)"
74
+ }
75
+ },
76
+ "env": {
77
+ "hostHarness": {
78
+ "markers": [
79
+ "CURSOR_TRACE_ID",
80
+ "CLAUDE_CODE_SESSION_ID",
81
+ "AI_AGENT"
82
+ ]
83
+ },
84
+ "path": {
85
+ "var": "PATH"
86
+ }
87
+ }
88
+ },
89
+ "derived": {
90
+ "root": {
91
+ "from": [
92
+ "git.root"
93
+ ]
94
+ },
95
+ "slug": {
96
+ "from": [
97
+ "plan"
98
+ ]
99
+ },
100
+ "workspace": {
101
+ "from": [
102
+ "root",
103
+ "slug"
104
+ ]
105
+ },
106
+ "handoffPath": {
107
+ "from": [
108
+ "workspace",
109
+ "mode",
110
+ "tasks",
111
+ "round"
112
+ ]
113
+ },
114
+ "briefPath": {
115
+ "from": [
116
+ "workspace",
117
+ "tasks"
118
+ ]
119
+ },
120
+ "ledgerPath": {
121
+ "from": [
122
+ "workspace"
123
+ ]
124
+ },
125
+ "constraintsPath": {
126
+ "from": [
127
+ "workspace"
128
+ ]
129
+ },
130
+ "findingsPath": {
131
+ "from": [
132
+ "workspace",
133
+ "tasks"
134
+ ]
135
+ },
136
+ "fixedPoint": {
137
+ "from": [
138
+ "prevHandoff",
139
+ "commits.base"
140
+ ]
141
+ }
142
+ },
143
+ "transport": {
144
+ "childEnv": {
145
+ "policy": "host-env-minus-credentials",
146
+ "cddVarsInjected": []
147
+ }
148
+ },
149
+ "timeouts": {
150
+ "defaults": {
151
+ "task": 10800000,
152
+ "review": 3600000
153
+ },
154
+ "liveness": {
155
+ "sampleIntervalMs": 60000,
156
+ "idleWindowMs": 900000
157
+ }
158
+ }
159
+ },
160
+ "failureCategories": {
161
+ "categories": [
162
+ {
163
+ "id": "TIMEOUT",
164
+ "countsTowardConvergence": false,
165
+ "counter": "timeoutCount",
166
+ "returnMarker": "timeout",
167
+ "terminal": "BLOCKED: dispatch-timeout-cap"
168
+ },
169
+ {
170
+ "id": "CONTRACT_VIOLATION",
171
+ "countsTowardConvergence": false,
172
+ "counter": "contractViolationCount",
173
+ "returnMarker": "contract-violation",
174
+ "terminal": "BLOCKED: contract-violation-exhausted",
175
+ "dispatchIncomplete": true
176
+ },
177
+ {
178
+ "id": "ENGINE_SELF_WRITTEN",
179
+ "countsTowardConvergence": false,
180
+ "counter": "engineSelfWrittenCount",
181
+ "returnMarker": "engine-self-written",
182
+ "terminal": "BLOCKED: engine-self-written-exhausted",
183
+ "dispatchIncomplete": true
184
+ },
185
+ {
186
+ "id": "EXECUTION_FAILURE",
187
+ "countsTowardConvergence": false,
188
+ "counter": "engineRecoveryCount",
189
+ "returnMarker": "recovery",
190
+ "terminal": "BLOCKED: engine-error"
191
+ },
192
+ {
193
+ "id": "UNVERIFIABLE",
194
+ "countsTowardConvergence": false
195
+ },
196
+ {
197
+ "id": "PLAN_CONFLICT",
198
+ "countsTowardConvergence": false
199
+ }
200
+ ]
201
+ },
202
+ "handoffNamespace": {
203
+ "schema": 1,
204
+ "workspaceRoot": ".osuperpowers/cdd",
205
+ "slugRule": "strip .md, then a single trailing -design or -plan suffix",
206
+ "families": {
207
+ "implement.task": {
208
+ "name": "tasks-{tasks}-implement.json",
209
+ "round": "fixed",
210
+ "status": "contract",
211
+ "schema": "task",
212
+ "phase": "implement"
213
+ },
214
+ "review.task": {
215
+ "name": "tasks-{tasks}-review-{round}.json",
216
+ "round": "increment",
217
+ "status": "rollup",
218
+ "schema": "task",
219
+ "returnFormat": "RETURN_STDOUT_BLOCK",
220
+ "phase": "review",
221
+ "fixFamily": "fix.task",
222
+ "prev": {
223
+ "round1": "implement.task",
224
+ "roundR": "fix.task:R-1"
225
+ }
226
+ },
227
+ "fix.task": {
228
+ "name": "tasks-{tasks}-fix-{round}.json",
229
+ "round": "source",
230
+ "status": "contract",
231
+ "schema": "task",
232
+ "fixTemplate": "fix",
233
+ "phase": "fix",
234
+ "prev": {
235
+ "roundR": "review.task:R"
236
+ }
237
+ },
238
+ "review.spec": {
239
+ "name": "spec-review-{round}.json",
240
+ "round": "increment",
241
+ "status": "rollup",
242
+ "schema": "docs",
243
+ "returnFormat": "RETURN_JSON",
244
+ "phase": "review",
245
+ "fixFamily": "fix.spec"
246
+ },
247
+ "fix.spec": {
248
+ "name": "spec-fix-{round}.json",
249
+ "round": "source",
250
+ "status": "contract",
251
+ "schema": "docs",
252
+ "fixTemplate": "docs",
253
+ "returnFormat": "RETURN_JSON",
254
+ "phase": "fix",
255
+ "prev": {
256
+ "roundR": "review.spec:R"
257
+ }
258
+ },
259
+ "review.plan": {
260
+ "name": "plan-review-{round}.json",
261
+ "round": "increment",
262
+ "status": "rollup",
263
+ "schema": "docs",
264
+ "returnFormat": "RETURN_JSON",
265
+ "phase": "review",
266
+ "fixFamily": "fix.plan"
267
+ },
268
+ "fix.plan": {
269
+ "name": "plan-fix-{round}.json",
270
+ "round": "source",
271
+ "status": "contract",
272
+ "schema": "docs",
273
+ "fixTemplate": "docs",
274
+ "returnFormat": "RETURN_JSON",
275
+ "phase": "fix",
276
+ "prev": {
277
+ "roundR": "review.plan:R"
278
+ }
279
+ },
280
+ "review.branch": {
281
+ "name": "branch-review-{base7}..{head7}-r{round}.json",
282
+ "round": "increment",
283
+ "status": "rollup",
284
+ "schema": "task",
285
+ "returnFormat": "RETURN_STDOUT_BLOCK",
286
+ "phase": "branch-review"
287
+ },
288
+ "fix.branch": {
289
+ "name": "branch-fix-{base7}..{head7}-r{round}.json",
290
+ "round": "source",
291
+ "status": "contract",
292
+ "schema": "task",
293
+ "fixTemplate": "fix",
294
+ "returnFormat": "RETURN_STDOUT_BLOCK",
295
+ "phase": "fix",
296
+ "prev": {
297
+ "roundR": "review.branch:R"
298
+ }
299
+ }
300
+ }
301
+ }
302
+ }