bootproof 0.1.0

package/dist/platform.js

@@ -0,0 +1,23 @@
+export function normalizeDockerBindPath(p, platform) {
+    if (platform === "wsl2" && /^\/mnt\/[^/]+\//.test(p))
+        return p;
+    if (platform === "windows") {
+        const m = p.match(/^([A-Za-z]):[\\/](.*)$/);
+        if (m)
+            return `/${m[1].toLowerCase()}/${m[2].replace(/\\/g, "/")}`;
+    }
+    return p;
+}
+export function detectHostPlatform() {
+    if (process.platform === "win32")
+        return "windows";
+    if (process.platform === "darwin")
+        return "macos";
+    try {
+        const fs = require("node:fs");
+        if (/microsoft/i.test(fs.readFileSync("/proc/version", "utf8")))
+            return "wsl2";
+    }
+    catch { /* not linux-with-procfs */ }
+    return "linux";
+}

package/dist/proof.d.ts

@@ -0,0 +1,24 @@
+import type { Attestation, ObservedStep, RunPlan, FailureClass } from "./types.js";
+export declare const TOOL_ID = "bootproof@0.1.0";
+export declare function gitInfo(repo: string): Attestation["repo"];
+export declare function buildAttestation(input: {
+    repo: string;
+    plan: RunPlan;
+    observed: ObservedStep[];
+    startedAt: string;
+    booted: boolean;
+    healthVerified: boolean;
+    healthObservation: string | null;
+    observedHealthCandidates?: string[];
+    failureClass: FailureClass | null;
+    failureEvidence: string | null;
+    explanation: string;
+}): Attestation;
+export declare function signDetached(body: Buffer): {
+    signature: string;
+    publicKeyPem: string;
+};
+export declare function verifyDetached(body: Buffer, signature: string, publicKeyPem: string): boolean;
+export declare function verifySignature(att: Attestation): boolean;
+export declare function attestationPath(repo: string): string;
+export declare function writeAttestation(repo: string, att: Attestation): string;

package/dist/proof.js

@@ -0,0 +1,104 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+export const TOOL_ID = "bootproof@0.1.0";
+export function gitInfo(repo) {
+    const git = (...args) => {
+        try {
+            return execFileSync("git", ["-C", repo, ...args], { encoding: "utf8" }).trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    if (!fs.existsSync(path.join(repo, ".git")))
+        return { path: repo, remote: null, commit: null, dirty: null };
+    const status = git("status", "--porcelain");
+    return {
+        path: repo,
+        remote: git("remote", "get-url", "origin"),
+        commit: git("rev-parse", "HEAD"),
+        dirty: status === null ? null : status.length > 0,
+    };
+}
+function signerKeyPath() {
+    return path.join(os.homedir(), ".bootproof", "signer.json");
+}
+function loadOrCreateSigner() {
+    const p = signerKeyPath();
+    if (fs.existsSync(p)) {
+        const saved = JSON.parse(fs.readFileSync(p, "utf8"));
+        return { privateKey: crypto.createPrivateKey(saved.privateKeyPem), publicKeyPem: saved.publicKeyPem };
+    }
+    const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519");
+    const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+    const publicKeyPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+    fs.mkdirSync(path.dirname(p), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(p, JSON.stringify({ privateKeyPem, publicKeyPem }), { mode: 0o600 });
+    return { privateKey: crypto.createPrivateKey(privateKeyPem), publicKeyPem };
+}
+function canonicalBody(att) {
+    const { signature: _s, signer: _k, ...body } = att;
+    return Buffer.from(JSON.stringify(body));
+}
+export function buildAttestation(input) {
+    const att = {
+        schema: "bootproof/attestation/v1",
+        tool: TOOL_ID,
+        repo: gitInfo(input.repo),
+        environment: { os: `${os.platform()} ${os.release()}`, arch: os.arch(), node: process.version },
+        trust: { level: "local_developer_signed", signer: "local_ed25519", oidc: null },
+        plan: input.plan,
+        observed: input.observed,
+        result: {
+            booted: input.booted,
+            healthVerified: input.healthVerified,
+            healthObservation: input.healthObservation,
+            observedHealthCandidates: input.observedHealthCandidates ?? [],
+            failureClass: input.failureClass,
+            failureEvidence: input.failureEvidence,
+            explanation: input.explanation,
+        },
+        startedAt: input.startedAt,
+        finishedAt: new Date().toISOString(),
+        signer: null,
+        signature: null,
+    };
+    const { privateKey, publicKeyPem } = loadOrCreateSigner();
+    att.signature = crypto.sign(null, canonicalBody(att), privateKey).toString("base64");
+    att.signer = { publicKey: publicKeyPem, algorithm: "ed25519" };
+    return att;
+}
+export function signDetached(body) {
+    const { privateKey, publicKeyPem } = loadOrCreateSigner();
+    return { signature: crypto.sign(null, body, privateKey).toString("base64"), publicKeyPem };
+}
+export function verifyDetached(body, signature, publicKeyPem) {
+    try {
+        return crypto.verify(null, body, crypto.createPublicKey(publicKeyPem), Buffer.from(signature, "base64"));
+    }
+    catch {
+        return false;
+    }
+}
+export function verifySignature(att) {
+    if (!att.signature || !att.signer)
+        return false;
+    try {
+        return crypto.verify(null, canonicalBody(att), crypto.createPublicKey(att.signer.publicKey), Buffer.from(att.signature, "base64"));
+    }
+    catch {
+        return false;
+    }
+}
+export function attestationPath(repo) {
+    return path.join(repo, ".bootproof", "attestation.json");
+}
+export function writeAttestation(repo, att) {
+    const p = attestationPath(repo);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(att, null, 2) + "\n");
+    return p;
+}

package/dist/redact.d.ts

@@ -0,0 +1,4 @@
+export declare function redactText(input: string): {
+    text: string;
+    applied: string[];
+};

package/dist/redact.js

@@ -0,0 +1,31 @@
+// Redaction for shareable artifacts. Rule: anything that leaves the machine goes
+// through here first, and the user is shown the exact redacted output before sharing.
+import os from "node:os";
+const PATTERNS = [
+    { name: "env assignment secrets", re: /\b([A-Z][A-Z0-9_]*(?:SECRET|TOKEN|PASSWORD|PASSWD|API_KEY|PRIVATE_KEY|ACCESS_KEY)[A-Z0-9_]*)=([^\s'"]+)/g, replace: "$1=[redacted]" },
+    { name: "url credentials", re: /\b([a-z][a-z0-9+.-]*:\/\/)([^\s:@\/]+):([^\s@\/]+)@/g, replace: "$1[redacted]:[redacted]@" },
+    { name: "bearer tokens", re: /\b(Bearer|token)\s+[A-Za-z0-9\-._~+/]{16,}={0,2}/g, replace: "$1 [redacted]" },
+    { name: "github tokens", re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, replace: "[redacted-github-token]" },
+    { name: "aws access keys", re: /\bAKIA[0-9A-Z]{16}\b/g, replace: "[redacted-aws-key]" },
+    { name: "jwt-like", re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, replace: "[redacted-jwt]" },
+    { name: "long hex secrets", re: /\b[0-9a-f]{40,}\b/gi, replace: "[redacted-hex]" },
+];
+export function redactText(input) {
+    let text = input;
+    const applied = [];
+    for (const p of PATTERNS) {
+        if (p.re.test(text)) {
+            applied.push(p.name);
+            text = text.replace(p.re, p.replace);
+        }
+        p.re.lastIndex = 0;
+    }
+    // machine-identifying paths
+    const home = os.homedir();
+    if (home && text.includes(home)) {
+        text = text.split(home).join("~");
+        applied.push("home directory path");
+    }
+    text = text.replace(/\/(?:Users|home)\/[^/\s]+/g, "~");
+    return { text, applied };
+}

package/dist/registry.d.ts

@@ -0,0 +1,38 @@
+import type { Attestation } from "./types.js";
+export interface RegistryEntry {
+    schema: "bootproof/registry-entry/v1";
+    tool: string;
+    repo: {
+        remote: string | null;
+        commit: string | null;
+        dirty: boolean | null;
+    };
+    environment: Attestation["environment"];
+    plan: {
+        provider: string;
+        healthUrl: string;
+        steps: {
+            kind: string;
+            command?: string;
+        }[];
+    };
+    result: {
+        booted: boolean;
+        healthVerified: boolean;
+        healthObservation: string | null;
+        failureClass: string | null;
+        redactedEvidence: string | null;
+    };
+    redactionsApplied: string[];
+    attestationSha256: string;
+    attestedAt: string;
+    signer: {
+        publicKey: string;
+        algorithm: "ed25519";
+    } | null;
+    signature: string | null;
+}
+export declare function buildRegistryEntry(att: Attestation): RegistryEntry;
+export declare function verifyRegistryEntry(entry: RegistryEntry): boolean;
+export declare function registryEntryPath(repo: string): string;
+export declare function writeRegistryEntry(repo: string, entry: RegistryEntry): string;

package/dist/registry.js

@@ -0,0 +1,70 @@
+// The proposed BootProof registry is federated by design (docs/REGISTRY.md):
+//   WRITE PATH: developers may commit signed proof to their own repositories.
+//   FUTURE READ PATH: an index could discover public artifacts and verify every signature.
+// No public index is operated today. The CLI never uploads evidence. `attest export` produces a
+// redacted, re-signed local entry; sharing it remains a deliberate git/PR action.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { redactText } from "./redact.js";
+import { signDetached, verifyDetached } from "./proof.js";
+export function buildRegistryEntry(att) {
+    const redactions = new Set();
+    let redactedEvidence = null;
+    if (att.result.failureEvidence) {
+        const r = redactText(att.result.failureEvidence);
+        redactedEvidence = r.text;
+        r.applied.forEach(a => redactions.add(a));
+    }
+    const fullHash = crypto.createHash("sha256").update(JSON.stringify(att)).digest("hex");
+    const entry = {
+        schema: "bootproof/registry-entry/v1",
+        tool: att.tool,
+        repo: { remote: att.repo.remote, commit: att.repo.commit, dirty: att.repo.dirty },
+        environment: att.environment,
+        plan: {
+            provider: att.plan.provider,
+            healthUrl: att.plan.healthUrl,
+            steps: att.plan.steps.map(s => {
+                const r = s.command ? redactText(s.command) : null;
+                if (r)
+                    r.applied.forEach(a => redactions.add(a));
+                return { kind: s.kind, command: r?.text };
+            }),
+        },
+        result: {
+            booted: att.result.booted,
+            healthVerified: att.result.healthVerified,
+            healthObservation: att.result.healthObservation,
+            failureClass: att.result.failureClass,
+            redactedEvidence,
+        },
+        redactionsApplied: [...redactions],
+        attestationSha256: fullHash,
+        attestedAt: att.finishedAt,
+        signer: null,
+        signature: null,
+    };
+    const signed = signDetached(canonical(entry));
+    entry.signature = signed.signature;
+    entry.signer = { publicKey: signed.publicKeyPem, algorithm: "ed25519" };
+    return entry;
+}
+function canonical(entry) {
+    const { signature: _s, signer: _k, ...body } = entry;
+    return Buffer.from(JSON.stringify(body));
+}
+export function verifyRegistryEntry(entry) {
+    if (!entry.signature || !entry.signer)
+        return false;
+    return verifyDetached(canonical(entry), entry.signature, entry.signer.publicKey);
+}
+export function registryEntryPath(repo) {
+    return path.join(repo, ".bootproof", "registry-entry.json");
+}
+export function writeRegistryEntry(repo, entry) {
+    const p = registryEntryPath(repo);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(entry, null, 2) + "\n");
+    return p;
+}

package/dist/remote.d.ts

@@ -0,0 +1,13 @@
+export interface GithubRemote {
+    originalUrl: string;
+    canonicalUrl: string;
+    owner: string;
+    repo: string;
+}
+export interface RemoteClone extends GithubRemote {
+    repoPath: string;
+}
+export declare function isRemoteTarget(value: string): boolean;
+export declare function parseGithubRemote(value: string): GithubRemote;
+export declare function cloneGithubRemote(value: string, cwd: string): RemoteClone;
+export declare function managedRemoteSource(repoPath: string): string | null;

package/dist/remote.js

@@ -0,0 +1,73 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+export function isRemoteTarget(value) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(value) || /^git@/i.test(value);
+}
+export function parseGithubRemote(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("Remote targets must be full HTTPS GitHub repository URLs.");
+    }
+    if (url.protocol !== "https:" || url.hostname.toLowerCase() !== "github.com") {
+        throw new Error("Remote mode currently accepts only public HTTPS GitHub repository URLs.");
+    }
+    if (url.username || url.password || url.port || url.search || url.hash) {
+        throw new Error("Remote URLs must not contain credentials, custom ports, query strings, or fragments.");
+    }
+    const parts = url.pathname.split("/").filter(Boolean);
+    if (parts.length !== 2) {
+        throw new Error("Remote GitHub URLs must identify exactly one repository: https://github.com/owner/repo.");
+    }
+    const owner = parts[0];
+    const repo = parts[1].replace(/\.git$/i, "");
+    const safeSegment = /^[A-Za-z0-9_.-]+$/;
+    if (!safeSegment.test(owner) || !safeSegment.test(repo) || owner === "." || owner === ".." || repo === "." || repo === "..") {
+        throw new Error("Remote GitHub owner and repository names contain unsupported characters.");
+    }
+    return {
+        originalUrl: value,
+        canonicalUrl: `https://github.com/${owner}/${repo}.git`,
+        owner,
+        repo,
+    };
+}
+export function cloneGithubRemote(value, cwd) {
+    const remote = parseGithubRemote(value);
+    const ownerRoot = path.join(cwd, ".bootproof", "remotes", "github.com", remote.owner);
+    fs.mkdirSync(ownerRoot, { recursive: true });
+    const runRoot = fs.mkdtempSync(path.join(ownerRoot, `${remote.repo}-`));
+    const repoPath = path.join(runRoot, "repo");
+    try {
+        execFileSync("git", ["clone", "--depth", "1", "--single-branch", "--no-tags", "--", remote.canonicalUrl, repoPath], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+        const marker = {
+            schema: "bootproof/remote-source/v1",
+            canonicalUrl: remote.canonicalUrl,
+            repoDirectory: "repo",
+        };
+        fs.writeFileSync(path.join(runRoot, "source.json"), JSON.stringify(marker, null, 2) + "\n");
+    }
+    catch (error) {
+        fs.rmSync(runRoot, { recursive: true, force: true });
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not clone ${remote.canonicalUrl}: ${detail}`);
+    }
+    return { ...remote, repoPath };
+}
+export function managedRemoteSource(repoPath) {
+    const markerPath = path.join(path.dirname(path.resolve(repoPath)), "source.json");
+    try {
+        const marker = JSON.parse(fs.readFileSync(markerPath, "utf8"));
+        return marker.schema === "bootproof/remote-source/v1"
+            && marker.repoDirectory === path.basename(path.resolve(repoPath))
+            && typeof marker.canonicalUrl === "string"
+            ? marker.canonicalUrl
+            : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/run.d.ts

@@ -0,0 +1,23 @@
+import type { Inference, RunPlan, FailureClass, Attestation } from "./types.js";
+export interface UpOptions {
+    provider: "docker" | "local";
+    unsafeLocal: boolean;
+    dryRun: boolean;
+    remoteSource?: string;
+    workspace?: string;
+    timeoutMs: number;
+    install: boolean;
+    port?: number;
+}
+export interface UpOutcome {
+    inference: Inference;
+    plan: RunPlan;
+    attestation: Attestation | null;
+    refusal: {
+        failureClass: FailureClass;
+        explanation: string;
+    } | null;
+    writtenFiles: string[];
+}
+export declare function packageManagerVersionMatches(expected: string, actual: string): boolean;
+export declare function up(repoPath: string, opts: UpOptions): Promise<UpOutcome>;

package/dist/run.js

@@ -0,0 +1,198 @@
+import { execFileSync } from "node:child_process";
+import { inferRepo } from "./infer.js";
+import { buildPlan, writePlanFiles } from "./plan.js";
+import { runToCompletion, superviseApp, pollHealthCandidates, minimalEnv } from "./exec.js";
+import { classifyFailure } from "./taxonomy.js";
+import { buildAttestation, writeAttestation } from "./proof.js";
+function classifyHealthFailure(evidence) {
+    if (/(only HTTP 5\d\d observed|HTTP 5\d\d|status\s*5\d\d|returned 5\d\d)/i.test(evidence)) {
+        return "health_http_error";
+    }
+    return "health_check_timeout";
+}
+function step(id, kind, command, startedAt, exitCode, ok, observation, evidenceTail) {
+    return { id, kind, command, startedAt, finishedAt: new Date().toISOString(), exitCode, ok, observation, evidenceTail };
+}
+export function packageManagerVersionMatches(expected, actual) {
+    const expectedMatch = expected.trim().match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
+    const actualMatch = actual.trim().match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    if (!expectedMatch || !actualMatch)
+        return true;
+    const expectedParts = expectedMatch.slice(1).filter((part) => part !== undefined);
+    const actualParts = actualMatch.slice(1, 1 + expectedParts.length);
+    return expectedParts.every((part, index) => part === actualParts[index]);
+}
+function packageManagerVersionEvidence(inference) {
+    if (inference.packageManager === "unknown" || !inference.packageManagerVersion)
+        return null;
+    try {
+        const actual = execFileSync(inference.packageManager, ["--version"], { cwd: inference.repoPath, encoding: "utf8" }).trim();
+        if (packageManagerVersionMatches(inference.packageManagerVersion, actual))
+            return null;
+        return `packageManager field or engines.${inference.packageManager} expected version: ${inference.packageManagerVersion}\nGot: ${actual}`;
+    }
+    catch {
+        return null;
+    }
+}
+export async function up(repoPath, opts) {
+    const startedAt = new Date().toISOString();
+    const inference = inferRepo(repoPath, { workspace: opts.workspace });
+    if (opts.port) {
+        inference.port = opts.port;
+        inference.portEvidence = "set by --port flag";
+        inference.healthCandidates = inference.healthCandidates.map(candidate => candidate.replace(/:\d{2,5}(?=\/)/, `:${opts.port}`));
+    }
+    const plan = buildPlan(inference, opts.provider);
+    const base = { inference, plan, writtenFiles: [] };
+    const refuse = (failureClass, explanation, observed = [], failureEvidence = explanation) => {
+        const refusal = { failureClass, explanation };
+        if (opts.dryRun)
+            return { ...base, attestation: null, refusal };
+        const ungeneratedPaths = plan.generatedFiles.map(file => file.path);
+        const refusalPlan = {
+            ...plan,
+            steps: plan.steps.filter(planned => !ungeneratedPaths.some(file => planned.command?.includes(file))),
+            generatedFiles: [],
+        };
+        const attestation = buildAttestation({
+            repo: inference.repoPath,
+            plan: refusalPlan,
+            observed,
+            startedAt,
+            booted: false,
+            healthVerified: false,
+            healthObservation: null,
+            observedHealthCandidates: [],
+            failureClass,
+            failureEvidence: failureEvidence.slice(-2000),
+            explanation,
+        });
+        writeAttestation(inference.repoPath, attestation);
+        return { inference, plan: refusalPlan, writtenFiles: [], attestation, refusal };
+    };
+    if (!inference.isApplication) {
+        return refuse("not_an_application", inference.notAppReason);
+    }
+    if (inference.stack.includes("python-backend") && inference.stack.includes("flask") && inference.setupSteps.length > 0) {
+        return refuse("python_flask_setup_required", "BootProof detected a Python/Flask + React application with setup steps. This repository requires database migration/init and service orchestration before it can be verified.");
+    }
+    if (!opts.workspace && inference.workspaces.length > 1 && !inference.appCommand) {
+        return refuse("workspace_ambiguous", `This is a monorepo with ${inference.workspaces.length} workspace candidates. Choose one with --workspace <dir> instead of letting bootproof guess.`);
+    }
+    if (opts.remoteSource && !opts.dryRun && (opts.provider !== "local" || !opts.unsafeLocal)) {
+        return refuse("unknown_failure", `BootProof cloned ${opts.remoteSource} for inspection but will not execute remote repository code without --provider local --unsafe-local.`);
+    }
+    if (opts.provider === "local" && !opts.unsafeLocal) {
+        return refuse("unknown_failure", "Local provider runs repository code directly on your machine. Re-run with --unsafe-local to acknowledge this, or use --provider docker.");
+    }
+    if (opts.dryRun)
+        return { ...base, attestation: null, refusal: null };
+    if (inference.dependencyInstallRequired && !opts.install) {
+        const skipped = step("install", "install", inference.installCommand ?? undefined, new Date().toISOString(), null, false, "skipped by default — dependency-backed application was not started; pass --install to run dependency installation");
+        return refuse("dependency_install_skipped", "The inferred application command depends on project packages, but dependency installation was not requested. BootProof did not start the partial application pipeline.", [skipped]);
+    }
+    if (opts.install) {
+        const versionEvidence = packageManagerVersionEvidence(inference);
+        if (versionEvidence) {
+            const observed = step("package-manager-version", "install", `${inference.packageManager} --version`, new Date().toISOString(), 0, false, `declared ${inference.packageManager} ${inference.packageManagerVersion}, but found ${versionEvidence.split("Got: ")[1]}`, versionEvidence);
+            return refuse("package_manager_version_mismatch", "The repository declares a package manager version that does not match the version available in the current environment. Enable Corepack or install the required package manager version before rerunning BootProof.", [observed], versionEvidence);
+        }
+    }
+    if (inference.multiAppCommand) {
+        return refuse("workspace_ambiguous", "BootProof detected a root command that starts multiple workspaces in parallel. Choose a specific application with --workspace <dir>; one responding workspace is not proof that the whole repository booted.");
+    }
+    if (inference.incompleteAppCommand) {
+        return refuse("unknown_failure", "BootProof detected a hybrid backend/frontend repository, but the inferred command starts only the frontend development pipeline. Complete application orchestration is not implemented, so no boot was attempted.");
+    }
+    const writtenFiles = writePlanFiles(inference, inference.repoPath);
+    const observed = [];
+    const env = minimalEnv({ PORT: String(inference.port) });
+    const fail = (failureClass, evidence, explanation) => {
+        const att = buildAttestation({ repo: inference.repoPath, plan, observed, startedAt, booted: false, healthVerified: false, healthObservation: null, observedHealthCandidates: [], failureClass, failureEvidence: evidence.slice(-2000), explanation });
+        writeAttestation(inference.repoPath, att);
+        return { inference, plan, writtenFiles, attestation: att, refusal: null };
+    };
+    for (const planned of plan.steps) {
+        if (planned.kind === "service" && planned.command) {
+            const t = new Date().toISOString();
+            const r = await runToCompletion(planned.command, inference.repoPath, 120_000, env);
+            const ok = r.exitCode === 0;
+            observed.push(step(planned.id, "service", planned.command, t, r.exitCode, ok, ok ? "services started (docker compose exit 0)" : "docker compose failed", r.stderr || r.stdout));
+            if (!ok) {
+                const c = classifyFailure(r.stderr + r.stdout);
+                return fail(c.class, r.stderr + r.stdout, c.explanation);
+            }
+        }
+        if (planned.kind === "install" && planned.command) {
+            if (!opts.install) {
+                observed.push(step(planned.id, "install", planned.command, new Date().toISOString(), null, false, "skipped by default — optional install was not needed for the observed boot"));
+                continue;
+            }
+            const t = new Date().toISOString();
+            const r = await runToCompletion(planned.command, inference.repoPath, 600_000, env);
+            const ok = r.exitCode === 0 && !r.timedOut;
+            observed.push(step(planned.id, "install", planned.command, t, r.exitCode, ok, ok ? "dependencies installed (exit 0)" : r.timedOut ? "install timed out" : `install failed (exit ${r.exitCode})`, ok ? undefined : r.stderr || r.stdout));
+            if (!ok) {
+                const c = classifyFailure(r.stderr + r.stdout);
+                return fail(c.class === "unknown_failure" ? "install_failed" : c.class, r.stderr + r.stdout, c.explanation);
+            }
+        }
+        if (planned.kind === "start-app" && planned.command) {
+            const t = new Date().toISOString();
+            const app = superviseApp(planned.command, inference.repoPath, env);
+            const health = await pollHealthCandidates(plan.healthCandidates, opts.timeoutMs, app.output);
+            plan.healthCandidates = health.candidates;
+            if (health.url)
+                plan.healthUrl = health.url;
+            const exit = app.exited();
+            if (exit && !health.responded) {
+                observed.push(step(planned.id, "start-app", planned.command, t, exit.code, false, `app process exited (code ${exit.code}) before responding`, app.output()));
+                const c = classifyFailure(app.output());
+                await app.stop();
+                return fail(c.class === "unknown_failure" ? "app_exited_early" : c.class, app.output(), c.explanation);
+            }
+            observed.push(step(planned.id, "start-app", planned.command, t, null, true, "app process started and was supervised"));
+            const ht = new Date().toISOString();
+            if (health.responded && health.status !== null && health.status < 500) {
+                const observedUrl = health.url ?? plan.healthUrl;
+                observed.push(step("health", "health", undefined, ht, null, true, `observed HTTP ${health.status} at ${observedUrl} after ${health.elapsedMs}ms (${health.attempts} attempts)`));
+                await app.stop();
+                const att = buildAttestation({ repo: inference.repoPath, plan, observed, startedAt, booted: true, healthVerified: true, healthObservation: `HTTP ${health.status} at ${observedUrl}`, observedHealthCandidates: health.discoveredCandidates, failureClass: null, failureEvidence: null, explanation: `Verified: ${observedUrl} responded HTTP ${health.status}. This attestation records what was observed, not a guarantee the app is fully functional.` });
+                writeAttestation(inference.repoPath, att);
+                return { inference, plan, writtenFiles, attestation: att, refusal: null };
+            }
+            const evidence = app.output();
+            const healthFailureMessage = health.responded
+                ? `only HTTP ${health.status} observed at ${health.url ?? plan.healthUrl}`
+                : `no HTTP response at candidates ${health.candidates.join(", ")} within ${opts.timeoutMs}ms`;
+            observed.push(step("health", "health", undefined, ht, null, false, healthFailureMessage, evidence));
+            const c = classifyFailure(`${healthFailureMessage}\n${evidence}`);
+            const healthClass = health.responded && health.status !== null && health.status >= 500
+                ? "health_http_error"
+                : c.class === "unknown_failure"
+                    ? classifyHealthFailure(healthFailureMessage)
+                    : c.class;
+            const healthExplanation = healthClass === "health_http_error"
+                ? "The app responded on the configured health URL, but returned HTTP 5xx. BootProof observed a running server, but not a verified healthy boot."
+                : c.explanation;
+            await app.stop();
+            const att = buildAttestation({
+                repo: inference.repoPath,
+                plan,
+                observed,
+                startedAt,
+                booted: false,
+                healthVerified: false,
+                healthObservation: null,
+                observedHealthCandidates: health.discoveredCandidates,
+                failureClass: healthClass,
+                failureEvidence: `${healthFailureMessage}\n${evidence}`.slice(-2000),
+                explanation: healthExplanation,
+            });
+            writeAttestation(inference.repoPath, att);
+            return { inference, plan, writtenFiles, attestation: att, refusal: null };
+        }
+    }
+    return fail("not_an_application", "", "Plan contained no runnable app step.");
+}

package/dist/taxonomy.d.ts

@@ -0,0 +1,6 @@
+import type { FailureClass } from "./types.js";
+export declare function classifyFailure(evidence: string): {
+    class: FailureClass;
+    explanation: string;
+};
+export declare const TAXONOMY_DOC_CLASSES: FailureClass[];