@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.
- package/dist/ce-sync.mjs +1401 -0
- package/dist/main.js +43200 -0
- package/dist/main.js.map +7 -0
- package/dist/tm.js +2 -0
- package/package.json +38 -4
- package/README.md +0 -3
package/dist/ce-sync.mjs
ADDED
|
@@ -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
|
+
}
|