@beignet/cli 0.0.47 → 0.0.48

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",
     {

package/src/preflight.ts

@@ -2,12 +2,15 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { parseProviderPackageMetadata } from "@beignet/core/providers";
 import { createJiti } from "jiti";
+import { runDatabaseStatus } from "./db.js";
 import {
   type InspectDiagnostic,
   inspectApp,
   productionHardeningDiagnosticCodes,
 } from "./inspect.js";
 import {
+  detectedProviderVariantsForRules,
+  formatProviderEnvAlternatives,
   installedPackageNames,
   type ProviderPackageJson,
   providerDoctorRulesForInstalledPackages,
@@ -46,8 +49,9 @@ export interface PreflightOptions {
    */
   doctor?: boolean;
   /**
-   * Boot the app server and run every port's `checkHealth()`. Needs network
-   * access and real credentials, so it is opt-in.
+   * Inspect database migration status, then boot the app server and run every
+   * port's `checkHealth()`. Needs network access and real credentials, so it
+   * is opt-in.
    */
   connect?: boolean;
   /**
@@ -56,9 +60,12 @@ export interface PreflightOptions {
    */
   serverModule?: string;
   /**
-   * Per-dependency health check timeout in milliseconds. Defaults to 5000.
+   * Per migration-status or dependency health check timeout in milliseconds.
+   * Defaults to 5000.
    */
   connectTimeoutMs?: number;
+  /** Cancel connected migration inspection and health checks on abort. */
+  signal?: AbortSignal;
 }
 
 export interface PreflightResult {
@@ -79,6 +86,15 @@ export interface PreflightResult {
    * Ports whose `checkHealth()` ran during a `connect` pass.
    */
   checkedDependencies: string[];
+  /**
+   * Database migration state observed before dependency checks.
+   */
+  migrationStatus:
+    | "not-checked"
+    | "current"
+    | "pending"
+    | "failed"
+    | "unavailable";
 }
 
 /**
@@ -175,6 +191,46 @@ function applyEnvToProcess(
   };
 }
 
+function appendProviderEnvFindings(options: {
+  owner: string;
+  required: readonly string[];
+  alternatives: readonly (readonly string[])[];
+  env: Readonly<Record<string, string | undefined>>;
+  requiredEnvKeys: Set<string>;
+  findings: PreflightFinding[];
+}): void {
+  for (const key of options.required) {
+    options.requiredEnvKeys.add(key);
+    const value = options.env[key];
+    if (value === undefined || value.trim() === "") {
+      options.findings.push({
+        severity: "error",
+        code: "BEIGNET_PREFLIGHT_ENV_MISSING",
+        message: `${key} is required by ${options.owner} but is not set.`,
+      });
+    }
+  }
+
+  for (const key of options.alternatives.flat()) {
+    options.requiredEnvKeys.add(key);
+  }
+  if (
+    options.alternatives.length > 0 &&
+    !options.alternatives.some((alternative) =>
+      alternative.every((key) => {
+        const value = options.env[key];
+        return value !== undefined && value.trim() !== "";
+      }),
+    )
+  ) {
+    options.findings.push({
+      severity: "error",
+      code: "BEIGNET_PREFLIGHT_ENV_MISSING",
+      message: `${options.owner} requires one complete environment configuration: ${formatProviderEnvAlternatives(options.alternatives)}.`,
+    });
+  }
+}
+
 /**
  * Validate the deploy environment against installed provider manifests, the
  * app's `.env.example` placeholders, and the app env schema module.
@@ -221,6 +277,7 @@ export async function runPreflight(
       envModuleChecked: false,
       doctorChecked: false,
       checkedDependencies: [],
+      migrationStatus: "not-checked",
     };
   }
 
@@ -230,19 +287,34 @@ export async function runPreflight(
   );
   const checkedProviders = rules.map((rule) => rule.packageName);
   const requiredEnvKeys = new Set<string>();
+  const detectedVariants = await detectedProviderVariantsForRules(
+    options.cwd,
+    rules,
+  );
 
   for (const rule of rules) {
-    for (const key of rule.requiredEnv ?? []) {
-      requiredEnvKeys.add(key);
-      const value = env[key];
-      if (value === undefined || value.trim() === "") {
-        findings.push({
-          severity: "error",
-          code: "BEIGNET_PREFLIGHT_ENV_MISSING",
-          message: `${key} is required by ${rule.packageName} but is not set.`,
+    if (rule.variants !== undefined) {
+      for (const variant of detectedVariants.get(rule.packageName) ?? []) {
+        appendProviderEnvFindings({
+          owner: `${rule.packageName} (${variant.displayName})`,
+          required: variant.requiredEnv,
+          alternatives: variant.requiredEnvAlternatives,
+          env,
+          requiredEnvKeys,
+          findings,
         });
       }
+      continue;
     }
+
+    appendProviderEnvFindings({
+      owner: rule.packageName,
+      required: rule.requiredEnv ?? [],
+      alternatives: rule.requiredEnvAlternatives ?? [],
+      env,
+      requiredEnvKeys,
+      findings,
+    });
   }
 
   const inngestDev = env.INNGEST_DEV?.trim().toLowerCase();
@@ -303,6 +375,7 @@ export async function runPreflight(
   let envModuleChecked = false;
   let doctorChecked = false;
   const checkedDependencies: string[] = [];
+  let migrationStatus: PreflightResult["migrationStatus"] = "not-checked";
   const restoreProcessEnv = applyEnvToProcess(env);
 
   try {
@@ -344,7 +417,67 @@ export async function runPreflight(
     }
 
     if (options.connect) {
-      await runDependencyChecks(options, findings, checkedDependencies);
+      if (!packageJson.scripts?.["db:status"]) {
+        migrationStatus = "unavailable";
+        findings.push({
+          severity: "note",
+          code: "BEIGNET_PREFLIGHT_DATABASE_STATUS_UNAVAILABLE",
+          message:
+            'No app-owned "db:status" script is configured; skipping pending migration detection.',
+        });
+      } else {
+        try {
+          const connectTimeoutMs = options.connectTimeoutMs ?? 5000;
+          const result = await runDatabaseStatus({
+            cwd: options.cwd,
+            captureOutput: true,
+            maxOutputBytes: 8 * 1024,
+            signal: options.signal,
+            timeoutMs: connectTimeoutMs,
+          });
+          migrationStatus = result.status;
+
+          if (result.status === "pending") {
+            findings.push({
+              severity: "error",
+              code: "BEIGNET_PREFLIGHT_DATABASE_MIGRATIONS_PENDING",
+              message: databaseStatusFindingMessage(
+                "Database migrations are pending. Run `beignet db migrate` in the serialized migration job before booting the app.",
+                result.stdout,
+                result.stderr,
+                result.outputTruncated,
+              ),
+            });
+          } else if (result.status === "failed") {
+            findings.push({
+              severity: "error",
+              code: "BEIGNET_PREFLIGHT_DATABASE_STATUS_FAILED",
+              message: databaseStatusFindingMessage(
+                result.timedOut
+                  ? `Database migration status inspection timed out after ${connectTimeoutMs}ms.`
+                  : "Database migration status inspection failed.",
+                result.stdout,
+                result.stderr,
+                result.outputTruncated,
+              ),
+            });
+          }
+        } catch (error) {
+          options.signal?.throwIfAborted();
+          migrationStatus = "failed";
+          findings.push({
+            severity: "error",
+            code: "BEIGNET_PREFLIGHT_DATABASE_STATUS_FAILED",
+            message: `Database migration status inspection failed: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          });
+        }
+      }
+
+      if (migrationStatus !== "pending" && migrationStatus !== "failed") {
+        await runDependencyChecks(options, findings, checkedDependencies);
+      }
     }
   } finally {
     restoreProcessEnv();
@@ -356,9 +489,26 @@ export async function runPreflight(
     envModuleChecked,
     doctorChecked,
     checkedDependencies,
+    migrationStatus,
   };
 }
 
+function databaseStatusFindingMessage(
+  summary: string,
+  stdout?: string,
+  stderr?: string,
+  outputTruncated?: boolean,
+): string {
+  const details = [
+    stdout?.trim() ? `stdout:\n${stdout.trim()}` : undefined,
+    stderr?.trim() ? `stderr:\n${stderr.trim()}` : undefined,
+  ].filter((value): value is string => value !== undefined);
+  if (outputTruncated) {
+    details.push("Output truncated; showing the retained tail.");
+  }
+  return [summary, ...details].join("\n");
+}
+
 interface HealthCheckable {
   checkHealth(): Promise<unknown>;
 }
@@ -381,10 +531,13 @@ async function withTimeout<T>(
   work: Promise<T>,
   ms: number,
   label: string,
+  signal?: AbortSignal,
 ): Promise<T> {
+  signal?.throwIfAborted();
   let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
   try {
-    return await Promise.race([
+    const contenders: Promise<T>[] = [
       work,
       new Promise<never>((_, reject) => {
         timer = setTimeout(
@@ -392,9 +545,25 @@ async function withTimeout<T>(
           ms,
         );
       }),
-    ]);
+    ];
+    if (signal) {
+      contenders.push(
+        new Promise<never>((_, reject) => {
+          onAbort = () =>
+            reject(
+              signal.reason instanceof Error
+                ? signal.reason
+                : new Error("Connected preflight cancelled."),
+            );
+          signal.addEventListener("abort", onAbort, { once: true });
+          if (signal.aborted) onAbort();
+        }),
+      );
+    }
+    return await Promise.race(contenders);
   } finally {
     if (timer !== undefined) clearTimeout(timer);
+    if (onAbort) signal?.removeEventListener("abort", onAbort);
   }
 }
 
@@ -407,6 +576,7 @@ async function runDependencyChecks(
   findings: PreflightFinding[],
   checkedDependencies: string[],
 ): Promise<void> {
+  options.signal?.throwIfAborted();
   const serverModule = options.serverModule ?? "server/index.ts";
   const serverModulePath = path.resolve(options.cwd, serverModule);
   const timeoutMs = options.connectTimeoutMs ?? 5000;
@@ -424,6 +594,7 @@ async function runDependencyChecks(
     | { ports: Record<string, unknown>; stop?: () => Promise<void> }
     | undefined;
   try {
+    options.signal?.throwIfAborted();
     const jiti = createJiti(serverModulePath, {
       interopDefault: true,
       moduleCache: false,
@@ -452,6 +623,7 @@ async function runDependencyChecks(
       stop?: () => Promise<void>;
     };
   } catch (error) {
+    options.signal?.throwIfAborted();
     findings.push({
       severity: "error",
       code: "BEIGNET_PREFLIGHT_SERVER_BOOT_FAILED",
@@ -464,6 +636,7 @@ async function runDependencyChecks(
 
   try {
     for (const [name, port] of Object.entries(server.ports)) {
+      options.signal?.throwIfAborted();
       if (!isHealthCheckable(port)) continue;
       checkedDependencies.push(name);
       try {
@@ -471,6 +644,7 @@ async function runDependencyChecks(
           port.checkHealth(),
           timeoutMs,
           `${name}.checkHealth()`,
+          options.signal,
         );
         if (!healthResultOk(result)) {
           const message = (result as { message?: unknown }).message;
@@ -483,6 +657,7 @@ async function runDependencyChecks(
           });
         }
       } catch (error) {
+        options.signal?.throwIfAborted();
         findings.push({
           severity: "error",
           code: "BEIGNET_PREFLIGHT_DEPENDENCY_UNHEALTHY",
@@ -534,14 +709,18 @@ export function formatPreflight(result: PreflightResult, cwd: string): string {
   const dependencySummary = result.checkedDependencies.length
     ? `, ${result.checkedDependencies.length} dependency health check(s) run`
     : "";
+  const migrationSummary =
+    result.migrationStatus === "not-checked"
+      ? "migration status not checked"
+      : `migration status ${result.migrationStatus}`;
 
   if (errors.length === 0) {
     lines.push(
-      `Preflight passed in ${cwd}: ${providerSummary} checked, ${envSummary}, ${doctorSummary}${dependencySummary}.`,
+      `Preflight passed in ${cwd}: ${providerSummary} checked, ${envSummary}, ${doctorSummary}, ${migrationSummary}${dependencySummary}.`,
     );
   } else {
     lines.push(
-      `Preflight failed in ${cwd}: ${errors.length} error(s) across ${providerSummary}, ${envSummary}, ${doctorSummary}${dependencySummary}.`,
+      `Preflight failed in ${cwd}: ${errors.length} error(s) across ${providerSummary}, ${envSummary}, ${doctorSummary}, ${migrationSummary}${dependencySummary}.`,
     );
   }
 

package/src/provider-add.ts

@@ -639,6 +639,8 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "# Vercel Blob storage provider. Vercel sets BLOB_READ_WRITE_TOKEN",
       "# automatically on deployments with a connected Blob store.",
       "# BLOB_READ_WRITE_TOKEN=vercel_blob_rw_...",
+      "# OIDC alternative on Vercel: VERCEL_OIDC_TOKEN plus BLOB_STORE_ID.",
+      "# BLOB_STORE_ID=store_...",
       "# BLOB_ACCESS=private",
       "# BLOB_KEY_PREFIX=",
       "",
@@ -649,14 +651,14 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "- Package: `@beignet/provider-storage-vercel-blob`",
       "- Peer dependency: `@vercel/blob`",
       "- The preset wires `createVercelBlobStorageProvider()` in `server/providers.ts` and defers `storage` in `infra/port-wiring.ts`.",
-      "- On Vercel, connect a Blob store to the project and `BLOB_READ_WRITE_TOKEN` is set automatically; set it manually elsewhere.",
+      "- On Vercel, connect a Blob store to the project. Use its `BLOB_READ_WRITE_TOKEN`, or Vercel OIDC with `VERCEL_OIDC_TOKEN` plus `BLOB_STORE_ID`; set a read-write token manually outside Vercel.",
       "- The store is uniform-visibility (`BLOB_ACCESS`, default `private`): Vercel Blob does not report per-object access back, so mixed visibility needs a second store.",
       "- Use `ctx.ports.storage` in app code; `ctx.ports.vercelBlob` is available as an escape hatch.",
       "",
     ].join("\n"),
     nextSteps: [
       "Run your package manager install command.",
-      "Connect a Vercel Blob store to the project (or set BLOB_READ_WRITE_TOKEN manually).",
+      "Connect a Vercel Blob store and configure either BLOB_READ_WRITE_TOKEN or Vercel OIDC with BLOB_STORE_ID plus VERCEL_OIDC_TOKEN.",
       "Run beignet provider audit and beignet doctor --strict.",
     ],
     conflictingProviderEntries: [
@@ -689,6 +691,8 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "UPSTASH_REDIS_REST_TOKEN=dev-placeholder-change-me",
       "UPSTASH_PREFIX=beignet:ratelimit",
       "# UPSTASH_ALGORITHM=fixed-window",
+      "# UPSTASH_TIMEOUT_MS=5000",
+      "# UPSTASH_TIMEOUT_POLICY=fail-closed",
       "",
     ].join("\n"),
     docs: [
@@ -698,6 +702,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "- Peer dependencies: `@upstash/ratelimit` and `@upstash/redis`",
       "- The preset wires `createUpstashRateLimitProvider()` in `server/providers.ts` and defers `rateLimit` in `infra/port-wiring.ts`.",
       "- `.env.example` ships dev placeholders so the app boots; set real `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` values before rate limiting requests.",
+      "- Rate-limit checks time out after 5000ms and fail closed by default. Set `UPSTASH_TIMEOUT_POLICY=fail-open` only when availability is more important than enforcement during an Upstash outage.",
       "- Use `ctx.ports.rateLimit` in app code; `ctx.ports.upstash` is available as an escape hatch.",
       "",
     ].join("\n"),