@beignet/cli 0.0.46 → 0.0.48

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.",
@@ -3857,7 +3857,7 @@ export type AppServiceContextInput =
  */
 export const appContext = defineServerContext<AppContext, AppRuntimePorts>()({
 \tgate: (ports) => ports.gate,
-\trequest: async ({ req, ports, requestId, trace }) => {
+\trequest: async ({ req, requestInfo, ports, requestId, trace }) => {
 \t\tconst auth = await ports.auth.getSession(req);
 \t\tconst { tenant, membership } = await resolveRequestWorkspace({
 \t\t\tauth,
@@ -3876,6 +3876,7 @@ export const appContext = defineServerContext<AppContext, AppRuntimePorts>()({
 \t\t\t\t\t})
 \t\t\t\t: createAnonymousActor(),
 \t\t\tauth,
+\t\t\trequestInfo,
 \t\t\t...trace,
 \t\t\tports,
 \t\t\t...(tenant ? { tenant } : {}),

package/src/mcp.ts

@@ -23,6 +23,7 @@ import {
   defaultDatabaseCommandMaxOutputBytes,
   defaultDatabaseCommandTimeoutMs,
   runDatabaseCommand,
+  runDatabaseStatus,
   syncDatabaseSchema,
 } from "./db.js";
 import { explainApp, explainTargetKinds } from "./explain.js";
@@ -639,7 +640,7 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
     "check",
     {
       description:
-        "Run the full Beignet app validation loop: Beignet lint, strict doctor, and the app's lint, typecheck, and test scripts. Returns the same versioned JSON as beignet check --json, including every step, bounded failure output, durations, and overall ok status. Does not apply Beignet fixes, but app-owned scripts run with their normal side effects.",
+        "Run the full Beignet app validation loop: Beignet lint, strict doctor, optional disconnected or connected preflight, and the app's lint, typecheck, and test scripts. Returns the same versioned JSON as beignet check --json, including every step, bounded failure output, durations, and overall ok status. Does not apply Beignet fixes, but app-owned scripts run with their normal side effects.",
       inputSchema: {
         preflight: z
           .boolean()
@@ -647,6 +648,21 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
           .describe(
             "Include the environment preflight check before app package scripts. Defaults to false.",
           ),
+        preflightConnect: z
+          .boolean()
+          .optional()
+          .describe(
+            "Include connected preflight with migration status and dependency health checks. Implies preflight and defaults to false.",
+          ),
+        connectTimeoutMs: z
+          .number()
+          .int()
+          .min(1)
+          .max(60 * 60 * 1_000)
+          .optional()
+          .describe(
+            "Maximum duration for migration status and each dependency health check in milliseconds. Defaults to 5000.",
+          ),
         timeoutMs: z
           .number()
           .int()
@@ -670,6 +686,8 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
           await checkApp({
             cwd,
             preflight: input.preflight ?? false,
+            preflightConnect: input.preflightConnect ?? false,
+            connectTimeoutMs: input.connectTimeoutMs,
             scriptTimeoutMs: input.timeoutMs ?? defaultMcpCheckTimeoutMs,
             signal: extra.signal,
           }),
@@ -725,6 +743,43 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
       ),
   );
 
+  server.registerTool(
+    "db_status",
+    {
+      description:
+        "Inspect app-owned database migrations and return exactly the versioned beignet db status --json result. Exit state distinguishes current, pending, and failed inspection without mutating the database. Output is bounded, the complete child process tree is cancelled with the MCP request, and execution stops after the configured timeout.",
+      inputSchema: {
+        timeoutMs: z
+          .number()
+          .int()
+          .min(1_000)
+          .max(60 * 60 * 1_000)
+          .optional()
+          .describe(
+            "Maximum status duration in milliseconds. Defaults to 600000 (10 minutes).",
+          ),
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (input, extra) =>
+      safeToolResult(async () =>
+        jsonResult(
+          await runDatabaseStatus({
+            cwd,
+            captureOutput: true,
+            maxOutputBytes: defaultDatabaseCommandMaxOutputBytes,
+            signal: extra.signal,
+            timeoutMs: input.timeoutMs ?? defaultDatabaseCommandTimeoutMs,
+          }),
+        ),
+      ),
+  );
+
   server.registerTool(
     "db_schema_sync",
     {