bootproof 0.1.0

package/dist/cli.js

@@ -0,0 +1,402 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { inferRepo } from "./infer.js";
+import { buildPlan, composeFileFor, envExampleFor } from "./plan.js";
+import { up } from "./run.js";
+import { verifySignature, attestationPath, TOOL_ID } from "./proof.js";
+import { pollHealth } from "./exec.js";
+import { buildRegistryEntry, verifyRegistryEntry, writeRegistryEntry, registryEntryPath } from "./registry.js";
+import { normalizeDockerBindPath, detectHostPlatform } from "./platform.js";
+import { diagnoseFailure } from "./diagnosis.js";
+import { cloneGithubRemote, isRemoteTarget, managedRemoteSource } from "./remote.js";
+let GREEN = "\x1b[32m", YELLOW = "\x1b[33m", RED = "\x1b[31m", DIM = "\x1b[2m", BOLD = "\x1b[1m", RESET = "\x1b[0m";
+const ok = (s) => console.log(`${GREEN}\u2713 ${s}${RESET}`);
+const would = (s) => console.log(`${DIM}\u25cb would: ${s}${RESET}`);
+const warn = (s) => console.log(`${YELLOW}! ${s}${RESET}`);
+const bad = (s) => console.log(`${RED}\u2717 ${s}${RESET}`);
+const disableColor = () => { GREEN = ""; YELLOW = ""; RED = ""; DIM = ""; BOLD = ""; RESET = ""; };
+const COMMANDS = ["up", "analyze", "plan", "verify", "explain", "attest", "help", "version", "--help", "-h", "--version"];
+void normalizeDockerBindPath;
+void detectHostPlatform; // exported surface, used by docker provider work in progress
+if (process.env.NO_COLOR !== undefined)
+    disableColor();
+function parseFlags(argv) {
+    const flags = {};
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else
+                flags[key] = true;
+        }
+        else
+            positional.push(a);
+    }
+    return { flags, positional };
+}
+function help() {
+    console.log(`${BOLD}bootproof${RESET} — Human diagnosis. Machine proof. One engine.
+
+Usage:
+  bootproof analyze <path|github-url> [--workspace dir] [--json]
+                                                            inspect a repo, show evidence-based inference
+  bootproof plan <path|github-url> [--workspace dir]        show the run plan and files that WOULD be generated
+  bootproof up <path|github-url> [options]                  execute the plan, verify localhost, write signed proof
+  bootproof verify <path|attestation.json>              validate an attestation signature and inspect its claim
+  bootproof explain <attestation.json>                  human explanation of an attestation
+  bootproof attest export <path>                        redacted, re-signed shareable registry entry (never uploads)
+  bootproof attest check <path>                         verify a registry entry signature
+  bootproof version
+
+Options for up:
+  --provider docker|local   execution provider (default docker)
+  --unsafe-local            required acknowledgement for --provider local
+  --install                 run the dependency install step (off by default)
+  --workspace <dir>         pick a monorepo workspace
+  --port <n>                override inferred port
+  --timeout <ms>            health verification timeout (default 60000)
+  --dry-run                 show what would happen; executes nothing, writes nothing
+  --json                    one bootproof/result/v1 JSON object on stdout
+  --ci                      no prompts, colours, or interactive UI; fail closed
+
+Honesty contract: no green check without an observed event; dry runs say "would";
+.env/.env.local are never written; secrets are never invented.
+Remote execution requires --provider local --unsafe-local. docs/HONESTY_CONTRACT.md`);
+}
+function printInference(inf) {
+    console.log(`${BOLD}Inference (evidence-based)${RESET}`);
+    console.log(`  application: ${inf.isApplication ? "yes" : `no — ${inf.notAppReason}`}`);
+    if (inf.stack.length)
+        console.log(`  stack: ${inf.stack.join(", ")}`);
+    if (inf.backendMarkers.length)
+        console.log(`  backend markers: ${inf.backendMarkers.join(", ")}`);
+    if (inf.frontendMarkers.length)
+        console.log(`  frontend markers: ${inf.frontendMarkers.join(", ")}`);
+    if (inf.serviceMarkers.length)
+        console.log(`  service markers: ${inf.serviceMarkers.join(", ")}`);
+    console.log(`  package manager: ${inf.packageManager} ${DIM}(${inf.packageManagerEvidence})${RESET}`);
+    if (inf.setupSteps.length)
+        console.log(`  setup steps: ${inf.setupSteps.join("; ")}`);
+    if (inf.backendCommand)
+        console.log(`  backend command: ${inf.backendCommand}`);
+    if (inf.frontendCommand)
+        console.log(`  frontend command: ${inf.frontendCommand}`);
+    if (inf.workerCommand)
+        console.log(`  worker command: ${inf.workerCommand}`);
+    if (inf.appCommand)
+        console.log(`  selected command: ${inf.appCommand} ${DIM}(${inf.appCommandSource})${RESET}`);
+    console.log(`  command scope: ${inf.commandScope}`);
+    console.log(`  port: ${inf.port} ${DIM}(${inf.portEvidence})${RESET}`);
+    if (inf.healthCandidates.length)
+        console.log(`  health candidates: ${inf.healthCandidates.join(", ")}`);
+    if (inf.services.length)
+        console.log(`  services: ${inf.services.map(s => `${s.kind} (${s.evidence})`).join("; ")}`);
+    if (inf.envWithoutSafeDefault.length)
+        console.log(`  secrets you must provide: ${inf.envWithoutSafeDefault.join(", ")}`);
+    if (inf.workspaces.length > 1) {
+        console.log(`  monorepo candidates (ranked):`);
+        for (const w of inf.workspaces.slice(0, 8))
+            console.log(`    ${w.score >= 3 ? "*" : " "} ${w.dir} ${DIM}(${w.name}; ${w.reason})${RESET}`);
+    }
+    console.log(`  confidence: ${inf.confidence}% ${DIM}(heuristic score of evidence found, not a success prediction)${RESET}`);
+}
+function machineResult(outcome, evidencePath) {
+    const result = outcome.attestation?.result;
+    return {
+        schema: "bootproof/result/v1",
+        booted: result?.booted ?? false,
+        healthVerified: result?.healthVerified ?? false,
+        failureClass: result?.failureClass ?? outcome.refusal?.failureClass ?? null,
+        attestationPath: outcome.attestation ? evidencePath : null,
+        inference: outcome.inference,
+        plan: outcome.plan,
+        observed: outcome.attestation?.observed ?? [],
+        explanation: result?.explanation ?? outcome.refusal?.explanation ?? null,
+        trust: outcome.attestation?.trust ?? null,
+        writtenFiles: outcome.writtenFiles,
+    };
+}
+function machineFailure(explanation) {
+    return {
+        schema: "bootproof/result/v1",
+        booted: false,
+        healthVerified: false,
+        failureClass: "unknown_failure",
+        attestationPath: null,
+        inference: {},
+        plan: {},
+        observed: [],
+        explanation,
+        trust: null,
+        writtenFiles: [],
+    };
+}
+function printFailure(failureClass, diagnosis, evidencePath) {
+    bad(`${BOLD}NOT VERIFIED${RESET}${RED} — ${failureClass}`);
+    console.log(`What happened: ${diagnosis.whatHappened}`);
+    console.log(`Why BootProof refused: ${diagnosis.whyRefused}`);
+    console.log(`Safe next step: ${diagnosis.safeNextStep}`);
+    console.log(`Evidence: ${evidencePath}`);
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h")
+        return help();
+    if (cmd === "version" || cmd === "--version")
+        return console.log(TOOL_ID);
+    if (!COMMANDS.includes(cmd)) {
+        bad(`unknown command: ${cmd}`);
+        console.log(`Run ${BOLD}bootproof help${RESET}. Bootproof never guesses what you meant.`);
+        process.exitCode = 1;
+        return;
+    }
+    const { flags, positional } = parseFlags(rest);
+    if (flags.ci || flags.json)
+        disableColor();
+    const targetInput = String(positional[0] ?? ".");
+    let target = path.resolve(targetInput);
+    let remote = null;
+    let remoteSource = null;
+    if (["analyze", "plan", "up"].includes(cmd) && isRemoteTarget(targetInput)) {
+        if (flags["dry-run"]) {
+            const explanation = "Remote dry runs are refused because cloning would write files, while BootProof dry runs promise to write nothing.";
+            if (flags.json)
+                console.log(JSON.stringify(machineFailure(explanation)));
+            else
+                bad(explanation);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            remote = cloneGithubRemote(targetInput, process.cwd());
+            target = remote.repoPath;
+            remoteSource = remote.canonicalUrl;
+            if (!flags.json) {
+                console.log(`${DIM}Remote source: ${remote.canonicalUrl}${RESET}`);
+                console.log(`${DIM}Clone retained at: ${path.relative(process.cwd(), remote.repoPath)}${RESET}`);
+            }
+        }
+        catch (error) {
+            const explanation = error instanceof Error ? error.message : String(error);
+            if (flags.json)
+                console.log(JSON.stringify(machineFailure(explanation)));
+            else
+                bad(explanation);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (!remote && ["analyze", "plan", "up"].includes(cmd)) {
+        remoteSource = managedRemoteSource(target);
+        if (remoteSource && !flags.json) {
+            console.log(`${DIM}Managed remote source: ${remoteSource}${RESET}`);
+        }
+    }
+    const evidencePath = remote
+        ? path.relative(process.cwd(), attestationPath(target))
+        : ".bootproof/attestation.json";
+    if (cmd === "analyze") {
+        const inf = inferRepo(target, { workspace: flags.workspace });
+        if (flags.json)
+            return console.log(JSON.stringify(inf, null, 2));
+        return printInference(inf);
+    }
+    if (cmd === "plan") {
+        const inf = inferRepo(target, { workspace: flags.workspace });
+        printInference(inf);
+        const plan = buildPlan(inf, flags.provider ?? "docker");
+        console.log(`\n${BOLD}Plan (nothing has been executed or written)${RESET}`);
+        for (const s of plan.steps)
+            would(s.command ? `${s.description} — ${DIM}${s.command}${RESET}` : s.description);
+        for (const f of plan.generatedFiles)
+            would(`generate ${f.path} (${f.purpose})`);
+        if (composeFileFor(inf))
+            console.log(`\n${DIM}--- docker-compose.bootproof.yml (preview) ---\n${composeFileFor(inf)}${RESET}`);
+        if (envExampleFor(inf))
+            console.log(`${DIM}--- .env.bootproof.example (preview) ---\n${envExampleFor(inf)}${RESET}`);
+        return;
+    }
+    if (cmd === "up") {
+        const provider = flags.provider ?? "docker";
+        const timeoutMs = Number(flags.timeout ?? 60_000);
+        const port = flags.port === undefined ? undefined : Number(flags.port);
+        const optionError = provider !== "docker" && provider !== "local"
+            ? `invalid --provider value: ${String(provider)} (expected docker or local)`
+            : !Number.isFinite(timeoutMs) || timeoutMs <= 0
+                ? `invalid --timeout value: ${String(flags.timeout)} (expected a positive number)`
+                : port !== undefined && (!Number.isInteger(port) || port < 1 || port > 65_535)
+                    ? `invalid --port value: ${String(flags.port)} (expected an integer from 1 to 65535)`
+                    : null;
+        if (optionError) {
+            if (flags.json)
+                console.log(JSON.stringify(machineFailure(optionError)));
+            else
+                bad(optionError);
+            process.exitCode = 1;
+            return;
+        }
+        const opts = {
+            provider: provider,
+            unsafeLocal: Boolean(flags["unsafe-local"]),
+            dryRun: Boolean(flags["dry-run"]),
+            remoteSource: remoteSource ?? undefined,
+            workspace: flags.workspace,
+            timeoutMs,
+            install: Boolean(flags.install),
+            port,
+        };
+        const outcome = await up(target, opts);
+        const verified = outcome.attestation?.result.booted === true && outcome.attestation.result.healthVerified === true;
+        if (flags.json) {
+            console.log(JSON.stringify(machineResult(outcome, evidencePath)));
+            if (flags.ci || !opts.dryRun)
+                process.exitCode = verified ? 0 : 1;
+            return;
+        }
+        printInference(outcome.inference);
+        console.log("");
+        if (outcome.refusal) {
+            for (const o of outcome.attestation?.observed ?? [])
+                (o.observation.startsWith("skipped") ? warn : o.ok ? ok : bad)(`${o.id}: ${o.observation}`);
+            const diagnosis = diagnoseFailure(outcome.refusal.failureClass, outcome.attestation?.result.failureEvidence ?? null, outcome.refusal.explanation, outcome.inference);
+            printFailure(outcome.refusal.failureClass, diagnosis, evidencePath);
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.dryRun) {
+            console.log(`${BOLD}Dry run — nothing was executed, nothing was written, no proof exists.${RESET}`);
+            for (const s of outcome.plan.steps)
+                would(s.command ? `${s.description} — ${DIM}${s.command}${RESET}` : s.description);
+            for (const f of outcome.plan.generatedFiles)
+                would(`generate ${f.path}`);
+            if (flags.ci)
+                process.exitCode = 1;
+            return;
+        }
+        for (const o of outcome.attestation.observed)
+            (o.observation.startsWith("skipped") ? warn : o.ok ? ok : bad)(`${o.id}: ${o.observation}`);
+        const r = outcome.attestation.result;
+        console.log("");
+        if (r.healthVerified) {
+            ok(`${BOLD}BOOTED${RESET}${GREEN} — ${r.healthObservation} (observed, signed)`);
+            console.log(`Evidence: ${evidencePath}`);
+        }
+        else {
+            const diagnosis = diagnoseFailure(r.failureClass, r.failureEvidence, r.explanation, outcome.inference);
+            printFailure(r.failureClass, diagnosis, evidencePath);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (cmd === "verify") {
+        const p = path.extname(target) === ".json" ? target : attestationPath(target);
+        if (!fs.existsSync(p)) {
+            bad(`no attestation at ${p} — run bootproof up first, or this repo has no committed proof yet`);
+            process.exitCode = 1;
+            return;
+        }
+        const att = JSON.parse(fs.readFileSync(p, "utf8"));
+        const sig = verifySignature(att);
+        (sig ? ok : bad)(`signature ${sig ? "valid" : "INVALID"} (ed25519, trust-on-first-use)`);
+        console.log(`Trust level: ${att.trust?.level ?? "legacy_unspecified"}`);
+        console.log(`${DIM}attested: booted=${att.result.booted} at commit ${att.repo.commit ?? "unknown"} on ${att.environment.os} node ${att.environment.node}${RESET}`);
+        const retainedRemote = managedRemoteSource(att.repo.path);
+        if (retainedRemote) {
+            console.log(`Retained remote source: ${retainedRemote}`);
+            console.log("Replay requires explicit host execution acknowledgement: bootproof up <clone-path> --provider local --unsafe-local.");
+        }
+        else {
+            console.log(`Replaying attested plan with bootproof up --provider ${att.plan.provider} would re-verify it on this machine.`);
+        }
+        if (att.result.booted) {
+            const live = await pollHealth(att.plan.healthUrl, 3000);
+            if (live.responded)
+                ok(`bonus observation: ${att.plan.healthUrl} is responding right now (HTTP ${live.status})`);
+            else
+                console.log(`${DIM}(app not currently running — attestation describes a past verified run)${RESET}`);
+        }
+        if (!sig)
+            process.exitCode = 1;
+        return;
+    }
+    if (cmd === "attest") {
+        const sub = positional[0];
+        const repo = path.resolve(String(positional[1] ?? "."));
+        if (sub === "export") {
+            const ap = attestationPath(repo);
+            if (!fs.existsSync(ap)) {
+                bad(`no attestation at ${ap} — run bootproof up first`);
+                process.exitCode = 1;
+                return;
+            }
+            const att = JSON.parse(fs.readFileSync(ap, "utf8"));
+            const entry = buildRegistryEntry(att);
+            const out = writeRegistryEntry(repo, entry);
+            ok(`wrote redacted registry entry: ${out}`);
+            console.log(`${DIM}redactions applied: ${entry.redactionsApplied.length ? entry.redactionsApplied.join(", ") : "none needed"}${RESET}`);
+            console.log(`Nothing has been uploaded. Bootproof never uploads. To share this proof:`);
+            console.log(`  1. review the file above — it is exactly what others will see;`);
+            console.log(`  2. commit .bootproof/ to your repo (git is the registry), or attach it to a PR/issue.`);
+            return;
+        }
+        if (sub === "check") {
+            const ep = registryEntryPath(repo);
+            if (!fs.existsSync(ep)) {
+                bad(`no registry entry at ${ep}`);
+                process.exitCode = 1;
+                return;
+            }
+            const entry = JSON.parse(fs.readFileSync(ep, "utf8"));
+            const valid = verifyRegistryEntry(entry);
+            (valid ? ok : bad)(`registry entry signature ${valid ? "valid" : "INVALID"}`);
+            console.log(`${DIM}booted=${entry.result.booted} class=${entry.result.failureClass ?? "none"} commit=${entry.repo.commit?.slice(0, 8) ?? "?"}${RESET}`);
+            if (!valid)
+                process.exitCode = 1;
+            return;
+        }
+        bad(`unknown attest subcommand: ${sub ?? "(none)"} — use export or check`);
+        process.exitCode = 1;
+        return;
+    }
+    if (cmd === "explain") {
+        const p = positional[0] ? path.resolve(positional[0]) : attestationPath(target);
+        const att = JSON.parse(fs.readFileSync(p, "utf8"));
+        console.log(`${BOLD}Attestation explained${RESET}`);
+        console.log(att.result.booted ? `This run BOOTED: ${att.result.healthObservation}.` : `This run did NOT verify. Failure class: ${att.result.failureClass}.`);
+        console.log(`Trust level: ${att.trust?.level ?? "legacy_unspecified"}`);
+        if (!att.result.booted && att.result.failureClass) {
+            const diagnosis = diagnoseFailure(att.result.failureClass, att.result.failureEvidence, att.result.explanation);
+            console.log(`What happened: ${diagnosis.whatHappened}`);
+            console.log(`Why BootProof refused: ${diagnosis.whyRefused}`);
+            console.log(`Safe next step: ${diagnosis.safeNextStep}`);
+            console.log(`Evidence: ${p}`);
+        }
+        else {
+            console.log(att.result.explanation);
+        }
+        if (att.plan.healthCandidates?.length)
+            console.log(`Health candidates: ${att.plan.healthCandidates.join(", ")}`);
+        if (att.result.observedHealthCandidates?.length)
+            console.log(`Observed health candidates: ${att.result.observedHealthCandidates.join(", ")}`);
+        for (const o of att.observed)
+            console.log(`  ${o.ok ? "\u2713" : "\u2717"} ${o.id}: ${o.observation}`);
+        return;
+    }
+}
+main().catch(err => {
+    const argv = process.argv.slice(2);
+    if (argv[0] === "up" && argv.includes("--json")) {
+        console.log(JSON.stringify(machineFailure(String(err?.message ?? err))));
+    }
+    else {
+        bad(String(err?.message ?? err));
+    }
+    process.exitCode = 1;
+});

package/dist/diagnosis.d.ts

@@ -0,0 +1,7 @@
+import type { FailureClass, Inference } from "./types.js";
+export interface FailureDiagnosis {
+    whatHappened: string;
+    whyRefused: string;
+    safeNextStep: string;
+}
+export declare function diagnoseFailure(failureClass: FailureClass | null, evidence: string | null, explanation: string, inference?: Inference): FailureDiagnosis;

package/dist/diagnosis.js

@@ -0,0 +1,139 @@
+function packageManagerMismatch(evidence, inference) {
+    const expected = evidence?.match(/expected version:\s*([^\n]+)/i)?.[1]?.trim() ?? inference?.packageManagerVersion ?? "the declared version";
+    const actual = evidence?.match(/Got:\s*([^\n]+)/i)?.[1]?.trim() ?? "a different version";
+    const evidencedManager = evidence?.match(/engines\.(npm|pnpm|yarn|bun)/i)?.[1]?.toLowerCase();
+    const manager = inference?.packageManager && inference.packageManager !== "unknown"
+        ? inference.packageManager
+        : evidencedManager ?? "package manager";
+    const activation = manager === "pnpm"
+        ? `Run corepack enable && corepack prepare pnpm@${expected} --activate, then rerun BootProof.`
+        : `Install or activate ${manager} ${expected}, then rerun BootProof.`;
+    return {
+        whatHappened: `The repository requires ${manager} ${expected}, but this environment has ${manager} ${actual}.`,
+        whyRefused: "The dependency install cannot be trusted with the wrong package manager version.",
+        safeNextStep: activation,
+    };
+}
+export function diagnoseFailure(failureClass, evidence, explanation, inference) {
+    switch (failureClass) {
+        case "package_manager_version_mismatch":
+            return packageManagerMismatch(evidence, inference);
+        case "dependency_install_skipped":
+            return {
+                whatHappened: "The inferred application depends on project packages, but dependency installation was not requested.",
+                whyRefused: "Starting the application without its declared dependencies would not be a trustworthy boot attempt.",
+                safeNextStep: "Review the inferred install command, then rerun with --install if you want BootProof to execute it.",
+            };
+        case "python_flask_setup_required":
+            return {
+                whatHappened: "BootProof detected a Python/Flask application with migration, initialization, frontend, or worker setup steps.",
+                whyRefused: "BootProof cannot yet orchestrate that multi-step application safely enough to claim a verified boot.",
+                safeNextStep: "Review the detected setup and service commands, complete the repository's documented initialization, then rerun when orchestration support is available.",
+            };
+        case "workspace_ambiguous":
+            if (/multiple workspaces in parallel|starts multiple workspaces in parallel/i.test(explanation)) {
+                return {
+                    whatHappened: "The root command starts multiple workspaces in parallel, so there is no single application verdict.",
+                    whyRefused: "One responding workspace would not prove that the whole repository booted.",
+                    safeNextStep: "Choose the intended application with --workspace <dir>, then rerun BootProof.",
+                };
+            }
+            return {
+                whatHappened: "More than one plausible application or health target was detected.",
+                whyRefused: "Choosing one automatically could verify the wrong workspace or mistake one responding service for the whole repository.",
+                safeNextStep: "Choose the intended application with --workspace <dir>, then rerun BootProof.",
+            };
+        case "service_port_allocated":
+            return {
+                whatHappened: "Docker reached the daemon, but a required service port could not be bound.",
+                whyRefused: "The planned service did not start, so the application boot could not be verified.",
+                safeNextStep: "Stop the process or container using the reported port, then rerun BootProof.",
+            };
+        case "health_http_error":
+            return {
+                whatHappened: "The application responded to a health candidate with HTTP 5xx.",
+                whyRefused: "A responding server is not a verified healthy boot when the observed response is a server error.",
+                safeNextStep: "Inspect the application logs and failing health route, fix the server error, then rerun BootProof.",
+            };
+        case "health_check_timeout":
+            return {
+                whatHappened: "No successful HTTP response was observed before the health timeout.",
+                whyRefused: "A running process alone is not proof that the application became reachable and healthy.",
+                safeNextStep: "Check the reported health candidates and application logs, then rerun with the correct port or a longer --timeout if justified.",
+            };
+        case "postgres_auth_env_missing":
+            return {
+                whatHappened: "Postgres was reached, but authentication or database environment configuration did not match.",
+                whyRefused: "The application could not establish the database connection required for a trustworthy boot.",
+                safeNextStep: "Check the repository's real database configuration and credentials. BootProof will not edit .env or invent a password.",
+            };
+        case "not_an_application":
+            return {
+                whatHappened: "No trustworthy runnable application entrypoint was found.",
+                whyRefused: "BootProof will not invent a command or advertise a localhost URL for a library or unrecognized repository.",
+                safeNextStep: "Point BootProof at a runnable workspace, or add an explicit documented start command to the repository.",
+            };
+        case "missing_package_manager":
+            return {
+                whatHappened: "The package manager required by the repository is not available.",
+                whyRefused: "BootProof cannot run the declared install or start command without that executable.",
+                safeNextStep: "Enable Corepack or install the repository's declared package manager, then rerun BootProof.",
+            };
+        case "runtime_engine_mismatch":
+            return {
+                whatHappened: "The available Node.js runtime does not satisfy the repository's declared engine requirement.",
+                whyRefused: "Continuing under an unsupported runtime would make install and boot evidence unreliable.",
+                safeNextStep: "Switch to a compatible Node.js version, then rerun BootProof.",
+            };
+        case "missing_env_var":
+            return {
+                whatHappened: "The application reported required environment configuration that is missing.",
+                whyRefused: "BootProof will not invent secrets or write protected .env files to force startup.",
+                safeNextStep: "Provide the real required values using the repository's documented configuration path, then rerun BootProof.",
+            };
+        case "port_in_use":
+            return {
+                whatHappened: "The application port is already in use.",
+                whyRefused: "BootProof could not observe the inferred application owning and serving that port.",
+                safeNextStep: "Stop the process using the port or rerun with an explicit --port value supported by the application.",
+            };
+        case "docker_unavailable":
+            return {
+                whatHappened: "The run plan requires Docker, but the Docker daemon or command is unavailable.",
+                whyRefused: "Required services could not be started, so BootProof could not verify the application.",
+                safeNextStep: "Start Docker and rerun, or explicitly choose local execution only when it is safe with --provider local --unsafe-local.",
+            };
+        case "install_failed":
+            return {
+                whatHappened: "The dependency install command exited unsuccessfully.",
+                whyRefused: "BootProof cannot trust an application boot when its declared dependency installation failed.",
+                safeNextStep: "Inspect the preserved install evidence, fix the underlying package or environment problem, then rerun BootProof.",
+            };
+        case "app_exited_early":
+            return {
+                whatHappened: "The application process exited before any health response was observed.",
+                whyRefused: "No live application health signal was available to verify.",
+                safeNextStep: "Inspect the preserved process output, fix the startup error, then rerun BootProof.",
+            };
+        default:
+            if (/cloned .* but will not execute remote repository code/i.test(explanation)) {
+                return {
+                    whatHappened: explanation,
+                    whyRefused: "A remote clone is untrusted code, and BootProof requires explicit acknowledgement before running it on the host.",
+                    safeNextStep: "Review the cloned repository, then rerun with --provider local --unsafe-local only if you accept host execution.",
+                };
+            }
+            if (/Local provider runs repository code directly/i.test(explanation)) {
+                return {
+                    whatHappened: explanation,
+                    whyRefused: "Host execution was selected without the required explicit acknowledgement.",
+                    safeNextStep: "Review the inferred commands, then rerun with --provider local --unsafe-local only if you accept host execution.",
+                };
+            }
+            return {
+                whatHappened: explanation,
+                whyRefused: "BootProof did not observe enough evidence to issue a verified boot result.",
+                safeNextStep: "Inspect the signed attestation and raw evidence, address the reported cause, then rerun BootProof.",
+            };
+    }
+}

package/dist/exec.d.ts

@@ -0,0 +1,29 @@
+export interface ExecResult {
+    exitCode: number | null;
+    timedOut: boolean;
+    stdout: string;
+    stderr: string;
+}
+export declare function runToCompletion(command: string, cwd: string, timeoutMs: number, env: NodeJS.ProcessEnv): Promise<ExecResult>;
+export interface SupervisedApp {
+    stop: () => Promise<void>;
+    exited: () => {
+        code: number | null;
+        early: boolean;
+    } | null;
+    output: () => string;
+}
+export declare function superviseApp(command: string, cwd: string, env: NodeJS.ProcessEnv): SupervisedApp;
+export interface HealthObservation {
+    responded: boolean;
+    status: number | null;
+    attempts: number;
+    elapsedMs: number;
+    url: string | null;
+    candidates: string[];
+    discoveredCandidates: string[];
+}
+export declare function extractHealthCandidates(output: string): string[];
+export declare function pollHealthCandidates(initialUrls: string[], timeoutMs: number, output?: () => string, intervalMs?: number): Promise<HealthObservation>;
+export declare function pollHealth(url: string, timeoutMs: number, intervalMs?: number): Promise<HealthObservation>;
+export declare function minimalEnv(extra?: Record<string, string>): NodeJS.ProcessEnv;