specproof 0.2.1 → 0.4.0

package/README.md

@@ -1,53 +1,61 @@
-<img src="public/banner.png" alt="SpecProof" />
+<img src="https://raw.githubusercontent.com/Durable-Quality/specproof/main/public/icon.png" alt="SpecProof" width="120" />
 
 # SpecProof
 
-A standalone Next.js app that renders an audit view of any repo's API test coverage: every OpenAPI operation and response status, cross-examined against the repo's test assertions. Click a stamped verdict to read the test itself.
+Audit your API test coverage against your OpenAPI spec. SpecProof cross-examines every operation and response status in the spec against your test suite's assertions and renders the verdicts as a browsable report. Click any verdict to read the test that proves it, or see exactly what's untested.
 
-Point it at a repo the same way OpenAPI tooling works when installed into one — no repo-specific configuration is baked in:
-
-- **Sources of truth** (read from the target repo, `SPECPROOF_REPO`): the OpenAPI spec (auto-discovered `openapi*.json` / `swagger*.json`, or set `SPECPROOF_SPEC`) + the repo's `*.test.ts` files, parsed from `describe("METHOD /path")` blocks and `.status).toBe(NNN)` assertions. `{param}`, `[param]`, and `:param` path segments are treated as equivalent when matching.
-- **Generator**: `scripts/generate-proof.ts` compiles them into `app/proof.generated.json` — checked in, deterministic, regenerated automatically before `dev`/`build`.
-- **Consumer**: the app renders the checked-in artifact; no target checkout is needed to build or deploy.
-- **Drift guard**: `app/proof-contract.test.ts` fails CI when the artifact is stale relative to the spec/tests, when the proof doesn't cover exactly the spec's operations, or when a quoted snippet no longer points at a real `it()` block. It self-skips when no target repo is configured.
-
-## Setup
+## Quick start
 
 Requires [Bun](https://bun.sh).
 
 ```bash
-bun install
-SPECPROOF_REPO=/path/to/your-repo bun run dev   # compiles the proof, then serves on http://localhost:3001
+bun add -d specproof     # or npm install -D specproof
+bunx specproof dev       # audit the current repo → http://localhost:3001
 ```
 
-`SPECPROOF_REPO` defaults to the current working directory, so running the generator from inside the target repo needs no configuration at all. If the spec isn't named `openapi*.json` / `swagger*.json`, point `SPECPROOF_SPEC` at it (relative to the repo root).
+The OpenAPI spec is auto-discovered (`openapi*.json` / `swagger*.json`); tests are your `*.test.ts` / `*.test.tsx` / `*.test.js` files.
 
-## Commands
+## CLI
 
 ```bash
-bun run dev             # generate:proof + next dev (port 3001)
-bun run build           # generate:proof + next build
-bun run start           # serve the production build (port 3001)
-bun run generate:proof  # regenerate app/proof.generated.json only
-bun run test:unit       # contract tests (self-skip without a configured target repo)
-bun run lint            # ESLint + tsc
+specproof generate [--out proof.json] [--check]   # compile the coverage proof
+specproof dev                                     # generate + serve the report
+specproof build && specproof start                # production build + serve
 ```
 
-## Updating the proof
+| Option | Env var | Meaning |
+| --- | --- | --- |
+| `--repo <path>` | `SPECPROOF_REPO` | Repo to audit (default: current directory) |
+| `--spec <path>` | `SPECPROOF_SPEC` | Spec file, relative to the repo root, when auto-discovery doesn't apply |
+| `--out <path>` | `SPECPROOF_OUT` | Where `generate` writes the proof |
+| `--port <port>` | | Port for `dev` / `start` (default: 3001) |
 
-When the target repo's tests or OpenAPI spec change, the checked-in artifact goes stale and the contract tests fail. The fix:
+## Drift guard in CI
+
+Commit the proof next to your code, then have CI fail whenever the spec or tests change without regenerating it:
 
 ```bash
-SPECPROOF_REPO=/path/to/your-repo bun run generate:proof
-git add app/proof.generated.json && git commit
+specproof generate --out specproof.json           # regenerate + commit
+specproof generate --out specproof.json --check   # CI: exits 1 when stale
 ```
 
 ## Conventions the parser relies on
 
-- Test suites titled `describe("METHOD /path")` (`GET|POST|PUT|DELETE|PATCH`) — the path is matched against the spec's paths.
+- Test suites titled `describe("METHOD /path")` (`GET|POST|PUT|DELETE|PATCH`). The path is matched against the spec's paths; `{param}`, `[param]`, and `:param` segments are equivalent.
 - Status assertions written as `.status).toBe(NNN)` or `.status).toEqual(NNN)`.
 - Prettier-consistent formatting: `it()`/`test()` blocks are extracted by indentation, not a full parser.
 
-## Releasing
+## Development
+
+```bash
+bun install
+bun run dev         # audits the bundled example/ fixture on port 3001
+bun run test:unit   # analyzer unit tests + proof drift guards
+bun run lint        # ESLint + tsc
+```
+
+Point a checkout at a real repo with `SPECPROOF_REPO=/path/to/repo bun run dev`. See [CLAUDE.md](CLAUDE.md) for architecture notes.
+
+## License
 
-Merges to `main` run the [Release workflow](.github/workflows/release.yml), which publishes the package to npm whenever `package.json`'s version isn't on the registry yet (requires the `NPM_TOKEN` repository secret).
+MIT

package/components/CoverageProof.tsx

@@ -228,8 +228,7 @@ function OperationRow({
           {operation.method}
         </span>
         <PathInk specPath={operation.specPath} />
-        <span className="sp-leader hidden sm:block" aria-hidden />
-        <span className="sp-marks shrink-0" aria-hidden>
+        <span className="sp-marks ml-auto shrink-0" aria-hidden>
           {operation.statuses.map((status) => (
             <span key={status.code} className="sp-mark" data-state={verdictOf(status)} />
           ))}
@@ -264,28 +263,33 @@ function TagSection({
   onShowEvidence: (evidence: Evidence) => void;
 }) {
   return (
-    <section className="sp-rise" style={{ '--sp-stagger': index + 3 } as React.CSSProperties}>
-      <header className="mb-1 flex items-baseline gap-4 border-b pb-2">
+    <AccordionItem
+      value={tag.tag}
+      className="sp-rise border-b-0"
+      style={{ '--sp-stagger': index + 3 } as React.CSSProperties}
+    >
+      <AccordionTrigger className="items-baseline gap-4 border-b py-0 pb-2 hover:no-underline">
         <span className="text-[0.65rem] tracking-[0.2em] text-muted-foreground">
           {String(index + 1).padStart(2, '0')}
         </span>
-        <h2 className="text-sm font-semibold uppercase tracking-[0.08em]">{tag.tag}</h2>
+        <span className="text-sm font-semibold uppercase tracking-[0.08em]">{tag.tag}</span>
         <span className="hidden text-xs text-muted-foreground sm:block">{tag.description}</span>
-        <span className="sp-leader" aria-hidden />
-        <span className="text-sm tabular-nums text-muted-foreground">
+        <span className="ml-auto text-sm font-normal tabular-nums text-muted-foreground">
           <span className="text-foreground">{tag.coveredCount}</span>/{tag.totalCount} verified
         </span>
-      </header>
-      <Accordion type="multiple" className="divide-y divide-[var(--sp-hair)]">
-        {tag.operations.map((operation) => (
-          <OperationRow
-            key={`${operation.method} ${operation.specPath}`}
-            operation={operation}
-            onShowEvidence={onShowEvidence}
-          />
-        ))}
-      </Accordion>
-    </section>
+      </AccordionTrigger>
+      <AccordionContent className="pb-0 pt-1">
+        <Accordion type="multiple" className="divide-y divide-[var(--sp-hair)]">
+          {tag.operations.map((operation) => (
+            <OperationRow
+              key={`${operation.method} ${operation.specPath}`}
+              operation={operation}
+              onShowEvidence={onShowEvidence}
+            />
+          ))}
+        </Accordion>
+      </AccordionContent>
+    </AccordionItem>
   );
 }
 
@@ -302,6 +306,7 @@ export function CoverageProof({
 }) {
   const [evidence, setEvidence] = useState<Evidence | null>(null);
   const gapCount = report.totalCount - report.coveredCount;
+  const verifiedPct = Math.round((report.coveredCount / Math.max(report.totalCount, 1)) * 100);
   const facts: Array<[string, string]> = [
     ['operations', String(report.operationCount)],
     ['status pairs verified', `${report.coveredCount}/${report.totalCount}`],
@@ -311,56 +316,43 @@ export function CoverageProof({
 
   return (
     <div className="proof-root proof-page min-h-screen">
-      <div className="mx-auto flex max-w-4xl flex-col gap-14 px-6 py-16">
+      <div className="mx-auto flex max-w-5xl flex-col gap-14 px-6 py-16">
         {/* masthead */}
-        <header className="sp-rise" style={{ '--sp-stagger': 0 } as React.CSSProperties}>
-          <div className="flex flex-wrap items-end justify-between gap-6">
+        <header
+          className="sp-rise flex flex-col gap-8"
+          style={{ '--sp-stagger': 0 } as React.CSSProperties}
+        >
+          <div className="flex flex-wrap items-end justify-between gap-4">
             <h1 className="text-5xl font-semibold tracking-tight">SpecProof</h1>
             <div className="text-right">
-              <div className="text-5xl font-semibold tabular-nums leading-none">
-                {Math.round((report.coveredCount / Math.max(report.totalCount, 1)) * 100)}
-                <span className="text-2xl font-normal text-muted-foreground">%</span>
-              </div>
-              <div className="mt-2 text-[0.65rem] tracking-[0.14em] text-muted-foreground">
-                DOCUMENTED RESPONSES VERIFIED
+              <div className="text-2xl font-semibold tracking-tight">{report.repoName}</div>
+              <div className="mt-2 text-[0.65rem] tracking-[0.18em] tabular-nums text-muted-foreground">
+                {new Date(compiledAt).toISOString().slice(0, 16).replace('T', ' ')} UTC
               </div>
             </div>
           </div>
-        </header>
 
-        {/* summary strip */}
-        <dl
-          className="sp-rise sp-rule-double flex flex-wrap items-baseline gap-x-10 gap-y-3 border-b py-3"
-          style={{ '--sp-stagger': 1 } as React.CSSProperties}
-        >
-          {facts.map(([label, value]) => (
-            <div key={label} className="flex items-baseline gap-2.5">
-              <dd className="text-xl tabular-nums">{value}</dd>
+          {/* report metadata */}
+          <dl className="sp-rule-double flex flex-wrap items-end justify-between gap-x-8 gap-y-4 border-b py-4">
+            {facts.map(([label, value]) => (
+              <div key={label}>
+                <dt className="text-[0.65rem] tracking-[0.18em] text-muted-foreground">
+                  {label.toUpperCase()}
+                </dt>
+                <dd className="mt-2 text-2xl font-semibold tabular-nums">{value}</dd>
+              </div>
+            ))}
+            <div className="text-right">
               <dt className="text-[0.65rem] tracking-[0.18em] text-muted-foreground">
-                {label.toUpperCase()}
+                RESPONSES VERIFIED
               </dt>
+              <dd className="mt-2 text-2xl font-semibold tabular-nums">
+                {verifiedPct}
+                <span className="text-base font-normal text-muted-foreground">%</span>
+              </dd>
             </div>
-          ))}
-          <div className="ml-auto text-[0.65rem] tracking-[0.18em] text-muted-foreground">
-            COMPILED {new Date(compiledAt).toISOString().slice(0, 10)}
-          </div>
-        </dl>
-
-        {/* legend */}
-        <div
-          className="sp-rise -mt-8 flex flex-wrap items-center gap-x-6 gap-y-2 text-[0.65rem] tracking-[0.14em] text-muted-foreground"
-          style={{ '--sp-stagger': 2 } as React.CSSProperties}
-        >
-          <span className="flex items-center gap-2">
-            <span className="sp-mark" data-state="ok" /> VERIFIED
-          </span>
-          <span className="flex items-center gap-2">
-            <span className="sp-mark" data-state="gap" /> NO TEST
-          </span>
-          <span className="flex items-center gap-2">
-            <span className="sp-mark" data-state="undoc" /> UNDOCUMENTED
-          </span>
-        </div>
+          </dl>
+        </header>
 
         {/* tag sections */}
         {report.operationCount === 0 ? (
@@ -370,14 +362,20 @@ export function CoverageProof({
           >
             <p className="text-sm font-semibold tracking-[0.14em]">NO API DEFINITION PROVIDED</p>
             <div className="mt-4 flex flex-col gap-1 text-xs text-muted-foreground">
-              <code className="text-foreground/70">SPECPROOF_REPO=/path/to/repo</code>
-              <code className="text-foreground/70">bun run generate:proof</code>
+              <code className="text-foreground/70">specproof dev --repo /path/to/repo</code>
+              <code className="text-foreground/70">specproof generate --spec path/to/openapi.json</code>
             </div>
           </section>
         ) : (
-          report.tags.map((tag, i) => (
-            <TagSection key={tag.tag} tag={tag} index={i} onShowEvidence={setEvidence} />
-          ))
+          <Accordion
+            type="multiple"
+            defaultValue={report.tags.map((tag) => tag.tag)}
+            className="flex flex-col gap-14"
+          >
+            {report.tags.map((tag, i) => (
+              <TagSection key={tag.tag} tag={tag} index={i} onShowEvidence={setEvidence} />
+            ))}
+          </Accordion>
         )}
       </div>
 

package/lib/api-test-coverage.ts

@@ -127,6 +127,8 @@ export interface TagCoverage {
 }
 
 export interface CoverageReport {
+  /** Display name of the audited repo (its package.json "name", falling back to the directory name) */
+  repoName: string;
   tags: TagCoverage[];
   operationCount: number;
   /** documented (path, method, status) pairs with assertions */
@@ -136,6 +138,19 @@ export interface CoverageReport {
   untestedOperations: number;
 }
 
+/** The audited repo's display name: its package.json "name", falling back to the directory name. */
+export function resolveRepoName(repoRoot: string): string {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')) as {
+      name?: string;
+    };
+    if (pkg.name) return pkg.name;
+  } catch {
+    // no readable package.json — fall through to the directory name
+  }
+  return path.basename(repoRoot);
+}
+
 // ============================================================================
 // Test-file parsing
 // ============================================================================
@@ -378,6 +393,7 @@ export function buildCoverageReport(repoRoot: string = TARGET_REPO_ROOT): Covera
 
   const operations = tags.flatMap((t) => t.operations);
   return {
+    repoName: resolveRepoName(repoRoot),
     tags,
     operationCount: operations.length,
     coveredCount: tags.reduce((n, t) => n + t.coveredCount, 0),

package/next.config.js

@@ -1,6 +1,9 @@
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   reactStrictMode: false,
+  // The app is built from source even when installed under node_modules
+  // (`specproof dev`/`build`); without this, Next's loaders skip its files.
+  transpilePackages: ['specproof'],
 };
 
 export default nextConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specproof",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Audit view of a repo's API test coverage: every OpenAPI operation and response status, cross-examined against the repo's test assertions.",
   "license": "MIT",
   "repository": "github:Durable-Quality/specproof",
@@ -13,6 +13,22 @@
     "audit"
   ],
   "type": "module",
+  "bin": {
+    "specproof": "scripts/cli.ts"
+  },
+  "files": [
+    "app",
+    "components",
+    "lib",
+    "scripts",
+    "!app/proof-contract.test.ts",
+    "!app/proof.generated.json",
+    "!lib/api-test-coverage.test.ts",
+    "next.config.js",
+    "postcss.config.js",
+    "tailwind.config.ts",
+    "tsconfig.json"
+  ],
   "scripts": {
     "build": "bun run generate:proof && bunx next build",
     "dev": "bun run generate:proof && bunx next dev --port 3001",
@@ -28,29 +44,29 @@
   "dependencies": {
     "@radix-ui/react-accordion": "^1.2.16",
     "@radix-ui/react-dialog": "^1.1.15",
+    "@types/node": "24.1.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "autoprefixer": "^10.4.22",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.562.0",
     "next": "^16.0.7",
+    "postcss": "^8.5.6",
+    "postcss-import": "^16.1.1",
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "tailwind-merge": "^3.4.0",
-    "tailwindcss-animate": "^1.0.7"
+    "tailwindcss": "^3.4.18",
+    "tailwindcss-animate": "^1.0.7",
+    "typescript": "^5.9.3"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
-    "@types/node": "24.1.0",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "autoprefixer": "^10.4.22",
     "eslint": "^9.39.1",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
     "globals": "^16.5.0",
-    "postcss": "^8.5.6",
-    "postcss-import": "^16.1.1",
-    "tailwindcss": "^3.4.18",
-    "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.1",
     "vitest": "^4.1.8"
   }

package/scripts/cli.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env bun
+// SpecProof CLI — the entrypoint when the package is installed into a target
+// repo (`bunx specproof <command>`). Audits the repo it is run from (override
+// with --repo / SPECPROOF_REPO) while Next.js dev/build/start run against the
+// SpecProof package directory itself, wherever it is installed.
+
+import path from 'path';
+import { createRequire } from 'module';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const appRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const USAGE = `specproof — audit a repo's API test coverage against its OpenAPI spec
+
+Usage: specproof <command> [options]
+
+Commands:
+  generate   Compile the coverage proof from the target repo's spec + tests
+  dev        generate, then serve the audit view with next dev
+  build      generate, then production-build the audit view
+  start      Serve the production build
+
+Options:
+  --repo <path>   Repo to audit (default: current directory; env SPECPROOF_REPO)
+  --spec <path>   OpenAPI spec, relative to the repo root when the auto-discovery
+                  of openapi*.json / swagger*.json doesn't apply (env SPECPROOF_SPEC)
+  --out <path>    generate only: where to write the proof (default: the app's
+                  bundled artifact; env SPECPROOF_OUT)
+  --check         generate only: verify the proof at --out is up to date instead
+                  of writing — exits 1 on drift (the CI guard)
+  --port <port>   dev/start only: port to serve on (default: 3001)
+`;
+
+function fail(message: string): never {
+  console.error(`specproof: ${message}\n\n${USAGE}`);
+  process.exit(1);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+
+let port = '3001';
+const generateArgs: string[] = [];
+for (let i = 0; i < rest.length; i++) {
+  const arg = rest[i];
+  const value = () => {
+    const v = rest[++i];
+    if (!v) fail(`${arg} requires a value`);
+    return v;
+  };
+  // --repo/--spec become env vars so the analyzer (which reads them at import
+  // time) picks them up when the generator is dynamically imported below.
+  if (arg === '--repo') process.env.SPECPROOF_REPO = value();
+  else if (arg === '--spec') process.env.SPECPROOF_SPEC = value();
+  else if (arg === '--port') port = value();
+  else if (arg === '--out' || arg === '--check') {
+    if (command !== 'generate') fail(`${arg} only applies to the generate command`);
+    generateArgs.push(arg);
+    if (arg === '--out') generateArgs.push(value());
+  } else fail(`unknown option: ${arg}`);
+}
+
+function generate(argv: string[]): number {
+  // Dynamic import so the env vars set above are read, not the values at CLI
+  // startup. require() keeps this synchronous under Bun and Node alike.
+  const require = createRequire(import.meta.url);
+  const { parseGenerateArgs, runGenerate } = require('./generate-proof') as
+    typeof import('./generate-proof');
+  return runGenerate(parseGenerateArgs(argv));
+}
+
+function nextCli(...args: string[]): number {
+  const require = createRequire(import.meta.url);
+  // Resolve Next's bin relative to this package so the CLI works no matter
+  // where the consumer's package manager hoisted the dependency tree.
+  const nextBin = require.resolve('next/dist/bin/next', { paths: [appRoot] });
+  const result = spawnSync(process.execPath, [nextBin, ...args], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  return result.status ?? 1;
+}
+
+switch (command) {
+  case 'generate':
+    process.exit(generate(generateArgs));
+    break;
+  case 'dev':
+  case 'build': {
+    // dev/build always refresh the bundled artifact — it is what the app
+    // renders. A consumer's committed copy (--out) is generate's concern.
+    const generated = generate([]);
+    if (generated !== 0) process.exit(generated);
+    process.exit(
+      command === 'dev'
+        ? nextCli('dev', appRoot, '--port', port)
+        : nextCli('build', appRoot)
+    );
+    break;
+  }
+  case 'start':
+    process.exit(nextCli('start', appRoot, '--port', port));
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+  case undefined:
+    console.log(USAGE);
+    process.exit(command ? 0 : 1);
+    break;
+  default:
+    fail(`unknown command: ${command}`);
+}

package/scripts/generate-proof.ts

@@ -4,16 +4,25 @@
 // SPECPROOF_SPEC).
 //
 // Run via `bun run generate:proof` (also runs automatically before
-// `bun run dev` / `bun run build`). The output is checked in at
-// app/proof.generated.json; the proof-contract test fails if it goes stale
-// relative to the spec or the tests. When no target spec is found, the
-// existing artifact is left untouched so the app still builds and renders.
+// `bun run dev` / `bun run build`), or `specproof generate` when installed.
+// The output defaults to the checked-in artifact at app/proof.generated.json;
+// override with --out / SPECPROOF_OUT to write the proof into the audited
+// repo instead (e.g. to commit it there). --check verifies the output file is
+// up to date without writing — the CI drift guard. When no target spec is
+// found, the existing artifact is left untouched so the app still builds and
+// renders.
 
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
-import { buildCoverageReport, resolveSpecPath, TARGET_REPO_ROOT } from '../lib/api-test-coverage';
+import {
+  buildCoverageReport,
+  resolveRepoName,
+  resolveSpecPath,
+  TARGET_REPO_ROOT,
+  type CoverageReport,
+} from '../lib/api-test-coverage';
 
 const appRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -26,24 +35,100 @@ export function buildProof(): Record<string, unknown> {
   return buildCoverageReport() as unknown as Record<string, unknown>;
 }
 
-const isMain =
-  process.argv[1] &&
-  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+export interface GenerateOptions {
+  /** Where to write (or, with check, what to verify). Resolved against cwd.
+   *  Defaults to SPECPROOF_OUT, then the app's checked-in artifact. */
+  out?: string;
+  /** Verify the file at `out` matches a fresh proof instead of writing. */
+  check?: boolean;
+}
+
+/** Parses --out <path> / --check from a generate argv slice. Throws on
+ *  anything unrecognized so callers surface their own usage text. */
+export function parseGenerateArgs(argv: string[]): GenerateOptions {
+  const options: GenerateOptions = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--check') {
+      options.check = true;
+    } else if (arg === '--out') {
+      const value = argv[++i];
+      if (!value) throw new Error('--out requires a path');
+      options.out = value;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+export function runGenerate(options: GenerateOptions = {}): number {
+  const outPath = path.resolve(
+    options.out ?? process.env.SPECPROOF_OUT ?? GENERATED_PROOF_PATH
+  );
+  const relative = path.relative(process.cwd(), outPath);
+  const outLabel = relative && !relative.startsWith('..') ? relative : outPath;
 
-if (isMain) {
   if (!resolveSpecPath()) {
-    console.warn(
-      `generate-proof: no OpenAPI spec found under ${TARGET_REPO_ROOT} — ` +
-        'set SPECPROOF_REPO to the repo to audit (or SPECPROOF_SPEC to the spec file); keeping the existing proof'
-    );
-    process.exit(0);
+    const hint =
+      `no OpenAPI spec found under ${TARGET_REPO_ROOT} — ` +
+      'set SPECPROOF_REPO to the repo to audit (or SPECPROOF_SPEC to the spec file)';
+    if (options.check) {
+      // A drift check with nothing to check against is a failure, not a skip:
+      // CI asked us to verify the proof and we can't.
+      console.error(`generate-proof: ${hint}`);
+      return 1;
+    }
+    if (!fs.existsSync(outPath)) {
+      // The artifact is not published with the package, so a fresh install has
+      // no proof at all. Write an empty one: the app needs the file to build,
+      // and an empty report renders the "no API definition" state.
+      const empty: CoverageReport = {
+        repoName: resolveRepoName(TARGET_REPO_ROOT),
+        tags: [],
+        operationCount: 0,
+        coveredCount: 0,
+        totalCount: 0,
+        untestedOperations: 0,
+      };
+      fs.writeFileSync(outPath, JSON.stringify(empty, null, 2) + '\n');
+      console.warn(`generate-proof: ${hint}; wrote an empty proof to ${outLabel}`);
+      return 0;
+    }
+    console.warn(`generate-proof: ${hint}; keeping the existing proof`);
+    return 0;
   }
+
   const proof = buildProof();
   const operationCount = (proof.operationCount as number) ?? 0;
   if (operationCount === 0) {
     console.error('generate-proof: no operations found in the OpenAPI spec — refusing to write an empty proof');
-    process.exit(1);
+    return 1;
   }
-  fs.writeFileSync(GENERATED_PROOF_PATH, JSON.stringify(proof, null, 2) + '\n');
-  console.log(`generate-proof: wrote ${path.relative(appRoot, GENERATED_PROOF_PATH)} (${operationCount} operations)`);
+  const serialized = JSON.stringify(proof, null, 2) + '\n';
+
+  if (options.check) {
+    const existing = fs.existsSync(outPath) ? fs.readFileSync(outPath, 'utf8') : null;
+    if (existing !== serialized) {
+      console.error(
+        `generate-proof: ${outLabel} is stale relative to the spec/tests — ` +
+          'regenerate it (specproof generate) and commit the result'
+      );
+      return 1;
+    }
+    console.log(`generate-proof: ${outLabel} is up to date (${operationCount} operations)`);
+    return 0;
+  }
+
+  fs.writeFileSync(outPath, serialized);
+  console.log(`generate-proof: wrote ${outLabel} (${operationCount} operations)`);
+  return 0;
+}
+
+const isMain =
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  process.exit(runGenerate(parseGenerateArgs(process.argv.slice(2))));
 }