bootproof 0.1.0 → 0.3.0

package/dist/run.d.ts

@@ -1,4 +1,4 @@
-import type { Inference, RunPlan, FailureClass, Attestation } from "./types.js";
+import type { Inference, RunPlan, FailureClass, Attestation, PreparationCommand } from "./types.js";
 export interface UpOptions {
     provider: "docker" | "local";
     unsafeLocal: boolean;
@@ -8,6 +8,8 @@ export interface UpOptions {
     timeoutMs: number;
     install: boolean;
     port?: number;
+    environment?: Record<string, string>;
+    additionalPreparationCommands?: PreparationCommand[];
 }
 export interface UpOutcome {
     inference: Inference;

package/dist/run.js

@@ -1,8 +1,10 @@
 import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
 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 { classifyFailure, extractMissingEnvNames } 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)) {
@@ -22,11 +24,21 @@ export function packageManagerVersionMatches(expected, actual) {
     const actualParts = actualMatch.slice(1, 1 + expectedParts.length);
     return expectedParts.every((part, index) => part === actualParts[index]);
 }
-function packageManagerVersionEvidence(inference) {
+function commandUsesExecutable(command, executable) {
+    if (!command)
+        return false;
+    const escaped = executable.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|&&|\\|\\||;)\\s*${escaped}(?:\\s|$)`).test(command);
+}
+function packageManagerVersionEvidence(inference, plan, env) {
     if (inference.packageManager === "unknown" || !inference.packageManagerVersion)
         return null;
+    if (!plan.steps.some(planned => commandUsesExecutable(planned.command, inference.packageManager)))
+        return null;
     try {
-        const actual = execFileSync(inference.packageManager, ["--version"], { cwd: inference.repoPath, encoding: "utf8" }).trim();
+        const actual = process.platform === "win32"
+            ? execFileSync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", `${inference.packageManager} --version`], { cwd: inference.repoPath, encoding: "utf8", env }).trim()
+            : execFileSync(inference.packageManager, ["--version"], { cwd: inference.repoPath, encoding: "utf8", env }).trim();
         if (packageManagerVersionMatches(inference.packageManagerVersion, actual))
             return null;
         return `packageManager field or engines.${inference.packageManager} expected version: ${inference.packageManagerVersion}\nGot: ${actual}`;
@@ -35,15 +47,65 @@ function packageManagerVersionEvidence(inference) {
         return null;
     }
 }
+function commandWithPort(command, port) {
+    return command
+        .replace(/((?:--port(?:=|\s+)|-p\s+))\d{2,5}\b/, `$1${port}`)
+        .replace(/(\bmanage\.py\s+runserver\s+(?:127\.0\.0\.1|localhost):)\d{2,5}\b/, `$1${port}`);
+}
+function unsupportedOrchestrationExplanation(inference) {
+    if (inference.appCommand)
+        return null;
+    const sourceComposeServices = inference.composeApplicationServices.filter(service => service.source === "build");
+    if (sourceComposeServices.length > 1) {
+        return `Detected multiple source-built HTTP services in ${inference.repoComposeFile}: ${sourceComposeServices.map(service => service.name).join(", ")}. BootProof will not treat one responding service as proof that the repository booted. Diagnosis only — no localhost claim.`;
+    }
+    if (sourceComposeServices.length === 1 && inference.composeHealthCandidates.length === 0) {
+        return `Detected source-built service ${sourceComposeServices[0].name} in ${inference.repoComposeFile}, but no unambiguous published HTTP candidate. Diagnosis only — no localhost claim.`;
+    }
+    const backend = inference.stack.includes("go-backend")
+        ? { stack: "go-backend", markers: inference.backendMarkers.filter(marker => marker === "go.mod" || marker === "go.work") }
+        : inference.stack.includes("ruby-backend")
+            ? { stack: "ruby-backend", markers: inference.backendMarkers.filter(marker => marker === "Gemfile" || marker === "config/database.yml") }
+            : inference.stack.includes("make-driven")
+                ? { stack: "make-driven", markers: inference.backendMarkers.filter(marker => marker === "Makefile") }
+                : null;
+    if (!backend)
+        return null;
+    const frontendStack = inference.stack.includes("react-frontend")
+        ? "react-frontend"
+        : inference.stack.includes("node-frontend")
+            ? "node-frontend"
+            : null;
+    const frontendMarker = inference.frontendMarkers.find(marker => marker.endsWith("/package.json"))
+        ?? inference.frontendMarkers.find(marker => marker === "package.json");
+    const frontend = frontendStack && frontendMarker ? ` with ${frontendStack} (${frontendMarker})` : "";
+    return `Detected ${backend.stack} (${backend.markers.join(", ")})${frontend}. BootProof can diagnose this stack but does not yet orchestrate its boot. Diagnosis only — no localhost claim.`;
+}
 export async function up(repoPath, opts) {
     const startedAt = new Date().toISOString();
     const inference = inferRepo(repoPath, { workspace: opts.workspace });
+    if (opts.additionalPreparationCommands?.length) {
+        inference.preparationCommands.push(...opts.additionalPreparationCommands);
+        inference.dependencyInstallRequired = true;
+    }
     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}`));
+        if (inference.appCommand) {
+            inference.port = opts.port;
+            inference.portEvidence = "set by --port flag";
+            inference.appCommand = commandWithPort(inference.appCommand, opts.port);
+            if (inference.backendCommand)
+                inference.backendCommand = commandWithPort(inference.backendCommand, opts.port);
+            inference.healthCandidates = inference.healthCandidates.map(candidate => candidate.replace(/:\d{2,5}(?=\/)/, `:${opts.port}`));
+        }
+        else if (inference.composeHealthCandidates.length) {
+            inference.portEvidence = `repository Compose published port retained; --port ${opts.port} was not applied`;
+        }
     }
     const plan = buildPlan(inference, opts.provider);
+    const env = minimalEnv({ PORT: String(inference.port), ...opts.environment });
+    const runsSourceComposeApplication = opts.provider === "docker" &&
+        Boolean(inference.repoComposeFile) &&
+        inference.composeHealthCandidates.length > 0;
     const base = { inference, plan, writtenFiles: [] };
     const refuse = (failureClass, explanation, observed = [], failureEvidence = explanation) => {
         const refusal = { failureClass, explanation };
@@ -77,6 +139,13 @@ export async function up(repoPath, opts) {
     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.");
     }
+    const orchestrationExplanation = unsupportedOrchestrationExplanation(inference);
+    if (orchestrationExplanation && !runsSourceComposeApplication) {
+        return refuse("orchestration_not_supported", orchestrationExplanation);
+    }
+    if (!inference.appCommand && inference.composeHealthCandidates.length > 0 && opts.provider !== "docker") {
+        return refuse("orchestration_not_supported", `Detected a source-built application in ${inference.repoComposeFile} with published HTTP candidates, but repository Compose requires --provider docker. Diagnosis only — no localhost claim.`);
+    }
     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.`);
     }
@@ -88,51 +157,99 @@ export async function up(repoPath, opts) {
     }
     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");
+    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.");
+    }
+    const preparationSteps = plan.steps.filter(planned => planned.kind === "install" || planned.kind === "build");
+    if (preparationSteps.length > 0 && !opts.install) {
+        const skipped = step(preparationSteps[0].id, preparationSteps[0].kind, preparationSteps[0].command, 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]);
     }
+    const hostExecutionSteps = plan.steps.filter(planned => planned.kind === "install" ||
+        planned.kind === "build" ||
+        planned.kind === "start-app");
+    if (opts.provider === "docker" && !runsSourceComposeApplication && hostExecutionSteps.length > 0) {
+        return refuse("orchestration_not_supported", `Docker provider selected, but the inferred plan contains host commands (${hostExecutionSteps.map(planned => planned.command).filter(Boolean).join("; ")}). BootProof will not silently run them on the host. Use a source-built repository Compose application, or explicitly choose --provider local --unsafe-local after review.`);
+    }
     if (opts.install) {
-        const versionEvidence = packageManagerVersionEvidence(inference);
+        const versionEvidence = packageManagerVersionEvidence(inference, plan, env);
         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);
+    if (inference.appCommand?.includes(".bootproof/runtime/")) {
+        fs.mkdirSync(path.join(inference.repoPath, ".bootproof", "runtime"), { recursive: true });
+    }
     const observed = [];
-    const env = minimalEnv({ PORT: String(inference.port) });
+    const explanationWithMissingEnv = (failureClass, evidence, explanation) => {
+        if (failureClass !== "missing_env_var")
+            return explanation;
+        const names = extractMissingEnvNames(evidence);
+        if (!names.length)
+            return explanation;
+        const generatedExample = path.join(inference.repoPath, ".env.bootproof.example");
+        const suffix = fs.existsSync(generatedExample)
+            ? `Missing: ${names.join(", ")} — see .env.bootproof.example; bootproof will not invent values.`
+            : `Missing: ${names.join(", ")}; bootproof will not invent values.`;
+        return `${explanation} ${suffix}`;
+    };
     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 });
+        const preciseExplanation = explanationWithMissingEnv(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: preciseExplanation });
         writeAttestation(inference.repoPath, att);
         return { inference, plan, writtenFiles, attestation: att, refusal: null };
     };
+    const composeDiagnostics = async () => {
+        if (!inference.repoComposeFile)
+            return "";
+        const commands = [
+            {
+                id: "compose-ps",
+                command: `docker compose -f ${inference.repoComposeFile} ps --all`,
+                observation: "captured repository Compose service state",
+            },
+            {
+                id: "compose-logs",
+                command: `docker compose -f ${inference.repoComposeFile} logs --no-color --tail 200`,
+                observation: "captured repository Compose logs",
+            },
+        ];
+        const evidence = [];
+        for (const diagnostic of commands) {
+            const t = new Date().toISOString();
+            const result = await runToCompletion(diagnostic.command, inference.repoPath, 30_000, env);
+            const text = [result.stdout, result.stderr].filter(Boolean).join("\n");
+            observed.push(step(diagnostic.id, "service", diagnostic.command, t, result.exitCode, result.exitCode === 0, result.exitCode === 0 ? diagnostic.observation : `${diagnostic.observation} failed`, text || undefined));
+            if (text)
+                evidence.push(`${diagnostic.command}\n${text}`);
+        }
+        return evidence.join("\n");
+    };
     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));
+            observed.push(step(planned.id, "service", planned.command, t, r.exitCode, ok, ok ? "docker compose accepted the start request (exit 0); HTTP health not yet verified" : "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 ((planned.kind === "install" || planned.kind === "build") && 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"));
+                observed.push(step(planned.id, planned.kind, planned.command, new Date().toISOString(), null, false, "skipped by default — preparation was not authorized"));
                 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));
+            observed.push(step(planned.id, planned.kind, planned.command, t, r.exitCode, ok, ok ? `${planned.kind === "install" ? "dependency preparation" : "build"} completed (exit 0)` : r.timedOut ? `${planned.kind} timed out` : `${planned.kind} 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);
@@ -176,6 +293,7 @@ export async function up(repoPath, opts) {
             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;
+            const preciseHealthExplanation = explanationWithMissingEnv(healthClass, `${healthFailureMessage}\n${evidence}`, healthExplanation);
             await app.stop();
             const att = buildAttestation({
                 repo: inference.repoPath,
@@ -188,11 +306,55 @@ export async function up(repoPath, opts) {
                 observedHealthCandidates: health.discoveredCandidates,
                 failureClass: healthClass,
                 failureEvidence: `${healthFailureMessage}\n${evidence}`.slice(-2000),
-                explanation: healthExplanation,
+                explanation: preciseHealthExplanation,
             });
             writeAttestation(inference.repoPath, att);
             return { inference, plan, writtenFiles, attestation: att, refusal: null };
         }
+        if (planned.kind === "health" && runsSourceComposeApplication) {
+            const ht = new Date().toISOString();
+            const health = await pollHealthCandidates(plan.healthCandidates, opts.timeoutMs);
+            plan.healthCandidates = health.candidates;
+            if (health.url)
+                plan.healthUrl = health.url;
+            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)`));
+                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: repository Compose started and ${observedUrl} responded HTTP ${health.status}. This proves the observed web boot, not every service or feature.`,
+                });
+                writeAttestation(inference.repoPath, att);
+                return { inference, plan, writtenFiles, attestation: att, refusal: null };
+            }
+            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));
+            const diagnostics = await composeDiagnostics();
+            const evidence = [healthFailureMessage, diagnostics].filter(Boolean).join("\n");
+            const classified = classifyFailure(evidence);
+            const failureClass = health.responded && health.status !== null && health.status >= 500
+                ? "health_http_error"
+                : classified.class === "unknown_failure"
+                    ? classifyHealthFailure(healthFailureMessage)
+                    : classified.class;
+            const explanation = failureClass === "health_http_error"
+                ? "The Compose application responded on the configured health URL, but returned HTTP 5xx. BootProof observed a server, but not a verified healthy boot."
+                : failureClass === "health_check_timeout"
+                    ? "Repository Compose accepted the start request, but no HTTP response was observed. Compose service state and logs are preserved in the attestation."
+                    : classified.explanation;
+            return fail(failureClass, evidence, explanation);
+        }
     }
-    return fail("not_an_application", "", "Plan contained no runnable app step.");
+    return fail("unknown_failure", "", "Inference identified an application, but the plan contained no supported runnable app or source-built Compose health step.");
 }

package/dist/taxonomy.d.ts

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

package/dist/taxonomy.js

@@ -12,6 +12,28 @@ function isServicePortAllocatedEvidence(evidence) {
         lower.includes("ports are not available") ||
         lower.includes("address already in use"));
 }
+export function extractMissingEnvNames(evidence) {
+    const names = [];
+    const seen = new Set();
+    const patterns = [
+        /\b([A-Z][A-Z0-9_]{2,})\s+is\s+(?:not\s+set|required|missing|undefined)\b/g,
+        /\bMissing required secret:\s*([A-Z][A-Z0-9_]{2,})\b/g,
+        /^\s+([A-Z][A-Z0-9_]{2,}):\s*Required\b/gm,
+        /\bplease set\s+([A-Z][A-Z0-9_]{2,})\b/gi,
+    ];
+    for (const pattern of patterns) {
+        for (const match of evidence.matchAll(pattern)) {
+            const name = match[1].toUpperCase();
+            if (!seen.has(name)) {
+                seen.add(name);
+                names.push(name);
+            }
+            if (names.length === 10)
+                return names;
+        }
+    }
+    return names;
+}
 const RULES = [
     { class: "package_manager_version_mismatch", pattern: /(ERR_PNPM_UNSUPPORTED_ENGINE|Unsupported environment \(bad (?:pnpm|yarn|npm|bun) and\/or Node\.js version\)|(?:pnpm|yarn|npm|bun)[\s\S]{0,160}Expected version:\s*[^\n]+[\s\S]{0,120}Got:\s*[^\n]+|packageManager field[\s\S]{0,120}(?:version|mismatch)|engines\.(?:pnpm|yarn|npm|bun))/i,
         explain: () => "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." },
@@ -19,6 +41,8 @@ const RULES = [
         explain: () => "The host Node version does not satisfy the project's engines requirement. Switch Node versions (nvm/fnm/corepack) and retry." },
     { class: "missing_package_manager", pattern: /\b(yarn|pnpm|bun): (command )?not found/i,
         explain: m => `The project needs ${m[1]} and it is not installed. Enable Corepack (corepack enable) or install ${m[1]} directly.` },
+    { class: "missing_runtime_tool", pattern: /(?:(?:^|\s)(go|ruby|bundle|make|python): (?:command )?not found\b|'(go|ruby|bundle|make|python)' is not recognized as an internal or external command|spawn (go|ruby|bundle|make|python) ENOENT)/im,
+        explain: m => `The repository's explicit run path requires ${m[1] ?? m[2] ?? m[3]}, but that executable is not available in this environment.` },
     { class: "private_registry_or_auth", pattern: /(401 Unauthorized|E401|ENEEDAUTH|authentication token not provided|Permission.*registry)/i,
         explain: () => "Dependency install needs credentials for a private registry. Bootproof will not invent credentials; provide real ones and retry." },
     { class: "native_build_dependency", pattern: /(node-gyp|gyp ERR|pg_config.*not found|fatal error: .*\.h|prebuild-install)/i,
@@ -28,10 +52,10 @@ const RULES = [
     { class: "postgres_auth_env_missing", pattern: /(SASL: SCRAM-SERVER-FIRST-MESSAGE|password authentication failed for user|client password must be a string)/i,
         explain: () => "Postgres was reached but authentication failed — the app's DATABASE_URL credentials don't match the running database. Inspect the repository's own env and compose examples, or rerun after generating BootProof service scaffolding; bootproof will not edit your .env." },
     { class: "database_unreachable", pattern: /(ECONNREFUSED.*:(5432|3306|6379|27017)|P1001|Can'?t reach database server|Connection refused.*postgres)/i,
-        explain: () => "The app requires a database that is not reachable. Start the generated docker-compose.bootproof.yml services first." },
-    { class: "migrations_missing", pattern: /(relation .* does not exist|no such table|Migration.*pending|P3009)/i,
+        explain: () => "The app requires a database that is not reachable. Start the repository's required database service and verify its configured address." },
+    { class: "migrations_missing", pattern: /(relation .* does not exist|no such table|Migration.*pending|unapplied migrations?|PendingMigrationError|P3009)/i,
         explain: () => "The database schema is missing or behind. Run the project's migration command against the local database." },
-    { class: "missing_env_var", pattern: /((Missing|Please set|required) (env(ironment)? var(iable)?s?|.*[A-Z][A-Z0-9_]{3,})|Invalid environment variables)/,
+    { class: "missing_env_var", pattern: /([A-Z][A-Z0-9_]{2,}\s+is\s+(?:not\s+set|required|missing|undefined)|Missing required secret:\s*[A-Z][A-Z0-9_]{2,}|^\s+[A-Z][A-Z0-9_]{2,}:\s*Required\b|please set\s+[A-Z][A-Z0-9_]{2,}|Invalid environment variables)/im,
         explain: () => "The app refuses to start without specific environment variables. See .env.bootproof.example; secrets without safe defaults must come from you." },
     { class: "tls_or_proxy_interception", pattern: /(SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE|unable to get local issuer certificate)/,
         explain: () => "A TLS-intercepting proxy or self-signed certificate chain is blocking package/tool downloads. Configure your proxy CA (NODE_EXTRA_CA_CERTS) or run outside the intercepting network." },
@@ -60,7 +84,7 @@ export function classifyFailure(evidence) {
     };
 }
 export const TAXONOMY_DOC_CLASSES = [
-    "not_an_application", "runtime_engine_mismatch", "missing_package_manager", "package_manager_version_mismatch",
+    "not_an_application", "orchestration_not_supported", "runtime_engine_mismatch", "missing_package_manager", "missing_runtime_tool", "package_manager_version_mismatch",
     "dependency_install_skipped", "python_flask_setup_required", "missing_env_var",
     "database_unreachable", "postgres_auth_env_missing", "migrations_missing", "port_in_use", "native_build_dependency",
     "private_registry_or_auth", "tls_or_proxy_interception", "service_port_allocated", "docker_unavailable", "install_failed", "app_exited_early",

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 export type PackageManager = "npm" | "pnpm" | "yarn" | "bun" | "unknown";
-export type FailureClass = "not_an_application" | "runtime_engine_mismatch" | "missing_package_manager" | "package_manager_version_mismatch" | "dependency_install_skipped" | "python_flask_setup_required" | "missing_env_var" | "database_unreachable" | "postgres_auth_env_missing" | "migrations_missing" | "port_in_use" | "native_build_dependency" | "private_registry_or_auth" | "tls_or_proxy_interception" | "service_port_allocated" | "docker_unavailable" | "install_failed" | "app_exited_early" | "health_check_timeout" | "health_http_error" | "workspace_ambiguous" | "unknown_failure";
+export type FailureClass = "not_an_application" | "orchestration_not_supported" | "runtime_engine_mismatch" | "missing_package_manager" | "missing_runtime_tool" | "package_manager_version_mismatch" | "dependency_install_skipped" | "python_flask_setup_required" | "missing_env_var" | "database_unreachable" | "postgres_auth_env_missing" | "migrations_missing" | "port_in_use" | "native_build_dependency" | "private_registry_or_auth" | "tls_or_proxy_interception" | "service_port_allocated" | "docker_unavailable" | "install_failed" | "app_exited_early" | "health_check_timeout" | "health_http_error" | "workspace_ambiguous" | "unknown_failure";
 export interface ServiceNeed {
     kind: "postgres" | "mysql" | "redis" | "mongodb";
     evidence: string;
@@ -10,6 +10,18 @@ export interface WorkspaceCandidate {
     score: number;
     reason: string;
 }
+export interface PreparationCommand {
+    id: string;
+    kind: "install" | "build";
+    command: string;
+    description: string;
+    source: string;
+}
+export interface ComposeApplicationService {
+    name: string;
+    source: "build" | "image";
+    healthCandidates: string[];
+}
 export interface Inference {
     repoPath: string;
     isApplication: boolean;
@@ -18,11 +30,15 @@ export interface Inference {
     backendMarkers: string[];
     frontendMarkers: string[];
     serviceMarkers: string[];
+    repoComposeFile: string | null;
+    composeApplicationServices: ComposeApplicationService[];
+    composeHealthCandidates: string[];
     setupSteps: string[];
     packageManager: PackageManager;
     packageManagerEvidence: string;
     packageManagerVersion: string | null;
     installCommand: string | null;
+    preparationCommands: PreparationCommand[];
     dependencyInstallRequired: boolean;
     appCommand: string | null;
     appCommandSource: string;
@@ -50,7 +66,7 @@ export interface Inference {
 }
 export interface PlanStep {
     id: string;
-    kind: "install" | "service" | "start-app" | "health";
+    kind: "install" | "build" | "service" | "start-app" | "health";
     command?: string;
     description: string;
     required: boolean;

package/docs/CI_ACTION.md

@@ -26,10 +26,11 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: "22"
+          package-manager-cache: false
 
       - run: npm install --global bootproof
 
@@ -48,7 +49,7 @@ jobs:
 
       - name: Upload evidence
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: bootproof-evidence
           path: .bootproof/

package/docs/FAILURE_TAXONOMY.md

@@ -14,15 +14,17 @@ Unknown evidence remains `unknown_failure`. BootProof does not pick a more marke
 | Class | Meaning | Safe next step |
 |---|---|---|
 | `not_an_application` | No trustworthy runnable entrypoint was found. | Select a runnable workspace or add an explicit start command. |
+| `orchestration_not_supported` | An application stack was detected, but no explicit supported entrypoint or source-built Compose web service was found. | Use the repository's documented runbook; treat the signed result as diagnosis, not boot proof. |
 | `runtime_engine_mismatch` | Node.js does not satisfy the declared engine. | Switch to a compatible runtime and rerun. |
 | `missing_package_manager` | The declared package manager executable is absent. | Enable Corepack or install the required manager. |
+| `missing_runtime_tool` | An explicit Go, Ruby, Bundler, or Make run path was selected, but the executable is absent. | Install the repository-supported runtime or tool and rerun. |
 | `package_manager_version_mismatch` | The available package-manager version differs from the exact/simple declared version. | Activate the declared version, then rerun. |
 | `dependency_install_skipped` | A dependency-backed application was not started because install was not requested. | Review the install command and opt in with `--install`. |
 | `python_flask_setup_required` | Python/Flask setup requires migrations, initialization, workers, frontend, or service orchestration not yet supported safely. | Complete the documented setup manually; do not treat detection as full support. |
 | `missing_env_var` | Required environment configuration is missing. | Supply real values through the repository's documented path. BootProof will not edit `.env`. |
 | `database_unreachable` | A required database or cache could not be reached. | Start the real required service and verify its address. |
 | `postgres_auth_env_missing` | Postgres was reached but authentication or env configuration did not match. | Correct the real database configuration; BootProof will not invent credentials. |
-| `migrations_missing` | The database schema is absent or behind. | Run the repository's documented migration flow. |
+| `migrations_missing` | The database schema is absent or behind. | Run the repository's documented migration flow. Repair is attempted only for one unambiguous recognized framework. |
 | `port_in_use` | The application port is occupied. | Stop the process or use a supported explicit port. |
 | `native_build_dependency` | An OS toolchain or native dependency is missing. | Install the required build dependency and rerun. |
 | `private_registry_or_auth` | Package installation requires credentials. | Provide real registry credentials outside BootProof. |

package/docs/HONESTY_CONTRACT.md

@@ -16,6 +16,12 @@ BootProof's promise is not that every repository boots. Its promise is that the
 10. Failed attestations preserve available raw local evidence; exported registry entries redact it.
 11. A process starting is not enough. A health signal must be observed.
 12. Confidence describes evidence found, not predicted success.
+13. An image-only Compose service does not prove the checked-out source. Compose application proof requires a repository-local build context, a published HTTP port, and an observed HTTP response.
+14. A repair is only ever proposed with a verified before and after attestation.
+15. Repair generation never touches the user's working tree; applying a diff requires the separate explicit `apply-repair` command. This separation is intentional and is not bypassed by `fix`.
+16. Repair diffs are restricted to boot-plumbing scope; application logic is never edited.
+17. An unverified or failed remediation is reported as such and is never proposed on hope.
+18. Explicit repair application requires a valid signed receipt and exact file preimages; stale or tampered receipts write nothing.
 
 These behaviors are enforced by tests.
 
@@ -61,6 +67,25 @@ It does not prove:
 - every service in a platform is healthy
 - another machine will produce the same outcome
 
+A repository Compose receipt is equally narrow. `docker compose up -d` exit 0 proves only that Compose accepted the request. BootProof issues `BOOTED` only after HTTP responds. If health fails, it records Compose service state and logs where available.
+
+## Verified Repairs
+
+`bootproof fix` copies the repository to a temporary sandbox, applies one registered deterministic remediation, and reruns the full BootProof verification engine. It reuses an existing failed attestation only when its signature is valid and it names the exact current clean Git commit; otherwise the failure is reproduced in the sandbox first.
+
+The original working tree is never used as the repair target. BootProof writes only its evidence under `.bootproof/`:
+
+- the signed failed before attestation
+- a human-reviewable patch when files changed
+- the signed healthy after attestation
+- the signed repair receipt linking both hashes
+
+If the sandbox does not reach observed HTTP health, no repair receipt or patch is emitted. The failed attempt is appended to signed failure evidence.
+
+`bootproof fix` never auto-applies a patch. `bootproof apply-repair` is a separate, explicit mutation command. It verifies the receipt signature, scope whitelist, signed content hashes, and current preimages before writing. A mismatch writes nothing.
+
+See [REPAIR_RECEIPT.md](REPAIR_RECEIPT.md).
+
 ## Trust Levels
 
 Current local runs use:
@@ -79,7 +104,11 @@ BootProof itself does not upload telemetry or evidence.
 
 Commands chosen from a repository, such as package installation or application startup, may perform their own network activity. That behavior belongs to the command being executed and should be reviewed before using `--install` or unsafe local execution.
 
-Remote mode accepts only credential-free public HTTPS GitHub repository URLs. BootProof clones them into a retained `.bootproof/remotes/` workspace. Cloning does not authorize execution: a remote application command runs only with `--provider local --unsafe-local`.
+Selecting `--provider docker` never authorizes host execution. If the inferred plan would require host-side install, build, migration, or application commands and no source-built repository Compose application can contain them, BootProof refuses with `orchestration_not_supported`.
+
+Remote mode accepts only credential-free public HTTPS repository URLs from GitHub, GitLab, Bitbucket, and Codeberg. BootProof clones them into a retained `.bootproof/remotes/` workspace. Cloning does not authorize execution: a remote application command runs only with `--provider local --unsafe-local`.
+
+The same rule applies to remote repair. Receipts and patches remain inside the retained clone. Applying a file repair requires naming that local clone with the separate `apply-repair` command.
 
 Remote `--dry-run` is refused before cloning. A clone writes files, while the dry-run contract promises that nothing is written.
 

package/docs/REAL_REPO_EVIDENCE.md

@@ -70,3 +70,80 @@ Useful failure is part of the product:
 - `NOT VERIFIED` can still provide a precise diagnosis and signed evidence.
 - Detection is not the same as execution support.
 - Local proof remains `local_developer_signed`, not enterprise CI/OIDC proof.
+
+## June 11, 2026 Precision Receipts
+
+These runs used fresh shallow clones and did not install dependencies.
+
+### Memos
+
+Command:
+
+```text
+node dist/cli.js up /tmp/memos --provider local --unsafe-local --timeout 10000
+```
+
+Before (`bootproof@0.1.0`):
+
+```text
+application: yes
+stack: go-backend, react-frontend
+health candidates: http://localhost:3000/
+NOT VERIFIED — not_an_application
+```
+
+After precision pass (`bootproof@0.2.0`):
+
+```text
+application: yes
+stack: go-backend, react-frontend
+NOT VERIFIED — orchestration_not_supported
+Detected go-backend (go.mod) with react-frontend (web/package.json).
+Diagnosis only — no localhost claim.
+```
+
+Observed result: exit code 1, signed `local_developer_signed` attestation, `booted: false`, `healthVerified: false`, empty observations, and no health candidates. This is diagnosis, not boot support.
+
+After conservative Go orchestration (`bootproof@0.3.0`):
+
+```text
+go-modules: dependency preparation completed (exit 0)
+start-app: app process started and was supervised
+health: observed HTTP 200 at http://localhost:49865/ after 13047ms
+BOOTED — HTTP 200 at http://localhost:49865/ (observed, signed)
+```
+
+Command:
+
+```text
+node dist/cli.js up /tmp/memos-orchestration --provider local --unsafe-local --install --port 49865 --timeout 120000 --ci
+```
+
+Observed result on June 11, 2026: exit code 0 and a signed `local_developer_signed` attestation. This proves that the checked-out Memos Go entrypoint served HTTP 200 with its embedded frontend assets. It does not prove every Memos feature, integration, or production configuration.
+
+### Formbricks
+
+Command:
+
+```text
+node dist/cli.js analyze /tmp/formbricks
+```
+
+Before (`bootproof@0.1.0`):
+
+```text
+services: postgres; redis
+apps/storybook ranked above apps/web
+no repository Compose file reported
+```
+
+After (`bootproof@0.3.0`):
+
+```text
+repo compose: docker-compose.dev.yml (bootproof defers to it)
+compose HTTP services: mailhog (image only); rustfs (image only); hub (image only); cube (image only)
+apps/web ranked above apps/storybook
+apps/storybook: documentation/storybook downranked
+```
+
+`composeFileFor()` returned null, and no `docker-compose.bootproof.yml` was generated. Analysis exited 0; no application boot was attempted or claimed. The selected Compose services use images rather than repository-local build contexts, so their health cannot prove the checked-out Formbricks source. The root `pnpm dev` command is also a parallel multi-workspace pipeline and remains ambiguous without a selected application.

package/docs/RELEASE_CHECKLIST.md

@@ -71,4 +71,12 @@ BootProof publishes compiled JavaScript, not TypeScript source. `dist/` is requi
    npx bootproof up https://github.com/user/repository
    ```
 
-Remote URL mode accepts credential-free public HTTPS GitHub repositories. It retains clones under `.bootproof/remotes/` and requires `--provider local --unsafe-local` before executing remote repository code.
+Remote URL mode accepts credential-free public HTTPS repositories from GitHub, GitLab, Bitbucket, and Codeberg. It retains clones under `.bootproof/remotes/` and requires `--provider local --unsafe-local` before executing remote repository code.
+
+Remote repair follows the same rule:
+
+```bash
+npx bootproof fix https://github.com/user/repository --provider local --unsafe-local
+```
+
+`fix` never mutates the source tree. `apply-repair` is the separate explicit application step and refuses invalid signatures, disallowed paths, and stale preimages.