bootproof 0.1.0

package/dist/taxonomy.js

@@ -0,0 +1,68 @@
+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 isServicePortAllocatedEvidence(evidence) {
+    const lower = evidence.toLowerCase();
+    return (lower.includes("port is already allocated") ||
+        lower.includes("bind for 0.0.0.0:") ||
+        lower.includes("failed programming external connectivity") ||
+        lower.includes("ports are not available") ||
+        lower.includes("address already in use"));
+}
+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." },
+    { class: "runtime_engine_mismatch", pattern: /(Node version .{0,40}doesn'?t (?:satisfy|match)|The engine "node" is incompatible|EBADENGINE|required:\s*\{\s*node)/i,
+        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: "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,
+        explain: () => "A dependency needs a native toolchain or OS package that is missing on this machine." },
+    { class: "port_in_use", pattern: /(EADDRINUSE|[Pp]ort \d+ is (already )?in use)/,
+        explain: () => "The app port is occupied by another process. Stop it or run with a different PORT." },
+    { 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 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)/,
+        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." },
+    { class: "service_port_allocated", pattern: /(port is already allocated|Bind for 0\.0\.0\.0:\d+ failed|failed programming external connectivity|Ports are not available)/i,
+        explain: () => "Docker is available, but a required service port is already allocated by another local process or container. Stop the process using that port, or rerun with a different service port." },
+    { class: "docker_unavailable", pattern: /(Cannot connect to the Docker daemon|docker: (command )?not found|docker daemon is not running|error during connect)/i,
+        explain: () => "Docker is not available, and this plan needs it for services. Start Docker, or rerun with --provider local --unsafe-local if the app needs no containers." },
+    { class: "health_http_error", pattern: /(only HTTP 5\d\d observed|HTTP 5\d\d|status\s*5\d\d|returned 5\d\d)/i,
+        explain: () => "The app responded on the configured health URL, but returned HTTP 5xx. BootProof observed a running server, but not a verified healthy boot." },
+];
+export function classifyFailure(evidence) {
+    if (isServicePortAllocatedEvidence(evidence) && /(docker|container|bind for|external connectivity|ports are not available|port is already allocated)/i.test(evidence)) {
+        return {
+            class: "service_port_allocated",
+            explanation: "Docker is available, but a required service port is already allocated by another local process or container. Stop the process using that port, or rerun with a different service port.",
+        };
+    }
+    for (const rule of RULES) {
+        const m = evidence.match(rule.pattern);
+        if (m)
+            return { class: rule.class, explanation: rule.explain(m) };
+    }
+    return {
+        class: "unknown_failure",
+        explanation: "Bootproof could not classify this failure. The raw evidence is preserved in the attestation — please open an issue with it so this becomes a new detector.",
+    };
+}
+export const TAXONOMY_DOC_CLASSES = [
+    "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",
+];

package/dist/types.d.ts

@@ -0,0 +1,117 @@
+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 interface ServiceNeed {
+    kind: "postgres" | "mysql" | "redis" | "mongodb";
+    evidence: string;
+}
+export interface WorkspaceCandidate {
+    dir: string;
+    name: string;
+    score: number;
+    reason: string;
+}
+export interface Inference {
+    repoPath: string;
+    isApplication: boolean;
+    notAppReason?: string;
+    stack: string[];
+    backendMarkers: string[];
+    frontendMarkers: string[];
+    serviceMarkers: string[];
+    setupSteps: string[];
+    packageManager: PackageManager;
+    packageManagerEvidence: string;
+    packageManagerVersion: string | null;
+    installCommand: string | null;
+    dependencyInstallRequired: boolean;
+    appCommand: string | null;
+    appCommandSource: string;
+    backendCommand: string | null;
+    frontendCommand: string | null;
+    workerCommand: string | null;
+    commandScope: string;
+    incompleteAppCommand: boolean;
+    multiAppCommand: boolean;
+    port: number;
+    portEvidence: string;
+    healthCandidates: string[];
+    services: ServiceNeed[];
+    requiredEnv: string[];
+    envWithoutSafeDefault: string[];
+    engines: {
+        node?: string;
+        npm?: string;
+        pnpm?: string;
+        yarn?: string;
+        bun?: string;
+    };
+    workspaces: WorkspaceCandidate[];
+    confidence: number;
+}
+export interface PlanStep {
+    id: string;
+    kind: "install" | "service" | "start-app" | "health";
+    command?: string;
+    description: string;
+    required: boolean;
+}
+export interface RunPlan {
+    provider: "docker" | "local";
+    steps: PlanStep[];
+    healthUrl: string;
+    healthCandidates: string[];
+    generatedFiles: {
+        path: string;
+        purpose: string;
+    }[];
+}
+export interface ObservedStep {
+    id: string;
+    kind: PlanStep["kind"];
+    command?: string;
+    startedAt: string;
+    finishedAt: string;
+    exitCode: number | null;
+    ok: boolean;
+    observation: string;
+    evidenceTail?: string;
+}
+export interface AttestationTrust {
+    level: "local_developer_signed" | "ci_oidc_signed";
+    signer: "local_ed25519" | "ci_oidc";
+    oidc: Record<string, string> | null;
+}
+export interface Attestation {
+    schema: "bootproof/attestation/v1";
+    tool: string;
+    repo: {
+        path: string;
+        remote: string | null;
+        commit: string | null;
+        dirty: boolean | null;
+    };
+    environment: {
+        os: string;
+        arch: string;
+        node: string;
+    };
+    trust: AttestationTrust;
+    plan: RunPlan;
+    observed: ObservedStep[];
+    result: {
+        booted: boolean;
+        healthVerified: boolean;
+        healthObservation: string | null;
+        observedHealthCandidates: string[];
+        failureClass: FailureClass | null;
+        failureEvidence: string | null;
+        explanation: string;
+    };
+    startedAt: string;
+    finishedAt: string;
+    signer: {
+        publicKey: string;
+        algorithm: "ed25519";
+    } | null;
+    signature: string | null;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+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";
+}
+export {};

package/docs/CI_ACTION.md

@@ -0,0 +1,75 @@
+# CI Usage
+
+BootProof has a fail-closed machine interface:
+
+```bash
+bootproof up . --ci --json
+```
+
+Exit `0` means both `booted` and `healthVerified` are true. Every refusal or failure exits `1`.
+
+## GitHub Actions Example
+
+This example records the JSON result and preserves the signed attestation even when verification fails:
+
+```yaml
+name: bootproof
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  bootproof:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - run: npm install --global bootproof
+
+      - name: Run BootProof
+        id: bootproof
+        continue-on-error: true
+        shell: bash
+        run: |
+          mkdir -p .bootproof
+          set +e
+          bootproof up . --provider local --unsafe-local --install --timeout 120000 --ci --json \
+            | tee .bootproof/result.json
+          code=${PIPESTATUS[0]}
+          echo "exit_code=$code" >> "$GITHUB_OUTPUT"
+          exit "$code"
+
+      - name: Upload evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: bootproof-evidence
+          path: .bootproof/
+
+      - name: Enforce verdict
+        if: steps.bootproof.outputs.exit_code != '0'
+        run: exit 1
+```
+
+Review execution flags for the target repository. `--install` can run package-manager lifecycle scripts, and `--unsafe-local` acknowledges host execution.
+
+## Current Trust Limitation
+
+Running BootProof in CI does not automatically produce OIDC trust.
+
+Current attestations still say:
+
+```text
+local_developer_signed
+```
+
+They are signed evidence generated on a CI runner, but they are not yet `ci_oidc_signed`. Workload-identity-backed signing remains future work.
+
+BootProof does not silently push commits or upload evidence. The workflow owner chooses whether to retain artifacts or commit `.bootproof/`.

package/docs/FAILURE_TAXONOMY.md

@@ -0,0 +1,55 @@
+# Failure Taxonomy
+
+BootProof classifies failure so humans get a runbook and machines get a stable verdict.
+
+Every class still means:
+
+```text
+booted: false
+healthVerified: false
+```
+
+Unknown evidence remains `unknown_failure`. BootProof does not pick a more marketable class when the evidence is inconclusive.
+
+| Class | Meaning | Safe next step |
+|---|---|---|
+| `not_an_application` | No trustworthy runnable entrypoint was found. | Select a runnable workspace or add an explicit start command. |
+| `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. |
+| `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. |
+| `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. |
+| `tls_or_proxy_interception` | TLS verification is blocked by a proxy or certificate chain. | Configure the trusted CA or use an appropriate network. |
+| `service_port_allocated` | Docker is available, but a service port bind failed. | Stop the conflicting process/container or change the service port. |
+| `docker_unavailable` | Docker is required by the plan but unavailable. | Start Docker or explicitly choose a safe local path. |
+| `install_failed` | Dependency installation failed for an otherwise unclassified reason. | Inspect preserved install evidence and fix the underlying cause. |
+| `app_exited_early` | The application exited before health was observed. | Inspect process evidence and fix startup. |
+| `health_check_timeout` | No HTTP response was observed before timeout. | Check logs, port inference, and health candidates. |
+| `health_http_error` | A health candidate returned HTTP 5xx. | Fix the server error; a responding process is not yet healthy. |
+| `workspace_ambiguous` | Multiple applications or health targets are plausible. | Choose one with `--workspace <dir>`. |
+| `unknown_failure` | Available evidence does not match a trustworthy detector. | Inspect the signed raw evidence and report a reproducible detector case. |
+
+## Important Distinctions
+
+- Docker bind conflicts are `service_port_allocated`, not `docker_unavailable`.
+- HTTP 5xx is `health_http_error`, not `health_check_timeout`.
+- Postgres authentication/env mismatch is `postgres_auth_env_missing`.
+- A skipped install is not success.
+- A detected stack is not a verified boot.
+
+## Evidence
+
+Local failed attestations preserve available raw evidence:
+
+```text
+.bootproof/attestation.json
+```
+
+Registry export redacts sensitive values before producing a shareable entry.

package/docs/HONESTY_CONTRACT.md

@@ -0,0 +1,86 @@
+# BootProof Honesty Contract
+
+BootProof's promise is not that every repository boots. Its promise is that the verdict matches the evidence.
+
+## Non-Negotiable Rules
+
+1. A run is `BOOTED` only after an HTTP health response is observed.
+2. Skipped steps are never rendered as success.
+3. Dry runs execute nothing, write nothing, and create no proof.
+4. `.env`, `.env.local`, `.env.development`, and `.env.production` are never written or modified.
+5. Secrets are never invented.
+6. BootProof never silently patches project files to force startup.
+7. Ambiguous workspaces are surfaced instead of guessed.
+8. Generated files are referenced as generated evidence only when they were actually written.
+9. Refusals and execution failures write signed failed attestations where a signer is available.
+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.
+
+These behaviors are enforced by tests.
+
+## Human And Machine Modes
+
+Human mode:
+
+```bash
+bootproof up .
+```
+
+It explains:
+
+- what happened
+- why BootProof withheld proof
+- a safe next step
+- where the signed evidence lives
+
+Machine mode:
+
+```bash
+bootproof up . --ci --json
+```
+
+It emits one JSON object and exits `0` only for an observed, health-verified boot. Human prose and ANSI colour are excluded from JSON output.
+
+Both modes use the same inference, execution, classification, and signing engine.
+
+## What An Attestation Proves
+
+An attestation is a signed execution receipt containing repository state, environment metadata, the plan, observed steps, health candidates, and the result.
+
+It can prove a narrow claim such as:
+
+```text
+HTTP 200 was observed at http://localhost:3000/
+```
+
+It does not prove:
+
+- every feature works
+- every dependency is production-ready
+- every service in a platform is healthy
+- another machine will produce the same outcome
+
+## Trust Levels
+
+Current local runs use:
+
+```text
+local_developer_signed
+```
+
+Local attestations are useful evidence. CI/OIDC attestations are stronger supply-chain proof. BootProof does not pretend local laptop proof is enterprise CI proof.
+
+`ci_oidc_signed` is reserved for future workload-identity-backed signing. BootProof does not emit it today.
+
+## Network And Sharing
+
+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`.
+
+Remote `--dry-run` is refused before cloning. A clone writes files, while the dry-run contract promises that nothing is written.
+
+Sharing proof is deliberate: inspect and commit `.bootproof/`, or export a redacted registry entry.

package/docs/REAL_REPO_EVIDENCE.md

@@ -0,0 +1,72 @@
+# Real Repository Evidence
+
+This document records observed validation outcomes. It is an evidence ledger, not a compatibility matrix.
+
+A detected stack or useful failure class does not mean BootProof fully supports that repository.
+
+## Plane
+
+- Result: `BOOTED`
+- Observed: HTTP 200 at `localhost:3000`
+- Value: demonstrated an observed web boot with signed proof
+- Limitation: proves only the observed web boot, not full platform health
+
+This result comes from prior validation evidence and was not rerun during the June 10, 2026 documentation pass.
+
+## Twenty
+
+- Result: `NOT VERIFIED`
+- Class: `postgres_auth_env_missing`
+- Value: detected a real database/environment authentication mismatch
+- Limitation: BootProof did not repair credentials, edit `.env`, or claim a boot
+
+This result comes from prior validation evidence and was not rerun during the June 10, 2026 documentation pass.
+
+## Documenso
+
+- Result: `NOT VERIFIED`
+- Class: `health_http_error`
+- Value: services started, dependency installation passed, and the application returned HTTP 500
+- Limitation: a running process and responding server were not treated as healthy
+
+This result comes from prior validation evidence and was not rerun during the June 10, 2026 documentation pass.
+
+## Grafana
+
+- Result: `NOT VERIFIED`
+- Latest class: `dependency_install_skipped`
+- Earlier observed class: `health_check_timeout`
+- Value: exposed the need to distinguish the Go backend from the Node/React frontend pipeline and to downrank test plugins
+- Current inference: `go-backend`, `node-frontend`, `react`
+- Limitation: BootProof detects the hybrid architecture but does not yet orchestrate the full application
+
+The latest local validation ran on June 10, 2026.
+
+## Supabase
+
+- Result: `NOT VERIFIED`
+- Historical class: `package_manager_version_mismatch`
+- Historical evidence: repository required pnpm 10.24 while the environment had pnpm 9.15.4
+- Latest local class: `workspace_ambiguous`
+- Value: package-manager mismatch detection is implemented and tested; a matching package manager still does not make a parallel multi-workspace root command a single verifiable app
+- Limitation: BootProof requires a specific workspace instead of accepting one responding service as proof for the entire repository
+
+The latest local validation on June 10, 2026 had pnpm 10.24.0, so the historical version mismatch did not reproduce.
+
+## Superset
+
+- Result: `NOT VERIFIED`
+- Class: `python_flask_setup_required`
+- Value: detected Python/Flask, React frontend, Docker Compose, Celery, migration/init steps, and port 8088
+- Limitation: BootProof does not yet orchestrate the database migration, initialization, frontend, worker, and service lifecycle required for verification
+
+The latest local validation ran on June 10, 2026.
+
+## Reading These Results
+
+Useful failure is part of the product:
+
+- `BOOTED` requires an observed health signal.
+- `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.

package/docs/REGISTRY.md

@@ -0,0 +1,49 @@
+# Git-Native Registry Design
+
+BootProof does not operate a public registry service today.
+
+The current primitive is portable signed evidence:
+
+```text
+.bootproof/attestation.json
+```
+
+Projects may deliberately commit that file or export a redacted entry:
+
+```bash
+bootproof attest export .
+```
+
+This writes:
+
+```text
+.bootproof/registry-entry.json
+```
+
+Nothing is uploaded automatically.
+
+## Intended Design
+
+The proposed registry model is federated:
+
+- write path: repositories deliberately publish signed proof through Git
+- read path: a future index discovers public attestations, verifies signatures, and links claims to source commits
+- failure corpus: classified failures improve detectors without converting failures into success claims
+
+The index, badge service, freshness tracking, and signer trust graph are roadmap items. They are not deployed capabilities.
+
+## Consent And Privacy
+
+1. BootProof sends no telemetry or hidden evidence upload.
+2. Sharing requires a visible local artifact and an explicit user action.
+3. Full local attestations may contain raw failure evidence.
+4. Registry export applies redaction and records which redactions were used.
+5. A future index should trust only valid signatures and public evidence.
+
+Repository commands executed by BootProof may access the network independently. The no-upload promise applies to BootProof's own telemetry and evidence handling, not arbitrary install or application commands.
+
+## Trust
+
+Current attestations are `local_developer_signed`.
+
+CI/OIDC-backed proof will be stronger because a verifier can bind the signature to a repository workflow identity. BootProof does not claim that trust level yet.

package/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,74 @@
+# npm Release Checklist
+
+BootProof publishes compiled JavaScript, not TypeScript source. `dist/` is required by the `bootproof` executable, generated during `prepack`, ignored by Git, and must not be committed.
+
+## Before Publishing
+
+1. Confirm the working tree contains only the intended release changes:
+
+   ```bash
+   git status --short
+   ```
+
+2. Install exactly the locked development dependencies:
+
+   ```bash
+   npm ci
+   ```
+
+3. Run the tests and a clean build:
+
+   ```bash
+   npm test
+   npm run build
+   ```
+
+4. Pack and smoke-test the installed artifact:
+
+   ```bash
+   npm run pack:check
+   ```
+
+   This checks archive hygiene, installs the tarball under a temporary `HOME`, runs `bootproof --help`, exercises a signed early refusal, verifies and explains that attestation, verifies a healthy fixture, and checks that remote URL mode clones but refuses execution without the host safety gate.
+
+5. Inspect the exact public archive:
+
+   ```bash
+   npm pack --dry-run
+   npm publish --dry-run
+   ```
+
+   The archive must not contain `.git/`, `node_modules/`, `.DS_Store`, `.bootproof/`, local evidence, fixtures, test repositories, or source-only development files.
+
+6. Confirm the package name, version, npm account, and registry target:
+
+   ```bash
+   npm view bootproof
+   npm whoami
+   npm config get registry
+   ```
+
+## Publish
+
+1. Commit the release changes and create the matching GitHub tag:
+
+   ```bash
+   git tag v0.1.0
+   git push origin main --tags
+   ```
+
+2. Publish the public package:
+
+   ```bash
+   npm publish
+   ```
+
+3. Install from the registry in a fresh temporary directory and rerun:
+
+   ```bash
+   npx bootproof --help
+   npx bootproof up /path/to/local/repository
+   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.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "bootproof",
+  "version": "0.1.0",
+  "description": "The honest run button for repos. Boots unfamiliar code when it safely can, tells the truth when it cannot, and signs proof of what happened.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "bootproof": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "pack:check": "node scripts/pack-smoke.mjs",
+    "release:check": "npm test && npm run build && npm run pack:check && npm publish --dry-run",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "ci": "npm run lint && npm run test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rossbuckley1990-hash/bootproof.git"
+  },
+  "keywords": [
+    "devtools",
+    "onboarding",
+    "docker",
+    "run",
+    "attestation",
+    "reproducibility"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.20",
+    "typescript": "5.8.3"
+  },
+  "bugs": {
+    "url": "https://github.com/rossbuckley1990-hash/bootproof/issues"
+  },
+  "homepage": "https://github.com/rossbuckley1990-hash/bootproof#readme"
+}