@mikenguyen69/harness 0.1.0-beta.1

package/dist/internal/orchestration/harness/cli.js

@@ -0,0 +1,378 @@
+/**
+ * cli — the real `Harness`, shelling the `@harness/system` binary. Portfolio
+ * rule 1 forbids importing system-harness source, so every method is a
+ * subprocess call.
+ *
+ * This replaces the v0 text-parsing shim: `harness next --json` and
+ * `harness claim --json` (SH P7.4) now return structured data, so `next` /
+ * `claim` / `escalated` parse JSON directly and the briefing carries the
+ * spec-declared merge facts. `next --all --json` supplies truthful DAG sizing
+ * and both startup crash-window checks; `claim --resume-after-door` is the
+ * signed-approval-only recovery path.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+/** Resolve an executable or JS entrypoint once; doctor prints this exact spec. */
+export function resolveCommandSpec(bin, cwd) {
+    const candidate = isAbsolute(bin) ? bin : resolve(cwd, bin);
+    if (bin.endsWith(".js") && existsSync(candidate)) {
+        return { command: process.execPath, args: [candidate] };
+    }
+    if (existsSync(candidate))
+        return { command: candidate, args: [] };
+    try {
+        const locator = process.platform === "win32" ? "where.exe" : "which";
+        const found = execFileSync(locator, [bin], { cwd, encoding: "utf8" })
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .find(Boolean);
+        if (found)
+            return { command: found, args: [] };
+    }
+    catch {
+        // handled by the explicit error below
+    }
+    throw new Error(`executable not found: ${bin}`);
+}
+/** A failed state-changing CLI call, retaining the child diagnostics. */
+export class CliMutationError extends Error {
+    request;
+    result;
+    name = "CliMutationError";
+    constructor(request, result) {
+        const detail = (result.stderr || result.stdout).trim();
+        super(`${request.command} ${request.args.join(" ")} exited ${result.code}` +
+            (detail ? `: ${detail}` : ""));
+        this.request = request;
+        this.result = result;
+    }
+}
+/**
+ * Cross-platform child-process primitive. Unlike execFile it supports stdin,
+ * never rejects for an ordinary non-zero exit, and preserves both output
+ * streams for the caller's policy decision.
+ */
+export function callProcess(request) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        const isWindowsShim = process.platform === "win32" && /\.(?:cmd|bat)$/i.test(request.command);
+        const command = isWindowsShim ? (process.env.ComSpec ?? "cmd.exe") : request.command;
+        const args = isWindowsShim
+            ? ["/d", "/s", "/c", windowsCommandLine(request.command, request.args)]
+            : request.args;
+        const child = spawn(command, args, {
+            cwd: request.cwd,
+            env: request.env ?? process.env,
+            windowsHide: true,
+            windowsVerbatimArguments: isWindowsShim,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => (stdout += chunk));
+        child.stderr.on("data", (chunk) => (stderr += chunk));
+        // A child that exits before consuming stdin can close the pipe early. Its
+        // exit/error event is the authoritative result; avoid an unhandled EPIPE.
+        child.stdin.on("error", () => undefined);
+        child.on("error", (error) => {
+            finish({ code: 1, stdout, stderr: stderr + error.message });
+        });
+        child.on("close", (code) => finish({ code: code ?? 1, stdout, stderr }));
+        if (request.stdin !== undefined)
+            child.stdin.end(request.stdin);
+        else
+            child.stdin.end();
+    });
+}
+function windowsCommandLine(command, args) {
+    const quote = (value) => `"${value.replaceAll("%", "%%").replaceAll("\"", "\"\"")}"`;
+    return `"${[command, ...args].map(quote).join(" ")}"`;
+}
+/** Map a `harness claim --json` payload onto this product's `Briefing`. Pure. */
+export function briefingFromClaimJson(j) {
+    const facts = {
+        addsDependency: j.merge_facts.adds_dependency,
+        schemaChange: j.merge_facts.schema_change,
+        security: j.merge_facts.security,
+        gateExternal: j.merge_facts.gate_external,
+        artifactProducerChange: j.merge_facts.artifact_producer_change,
+    };
+    if (j.door)
+        facts.door = j.door;
+    const briefing = {
+        unitId: j.unit_id,
+        intent: j.intent,
+        acceptanceCriteria: j.acceptance_criteria,
+        scope: j.scope,
+        branch: j.branch,
+        mergeFacts: facts,
+    };
+    if (j.component)
+        briefing.component = j.component;
+    if (j.profile)
+        briefing.profile = j.profile;
+    return briefing;
+}
+export class CliHarness {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    base() {
+        return this.opts.ledgerDir ? ["--ledger", this.opts.ledgerDir] : [];
+    }
+    callRead(args, stdin) {
+        return (this.opts.processCall ?? callProcess)({
+            command: this.opts.bin,
+            args: [...(this.opts.binArgs ?? []), ...args],
+            cwd: this.opts.cwd,
+            env: this.opts.env ?? process.env,
+            ...(stdin !== undefined ? { stdin } : {}),
+        });
+    }
+    async callMutation(args, stdin) {
+        const request = {
+            command: this.opts.bin,
+            args: [...(this.opts.binArgs ?? []), ...args],
+            cwd: this.opts.cwd,
+            env: this.opts.env ?? process.env,
+            ...(stdin !== undefined ? { stdin } : {}),
+        };
+        const result = await (this.opts.processCall ?? callProcess)(request);
+        if (result.code !== 0)
+            throw new CliMutationError(request, result);
+        return result;
+    }
+    toReadyUnit(u) {
+        const r = { id: u.id, deps: u.deps, mode: u.mode };
+        if (u.component)
+            r.component = u.component;
+        return r;
+    }
+    async next(opts) {
+        const args = ["next", "--json", ...this.base()];
+        if (opts?.only)
+            args.push("--only", opts.only);
+        const { stdout } = await this.callRead(args);
+        return JSON.parse(stdout || "[]").map((u) => this.toReadyUnit(u));
+    }
+    async escalated() {
+        const { stdout } = await this.callRead([
+            "next",
+            "--escalated",
+            "--json",
+            ...this.base(),
+        ]);
+        return JSON.parse(stdout || "[]").map((u) => this.toReadyUnit(u));
+    }
+    async units() {
+        const { stdout } = await this.callRead(["next", "--all", "--json", ...this.base()]);
+        const out = [];
+        for (const u of JSON.parse(stdout || "[]")) {
+            const snap = { id: u.id, state: u.state ?? "planned" };
+            if (u.component)
+                snap.component = u.component;
+            if (u.done_at)
+                snap.heartbeatAt = u.done_at;
+            if (u.landed)
+                snap.landedSha = u.landed;
+            out.push(snap);
+        }
+        return out;
+    }
+    async claim(unitId, session) {
+        return this.claimWith(unitId, session, []);
+    }
+    async resumeAfterDoor(unitId, session) {
+        return this.claimWith(unitId, session, ["--resume-after-door", "--keys", join(this.opts.cwd, ".harness")]);
+    }
+    async claimWith(unitId, session, extra) {
+        const args = [
+            "claim",
+            unitId,
+            "--session",
+            session,
+            "--json",
+            ...extra,
+            ...this.base(),
+        ];
+        if (this.opts.specsDir)
+            args.push("--specs", this.opts.specsDir);
+        if (this.opts.systemToml)
+            args.push("--system", this.opts.systemToml);
+        const { code, stdout } = await this.callRead(args);
+        if (code !== 0)
+            return null;
+        const briefing = briefingFromClaimJson(JSON.parse(stdout));
+        if (briefing.component) {
+            const descriptor = this.opts.components?.get(briefing.component);
+            if (descriptor)
+                briefing.componentRoot = descriptor.root;
+        }
+        return briefing;
+    }
+    async heartbeat(unitId, session) {
+        await this.callMutation(["heartbeat", unitId, "--session", session, ...this.base()]);
+    }
+    async ledgerAppend(event) {
+        const system = this.opts.systemId;
+        const actorId = event.session ?? this.opts.actorId;
+        if (!system || !actorId) {
+            throw new Error("CliHarness ledger append requires systemId and actorId context");
+        }
+        const body = {
+            unit_id: event.unitId,
+            ...(event.session ? { session: event.session, session_id: event.session } : {}),
+            ...event.body,
+        };
+        const payload = JSON.stringify({
+            system,
+            actor: { kind: event.session ? "agent" : "harness", id: actorId },
+            type: event.type,
+            body,
+        });
+        await this.callMutation(["ledger", "append", "--dir", this.opts.ledgerDir ?? join(this.opts.cwd, ".harness", "ledger")], payload);
+    }
+    async verify(briefing, session, baseRef, workspace) {
+        const componentDir = workspacePath(briefing.componentRoot ?? this.opts.cwd, workspace);
+        const componentId = briefing.component ?? "unknown";
+        const { code, stdout, stderr } = await this.callRead([
+            "verify",
+            "--component",
+            componentDir,
+            "--component-id",
+            componentId,
+            "--unit",
+            briefing.unitId,
+            "--session",
+            session,
+            "--base",
+            baseRef,
+            ...(this.opts.specsDir ? ["--specs", workspacePath(this.opts.specsDir, workspace)] : []),
+            ...(this.opts.profilesDir ? ["--profiles", workspacePath(this.opts.profilesDir, workspace)] : []),
+            ...(this.opts.systemId ? ["--system-id", this.opts.systemId] : []),
+            "--json",
+            ...this.base(),
+        ]);
+        // `harness verify --json` (SH G2.4) emits `{status, envelope_hash?}` on
+        // stdout — a deterministic handle to THIS verify's `envelope` event even
+        // when parallel verifies make the ledger tail ambiguous.
+        if (code === 0) {
+            const hash = parseEnvelopeHash(stdout);
+            return hash ? { status: "pass", envelopeHash: hash } : { status: "pass" };
+        }
+        if (code === 2)
+            return { status: "halt", evidence: stderr || stdout };
+        return { status: "fail", evidence: stderr || stdout };
+    }
+    async verifySystem(unitId, systemToml, workspace) {
+        const { code, stdout, stderr } = await this.callRead([
+            "verify",
+            "--unit",
+            unitId,
+            "--system",
+            workspacePath(systemToml, workspace),
+            ...this.base(),
+        ]);
+        if (code === 0)
+            return { status: "pass" };
+        if (code === 2)
+            return { status: "halt", evidence: stderr || stdout };
+        return { status: "fail", evidence: stderr || stdout };
+    }
+    async authorizeMerge(unitId, facts, workspace) {
+        const { code, stdout, stderr } = await this.callRead([
+            "merge",
+            unitId,
+            "--check",
+            ...(this.opts.systemToml ? ["--system", workspacePath(this.opts.systemToml, workspace)] : []),
+            ...mergeFactFlags(facts),
+            ...this.base(),
+        ]);
+        if (code === 0)
+            return { status: "authorized" };
+        return blockedMerge(unitId, stderr || stdout);
+    }
+    async recordMerge(unitId, landedSha, facts, workspace) {
+        const { code, stdout, stderr } = await this.callRead([
+            "merge",
+            unitId,
+            "--landed",
+            landedSha,
+            ...(this.opts.systemToml ? ["--system", workspacePath(this.opts.systemToml, workspace)] : []),
+            ...mergeFactFlags(facts),
+            ...this.base(),
+        ]);
+        if (code === 0)
+            return { status: "merged", landedSha };
+        return blockedMerge(unitId, stderr || stdout);
+    }
+}
+function mergeFactFlags(facts) {
+    const flags = [];
+    if (facts.door === "one-way")
+        flags.push("--one-way");
+    if (facts.door === "two-way")
+        flags.push("--two-way");
+    if (facts.addsDependency)
+        flags.push("--adds-dependency");
+    if (facts.schemaChange)
+        flags.push("--schema-change");
+    if (facts.security)
+        flags.push("--security");
+    if (facts.gateExternal)
+        flags.push("--gate-external");
+    if (facts.artifactProducerChange)
+        flags.push("--artifact-producer-change");
+    if (facts.mode)
+        flags.push("--mode", facts.mode);
+    return flags;
+}
+function blockedMerge(unitId, output) {
+    const blurb = output.trim();
+    return {
+        status: "door-open",
+        doorId: parseDoorId(blurb) ?? `${unitId}#door`,
+        unblock: blurb || `harness door approve ${unitId} --reason "<why>" --who <operator>`,
+    };
+}
+function workspacePath(path, workspace) {
+    if (!workspace)
+        return path;
+    const rel = relative(workspace.controlRepo, resolve(path));
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return path;
+    return resolve(workspace.path, rel);
+}
+/** `{"status":"pass","envelope_hash":"<hex>"}` → the hash, or undefined. */
+export function parseEnvelopeHash(stdout) {
+    try {
+        const j = JSON.parse(stdout.trim());
+        return typeof j.envelope_hash === "string" && j.envelope_hash
+            ? j.envelope_hash
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Pull the door id out of `harness merge`'s blocked-merge stderr, e.g.
+ *   `⛔ merge blocked — door door-core-a-schema opened. Decide with: …`
+ *   `⛔ merge blocked — door door-core-a-schema was REJECTED: …`
+ *   `⛔ merge blocked — door door-core-a-schema awaits a decision`
+ */
+export function parseDoorId(stderr) {
+    const m = stderr.match(/door\s+(\S+?)\s+(?:opened|was REJECTED|awaits)\b/);
+    return m ? m[1] : undefined;
+}
+//# sourceMappingURL=cli.js.map

package/dist/internal/orchestration/harness/index.js

@@ -0,0 +1,186 @@
+/**
+ * harness — the typed wrapper over the `@harness/system` CLI surface.
+ *
+ * This product reimplements NONE of the pipeline it drives. Every method here
+ * is a call to a `harness` subcommand: verify (rings 1 + 2), door classification
+ * (folded into `merge`), the `unit.merged` fact, provenance appends. The loop
+ * talks only to this interface — never to `child_process` directly, never to a
+ * system-harness source import (portfolio rule 1).
+ *
+ * Two implementations ship in v0:
+ *   - `FakeHarness` (this file) — an in-memory unit table the dry loop (M1) and
+ *     the test suite drive against. No process, no ledger, no git.
+ *   - `CliHarness` (./cli.ts) — shells the real `harness` binary, parsing the
+ *     `--json` surface from SH P7.4 (`next` / `claim` / `escalated`) plus the
+ *     separate pre-land merge check and post-land merge record calls. The v0
+ *     text-parsing shim it replaced is gone.
+ */
+export class FakeHarness {
+    table = new Map();
+    appends = [];
+    heartbeats = [];
+    constructor(specs = []) {
+        for (const s of specs)
+            this.add(s);
+    }
+    add(s) {
+        const u = {
+            id: s.id,
+            deps: s.deps ?? [],
+            mode: s.mode ?? "build",
+            intent: s.intent ?? `implement ${s.id} to its acceptance criteria`,
+            acceptanceCriteria: s.acceptanceCriteria ?? [
+                { statement: `${s.id} MUST satisfy its intent`, verifier: "test" },
+            ],
+            scope: s.scope ?? [`src/${s.id}/**`],
+            mergeFacts: s.mergeFacts ?? { door: "two-way" },
+            state: s.state ?? "planned",
+        };
+        if (s.component !== undefined)
+            u.component = s.component;
+        if (s.escalated !== undefined)
+            u.escalated = s.escalated;
+        if (s.landedSha !== undefined)
+            u.landedSha = s.landedSha;
+        if (s.stale !== undefined)
+            u.stale = s.stale;
+        if (s.verify !== undefined)
+            u.verify = s.verify;
+        if (s.verifySystem !== undefined)
+            u.verifySystem = s.verifySystem;
+        this.table.set(s.id, u);
+    }
+    ready(u) {
+        if (u.escalated)
+            return false;
+        // planned, or executing-but-stale (the sequencer re-offers a dead session's unit).
+        if (u.state !== "planned" && !(u.state === "executing" && u.stale))
+            return false;
+        return u.deps.every((d) => this.table.get(bareId(d))?.state === "merged");
+    }
+    toReadyUnit(u) {
+        const r = { id: u.id, deps: u.deps, mode: u.mode };
+        if (u.component !== undefined)
+            r.component = u.component;
+        return r;
+    }
+    async next(opts) {
+        return [...this.table.values()]
+            .filter((u) => this.ready(u))
+            .filter((u) => !opts?.only || u.id.startsWith(opts.only))
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .map((u) => this.toReadyUnit(u));
+    }
+    async escalated() {
+        return [...this.table.values()]
+            .filter((u) => u.escalated)
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .map((u) => this.toReadyUnit(u));
+    }
+    async units() {
+        return [...this.table.values()]
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .map((u) => {
+            const snap = { id: u.id, state: u.state };
+            if (u.component !== undefined)
+                snap.component = u.component;
+            if (u.landedSha !== undefined)
+                snap.landedSha = u.landedSha;
+            return snap;
+        });
+    }
+    async claim(unitId, session) {
+        const u = this.table.get(unitId);
+        if (!u || !this.ready(u))
+            return null;
+        u.state = "executing";
+        u.claimedBy = session;
+        delete u.stale; // a fresh claim takes ownership from the dead session
+        return this.briefing(u);
+    }
+    async resumeAfterDoor(unitId, session) {
+        const u = this.table.get(unitId);
+        if (!u || u.state !== "in-review")
+            return null;
+        u.state = "executing";
+        u.claimedBy = session;
+        return this.briefing(u);
+    }
+    briefing(u) {
+        const b = {
+            unitId: u.id,
+            intent: u.intent,
+            acceptanceCriteria: u.acceptanceCriteria,
+            scope: u.scope,
+            branch: `unit/${u.id}`,
+            mergeFacts: u.mergeFacts,
+        };
+        if (u.component !== undefined)
+            b.component = u.component;
+        return b;
+    }
+    async heartbeat(unitId, session) {
+        this.heartbeats.push({ unitId, session });
+    }
+    async ledgerAppend(event) {
+        this.appends.push(event);
+        if (event.type === "unit.done") {
+            const u = this.table.get(event.unitId);
+            // in-review → in-review is a documented no-op in the fold (M3).
+            if (u && u.state === "executing")
+                u.state = "in-review";
+        }
+    }
+    async verify(briefing, _session, _baseRef) {
+        return (this.table.get(briefing.unitId)?.verify ?? {
+            status: "pass",
+            // a deterministic stand-in for the ring-1 `envelope` event hash (G4).
+            envelopeHash: `env-${briefing.unitId}`,
+        });
+    }
+    async verifySystem(unitId, _systemToml) {
+        return this.table.get(unitId)?.verifySystem ?? { status: "pass" };
+    }
+    async authorizeMerge(unitId, facts) {
+        const u = this.table.get(unitId);
+        if (!u)
+            return {
+                status: "door-open",
+                doorId: `${unitId}#missing`,
+                unblock: "unit not found",
+            };
+        // classifyMerge: an absent door is one-way (safety default — v0-plan calibration note).
+        const oneWay = facts.door === "one-way" ||
+            facts.door === undefined ||
+            facts.schemaChange === true ||
+            facts.security === true;
+        if (oneWay) {
+            return {
+                status: "door-open",
+                doorId: `${unitId}#door`,
+                unblock: `harness door approve ${unitId} --reason "<why>" --who <operator>`,
+            };
+        }
+        return { status: "authorized" };
+    }
+    async recordMerge(unitId, landedSha, _facts) {
+        const u = this.table.get(unitId);
+        if (!u)
+            return {
+                status: "door-open",
+                doorId: `${unitId}#missing`,
+                unblock: "unit not found",
+            };
+        u.state = "merged";
+        u.landedSha = landedSha;
+        return { status: "merged", landedSha };
+    }
+    /** test helper: current state of a unit. */
+    stateOf(unitId) {
+        return this.table.get(unitId)?.state;
+    }
+}
+export function bareId(ref) {
+    return ref.includes("#") ? ref.slice(ref.indexOf("#") + 1) : ref;
+}
+//# sourceMappingURL=index.js.map