@mikenguyen69/harness 0.1.0-beta.1

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

@@ -0,0 +1,202 @@
+/** Read-only launch preflight for a real orchestration run. */
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync, statSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { loadOrchestrationConfig } from "../config/index.js";
+import { callProcess, CliHarness, } from "../harness/cli.js";
+import { CliRouteSource } from "../routes/index.js";
+import { loadComponentDescriptors } from "../run/index.js";
+export async function runDoctor(options) {
+    const repo = resolve(options.repo);
+    const checks = [];
+    const readyUnits = [];
+    const add = (check) => checks.push(check);
+    const configPath = options.configPath ?? join(repo, "orchestration.json");
+    const systemToml = join(repo, "system.toml");
+    const specsDir = join(repo, "specs");
+    const profilesDir = join(repo, "profiles");
+    const ledgerDir = join(repo, ".harness", "ledger");
+    if (!existsSync(repo) || !statSync(repo).isDirectory()) {
+        add({ id: "repo", status: "fail", detail: `repository directory not found: ${repo}`, fix: "pass --repo with an existing checkout" });
+        return report();
+    }
+    let config;
+    try {
+        config = loadOrchestrationConfig(configPath);
+        add({ id: "config", status: "pass", detail: `loaded ${configPath}` });
+    }
+    catch (error) {
+        add({ id: "config", status: "fail", detail: error.message, fix: "create or repair orchestration.json" });
+    }
+    try {
+        const top = git(repo, ["rev-parse", "--show-toplevel"]);
+        add({ id: "git-repo", status: "pass", detail: `git worktree: ${top}` });
+    }
+    catch (error) {
+        add({ id: "git-repo", status: "fail", detail: error.message, fix: "initialize or select a Git checkout" });
+    }
+    if (config) {
+        try {
+            git(repo, ["show-ref", "--verify", `refs/heads/${config.baseBranch}`]);
+            add({ id: "base-branch", status: "pass", detail: `base branch exists: ${config.baseBranch}` });
+        }
+        catch {
+            add({ id: "base-branch", status: "fail", detail: `base branch missing: ${config.baseBranch}`, fix: `create/fetch ${config.baseBranch} or correct baseBranch` });
+        }
+    }
+    try {
+        const dirty = git(repo, ["status", "--porcelain"]);
+        if (dirty && !options.allowDirty) {
+            add({ id: "working-tree", status: "fail", detail: "checkout has uncommitted or untracked changes", fix: "commit/stash them, or explicitly rerun doctor with --allow-dirty" });
+        }
+        else {
+            add({ id: "working-tree", status: dirty ? "warn" : "pass", detail: dirty ? "dirty checkout explicitly allowed" : "checkout is clean" });
+        }
+    }
+    catch {
+        // git-repo already carries the blocking diagnostic
+    }
+    let components = new Map();
+    try {
+        components = loadComponentDescriptors(systemToml);
+        const missing = [...components.values()].flatMap((component) => {
+            const paths = [join(component.root, "component.toml"), join(profilesDir, component.profile, "bindings.toml")];
+            return paths.filter((path) => !existsSync(path));
+        });
+        if (missing.length) {
+            add({ id: "components", status: "fail", detail: `missing component/profile files: ${missing.join(", ")}`, fix: "repair system.toml roots and install every declared profile" });
+        }
+        else {
+            add({ id: "components", status: "pass", detail: `${components.size} component(s) and profiles resolved` });
+        }
+    }
+    catch (error) {
+        add({ id: "components", status: "fail", detail: error.message, fix: "create or repair system.toml and component.toml" });
+    }
+    const specCheck = await callProcess({
+        command: options.harness.command,
+        args: [...options.harness.args, "spec", "check", "--specs", specsDir, "--system", systemToml],
+        cwd: repo,
+    });
+    add(specCheck.code === 0
+        ? { id: "specs", status: "pass", detail: "spec schema and dependency DAG pass" }
+        : { id: "specs", status: "fail", detail: (specCheck.stderr || specCheck.stdout).trim(), fix: "run the printed harness spec check and repair every finding" });
+    const chain = await callProcess({
+        command: options.harness.command,
+        args: [...options.harness.args, "ledger", "verify-chain", "--dir", ledgerDir],
+        cwd: repo,
+    });
+    add(chain.code === 0
+        ? { id: "ledger", status: "pass", detail: chain.stdout.trim() }
+        : { id: "ledger", status: "fail", detail: (chain.stderr || chain.stdout).trim(), fix: "restore the ledger from trusted evidence; do not hand-edit JSONL" });
+    const harness = new CliHarness({
+        bin: options.harness.command,
+        binArgs: options.harness.args,
+        cwd: repo,
+        ledgerDir,
+        specsDir,
+        profilesDir,
+        systemToml,
+        components,
+        systemId: basename(repo),
+        actorId: "doctor-read-only",
+    });
+    try {
+        const ready = await harness.next();
+        const routes = new CliRouteSource({
+            bin: options.agentHarness.command,
+            binArgs: options.agentHarness.args,
+            cwd: repo,
+            routesPath: options.routesPath,
+            ledgerDir,
+            profileForComponent: (component) => component ? components.get(component)?.profile : undefined,
+        });
+        for (const unit of ready) {
+            const policy = await routes.resolve(unit.id, unit.component);
+            readyUnits.push({
+                id: unit.id,
+                ...(unit.component ? { component: unit.component } : {}),
+                runner: policy.runner,
+                model: policy.model,
+            });
+            if (config && !config.runnersEnabled.includes(policy.runner)) {
+                add({ id: `route:${unit.id}`, status: "fail", detail: `${unit.id} resolves to disabled runner ${policy.runner}`, fix: `enable ${policy.runner} or change ${options.routesPath}` });
+            }
+            else {
+                add({ id: `route:${unit.id}`, status: "pass", detail: `${unit.id} → ${policy.runner}/${policy.model}` });
+            }
+        }
+        if (ready.length === 0)
+            add({ id: "routes", status: "warn", detail: "no currently ready units to route" });
+    }
+    catch (error) {
+        add({ id: "routes", status: "fail", detail: error.message, fix: `create/fix ${options.routesPath} and ensure every component profile resolves` });
+    }
+    if (config) {
+        const bounded = config.maxRunCost !== undefined && config.maxRunDuration !== undefined;
+        add(bounded
+            ? { id: "budgets", status: "pass", detail: `cost <= ${config.maxRunCost}; duration <= ${config.maxRunDuration}ms` }
+            : { id: "budgets", status: "warn", detail: "one or more run budgets are uncapped", fix: "set maxRunCost and maxRunDuration before a paid run" });
+    }
+    const hookText = safeRead(join(repo, ".claude", "settings.json"));
+    add(hookText.includes("hook pre-tool-use")
+        ? { id: "scope-hook", status: "pass", detail: "Claude PreToolUse scope hook is installed" }
+        : { id: "scope-hook", status: "warn", detail: "Claude scope hook is not installed yet; ClaudeRunner installs it before dispatch" });
+    add(existsSync(join(repo, ".harness", "operator-key.pem"))
+        ? { id: "operator-key", status: "pass", detail: "operator signing key exists" }
+        : { id: "operator-key", status: "warn", detail: "operator key is absent; a one-way door can halt but cannot yet be approved", fix: "a human runs harness door init-key before approval" });
+    if (options.spoolDir) {
+        const writable = writableAncestor(options.spoolDir);
+        add(writable.ok
+            ? { id: "spool", status: "pass", detail: `evidence spool is writable via ${writable.path}` }
+            : { id: "spool", status: "fail", detail: `evidence spool is not writable: ${options.spoolDir}`, fix: "choose a writable --spool directory" });
+    }
+    add({
+        id: "executables",
+        status: "pass",
+        detail: `harness=${renderCommand(options.harness)}; agent-harness=${renderCommand(options.agentHarness)}`,
+    });
+    return report();
+    function report() {
+        return {
+            status: checks.some((check) => check.status === "fail") ? "blocked" : "ready",
+            repo,
+            checks,
+            commands: { harness: options.harness, agentHarness: options.agentHarness },
+            readyUnits,
+        };
+    }
+}
+function git(cwd, args) {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function safeRead(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function writableAncestor(path) {
+    let current = resolve(path);
+    while (!existsSync(current)) {
+        const parent = dirname(current);
+        if (parent === current)
+            return { ok: false, path: current };
+        current = parent;
+    }
+    try {
+        if (!statSync(current).isDirectory())
+            return { ok: false, path: current };
+        accessSync(current, constants.W_OK);
+        return { ok: true, path: current };
+    }
+    catch {
+        return { ok: false, path: current };
+    }
+}
+function renderCommand(spec) {
+    return [spec.command, ...spec.args].map((part) => part.includes(" ") ? `"${part}"` : part).join(" ");
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,121 @@
+/**
+ * forge — how a verified, rebased unit branch *lands* on the base branch. Two
+ * implementations (v0-plan M4):
+ *   - LocalForge  — fast-forward `baseBranch` to the branch tip (no PR).
+ *   - GithubForge — push the branch, open/reuse its PR, merge on green.
+ *
+ * The loop calls `forge.land()` only after the system harness authorizes the
+ * merge facts and signed doors. The actual `unit.merged` fact is recorded only
+ * after this returns the landed object id.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/** No PR — fast-forward the base ref to the (already rebased) branch tip. */
+export class LocalForge {
+    git;
+    kind = "local";
+    constructor(git) {
+        this.git = git;
+    }
+    async land(p) {
+        const ff = await this.git.fastForward(p.base, p.tipSha);
+        return ff.ok
+            ? { ok: true, landedSha: p.tipSha }
+            : { ok: false, reason: ff.reason ?? "fast-forward failed" };
+    }
+}
+/** Push the branch, open or reuse its PR, merge it (`--merge --auto` off — we gate). */
+export class GithubForge {
+    opts;
+    kind = "github";
+    bin;
+    gitBin;
+    constructor(opts) {
+        this.opts = opts;
+        this.bin = opts.bin ?? "gh";
+        this.gitBin = opts.gitBin ?? "git";
+    }
+    async gitCmd(args) {
+        if (this.opts.execGit)
+            return this.opts.execGit(args);
+        try {
+            const { stdout, stderr } = await run(this.gitBin, args, { cwd: this.opts.cwd });
+            return { code: 0, stdout, stderr };
+        }
+        catch (e) {
+            const err = e;
+            return {
+                code: typeof err.code === "number" ? err.code : 1,
+                stdout: err.stdout ?? "",
+                stderr: err.stderr ?? "",
+            };
+        }
+    }
+    async gh(args) {
+        if (this.opts.exec)
+            return this.opts.exec(args);
+        try {
+            const { stdout, stderr } = await run(this.bin, args, { cwd: this.opts.cwd });
+            return { code: 0, stdout, stderr };
+        }
+        catch (e) {
+            const err = e;
+            return {
+                code: typeof err.code === "number" ? err.code : 1,
+                stdout: err.stdout ?? "",
+                stderr: err.stderr ?? "",
+            };
+        }
+    }
+    async land(p) {
+        // `gh pr create --head <branch>` needs the branch on the remote first; the
+        // orchestrator rebases the unit branch before landing, so the remote ref may
+        // be behind — force-with-lease keeps the push safe for this owned branch.
+        const pushed = await this.gitCmd([
+            "push",
+            "--force-with-lease",
+            "origin",
+            `${p.branch}:refs/heads/${p.branch}`,
+        ]);
+        if (pushed.code !== 0) {
+            return { ok: false, reason: `git push: ${(pushed.stderr || pushed.stdout).trim()}` };
+        }
+        const push = await this.gh([
+            "pr",
+            "create",
+            "--head",
+            p.branch,
+            "--base",
+            p.base,
+            "--title",
+            `${p.unitId}`,
+            "--body",
+            `Landed by orchestrate. Unit: ${p.unitId}`,
+            "--fill",
+        ]);
+        // `pr create` fails if a PR already exists — that is fine, proceed to merge.
+        const created = push.code === 0;
+        const existsAlready = /already exists/i.test(push.stderr);
+        if (!created && !existsAlready) {
+            return { ok: false, reason: `gh pr create: ${(push.stderr || push.stdout).trim()}` };
+        }
+        const merge = await this.gh([
+            "pr",
+            "merge",
+            p.branch,
+            "--merge",
+            "--delete-branch=false",
+        ]);
+        if (merge.code !== 0) {
+            return { ok: false, reason: `gh pr merge: ${(merge.stderr || merge.stdout).trim()}` };
+        }
+        // the PR merge commit is the landed sha; ask gh for it.
+        const sha = await this.gh(["pr", "view", p.branch, "--json", "mergeCommit", "-q", ".mergeCommit.oid"]);
+        return {
+            ok: true,
+            landedSha: sha.code === 0 && sha.stdout.trim() ? sha.stdout.trim() : p.tipSha,
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,181 @@
+/**
+ * git — the real `Git`, shelling `git` in the driven project's checkout. M3
+ * needs an actual rebase; M4 layers `gh` / PR handling on top of the same
+ * interface. Nothing here reaches for a git library — plain subprocess calls,
+ * so the behaviour matches what an operator would see on the command line.
+ *
+ * All operations run with `cwd` at the driven checkout. `rebase` never throws on
+ * a conflict: it aborts the rebase and returns `{ ok: false, conflict }` so the
+ * lane can treat it as a retry.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+const FETCH_TIMEOUT_MS = 30_000;
+export class ShellGit {
+    opts;
+    bin;
+    constructor(opts) {
+        this.opts = opts;
+        this.bin = opts.bin ?? "git";
+    }
+    async git(args, cwd = this.opts.cwd, extra) {
+        try {
+            const { stdout, stderr } = await run(this.bin, args, {
+                cwd,
+                timeout: extra?.timeout,
+                env: extra?.env ? { ...process.env, ...extra.env } : undefined,
+            });
+            return { code: 0, stdout, stderr };
+        }
+        catch (e) {
+            const err = e;
+            return {
+                code: typeof err.code === "number" ? err.code : 1,
+                stdout: err.stdout ?? "",
+                stderr: err.stderr ?? "",
+            };
+        }
+    }
+    async headSha(ref) {
+        const { stdout } = await this.git(["rev-parse", ref]);
+        return stdout.trim();
+    }
+    async isAncestor(sha, ref) {
+        const { code } = await this.git(["merge-base", "--is-ancestor", sha, ref]);
+        return code === 0;
+    }
+    async fetchRemoteTracking(branch) {
+        try {
+            const remotes = await this.git(["remote"]);
+            if (remotes.code !== 0 || !remotes.stdout.trim())
+                return { ok: false };
+            const remote = await this.selectRemote(branch, remotes.stdout);
+            if (!remote)
+                return { ok: false };
+            const localBranch = stripHeads(branch);
+            const src = `refs/heads/${localBranch}`;
+            const dest = `refs/remotes/${remote}/${localBranch}`;
+            // `+` matches git's default fetch refspec (force-update tracking only).
+            // Destination is always a remote-tracking ref — never a local branch.
+            const fetched = await this.git(["fetch", "--no-tags", "--", remote, `+${src}:${dest}`], this.opts.cwd, { timeout: FETCH_TIMEOUT_MS, env: { GIT_TERMINAL_PROMPT: "0" } });
+            if (fetched.code !== 0)
+                return { ok: false };
+            return { ok: true, trackingRef: `${remote}/${localBranch}` };
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+    async selectRemote(branch, remoteList) {
+        const names = remoteList
+            .split(/\r?\n/)
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (names.length === 0)
+            return undefined;
+        const configured = await this.git(["config", "--get", `branch.${stripHeads(branch)}.remote`]);
+        const preferred = configured.stdout.trim();
+        if (configured.code === 0 && preferred && names.includes(preferred))
+            return preferred;
+        if (names.includes("origin"))
+            return "origin";
+        return names[0];
+    }
+    async rebase(branch, onto, workspace) {
+        const cwd = workspace?.path ?? this.opts.cwd;
+        if (!workspace) {
+            const co = await this.git(["checkout", branch], cwd);
+            if (co.code !== 0) {
+                return { ok: false, conflict: `checkout ${branch} failed: ${co.stderr.trim()}` };
+            }
+        }
+        else {
+            const current = await this.git(["branch", "--show-current"], cwd);
+            if (current.stdout.trim() !== branch) {
+                return { ok: false, conflict: `worktree ${cwd} is on ${current.stdout.trim()}, expected ${branch}` };
+            }
+        }
+        const rb = await this.git(["rebase", onto], cwd);
+        if (rb.code === 0) {
+            return { ok: true, tipSha: (await this.git(["rev-parse", "HEAD"], cwd)).stdout.trim() };
+        }
+        // capture the conflict, then leave the tree clean.
+        const status = await this.git(["diff", "--name-only", "--diff-filter=U"], cwd);
+        await this.git(["rebase", "--abort"], cwd);
+        const files = status.stdout.trim();
+        return {
+            ok: false,
+            conflict: `git rebase ${branch} onto ${onto} failed:\n` +
+                `${(rb.stderr || rb.stdout).trim()}` +
+                (files ? `\nconflicted paths:\n${files}` : ""),
+        };
+    }
+    async fastForward(ref, sha) {
+        const branch = stripHeads(ref);
+        const current = await this.git(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+        if (current.code !== 0 || current.stdout.trim() !== branch) {
+            return {
+                ok: false,
+                reason: `control checkout is on ${current.stdout.trim() || "detached HEAD"}, expected ${branch}`,
+            };
+        }
+        // A checkout-aware fast-forward updates the ref, index, and visible files
+        // together. `update-ref` alone left checked-out main pointing at a tree the
+        // worktree did not display.
+        const old = await this.headSha(ref);
+        const ancestor = await this.git(["merge-base", "--is-ancestor", old, sha]);
+        if (ancestor.code !== 0) {
+            return { ok: false, reason: `${ref} is not an ancestor of ${sha} — not a fast-forward` };
+        }
+        const merged = await this.git(["merge", "--ff-only", sha]);
+        if (merged.code !== 0) {
+            return { ok: false, reason: (merged.stderr || merged.stdout).trim() };
+        }
+        return { ok: true };
+    }
+    async changedFiles(branch, base, workspace) {
+        // files the branch changed relative to its merge-base with the base branch.
+        const { stdout } = await this.git(["diff", "--name-only", `${base}...${branch}`], workspace?.path);
+        return stdout
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+    }
+    async diffText(branch, base, workspace) {
+        // patch vs. the merge-base — what the branch actually proposes.
+        return (await this.git(["diff", `${base}...${branch}`], workspace?.path)).stdout;
+    }
+    async workingTreeFiles(workspace) {
+        const { stdout } = await this.git(["status", "--porcelain"], workspace.path);
+        return parsePorcelain(stdout);
+    }
+    async commitWorkspace(workspace, message) {
+        const cwd = workspace.path;
+        const add = await this.git(["add", "-A"], cwd);
+        if (add.code !== 0) {
+            throw new Error(`git add failed: ${add.stderr.trim() || add.stdout.trim()}`);
+        }
+        const commit = await this.git(["commit", "-m", message], cwd);
+        if (commit.code !== 0) {
+            throw new Error(`git commit failed: ${commit.stderr.trim() || commit.stdout.trim()}`);
+        }
+        return (await this.git(["rev-parse", "HEAD"], cwd)).stdout.trim();
+    }
+}
+function parsePorcelain(stdout) {
+    const files = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        const raw = line.slice(3).trim();
+        const path = raw.includes(" -> ") ? raw.split(" -> ").pop().trim() : raw;
+        if (path)
+            files.push(path.replace(/\\/g, "/"));
+    }
+    return files;
+}
+function stripHeads(ref) {
+    return ref.replace(/^refs\/heads\//, "");
+}
+//# sourceMappingURL=index.js.map