lazycodex-ai 5.0.0-beta.9 → 5.0.0

package/packages/shared-skills/skills/ulw-research/scripts/outcome.mjs

@@ -0,0 +1,250 @@
+// outcome.mjs - the per-run outcome manifest (`outcome.json`) and the closing briefing.
+// Manifest functions are pure (they return a new manifest); the briefing reads only the
+// manifest, the sources-ledger text, and an injected `now`. node: builtins only.
+
+import * as nodeFs from "node:fs"
+import { basename, dirname, join } from "node:path"
+
+import { DELIVERABLE_FORMATS, DELIVERABLE_STATUSES, GATE_NAMES, GATE_STATUSES, LANES } from "./contracts.mjs"
+import { MANIFEST_CODES, SCHEMA_VERSION, validateOutcomeManifest } from "./contracts.mjs"
+
+export const MANIFEST_FILENAME = "outcome.json"
+const MISSING = MANIFEST_CODES[0]
+const SESSION_STAMP = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})$/
+const SOURCE_LINE = /^\[(S|Source )\d+\]/
+const URL_PATTERN = /https?:\/\/[^\s)<>\]"'`]+/g
+const DRAFT_MARKER = "STATUS: draft"
+const DRAFT_SCAN_LINES = 5
+const REASON_REQUIRED = new Set(["blocked_capability", "skipped", "failed"])
+
+export class OutcomeError extends Error {
+	/** @param {string} code @param {string} message @param {readonly string[]} [allowed] */
+	constructor(code, message, allowed) {
+		super(message)
+		this.name = "OutcomeError"
+		this.code = code
+		if (allowed) this.allowed = [...allowed]
+	}
+}
+
+function assertOneOf(code, label, value, allowed) {
+	if (!allowed.includes(value)) {
+		throw new OutcomeError(code, `unknown ${label} ${JSON.stringify(value)}; allowed: ${allowed.join(", ")}`, allowed)
+	}
+}
+
+const clone = (manifest) => structuredClone(manifest)
+const isMissing = (error) => error?.code === "ENOENT" || error?.code === "ENOTDIR"
+
+function stamp(now) {
+	return (now ?? new Date()).toISOString()
+}
+
+/** Local wall-clock start time from a `YYYYMMDD-HHMMSS` session dir basename. */
+export function parseSessionStart(sessionDir) {
+	const match = SESSION_STAMP.exec(basename(sessionDir))
+	if (!match) throw new OutcomeError("invalid_session_dir", `session dir basename must be YYYYMMDD-HHMMSS: ${sessionDir}`)
+	const [y, mo, d, h, mi, s] = match.slice(1).map(Number)
+	const date = new Date(y, mo - 1, d, h, mi, s)
+	if (date.getMonth() !== mo - 1 || date.getDate() !== d || date.getHours() !== h) {
+		throw new OutcomeError("invalid_session_dir", `session dir basename is not a real local time: ${sessionDir}`)
+	}
+	return date
+}
+
+/** @param {{ sessionDir: string, promised: string[], lane: string|null, interview?: object|null, now?: Date }} input */
+export function initManifest({ sessionDir, promised, lane, interview = null, now }) {
+	const startedAt = parseSessionStart(sessionDir).toISOString()
+	if (lane !== null && lane !== undefined) assertOneOf("unknown_lane", "lane", lane, LANES)
+	const formats = [...new Set(promised)]
+	for (const format of formats) assertOneOf("unknown_format", "deliverable format", format, DELIVERABLE_FORMATS)
+	const updatedAt = stamp(now)
+	return {
+		schemaVersion: SCHEMA_VERSION,
+		sessionDir,
+		startedAt,
+		finishedAt: null,
+		elapsedMinutes: null,
+		lane: lane ?? null,
+		interview,
+		deliverables: formats.map((format) => ({ format, status: "pending", promised: true, updatedAt })),
+		renders: [],
+		gates: Object.fromEntries(GATE_NAMES.map((gate) => [gate, "not_run"])),
+		residualDefects: [],
+		repair: null,
+		sources: null,
+	}
+}
+
+/**
+ * Set one format's row; every other row is kept as is. An unpromised format gets a new
+ * row with promised=false. The row's detail fields are replaced by the ones given.
+ * @param {{ path?: string, reason?: string, pages?: number, bytes?: number, now?: Date }} [detail]
+ */
+export function setDeliverable(manifest, format, status, detail = {}) {
+	assertOneOf("unknown_format", "deliverable format", format, DELIVERABLE_FORMATS)
+	assertOneOf("unknown_status", "deliverable status", status, DELIVERABLE_STATUSES)
+	const next = clone(manifest)
+	const index = next.deliverables.findIndex((row) => row.format === format)
+	const row = { format, status, promised: index >= 0 ? next.deliverables[index].promised : false, updatedAt: stamp(detail.now) }
+	for (const key of ["path", "reason", "pages", "bytes"]) {
+		if (detail[key] !== undefined) row[key] = detail[key]
+	}
+	if (index >= 0) next.deliverables[index] = row
+	else next.deliverables.push(row)
+	return next
+}
+
+export function setGate(manifest, gate, status) {
+	assertOneOf("unknown_gate", "gate", gate, GATE_NAMES)
+	assertOneOf("unknown_gate_status", "gate status", status, GATE_STATUSES)
+	const next = clone(manifest)
+	next.gates[gate] = status
+	return next
+}
+
+export function addRender(manifest, path, page) {
+	if (typeof path !== "string" || path.length === 0) throw new OutcomeError("invalid_render", "render path must be a non-empty string")
+	if (!Number.isInteger(page) || page < 1) throw new OutcomeError("invalid_render", `render page must be an integer >= 1, got ${page}`)
+	const next = clone(manifest)
+	if (!next.renders.some((render) => render.path === path && render.page === page)) next.renders.push({ path, page })
+	return next
+}
+
+function fileSize(fs, path) {
+	try {
+		const stat = fs.statSync(path)
+		return stat.isFile() ? stat.size : null
+	} catch (error) {
+		if (isMissing(error)) return null
+		throw error
+	}
+}
+
+/**
+ * @param {object} manifest
+ * @param {{ statSync: typeof nodeFs.statSync }} [fs]
+ * @returns {{ ok: boolean, problems: { code: string, format: string, message: string, path?: string }[] }}
+ */
+export function verifyManifest(manifest, fs = nodeFs) {
+	const problems = []
+	for (const row of manifest.deliverables) {
+		const problem = (message, path) => problems.push({ code: MISSING, format: row.format, message, ...(path ? { path } : {}) })
+		if (row.status === "pending") problem(`${row.format} is still pending`)
+		else if (row.status === "delivered") {
+			if (!row.path) problem(`${row.format} is delivered without a path`)
+			else {
+				const size = fileSize(fs, row.path)
+				if (size === null) problem(`${row.format} delivered file is missing: ${row.path}`, row.path)
+				else if (size === 0) problem(`${row.format} delivered file is empty: ${row.path}`, row.path)
+			}
+		} else if (REASON_REQUIRED.has(row.status) && !row.reason) problem(`${row.format} is ${row.status} without a reason`)
+	}
+	return { ok: problems.length === 0, problems }
+}
+
+/**
+ * none = missing or empty file; partial = `STATUS: draft` in the first 5 lines, or the
+ * manifest (given, else a sibling outcome.json) still has a pending row; else complete.
+ * @returns {"none"|"partial"|"complete"}
+ */
+export function deliverableState(deliverablePath, manifestOrNull) {
+	let text
+	try {
+		text = nodeFs.readFileSync(deliverablePath, "utf8")
+	} catch (error) {
+		if (isMissing(error)) return "none"
+		throw error
+	}
+	if (text.trim() === "") return "none"
+	if (text.split(/\r?\n/, DRAFT_SCAN_LINES).some((line) => line.includes(DRAFT_MARKER))) return "partial"
+	const sibling = join(dirname(deliverablePath), MANIFEST_FILENAME)
+	const manifest = manifestOrNull ?? (nodeFs.existsSync(sibling) ? readManifest(sibling) : null)
+	if (manifest && manifest.deliverables.some((row) => row.status === "pending")) return "partial"
+	return "complete"
+}
+
+/** Hostname without a leading `www.`; null for a string URL cannot parse (not a source host). */
+function hostOf(url) {
+	return URL.canParse(url) ? new URL(url).hostname.toLowerCase().replace(/^www\./, "") : null
+}
+
+function repairSummary(repair) {
+	if (!repair) return null
+	const attempts = Array.isArray(repair.attempts) ? repair.attempts.length : repair.attempts ?? null
+	return { attempts, action: repair.decision?.action ?? repair.action ?? null, reason: repair.decision?.reason ?? repair.reason ?? null }
+}
+
+/** The briefing numbers, from the manifest + ledger text + injected `now` only. */
+export function briefingFacts(manifest, sourcesLedgerText, now) {
+	const sourceLines = String(sourcesLedgerText ?? "").split(/\r?\n/).filter((line) => SOURCE_LINE.test(line))
+	const hosts = new Set()
+	for (const line of sourceLines) {
+		for (const url of line.match(URL_PATTERN) ?? []) {
+			const host = hostOf(url)
+			if (host) hosts.add(host)
+		}
+	}
+	const elapsedMs = now.getTime() - new Date(manifest.startedAt).getTime()
+	return {
+		sources: sourceLines.length,
+		domains: hosts.size,
+		hosts: [...hosts].sort(),
+		minutes: Math.max(0, Math.round(elapsedMs / 60000)),
+		deliverables: manifest.deliverables.map((row) => ({ format: row.format, status: row.status, reason: row.reason ?? null, path: row.path ?? null })),
+		gates: { ...manifest.gates },
+		residualDefects: manifest.residualDefects.length,
+		repair: repairSummary(manifest.repair),
+	}
+}
+
+/** The closing briefing block as plain text. */
+export function buildBriefing(manifest, sourcesLedgerText, now) {
+	const facts = briefingFacts(manifest, sourcesLedgerText, now)
+	const repair = facts.repair
+		? `${facts.repair.attempts ?? "?"} attempt(s), last decision ${facts.repair.action ?? "?"} (${facts.repair.reason ?? "?"})`
+		: "not run"
+	return [
+		"Closing briefing",
+		`- Sources: ${facts.sources} from ${facts.domains} distinct domain(s), counted from the sources ledger.`,
+		`- Elapsed: ${facts.minutes} minute(s) since ${manifest.startedAt}.`,
+		"- Deliverables:",
+		"  | format | status | detail |",
+		"  |---|---|---|",
+		...facts.deliverables.map((row) => `  | ${row.format} | ${row.status} | ${row.reason ?? row.path ?? ""} |`),
+		`- Gates: ${GATE_NAMES.map((gate) => `${gate} ${facts.gates[gate]}`).join(", ")}.`,
+		`- Residual defects: ${facts.residualDefects}.`,
+		`- Repair: ${repair}.`,
+	].join("\n")
+}
+
+function assertValid(manifest, where) {
+	const { ok, errors } = validateOutcomeManifest(manifest)
+	if (!ok) throw new OutcomeError("invalid_manifest", `${where}: ${errors.join("; ")}`)
+}
+
+export function readManifest(file) {
+	let manifest
+	try {
+		manifest = JSON.parse(nodeFs.readFileSync(file, "utf8"))
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new OutcomeError("invalid_manifest", `${file}: not valid JSON (${error.message})`)
+		throw error
+	}
+	assertValid(manifest, file)
+	return manifest
+}
+
+/** Validate, then write atomically (temp file in the same dir + rename). */
+export function writeManifest(file, manifest) {
+	assertValid(manifest, file)
+	const temp = join(dirname(file), `.${basename(file)}.${process.pid}.${Date.now()}.tmp`)
+	try {
+		nodeFs.writeFileSync(temp, `${JSON.stringify(manifest, null, "\t")}\n`, "utf8")
+		nodeFs.renameSync(temp, file)
+	} catch (error) {
+		nodeFs.rmSync(temp, { force: true })
+		throw error
+	}
+	return file
+}

package/packages/shared-skills/skills/ulw-research/scripts/outcome.test.ts

@@ -0,0 +1,281 @@
+import { describe, expect, test } from "bun:test"
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { DELIVERABLE_FORMATS, GATE_NAMES, validateOutcomeManifest } from "./contracts.mjs"
+import {
+	MANIFEST_FILENAME,
+	OutcomeError,
+	addRender,
+	briefingFacts,
+	buildBriefing,
+	deliverableState,
+	initManifest,
+	readManifest,
+	setDeliverable,
+	setGate,
+	verifyManifest,
+	writeManifest,
+} from "./outcome.mjs"
+
+const STAMP = "20260101-120000"
+const START_LOCAL = new Date(2026, 0, 1, 12, 0, 0)
+
+function sessionDir(): string {
+	const dir = join(mkdtempSync(join(tmpdir(), "ulw-outcome-")), STAMP)
+	mkdirSync(dir)
+	return dir
+}
+
+function oneByteFile(dir: string, name: string): string {
+	const file = join(dir, name)
+	writeFileSync(file, "x")
+	return file
+}
+
+function codes(problems: { code: string }[]): string[] {
+	return problems.map((problem) => problem.code)
+}
+
+describe("initManifest", () => {
+	test("#given promised pdf and docx #when initialised #then there is one pending row per format and the schema validates", () => {
+		// given
+		const dir = sessionDir()
+		// when
+		const manifest = initManifest({ sessionDir: dir, promised: ["pdf", "docx"], lane: "no-format" })
+		// then
+		expect(manifest.deliverables.map((row) => [row.format, row.status, row.promised])).toEqual([
+			["pdf", "pending", true],
+			["docx", "pending", true],
+		])
+		expect(manifest.startedAt).toBe(START_LOCAL.toISOString())
+		expect(Object.keys(manifest.gates)).toEqual([...GATE_NAMES])
+		expect(Object.values(manifest.gates).every((status) => status === "not_run")).toBe(true)
+		expect(validateOutcomeManifest(manifest)).toEqual({ ok: true, errors: [] })
+	})
+
+	test("#given a session dir without a YYYYMMDD-HHMMSS basename #when initialised #then it throws a typed error", () => {
+		// given
+		const dir = mkdtempSync(join(tmpdir(), "ulw-outcome-"))
+		// when / then
+		expect(() => initManifest({ sessionDir: dir, promised: ["pdf"], lane: null })).toThrow(OutcomeError)
+	})
+})
+
+describe("setDeliverable and verifyManifest", () => {
+	test("#given a fresh pdf+docx manifest #when verified #then both pending rows are missing_promised_deliverable", () => {
+		// given
+		const manifest = initManifest({ sessionDir: sessionDir(), promised: ["pdf", "docx"], lane: "no-format" })
+		// when
+		const result = verifyManifest(manifest)
+		// then
+		expect(result.ok).toBe(false)
+		expect(codes(result.problems)).toEqual(["missing_promised_deliverable", "missing_promised_deliverable"])
+	})
+
+	test("#given pdf delivered as a 1-byte file and docx blocked with a reason #when verified #then it passes", () => {
+		// given
+		const dir = sessionDir()
+		const initial = initManifest({ sessionDir: dir, promised: ["pdf", "docx"], lane: "no-format" })
+		// when
+		const afterPdf = setDeliverable(initial, "pdf", "delivered", { path: oneByteFile(dir, "report.pdf") })
+		const afterDocx = setDeliverable(afterPdf, "docx", "blocked_capability", { reason: "no docx renderer" })
+		// then
+		expect(afterPdf.deliverables.find((row) => row.format === "docx")?.status).toBe("pending")
+		expect(codes(verifyManifest(afterPdf).problems)).toEqual(["missing_promised_deliverable"])
+		expect(verifyManifest(afterDocx)).toEqual({ ok: true, problems: [] })
+		expect(initial.deliverables.every((row) => row.status === "pending")).toBe(true)
+	})
+
+	test("#given a delivered row whose file is missing or empty #when verified #then each path is named in problems", () => {
+		// given
+		const dir = sessionDir()
+		const missing = join(dir, "gone.pdf")
+		const empty = join(dir, "empty.html")
+		writeFileSync(empty, "")
+		let manifest = initManifest({ sessionDir: dir, promised: ["pdf", "html"], lane: "no-format" })
+		manifest = setDeliverable(manifest, "pdf", "delivered", { path: missing })
+		manifest = setDeliverable(manifest, "html", "delivered", { path: empty })
+		// when
+		const result = verifyManifest(manifest)
+		// then
+		expect(result.ok).toBe(false)
+		expect(result.problems.map((problem) => problem.path)).toEqual([missing, empty])
+	})
+
+	test("#given a skipped row without a reason #when verified #then it is a problem", () => {
+		// given
+		const base = initManifest({ sessionDir: sessionDir(), promised: ["md"], lane: null })
+		// when
+		const result = verifyManifest(setDeliverable(base, "md", "skipped", {}))
+		// then
+		expect(codes(result.problems)).toEqual(["missing_promised_deliverable"])
+	})
+
+	test("#given an unpromised format #when set #then a non-promised row is appended and the promised rows survive", () => {
+		// given
+		const dir = sessionDir()
+		const base = initManifest({ sessionDir: dir, promised: ["pdf"], lane: null })
+		// when
+		const next = setDeliverable(base, "html", "delivered", { path: oneByteFile(dir, "r.html"), bytes: 1, pages: 1 })
+		// then
+		expect(next.deliverables.map((row) => [row.format, row.status, row.promised])).toEqual([
+			["pdf", "pending", true],
+			["html", "delivered", false],
+		])
+		expect(validateOutcomeManifest(next).ok).toBe(true)
+	})
+
+	test("#given an unknown format #when set #then it throws a typed error naming the allowed list", () => {
+		// given
+		const base = initManifest({ sessionDir: sessionDir(), promised: ["pdf"], lane: null })
+		// when
+		let caught: unknown
+		try {
+			setDeliverable(base, "epub", "delivered", { path: "x" })
+		} catch (error) {
+			caught = error
+		}
+		// then
+		expect(caught).toBeInstanceOf(OutcomeError)
+		const error = caught as OutcomeError
+		expect(error.code).toBe("unknown_format")
+		expect(error.allowed).toEqual([...DELIVERABLE_FORMATS])
+		for (const format of DELIVERABLE_FORMATS) expect(error.message).toContain(format)
+	})
+})
+
+describe("setGate and addRender", () => {
+	test("#given a manifest #when a gate and renders are recorded #then they land without mutating the input", () => {
+		// given
+		const base = initManifest({ sessionDir: sessionDir(), promised: ["pdf"], lane: null })
+		// when
+		const gated = setGate(base, "static", "pass")
+		const rendered = addRender(addRender(addRender(gated, "p1.png", 1), "p2.png", 2), "p1.png", 1)
+		// then
+		expect(base.gates.static).toBe("not_run")
+		expect(rendered.gates.static).toBe("pass")
+		expect(rendered.renders).toEqual([
+			{ path: "p1.png", page: 1 },
+			{ path: "p2.png", page: 2 },
+		])
+		expect(() => setGate(base, "spelling", "pass")).toThrow(OutcomeError)
+		expect(() => setGate(base, "static", "ok")).toThrow(OutcomeError)
+		expect(() => addRender(base, "p0.png", 0)).toThrow(OutcomeError)
+	})
+})
+
+describe("deliverableState", () => {
+	test("#given the draft marker, no marker, and a sibling manifest #when read #then state follows the file and the manifest", () => {
+		// given
+		const dir = sessionDir()
+		const report = join(dir, "report.md")
+		// when / then
+		expect(deliverableState(report, null)).toBe("none")
+		writeFileSync(report, "")
+		expect(deliverableState(report, null)).toBe("none")
+		writeFileSync(report, "# Report\nSTATUS: draft \u2014 3 sections open\n\nbody\n")
+		expect(deliverableState(report, null)).toBe("partial")
+		writeFileSync(report, "# Report\n\nbody\n")
+		expect(deliverableState(report, null)).toBe("complete")
+		const pending = initManifest({ sessionDir: dir, promised: ["md"], lane: null })
+		writeManifest(join(dir, MANIFEST_FILENAME), pending)
+		expect(deliverableState(report, null)).toBe("partial")
+		const done = setDeliverable(pending, "md", "delivered", { path: report })
+		expect(deliverableState(report, done)).toBe("complete")
+		writeManifest(join(dir, MANIFEST_FILENAME), done)
+		expect(deliverableState(report, null)).toBe("complete")
+	})
+})
+
+describe("briefingFacts and buildBriefing", () => {
+	test("#given 2 [S<n>] lines and 1 [Source 3] line on 2 hosts and now = start + 61 min #when briefed #then sources 3, domains 2, minutes 61", () => {
+		// given
+		const dir = sessionDir()
+		const manifest = setDeliverable(
+			initManifest({ sessionDir: dir, promised: ["pdf", "docx"], lane: "no-format" }),
+			"docx",
+			"skipped",
+			{ reason: "chat delivery" },
+		)
+		const ledger = [
+			"# Sources ledger",
+			"[S1] https://alpha.example/one - primary",
+			"[S2] https://www.beta.example/two",
+			"[Source 3] https://alpha.example/three",
+			"note: https://gamma.example/not-a-source",
+			"",
+		].join("\n")
+		const now = new Date(2026, 0, 1, 13, 1, 0)
+		// when
+		const facts = briefingFacts(manifest, ledger, now)
+		const text = buildBriefing(manifest, ledger, now)
+		// then
+		expect(facts.sources).toBe(3)
+		expect(facts.domains).toBe(2)
+		expect(facts.minutes).toBe(61)
+		expect(facts.deliverables).toEqual([
+			{ format: "pdf", status: "pending", reason: null, path: null },
+			{ format: "docx", status: "skipped", reason: "chat delivery", path: null },
+		])
+		expect(facts.gates).toEqual(manifest.gates)
+		expect(facts.residualDefects).toBe(0)
+		expect(facts.repair).toBeNull()
+		expect(typeof text).toBe("string")
+		for (const token of ["pdf", "docx", "chat delivery"]) expect(text).toContain(token)
+	})
+})
+
+describe("readManifest and writeManifest", () => {
+	test("#given an existing manifest file #when overwritten #then it round-trips and leaves no temp file", () => {
+		// given
+		const dir = sessionDir()
+		const file = join(dir, MANIFEST_FILENAME)
+		const first = initManifest({ sessionDir: dir, promised: ["pdf"], lane: null })
+		writeManifest(file, first)
+		// when
+		const second = setGate(first, "visual", "fail")
+		writeManifest(file, second)
+		// then
+		expect(readManifest(file)).toEqual(second)
+		expect(readdirSync(dir)).toEqual([MANIFEST_FILENAME])
+	})
+
+	test("#given an invalid manifest #when written or read #then it throws a typed error and writes nothing", () => {
+		// given
+		const dir = sessionDir()
+		const file = join(dir, MANIFEST_FILENAME)
+		// when / then
+		expect(() => writeManifest(file, { schemaVersion: 99 })).toThrow(OutcomeError)
+		expect(existsSync(file)).toBe(false)
+		writeFileSync(file, "{not json")
+		expect(() => readManifest(file)).toThrow(OutcomeError)
+	})
+})
+
+describe("round trip in a stamped session dir", () => {
+	test("#given session dir 20260101-120000 #when init, set, gate, render, verify, brief through the file #then verify passes and the briefing is computed", () => {
+		// given
+		const dir = sessionDir()
+		const file = join(dir, MANIFEST_FILENAME)
+		writeManifest(file, initManifest({ sessionDir: dir, promised: ["html", "post"], lane: "no-format" }))
+		expect(verifyManifest(readManifest(file)).ok).toBe(false)
+		// when
+		let manifest = readManifest(file)
+		manifest = setDeliverable(manifest, "html", "delivered", { path: oneByteFile(dir, "report.html"), bytes: 1 })
+		manifest = setDeliverable(manifest, "post", "skipped", { reason: "chat delivery" })
+		manifest = addRender(setGate(manifest, "static", "pass"), join(dir, "page-1.png"), 1)
+		writeManifest(file, manifest)
+		const reread = readManifest(file)
+		const ledger = join(dir, "sources-ledger.md")
+		writeFileSync(ledger, "[S1] https://a.example/\n")
+		const facts = briefingFacts(reread, readFileSync(ledger, "utf8"), new Date(2026, 0, 1, 12, 30, 0))
+		// then
+		expect(verifyManifest(reread)).toEqual({ ok: true, problems: [] })
+		expect(facts.sources).toBe(1)
+		expect(facts.minutes).toBe(30)
+		expect(facts.gates.static).toBe("pass")
+		expect(deliverableState(join(dir, "report.html"), null)).toBe("complete")
+	})
+})