@beignet/cli 0.0.40 → 0.0.42

package/src/check.ts

@@ -22,6 +22,7 @@ export type CheckStep = {
   status: "passed" | "failed" | "skipped";
   detail?: string;
   output?: string;
+  outputTruncated?: boolean;
   durationMs: number;
 };
 
@@ -40,11 +41,18 @@ export type CheckAppOptions = {
   color?: boolean;
   /** Append a `beignet preflight` step after the doctor step. */
   preflight?: boolean;
+  /** Keep only the last N bytes from each package-script output stream. */
+  maxOutputBytes?: number;
+  /** Cancel the active package script with the owning request. */
+  signal?: AbortSignal;
+  /** Fail each package script after this many milliseconds. */
+  scriptTimeoutMs?: number;
   /** Called after each step completes, for incremental progress output. */
   onStep?: (step: CheckStep) => void;
 };
 
 const scriptStepNames = ["lint", "typecheck", "test"] as const;
+const defaultMaxOutputBytes = 64 * 1024;
 
 /**
  * Run the whole app validation loop as one command: `beignet lint`,
@@ -67,17 +75,21 @@ export async function checkApp(
     options.onStep?.(step);
   };
 
+  options.signal?.throwIfAborted();
   record(await lintStep(targetDir, options));
+  options.signal?.throwIfAborted();
   const { step: doctorStep, fixes } = await runDoctorStep(targetDir, options);
   record(doctorStep);
 
   if (options.preflight) {
+    options.signal?.throwIfAborted();
     record(await preflightStep(targetDir));
   }
 
   const scripts = await readPackageScripts(targetDir);
   for (const script of scriptStepNames) {
-    record(await scriptStep(targetDir, runner, script, scripts));
+    options.signal?.throwIfAborted();
+    record(await scriptStep(targetDir, runner, script, scripts, options));
   }
 
   return {
@@ -114,7 +126,10 @@ export function formatCheckStep(
     .split("\n")
     .map((outputLine) => `  ${outputLine}`)
     .join("\n");
-  return `${line}\n${indented}`;
+  const truncation = step.outputTruncated
+    ? "\n  … output truncated; showing the retained tail"
+    : "";
+  return `${line}\n${indented}${truncation}`;
 }
 
 /**
@@ -203,6 +218,7 @@ async function scriptStep(
   runner: string,
   script: (typeof scriptStepNames)[number],
   scripts: Record<string, string>,
+  options: CheckAppOptions,
 ): Promise<CheckStep> {
   const command = `${runner} run ${script}`;
   if (!scripts[script]) {
@@ -218,17 +234,24 @@ async function scriptStep(
   const startedAt = Date.now();
   const result = await spawnCommand(runner, ["run", script], targetDir, {
     captureOutput: true,
+    maxOutputBytes: options.maxOutputBytes ?? defaultMaxOutputBytes,
+    signal: options.signal,
+    timeoutMs: options.scriptTimeoutMs,
   });
-  const failed = result.exitCode !== 0;
+  const failed = result.timedOut === true || result.exitCode !== 0;
+  const detail = result.timedOut
+    ? `${command}; timed out after ${options.scriptTimeoutMs}ms`
+    : command;
 
   return {
     name: script,
     command,
     status: failed ? "failed" : "passed",
-    detail: command,
+    detail,
     ...(failed
       ? { output: [result.stdout, result.stderr].filter(Boolean).join("\n") }
       : {}),
+    ...(failed && result.outputTruncated ? { outputTruncated: true } : {}),
     durationMs: Date.now() - startedAt,
   };
 }

package/src/choices.ts

@@ -5,6 +5,12 @@
  * templates or generators at startup.
  */
 
+function defineExhaustiveChoices<Choice extends string>() {
+  return <const Choices extends readonly Choice[]>(
+    choices: Exclude<Choice, Choices[number]> extends never ? Choices : never,
+  ): Choices => choices;
+}
+
 /**
  * Package managers supported by the app template generator.
  */
@@ -13,6 +19,23 @@ export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
  * Application templates supported by the app template generator.
  */
 export type TemplateName = "next";
+
+/**
+ * Stable repair operations supported by doctor fix planning.
+ */
+export const doctorFixOperationIds = [
+  "package.repair-generated-support",
+  "routes.register-missing",
+  "schedules.register-missing",
+  "tasks.register-missing",
+  "workflows.register-missing",
+  "outbox.register-missing",
+  "listeners.register-missing",
+  "openapi.register-missing",
+] as const;
+
+/** Stable identifier for one selectable doctor repair operation. */
+export type DoctorFixOperationId = (typeof doctorFixOperationIds)[number];
 /**
  * Optional providers rendered directly by the starter template.
  *
@@ -27,6 +50,40 @@ export type StarterProviderName =
  * Databases supported by the starter's Drizzle persistence layer.
  */
 export type DatabaseName = "sqlite" | "postgres" | "mysql";
+
+/** Database lifecycle command supported by Beignet. */
+export type DatabaseCommand = "generate" | "migrate" | "seed" | "reset";
+
+/** Database lifecycle commands shared by the CLI, library, and MCP tool. */
+export const databaseCommandChoices =
+  defineExhaustiveChoices<DatabaseCommand>()([
+    "generate",
+    "migrate",
+    "seed",
+    "reset",
+  ]);
+
+/** Drizzle dialect supported by provider-table schema sync. */
+export type DatabaseSchemaDialect = "sqlite" | "postgres" | "mysql";
+
+/** Drizzle dialects supported by provider-table schema sync. */
+export const databaseSchemaDialectChoices =
+  defineExhaustiveChoices<DatabaseSchemaDialect>()([
+    "sqlite",
+    "postgres",
+    "mysql",
+  ]);
+
+/** Beignet provider table supported by database schema sync. */
+export type DatabaseSchemaTable = "audit" | "idempotency" | "outbox";
+
+/** Beignet provider tables supported by database schema sync. */
+export const databaseSchemaTableChoices =
+  defineExhaustiveChoices<DatabaseSchemaTable>()([
+    "audit",
+    "idempotency",
+    "outbox",
+  ]);
 /**
  * Provider setup presets supported by `beignet provider add`.
  */

package/src/db.ts

@@ -1,11 +1,23 @@
-import { spawn } from "node:child_process";
+import { type ChildProcess, spawn } from "node:child_process";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import {
+  type DatabaseCommand,
+  type DatabaseSchemaDialect,
+  type DatabaseSchemaTable,
+  databaseSchemaTableChoices,
+} from "./choices.js";
+
+export type {
+  DatabaseCommand,
+  DatabaseSchemaDialect,
+  DatabaseSchemaTable,
+} from "./choices.js";
 
-/**
- * Database lifecycle operations supported by the Beignet CLI.
- */
-export type DatabaseCommand = "generate" | "migrate" | "seed" | "reset";
+/** Default output retained per stream by structured database command callers. */
+export const defaultDatabaseCommandMaxOutputBytes = 64 * 1024;
+/** Default timeout used by request-controlled database command callers. */
+export const defaultDatabaseCommandTimeoutMs = 10 * 60 * 1_000;
 
 /**
  * Options for running a database lifecycle command.
@@ -14,6 +26,12 @@ export type RunDatabaseCommandOptions = {
   command: DatabaseCommand;
   cwd?: string;
   captureOutput?: boolean;
+  /** Keep only the last N bytes from each output stream. */
+  maxOutputBytes?: number;
+  /** Cancel the app-owned database script when the owning request aborts. */
+  signal?: AbortSignal;
+  /** Stop the app-owned database script after this many milliseconds. */
+  timeoutMs?: number;
   dryRun?: boolean;
 };
 
@@ -29,21 +47,47 @@ export type RunDatabaseCommandResult = {
   args: string[];
   stdout?: string;
   stderr?: string;
+  outputTruncated?: boolean;
+  timedOut?: boolean;
   dryRun: boolean;
   exitCode: number;
 };
 
-export type DatabaseSchemaDialect = "sqlite" | "postgres" | "mysql";
-export type DatabaseSchemaTable = "audit" | "idempotency" | "outbox";
+export type SpawnCommandOptions = {
+  captureOutput: boolean;
+  /** Keep only the last N bytes from each output stream. Unbounded when omitted. */
+  maxOutputBytes?: number;
+  /** Cancel the child process when the owning request is aborted. */
+  signal?: AbortSignal;
+  /** Stop the child process after this many milliseconds. Unbounded when omitted. */
+  timeoutMs?: number;
+};
+
+export type SpawnCommandResult = {
+  exitCode: number;
+  stdout?: string;
+  stderr?: string;
+  outputTruncated?: boolean;
+  timedOut?: boolean;
+};
+
+type ProcessTerminationPlan =
+  | { kind: "child"; signal: NodeJS.Signals }
+  | { kind: "process-group"; pid: number; signal: NodeJS.Signals }
+  | { kind: "windows-process-tree"; command: string; args: string[] };
 
+/** Options for syncing app-owned Beignet provider-table schema re-exports. */
 export type SyncDatabaseSchemaOptions = {
   cwd?: string;
   dialect?: DatabaseSchemaDialect;
   tables?: readonly DatabaseSchemaTable[];
   output?: string;
   dryRun?: boolean;
+  /** Cancel before applying pending schema-file writes. */
+  signal?: AbortSignal;
 };
 
+/** Versioned report returned by `syncDatabaseSchema`. */
 export type SyncDatabaseSchemaResult = {
   schemaVersion: 1;
   command: "schema:sync";
@@ -69,12 +113,6 @@ const databaseScripts: Record<DatabaseCommand, string> = {
   reset: "db:reset",
 };
 
-const allDatabaseSchemaTables = [
-  "audit",
-  "idempotency",
-  "outbox",
-] as const satisfies readonly DatabaseSchemaTable[];
-
 /**
  * Run an app-owned database lifecycle script.
  *
@@ -85,6 +123,7 @@ const allDatabaseSchemaTables = [
 export async function runDatabaseCommand(
   options: RunDatabaseCommandOptions,
 ): Promise<RunDatabaseCommandResult> {
+  options.signal?.throwIfAborted();
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const script = databaseScripts[options.command];
   const packageJson = await readPackageJson(cwd);
@@ -95,6 +134,7 @@ export async function runDatabaseCommand(
   }
 
   await assertDatabaseCommandPreflight(cwd, options.command, scriptCommand);
+  options.signal?.throwIfAborted();
 
   const runner = await detectPackageManager(cwd);
   const args = ["run", script];
@@ -114,6 +154,9 @@ export async function runDatabaseCommand(
 
   const commandResult = await spawnCommand(runner, args, cwd, {
     captureOutput: Boolean(options.captureOutput),
+    maxOutputBytes: options.maxOutputBytes,
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
   });
 
   return {
@@ -128,6 +171,8 @@ export async function runDatabaseCommand(
     ...(options.captureOutput
       ? { stdout: commandResult.stdout, stderr: commandResult.stderr }
       : {}),
+    ...(commandResult.outputTruncated ? { outputTruncated: true } : {}),
+    ...(commandResult.timedOut ? { timedOut: true } : {}),
   };
 }
 
@@ -141,9 +186,12 @@ export async function runDatabaseCommand(
 export async function syncDatabaseSchema(
   options: SyncDatabaseSchemaOptions = {},
 ): Promise<SyncDatabaseSchemaResult> {
+  options.signal?.throwIfAborted();
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const dialect = await resolveDatabaseSchemaDialect(cwd, options.dialect);
-  const tables = uniqueSchemaTables(options.tables ?? allDatabaseSchemaTables);
+  const tables = uniqueSchemaTables(
+    options.tables ?? databaseSchemaTableChoices,
+  );
   const output = normalizeAppRelativePath(
     cwd,
     options.output ?? "infra/db/schema/beignet.ts",
@@ -173,6 +221,7 @@ export async function syncDatabaseSchema(
     dryRun: Boolean(options.dryRun),
   };
 
+  options.signal?.throwIfAborted();
   const schemaStatus = await writeProjectFile(
     cwd,
     output,
@@ -370,7 +419,7 @@ const schemaTableDefinitions: Record<
 function uniqueSchemaTables(
   tables: readonly DatabaseSchemaTable[],
 ): DatabaseSchemaTable[] {
-  const unique = allDatabaseSchemaTables.filter((table) =>
+  const unique = databaseSchemaTableChoices.filter((table) =>
     tables.includes(table),
   );
   if (unique.length === 0) {
@@ -504,34 +553,233 @@ export function spawnCommand(
   command: string,
   args: readonly string[],
   cwd: string,
-  options: { captureOutput: boolean },
-): Promise<{ exitCode: number; stdout?: string; stderr?: string }> {
+  options: SpawnCommandOptions,
+): Promise<SpawnCommandResult> {
+  if (options.signal?.aborted) {
+    return Promise.reject(commandAbortError(options.signal));
+  }
+  const timeoutMs =
+    options.timeoutMs === undefined
+      ? undefined
+      : normalizePositiveInteger(options.timeoutMs, "Command timeout");
+  const maxOutputBytes =
+    options.maxOutputBytes === undefined
+      ? undefined
+      : normalizeNonNegativeInteger(
+          options.maxOutputBytes,
+          "Maximum output bytes",
+        );
+
   return new Promise((resolve, reject) => {
+    let settled = false;
+    let timedOut = false;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let forceKillTimeout: ReturnType<typeof setTimeout> | undefined;
+    const ownsProcessGroup = commandOwnsProcessGroup(process.platform, {
+      signal: options.signal,
+      timeoutMs,
+    });
     const child = spawn(command, args, {
       cwd,
+      detached: ownsProcessGroup,
       env: process.env,
       stdio: options.captureOutput ? ["ignore", "pipe", "pipe"] : "inherit",
     });
 
-    const stdout: Buffer[] = [];
-    const stderr: Buffer[] = [];
+    const stdout = createOutputCapture(maxOutputBytes);
+    const stderr = createOutputCapture(maxOutputBytes);
+
+    const cleanup = () => {
+      if (timeout) clearTimeout(timeout);
+      if (forceKillTimeout) clearTimeout(forceKillTimeout);
+      options.signal?.removeEventListener("abort", abort);
+    };
+    const abort = () => {
+      if (settled) return;
+      settled = true;
+      terminateChild(child, "SIGKILL", ownsProcessGroup);
+      cleanup();
+      reject(commandAbortError(options.signal));
+    };
 
     if (options.captureOutput) {
-      child.stdout?.on("data", (chunk: Buffer) => stdout.push(chunk));
-      child.stderr?.on("data", (chunk: Buffer) => stderr.push(chunk));
+      child.stdout?.on("data", (chunk: Buffer) => stdout.append(chunk));
+      child.stderr?.on("data", (chunk: Buffer) => stderr.append(chunk));
     }
 
-    child.on("error", reject);
-    child.on("close", (code) =>
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      if (timedOut && ownsProcessGroup && forceKillTimeout) {
+        terminateChild(child, "SIGKILL", ownsProcessGroup);
+      }
+      settled = true;
+      cleanup();
       resolve({
-        exitCode: code ?? 1,
+        exitCode: timedOut ? 1 : (code ?? 1),
         ...(options.captureOutput
           ? {
-              stdout: Buffer.concat(stdout).toString("utf8"),
-              stderr: Buffer.concat(stderr).toString("utf8"),
+              stdout: stdout.text(),
+              stderr: stderr.text(),
+              ...(stdout.truncated() || stderr.truncated()
+                ? { outputTruncated: true }
+                : {}),
             }
           : {}),
-      }),
-    );
+        ...(timedOut ? { timedOut: true } : {}),
+      });
+    });
+
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted) {
+      abort();
+      return;
+    }
+    if (timeoutMs !== undefined) {
+      timeout = setTimeout(() => {
+        if (settled) return;
+        timedOut = true;
+        terminateChild(child, "SIGTERM", ownsProcessGroup);
+        forceKillTimeout = setTimeout(() => {
+          forceKillTimeout = undefined;
+          if (!settled) terminateChild(child, "SIGKILL", ownsProcessGroup);
+        }, 1_000);
+        forceKillTimeout.unref?.();
+      }, timeoutMs);
+      timeout.unref?.();
+    }
   });
 }
+
+export function commandOwnsProcessGroup(
+  platform: NodeJS.Platform,
+  options: Pick<SpawnCommandOptions, "signal" | "timeoutMs">,
+): boolean {
+  return (
+    platform !== "win32" &&
+    (options.signal !== undefined || options.timeoutMs !== undefined)
+  );
+}
+
+export function commandTerminationPlan(
+  platform: NodeJS.Platform,
+  pid: number | undefined,
+  signal: NodeJS.Signals,
+  ownsProcessGroup: boolean,
+): ProcessTerminationPlan {
+  if (platform === "win32" && pid !== undefined) {
+    return {
+      kind: "windows-process-tree",
+      command: "taskkill",
+      args: ["/PID", String(pid), "/T", "/F"],
+    };
+  }
+  if (ownsProcessGroup && pid !== undefined) {
+    return { kind: "process-group", pid: -pid, signal };
+  }
+  return { kind: "child", signal };
+}
+
+function terminateChild(
+  child: ChildProcess,
+  signal: NodeJS.Signals,
+  ownsProcessGroup: boolean,
+): void {
+  const plan = commandTerminationPlan(
+    process.platform,
+    child.pid,
+    signal,
+    ownsProcessGroup,
+  );
+  if (plan.kind === "windows-process-tree") {
+    const killer = spawn(plan.command, plan.args, {
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    const fallback = () => {
+      if (child.exitCode === null) child.kill(signal);
+    };
+    killer.once("error", fallback);
+    killer.once("close", (code) => {
+      if (code !== 0) fallback();
+    });
+    killer.unref();
+    return;
+  }
+  if (plan.kind === "process-group") {
+    try {
+      process.kill(plan.pid, plan.signal);
+      return;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ESRCH") return;
+    }
+  }
+  child.kill(plan.signal);
+}
+
+function createOutputCapture(maxOutputBytes?: number): {
+  append(chunk: Buffer): void;
+  text(): string;
+  truncated(): boolean;
+} {
+  const limit = maxOutputBytes;
+  const unboundedChunks: Buffer[] = [];
+  let output: Buffer = Buffer.alloc(0);
+  let wasTruncated = false;
+
+  return {
+    append(chunk) {
+      if (limit === undefined) {
+        unboundedChunks.push(chunk);
+        return;
+      }
+      if (limit === 0) {
+        if (chunk.length > 0) wasTruncated = true;
+        return;
+      }
+      if (chunk.length >= limit) {
+        wasTruncated ||= output.length > 0 || chunk.length > limit;
+        output = Buffer.from(chunk.subarray(chunk.length - limit));
+        return;
+      }
+      const overflow = output.length + chunk.length - limit;
+      if (overflow > 0) {
+        wasTruncated = true;
+        output = Buffer.concat([output.subarray(overflow), chunk]);
+        return;
+      }
+      output = Buffer.concat([output, chunk]);
+    },
+    text: () =>
+      (limit === undefined ? Buffer.concat(unboundedChunks) : output).toString(
+        "utf8",
+      ),
+    truncated: () => wasTruncated,
+  };
+}
+
+function commandAbortError(signal?: AbortSignal): Error {
+  if (signal?.reason instanceof Error) return signal.reason;
+  const error = new Error("Command cancelled.");
+  error.name = "AbortError";
+  return error;
+}
+
+function normalizePositiveInteger(value: number, label: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+  return value;
+}
+
+function normalizeNonNegativeInteger(value: number, label: string): number {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`${label} must be a non-negative integer.`);
+  }
+  return value;
+}