@beignet/cli 0.0.41 → 0.0.42

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 { 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,6 +47,8 @@ export type RunDatabaseCommandResult = {
   args: string[];
   stdout?: string;
   stderr?: string;
+  outputTruncated?: boolean;
+  timedOut?: boolean;
   dryRun: boolean;
   exitCode: number;
 };
@@ -56,17 +76,18 @@ type ProcessTerminationPlan =
   | { kind: "process-group"; pid: number; signal: NodeJS.Signals }
   | { kind: "windows-process-tree"; command: string; args: string[] };
 
-export type DatabaseSchemaDialect = "sqlite" | "postgres" | "mysql";
-export type DatabaseSchemaTable = "audit" | "idempotency" | "outbox";
-
+/** 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";
@@ -92,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.
  *
@@ -108,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);
@@ -118,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];
@@ -137,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 {
@@ -151,6 +171,8 @@ export async function runDatabaseCommand(
     ...(options.captureOutput
       ? { stdout: commandResult.stdout, stderr: commandResult.stderr }
       : {}),
+    ...(commandResult.outputTruncated ? { outputTruncated: true } : {}),
+    ...(commandResult.timedOut ? { timedOut: true } : {}),
   };
 }
 
@@ -164,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",
@@ -196,6 +221,7 @@ export async function syncDatabaseSchema(
     dryRun: Boolean(options.dryRun),
   };
 
+  options.signal?.throwIfAborted();
   const schemaStatus = await writeProjectFile(
     cwd,
     output,
@@ -393,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) {
@@ -589,6 +615,9 @@ export function spawnCommand(
     });
     child.on("close", (code) => {
       if (settled) return;
+      if (timedOut && ownsProcessGroup && forceKillTimeout) {
+        terminateChild(child, "SIGKILL", ownsProcessGroup);
+      }
       settled = true;
       cleanup();
       resolve({
@@ -617,6 +646,7 @@ export function spawnCommand(
         timedOut = true;
         terminateChild(child, "SIGTERM", ownsProcessGroup);
         forceKillTimeout = setTimeout(() => {
+          forceKillTimeout = undefined;
           if (!settled) terminateChild(child, "SIGKILL", ownsProcessGroup);
         }, 1_000);
         forceKillTimeout.unref?.();

package/src/doctor-fixes.ts

@@ -0,0 +1,252 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createTwoFilesPatch } from "diff";
+import { type DoctorFixOperationId, doctorFixOperationIds } from "./choices.js";
+
+export type { DoctorFixOperationId } from "./choices.js";
+export { doctorFixOperationIds } from "./choices.js";
+
+/** Automatic doctor fix that was applied. */
+export type InspectFix = {
+  code: string;
+  message: string;
+  file: string;
+};
+
+/** Exact file mutation proposed by a doctor fix operation. */
+export type DoctorFixFileChange = {
+  file: string;
+  kind: "create" | "update";
+  beforeHash: string | null;
+  afterHash: string;
+  patch: string;
+};
+
+/** Selectable low-risk repair and every file change it requires. */
+export type DoctorFixOperation = {
+  id: DoctorFixOperationId;
+  fixes: InspectFix[];
+  changes: DoctorFixFileChange[];
+};
+
+/** Deterministic, read-only repair plan for the current app state. */
+export type DoctorFixPlan = {
+  schemaVersion: 1;
+  targetDir: string;
+  strict: boolean;
+  planId: string;
+  operations: DoctorFixOperation[];
+};
+
+/** Result of applying all or part of a guarded doctor fix plan. */
+export type DoctorFixApplyResult = {
+  schemaVersion: 1;
+  targetDir: string;
+  planId: string;
+  operationIds: DoctorFixOperationId[];
+  fixes: InspectFix[];
+};
+
+export type PlannedDoctorFixFileChange = DoctorFixFileChange & {
+  before: string | undefined;
+  after: string;
+};
+
+export type PlannedDoctorFixOperation = Omit<DoctorFixOperation, "changes"> & {
+  changes: PlannedDoctorFixFileChange[];
+};
+
+export type PlannedDoctorFixPlan = Omit<DoctorFixPlan, "operations"> & {
+  operations: PlannedDoctorFixOperation[];
+};
+
+export function planDoctorFixFileChange(options: {
+  file: string;
+  before?: string;
+  after: string;
+}): PlannedDoctorFixFileChange {
+  const oldName =
+    options.before === undefined ? "/dev/null" : `a/${options.file}`;
+  const newName = `b/${options.file}`;
+  return {
+    file: options.file,
+    kind: options.before === undefined ? "create" : "update",
+    beforeHash:
+      options.before === undefined ? null : contentHash(options.before),
+    afterHash: contentHash(options.after),
+    patch: createTwoFilesPatch(
+      oldName,
+      newName,
+      options.before ?? "",
+      options.after,
+      "",
+      "",
+      { context: 3 },
+    ),
+    before: options.before,
+    after: options.after,
+  };
+}
+
+export function createDoctorFixPlan(options: {
+  targetDir: string;
+  strict: boolean;
+  operations: PlannedDoctorFixOperation[];
+}): PlannedDoctorFixPlan {
+  const operationOrder = new Map(
+    doctorFixOperationIds.map((id, index) => [id, index]),
+  );
+  const operations = [...options.operations].sort(
+    (left, right) =>
+      (operationOrder.get(left.id) ?? Number.MAX_SAFE_INTEGER) -
+      (operationOrder.get(right.id) ?? Number.MAX_SAFE_INTEGER),
+  );
+  const fingerprint = {
+    targetDir: path.resolve(options.targetDir),
+    operations: operations.map((operation) => ({
+      id: operation.id,
+      changes: operation.changes.map((change) => ({
+        file: change.file,
+        beforeHash: change.beforeHash,
+        afterHash: change.afterHash,
+      })),
+    })),
+  };
+
+  return {
+    schemaVersion: 1,
+    targetDir: path.resolve(options.targetDir),
+    strict: options.strict,
+    planId: contentHash(JSON.stringify(fingerprint)),
+    operations,
+  };
+}
+
+export function publicDoctorFixPlan(plan: PlannedDoctorFixPlan): DoctorFixPlan {
+  return {
+    ...plan,
+    operations: plan.operations.map((operation) => ({
+      id: operation.id,
+      fixes: operation.fixes,
+      changes: operation.changes.map(
+        ({ before: _before, after: _after, ...change }) => change,
+      ),
+    })),
+  };
+}
+
+export async function applyPlannedDoctorFixes(
+  plan: PlannedDoctorFixPlan,
+  fixIds?: readonly DoctorFixOperationId[],
+  hooks: {
+    beforeWrite?: (
+      change: PlannedDoctorFixFileChange,
+      index: number,
+    ) => void | Promise<void>;
+  } = {},
+): Promise<DoctorFixApplyResult> {
+  const requested = fixIds ? new Set(fixIds) : undefined;
+  const operations = requested
+    ? plan.operations.filter((operation) => requested.has(operation.id))
+    : plan.operations;
+
+  if (requested) {
+    const available = new Set(plan.operations.map((operation) => operation.id));
+    const missing = [...requested].filter((id) => !available.has(id));
+    if (missing.length > 0) {
+      throw new Error(
+        `Doctor fix operations are not available in this plan: ${missing.join(", ")}. Run beignet doctor --fix --dry-run again.`,
+      );
+    }
+  }
+
+  const changes = operations.flatMap((operation) => operation.changes);
+  const duplicateFiles = duplicateValues(changes.map((change) => change.file));
+  if (duplicateFiles.length > 0) {
+    throw new Error(
+      `Doctor fix operations overlap on ${duplicateFiles.join(", ")}; no files were changed.`,
+    );
+  }
+
+  for (const change of changes) {
+    const current = await readOptionalFile(
+      path.join(plan.targetDir, change.file),
+    );
+    const currentHash = current === undefined ? null : contentHash(current);
+    if (currentHash !== change.beforeHash) {
+      throw new Error(
+        `Doctor fix plan is stale because ${change.file} changed. No files were changed; run beignet doctor --fix --dry-run again.`,
+      );
+    }
+  }
+
+  const attempted: PlannedDoctorFixFileChange[] = [];
+  try {
+    for (const [index, change] of changes.entries()) {
+      attempted.push(change);
+      await hooks.beforeWrite?.(change, index);
+      const destination = path.join(plan.targetDir, change.file);
+      await mkdir(path.dirname(destination), { recursive: true });
+      await writeFile(destination, change.after);
+    }
+  } catch (error) {
+    const rollbackErrors: string[] = [];
+    for (const change of attempted.reverse()) {
+      const destination = path.join(plan.targetDir, change.file);
+      try {
+        if (change.before === undefined) {
+          await rm(destination, { force: true });
+        } else {
+          await mkdir(path.dirname(destination), { recursive: true });
+          await writeFile(destination, change.before);
+        }
+      } catch (rollbackError) {
+        rollbackErrors.push(
+          rollbackError instanceof Error
+            ? rollbackError.message
+            : String(rollbackError),
+        );
+      }
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      rollbackErrors.length === 0
+        ? `Doctor fix application failed and was rolled back: ${message}`
+        : `Doctor fix application failed: ${message}. Rollback also failed: ${rollbackErrors.join("; ")}`,
+      { cause: error },
+    );
+  }
+
+  return {
+    schemaVersion: 1,
+    targetDir: plan.targetDir,
+    planId: plan.planId,
+    operationIds: operations.map((operation) => operation.id),
+    fixes: operations.flatMap((operation) => operation.fixes),
+  };
+}
+
+function contentHash(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+async function readOptionalFile(file: string): Promise<string | undefined> {
+  try {
+    return await readFile(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function duplicateValues(values: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+  for (const value of values) {
+    if (seen.has(value)) duplicates.add(value);
+    seen.add(value);
+  }
+  return [...duplicates].sort();
+}