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

package/dist/cli/otc.js

@@ -0,0 +1,435 @@
+#!/usr/bin/env node
+/**
+ * The `otc` command line: thin handlers over the lifecycle modules. Every
+ * command validates at its boundary, prints actionable problems, and exits
+ * 0 (ok), 1 (operational failure) or 2 (usage/validation refusal).
+ */
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { prepareCampaign, prepareSummary } from "../campaign/prepare.js";
+import { deliveryCheck, freezeCampaign } from "../campaign/freeze.js";
+import { runCampaign } from "../campaign/run.js";
+import { judgeCampaign } from "../campaign/judge.js";
+import { assessCampaign } from "../campaign/assess.js";
+import { closeCampaign } from "../campaign/close.js";
+import { statusOf } from "../campaign/status.js";
+import { analyseCampaign } from "../reporting/report.js";
+import { runAnalysis } from "../evaluators/docs/analysis/replay.js";
+import { loadCampaignBundle } from "../contracts/validate.js";
+import { packageVersion } from "../contracts/version.js";
+/** The commands `otc` exposes. */
+export const COMMANDS = [
+    "validate",
+    "prepare",
+    "delivery-check",
+    "freeze",
+    "run",
+    "judge",
+    "assess",
+    "close",
+    "analyse",
+    "status",
+    "replay",
+    "help",
+    "version",
+];
+/** Usage text, kept identical to the documented command list. */
+export const USAGE = `otc — an isolated test sandbox for OpenCode plugins, skills and agent instructions
+
+Usage: otc <command> [options]
+
+Commands:
+  validate        Validate a campaign and its suite; no writes
+  prepare         Validate, then stage an immutable campaign root
+  delivery-check  Recheck staged payloads and the freeze receipt
+  freeze          Resolve the image ID and freeze all input identities
+  run             Execute scheduled slots through Podman and OpenCode
+  judge           Blindly judge completed docs trials from checked evidence
+  assess          Deterministically assess captured evidence
+  close           Append closure to the ledger (idempotent)
+  analyse         Render final analysis after closure
+  status          Read-only state and next actions
+  replay          Replay recorded docs evidence through the docs evaluator
+  help            This text
+  version         Print the package version
+
+Options:
+  --campaign <file>   Campaign JSON (default: $OTC_CAMPAIGN)
+  --root <dir>        Campaign root (default: $OTC_ROOT)
+  --out <dir>         Fresh report directory (analyse)
+  --slot <id>         Select a slot; repeat or comma-separate
+  --passthrough <name> Pass one named environment variable into the trial
+  --manifest <file>   Recorded docs campaign manifest (replay)
+  --evidence-root <dir> Recorded evidence root (replay)
+  --rerender          Replace an existing analysis output (replay)
+  --allow-legacy-unbound Allow unbound legacy answers (replay)
+  --dry-run           Plan a trial without dispatching it
+  --json              Machine-readable output (status, validate, assess)
+  --help              This text
+
+Examples:
+  otc validate --campaign examples/skills/otel-skill-container.json
+  otc prepare --campaign campaign.json --root /tmp/otc-run
+  otc freeze --root /tmp/otc-run
+  otc run --root /tmp/otc-run --dry-run
+  otc run --root /tmp/otc-run
+  otc judge --root /tmp/otc-run
+  otc assess --root /tmp/otc-run
+  otc close --root /tmp/otc-run
+  otc analyse --root /tmp/otc-run --out /tmp/otc-report
+  otc status --root /tmp/otc-run --json
+  otc replay --manifest campaign.json --evidence-root evidence --out report
+`;
+/** Parse argv into a command and its options. */
+/** Take one option's value, refusing a missing or flag-like value. */
+function optionValue(name, args) {
+    const next = args.shift();
+    if (next === undefined || next.startsWith("--")) {
+        throw new UsageError(`${name} needs a value`);
+    }
+    return next;
+}
+/** Apply one value-bearing option; false when the argument is unknown. */
+function applyOption(options, arg, args) {
+    switch (arg) {
+        case "--campaign":
+            options.campaign = optionValue(arg, args);
+            return true;
+        case "--root":
+            options.root = optionValue(arg, args);
+            return true;
+        case "--out":
+            options.out = optionValue(arg, args);
+            return true;
+        case "--slot":
+            options.slots.push(...optionValue(arg, args)
+                .split(",")
+                .map((entry) => entry.trim())
+                .filter((entry) => entry !== ""));
+            return true;
+        case "--passthrough":
+            options.passthrough.push(optionValue(arg, args));
+            return true;
+        case "--manifest":
+            options.manifest = optionValue(arg, args);
+            return true;
+        case "--evidence-root":
+            options.evidenceRoot = optionValue(arg, args);
+            return true;
+        default:
+            return false;
+    }
+}
+/** Resolve the command name, refusing an unknown one. */
+function commandOf(first) {
+    if (!COMMANDS.includes(first)) {
+        throw new UsageError(`unknown command ${first}`);
+    }
+    return first;
+}
+/** Apply every remaining argument to the options. */
+function parseOptionLoop(options, args) {
+    while (args.length > 0) {
+        const arg = args.shift();
+        if (arg === undefined)
+            break;
+        if (arg === "--help" || arg === "-h")
+            options.help = true;
+        else if (arg === "--json")
+            options.json = true;
+        else if (arg === "--dry-run")
+            options.dryRun = true;
+        else if (arg === "--rerender")
+            options.rerender = true;
+        else if (arg === "--allow-legacy-unbound") {
+            options.allowLegacyUnbound = true;
+        }
+        else if (!applyOption(options, arg, args)) {
+            throw new UsageError(`unknown option ${arg}`);
+        }
+    }
+}
+/**
+ * Parse argv into a command and its options.
+ * @param argv Arguments after the executable.
+ * @returns The parsed options.
+ */
+export function parseArgs(argv) {
+    const options = {
+        command: "help",
+        campaign: process.env.OTC_CAMPAIGN ?? null,
+        root: process.env.OTC_ROOT ?? null,
+        out: null,
+        slots: [],
+        json: false,
+        dryRun: false,
+        passthrough: [],
+        manifest: null,
+        evidenceRoot: null,
+        rerender: false,
+        allowLegacyUnbound: false,
+        help: false,
+    };
+    const args = [...argv];
+    const first = args.shift();
+    if (first === undefined || first === "--help" || first === "-h") {
+        return options;
+    }
+    if (first === "--version" || first === "-v") {
+        options.command = "version";
+        return options;
+    }
+    options.command = commandOf(first);
+    parseOptionLoop(options, args);
+    return options;
+}
+/** A command-line usage refusal. */
+export class UsageError extends Error {
+}
+/** Require a campaign path for commands that read one. */
+function requireCampaign(options) {
+    if (options.campaign === null) {
+        throw new UsageError("--campaign (or $OTC_CAMPAIGN) is required");
+    }
+    return options.campaign;
+}
+/** Require a root for commands that operate on staged state. */
+function requireRoot(options) {
+    if (options.root === null) {
+        throw new UsageError("--root (or $OTC_ROOT) is required");
+    }
+    return options.root;
+}
+/** Print a failure block and return the exit code. */
+function fail(problems, code = 2) {
+    for (const problem of problems)
+        console.error(`otc: ${problem}`);
+    return code;
+}
+/**
+ * Run one command and return its exit code.
+ * @param argv Arguments after the executable.
+ * @returns The process exit code.
+ */
+export async function main(argv) {
+    let options;
+    try {
+        options = parseArgs(argv);
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            console.error(`otc: ${error.message}`);
+            console.error(USAGE);
+            return 2;
+        }
+        throw error;
+    }
+    if (options.help || options.command === "help") {
+        console.log(USAGE);
+        return 0;
+    }
+    if (options.command === "version") {
+        console.log(packageVersion());
+        return 0;
+    }
+    if (options.command === "analyse" && options.out === null) {
+        return fail(["analyse needs --out <fresh-directory>"]);
+    }
+    const handler = HANDLERS[options.command];
+    return handler === undefined ? 0 : handler(options);
+}
+/** Validate a campaign bundle and print its summary. */
+function validate(options) {
+    const loaded = loadCampaignBundle(requireCampaign(options));
+    if (!loaded.ok)
+        return fail(loaded.problems);
+    const bundle = loaded.value;
+    const summary = {
+        campaignId: bundle.campaign.campaignId,
+        suiteId: bundle.suite.suiteId,
+        assessment: bundle.suite.assessment,
+        cases: bundle.suite.cases.length,
+        arms: bundle.campaign.subjects.length,
+        slots: bundle.campaign.schedule.slots.length,
+    };
+    console.log(options.json
+        ? JSON.stringify({ ok: true, ...summary }, null, 2)
+        : `valid: ${summary.campaignId} / ${summary.suiteId}; ${summary.cases} case(s), ${summary.arms} arm(s), ${summary.slots} slot(s)`);
+    return 0;
+}
+/** Stage a fresh campaign root. */
+function prepare(options) {
+    const prepared = prepareCampaign(requireCampaign(options), requireRoot(options));
+    if (!prepared.ok)
+        return fail(prepared.problems);
+    console.log(prepareSummary(prepared.manifest));
+    return 0;
+}
+/** Recheck staged payloads and the freeze receipt. */
+function checkDelivery(options) {
+    const root = requireRoot(options);
+    const problems = deliveryCheck(root);
+    if (problems.length > 0)
+        return fail(problems, 1);
+    console.log(`delivery intact: ${root}`);
+    return 0;
+}
+/** Resolve and freeze the runtime identity. */
+async function freeze(options) {
+    const frozen = await freezeCampaign(requireRoot(options));
+    if (!frozen.ok)
+        return fail(frozen.problems, 1);
+    console.log(frozen.alreadyFrozen
+        ? `already frozen: ${frozen.record.imageId}`
+        : `frozen: ${frozen.record.imageId} (${frozen.record.opencodeVersion})`);
+    return 0;
+}
+/** Execute the selected slots. */
+async function run(options) {
+    const summary = await runCampaign(requireRoot(options), {
+        ...(options.slots.length === 0 ? {} : { slotIds: options.slots }),
+        dryRun: options.dryRun,
+        passthrough: options.passthrough,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(summary, null, 2));
+    }
+    else {
+        for (const slotId of summary.ran) {
+            console.log(`${options.dryRun ? "planned" : "ran"} ${slotId}`);
+        }
+        for (const problem of summary.problems) {
+            console.error(`otc: ${problem}`);
+        }
+    }
+    return summary.ok ? 0 : 1;
+}
+/** Blindly judge selected docs slots from checked evidence. */
+async function judge(options) {
+    const summary = await judgeCampaign(requireRoot(options), {
+        ...(options.slots.length === 0 ? {} : { slotIds: options.slots }),
+        dryRun: options.dryRun,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(summary, null, 2));
+    }
+    else {
+        for (const slotId of summary.judged) {
+            console.log(`${options.dryRun ? "would judge" : "judged"} ${slotId}`);
+        }
+        for (const slotId of summary.skipped) {
+            console.log(`already judged ${slotId}`);
+        }
+        for (const problem of summary.problems) {
+            console.error(`otc: ${problem}`);
+        }
+    }
+    return summary.ok ? 0 : 1;
+}
+/** Deterministically assess captured evidence. */
+function assess(options) {
+    const summary = assessCampaign(requireRoot(options), {
+        ...(options.slots.length === 0 ? {} : { slotIds: options.slots }),
+    });
+    if (options.json) {
+        console.log(JSON.stringify(summary, null, 2));
+    }
+    else {
+        console.log(`assessed ${summary.summary.assessed}: pass ${summary.summary.pass}, fail ${summary.summary.fail}, unknown ${summary.summary.unknown}, invalid ${summary.summary.invalid}, unrun ${summary.summary.unrun}`);
+        for (const problem of summary.problems) {
+            console.error(`otc: ${problem}`);
+        }
+    }
+    return summary.ok ? 0 : 1;
+}
+/** Close the campaign ledger. */
+function close(options) {
+    const closed = closeCampaign(requireRoot(options));
+    if (!closed.ok)
+        return fail(closed.problems, 1);
+    console.log(closed.alreadyClosed
+        ? `already closed at ${closed.closedAt}`
+        : `closed at ${closed.closedAt}`);
+    return 0;
+}
+/** Render final analysis after closure. */
+function analyse(options) {
+    const analysed = analyseCampaign(requireRoot(options), options.out ?? "");
+    if (!analysed.ok)
+        return fail(analysed.problems, 1);
+    console.log(analysed.markdown);
+    return 0;
+}
+/** Print checked, read-only status. */
+function status(options) {
+    const status = statusOf(requireRoot(options));
+    if (options.json) {
+        console.log(JSON.stringify(status, null, 2));
+        return status.state === "blocked" ? 1 : 0;
+    }
+    console.log([
+        `campaign ${status.campaignId ?? "unknown"} (${status.state})`,
+        `slots ${status.counts.slots}; started ${status.counts.started}; assessed ${status.counts.assessed}`,
+        ...(status.problems.length === 0
+            ? []
+            : [`problems: ${status.problems.join("; ")}`]),
+        ...status.nextActions.map((action) => `next: ${action.command} — ${action.reason}`),
+    ].join("\n"));
+    return status.state === "blocked" ? 1 : 0;
+}
+/** Replay a recorded docs campaign through the checked docs evaluator. */
+function replay(options) {
+    if (options.manifest === null ||
+        options.evidenceRoot === null ||
+        options.out === null) {
+        return fail(["replay needs --manifest, --evidence-root and --out"]);
+    }
+    const flags = [
+        "--campaign",
+        options.manifest,
+        "--evidence-root",
+        options.evidenceRoot,
+        "--out",
+        options.out,
+        ...(options.rerender ? ["--rerender"] : []),
+        ...(options.allowLegacyUnbound ? ["--allow-legacy-unbound"] : []),
+    ];
+    const result = runAnalysis(flags);
+    for (const message of result.messages)
+        console.log(message);
+    return result.status;
+}
+/** The command dispatch table. */
+const HANDLERS = {
+    validate,
+    prepare,
+    "delivery-check": checkDelivery,
+    freeze,
+    run,
+    judge,
+    assess,
+    close,
+    analyse,
+    status,
+    replay,
+};
+const invokedDirectly = process.argv[1] !== undefined &&
+    (() => {
+        try {
+            return (realpathSync(process.argv[1]) ===
+                realpathSync(fileURLToPath(import.meta.url)));
+        }
+        catch {
+            return false;
+        }
+    })();
+if (invokedDirectly) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    }, (error) => {
+        console.error(error instanceof Error
+            ? (error.stack ?? String(error))
+            : String(error));
+        process.exitCode = 1;
+    });
+}

package/dist/contracts/canonical.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Stable JSON for identity purposes: object keys are sorted recursively,
+ * array order is preserved, and `undefined` members are omitted. Freeze
+ * identities and receipts use this serialisation so that formatting cannot
+ * change an identity.
+ * @param value Any JSON-compatible value.
+ * @returns Canonical JSON text.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * The SHA-256 identity of a value's canonical JSON.
+ * @param value Any JSON-compatible value.
+ * @returns The lower-case hex digest.
+ */
+export declare function sha256Of(value: unknown): string;
+/**
+ * The SHA-256 identity of exact bytes.
+ * @param bytes The bytes to hash.
+ * @returns The lower-case hex digest.
+ */
+export declare function sha256Bytes(bytes: Buffer | string): string;

package/dist/contracts/canonical.js

@@ -0,0 +1,44 @@
+import { createHash } from "node:crypto";
+/**
+ * Stable JSON for identity purposes: object keys are sorted recursively,
+ * array order is preserved, and `undefined` members are omitted. Freeze
+ * identities and receipts use this serialisation so that formatting cannot
+ * change an identity.
+ * @param value Any JSON-compatible value.
+ * @returns Canonical JSON text.
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(sortValue(value));
+}
+/** Recursively sort object keys, leaving arrays and primitives alone. */
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (value === null || typeof value !== "object")
+        return value;
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        const entry = value[key];
+        if (entry !== undefined)
+            sorted[key] = sortValue(entry);
+    }
+    return sorted;
+}
+/**
+ * The SHA-256 identity of a value's canonical JSON.
+ * @param value Any JSON-compatible value.
+ * @returns The lower-case hex digest.
+ */
+export function sha256Of(value) {
+    return createHash("sha256")
+        .update(canonicalJson(value), "utf8")
+        .digest("hex");
+}
+/**
+ * The SHA-256 identity of exact bytes.
+ * @param bytes The bytes to hash.
+ * @returns The lower-case hex digest.
+ */
+export function sha256Bytes(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}