forgeos 0.1.0-alpha.30 → 0.1.0-alpha.31

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.30 input=5d12d4ad2a959d692b306eb18ba706c52f22f2d148c6e4ed541bd67fd8222c84 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
+// @forge-generated generator=0.1.0-alpha.31 input=ffdf0fea34e4880fa5215aaef174878f8b3e824def735dec6040c8a7502c4ae4 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # forgeos
 
+## 0.1.0-alpha.31
+
+### Patch Changes
+
+- Smooth the ForgeOS field-demo DX after the alpha.30 app-server and WorkOS exercises.
+
+  - Add `forge baseline create` and `forge baseline status` so non-git template workspaces can establish a local baseline and get useful `forge changed` / `forge handoff` diffs instead of noisy filesystem inventories.
+  - Add `forge auth status` and production-focused `forge auth prove --prod` output so `dev-headers` is clearly labeled as local-only while JWT/OIDC proofs show production auth posture.
+  - Expand `forge doctor windows` with local PGlite store posture and cleanup guidance, including safer PGlite abort inspection that does not poison the surrounding process exit code.
+  - Add `forge ui audit` and run it during `forge verify --smoke` when a web app is present, catching missing UI scenarios, missing stable Forge test IDs, and missing policy-denied coverage for sensitive routes.
+
 ## 0.1.0-alpha.30
 
 ### Patch Changes

package/docs/changelog.md

@@ -6,6 +6,22 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.31
+
+- Added Forge workspace baselines for non-git app directories:
+  `forge baseline create` records a local baseline and `forge changed` /
+  `forge handoff` can now report baseline diffs instead of noisy full
+  filesystem inventories.
+- Added `forge auth status` and production-aware `forge auth prove --prod`
+  posture checks so local `dev-headers` auth is clearly distinguished from
+  JWT/OIDC production authentication.
+- Expanded `forge doctor windows` with local PGlite store posture and cleanup
+  guidance, and made PGlite abort inspection preserve the surrounding process
+  exit code.
+- Added `forge ui audit` and wired it into `forge verify --smoke` for web apps
+  to catch missing route scenarios, missing stable Forge test IDs, and missing
+  policy-denied coverage for sensitive flows.
+
 ## 0.1.0-alpha.30
 
 - Hardened the WorkOS/AuthKit adapter and dev telemetry after the alpha.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.31",
   "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
   "type": "module",
   "license": "MIT",

package/src/forge/_generated/releaseManifest.json

@@ -1 +1 @@
-{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.30","releaseId":"forgeos@0.1.0-alpha.30+unknown","schemaVersion":"0.1.0"}
+{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.31","releaseId":"forgeos@0.1.0-alpha.31+unknown","schemaVersion":"0.1.0"}

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.30 input=5d12d4ad2a959d692b306eb18ba706c52f22f2d148c6e4ed541bd67fd8222c84 content=065153708d210de0b5893a6e8c8ecbfc8bab3b011c8f1e576ae54d9c59bff838
+// @forge-generated generator=0.1.0-alpha.31 input=ffdf0fea34e4880fa5215aaef174878f8b3e824def735dec6040c8a7502c4ae4 content=806e4e7f20264628107bf964331f13335175f065d6a8826b5defc2027d8047cd
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.30",
-  "releaseId": "forgeos@0.1.0-alpha.30+unknown",
+  "packageVersion": "0.1.0-alpha.31",
+  "releaseId": "forgeos@0.1.0-alpha.31+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/cli/auth.ts

@@ -10,13 +10,14 @@ import { ForgeAuthError } from "../runtime/auth/errors.ts";
 import { verifyJwtToken } from "../runtime/auth/verifier.ts";
 import { loadSecretRegistry } from "../runtime/secrets/check.ts";
 
-export type AuthSubcommand = "check" | "config" | "decode" | "test-token" | "jwks" | "prove";
+export type AuthSubcommand = "check" | "config" | "decode" | "test-token" | "jwks" | "prove" | "status";
 
 export interface AuthCommandOptions {
   subcommand: AuthSubcommand;
   workspaceRoot: string;
   json: boolean;
   token?: string;
+  prod?: boolean;
 }
 
 export interface AuthCommandResult {
@@ -59,11 +60,8 @@ function detectWorkOS(workspaceRoot: string, claims: AuthClaimsMapping) {
   };
 }
 
-function validateConfig(workspaceRoot: string): AuthCommandResult {
-  const config = loadAuthConfigFromEnv(workspaceRoot);
+function configErrors(config: ReturnType<typeof loadAuthConfigFromEnv>): { code: string; message: string }[] {
   const errors: { code: string; message: string }[] = [];
-  const workos = detectWorkOS(workspaceRoot, config.claims);
-
   if ((config.mode === "jwt" || config.mode === "oidc") && !config.issuer) {
     errors.push({
       code: FORGE_AUTH_INVALID_ISSUER,
@@ -82,6 +80,39 @@ function validateConfig(workspaceRoot: string): AuthCommandResult {
       message: "FORGE_AUTH_JWKS_URI is required for jwt auth",
     });
   }
+  return errors;
+}
+
+function buildAuthPosture(workspaceRoot: string) {
+  const config = loadAuthConfigFromEnv(workspaceRoot);
+  const productionMode = config.mode === "jwt" || config.mode === "oidc";
+  const errors = configErrors(config);
+  const configReady = errors.length === 0;
+  return {
+    schemaVersion: "0.1.0",
+    mode: config.mode,
+    localOnly: config.mode === "dev-headers",
+    productionReady: productionMode && configReady,
+    requiresTenant: config.requiresTenant,
+    bearerHeader: productionMode ? "Authorization: Bearer <token>" : null,
+    tenantClaim: config.claims.tenantId ?? "tenant_id",
+    reason: productionMode
+      ? configReady
+        ? "jwt/oidc production auth configuration is present"
+        : "jwt/oidc production auth is selected but required settings are missing"
+      : "dev-headers auth is local-only and is not real production authentication",
+    nextActions: productionMode
+      ? configReady
+        ? ["forge auth prove --prod --token <jwt> --json", "forge serve --json"]
+        : ["forge auth check --json", "configure FORGE_AUTH_ISSUER, FORGE_AUTH_AUDIENCE, and FORGE_AUTH_JWKS_URI or OIDC issuer"]
+      : ["set FORGE_AUTH_MODE=jwt or oidc for production", "forge auth prove --prod --token <jwt> --json"],
+  };
+}
+
+function validateConfig(workspaceRoot: string): AuthCommandResult {
+  const config = loadAuthConfigFromEnv(workspaceRoot);
+  const errors = configErrors(config);
+  const workos = detectWorkOS(workspaceRoot, config.claims);
 
   return {
     ok: errors.length === 0,
@@ -94,6 +125,7 @@ function validateConfig(workspaceRoot: string): AuthCommandResult {
       algorithms: config.algorithms,
       claims: config.claims,
       requiresTenant: config.requiresTenant,
+      authPosture: buildAuthPosture(workspaceRoot),
       workos,
       errors,
     },
@@ -116,6 +148,7 @@ function publicConfig(workspaceRoot: string): AuthCommandResult {
       algorithms: config.algorithms,
       claims: config.claims,
       requiresTenant: config.requiresTenant,
+      authPosture: buildAuthPosture(workspaceRoot),
       workos,
     },
     exitCode: 0,
@@ -197,6 +230,15 @@ async function testToken(
 export async function runAuthCommand(
   options: AuthCommandOptions,
 ): Promise<AuthCommandResult> {
+  if (options.subcommand === "status") {
+    const posture = buildAuthPosture(options.workspaceRoot);
+    return {
+      ok: true,
+      mode: posture.mode,
+      data: posture,
+      exitCode: 0,
+    };
+  }
   if (options.subcommand === "check") {
     return validateConfig(options.workspaceRoot);
   }
@@ -206,15 +248,28 @@ export async function runAuthCommand(
     const workos = detectWorkOS(options.workspaceRoot, config.claims);
     const productionMode = config.mode === "jwt" || config.mode === "oidc";
     const workosClaimsOk = workos.claimStatus.every((claim) => claim.ok);
+    const posture = buildAuthPosture(options.workspaceRoot);
+    const tokenProof = options.token ? await testToken(options.workspaceRoot, options.token) : null;
+    const prodError = options.prod && !productionMode
+      ? { code: "FORGE_AUTH_MODE_INVALID", message: "forge auth prove --prod requires FORGE_AUTH_MODE=jwt or oidc" }
+      : options.prod && !options.token
+        ? { code: "FORGE_AUTH_MISSING_TOKEN", message: "forge auth prove --prod requires --token" }
+        : options.prod && tokenProof && !tokenProof.ok
+          ? tokenProof.error
+          : undefined;
+    const proofOk = checked.ok && (!options.prod || (productionMode && tokenProof?.ok === true));
     return {
-      ok: checked.ok,
+      ok: proofOk,
       mode: config.mode,
       data: {
         schemaVersion: "0.1.0",
         kind: "auth-proof",
-        ok: checked.ok,
+        ok: proofOk,
         mode: config.mode,
         productionReady: productionMode && checked.ok,
+        prod: options.prod === true,
+        authPosture: posture,
+        ...(tokenProof ? { tokenProof: tokenProof.ok ? tokenProof.data : tokenProof.error } : {}),
         invariants: [
           {
             id: "INV-001",
@@ -249,8 +304,8 @@ export async function runAuthCommand(
         workos,
         checkedAt: "deterministic",
       },
-      error: checked.error,
-      exitCode: checked.exitCode,
+      error: prodError ?? checked.error,
+      exitCode: proofOk ? 0 : 1,
     };
   }
   if (options.subcommand === "config") {

package/src/forge/cli/baseline.ts

@@ -0,0 +1,112 @@
+import { spawnSync } from "node:child_process";
+import { createWorkspaceBaseline, readWorkspaceBaseline, writeWorkspaceBaseline, WORKSPACE_BASELINE_PATH } from "../workspace/baseline.ts";
+import { listWorkspaceFiles } from "../workspace/git-summary.ts";
+
+export type BaselineSubcommand = "create" | "status";
+
+export interface BaselineCommandOptions {
+  subcommand: BaselineSubcommand;
+  workspaceRoot: string;
+  json: boolean;
+  reason?: string;
+}
+
+export interface BaselineCommandResult {
+  ok: boolean;
+  path: string;
+  required: boolean;
+  created?: boolean;
+  baseline?: ReturnType<typeof readWorkspaceBaseline>;
+  summary: {
+    files: number;
+    reason?: string;
+    tracking: "git" | "forge-baseline" | "missing";
+  };
+  nextActions: string[];
+  exitCode: 0 | 1;
+}
+
+function gitAvailable(workspaceRoot: string): boolean {
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: workspaceRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  return result.status === 0;
+}
+
+export function runBaselineCommand(options: BaselineCommandOptions): BaselineCommandResult {
+  if (options.subcommand === "create") {
+    const files = listWorkspaceFiles(options.workspaceRoot);
+    const baseline = createWorkspaceBaseline({
+      workspaceRoot: options.workspaceRoot,
+      files,
+      reason: options.reason,
+    });
+    writeWorkspaceBaseline(options.workspaceRoot, baseline);
+    return {
+      ok: true,
+      path: WORKSPACE_BASELINE_PATH,
+      required: false,
+      created: true,
+      baseline,
+      summary: {
+        files: Object.keys(baseline.files).length,
+        tracking: "forge-baseline",
+        ...(baseline.reason ? { reason: baseline.reason } : {}),
+      },
+      nextActions: ["forge changed --json", "forge handoff --json"],
+      exitCode: 0,
+    };
+  }
+
+  const baseline = readWorkspaceBaseline(options.workspaceRoot);
+  if (!baseline && gitAvailable(options.workspaceRoot)) {
+    return {
+      ok: true,
+      path: WORKSPACE_BASELINE_PATH,
+      required: false,
+      baseline: null,
+      summary: {
+        files: 0,
+        tracking: "git",
+      },
+      nextActions: ["forge changed --json", "git status --short"],
+      exitCode: 0,
+    };
+  }
+  return {
+    ok: baseline !== null,
+    path: WORKSPACE_BASELINE_PATH,
+    required: baseline === null,
+    baseline,
+    summary: {
+      files: baseline ? Object.keys(baseline.files).length : 0,
+      tracking: baseline ? "forge-baseline" : "missing",
+      ...(baseline?.reason ? { reason: baseline.reason } : {}),
+    },
+    nextActions: baseline
+      ? ["forge changed --json", "forge baseline create --reason refresh --json"]
+      : ["forge baseline create --reason initial-scaffold --json", "git init"],
+    exitCode: baseline ? 0 : 1,
+  };
+}
+
+export function formatBaselineJson(result: BaselineCommandResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function formatBaselineHuman(result: BaselineCommandResult): string {
+  const label = result.required ? "missing" : result.summary.tracking === "git" ? "not required (git workspace)" : "ready";
+  const lines = [
+    `Forge baseline: ${label}`,
+    `Path: ${result.path}`,
+    `Tracking: ${result.summary.tracking}`,
+    `Files: ${result.summary.files}`,
+  ];
+  if (result.summary.reason) {
+    lines.push(`Reason: ${result.summary.reason}`);
+  }
+  lines.push("", "Next:", ...result.nextActions.map((action) => `  ${action}`));
+  return `${lines.join("\n")}\n`;
+}

package/src/forge/cli/changed.ts

@@ -87,10 +87,12 @@ function selectDerivedChangeSummary(summary: CategorizedFileSummary): DerivedCha
 function buildRisks(git: WorkspaceGitSummary): string[] {
   const risks: string[] = [];
   const changed = git.changeSummary.changed;
-  if (!git.available) {
+  if (!git.available && git.source === "forge-baseline") {
+    risks.push("git status is unavailable; using Forge workspace baseline for non-git change tracking");
+  } else if (!git.available) {
     risks.push("git status is unavailable; using filesystem inventory as untracked-file analysis");
   }
-  if (git.untracked.count > 0) {
+  if (git.untracked.count > 0 && git.source !== "forge-baseline") {
     risks.push(`${git.untracked.count} untracked file(s) are not in git history`);
   }
   if (changed.byType.other.count > 0) {
@@ -107,8 +109,11 @@ function buildRisks(git: WorkspaceGitSummary): string[] {
 }
 
 function buildRecommendedCommands(git: WorkspaceGitSummary): string[] {
+  if (!git.available && git.source === "forge-baseline") {
+    return ["forge handoff --json", "forge test plan --changed --json", "forge verify --changed", "git init"];
+  }
   if (!git.available) {
-    return ["forge status --json", "forge handoff --json", "git init"];
+    return ["forge baseline create --reason initial-scaffold --json", "forge status --json", "forge handoff --json", "git init"];
   }
   if (git.changeSummary.changed.total.count === 0) {
     return ["forge status --json", "forge dev --once --json"];
@@ -206,7 +211,7 @@ export function runChangedCommand(workspaceRoot: string, options: { authoredOnly
   const reviewFocus = buildReviewFocus(viewHumanChanges, viewDerivedChanges);
   const generatedExplanation = buildGeneratedChangeExplanation(viewHumanChanges, viewDerivedChanges);
   const diffPlan: DiffPlan = buildDiffPlanFromChangeSummary(viewChanged);
-  const ok = git.available || git.source === "filesystem";
+  const ok = git.available || git.source === "filesystem" || git.source === "forge-baseline";
 
   return {
     ok,
@@ -216,6 +221,8 @@ export function runChangedCommand(workspaceRoot: string, options: { authoredOnly
       summary: {
         branch: git.branch,
         commit: git.commit,
+        workspaceMode: git.workspaceMode ?? (git.available ? "git" : "nonGit"),
+        tracking: git.tracking ?? git.source,
         view: options.authoredOnly ? "authored" : "all",
         changedFiles: viewChanged.total.count,
         humanFiles: viewHumanChanges.total,
@@ -229,6 +236,9 @@ export function runChangedCommand(workspaceRoot: string, options: { authoredOnly
       git: {
         available: git.available,
         source: git.source,
+        workspaceMode: git.workspaceMode,
+        tracking: git.tracking,
+        baseline: git.baseline,
         ...(git.error ? { error: git.error } : {}),
         branch: git.branch,
         commit: git.commit,

package/src/forge/cli/commands.ts

@@ -181,6 +181,9 @@ import {
 import {
   formatDoctorHuman,
   formatDoctorJson,
+  formatPgliteDoctorHuman,
+  formatPgliteDoctorJson,
+  runPgliteDoctorCommand,
   runDoctorCommand,
 } from "./doctor.ts";
 import {
@@ -202,6 +205,16 @@ import {
   formatWorkOSJson,
   runWorkOSCommand,
 } from "./workos.ts";
+import {
+  formatLastHuman,
+  formatLastJson,
+  runLastCommand,
+} from "./last-run.ts";
+import {
+  formatBaselineHuman,
+  formatBaselineJson,
+  runBaselineCommand,
+} from "./baseline.ts";
 import { formatRlsHuman, formatRlsJson, runRlsCommand } from "./rls.ts";
 import {
   formatSecurityHuman,
@@ -272,6 +285,7 @@ import { getActiveDbAdapter } from "../runtime/executor.ts";
 import { CLI_VERSION, FORGEOS_VERSION } from "../version.ts";
 import type { CategorizedFileSummary } from "../workspace/change-summary.ts";
 import { buildWorkspaceGitSummary } from "../workspace/git-summary.ts";
+import { startCommandHeartbeat } from "./progress.ts";
 
 function readGeneratedJson<T>(workspaceRoot: string, relative: string): T | null {
   const absolute = join(workspaceRoot, relative);
@@ -1558,6 +1572,16 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       }
       return 0;
     }
+    case "last": {
+      const result = runLastCommand({ workspaceRoot: command.workspaceRoot });
+      process.stdout.write(command.json ? formatLastJson(result) : formatLastHuman(result));
+      return result.exitCode;
+    }
+    case "baseline": {
+      const result = runBaselineCommand(command);
+      process.stdout.write(command.json ? formatBaselineJson(result) : formatBaselineHuman(result));
+      return result.exitCode;
+    }
     case "new": {
       const result = await runNewCommand({
         name: command.name,
@@ -1668,6 +1692,11 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
         process.stdout.write(command.json ? formatDeltaDoctorJson(result) : formatDeltaDoctorHuman(result));
         return result.exitCode;
       }
+      if (command.target === "pglite") {
+        const result = await runPgliteDoctorCommand({ workspaceRoot: command.workspaceRoot });
+        process.stdout.write(command.json ? formatPgliteDoctorJson(result) : formatPgliteDoctorHuman(result));
+        return result.exitCode;
+      }
       const result = await runDoctorCommand({ workspaceRoot: command.workspaceRoot });
       if (command.json) {
         process.stdout.write(formatDoctorJson(result));
@@ -1930,13 +1959,23 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       return result.exitCode;
     }
     case "agent": {
-      const result = await runAgentCommand(command.options);
-      if (command.options.json) {
-        process.stdout.write(formatAgentJson(result));
-      } else {
-        process.stdout.write(formatAgentHuman(result));
+      const heartbeat = command.options.subcommand === "onboard"
+        ? startCommandHeartbeat({
+            label: `agent onboard ${command.options.target ?? "codex"}`,
+            initialPhase: "prepare-hooks-memory-and-dev-snapshot",
+          })
+        : null;
+      try {
+        const result = await runAgentCommand(command.options);
+        if (command.options.json) {
+          process.stdout.write(formatAgentJson(result));
+        } else {
+          process.stdout.write(formatAgentHuman(result));
+        }
+        return result.exitCode;
+      } finally {
+        heartbeat?.stop();
       }
-      return result.exitCode;
     }
     case "mcp": {
       return runMcpServe(command.workspaceRoot);
@@ -2286,6 +2325,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
         workspaceRoot: command.workspaceRoot,
         db: command.db,
         databaseUrl: command.databaseUrl,
+        local: command.local,
         json: command.json,
       });
 

package/src/forge/cli/db.ts

@@ -7,6 +7,9 @@ import { buildAppGraph } from "../compiler/app-graph/build.ts";
 import { createDiagnostic } from "../compiler/diagnostics/create.ts";
 import {
   FORGE_RLS_APPLY_FAILED,
+  FORGE_DB_ADAPTER_UNAVAILABLE,
+  FORGE_PGLITE_STORE_ABORTED,
+  FORGE_PGLITE_STORE_ACTIVE,
   FORGE_RUNTIME_NOT_FOUND,
 } from "../compiler/diagnostics/codes.ts";
 import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
@@ -23,14 +26,19 @@ import {
   resetDatabase,
 } from "../runtime/db/migrate.ts";
 import type { DbAdapterKind } from "../runtime/db/adapter.ts";
+import {
+  DEFAULT_PGLITE_DIR,
+  repairLocalPgliteStore,
+} from "../runtime/db/pglite-adapter.ts";
 
-export type DbSubcommand = "diff" | "migrate" | "reset" | "status" | "doctor" | "rls-check";
+export type DbSubcommand = "diff" | "migrate" | "reset" | "status" | "doctor" | "repair" | "rls-check";
 
 export interface DbCommandOptions {
   subcommand: DbSubcommand;
   workspaceRoot: string;
   db: DbAdapterKind;
   databaseUrl?: string;
+  local?: boolean;
   json: boolean;
 }
 
@@ -285,7 +293,86 @@ async function runDbDoctor(
   }
 }
 
+async function runDbRepair(options: DbCommandOptions): Promise<DbCommandResult> {
+  if (!options.local) {
+    return {
+      ok: false,
+      data: {
+        schemaVersion: "0.1.0",
+        repaired: false,
+        adapter: options.db,
+        local: false,
+        nextActions: ["forge db repair --local --adapter pglite --json"],
+      },
+      diagnostics: [
+        createDiagnostic({
+          severity: "error",
+          code: "FORGE_CLI_USAGE",
+          message: "local database repair requires --local",
+          fixHint: "Pass --local to confirm you want Forge to repair the local development database store.",
+          suggestedCommands: ["forge db repair --local --adapter pglite --json"],
+        }),
+      ],
+      exitCode: 1,
+    };
+  }
+
+  if (options.db !== "pglite") {
+    return {
+      ok: false,
+      data: {
+        schemaVersion: "0.1.0",
+        repaired: false,
+        adapter: options.db,
+        nextActions: ["forge db repair --local --adapter pglite --json"],
+      },
+      diagnostics: [
+        createDiagnostic({
+          severity: "error",
+          code: FORGE_DB_ADAPTER_UNAVAILABLE,
+          message: "local repair currently supports only the pglite adapter",
+          fixHint: "Use --adapter pglite for the local Forge dev database store.",
+          suggestedCommands: ["forge db repair --local --adapter pglite --json"],
+        }),
+      ],
+      exitCode: 1,
+    };
+  }
+
+  const dataDir = join(options.workspaceRoot, DEFAULT_PGLITE_DIR);
+  const result = await repairLocalPgliteStore(dataDir);
+  const diagnostics = result.ok
+    ? []
+    : [
+        createDiagnostic({
+          severity: "error",
+          code: result.before.state === "active" ? FORGE_PGLITE_STORE_ACTIVE : FORGE_PGLITE_STORE_ABORTED,
+          message: result.message,
+          fixHint: result.before.state === "active"
+            ? "Stop the running forge dev process before repairing the PGlite store."
+            : "Archive the local PGlite store and retry forge dev, or use --db memory for non-persistent validation.",
+          suggestedCommands: result.nextActions,
+        }),
+      ];
+
+  return {
+    ok: result.ok,
+    data: {
+      schemaVersion: "0.1.0",
+      adapter: "pglite",
+      local: true,
+      ...result,
+    },
+    diagnostics,
+    exitCode: result.ok ? 0 : 1,
+  };
+}
+
 export async function runDbCommand(options: DbCommandOptions): Promise<DbCommandResult> {
+  if (options.subcommand === "repair") {
+    return runDbRepair(options);
+  }
+
   const { plan, diagnostics: planDiagnostics } = await loadSqlPlan(options.workspaceRoot);
 
   if (!plan) {
@@ -427,7 +514,7 @@ export function formatDbHuman(subcommand: DbSubcommand, result: DbCommandResult)
     return "database reset complete\n";
   }
 
-  if (subcommand === "status" || subcommand === "diff" || subcommand === "doctor") {
+  if (subcommand === "status" || subcommand === "diff" || subcommand === "doctor" || subcommand === "repair") {
     return `${JSON.stringify(result.data, null, 2)}\n`;
   }