@beignet/cli 0.0.47 → 0.0.49

package/src/check.ts

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { createPainter } from "./ansi.js";
 import { detectPackageManager, spawnCommand } from "./db.js";
@@ -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. */
@@ -68,6 +75,7 @@ export async function checkApp(
   options: CheckAppOptions = {},
 ): Promise<CheckAppResult> {
   const targetDir = path.resolve(options.cwd ?? process.cwd());
+  const scripts = await readAppPackageScripts(targetDir);
   const runner = await detectPackageManager(targetDir);
   const steps: CheckStep[] = [];
   const record = (step: CheckStep): void => {
@@ -81,12 +89,17 @@ 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);
   for (const script of scriptStepNames) {
     options.signal?.throwIfAborted();
     record(await scriptStep(targetDir, runner, script, scripts, options));
@@ -256,7 +269,7 @@ async function scriptStep(
   };
 }
 
-async function readPackageScripts(
+async function readAppPackageScripts(
   targetDir: string,
 ): Promise<Record<string, string>> {
   let source: string;
@@ -269,22 +282,85 @@ async function readPackageScripts(
   }
 
   const parsed = JSON.parse(source) as {
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
     scripts?: Record<string, string>;
   };
+  const dependencies = {
+    ...parsed.dependencies,
+    ...parsed.optionalDependencies,
+  };
+  if (
+    !["@beignet/core", "@beignet/next", "@beignet/web"].some(
+      (packageName) => dependencies[packageName] !== undefined,
+    )
+  ) {
+    throw new Error(
+      "package.json does not declare a Beignet runtime dependency. Run beignet check from a Beignet app root that depends on @beignet/core, @beignet/next, or @beignet/web.",
+    );
+  }
+  if (!(await hasBeignetAppStructure(targetDir))) {
+    throw new Error(
+      "package.json declares a Beignet runtime dependency, but no Beignet app structure was found. Run beignet check from an app root containing app-context.ts, beignet.config.*, or features/ with server/index.ts.",
+    );
+  }
   return parsed.scripts ?? {};
 }
 
-async function preflightStep(targetDir: string): Promise<CheckStep> {
+async function hasBeignetAppStructure(targetDir: string): Promise<boolean> {
+  const entries = await readdir(targetDir, { withFileTypes: true });
+  const entryByName = new Map(entries.map((entry) => [entry.name, entry]));
+  if (entryByName.get("app-context.ts")?.isFile()) return true;
+  if (
+    [
+      "beignet.config.ts",
+      "beignet.config.json",
+      "beignet.config.mjs",
+      "beignet.config.js",
+    ].some((file) => entryByName.get(file)?.isFile())
+  ) {
+    return true;
+  }
+  if (
+    !entryByName.get("features")?.isDirectory() ||
+    !entryByName.get("server")?.isDirectory()
+  ) {
+    return false;
+  }
+
+  try {
+    return (await stat(path.join(targetDir, "server/index.ts"))).isFile();
+  } catch {
+    return false;
+  }
+}
+
+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/explain.ts

@@ -795,7 +795,7 @@ const conventionsByTargetKind = {
   ],
   job: [
     "Jobs represent background work and remain explicit at provider-backed execution boundaries.",
-    "Feature jobs register through central runtime or outbox registries before workers can dispatch them.",
+    "Feature jobs register through central runtime or outbox registries before workers can dispatch them; registration does not install the required jobs port.",
   ],
   schedule: [
     "Schedules represent time-based triggers and delegate work to application workflows.",
@@ -819,11 +819,11 @@ const conventionsByTargetKind = {
   ],
   registry: [
     "Registries explicitly compose feature declarations into the runtime surface inspected by doctor and app-map.",
-    "Central registries remain the source of truth for runtime wiring and integrity checks.",
+    "Central registries remain the source of truth for runtime wiring and integrity checks; outbox registries containing jobs depend on a bound or deferred jobs dispatcher.",
   ],
   port: [
     "Ports define app-facing dependency interfaces; infrastructure adapters provide their concrete implementations.",
-    "App ports wire through infra/port-wiring.ts and remain available to use cases through application context.",
+    "App ports wire through the configured port-wiring file and remain available to use cases through application context; deferred ports are verified during server startup.",
   ],
   provider: [
     "Ports define app-facing interfaces, providers adapt external systems, and app infrastructure wires them together.",
@@ -839,7 +839,7 @@ const conventionsByTargetKind = {
   ],
   entrypoint: [
     "Runtime entrypoints compose the server or expose thin framework adapters over registered routes.",
-    "Entrypoints reuse central context, routes, providers, and workflow registries instead of duplicating application behavior.",
+    "Entrypoints reuse central context, routes, providers, and workflow registries instead of duplicating application behavior; outbox drains require delivery ports before they claim messages.",
   ],
   test: [
     "Feature behavior tests stay under features/<feature>/tests and exercise use cases, routes, policies, workflows, and UI.",

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.",
   ]);
 }