@beignet/cli 0.0.41 → 0.0.42

package/src/lib.ts

@@ -27,7 +27,25 @@ export {
 } from "./app-map.js";
 export type { CreateOptions } from "./create.js";
 export { createProject } from "./create.js";
-export { runDatabaseCommand } from "./db.js";
+export type {
+  DatabaseCommand,
+  DatabaseSchemaDialect,
+  DatabaseSchemaTable,
+  RunDatabaseCommandOptions,
+  RunDatabaseCommandResult,
+  SyncDatabaseSchemaOptions,
+  SyncDatabaseSchemaResult,
+} from "./db.js";
+export { runDatabaseCommand, syncDatabaseSchema } from "./db.js";
+export type {
+  DoctorFixApplyResult,
+  DoctorFixFileChange,
+  DoctorFixOperation,
+  DoctorFixOperationId,
+  DoctorFixPlan,
+  InspectFix,
+} from "./doctor-fixes.js";
+export { doctorFixOperationIds } from "./doctor-fixes.js";
 export type {
   ExplainAppOptions,
   ExplainAppResult,
@@ -46,12 +64,21 @@ export {
   formatExplain,
 } from "./explain.js";
 export { main } from "./index.js";
+export type {
+  ApplyDoctorFixPlanOptions,
+  DoctorFixInspectionResult,
+  DoctorFixPlanResult,
+} from "./inspect.js";
 export {
   applyDoctorFixes,
+  applyDoctorFixPlan,
   formatDoctor,
+  formatDoctorFixPlan,
+  formatDoctorFixPlanGithub,
   formatDoctorGithub,
   formatRoutes,
   inspectApp,
+  planDoctorFixes,
 } from "./inspect.js";
 export { formatLint, formatLintGithub, lintApp } from "./lint.js";
 export type { MakeFeatureAddon, MakeFeatureRecipe } from "./make.js";

package/src/make/shared.ts

@@ -18,7 +18,7 @@ import {
 import {
   currentGeneratedPackageScripts,
   externalVersions,
-  legacyGeneratedPackageScripts,
+  isLegacyGeneratedPackageScript,
 } from "../templates/shared.js";
 
 export type MakeResult = {
@@ -1096,7 +1096,7 @@ export async function updatePackageScripts(
   for (const [name, command] of Object.entries(scripts)) {
     if (
       !packageJson.scripts[name] ||
-      packageJson.scripts[name] === legacyGeneratedPackageScripts[name]
+      isLegacyGeneratedPackageScript(name, packageJson.scripts[name])
     ) {
       packageJson.scripts[name] = command;
     }
@@ -1162,7 +1162,7 @@ function updateGeneratedPackageScripts(scripts: Record<string, string>): void {
     currentGeneratedPackageScripts,
   )) {
     if (
-      scripts[name] === legacyGeneratedPackageScripts[name] ||
+      isLegacyGeneratedPackageScript(name, scripts[name]) ||
       (name === "test" && !scripts[name])
     ) {
       scripts[name] = command;

package/src/mcp.ts

@@ -5,9 +5,28 @@ import { z } from "zod";
 import { mapApp, projectAppMap } from "./app-map.js";
 import { appMapNodeKinds } from "./app-map-schema.js";
 import { checkApp } from "./check.js";
-import { type ProviderPresetName, providerPresetChoices } from "./choices.js";
+import {
+  databaseCommandChoices,
+  databaseSchemaDialectChoices,
+  databaseSchemaTableChoices,
+  doctorFixOperationIds,
+  type ProviderPresetName,
+  providerPresetChoices,
+} from "./choices.js";
+import {
+  defaultDatabaseCommandMaxOutputBytes,
+  defaultDatabaseCommandTimeoutMs,
+  runDatabaseCommand,
+  syncDatabaseSchema,
+} from "./db.js";
 import { explainApp, explainTargetKinds } from "./explain.js";
-import { applyDoctorFixes, inspectApp } from "./inspect.js";
+import {
+  applyDoctorFixesWithResult,
+  applyDoctorFixPlan,
+  createDoctorFixInspectionResult,
+  inspectApp,
+  planDoctorFixes,
+} from "./inspect.js";
 import { lintApp } from "./lint.js";
 import {
   type MakeResourceResult,
@@ -379,14 +398,14 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
     "explain",
     {
       description:
-        "Explain one mapped Beignet feature, route, provider, or diagnostic using deterministic source evidence. Returns relationships, relevant conventions, findings, suggested files, and follow-up commands without changing the app.",
+        "Explain one mapped Beignet concept or diagnostic using deterministic source evidence. Supports every app-map node kind and returns relationships, relevant conventions, findings, suggested files, and follow-up commands without changing the app.",
       inputSchema: {
         kind: z.enum(explainTargetKinds).describe("Mapped concept to explain."),
         target: z
           .string()
           .min(1)
           .describe(
-            "Feature name, METHOD /path route, provider package or port name, or diagnostic code.",
+            "Stable ID, runtime name, declaration name, source selector, applicable concept alias, or diagnostic code.",
           ),
       },
       annotations: { readOnlyHint: true },
@@ -441,6 +460,107 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
       ),
   );
 
+  server.registerTool(
+    "db",
+    {
+      description:
+        "Run one app-owned database lifecycle command and return exactly the versioned beignet db <command> --json result. Supports generate, migrate, seed, and reset; captures a bounded output tail, stops after the configured timeout, and cancels the complete child process tree with the MCP request. Dry runs validate prerequisites and report the command without executing it.",
+      inputSchema: {
+        command: z
+          .enum(databaseCommandChoices)
+          .describe("Database lifecycle command to run."),
+        dryRun: z
+          .boolean()
+          .optional()
+          .describe(
+            "Validate prerequisites and report the app-owned script without executing it. This does not simulate SQL or data changes.",
+          ),
+        timeoutMs: z
+          .number()
+          .int()
+          .min(1_000)
+          .max(60 * 60 * 1_000)
+          .optional()
+          .describe(
+            "Maximum command duration in milliseconds. Defaults to 600000 (10 minutes).",
+          ),
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (input, extra) =>
+      safeToolResult(async () =>
+        jsonResult(
+          await runDatabaseCommand({
+            command: input.command,
+            cwd,
+            captureOutput: true,
+            maxOutputBytes: defaultDatabaseCommandMaxOutputBytes,
+            signal: extra.signal,
+            timeoutMs: input.timeoutMs ?? defaultDatabaseCommandTimeoutMs,
+            dryRun: input.dryRun,
+          }),
+        ),
+      ),
+  );
+
+  server.registerTool(
+    "db_schema_sync",
+    {
+      description:
+        "Idempotently sync app-owned Drizzle schema re-exports for Beignet provider tables and return exactly the versioned beignet db schema sync --json result. Supports dry-run planning and never generates or applies SQL migrations.",
+      inputSchema: {
+        dialect: z
+          .enum(databaseSchemaDialectChoices)
+          .optional()
+          .describe(
+            "Drizzle dialect. Inferred from registered providers or drizzle.config.* when omitted.",
+          ),
+        tables: z
+          .array(z.enum(databaseSchemaTableChoices))
+          .min(1)
+          .optional()
+          .describe(
+            "Beignet provider tables to re-export. Defaults to audit, idempotency, and outbox.",
+          ),
+        output: z
+          .string()
+          .min(1)
+          .optional()
+          .describe(
+            "App-relative schema output. Defaults to infra/db/schema/beignet.ts.",
+          ),
+        dryRun: z
+          .boolean()
+          .optional()
+          .describe("Preview schema source changes without writing files."),
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (input, extra) =>
+      safeToolResult(async () =>
+        jsonResult(
+          await syncDatabaseSchema({
+            cwd,
+            dialect: input.dialect,
+            tables: input.tables,
+            output: input.output,
+            dryRun: input.dryRun,
+            signal: extra.signal,
+          }),
+        ),
+      ),
+  );
+
   server.registerTool(
     "routes",
     {
@@ -469,7 +589,7 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
     "doctor",
     {
       description:
-        "Check app wiring and Beignet conventions, returning diagnostics, the detected convention, and applied fixes as JSON. Strict mode (the default) is the CI bar and includes CI-oriented warnings. Read-only; use doctor_fix to repair registration drift.",
+        "Check app wiring and Beignet conventions, returning diagnostics and the detected convention as JSON. Strict mode (the default) is the CI bar and includes CI-oriented warnings. Read-only; use doctor_fix_plan before a guarded doctor_fix repair.",
       inputSchema: {
         strict: z
           .boolean()
@@ -489,28 +609,82 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
       }),
   );
 
+  server.registerTool(
+    "doctor_fix_plan",
+    {
+      description:
+        "Plan every currently available low-risk doctor repair without changing files. Returns stable operation IDs, exact unified patches, file hashes, and a plan ID for guarded doctor_fix application.",
+      inputSchema: {
+        strict: z
+          .boolean()
+          .optional()
+          .describe("Include CI-oriented warnings. Defaults to true."),
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (input) =>
+      safeToolResult(async () => {
+        return jsonResult(
+          await planDoctorFixes({ cwd, strict: input.strict ?? true }),
+        );
+      }),
+  );
+
   server.registerTool(
     "doctor_fix",
     {
       description:
-        "Apply low-risk doctor fixes, then re-check the app. Repairs route-group, schedule, task, outbox, and listener registration drift. Returns applied fixes and remaining diagnostics as JSON.",
+        "Apply low-risk doctor repairs, then re-check the app. With no planId, preserves the legacy apply-all behavior. Pass the planId returned by doctor_fix_plan for stale-file protection, optionally with fixIds to select repair operations.",
       inputSchema: {
         strict: z
           .boolean()
           .optional()
           .describe("Include CI-oriented warnings. Defaults to true."),
+        planId: z
+          .string()
+          .min(1)
+          .optional()
+          .describe("Plan ID returned by doctor_fix_plan."),
+        fixIds: z
+          .array(z.enum(doctorFixOperationIds))
+          .min(1)
+          .optional()
+          .describe("Repair operation IDs to apply. Requires planId."),
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
       },
     },
     async (input) =>
       safeToolResult(async () => {
         const strict = input.strict ?? true;
-        const fixes = await applyDoctorFixes({ cwd, strict });
-        const result = await inspectApp({ cwd, strict });
-        return jsonResult({
-          diagnostics: result.diagnostics,
-          convention: result.convention,
-          fixes,
-        });
+        if (input.fixIds && !input.planId) {
+          throw new Error(
+            "doctor_fix fixIds require planId from doctor_fix_plan.",
+          );
+        }
+        const applied = input.planId
+          ? await applyDoctorFixPlan({
+              cwd,
+              strict,
+              planId: input.planId,
+              ...(input.fixIds ? { fixIds: input.fixIds } : {}),
+            })
+          : await applyDoctorFixesWithResult({ cwd, strict });
+        return jsonResult(
+          createDoctorFixInspectionResult(
+            await inspectApp({ cwd, strict }),
+            applied,
+          ),
+        );
       }),
   );
 

package/src/templates/agents.ts

@@ -62,8 +62,11 @@ use, so their absence is fine. \`${cli} make event\`, \`${cli} make job\`,
 \`${cli} make listener\`, \`${cli} make schedule\`, \`${cli} make task\`,
 \`${cli} make seed\`, and \`${cli} make upload\` create or update their
 required app entrypoints.
-\`${cli} doctor\` detects registration drift. \`${cli} doctor --fix\` repairs
-route-group, schedule, task, outbox, and listener registration.
+\`${cli} doctor\` detects registration drift. Preview exact repair patches
+with \`${cli} doctor --fix --dry-run\`, then apply the returned plan with
+\`${cli} doctor --fix --plan <plan-id>\` and optional
+\`--only <operation-ids>\`. Plain \`${cli} doctor --fix\` remains the
+apply-all shortcut.
 
 ## Prefer generators
 
@@ -73,6 +76,9 @@ artifact list. Use \`${cli} make feature <name> --recipe full-slice\` when you
 need a richer reference slice with policy, client helpers, workflow artifacts,
 events, listener registration, jobs, and outbox wiring. After changing the Drizzle schema in
 \`infra/db/schema/\`, run \`${cli} db generate\` then \`${cli} db migrate\`.
+When MCP is available, use \`db_schema_sync\` for Beignet provider table
+re-exports and \`db\` for \`generate\`, \`migrate\`, \`seed\`, or \`reset\`
+instead of falling back to a shell.
 
 ## The framework already solves these
 
@@ -148,17 +154,27 @@ skill-loading block.
 \`.mcp.json\` registers the app-local \`@beignet/cli\` bin at
 \`./node_modules/.bin/beignet mcp\`, which exposes the app map, validation, and
 generators as structured tools named exactly: \`app_map\`, \`explain\`,
-\`check\`, \`routes\`, \`doctor\`, \`doctor_fix\`, \`lint\`, \`make\`,
-\`provider_add\`. Use \`app_map\` before broad code search and pass a feature
+\`check\`, \`db\`, \`db_schema_sync\`, \`routes\`, \`doctor\`,
+\`doctor_fix_plan\`, \`doctor_fix\`, \`lint\`, \`make\`, \`provider_add\`.
+Use \`doctor_fix_plan\` to inspect
+stable operation IDs, hashes, exact patches, and current diagnostics before
+passing its \`planId\` and optional \`fixIds\` to \`doctor_fix\`. Guarded
+apply returns the same plan metadata and inspection payload as the CLI. Use
+\`app_map\` before broad code search and pass a feature
 or node kinds to keep context focused. Use \`explain\` for source-backed
-relationships, conventions, findings, and suggested files for one feature,
-route, provider, or diagnostic. Use \`check\` after edits to run the complete
-validation loop; it returns the same versioned result as
+relationships, conventions, findings, and suggested files for any mapped
+concept or diagnostic; its kinds match the app map. Use \`check\` after edits
+to run the complete validation loop; it returns the same versioned result as
 \`${cli} check --json\`, bounds failure output, and cancels the active package
 script when the MCP request is cancelled. It does not apply Beignet fixes, but
-app-owned scripts retain their normal side effects. Clients that do not read
-\`.mcp.json\` can use the same command from the app root; use \`${cli} mcp\`
-only for terminal debugging.
+app-owned scripts retain their normal side effects. Use \`db_schema_sync\` to
+preview or apply idempotent provider-table schema re-exports, then call \`db\`
+with \`generate\` and \`migrate\`; database output is bounded, commands time
+out, and cancellation stops the active process tree. Treat \`seed\` and
+especially \`reset\` as app-owned mutations. Lifecycle \`dryRun\` validates
+and reports the script without executing it; it does not simulate SQL or data
+changes. Clients that do not read \`.mcp.json\` can use the same command from
+the app root; use \`${cli} mcp\` only for terminal debugging.
 `;
 }
 

package/src/templates/base.ts

@@ -1,6 +1,7 @@
 import { databaseLocalUrl, databaseStartCommand } from "../choices.js";
 import { shadcnDependencies, shadcnDevDependencies } from "./shadcn.js";
 import {
+  currentGeneratedPackageScripts,
   externalVersions,
   hasStarterProvider,
   json,
@@ -97,11 +98,11 @@ export function packageJson(ctx: TemplateContext): string {
     start: "next start",
     lint: "biome lint .",
     format: "biome format --write .",
-    test: "tsx lib/beignet-test-runner.ts",
+    test: currentGeneratedPackageScripts.test,
     typecheck: "tsc --noEmit",
     "db:generate": "drizzle-kit generate",
     "db:migrate": "drizzle-kit migrate",
-    "db:reset": "tsx infra/db/reset.ts",
+    "db:reset": currentGeneratedPackageScripts["db:reset"],
   };
 
   return json({

package/src/templates/shared.ts

@@ -67,18 +67,26 @@ export const externalVersions = {
   upstashRedis: "^1.0.0",
 };
 
-export const legacyGeneratedPackageScripts: Record<string, string> = {
-  "db:reset": "bun infra/db/reset.ts",
-  "db:seed": "bun server/seed.ts",
-  test: "bun test",
-};
+export const legacyGeneratedPackageScripts: Record<string, readonly string[]> =
+  {
+    "db:reset": ["bun infra/db/reset.ts"],
+    "db:seed": ["bun server/seed.ts"],
+    test: ["bun test", "tsx lib/beignet-test-runner.ts"],
+  };
 
 export const currentGeneratedPackageScripts: Record<string, string> = {
   "db:reset": "tsx infra/db/reset.ts",
   "db:seed": "tsx server/seed.ts",
-  test: "tsx lib/beignet-test-runner.ts",
+  test: "node --import tsx lib/beignet-test-runner.ts",
 };
 
+export function isLegacyGeneratedPackageScript(
+  name: string,
+  command: string | undefined,
+): boolean {
+  return legacyGeneratedPackageScripts[name]?.includes(command ?? "") ?? false;
+}
+
 /**
  * Dialect-specific names used when rendering database-aware templates.
  */