@beignet/cli 0.0.47 → 0.0.48

package/skills/app-structure/SKILL.md

@@ -64,6 +64,7 @@ changing `infra/db/schema/`, run the app's db lifecycle commands:
 ```bash
 beignet db generate
 beignet db migrate
+beignet db status
 ```
 
 ## Explicit Registration
@@ -195,7 +196,7 @@ Generated apps register:
 }
 ```
 
-The MCP server exposes `app_map`, `explain`, `check`, `db`,
+The MCP server exposes `app_map`, `explain`, `check`, `db`, `db_status`,
 `db_schema_sync`, `task_run`, `schedule_run`, `outbox_inspect`, `outbox_run`,
 `routes`, `doctor`, `doctor_fix_plan`, `doctor_fix`, `lint`, `make`, and
 `provider_add`. It also publishes `beignet://app/guidance` and the
@@ -210,10 +211,11 @@ concept or diagnostic and returns the same deterministic result as
 `beignet explain <kind> <target> --json`. Explain accepts every app-map node
 kind plus `diagnostic`; targets may use stable IDs, runtime or declaration
 names, source selectors, and applicable aliases. `check` accepts optional
-`{ preflight?: boolean, timeoutMs?: number }`, bounds failure output, cancels
-the active script with the MCP request, and returns the same versioned result
-as `beignet check --json`. It does not apply Beignet fixes, but app package
-scripts retain their normal side effects. `db` accepts
+`{ preflight?: boolean, preflightConnect?: boolean, connectTimeoutMs?: number, timeoutMs?: number }`.
+Connected preflight adds migration status and dependency health checks. Check
+bounds failure output, cancels the active script with the MCP request, and
+returns the same versioned result as `beignet check --json`. It does not apply
+Beignet fixes, but app package scripts retain their normal side effects. `db` accepts
 `{ command: "generate" | "migrate" | "seed" | "reset", dryRun?, timeoutMs? }`
 and returns the matching versioned `beignet db <command> --json` report with
 bounded output, cancellation, and process-tree timeouts. `db_schema_sync`
@@ -221,7 +223,9 @@ accepts `{ dialect?, tables?, output?, dryRun? }` and returns the matching
 `beignet db schema sync --json` report. For lifecycle commands, `dryRun`
 validates and reports the app-owned script without executing it; it does not
 simulate SQL or data changes. `reset` remains environment-sensitive even
-though the generated entrypoint has a production guard. `task_run` and
+though the generated entrypoint has a production guard. `db_status` runs the
+app-owned read-only migration inspection: current exits 0, pending exits 2,
+and inspection failures use another non-zero exit. `task_run` and
 `schedule_run` execute registered app workflows. Use `outbox_inspect` for
 read-only `list` and `show`, and `outbox_run` for state-changing `drain`,
 `requeue`, `purge`, and `prune`; purge and prune support `dryRun`. Operational
@@ -255,7 +259,7 @@ When MCP is available, call `check` after edits to run the full validation loop
 through the app-local CLI without reconstructing these commands individually.
 For a generated persistent resource, the complete structured workflow is
 `app_map` → `explain` → `make` → `db_schema_sync` when provider tables changed
-→ `db` generate → `db` migrate → the relevant `task_run`, `schedule_run`, or
+→ `db` generate → `db` migrate → `db_status` → the relevant `task_run`, `schedule_run`, or
 outbox tool when operational work is required → `check`.
 
 For generated app template changes inside the Beignet monorepo, also run:

package/src/check.ts

@@ -39,8 +39,15 @@ export type CheckAppOptions = {
   cwd?: string;
   fix?: boolean;
   color?: boolean;
-  /** Append a `beignet preflight` step after the doctor step. */
+  /** Append a disconnected `beignet preflight` step after the doctor step. */
   preflight?: boolean;
+  /**
+   * Append a connected `beignet preflight --connect` step after doctor.
+   * Implies `preflight`.
+   */
+  preflightConnect?: boolean;
+  /** Per migration-status or dependency health check timeout in milliseconds. */
+  connectTimeoutMs?: number;
   /** Keep only the last N bytes from each package-script output stream. */
   maxOutputBytes?: number;
   /** Cancel the active package script with the owning request. */
@@ -81,9 +88,15 @@ export async function checkApp(
   const { step: doctorStep, fixes } = await runDoctorStep(targetDir, options);
   record(doctorStep);
 
-  if (options.preflight) {
+  if (options.preflight || options.preflightConnect) {
     options.signal?.throwIfAborted();
-    record(await preflightStep(targetDir));
+    record(
+      await preflightStep(targetDir, {
+        connect: Boolean(options.preflightConnect),
+        connectTimeoutMs: options.connectTimeoutMs,
+        signal: options.signal,
+      }),
+    );
   }
 
   const scripts = await readPackageScripts(targetDir);
@@ -274,17 +287,32 @@ async function readPackageScripts(
   return parsed.scripts ?? {};
 }
 
-async function preflightStep(targetDir: string): Promise<CheckStep> {
+async function preflightStep(
+  targetDir: string,
+  options: {
+    connect: boolean;
+    connectTimeoutMs?: number;
+    signal?: AbortSignal;
+  },
+): Promise<CheckStep> {
   const startedAt = Date.now();
   const { formatPreflight, runPreflight } = await import("./preflight.js");
-  const result = await runPreflight({ cwd: targetDir });
+  const result = await runPreflight({
+    cwd: targetDir,
+    connect: options.connect,
+    connectTimeoutMs: options.connectTimeoutMs,
+    signal: options.signal,
+  });
   const failed = result.findings.some(
     (finding) => finding.severity === "error",
   );
+  const command = options.connect
+    ? "beignet preflight --connect"
+    : "beignet preflight";
 
   return {
-    name: "beignet preflight",
-    command: "beignet preflight",
+    name: command,
+    command,
     status: failed ? "failed" : "passed",
     ...(failed ? { output: formatPreflight(result, targetDir) } : {}),
     durationMs: Date.now() - startedAt,

package/src/db.ts

@@ -18,6 +18,8 @@ export type {
 export const defaultDatabaseCommandMaxOutputBytes = 64 * 1024;
 /** Default timeout used by request-controlled database command callers. */
 export const defaultDatabaseCommandTimeoutMs = 10 * 60 * 1_000;
+/** Exit code reserved for an app-owned status script that found pending migrations. */
+export const databaseMigrationsPendingExitCode = 2;
 
 /**
  * Options for running a database lifecycle command.
@@ -53,6 +55,37 @@ export type RunDatabaseCommandResult = {
   exitCode: number;
 };
 
+/** Migration state reported by an app-owned database status script. */
+export type DatabaseMigrationStatus = "current" | "pending" | "failed";
+
+/** Options for inspecting app-owned database migration status. */
+export type RunDatabaseStatusOptions = {
+  cwd?: string;
+  captureOutput?: boolean;
+  /** Keep only the last N bytes from each output stream. */
+  maxOutputBytes?: number;
+  /** Cancel the app-owned status script when the owning request aborts. */
+  signal?: AbortSignal;
+  /** Stop the app-owned status script after this many milliseconds. */
+  timeoutMs?: number;
+};
+
+/** Versioned result returned by `beignet db status`. */
+export type RunDatabaseStatusResult = {
+  schemaVersion: 1;
+  command: "status";
+  status: DatabaseMigrationStatus;
+  cwd: string;
+  script: "db:status";
+  runner: string;
+  args: string[];
+  stdout?: string;
+  stderr?: string;
+  outputTruncated?: boolean;
+  timedOut?: boolean;
+  exitCode: number;
+};
+
 export type SpawnCommandOptions = {
   captureOutput: boolean;
   /** Keep only the last N bytes from each output stream. Unbounded when omitted. */
@@ -176,6 +209,70 @@ export async function runDatabaseCommand(
   };
 }
 
+/**
+ * Inspect migrations through the app-owned `db:status` script.
+ *
+ * Exit 0 means current, exit 2 means pending, and every other non-zero exit
+ * means the inspection failed. The app owns database-specific comparison
+ * logic while Beignet owns the stable report and automation contract.
+ */
+export async function runDatabaseStatus(
+  options: RunDatabaseStatusOptions = {},
+): Promise<RunDatabaseStatusResult> {
+  options.signal?.throwIfAborted();
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const script = "db:status" as const;
+  const packageJson = await readPackageJson(cwd);
+  const scriptCommand = packageJson.scripts?.[script];
+
+  if (!scriptCommand) {
+    throw new Error(
+      'Missing package.json script "db:status". Add an app-owned read-only migration status script so beignet db status can inspect the target database.',
+    );
+  }
+
+  if (
+    scriptCommand.includes("infra/db/migration-status.ts") &&
+    !(await exists(path.join(cwd, "infra/db/migration-status.ts")))
+  ) {
+    throw new Error(
+      'Missing database status entrypoint infra/db/migration-status.ts. beignet db status runs the "db:status" script, so restore the entrypoint or update package.json.',
+    );
+  }
+
+  options.signal?.throwIfAborted();
+  const runner = await detectPackageManager(cwd);
+  const args = ["run", script];
+  const commandResult = await spawnCommand(runner, args, cwd, {
+    captureOutput: Boolean(options.captureOutput),
+    maxOutputBytes: options.maxOutputBytes,
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+  });
+  const status: DatabaseMigrationStatus =
+    commandResult.exitCode === 0
+      ? "current"
+      : commandResult.exitCode === databaseMigrationsPendingExitCode
+        ? "pending"
+        : "failed";
+
+  return {
+    schemaVersion: 1,
+    command: "status",
+    status,
+    cwd,
+    script,
+    runner,
+    args,
+    exitCode: commandResult.exitCode,
+    ...(options.captureOutput
+      ? { stdout: commandResult.stdout, stderr: commandResult.stderr }
+      : {}),
+    ...(commandResult.outputTruncated ? { outputTruncated: true } : {}),
+    ...(commandResult.timedOut ? { timedOut: true } : {}),
+  };
+}
+
 /**
  * Sync the app-owned Drizzle schema entrypoint for Beignet provider tables.
  *

package/src/index.ts

@@ -134,6 +134,8 @@ type CheckFlags = {
   json?: boolean;
   fix?: boolean;
   preflight?: boolean;
+  preflightConnect?: boolean;
+  connectTimeoutMs?: number;
   cwd?: string;
 };
 
@@ -142,6 +144,7 @@ type PreflightFlags = {
   envFile?: string;
   envModule?: string;
   connect?: boolean;
+  connectTimeoutMs?: number;
   serverModule?: string;
   cwd?: string;
 };
@@ -152,6 +155,11 @@ type DbFlags = {
   cwd?: string;
 };
 
+type DbStatusFlags = {
+  json?: boolean;
+  cwd?: string;
+};
+
 type DbSchemaSyncFlags = DbFlags & {
   dialect?: DatabaseSchemaDialect;
   tables?: readonly DatabaseSchemaTable[];
@@ -349,6 +357,14 @@ const parsedDateFlag = (brief: string) =>
     brief,
   }) as const;
 
+const connectTimeoutMsFlag = {
+  kind: "parsed",
+  parse: parsePositiveInteger,
+  optional: true,
+  brief:
+    "Per migration-status or dependency health check timeout in milliseconds. Defaults to 5000.",
+} as const;
+
 const cwdFlag = parsedStringFlag(
   "App directory. Defaults to the current working directory.",
 );
@@ -411,6 +427,11 @@ const dbFlagParameters = {
   cwd: cwdFlag,
 } satisfies FlagParametersForType<DbFlags, CliContext>;
 
+const dbStatusFlagParameters = {
+  json: jsonFlag,
+  cwd: cwdFlag,
+} satisfies FlagParametersForType<DbStatusFlags, CliContext>;
+
 const dbSchemaSyncFlagParameters = {
   ...dbFlagParameters,
   dialect: {
@@ -1097,7 +1118,7 @@ const checkCommand = buildCommand<CheckFlags, [], CliContext>({
   docs: {
     brief: "Run the full app validation loop as one command.",
     fullDescription:
-      "Runs beignet lint, beignet doctor --strict, and the app's lint, typecheck, and test package scripts through the detected package manager. Every step runs even when an earlier one fails, so one run reports everything. Missing package scripts are skipped, not failed.",
+      "Runs beignet lint, beignet doctor --strict, optional disconnected or connected preflight, and the app's lint, typecheck, and test package scripts through the detected package manager. Every step runs even when an earlier one fails, so one run reports everything. Missing package scripts are skipped, not failed.",
   },
   parameters: {
     flags: {
@@ -1112,8 +1133,17 @@ const checkCommand = buildCommand<CheckFlags, [], CliContext>({
         kind: "boolean",
         optional: true,
         withNegated: false,
-        brief: "Append a beignet preflight step after doctor.",
+        brief:
+          "Append a disconnected beignet preflight environment step after doctor.",
+      },
+      preflightConnect: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief:
+          "Append beignet preflight --connect after doctor. Implies --preflight.",
       },
+      connectTimeoutMs: connectTimeoutMsFlag,
       cwd: cwdFlag,
     } satisfies FlagParametersForType<CheckFlags, CliContext>,
   },
@@ -1128,6 +1158,8 @@ const checkCommand = buildCommand<CheckFlags, [], CliContext>({
         cwd: flags.cwd,
         fix: flags.fix,
         preflight: flags.preflight,
+        preflightConnect: flags.preflightConnect,
+        connectTimeoutMs: flags.connectTimeoutMs,
         color,
         ...(flags.json
           ? {}
@@ -1153,7 +1185,7 @@ const preflightCommand = buildCommand<PreflightFlags, [], CliContext>({
   docs: {
     brief: "Validate the deploy environment before shipping.",
     fullDescription:
-      "Runtime production gate, unlike the static doctor checks: reads the actual environment the process runs with, verifies every env var installed provider manifests mark as required, flags values still matching .env.example or common placeholders on secret-like keys, and validates the app env schema by importing lib/env.ts. Run it in the deploy pipeline where production configuration is present. Exits 1 on any error finding.",
+      "Runtime production gate, unlike the static doctor checks: reads the actual environment the process runs with, verifies every env var installed provider manifests mark as required, flags values still matching .env.example or common placeholders on secret-like keys, and validates the app env schema by importing lib/env.ts. With --connect, it checks migration status before booting the server and running port health checks. Run it in the deploy pipeline where production configuration is present. Exits 1 on any error finding.",
   },
   parameters: {
     flags: {
@@ -1169,8 +1201,9 @@ const preflightCommand = buildCommand<PreflightFlags, [], CliContext>({
         optional: true,
         withNegated: false,
         brief:
-          "Boot the app server and run every port's checkHealth(). Needs network and real credentials.",
+          "Check migration status, then boot the app server and run every port's checkHealth(). Needs network and real credentials.",
       },
+      connectTimeoutMs: connectTimeoutMsFlag,
       serverModule: parsedStringFlag(
         "Module exporting getServer, used by --connect. Defaults to server/index.ts.",
       ),
@@ -1191,6 +1224,7 @@ const preflightCommand = buildCommand<PreflightFlags, [], CliContext>({
         envFile: flags.envFile,
         envModule: flags.envModule,
         connect: flags.connect,
+        connectTimeoutMs: flags.connectTimeoutMs,
         serverModule: flags.serverModule,
       });
 
@@ -1374,6 +1408,42 @@ function databaseCommand(command: DatabaseCommand) {
   });
 }
 
+const databaseStatusCommand = buildCommand<DbStatusFlags, [], CliContext>({
+  docs: {
+    brief: "Inspect whether app-owned database migrations are current.",
+    fullDescription:
+      "Runs the app's read-only db:status script. Exit 0 means current, exit 2 means pending migrations, and any other non-zero exit means inspection failed.",
+  },
+  parameters: {
+    flags: dbStatusFlagParameters,
+  },
+  loader: async () => {
+    const { defaultDatabaseCommandMaxOutputBytes, runDatabaseStatus } =
+      await import("./db.js");
+
+    return async function runDbStatus(this: CliContext, flags: DbStatusFlags) {
+      const captureOutput = Boolean(flags.json);
+      const result = await runDatabaseStatus({
+        cwd: flags.cwd,
+        captureOutput,
+        maxOutputBytes: captureOutput
+          ? defaultDatabaseCommandMaxOutputBytes
+          : undefined,
+      });
+
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : databaseStatusNextSteps(result),
+      );
+      if (result.exitCode !== 0) {
+        this.process.exitCode = result.exitCode;
+      }
+    };
+  },
+});
+
 const dbSchemaSyncCommand = buildCommand<DbSchemaSyncFlags, [], CliContext>({
   docs: {
     brief: "Sync app-owned re-exports of Beignet provider tables.",
@@ -1427,7 +1497,8 @@ const dbRoutes = buildRouteMap({
     reset: databaseCommand("reset"),
     schema: dbSchemaRoutes,
     seed: databaseCommand("seed"),
-  } satisfies Record<DatabaseCommand | "schema", unknown>,
+    status: databaseStatusCommand,
+  } satisfies Record<DatabaseCommand | "schema" | "status", unknown>,
 });
 
 const taskRunCommand = buildCommand<TaskRunFlags, [string], CliContext>({
@@ -2398,6 +2469,14 @@ type DatabaseCommandNextStepsResult = {
   dryRun: boolean;
 };
 
+type DatabaseStatusNextStepsResult = {
+  status: "current" | "pending" | "failed";
+  cwd: string;
+  script: string;
+  runner: string;
+  args: string[];
+};
+
 type DatabaseSchemaSyncNextStepsResult = {
   cwd: string;
   dialect: DatabaseSchemaDialect;
@@ -2632,6 +2711,7 @@ Next steps:
 ${envStep}
 ${startDatabaseStep}Prepare the database:
   ${cli} db migrate
+  ${cli} db status
 
 Start the app:
   ${run} dev
@@ -2646,6 +2726,7 @@ Generate a feature:
   ${cli} make feature projects
   ${cli} db generate
   ${cli} db migrate
+  ${cli} db status
   ${cli} check`;
 }
 
@@ -2722,7 +2803,7 @@ function makeResourceNextSteps(result: MakeNextStepsResult): string {
   return makeNextSteps(result, "resource", [
     "Use make resource when the feature maps cleanly to a REST resource with repository-backed persistence.",
     "Review the generated schemas and repository fields.",
-    "If this app uses Drizzle, run beignet db generate and beignet db migrate so the new schema is ready.",
+    "If this app uses Drizzle, run beignet db generate, beignet db migrate, and beignet db status so the new schema is ready and verified.",
     "Run your app's lint, test, and typecheck commands, then beignet lint and beignet doctor.",
   ]);
 }
@@ -2739,6 +2820,25 @@ Command:
   ${command}`;
 }
 
+function databaseStatusNextSteps(
+  result: DatabaseStatusNextStepsResult,
+): string {
+  const command = [result.runner, ...result.args].join(" ");
+  const summary =
+    result.status === "current"
+      ? "Database migrations are current."
+      : result.status === "pending"
+        ? "Database migrations are pending."
+        : "Database migration status could not be determined.";
+
+  return `${summary}
+
+Ran ${result.script} in ${result.cwd}
+
+Command:
+  ${command}`;
+}
+
 function databaseSchemaSyncNextSteps(
   result: DatabaseSchemaSyncNextStepsResult,
 ): string {
@@ -2759,6 +2859,7 @@ ${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
 Next steps:
   Run beignet db generate to produce app-owned Drizzle migrations.
   Run beignet db migrate to apply the migration.
+  Run beignet db status to verify the target database.
   Run beignet doctor --strict to check provider setup.`;
 }
 
@@ -2766,7 +2867,7 @@ function makeFeatureNextSteps(result: MakeNextStepsResult): string {
   return makeNextSteps(result, "feature slice", [
     "Use make feature for product capabilities and workflows. Use make resource when the concept is mostly CRUD-shaped.",
     "Treat the generated name field as a placeholder and shape the contracts, use cases, and repository around the feature's real workflow.",
-    "If this app uses Drizzle, run beignet db generate and beignet db migrate so the new schema is ready.",
+    "If this app uses Drizzle, run beignet db generate, beignet db migrate, and beignet db status so the new schema is ready and verified.",
     "Run your app's lint, test, and typecheck commands, then beignet lint and beignet doctor.",
   ]);
 }

package/src/inspect.ts

@@ -43,6 +43,7 @@ import {
 import {
   detectedProviderVariants,
   diagnosticPackageJsonFile,
+  formatProviderEnvAlternatives,
   formatProviderMetadataIssues,
   installedPackageNames,
   providerDoctorRulesForInstalledPackages,
@@ -2619,6 +2620,27 @@ async function inspectProductionReadiness(
         provider.variants,
         providerEntries,
       )) {
+        const envAlternatives = configuredProviderRequiredEnvAlternatives(
+          variant.requiredEnvAlternatives,
+          config,
+        );
+        if (
+          envAlternatives.length > 0 &&
+          !(await providerRequiredEnvAlternativeExists(
+            targetDir,
+            configFiles,
+            envAlternatives,
+            sourceCache,
+          ))
+        ) {
+          diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_PROVIDER_ENV_MISSING",
+            file: "package.json",
+            message: `${provider.packageName} is installed and ${variant.displayName} is registered, but none of its required environment configurations are fully mentioned in app env/config files. Configure ${formatProviderEnvAlternatives(envAlternatives)}, or remove the provider registration.`,
+          });
+        }
+
         for (const envVar of configuredProviderRequiredEnv(
           variant.requiredEnv,
           config,
@@ -2669,6 +2691,27 @@ async function inspectProductionReadiness(
       continue;
     }
 
+    const envAlternatives = configuredProviderRequiredEnvAlternatives(
+      provider.requiredEnvAlternatives ?? [],
+      config,
+    );
+    if (
+      envAlternatives.length > 0 &&
+      !(await providerRequiredEnvAlternativeExists(
+        targetDir,
+        configFiles,
+        envAlternatives,
+        sourceCache,
+      ))
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_PROVIDER_ENV_MISSING",
+        file: "package.json",
+        message: `${provider.packageName} is installed, but none of its required environment configurations are fully mentioned in app env/config files. Configure ${formatProviderEnvAlternatives(envAlternatives)}, or remove the unused provider package.`,
+      });
+    }
+
     for (const envVar of configuredProviderRequiredEnv(
       provider.requiredEnv ?? [],
       config,
@@ -5175,7 +5218,7 @@ async function inspectDatabaseLifecycleDrift(
   }
 
   if (hasDrizzleArtifacts) {
-    for (const script of ["db:generate", "db:migrate"] as const) {
+    for (const script of ["db:generate", "db:migrate", "db:status"] as const) {
       if (packageScripts[script]) continue;
       diagnostics.push({
         severity: "warning",
@@ -5257,6 +5300,12 @@ async function inspectDatabaseLifecycleDrift(
       file: `${infrastructurePath}/db/reset.ts`,
       code: "BEIGNET_DB_RESET_ENTRYPOINT_MISSING",
     },
+    {
+      script: "db:status",
+      command: "status",
+      file: `${infrastructurePath}/db/migration-status.ts`,
+      code: "BEIGNET_DB_STATUS_ENTRYPOINT_MISSING",
+    },
   ] as const;
 
   for (const entrypoint of standardEntrypoints) {
@@ -6284,6 +6333,32 @@ function configuredProviderRequiredEnv(
   return envVars.filter((envVar) => !ignored.has(envVar));
 }
 
+function configuredProviderRequiredEnvAlternatives(
+  alternatives: readonly (readonly string[])[],
+  config: ResolvedBeignetConfig,
+): string[][] {
+  return alternatives.map((alternative) =>
+    configuredProviderRequiredEnv(alternative, config),
+  );
+}
+
+async function providerRequiredEnvAlternativeExists(
+  targetDir: string,
+  configFiles: readonly string[],
+  alternatives: readonly (readonly string[])[],
+  sourceCache: Map<string, string>,
+): Promise<boolean> {
+  for (const alternative of alternatives) {
+    const exists = await Promise.all(
+      alternative.map((envVar) =>
+        providerRequiredEnvExists(targetDir, configFiles, envVar, sourceCache),
+      ),
+    );
+    if (exists.every(Boolean)) return true;
+  }
+  return false;
+}
+
 function configuredProviderRequiredTable(
   tableName: string,
   config: ResolvedBeignetConfig,

package/src/lib.ts

@@ -29,14 +29,22 @@ export type { CreateOptions } from "./create.js";
 export { createProject } from "./create.js";
 export type {
   DatabaseCommand,
+  DatabaseMigrationStatus,
   DatabaseSchemaDialect,
   DatabaseSchemaTable,
   RunDatabaseCommandOptions,
   RunDatabaseCommandResult,
+  RunDatabaseStatusOptions,
+  RunDatabaseStatusResult,
   SyncDatabaseSchemaOptions,
   SyncDatabaseSchemaResult,
 } from "./db.js";
-export { runDatabaseCommand, syncDatabaseSchema } from "./db.js";
+export {
+  databaseMigrationsPendingExitCode,
+  runDatabaseCommand,
+  runDatabaseStatus,
+  syncDatabaseSchema,
+} from "./db.js";
 export type {
   DoctorFixApplyResult,
   DoctorFixFileChange,

package/src/make/inbox.ts

@@ -226,7 +226,7 @@ export async function makeInbox(
  */
 export function makeInboxNextStepLines(): string[] {
   return [
-    "Run beignet db generate and beignet db migrate so inbox_notifications exists.",
+    "Run beignet db generate, beignet db migrate, and beignet db status so inbox_notifications exists and is verified.",
     'Add an in-app channel to any feature notification: import { defineInboxNotificationChannel } from "@/features/inbox/channel" and add inApp: defineInboxNotificationChannel(({ payload }) => ({ userId: payload.userId, type: "your-type", title: "Something happened" })) to its channels.',
     "Render the unread badge from features/inbox/components/unread-badge.tsx next to your Inbox nav link for a live unread count.",
     "Run your app's test, lint, and typecheck commands, then beignet lint and beignet doctor.",

package/src/make/payments.ts

@@ -209,7 +209,7 @@ export function makePaymentsNextStepLines(
   return [
     "The free plan works out of the box; billing accounts without an active subscription resolve to it automatically.",
     "Set BILLING_PRO_PRICE_ID in .env.local to the provider price ID for your pro plan.",
-    "Run beignet db generate and beignet db migrate so billing_accounts exists before handling webhooks.",
+    "Run beignet db generate, beignet db migrate, and beignet db status so billing_accounts exists and is verified before handling webhooks.",
     'Gate paid actions once usage passes FREE_PLAN_LIMITS: await requireEntitlement(ctx, { entitlement: "todos.create", subject: { type: "tenant", id: tenantId } });',
     ...(hasPlanUi
       ? [

package/src/make/tenancy.ts

@@ -249,7 +249,7 @@ export async function makeTenancy(
  */
 export function makeTenancyNextStepLines(): string[] {
   return [
-    "Run beignet db generate and beignet db migrate so the workspaces, workspace_members, and workspace_invites tables exist.",
+    "Run beignet db generate, beignet db migrate, and beignet db status so the workspaces, workspace_members, and workspace_invites tables exist and are verified.",
     "Requests resolve the active workspace from memberships and the beignet-workspace cookie; users without a workspace have no tenant, so point them at Settings > Workspace to create one.",
     "Run the db:seed script for a demo workspace with a sign-in-able demo admin (demo-admin@example.com).",
     "Invite emails send through the in-memory mailer in development; swap server/providers.ts to a real mail provider such as @beignet/provider-mail-resend for delivery.",