@rusha/task-master 0.0.0-stage → 0.1.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,1401 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * ce-sync — one-way sync of contract-engineering (CE) YAML records into Task Master.
4
+ *
5
+ * The YAML files under `.contract-engineering/` stay authoritative. This CLI
6
+ * parses them, preserves each document verbatim (with a SHA-256 content hash),
7
+ * and calls the `ce.import` tRPC procedure on the Packet API. Run with
8
+ * --dry-run to preview the summary, the workspace format check, and the link
9
+ * report without writing anything.
10
+ *
11
+ * Before importing, packet transitions recorded in Task Master since the last
12
+ * sync (claim, evidence verification, handoff review) are written back into
13
+ * the work-packet YAML's `state`/`owner`/`claim_timestamp` so the files stay
14
+ * authoritative. A packet edited locally while Task Master also moved it is a
15
+ * conflict unless the local state already matches Task Master's current state;
16
+ * in that case lifecycle metadata is reconciled and the local document imports.
17
+ * `--no-write-back` disables the write-back step.
18
+ *
19
+ * What is synced:
20
+ * - work packets, with their decision / data-gate / threat-model sidecars,
21
+ * - evidence files (referenced by packets or named "<packetId>-EV*"/"-REV*"),
22
+ * - handoff records (by packet_id / packet_ids, plus the receiver review
23
+ * embedded from the matching "*-REVIEW.md"),
24
+ * - sidecars named for a packet by convention ("<packetId>-DEC*"-style) even
25
+ * when the packet's ref is missing or unresolvable.
26
+ *
27
+ * The API namespaces stored ids as "<project>:<CE id>", so one run syncs one
28
+ * workspace: use --root <path> to point at another repository's
29
+ * .contract-engineering/ and --project <id> to label it.
30
+ *
31
+ * Token sources, in order: --token, CE_SYNC_TOKEN, a stored refresh token
32
+ * (`.agent/ce-sync-token.json`, encrypted with CE_SYNC_CONFIG_KEY), or the
33
+ * OIDC device flow. The device flow needs the Keycloak client to allow the
34
+ * OAuth 2.0 Device Authorization Grant — see
35
+ * docs/keycloak-device-grant-request.md when it is disabled.
36
+ */
37
+
38
+ import { createHash, randomBytes, scryptSync, createCipheriv, createDecipheriv } from "node:crypto";
39
+ import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, readdirSync, statSync } from "node:fs";
40
+ import { join, dirname } from "node:path";
41
+ import { fileURLToPath } from "node:url";
42
+ import yaml from "js-yaml";
43
+
44
+ import { basename, resolve } from "node:path";
45
+
46
+ const __dirname = dirname(fileURLToPath(import.meta.url));
47
+ const SCRIPT_ROOT = join(__dirname, "..");
48
+
49
+ /**
50
+ * The workspace whose .contract-engineering/ records are synced. Defaults to
51
+ * this repository so existing behaviour is unchanged; set --root (or
52
+ * PACKET_WORKSPACE_ROOT) to sync another project's records from there.
53
+ *
54
+ * The encrypted token and key live in the Task Master repo's .agent/ because
55
+ * they are per-user, not per-project; a different repo should not have to know
56
+ * about the key.
57
+ */
58
+ function resolveWorkspaceRoot(argv) {
59
+ const flag = argv.find((arg, index) => argv[index - 1] === "--root");
60
+ return resolve(flag ?? process.env.PACKET_WORKSPACE_ROOT ?? SCRIPT_ROOT);
61
+ }
62
+
63
+ const ROOT = resolveWorkspaceRoot(process.argv.slice(2));
64
+ const CE_DIR = join(ROOT, ".contract-engineering");
65
+
66
+ const DEFAULTS = {
67
+ apiUrl: process.env.CE_SYNC_API_URL ?? "https://task-master-api.dev.rusha.tierravivaai.net/trpc",
68
+ // The project id labels the imported records. Default to the workspace
69
+ // folder name (e.g. "task-master") unless an explicit id is given.
70
+ projectId: process.env.PACKET_PROJECT_ID ?? basename(ROOT),
71
+ issuer: process.env.CE_SYNC_ISSUER ?? "https://idp.dev.rusha.tierravivaai.net/realms/rusha-dev",
72
+ clientId: process.env.CE_SYNC_CLIENT_ID ?? process.env.OIDC_CLIENT_ID ?? "rusha-rusha-corp-app-task-master-api-dev",
73
+ orgScope: process.env.OIDC_ORG_SCOPE ?? "rusha-corp",
74
+ // Per-user secrets stay in the Task Master repo, not the synced workspace.
75
+ tokenPath: join(SCRIPT_ROOT, ".agent", "ce-sync-token.json"),
76
+ keyPath: join(SCRIPT_ROOT, ".agent", "ce-sync.key"),
77
+ // Keep requests well under the API's default 100kb JSON body limit.
78
+ // Chunks must hold a single artifact (base64 of a 5 MB file is ~6.7 MB).
79
+ chunkBytes: 8 * 1024 * 1024,
80
+ };
81
+
82
+ // Per-file size cap for binary artifacts (5 MB).
83
+ const MAX_ARTIFACT_BYTES = 5 * 1024 * 1024;
84
+
85
+ // Extension -> MIME type map for collectable artifact files.
86
+ // SVG is excluded (active content); .md/.yaml are text evidence, not artifacts.
87
+ const ARTIFACT_EXTENSIONS = new Map([
88
+ [".png", "image/png"],
89
+ [".jpg", "image/jpeg"],
90
+ [".jpeg", "image/jpeg"],
91
+ [".gif", "image/gif"],
92
+ [".webp", "image/webp"],
93
+ [".html", "text/html"],
94
+ ]);
95
+
96
+ // Text evidence extensions (handled as before — read as UTF-8, no base64).
97
+ const TEXT_EXTENSIONS = new Set([".md", ".yaml"]);
98
+
99
+ // Board states the importer accepts. Keep in sync with
100
+ // src/apps/api/src/import/ce-import.service.ts (CE_STATES).
101
+ export const CE_STATES = [
102
+ "planned", "claimed", "design_review", "ready", "implementing", "validation", "handoff", "complete", "cancelled",
103
+ ];
104
+
105
+ // Task Master (lowercase) -> CE protocol state names for the write-back of
106
+ // Task Master transitions into work-packet YAML. Design_Review preserves the
107
+ // multiword separator required by the importer's design_review state.
108
+ export const TM_TO_CE_STATE = {
109
+ planned: "Planned",
110
+ claimed: "Claimed",
111
+ design_review: "Design_Review",
112
+ ready: "Ready",
113
+ implementing: "Implementing",
114
+ validation: "Validation",
115
+ handoff: "Handoff",
116
+ complete: "Complete",
117
+ cancelled: "Cancelled",
118
+ };
119
+
120
+ const SIDECAR_FIELDS = {
121
+ design_decision_ref: { dir: "decisions", suffix: "-DEC", label: "decisions" },
122
+ data_gate_ref: { dir: "data-gates", suffix: "-DG", label: "data_gates" },
123
+ threat_model_ref: { dir: "threat-models", suffix: "-TM", label: "threat_models" },
124
+ };
125
+
126
+ // Maps the "-DEC001"-style suffix of a CE record id to the folder that owns it.
127
+ const ID_SUFFIX_DIRS = {
128
+ DEC: "decisions",
129
+ DG: "data-gates",
130
+ TM: "threat-models",
131
+ EV: "evidence",
132
+ REV: "evidence",
133
+ HO: "handoffs",
134
+ };
135
+
136
+ const SIDECAR_DIRS = new Set(["decisions", "data-gates", "threat-models", "evidence", "handoffs"]);
137
+
138
+ // ---------- payload building (pure, unit-tested) ----------
139
+
140
+ export function sha256(content) {
141
+ return createHash("sha256").update(content).digest("hex");
142
+ }
143
+
144
+ export function parseCeFile(sourcePath, content) {
145
+ let doc;
146
+ try {
147
+ doc = yaml.load(content);
148
+ } catch (error) {
149
+ throw new Error(`"${sourcePath}" is not valid YAML: ${error instanceof Error ? error.message : String(error)}`);
150
+ }
151
+ if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
152
+ throw new Error(`"${sourcePath}" is not a YAML mapping.`);
153
+ }
154
+ return { source_path: sourcePath, content_hash: sha256(content), document: doc };
155
+ }
156
+
157
+ function stringArr(value) {
158
+ return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.length > 0) : [];
159
+ }
160
+
161
+ function contractCriteria(document) {
162
+ const contract = document.acceptance_contract;
163
+ if (contract && typeof contract === "object" && Array.isArray(contract.criteria)) {
164
+ return contract.criteria.filter((criterion) => criterion && typeof criterion === "object");
165
+ }
166
+ return [];
167
+ }
168
+
169
+ const ceDirCache = new Map();
170
+
171
+ function listCeDir(dir) {
172
+ if (!ceDirCache.has(dir)) {
173
+ const absolutePath = join(CE_DIR, dir);
174
+ ceDirCache.set(dir, existsSync(absolutePath) ? readdirSync(absolutePath).sort() : []);
175
+ }
176
+ return ceDirCache.get(dir);
177
+ }
178
+
179
+ /**
180
+ * Work-packet YAML files to import: the active work-packets/ folder plus,
181
+ * in workspaces that use the tracker-rollover layout, the terminal packets
182
+ * in archive/work-packets/. Archived packets are imported as finished
183
+ * history with their real source paths, so record links and write-back
184
+ * point at the actual files.
185
+ */
186
+ export function collectWorkPacketFiles(ceDir = CE_DIR) {
187
+ const files = new Map();
188
+ const activeDir = join(ceDir, "work-packets");
189
+ for (const name of readdirSync(activeDir).filter((file) => file.endsWith(".yaml")).sort()) {
190
+ files.set(`.contract-engineering/work-packets/${name}`, readFileSync(join(activeDir, name), "utf8"));
191
+ }
192
+ const archiveDir = join(ceDir, "archive", "work-packets");
193
+ if (existsSync(archiveDir)) {
194
+ for (const name of readdirSync(archiveDir).filter((file) => file.endsWith(".yaml")).sort()) {
195
+ files.set(`.contract-engineering/archive/work-packets/${name}`, readFileSync(join(archiveDir, name), "utf8"));
196
+ }
197
+ }
198
+ return files;
199
+ }
200
+
201
+ /**
202
+ * Why an evidence or sidecar ref could not be resolved, for the report.
203
+ * "wrong-kind-id" covers refs that point at another record type (an evidence
204
+ * id in data_gate_ref, a bare packet id, ...); "non-record-doc" covers
205
+ * repo-relative paths to documents that are not governance records (specs,
206
+ * deprecations, ...).
207
+ */
208
+ export function categorizeRef(ref, expectedDir) {
209
+ if (typeof ref !== "string" || ref.length === 0) return "empty";
210
+ if (/\s/.test(ref) || /^approved specification/i.test(ref)) return "prose";
211
+ if (ref.startsWith("/")) return "absolute-path";
212
+ if (ref.startsWith(".contract-engineering/")) {
213
+ const kind = ref.split("/")[1];
214
+ if (kind === expectedDir) return "missing-file";
215
+ if (SIDECAR_DIRS.has(kind)) return "wrong-kind-id";
216
+ return "non-record-doc";
217
+ }
218
+ const suffix = ref.match(/-(DEC|DG|TM|EV|REV|HO)\d+$/);
219
+ if (suffix && ID_SUFFIX_DIRS[suffix[1]] !== expectedDir) return "wrong-kind-id";
220
+ if (!suffix && !ref.endsWith(".md")) return "wrong-kind-id";
221
+ return "missing-file";
222
+ }
223
+
224
+ function readSidecarRecord(absolutePath, sourcePath) {
225
+ const content = readFileSync(absolutePath, "utf8");
226
+ if (absolutePath.endsWith(".yaml")) {
227
+ return parseCeFile(sourcePath, content);
228
+ }
229
+ // Legacy sidecars are Markdown records ("# Decision MOCKUP-T002-DEC001").
230
+ // Preserve them verbatim; the importer marks their status "imported".
231
+ return {
232
+ source_path: sourcePath,
233
+ content_hash: sha256(content),
234
+ document: { source_format: "markdown", content },
235
+ };
236
+ }
237
+
238
+ /**
239
+ * Resolve one sidecar field of a packet: the explicit ref first (repo-relative
240
+ * YAML path or bare record id), then every file named "<packetId>-<KIND>*" as
241
+ * an ID-convention fallback. Unresolvable refs become categorized warnings,
242
+ * not packet failures — the ref text is preserved in the packet's verbatim
243
+ * ceDocument.
244
+ */
245
+ function resolveSidecar(ref, field, packetId, packetPath, warnings, conventionLinks) {
246
+ const { dir, suffix, label } = SIDECAR_FIELDS[field];
247
+ const found = new Map();
248
+
249
+ if (typeof ref === "string" && ref.length > 0) {
250
+ const candidates = [];
251
+ if (ref.startsWith(".contract-engineering/") && ref.endsWith(".yaml")) {
252
+ candidates.push([join(ROOT, ref), ref]);
253
+ } else if (!ref.includes("/") && !ref.includes(":") && !ref.endsWith(".md")) {
254
+ for (const ext of [".yaml", ".md"]) {
255
+ const sourcePath = `.contract-engineering/${dir}/${ref}${ext}`;
256
+ candidates.push([join(ROOT, sourcePath), sourcePath]);
257
+ }
258
+ }
259
+ let resolved = false;
260
+ for (const [absolutePath, sourcePath] of candidates) {
261
+ if (!existsSync(absolutePath)) continue;
262
+ resolved = true;
263
+ try {
264
+ found.set(sourcePath, readSidecarRecord(absolutePath, sourcePath));
265
+ } catch (error) {
266
+ const message = error instanceof Error ? error.message : String(error);
267
+ warnings.push({ source_path: packetPath, category: "unreadable", field, ref, message: `unreadable ${field} ref "${ref}": ${message}` });
268
+ }
269
+ }
270
+ if (!resolved) {
271
+ const category = categorizeRef(ref, dir);
272
+ warnings.push({ source_path: packetPath, category, field, ref, message: `unresolved ${field} ref "${ref}" (${category})` });
273
+ }
274
+ }
275
+
276
+ for (const name of listCeDir(dir)) {
277
+ if (!name.startsWith(`${packetId}${suffix}`)) continue;
278
+ if (!name.endsWith(".yaml") && !name.endsWith(".md")) continue;
279
+ const sourcePath = `.contract-engineering/${dir}/${name}`;
280
+ if (found.has(sourcePath)) continue;
281
+ try {
282
+ found.set(sourcePath, readSidecarRecord(join(ROOT, sourcePath), sourcePath));
283
+ conventionLinks.push({ field: label, packet_id: packetId, source_path: sourcePath });
284
+ } catch (error) {
285
+ const message = error instanceof Error ? error.message : String(error);
286
+ warnings.push({ source_path: sourcePath, category: "unreadable", field, message: `unreadable sidecar "${sourcePath}": ${message}` });
287
+ }
288
+ }
289
+
290
+ return [...found.values()];
291
+ }
292
+
293
+ /**
294
+ * Task display titles from the execution tracker's headings:
295
+ * "### <task id> — <title>" sections and the "## <label>: <task id>" form
296
+ * (e.g. "## New integration task: MOCKUP-T003"). Tasks with no matching
297
+ * heading keep their bare CE id; the first heading wins.
298
+ */
299
+ export function deriveTaskTitles(trackerContent) {
300
+ const titles = new Map();
301
+ for (const line of String(trackerContent).split(/\r?\n/)) {
302
+ let match = line.match(/^###\s+([A-Za-z0-9][A-Za-z0-9_-]*)\s*[—–]\s*(\S.*)$/);
303
+ if (match && !titles.has(match[1])) {
304
+ titles.set(match[1], match[2].trim());
305
+ continue;
306
+ }
307
+ match = line.match(/^##\s+(.+?):\s*([A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])\s*$/);
308
+ if (match && /-T\d+$/.test(match[2]) && !titles.has(match[2])) {
309
+ titles.set(match[2], match[1].trim());
310
+ }
311
+ }
312
+ return titles;
313
+ }
314
+
315
+ /**
316
+ * Build task payloads from the CE work-packet files. `files` maps work-packet
317
+ * paths to file contents; sidecars are resolved through the packet document's
318
+ * decision/data-gate/threat-model refs and the ID convention.
319
+ */
320
+ export function buildTaskPayloads(files, { projectId } = { projectId: DEFAULTS.projectId }) {
321
+ const byTask = new Map();
322
+ const errors = [];
323
+ const warnings = [];
324
+ const conventionLinks = [];
325
+
326
+ for (const [sourcePath, content] of [...files.entries()].sort(([a], [b]) => a.localeCompare(b))) {
327
+ try {
328
+ const record = parseCeFile(sourcePath, content);
329
+ const doc = record.document;
330
+ const taskId = doc.task_id;
331
+ const packetId = doc.packet_id;
332
+ if (typeof taskId !== "string" || taskId.length === 0) throw new Error(`"${sourcePath}" has no task_id.`);
333
+ if (typeof packetId !== "string" || packetId.length === 0) throw new Error(`"${sourcePath}" has no packet_id.`);
334
+
335
+ const packet = {
336
+ ...record,
337
+ decisions: resolveSidecar(doc.design_decision_ref, "design_decision_ref", packetId, sourcePath, warnings, conventionLinks),
338
+ data_gates: resolveSidecar(doc.data_gate_ref, "data_gate_ref", packetId, sourcePath, warnings, conventionLinks),
339
+ threat_models: resolveSidecar(doc.threat_model_ref, "threat_model_ref", packetId, sourcePath, warnings, conventionLinks),
340
+ };
341
+ if (!byTask.has(taskId)) byTask.set(taskId, []);
342
+ byTask.get(taskId).push(packet);
343
+ } catch (error) {
344
+ errors.push({ source_path: sourcePath, message: error instanceof Error ? error.message : String(error) });
345
+ }
346
+ }
347
+
348
+ const trackerPath = join(CE_DIR, "execution-tracker.md");
349
+ const taskTitles = existsSync(trackerPath) ? deriveTaskTitles(readFileSync(trackerPath, "utf8")) : new Map();
350
+ const tasks = [...byTask.entries()]
351
+ .sort(([a], [b]) => a.localeCompare(b))
352
+ .map(([id, packets]) => ({ id, project_id: projectId, title: taskTitles.get(id) ?? id, phase: "contract-engineering", packets }));
353
+ return { tasks, errors, warnings, conventionLinks };
354
+ }
355
+
356
+ /**
357
+ * Collect evidence records: packet `evidence_refs`, per-criterion
358
+ * `evidence_refs`, and "<packetId>-EV*"/"-REV*" files by convention. A file
359
+ * shared by several packets is sent once with all its packet ids.
360
+ *
361
+ * Text evidence (.md, .yaml) is read as UTF-8 and stored in `content`.
362
+ * Binary artifacts (.png, .jpg, .gif, .webp) are base64-encoded and stored
363
+ * in `artifact_data` with a `content_type` MIME label. HTML files are text
364
+ * artifacts (stored in `content` with `content_type: text/html`).
365
+ *
366
+ * SVG files are skipped (active content). Files exceeding 5 MB are skipped.
367
+ * All skipped files are reported in `skippedBinary` with a `category` field.
368
+ */
369
+ export function collectEvidence(tasks, { projectId = DEFAULTS.projectId, warnings = [], conventionLinks = [] } = {}) {
370
+ const allEvidenceFiles = listCeDir("evidence");
371
+ // Text evidence: .md and .yaml (parsed as before).
372
+ const textFiles = new Set(allEvidenceFiles.filter((name) => name.endsWith(".md") || name.endsWith(".yaml")));
373
+ // Artifact evidence: files with collectable binary/text-artifact extensions.
374
+ const artifactFiles = new Set(allEvidenceFiles.filter((name) => {
375
+ const ext = name.slice(name.lastIndexOf("."));
376
+ return ARTIFACT_EXTENSIONS.has(ext);
377
+ }));
378
+ // SVG files exist on disk but are actively excluded.
379
+ const svgFiles = new Set(allEvidenceFiles.filter((name) => name.endsWith(".svg")));
380
+
381
+ // Combined set of all files we track (text + artifacts, excluding SVG).
382
+ const evidenceFiles = allEvidenceFiles.filter((name) => textFiles.has(name) || artifactFiles.has(name));
383
+
384
+ const records = new Map();
385
+ const skippedBinary = [];
386
+ const linkedFiles = new Set();
387
+
388
+ const extOf = (name) => name.slice(name.lastIndexOf("."));
389
+
390
+ const addTextFile = (fileName, packetId, via) => {
391
+ if (!textFiles.has(fileName)) return false;
392
+ const sourcePath = `.contract-engineering/evidence/${fileName}`;
393
+ if (!records.has(sourcePath)) {
394
+ let document;
395
+ const content = readFileSync(join(ROOT, sourcePath), "utf8");
396
+ if (fileName.endsWith(".yaml")) {
397
+ try {
398
+ document = parseCeFile(sourcePath, content).document;
399
+ } catch (error) {
400
+ const message = error instanceof Error ? error.message : String(error);
401
+ warnings.push({ source_path: sourcePath, category: "invalid-yaml", message: `evidence is not valid YAML: ${message}` });
402
+ return false;
403
+ }
404
+ } else {
405
+ document = { source_format: "markdown", content };
406
+ }
407
+ records.set(sourcePath, { source_path: sourcePath, content_hash: sha256(content), content, document, packet_ids: new Set() });
408
+ }
409
+ const alreadyLinked = records.get(sourcePath).packet_ids.has(packetId);
410
+ records.get(sourcePath).packet_ids.add(packetId);
411
+ linkedFiles.add(sourcePath);
412
+ if (via === "convention" && !alreadyLinked) {
413
+ conventionLinks.push({ field: "evidence", packet_id: packetId, source_path: sourcePath });
414
+ }
415
+ return true;
416
+ };
417
+
418
+ const addArtifactFile = (fileName, packetId, via) => {
419
+ if (!artifactFiles.has(fileName)) return false;
420
+ const sourcePath = `.contract-engineering/evidence/${fileName}`;
421
+ if (records.has(sourcePath)) {
422
+ const alreadyLinked = records.get(sourcePath).packet_ids.has(packetId);
423
+ records.get(sourcePath).packet_ids.add(packetId);
424
+ linkedFiles.add(sourcePath);
425
+ if (via === "convention" && !alreadyLinked) {
426
+ conventionLinks.push({ field: "evidence", packet_id: packetId, source_path: sourcePath });
427
+ }
428
+ return true;
429
+ }
430
+
431
+ const ext = extOf(fileName);
432
+ const contentType = ARTIFACT_EXTENSIONS.get(ext);
433
+ const absolutePath = join(ROOT, sourcePath);
434
+ const stat = statSync(absolutePath);
435
+
436
+ if (stat.size > MAX_ARTIFACT_BYTES) {
437
+ skippedBinary.push({ source_path: sourcePath, ref: sourcePath, category: "oversized", size: stat.size });
438
+ return false;
439
+ }
440
+
441
+ if (ext === ".html") {
442
+ // HTML is a text artifact: store content directly, no base64.
443
+ const content = readFileSync(absolutePath, "utf8");
444
+ const document = { kind: "artifact", source_format: "html", content_type: contentType, content };
445
+ records.set(sourcePath, {
446
+ source_path: sourcePath, content_hash: sha256(content),
447
+ content, document, content_type: contentType, packet_ids: new Set([packetId]),
448
+ });
449
+ } else {
450
+ // Binary artifact: base64-encode the raw bytes.
451
+ const raw = readFileSync(absolutePath);
452
+ const artifactData = raw.toString("base64");
453
+ const document = { kind: "artifact", source_format: "binary", content_type: contentType, content: fileName };
454
+ records.set(sourcePath, {
455
+ source_path: sourcePath, content_hash: sha256(raw),
456
+ document, content_type: contentType, artifact_data: artifactData, packet_ids: new Set([packetId]),
457
+ });
458
+ }
459
+
460
+ linkedFiles.add(sourcePath);
461
+ if (via === "convention") {
462
+ conventionLinks.push({ field: "evidence", packet_id: packetId, source_path: sourcePath });
463
+ }
464
+ return true;
465
+ };
466
+
467
+ const addFile = (fileName, packetId, via) => {
468
+ if (textFiles.has(fileName)) return addTextFile(fileName, packetId, via);
469
+ if (artifactFiles.has(fileName)) return addArtifactFile(fileName, packetId, via);
470
+ return false;
471
+ };
472
+
473
+ const resolveRefToFile = (ref) => {
474
+ if (ref.startsWith(".contract-engineering/evidence/")) {
475
+ const fileName = ref.split("/").pop();
476
+ if (textFiles.has(fileName) || artifactFiles.has(fileName)) return fileName;
477
+ if (svgFiles.has(fileName)) return { svg: fileName };
478
+ return { missing: fileName };
479
+ }
480
+ if (!ref.includes("/") && !ref.includes(":") && !ref.endsWith(".md")) {
481
+ for (const ext of [".md", ".yaml", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".html"]) {
482
+ if (textFiles.has(ref + ext) || artifactFiles.has(ref + ext)) return ref + ext;
483
+ }
484
+ }
485
+ return null;
486
+ };
487
+
488
+ for (const task of tasks) {
489
+ for (const packet of task.packets) {
490
+ const doc = packet.document;
491
+ const packetId = doc.packet_id;
492
+ const refs = stringArr(doc.evidence_refs).map((ref) => [ref, packet]);
493
+ for (const criterion of contractCriteria(doc)) {
494
+ for (const ref of stringArr(criterion.evidence_refs)) refs.push([ref, packet]);
495
+ }
496
+ for (const [ref, packet] of refs) {
497
+ const file = resolveRefToFile(ref);
498
+ if (typeof file === "string" && addFile(file, packetId, "ref")) continue;
499
+ if (file && typeof file === "object" && file.svg) {
500
+ skippedBinary.push({ source_path: packet.source_path, ref, category: "svg-active-content" });
501
+ continue;
502
+ }
503
+ if (file && typeof file === "object" && file.missing && existsSync(join(ROOT, ".contract-engineering", "evidence", file.missing))) {
504
+ // File exists on disk but isn't in our collectable set (e.g. .svg or unknown type).
505
+ const missingExt = extOf(file.missing);
506
+ if (missingExt === ".svg") {
507
+ skippedBinary.push({ source_path: packet.source_path, ref, category: "svg-active-content" });
508
+ } else {
509
+ skippedBinary.push({ source_path: packet.source_path, ref, category: "unsupported-type" });
510
+ }
511
+ continue;
512
+ }
513
+ const category = categorizeRef(ref, "evidence");
514
+ warnings.push({ source_path: packet.source_path, category, field: "evidence_refs", ref, message: `unresolved evidence ref "${ref}" (${category})` });
515
+ }
516
+ for (const name of evidenceFiles) {
517
+ if (name.startsWith(`${packetId}-EV`) || name.startsWith(`${packetId}-REV`)) {
518
+ addFile(name, packetId, "convention");
519
+ }
520
+ }
521
+ }
522
+ }
523
+
524
+ const evidence = [...records.values()]
525
+ .map((record) => ({ ...record, project_id: projectId, packet_ids: [...record.packet_ids] }))
526
+ .sort((a, b) => a.source_path.localeCompare(b.source_path));
527
+ const unlinked = evidenceFiles.filter((name) => !linkedFiles.has(`.contract-engineering/evidence/${name}`));
528
+ return { evidence, skippedBinary, unlinked };
529
+ }
530
+
531
+ /**
532
+ * Collect handoff records from handoffs/*.yaml, linking each to the packets
533
+ * its document names (packet_id or batch packet_ids) plus any packet whose
534
+ * handoff_ref points at the file. The "*-REVIEW.md" receiver review is
535
+ * embedded in the document; the content hash covers YAML plus review.
536
+ */
537
+ export function collectHandoffs(tasks, { projectId = DEFAULTS.projectId, warnings = [] } = {}) {
538
+ const packetIds = new Set(tasks.flatMap((task) => task.packets.map((packet) => packet.document.packet_id)));
539
+ const handoffFiles = listCeDir("handoffs").filter((name) => name.endsWith(".yaml"));
540
+ const refLinks = new Map();
541
+
542
+ for (const task of tasks) {
543
+ for (const packet of task.packets) {
544
+ const ref = packet.document.handoff_ref;
545
+ if (typeof ref !== "string" || ref.length === 0) continue;
546
+ let sourcePath = null;
547
+ if (ref.startsWith(".contract-engineering/handoffs/") && ref.endsWith(".yaml")) {
548
+ sourcePath = ref;
549
+ } else if (!ref.includes("/") && !ref.includes(":") && !ref.endsWith(".md")) {
550
+ sourcePath = `.contract-engineering/handoffs/${ref}.yaml`;
551
+ }
552
+ if (sourcePath && existsSync(join(ROOT, sourcePath))) {
553
+ if (!refLinks.has(sourcePath)) refLinks.set(sourcePath, new Set());
554
+ refLinks.get(sourcePath).add(packet.document.packet_id);
555
+ } else {
556
+ const category = categorizeRef(ref, "handoffs");
557
+ warnings.push({ source_path: packet.source_path, category, field: "handoff_ref", ref, message: `unresolved handoff_ref "${ref}" (${category})` });
558
+ }
559
+ }
560
+ }
561
+
562
+ const handoffs = [];
563
+ const unlinked = [];
564
+ for (const name of handoffFiles) {
565
+ const sourcePath = `.contract-engineering/handoffs/${name}`;
566
+ const yamlContent = readFileSync(join(ROOT, sourcePath), "utf8");
567
+ let document;
568
+ try {
569
+ document = parseCeFile(sourcePath, yamlContent).document;
570
+ } catch (error) {
571
+ const message = error instanceof Error ? error.message : String(error);
572
+ warnings.push({ source_path: sourcePath, category: "invalid-yaml", message: `handoff is not valid YAML: ${message}` });
573
+ continue;
574
+ }
575
+
576
+ const packetIdSet = new Set();
577
+ const declared = [document.packet_id, ...(Array.isArray(document.packet_ids) ? document.packet_ids : [])];
578
+ for (const pid of declared) {
579
+ if (typeof pid !== "string" || pid.length === 0) continue;
580
+ if (packetIds.has(pid)) packetIdSet.add(pid);
581
+ else warnings.push({ source_path: sourcePath, category: "handoff-unknown-packet", message: `handoff references packet "${pid}", which is not in this workspace` });
582
+ }
583
+ for (const pid of refLinks.get(sourcePath) ?? []) packetIdSet.add(pid);
584
+ if (packetIdSet.size === 0) {
585
+ unlinked.push(sourcePath);
586
+ continue;
587
+ }
588
+
589
+ const reviewName = `${name.replace(/\.yaml$/, "")}-REVIEW.md`;
590
+ let review = null;
591
+ if (listCeDir("handoffs").includes(reviewName)) {
592
+ review = {
593
+ source_path: `.contract-engineering/handoffs/${reviewName}`,
594
+ content: readFileSync(join(ROOT, ".contract-engineering", "handoffs", reviewName), "utf8"),
595
+ };
596
+ }
597
+ handoffs.push({
598
+ project_id: projectId,
599
+ source_path: sourcePath,
600
+ content_hash: sha256(yamlContent + (review ? review.content : "")),
601
+ document: review ? { ...document, review } : document,
602
+ packet_ids: [...packetIdSet].sort(),
603
+ });
604
+ }
605
+ handoffs.sort((a, b) => a.source_path.localeCompare(b.source_path));
606
+ return { handoffs, unlinked };
607
+ }
608
+
609
+ /**
610
+ * Split tasks into request-sized chunks. A task's packets may span chunks; the
611
+ * task header repeats per chunk and the importer's task upsert is idempotent.
612
+ */
613
+ export function chunkTasks(tasks, maxBytes = DEFAULTS.chunkBytes) {
614
+ const chunks = [];
615
+ let current = [];
616
+ let size = 0;
617
+ for (const task of tasks) {
618
+ for (const packet of task.packets) {
619
+ const packetSize = Buffer.byteLength(JSON.stringify(packet));
620
+ if (current.length > 0 && size + packetSize > maxBytes) {
621
+ chunks.push(current);
622
+ current = [];
623
+ size = 0;
624
+ }
625
+ current.push({ task, packet });
626
+ size += packetSize;
627
+ }
628
+ }
629
+ if (current.length > 0) chunks.push(current);
630
+ return chunks.map((entries) => {
631
+ const grouped = new Map();
632
+ for (const { task, packet } of entries) {
633
+ if (!grouped.has(task.id)) grouped.set(task.id, { ...task, packets: [] });
634
+ grouped.get(task.id).packets.push(packet);
635
+ }
636
+ return { dry_run: false, tasks: [...grouped.values()] };
637
+ });
638
+ }
639
+
640
+ /**
641
+ * Split evidence and handoff records into request-sized chunks. Each chunk can
642
+ * stand alone: the importer upserts each record against the packets that
643
+ * already exist.
644
+ */
645
+ export function chunkRecords(evidence, handoffs, maxBytes = DEFAULTS.chunkBytes) {
646
+ const items = [
647
+ ...evidence.map((record) => ({ kind: "evidence", record })),
648
+ ...handoffs.map((record) => ({ kind: "handoffs", record })),
649
+ ];
650
+ const chunks = [];
651
+ let current = null;
652
+ for (const item of items) {
653
+ const size = Buffer.byteLength(JSON.stringify(item.record));
654
+ if (current && current.size + size > maxBytes) {
655
+ chunks.push(current);
656
+ current = null;
657
+ }
658
+ if (!current) current = { evidence: [], handoffs: [], size: 0 };
659
+ current[item.kind].push(item.record);
660
+ current.size += size;
661
+ }
662
+ if (current && current.evidence.length + current.handoffs.length > 0) chunks.push(current);
663
+ return chunks.map(({ evidence: ev, handoffs: ho }) => ({ dry_run: false, tasks: [], evidence: ev, handoffs: ho }));
664
+ }
665
+
666
+ // ---------- Task Master write-back (state -> YAML) ----------
667
+
668
+ /**
669
+ * Rewrite the top-level `state`, `owner`, and `claim_timestamp` lines of a
670
+ * work-packet file. Only column-0 keys are touched, so nested keys, lists,
671
+ * and comments survive; missing keys are appended. Values are JSON-quoted.
672
+ */
673
+ export function applyWriteBack(content, updates) {
674
+ const wanted = Object.keys(updates);
675
+ if (wanted.length === 0) return content;
676
+ const hadTrailingNewline = content.endsWith("\n");
677
+ const lines = content.split("\n");
678
+ if (hadTrailingNewline) lines.pop();
679
+ const seen = new Set();
680
+ const rewritten = lines.map((line) => {
681
+ const match = line.match(/^(state|owner|claim_timestamp):/);
682
+ if (!match || !(match[1] in updates)) return line;
683
+ seen.add(match[1]);
684
+ return `${match[1]}: ${JSON.stringify(updates[match[1]])}`;
685
+ });
686
+ for (const key of wanted) {
687
+ if (!seen.has(key)) rewritten.push(`${key}: ${JSON.stringify(updates[key])}`);
688
+ }
689
+ return rewritten.join("\n") + (hadTrailingNewline ? "\n" : "");
690
+ }
691
+
692
+ /**
693
+ * Compare local work-packet records with Task Master's stored state and plan
694
+ * YAML write-backs. Four outcomes per packet:
695
+ * - unchanged locally since the last import while Task Master moved it: plan
696
+ * a write-back of Task Master's state/owner/claim_timestamp;
697
+ * - edited locally while Task Master still holds the imported state: the
698
+ * local edit wins and imports as usual;
699
+ * - edited locally while Task Master moved it, but the local state already
700
+ * matches Task Master's current state: reconcile lifecycle metadata and
701
+ * import the local document;
702
+ * - edited locally AND moved in Task Master: a conflict; the packet is
703
+ * reported and skipped so neither side is lost.
704
+ */
705
+ function statusWriteBackUpdates(remote, document) {
706
+ const updates = {};
707
+ const localState = typeof document.state === "string" ? document.state.toLowerCase() : "";
708
+ const ceState = TM_TO_CE_STATE[remote.state];
709
+ if (ceState && remote.state !== localState) updates.state = ceState;
710
+ if (
711
+ (typeof remote.owner === "string" || remote.owner === null) &&
712
+ remote.owner !== (document.owner ?? null)
713
+ ) {
714
+ updates.owner = remote.owner;
715
+ }
716
+ if (typeof remote.claim_timestamp === "string" || remote.claim_timestamp === null) {
717
+ const localTime = typeof document.claim_timestamp === "string"
718
+ ? Date.parse(document.claim_timestamp)
719
+ : null;
720
+ const remoteTime = typeof remote.claim_timestamp === "string"
721
+ ? Date.parse(remote.claim_timestamp)
722
+ : null;
723
+ if (localTime !== remoteTime) updates.claim_timestamp = remote.claim_timestamp;
724
+ }
725
+ return updates;
726
+ }
727
+
728
+ export function planPacketWriteBacks(localPackets, remoteStatus) {
729
+ const bySourcePath = new Map(
730
+ remoteStatus
731
+ .filter((entry) => typeof entry.ce_source_path === "string")
732
+ .map((entry) => [entry.ce_source_path, entry]),
733
+ );
734
+ const writeBacks = [];
735
+ const conflicts = [];
736
+ for (const packet of localPackets) {
737
+ const remote = bySourcePath.get(packet.source_path);
738
+ if (!remote) continue;
739
+ const document = packet.document ?? {};
740
+ const localState = typeof document.state === "string" ? document.state.toLowerCase() : "";
741
+ if (packet.content_hash === remote.ce_content_hash) {
742
+ if (!TM_TO_CE_STATE[remote.state]) continue;
743
+ const updates = statusWriteBackUpdates(remote, document);
744
+ if (Object.keys(updates).length > 0) {
745
+ writeBacks.push({
746
+ source_path: packet.source_path,
747
+ ce_id: remote.ce_id,
748
+ remote_state: remote.state,
749
+ updates,
750
+ });
751
+ }
752
+ } else if (
753
+ typeof remote.imported_state === "string" &&
754
+ remote.state !== remote.imported_state.toLowerCase()
755
+ ) {
756
+ if (localState === remote.state && TM_TO_CE_STATE[remote.state]) {
757
+ const updates = statusWriteBackUpdates(remote, document);
758
+ if (Object.keys(updates).length > 0) {
759
+ writeBacks.push({
760
+ source_path: packet.source_path,
761
+ ce_id: remote.ce_id,
762
+ remote_state: remote.state,
763
+ updates,
764
+ });
765
+ }
766
+ } else {
767
+ conflicts.push({
768
+ source_path: packet.source_path,
769
+ ce_id: remote.ce_id,
770
+ local_state: typeof document.state === "string" ? document.state : "(none)",
771
+ remote_state: remote.state,
772
+ });
773
+ }
774
+ }
775
+ }
776
+ return { writeBacks, conflicts };
777
+ }
778
+
779
+ // ---------- format check (local only, printed first by --dry-run) ----------
780
+
781
+ // work-packets is the only required folder; the others are sidecar/record
782
+ // folders whose absence is informational (a workspace may use none of them).
783
+ const REQUIRED_CE_DIRS = ["work-packets"];
784
+ const OPTIONAL_CE_DIRS = ["decisions", "data-gates", "threat-models", "evidence", "handoffs"];
785
+
786
+ /**
787
+ * Scan the workspace for layout problems that would make the import fail or
788
+ * import less than expected. Purely local: it needs no token and no API call.
789
+ */
790
+ export function checkWorkspaceFormat(files) {
791
+ const findings = [];
792
+ let protocolVersion = null;
793
+
794
+ const lockPath = join(CE_DIR, "protocol.lock.yaml");
795
+ if (existsSync(lockPath)) {
796
+ try {
797
+ const lock = yaml.load(readFileSync(lockPath, "utf8"));
798
+ protocolVersion = lock?.protocol?.release ?? null;
799
+ if (!protocolVersion) findings.push("protocol.lock.yaml has no protocol.release version");
800
+ } catch {
801
+ findings.push("protocol.lock.yaml is not valid YAML");
802
+ }
803
+ } else {
804
+ findings.push("missing protocol.lock.yaml");
805
+ }
806
+ for (const dir of REQUIRED_CE_DIRS) {
807
+ if (!existsSync(join(CE_DIR, dir))) findings.push(`missing folder: .contract-engineering/${dir}`);
808
+ }
809
+ const optionalDirs = OPTIONAL_CE_DIRS.filter((dir) => !existsSync(join(CE_DIR, dir)));
810
+
811
+ const missingFields = [];
812
+ const badStates = [];
813
+ for (const [sourcePath, content] of [...files.entries()].sort(([a], [b]) => a.localeCompare(b))) {
814
+ let doc;
815
+ try {
816
+ doc = yaml.load(content);
817
+ } catch {
818
+ continue; // buildTaskPayloads already reports YAML parse failures
819
+ }
820
+ if (!doc || typeof doc !== "object" || Array.isArray(doc)) continue;
821
+ for (const field of ["packet_id", "task_id", "title", "state"]) {
822
+ if (typeof doc[field] !== "string" || doc[field].length === 0) {
823
+ missingFields.push(`${sourcePath}: missing "${field}"`);
824
+ }
825
+ }
826
+ if (typeof doc.state === "string" && !CE_STATES.includes(doc.state.toLowerCase())) {
827
+ badStates.push(`${sourcePath}: unknown state "${doc.state}"`);
828
+ }
829
+ }
830
+
831
+ // Informational: legacy Markdown sidecars and data-gate id field variants.
832
+ const legacyMarkdown = listCeDir("decisions").concat(listCeDir("data-gates"), listCeDir("threat-models"))
833
+ .filter((name) => name.endsWith(".md")).length;
834
+ const gateIdFields = { gate_id: 0, data_gate_id: 0, missing: 0 };
835
+ for (const name of listCeDir("data-gates").filter((n) => n.endsWith(".yaml"))) {
836
+ try {
837
+ const doc = yaml.load(readFileSync(join(CE_DIR, "data-gates", name), "utf8"));
838
+ if (doc && typeof doc === "object" && !Array.isArray(doc)) {
839
+ if (doc.gate_id !== undefined) gateIdFields.gate_id++;
840
+ else if (doc.data_gate_id !== undefined) gateIdFields.data_gate_id++;
841
+ else gateIdFields.missing++;
842
+ }
843
+ } catch {
844
+ // the build step reports unreadable files
845
+ }
846
+ }
847
+
848
+ return { protocolVersion, findings, optionalDirs, missingFields, badStates, legacyMarkdown, gateIdFields };
849
+ }
850
+
851
+ // ---------- reporting ----------
852
+
853
+ function summarizeIds(ids, max = 4) {
854
+ const sorted = [...ids].sort();
855
+ const shown = sorted.slice(0, max).join(", ");
856
+ return sorted.length > max ? `${shown} (+${sorted.length - max} more)` : shown;
857
+ }
858
+
859
+ export function packetIdOf(warning) {
860
+ return (warning.source_path ?? "")
861
+ .replace(".contract-engineering/archive/work-packets/", "")
862
+ .replace(".contract-engineering/work-packets/", "")
863
+ .replace(/\.yaml$/, "");
864
+ }
865
+
866
+ function sidecarLinkStats(tasks) {
867
+ const stats = {
868
+ decisions: { links: 0, distinct: new Set() },
869
+ data_gates: { links: 0, distinct: new Set() },
870
+ threat_models: { links: 0, distinct: new Set() },
871
+ };
872
+ for (const task of tasks) {
873
+ for (const packet of task.packets) {
874
+ for (const field of ["decisions", "data_gates", "threat_models"]) {
875
+ for (const record of packet[field]) {
876
+ stats[field].links++;
877
+ stats[field].distinct.add(record.source_path);
878
+ }
879
+ }
880
+ }
881
+ }
882
+ return stats;
883
+ }
884
+
885
+ function printReport({ warnings, conventionLinks, evidenceInfo, handoffInfo, tasks }) {
886
+ const lines = ["report:"];
887
+
888
+ const byCategory = new Map();
889
+ for (const warning of warnings) {
890
+ if (!byCategory.has(warning.category)) byCategory.set(warning.category, []);
891
+ byCategory.get(warning.category).push(warning);
892
+ }
893
+ for (const [category, items] of [...byCategory.entries()].sort(([a], [b]) => a.localeCompare(b))) {
894
+ lines.push(` unresolved refs [${category}]: ${items.length} packets=${summarizeIds(items.map(packetIdOf))}`);
895
+ }
896
+
897
+ const byField = new Map();
898
+ for (const link of conventionLinks) {
899
+ if (!byField.has(link.field)) byField.set(link.field, []);
900
+ byField.get(link.field).push(link);
901
+ }
902
+ for (const [field, links] of [...byField.entries()].sort(([a], [b]) => a.localeCompare(b))) {
903
+ lines.push(` linked by id convention [${field}]: ${links.length} packets=${summarizeIds(links.map((link) => link.packet_id))}`);
904
+ }
905
+
906
+ if (evidenceInfo.skippedBinary.length) {
907
+ lines.push(` skipped evidence refs: ${evidenceInfo.skippedBinary.length} refs=${summarizeIds(evidenceInfo.skippedBinary.map((s) => s.ref))}`);
908
+ const byCategory = new Map();
909
+ for (const s of evidenceInfo.skippedBinary) {
910
+ const cat = s.category ?? "unknown";
911
+ if (!byCategory.has(cat)) byCategory.set(cat, []);
912
+ byCategory.get(cat).push(s.ref);
913
+ }
914
+ for (const [cat, refs] of [...byCategory.entries()].sort()) {
915
+ lines.push(` ${cat}: ${refs.length} refs=${summarizeIds(refs)}`);
916
+ }
917
+ }
918
+ if (evidenceInfo.unlinked.length) {
919
+ lines.push(` evidence files not linked to any packet: ${evidenceInfo.unlinked.length} files=${summarizeIds(evidenceInfo.unlinked)}`);
920
+ }
921
+ if (handoffInfo.unlinked.length) {
922
+ lines.push(` handoff files not linked to any packet: ${handoffInfo.unlinked.length} files=${summarizeIds(handoffInfo.unlinked)}`);
923
+ }
924
+
925
+ const stats = sidecarLinkStats(tasks);
926
+ for (const [field, stat] of Object.entries(stats)) {
927
+ lines.push(` ${field}: ${stat.links} packet links, ${stat.distinct.size} distinct records`);
928
+ }
929
+ const evidenceLinks = evidenceInfo.evidence.reduce((sum, record) => sum + record.packet_ids.length, 0);
930
+ const handoffLinks = handoffInfo.handoffs.reduce((sum, record) => sum + record.packet_ids.length, 0);
931
+ lines.push(` evidence: ${evidenceLinks} packet links, ${evidenceInfo.evidence.length} distinct records`);
932
+ lines.push(` handoffs: ${handoffLinks} packet links, ${handoffInfo.handoffs.length} distinct records`);
933
+
934
+ process.stdout.write(lines.join("\n") + "\n");
935
+ }
936
+
937
+ function printFormatCheck(format) {
938
+ const lines = ["format check:"];
939
+ lines.push(` protocol lock version: ${format.protocolVersion ?? "unknown"}`);
940
+ for (const finding of format.findings) lines.push(` problem: ${finding}`);
941
+ for (const problem of format.missingFields) lines.push(` problem: ${problem}`);
942
+ for (const problem of format.badStates) lines.push(` problem: ${problem}`);
943
+ if (format.optionalDirs.length > 0) {
944
+ lines.push(` folders not present (no such records): ${format.optionalDirs.join(", ")}`);
945
+ }
946
+ lines.push(` legacy Markdown sidecars: ${format.legacyMarkdown}`);
947
+ lines.push(` data-gate id fields: gate_id=${format.gateIdFields.gate_id} data_gate_id=${format.gateIdFields.data_gate_id} missing=${format.gateIdFields.missing}`);
948
+ process.stdout.write(lines.join("\n") + "\n");
949
+ }
950
+
951
+ // ---------- workstream order (local, printed by --dry-run) ----------
952
+
953
+ // A workstream is one CE task; terminal packet states count as finished.
954
+ const TERMINAL_PACKET_STATES = new Set(["complete", "cancelled"]);
955
+
956
+ // A workstream holds the one-workstream slot only while one of its packets
957
+ // is actually in flight; resting tasks (planned + terminal mixtures) do
958
+ // not block claims. Mirrors ACTIVE_PACKET_STATES in the API's gate-service.
959
+ const ACTIVE_PACKET_STATES = new Set(["claimed", "design_review", "ready", "implementing", "validation", "handoff"]);
960
+
961
+ /**
962
+ * One CE task at a time per project: Task Master blocks claims in a task
963
+ * while another task in the same project has packets in flight, and blocks
964
+ * claims on packets whose dependencies are not finished. This local check
965
+ * mirrors those rules so --dry-run surfaces the same ordering before
966
+ * anything is written. Partially finished tasks (terminal + planned
967
+ * mixtures) are reported as resting, not blocking.
968
+ */
969
+ export function checkWorkstreamOrder(tasks) {
970
+ const stateOf = new Map();
971
+ for (const task of tasks) {
972
+ for (const packet of task.packets) {
973
+ stateOf.set(String(packet.document.packet_id), String(packet.document.state ?? "").toLowerCase());
974
+ }
975
+ }
976
+
977
+ const inProgress = [];
978
+ const partiallyFinished = [];
979
+ for (const task of tasks) {
980
+ const states = task.packets.map((packet) => String(packet.document.state ?? "").toLowerCase());
981
+ if (states.length === 0) continue;
982
+ const inFlight = states.filter((state) => ACTIVE_PACKET_STATES.has(state)).length;
983
+ if (inFlight > 0) {
984
+ inProgress.push({ task_id: task.id, in_flight_packets: inFlight });
985
+ continue;
986
+ }
987
+ const terminal = states.filter((state) => TERMINAL_PACKET_STATES.has(state)).length;
988
+ if (terminal > 0 && terminal < states.length) {
989
+ partiallyFinished.push({
990
+ task_id: task.id,
991
+ terminal_packets: terminal,
992
+ planned_packets: states.length - terminal,
993
+ });
994
+ }
995
+ }
996
+
997
+ const unmetDeps = [];
998
+ for (const task of tasks) {
999
+ for (const packet of task.packets) {
1000
+ const deps = Array.isArray(packet.document.dependencies)
1001
+ ? packet.document.dependencies.filter((dep) => typeof dep === "string")
1002
+ : [];
1003
+ const unmet = deps.filter((dep) => {
1004
+ const state = stateOf.get(dep);
1005
+ return state === undefined || !TERMINAL_PACKET_STATES.has(state);
1006
+ });
1007
+ if (unmet.length > 0) unmetDeps.push({ packet_id: packet.document.packet_id, unmet });
1008
+ }
1009
+ }
1010
+ return { inProgress, partiallyFinished, unmetDeps };
1011
+ }
1012
+
1013
+ function printWorkstreamOrder(order) {
1014
+ const lines = ["workstream order (one CE task in progress per project):"];
1015
+ if (order.inProgress.length === 0 && order.partiallyFinished.length === 0 && order.unmetDeps.length === 0) {
1016
+ lines.push(" no in-progress tasks, no unmet dependencies");
1017
+ } else {
1018
+ for (const task of order.inProgress) {
1019
+ lines.push(` in progress: ${task.task_id} (${task.in_flight_packets} packets in flight; claims in other tasks of this project will be blocked)`);
1020
+ }
1021
+ for (const task of order.partiallyFinished) {
1022
+ lines.push(` partially finished (resting, not blocking claims): ${task.task_id} (${task.terminal_packets} terminal, ${task.planned_packets} planned)`);
1023
+ }
1024
+ for (const dep of order.unmetDeps.slice(0, 10)) {
1025
+ lines.push(` waiting on dependencies: ${dep.packet_id} <- ${summarizeIds(dep.unmet)}`);
1026
+ }
1027
+ if (order.unmetDeps.length > 10) {
1028
+ lines.push(` (+${order.unmetDeps.length - 10} more packets with unmet dependencies)`);
1029
+ }
1030
+ }
1031
+ process.stdout.write(lines.join("\n") + "\n");
1032
+ }
1033
+
1034
+ // ---------- token handling ----------
1035
+
1036
+ function encryptionKey() {
1037
+ const fromEnv = process.env.CE_SYNC_CONFIG_KEY ?? process.env.GATEWAY_CONFIG_KEY;
1038
+ if (fromEnv) return Buffer.from(fromEnv, "utf8");
1039
+ if (!existsSync(DEFAULTS.keyPath)) {
1040
+ mkdirSync(dirname(DEFAULTS.keyPath), { recursive: true });
1041
+ const key = randomBytes(32).toString("hex");
1042
+ writeFileSync(DEFAULTS.keyPath, key + "\n", { mode: 0o600 });
1043
+ chmodSync(DEFAULTS.keyPath, 0o600);
1044
+ process.stderr.write(`note: generated a new local key at ${DEFAULTS.keyPath} (set CE_SYNC_CONFIG_KEY to use an explicit key)\n`);
1045
+ }
1046
+ return Buffer.from(readFileSync(DEFAULTS.keyPath, "utf8").trim(), "utf8");
1047
+ }
1048
+
1049
+ function encryptToken(plaintext) {
1050
+ const salt = randomBytes(16);
1051
+ const iv = randomBytes(12);
1052
+ const key = scryptSync(encryptionKey(), salt, 32);
1053
+ const cipher = createCipheriv("aes-256-gcm", key, iv);
1054
+ const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
1055
+ return {
1056
+ version: 1,
1057
+ salt: salt.toString("base64"),
1058
+ iv: iv.toString("base64"),
1059
+ tag: cipher.getAuthTag().toString("base64"),
1060
+ data: ciphertext.toString("base64"),
1061
+ };
1062
+ }
1063
+
1064
+ function decryptToken(record) {
1065
+ const key = scryptSync(encryptionKey(), Buffer.from(record.salt, "base64"), 32);
1066
+ const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(record.iv, "base64"));
1067
+ decipher.setAuthTag(Buffer.from(record.tag, "base64"));
1068
+ return Buffer.concat([decipher.update(Buffer.from(record.data, "base64")), decipher.final()]).toString("utf8");
1069
+ }
1070
+
1071
+ function loadStoredRefreshToken() {
1072
+ if (!existsSync(DEFAULTS.tokenPath)) return null;
1073
+ try {
1074
+ const parsed = JSON.parse(readFileSync(DEFAULTS.tokenPath, "utf8"));
1075
+ return typeof parsed === "object" && parsed.data ? decryptToken(parsed) : null;
1076
+ } catch {
1077
+ return null;
1078
+ }
1079
+ }
1080
+
1081
+ function storeRefreshToken(refreshToken) {
1082
+ mkdirSync(dirname(DEFAULTS.tokenPath), { recursive: true });
1083
+ writeFileSync(DEFAULTS.tokenPath, JSON.stringify(encryptToken(refreshToken), null, 2) + "\n", { mode: 0o600 });
1084
+ chmodSync(DEFAULTS.tokenPath, 0o600);
1085
+ }
1086
+
1087
+ async function tokenRequest(body) {
1088
+ const response = await fetch(`${DEFAULTS.issuer}/protocol/openid-connect/token`, {
1089
+ method: "POST",
1090
+ headers: { "Content-Type": "application/x-www-form-urlencoded" },
1091
+ body: new URLSearchParams(body).toString(),
1092
+ });
1093
+ const text = await response.text();
1094
+ let json;
1095
+ try { json = JSON.parse(text); } catch { json = null; }
1096
+ if (!response.ok) {
1097
+ const description = json?.error_description ?? text.slice(0, 200);
1098
+ throw new Error(`Token endpoint returned ${response.status}: ${description}`);
1099
+ }
1100
+ return json;
1101
+ }
1102
+
1103
+ async function refreshTokenGrant(refreshToken) {
1104
+ const json = await tokenRequest({
1105
+ grant_type: "refresh_token",
1106
+ refresh_token: refreshToken,
1107
+ client_id: DEFAULTS.clientId,
1108
+ });
1109
+ if (json.refresh_token) storeRefreshToken(json.refresh_token);
1110
+ return json.access_token;
1111
+ }
1112
+
1113
+ // offline_access keeps the stored refresh token valid until revoked, so
1114
+ // repeat syncs do not need a fresh interactive login.
1115
+ export function deviceFlowScope(orgScope = DEFAULTS.orgScope) {
1116
+ return `openid offline_access profile org:${orgScope}:packets:read org:${orgScope}:packets:write`;
1117
+ }
1118
+
1119
+ export function isAuthorizationPendingError(error) {
1120
+ return error instanceof Error &&
1121
+ /\bauthorization_pending\b|the authorization request is still pending/i.test(error.message);
1122
+ }
1123
+
1124
+ // Keycloak enforces PKCE on the device flow for public clients (a request
1125
+ // without code_challenge_method fails with invalid_request), so the device
1126
+ // authorization request carries an S256 challenge and the token request
1127
+ // carries the matching verifier.
1128
+ export function pkcePair() {
1129
+ const verifier = randomBytes(32).toString("base64url");
1130
+ const challenge = createHash("sha256").update(verifier).digest("base64url");
1131
+ return { verifier, challenge, method: "S256" };
1132
+ }
1133
+
1134
+ async function deviceFlow() {
1135
+ const discovery = await fetch(`${DEFAULTS.issuer}/.well-known/openid-configuration`);
1136
+ const cfg = await discovery.json();
1137
+ const deviceEndpoint = cfg.device_authorization_endpoint;
1138
+ if (!deviceEndpoint) throw new Error("The issuer does not advertise a device authorization endpoint.");
1139
+
1140
+ const pkce = pkcePair();
1141
+ const response = await fetch(deviceEndpoint, {
1142
+ method: "POST",
1143
+ headers: { "Content-Type": "application/x-www-form-urlencoded" },
1144
+ body: new URLSearchParams({
1145
+ client_id: DEFAULTS.clientId,
1146
+ scope: deviceFlowScope(),
1147
+ code_challenge: pkce.challenge,
1148
+ code_challenge_method: pkce.method,
1149
+ }).toString(),
1150
+ });
1151
+ const text = await response.text();
1152
+ let json;
1153
+ try { json = JSON.parse(text); } catch { json = null; }
1154
+ if (!response.ok) {
1155
+ if (json?.error === "unauthorized_client") {
1156
+ throw new Error(
1157
+ "Keycloak rejected the device grant for this client " +
1158
+ "(OAuth 2.0 Device Authorization Grant is disabled). " +
1159
+ "See docs/keycloak-device-grant-request.md, or pass a bearer token via --token / CE_SYNC_TOKEN.",
1160
+ );
1161
+ }
1162
+ throw new Error(`Device authorization failed (${response.status}): ${text.slice(0, 200)}`);
1163
+ }
1164
+
1165
+ process.stderr.write(`\nOpen ${json.verification_uri ?? json.verification_uri_complete} and approve code: ${json.user_code}\n`);
1166
+ const intervalSeconds = json.interval ?? 5;
1167
+ const deadline = Date.now() + (json.expires_in ?? 600) * 1000;
1168
+ while (Date.now() < deadline) {
1169
+ await new Promise((resolve) => setTimeout(resolve, intervalSeconds * 1000));
1170
+ try {
1171
+ const tokens = await tokenRequest({
1172
+ grant_type: "urn:ietf:params:oauth:grant-type:device_code",
1173
+ device_code: json.device_code,
1174
+ client_id: DEFAULTS.clientId,
1175
+ code_verifier: pkce.verifier,
1176
+ });
1177
+ if (tokens.refresh_token) storeRefreshToken(tokens.refresh_token);
1178
+ return tokens.access_token;
1179
+ } catch (error) {
1180
+ if (isAuthorizationPendingError(error)) continue;
1181
+ throw error;
1182
+ }
1183
+ }
1184
+ throw new Error("Device authorization timed out.");
1185
+ }
1186
+
1187
+ async function resolveToken(cliToken) {
1188
+ if (cliToken) return cliToken;
1189
+ if (process.env.CE_SYNC_TOKEN) return process.env.CE_SYNC_TOKEN;
1190
+ const stored = loadStoredRefreshToken();
1191
+ if (stored) {
1192
+ try { return await refreshTokenGrant(stored); } catch { /* fall through to device flow */ }
1193
+ }
1194
+ return deviceFlow();
1195
+ }
1196
+
1197
+ // ---------- API call ----------
1198
+
1199
+ async function callImport(apiUrl, token, payload) {
1200
+ // The chunk travels in the POST body, not the query string: a 64 KB chunk
1201
+ // percent-encoded into a URL exceeds the API's request-line/header limit
1202
+ // (HTTP 431). tRPC reads batch inputs from the body as {"0": payload}.
1203
+ const response = await fetch(`${apiUrl}/ce.import?batch=1`, {
1204
+ method: "POST",
1205
+ headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
1206
+ body: JSON.stringify({ "0": payload }),
1207
+ });
1208
+ const text = await response.text();
1209
+ let body;
1210
+ try { body = JSON.parse(text); } catch {
1211
+ throw new Error(`API returned ${response.status} with a non-JSON body: ${text.slice(0, 200)}`);
1212
+ }
1213
+ const entry = Array.isArray(body) ? body[0] : body;
1214
+ if (entry?.error) {
1215
+ throw new Error(`ce.import failed: ${entry.error.message ?? JSON.stringify(entry.error)}`);
1216
+ }
1217
+ return entry.result?.data;
1218
+ }
1219
+
1220
+ /**
1221
+ * Task Master's stored state for the project's imported packets, used by the
1222
+ * write-back comparison. ce.packetStatus is a tRPC query, so the batched
1223
+ * input travels in the query string of a GET request.
1224
+ */
1225
+ async function fetchPacketStatus(apiUrl, token, projectId) {
1226
+ const input = encodeURIComponent(JSON.stringify({ "0": { project_id: projectId } }));
1227
+ const response = await fetch(`${apiUrl}/ce.packetStatus?batch=1&input=${input}`, {
1228
+ headers: { Authorization: `Bearer ${token}` },
1229
+ });
1230
+ const text = await response.text();
1231
+ let body;
1232
+ try { body = JSON.parse(text); } catch {
1233
+ throw new Error(`API returned ${response.status} with a non-JSON body: ${text.slice(0, 200)}`);
1234
+ }
1235
+ const entry = Array.isArray(body) ? body[0] : body;
1236
+ if (entry?.error) {
1237
+ throw new Error(`ce.packetStatus failed: ${entry.error.message ?? JSON.stringify(entry.error)}`);
1238
+ }
1239
+ const result = entry.result?.data;
1240
+ return Array.isArray(result) ? result : [];
1241
+ }
1242
+
1243
+ const SUMMARY_SECTIONS = ["tasks", "packets", "decisions", "data_gates", "threat_models", "evidence", "handoffs"];
1244
+
1245
+ function mergeSummary(total, chunk) {
1246
+ for (const section of SUMMARY_SECTIONS) {
1247
+ total[section].created += chunk[section].created;
1248
+ total[section].updated += chunk[section].updated;
1249
+ total[section].unchanged += chunk[section].unchanged;
1250
+ }
1251
+ total.errors.push(...chunk.errors);
1252
+ }
1253
+
1254
+ function printSummary(summary) {
1255
+ for (const section of SUMMARY_SECTIONS) {
1256
+ const s = summary[section];
1257
+ process.stdout.write(`${section.padEnd(14)} created=${s.created} updated=${s.updated} unchanged=${s.unchanged}\n`);
1258
+ }
1259
+ process.stdout.write(`errors ${summary.errors.length}\n`);
1260
+ for (const error of summary.errors) {
1261
+ process.stdout.write(` ${error.source_path}: ${error.message}\n`);
1262
+ }
1263
+ }
1264
+
1265
+ // ---------- main ----------
1266
+
1267
+ async function main() {
1268
+ const args = process.argv.slice(2);
1269
+ const dryRun = args.includes("--dry-run");
1270
+ const noWriteBack = args.includes("--no-write-back");
1271
+ const tokenFlag = args.find((arg, index) => args[index - 1] === "--token");
1272
+ // --project overrides the workspace folder-name default. PACKET_PROJECT_ID
1273
+ // already fed DEFAULTS.projectId at module load; a CLI flag wins over both.
1274
+ const projectFlag = args.find((arg, index) => args[index - 1] === "--project");
1275
+ const projectId = projectFlag ?? DEFAULTS.projectId;
1276
+ const files = collectWorkPacketFiles();
1277
+
1278
+ const { tasks, errors, warnings, conventionLinks } = buildTaskPayloads(files, { projectId });
1279
+ const evidenceInfo = collectEvidence(tasks, { projectId, warnings, conventionLinks });
1280
+ const handoffInfo = collectHandoffs(tasks, { projectId, warnings });
1281
+ const packetCount = tasks.reduce((sum, task) => sum + task.packets.length, 0);
1282
+ const archivedCount = tasks.reduce(
1283
+ (sum, task) => sum + task.packets.filter((packet) => packet.source_path.startsWith(".contract-engineering/archive/")).length,
1284
+ 0,
1285
+ );
1286
+ const archivedNote = archivedCount > 0 ? `, ${archivedCount} archived` : "";
1287
+ process.stdout.write(`CE records: ${tasks.length} tasks, ${packetCount} packets${archivedNote} (project: ${projectId})${dryRun ? " (dry run)" : ""}\n`);
1288
+ for (const error of errors) {
1289
+ process.stderr.write(` error ${error.source_path}: ${error.message}\n`);
1290
+ }
1291
+ if (dryRun) {
1292
+ printFormatCheck(checkWorkspaceFormat(files));
1293
+ printWorkstreamOrder(checkWorkstreamOrder(tasks));
1294
+ }
1295
+ printReport({ warnings, conventionLinks, evidenceInfo, handoffInfo, tasks });
1296
+
1297
+ // The format check and report above are local-only, so they still print
1298
+ // when the token cannot be resolved or the API is unreachable.
1299
+ const token = await resolveToken(tokenFlag);
1300
+
1301
+ // Write-back: Task Master transitions recorded since the last sync are
1302
+ // written into the work-packet YAML before the import so the files stay
1303
+ // authoritative. When both sides changed, local state matching Task Master's
1304
+ // current state reconciles lifecycle metadata; a state mismatch is skipped.
1305
+ let importTasks = tasks;
1306
+ let importEvidenceInfo = evidenceInfo;
1307
+ let importHandoffInfo = handoffInfo;
1308
+ if (!noWriteBack) {
1309
+ // Older deployed APIs do not expose ce.packetStatus; the sync still runs,
1310
+ // just without the write-back step.
1311
+ let status = [];
1312
+ try {
1313
+ status = await fetchPacketStatus(DEFAULTS.apiUrl, token, projectId);
1314
+ } catch (error) {
1315
+ const message = error instanceof Error ? error.message : String(error);
1316
+ process.stdout.write(`write-back skipped: ce.packetStatus unavailable (${message})
1317
+ `);
1318
+ }
1319
+ const localPackets = tasks.flatMap((task) => task.packets);
1320
+ const plan = planPacketWriteBacks(localPackets, status);
1321
+
1322
+ for (const writeBack of plan.writeBacks) {
1323
+ const fields = Object.keys(writeBack.updates).join(", ");
1324
+ const suffix = dryRun ? " (dry run)" : "";
1325
+ if (!dryRun) {
1326
+ const absolutePath = join(ROOT, writeBack.source_path);
1327
+ writeFileSync(absolutePath, applyWriteBack(readFileSync(absolutePath, "utf8"), writeBack.updates));
1328
+ }
1329
+ process.stdout.write(`write-back${suffix} ${writeBack.source_path}: ${fields} <- Task Master state "${writeBack.remote_state}"\n`);
1330
+ }
1331
+ for (const conflict of plan.conflicts) {
1332
+ process.stdout.write(`conflict ${conflict.source_path}: local edits ("${conflict.local_state}") and Task Master state "${conflict.remote_state}" both changed since the last sync; packet skipped\n`);
1333
+ }
1334
+
1335
+ if (plan.writeBacks.length > 0 && !dryRun) {
1336
+ // Re-read the rewritten files so the import carries the written-back
1337
+ // state and its fresh content hash.
1338
+ for (const sourcePath of files.keys()) {
1339
+ files.set(sourcePath, readFileSync(join(ROOT, sourcePath), "utf8"));
1340
+ }
1341
+ const rebuilt = buildTaskPayloads(files, { projectId });
1342
+ errors.push(...rebuilt.errors);
1343
+ importTasks = rebuilt.tasks;
1344
+ }
1345
+ if (plan.conflicts.length > 0) {
1346
+ const conflictPaths = new Set(plan.conflicts.map((conflict) => conflict.source_path));
1347
+ const kept = [];
1348
+ let droppedTasks = 0;
1349
+ for (const task of importTasks) {
1350
+ const packets = task.packets.filter((packet) => !conflictPaths.has(packet.source_path));
1351
+ if (packets.length === 0) { droppedTasks++; continue; }
1352
+ kept.push({ ...task, packets });
1353
+ }
1354
+ importTasks = kept;
1355
+ if (droppedTasks > 0) {
1356
+ process.stdout.write(`${droppedTasks} task(s) dropped from this sync because every packet conflicted\n`);
1357
+ }
1358
+ }
1359
+ if ((plan.writeBacks.length > 0 && !dryRun) || plan.conflicts.length > 0) {
1360
+ // Re-link evidence and handoffs against the packets that will actually
1361
+ // import; links to conflicted packets would fail the packet check.
1362
+ importEvidenceInfo = collectEvidence(importTasks, { projectId, warnings: [], conventionLinks: [] });
1363
+ importHandoffInfo = collectHandoffs(importTasks, { projectId, warnings: [] });
1364
+ }
1365
+ }
1366
+
1367
+ const total = {
1368
+ tasks: { created: 0, updated: 0, unchanged: 0 },
1369
+ packets: { created: 0, updated: 0, unchanged: 0 },
1370
+ decisions: { created: 0, updated: 0, unchanged: 0 },
1371
+ data_gates: { created: 0, updated: 0, unchanged: 0 },
1372
+ threat_models: { created: 0, updated: 0, unchanged: 0 },
1373
+ evidence: { created: 0, updated: 0, unchanged: 0 },
1374
+ handoffs: { created: 0, updated: 0, unchanged: 0 },
1375
+ errors: [...errors],
1376
+ };
1377
+
1378
+ let chunkIndex = 0;
1379
+ for (const chunk of chunkTasks(importTasks)) {
1380
+ const summary = await callImport(DEFAULTS.apiUrl, token, { ...chunk, dry_run: dryRun });
1381
+ mergeSummary(total, summary);
1382
+ chunkIndex++;
1383
+ process.stdout.write(`chunk ${chunkIndex}: ${summary.packets.created} created, ${summary.packets.updated} updated, ${summary.packets.unchanged} unchanged\n`);
1384
+ }
1385
+ for (const chunk of chunkRecords(importEvidenceInfo.evidence, importHandoffInfo.handoffs)) {
1386
+ const summary = await callImport(DEFAULTS.apiUrl, token, { ...chunk, dry_run: dryRun });
1387
+ mergeSummary(total, summary);
1388
+ chunkIndex++;
1389
+ process.stdout.write(`chunk ${chunkIndex}: evidence ${summary.evidence.created}/${summary.evidence.updated}/${summary.evidence.unchanged}, handoffs ${summary.handoffs.created}/${summary.handoffs.updated}/${summary.handoffs.unchanged} (created/updated/unchanged)\n`);
1390
+ }
1391
+
1392
+ printSummary(total);
1393
+ process.exit(total.errors.length > 0 ? 1 : 0);
1394
+ }
1395
+
1396
+ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
1397
+ main().catch((error) => {
1398
+ process.stderr.write(`ce-sync failed: ${error instanceof Error ? error.message : String(error)}\n`);
1399
+ process.exit(1);
1400
+ });
1401
+ }