@markstanden/opencode-test-container 0.0.0-stage → 0.1.1

package/dist/campaign/freeze.js

@@ -0,0 +1,297 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sha256Bytes, sha256Of } from "../contracts/canonical.js";
+import { isRecord, readJson } from "../contracts/validate.js";
+import { resolveImage } from "../adapters/podman/image.js";
+import { runCommand } from "../adapters/process.js";
+import { loadPreparedManifest, manifestSha256, preparedDifferences, } from "./prepare.js";
+import { toolIdentity, toolIdentityProblems, } from "../contracts/version.js";
+/** The canonical freeze identity, independent of the freeze timestamp. */
+export function freezeIdentity(record) {
+    return sha256Of(record);
+}
+/** Path of the freeze receipt. */
+export function frozenPath(root) {
+    return join(root, "prepare", "frozen.json");
+}
+/** The required string fields of a freeze record. */
+const FROZEN_TEXT_FIELDS = [
+    "campaignId",
+    "suiteId",
+    "freezeSha256",
+    "manifestSha256",
+    "campaignSha256",
+    "suiteSha256",
+    "scheduleSha256",
+    "subjectsSha256",
+    "workspacesSha256",
+    "promptsSha256",
+    "primaryChecksSha256",
+    "image",
+    "imageId",
+    "opencodeVersion",
+    "frozenAt",
+];
+/** Check the freeze record's tool identity shape. */
+function toolShapeProblems(tool, path) {
+    return !isRecord(tool) ||
+        typeof tool.name !== "string" ||
+        typeof tool.version !== "string" ||
+        typeof tool.evaluatorVersion !== "number" ||
+        typeof tool.artifactSha256 !== "string"
+        ? [
+            `${path}.tool must name name, version, evaluatorVersion and artifactSha256`,
+        ]
+        : [];
+}
+/** Check a freeze record's shape. */
+function frozenShapeProblems(record, path) {
+    const problems = FROZEN_TEXT_FIELDS.filter((field) => typeof record[field] !== "string").map((field) => `${path}.${field} must be a string`);
+    if (!isRecord(record.provider) ||
+        typeof record.provider.route !== "string" ||
+        typeof record.provider.model !== "string") {
+        problems.push(`${path}.provider must name route and model`);
+    }
+    problems.push(...toolShapeProblems(record.tool, path));
+    if (record.schemaVersion !== 1 || record.kind !== "otc-freeze") {
+        problems.push(`${path} is not a schemaVersion 1 otc-freeze record`);
+    }
+    return problems;
+}
+/**
+ * Read a freeze receipt without trusting its shape.
+ * @param root The campaign root.
+ * @returns The record, or the reason it is unusable.
+ */
+export function loadFrozen(root) {
+    const path = frozenPath(root);
+    if (!existsSync(path)) {
+        return { ok: false, problem: `${path} is missing; run otc freeze` };
+    }
+    const parsed = readJson(path);
+    if (!parsed.ok)
+        return { ok: false, problem: parsed.problem };
+    if (!isRecord(parsed.value)) {
+        return { ok: false, problem: `${path} is not an object` };
+    }
+    const problems = frozenShapeProblems(parsed.value, path);
+    if (problems.length > 0) {
+        return { ok: false, problem: problems.join("; ") };
+    }
+    const typed = parsed.value;
+    if (freezeIdentity(identityOf(typed)) !== typed.freezeSha256) {
+        return {
+            ok: false,
+            problem: `${path} freezeSha256 does not match its content`,
+        };
+    }
+    return { ok: true, record: typed };
+}
+/** Strip volatile and derived fields from a freeze record. */
+export function identityOf(record) {
+    return {
+        schemaVersion: record.schemaVersion,
+        kind: record.kind,
+        campaignId: record.campaignId,
+        suiteId: record.suiteId,
+        manifestSha256: record.manifestSha256,
+        campaignSha256: record.campaignSha256,
+        suiteSha256: record.suiteSha256,
+        scheduleSha256: record.scheduleSha256,
+        subjectsSha256: record.subjectsSha256,
+        workspacesSha256: record.workspacesSha256,
+        promptsSha256: record.promptsSha256,
+        primaryChecksSha256: record.primaryChecksSha256,
+        tool: record.tool,
+        image: record.image,
+        imageId: record.imageId,
+        opencodeVersion: record.opencodeVersion,
+        provider: record.provider,
+    };
+}
+/** Compare prepared inputs with a freeze receipt. */
+export function freezeDifferences(manifest, frozen, current = toolIdentity()) {
+    const observed = {
+        schemaVersion: 1,
+        kind: "otc-freeze",
+        campaignId: manifest.campaignId,
+        suiteId: manifest.suiteId,
+        manifestSha256: manifestSha256(manifest),
+        campaignSha256: manifest.campaignSha256,
+        suiteSha256: manifest.suiteSha256,
+        scheduleSha256: manifest.scheduleSha256,
+        subjectsSha256: manifest.subjectsSha256,
+        workspacesSha256: manifest.workspacesSha256,
+        promptsSha256: manifest.promptsSha256,
+        primaryChecksSha256: manifest.primaryChecksSha256,
+        tool: current,
+        image: manifest.campaign.runtime.image,
+        imageId: manifest.campaign.runtime.imageId ?? frozen.imageId,
+        opencodeVersion: manifest.campaign.runtime.opencodeVersion,
+        provider: {
+            route: manifest.campaign.runtime.provider.route,
+            model: manifest.campaign.runtime.provider.model,
+        },
+    };
+    const differences = [];
+    for (const field of Object.keys(observed)) {
+        const same = field === "imageId"
+            ? String(observed[field]).replace(/^sha256:/, "") ===
+                String(frozen[field]).replace(/^sha256:/, "")
+            : typeof observed[field] === "object"
+                ? sha256Of(observed[field]) === sha256Of(frozen[field])
+                : observed[field] === frozen[field];
+        if (!same) {
+            differences.push(`frozen ${field} no longer holds`);
+        }
+    }
+    return differences;
+}
+/** Check that prepared files and the stored campaign copy are intact. */
+export function inputDifferences(root, manifest) {
+    const problems = preparedDifferences(root, manifest);
+    const campaign = join(root, "prepare", "campaign.json");
+    if (!existsSync(campaign)) {
+        problems.push("missing prepare/campaign.json");
+    }
+    else if (sha256Bytes(readFileSync(campaign)) !== manifest.campaignSha256) {
+        problems.push("changed prepare/campaign.json");
+    }
+    return problems;
+}
+/** The state of an existing freeze receipt, if one exists. */
+function existingFreeze(root, manifest, current) {
+    if (!existsSync(frozenPath(root)))
+        return { kind: "none" };
+    const existing = loadFrozen(root);
+    if (!existing.ok) {
+        return {
+            kind: "refuse",
+            problems: [existing.problem],
+        };
+    }
+    const drift = freezeDifferences(manifest, existing.record, current);
+    return drift.length === 0
+        ? { kind: "ok", record: existing.record }
+        : {
+            kind: "refuse",
+            problems: [
+                "already frozen with different inputs; use a fresh root",
+                ...drift,
+            ],
+        };
+}
+/**
+ * Freeze a prepared campaign: resolve the image to its immutable identity,
+ * verify the CLI version it contains, and record all input identities.
+ * @param root The prepared campaign root.
+ * @param run Process adapter, injected for tests.
+ * @returns The receipt, or every refusal.
+ */
+export async function freezeCampaign(root, run = runCommand) {
+    const loaded = loadPreparedManifest(root);
+    if (!loaded.ok)
+        return { ok: false, problems: [loaded.problem] };
+    const manifest = loaded.manifest;
+    const differences = inputDifferences(root, manifest);
+    if (differences.length > 0) {
+        return {
+            ok: false,
+            problems: [
+                "prepared payload does not match its manifest",
+                ...differences,
+            ],
+        };
+    }
+    const current = toolIdentity();
+    if (manifest.tool === undefined) {
+        return {
+            ok: false,
+            problems: [
+                "prepared manifest has no tool identity; prepare a fresh root",
+            ],
+        };
+    }
+    const toolDrift = toolIdentityProblems(manifest.tool, current);
+    if (toolDrift.length > 0) {
+        return {
+            ok: false,
+            problems: [
+                "prepared payload was produced by a different executing tool",
+                ...toolDrift,
+            ],
+        };
+    }
+    const existing = existingFreeze(root, manifest, current);
+    if (existing.kind === "ok") {
+        return { ok: true, record: existing.record, alreadyFrozen: true };
+    }
+    if (existing.kind === "refuse") {
+        return { ok: false, problems: existing.problems };
+    }
+    const resolved = await resolveImage(manifest.campaign.runtime.imageId ?? manifest.campaign.runtime.image, manifest.campaign.runtime.opencodeVersion, run);
+    if (!resolved.ok)
+        return { ok: false, problems: [resolved.problem] };
+    const image = resolved.image;
+    const identity = {
+        schemaVersion: 1,
+        kind: "otc-freeze",
+        campaignId: manifest.campaignId,
+        suiteId: manifest.suiteId,
+        manifestSha256: manifestSha256(manifest),
+        campaignSha256: manifest.campaignSha256,
+        suiteSha256: manifest.suiteSha256,
+        scheduleSha256: manifest.scheduleSha256,
+        subjectsSha256: manifest.subjectsSha256,
+        workspacesSha256: manifest.workspacesSha256,
+        promptsSha256: manifest.promptsSha256,
+        primaryChecksSha256: manifest.primaryChecksSha256,
+        tool: current,
+        image: manifest.campaign.runtime.image,
+        imageId: image.imageId,
+        opencodeVersion: image.opencodeVersion,
+        provider: {
+            route: manifest.campaign.runtime.provider.route,
+            model: manifest.campaign.runtime.provider.model,
+        },
+    };
+    const record = {
+        ...identity,
+        freezeSha256: freezeIdentity(identity),
+        frozenAt: new Date().toISOString(),
+    };
+    writeFileSync(frozenPath(root), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+    return { ok: true, record, alreadyFrozen: false };
+}
+/**
+ * The read-only delivery check: is the frozen payload complete and unchanged?
+ * @param root The campaign root.
+ * @returns Differences; empty means delivery is intact.
+ */
+export function deliveryCheck(root, current = toolIdentity()) {
+    const frozen = loadFrozen(root);
+    const prepared = loadPreparedManifest(root);
+    if (!frozen.ok)
+        return [frozen.problem];
+    if (!prepared.ok)
+        return [prepared.problem];
+    const problems = inputDifferences(root, prepared.manifest);
+    if (manifestSha256(prepared.manifest) !== frozen.record.manifestSha256) {
+        problems.push("prepared manifest does not match the freeze");
+    }
+    for (const difference of freezeDifferences(prepared.manifest, frozen.record, current)) {
+        problems.push(difference);
+    }
+    problems.push(...toolIdentityProblems(frozen.record.tool, current));
+    for (const arm of prepared.manifest.subjects) {
+        if (arm.plugins.length > 0) {
+            for (const plugin of arm.plugins) {
+                const packageJson = join(root, "prepare", plugin.path, "package.json");
+                if (!existsSync(packageJson)) {
+                    problems.push(`arm ${arm.armId}: plugin ${plugin.id} has no package.json`);
+                }
+            }
+        }
+    }
+    return problems;
+}

package/dist/campaign/inventory.d.ts

@@ -0,0 +1,62 @@
+/** One file identity in an immutable inventory. */
+export interface InventoryEntry {
+    /** The path value. */
+    path: string;
+    /** The sha256 value. */
+    sha256: string;
+    /** Present only for a contained symlink, recording its relative target. */
+    link?: string;
+}
+/** A deterministic inventory of a directory tree. */
+export type Inventory = InventoryEntry[];
+/** Whether a path is inside a root after resolution. */
+export declare function isContained(root: string, path: string): boolean;
+/**
+ * Resolve an existing path and prove it stays inside an allowed root.
+ * @param root The allowed root; it must exist.
+ * @param candidate The path to resolve.
+ * @returns The real path, or a refusal.
+ */
+export declare function containedRealPath(root: string, candidate: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    problem: string;
+};
+/** The SHA-256 of one file's exact bytes. */
+export declare function fileSha256(path: string): string;
+/**
+ * Inventory a directory deterministically. Symlinks are followed only when
+ * their resolved target stays inside the root; anything else is a refusal.
+ * @param root The directory to inventory.
+ * @returns The sorted inventory or the first unsafe path.
+ */
+export declare function inventory(root: string): {
+    ok: true;
+    entries: Inventory;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Recheck an inventory against a directory.
+ * @param root The directory to check.
+ * @param expected The inventory that must still hold.
+ * @returns The differences; empty means intact.
+ */
+export declare function inventoryDifferences(root: string, expected: Inventory): string[];
+/**
+ * Copy a source tree into a destination that must not already exist.
+ * Symlinks are checked for containment and preserved as relative links.
+ * @param source The source directory.
+ * @param destination The destination directory.
+ * @param include Optional top-level members to copy; all when omitted.
+ * @returns Nothing, or the refusal that stopped the copy.
+ */
+export declare function stageTree(source: string, destination: string, include?: readonly string[]): {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};

package/dist/campaign/inventory.js

@@ -0,0 +1,192 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, symlinkSync, copyFileSync, } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+/** Whether a path is inside a root after resolution. */
+export function isContained(root, path) {
+    const rel = relative(root, path);
+    return rel === "" || (!rel.startsWith("..") && !rel.startsWith(`..${sep}`));
+}
+/**
+ * Resolve an existing path and prove it stays inside an allowed root.
+ * @param root The allowed root; it must exist.
+ * @param candidate The path to resolve.
+ * @returns The real path, or a refusal.
+ */
+export function containedRealPath(root, candidate) {
+    if (!existsSync(candidate)) {
+        return { ok: false, problem: `${candidate} does not exist` };
+    }
+    let realRoot;
+    let realCandidate;
+    try {
+        realRoot = realpathSync(root);
+        realCandidate = realpathSync(candidate);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            problem: `${candidate}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!isContained(realRoot, realCandidate)) {
+        return {
+            ok: false,
+            problem: `${candidate} resolves outside ${root}`,
+        };
+    }
+    return { ok: true, path: realCandidate };
+}
+/** The SHA-256 of one file's exact bytes. */
+export function fileSha256(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+/**
+ * Inventory a directory deterministically. Symlinks are followed only when
+ * their resolved target stays inside the root; anything else is a refusal.
+ * @param root The directory to inventory.
+ * @returns The sorted inventory or the first unsafe path.
+ */
+export function inventory(root) {
+    if (!existsSync(root)) {
+        return { ok: false, problem: `${root} does not exist` };
+    }
+    const realRoot = realpathSync(root);
+    const entries = [];
+    const walk = (directory) => {
+        for (const entry of readdirSync(directory, {
+            withFileTypes: true,
+        }).sort((left, right) => left.name.localeCompare(right.name))) {
+            const path = join(directory, entry.name);
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink()) {
+                const target = readlinkSync(path);
+                const resolved = resolve(dirname(path), target);
+                if (!isContained(realRoot, resolved)) {
+                    return `${path} symlink escapes ${root}`;
+                }
+                const real = realpathSync(path);
+                if (!isContained(realRoot, real)) {
+                    return `${path} resolves outside ${root}`;
+                }
+                entries.push({
+                    path: relative(realRoot, path).split(sep).join("/"),
+                    sha256: fileSha256(real),
+                    link: target,
+                });
+                continue;
+            }
+            if (stat.isDirectory()) {
+                const problem = walk(path);
+                if (problem !== null)
+                    return problem;
+                continue;
+            }
+            if (!stat.isFile()) {
+                return `${path} is not a regular file`;
+            }
+            entries.push({
+                path: relative(realRoot, path).split(sep).join("/"),
+                sha256: fileSha256(path),
+            });
+        }
+        return null;
+    };
+    const problem = walk(realRoot);
+    if (problem !== null)
+        return { ok: false, problem };
+    return {
+        ok: true,
+        entries: entries.sort((left, right) => left.path.localeCompare(right.path)),
+    };
+}
+/**
+ * Recheck an inventory against a directory.
+ * @param root The directory to check.
+ * @param expected The inventory that must still hold.
+ * @returns The differences; empty means intact.
+ */
+export function inventoryDifferences(root, expected) {
+    const observed = inventory(root);
+    if (!observed.ok)
+        return [observed.problem];
+    const expectedMap = new Map(expected.map((entry) => [entry.path, entry]));
+    const observedMap = new Map(observed.entries.map((entry) => [entry.path, entry]));
+    const problems = [];
+    for (const [path, entry] of expectedMap) {
+        const found = observedMap.get(path);
+        if (found === undefined)
+            problems.push(`missing ${path}`);
+        else if (found.sha256 !== entry.sha256) {
+            problems.push(`changed ${path}`);
+        }
+    }
+    for (const path of observedMap.keys()) {
+        if (!expectedMap.has(path))
+            problems.push(`added ${path}`);
+    }
+    return problems;
+}
+/**
+ * Copy a source tree into a destination that must not already exist.
+ * Symlinks are checked for containment and preserved as relative links.
+ * @param source The source directory.
+ * @param destination The destination directory.
+ * @param include Optional top-level members to copy; all when omitted.
+ * @returns Nothing, or the refusal that stopped the copy.
+ */
+export function stageTree(source, destination, include) {
+    const contained = containedRealPath(source, source);
+    if (!contained.ok)
+        return contained;
+    const realSource = contained.path;
+    if (existsSync(destination)) {
+        return { ok: false, problem: `${destination} already exists` };
+    }
+    mkdirSync(destination, { recursive: true });
+    const copied = new Set();
+    const copy = (from, to) => {
+        const stat = lstatSync(from);
+        if (stat.isSymbolicLink()) {
+            const target = readlinkSync(from);
+            const resolved = resolve(dirname(from), target);
+            if (!isContained(realSource, resolved)) {
+                return `${from} symlink escapes ${realSource}`;
+            }
+            mkdirSync(dirname(to), { recursive: true });
+            symlinkSync(target, to);
+            return null;
+        }
+        if (stat.isDirectory()) {
+            mkdirSync(to, { recursive: true });
+            for (const entry of readdirSync(from, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+                const problem = copy(join(from, entry.name), join(to, entry.name));
+                if (problem !== null)
+                    return problem;
+            }
+            return null;
+        }
+        if (!stat.isFile())
+            return `${from} is not a regular file`;
+        mkdirSync(dirname(to), { recursive: true });
+        copyFileSync(from, to);
+        return null;
+    };
+    const members = include === undefined
+        ? readdirSync(realSource, { withFileTypes: true })
+            .map((entry) => entry.name)
+            .sort()
+        : [...include].sort();
+    for (const member of members) {
+        if (!copied.add(member)) {
+            return { ok: false, problem: `duplicate include ${member}` };
+        }
+        const from = join(realSource, member);
+        if (!existsSync(from)) {
+            return { ok: false, problem: `${from} does not exist` };
+        }
+        const problem = copy(from, join(destination, member));
+        if (problem !== null)
+            return { ok: false, problem };
+    }
+    return { ok: true };
+}