@beignet/cli 0.0.39 → 0.0.41

package/src/lib.ts

@@ -6,9 +6,45 @@
  * loads command modules lazily.
  */
 
+export type {
+  AppMapEdge,
+  AppMapEdgeKind,
+  AppMapNode,
+  AppMapNodeKind,
+  AppMapNodeStatus,
+  AppMapOptions,
+  AppMapProjectionOptions,
+  AppMapResult,
+  AppMapSource,
+  AppMapSummary,
+  AppMapUnresolvedReference,
+} from "./app-map.js";
+export {
+  appMapNodeKinds,
+  formatAppMap,
+  mapApp,
+  projectAppMap,
+} from "./app-map.js";
 export type { CreateOptions } from "./create.js";
 export { createProject } from "./create.js";
 export { runDatabaseCommand } from "./db.js";
+export type {
+  ExplainAppOptions,
+  ExplainAppResult,
+  ExplainEvidence,
+  ExplainFinding,
+  ExplainRelatedNode,
+  ExplainRelationship,
+  ExplainSuggestedAction,
+  ExplainSuggestedFile,
+  ExplainTarget,
+  ExplainTargetKind,
+} from "./explain.js";
+export {
+  explainApp,
+  explainTargetKinds,
+  formatExplain,
+} from "./explain.js";
 export { main } from "./index.js";
 export {
   applyDoctorFixes,

package/src/make/payments.ts

@@ -6,6 +6,7 @@ import {
   type ResolvedBeignetConfig,
   resolveConfig,
 } from "../config.js";
+import { assertNextFramework } from "../framework.js";
 import { appendToNamedArray, insertAfterImports } from "../registry-edits.js";
 import { testSupportTemplateFiles } from "../templates/testing.js";
 import {
@@ -71,6 +72,12 @@ export async function makePayments(
     ? resolveConfig(options.config)
     : await loadBeignetConfig(targetDir);
 
+  assertNextFramework(
+    config,
+    "beignet make payments",
+    "Next.js App Router billing and webhook handlers",
+  );
+
   await assertStandardApp(targetDir, config);
 
   const persistence = await detectResourcePersistence(targetDir, config);

package/src/make.ts

@@ -11,6 +11,7 @@ import {
   type ResolvedBeignetConfig,
   resolveConfig,
 } from "./config.js";
+import { assertNextFramework } from "./framework.js";
 import {
   adapterFilePath,
   addNamedImport,
@@ -143,6 +144,7 @@ import {
 } from "./make/shared.js";
 import {
   appendToArrayExpression,
+  appendToNamedArray,
   appendToOutboxRegistryArray,
   arrayInitializerInfo,
   identifiersFromArrayExpression,
@@ -1088,6 +1090,7 @@ export async function makeJob(options: MakeJobOptions): Promise<MakeJobResult> {
   await updateOutboxRegistry(targetDir, names, "jobs", config, {
     dryRun: true,
   });
+  await updateInngestJobRegistry(targetDir, names, config, { dryRun: true });
 
   const result = await makeFeatureArtifact({
     targetDir,
@@ -1114,6 +1117,9 @@ export async function makeJob(options: MakeJobOptions): Promise<MakeJobResult> {
   await applyOutboxPortWiring(result, targetDir, config, {
     dryRun: Boolean(options.dryRun),
   });
+  await applyInngestJobRegistryUpdate(result, targetDir, names, config, {
+    dryRun: Boolean(options.dryRun),
+  });
 
   return result;
 }
@@ -1499,6 +1505,14 @@ export async function makeSchedule(
     ? resolveConfig(options.config)
     : await loadBeignetConfig(targetDir);
 
+  if (options.route) {
+    assertNextFramework(
+      config,
+      "beignet make schedule --route",
+      "a Next.js App Router cron handler",
+    );
+  }
+
   await assertFeatureArtifactApp(targetDir, config, "schedule", {
     requireServer: Boolean(options.route),
   });
@@ -1714,6 +1728,9 @@ async function updateOutboxPortWiring(
       path.join(infrastructureDir(config), "db/provider.ts"),
     );
   }
+  if (await updateOutboxDrainProvider(targetDir, config, options)) {
+    changes.updatedFiles.push(providersFilePath(config));
+  }
   if (await updateOutboxRepositoriesReturnType(targetDir, config, options)) {
     changes.updatedFiles.push(drizzleRepositoriesPath(config));
   }
@@ -1825,6 +1842,31 @@ async function updateOutboxInfrastructurePorts(
   return true;
 }
 
+async function projectSupportsNextAfter(targetDir: string): Promise<boolean> {
+  const packageJson = JSON.parse(
+    await readFile(path.join(targetDir, "package.json"), "utf8"),
+  ) as PackageJsonLike;
+  const version =
+    packageJson.dependencies?.next ?? packageJson.devDependencies?.next;
+  if (!version) return false;
+
+  return version.split("||").every((range) => {
+    const lowerBound =
+      /^\s*(\^|~|>=|>|=|<=|<)?\s*v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?([+-][0-9A-Za-z.-]+)?(?=\s|$)/.exec(
+        range,
+      );
+    if (!lowerBound) return false;
+
+    const operator = lowerBound[1];
+    if (operator === "<" || operator === "<=") return false;
+    if (lowerBound[5]?.startsWith("-")) return false;
+
+    const major = Number(lowerBound[2]);
+    const minor = /^\d+$/.test(lowerBound[3] ?? "") ? Number(lowerBound[3]) : 0;
+    return major > 15 || (major === 15 && minor >= 1);
+  });
+}
+
 async function updateOutboxDatabaseProvider(
   targetDir: string,
   config: ResolvedBeignetConfig,
@@ -1923,6 +1965,95 @@ async function updateOutboxDatabaseProvider(
   return true;
 }
 
+async function updateOutboxDrainProvider(
+  targetDir: string,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean },
+): Promise<boolean> {
+  if (!(await projectSupportsNextAfter(targetDir))) return false;
+
+  const file = providersFilePath(config);
+  const filePath = path.join(targetDir, file);
+  const original = await readOptionalFile(filePath);
+  if (original === undefined) {
+    throw new Error(
+      `Could not find the generated providers file ${file}. Register the outbox drain trigger manually, or restore the generated providers file before running make outbox.`,
+    );
+  }
+
+  let next = addNamedImport(
+    original,
+    "createObservedUnitOfWork",
+    "@beignet/core/ports",
+  );
+  next = addNamedImport(next, "createProvider", "@beignet/core/providers");
+  next = addNamedImport(next, "createNextOutboxDrainTrigger", "@beignet/next");
+  next = addNamedImport(next, "after", "next/server");
+  next = addNamedTypeImport(
+    next,
+    "AppContext",
+    aliasModule(config.paths.appContext),
+  );
+  next = addNamedTypeImport(next, "AppPorts", aliasModule(config.paths.ports));
+  next = addNamedTypeImport(
+    next,
+    "AppServiceContextInput",
+    aliasModule(path.join(path.dirname(config.paths.server), "context.ts")),
+  );
+
+  const providerName = "outboxDrainProvider";
+  if (!new RegExp(`\\bconst\\s+${providerName}\\b`).test(next)) {
+    const outboxModule = aliasModule(config.paths.outbox);
+    const providerDefinition = `const ${providerName} = createProvider<
+\tPick<AppPorts, "uow">,
+\tAppContext,
+\tAppServiceContextInput
+>()({
+\tname: "outbox-drain-trigger",
+\tsetup({ ports, createServiceContext }): { ports: Pick<AppPorts, "uow"> } {
+\t\tconst triggerOutboxDrain: () => void = createNextOutboxDrainTrigger({
+\t\t\tdefer: after,
+\t\t\tcreateContext: () => createServiceContext(undefined),
+\t\t\tregistry: async () => (await import("${outboxModule}")).outboxRegistry,
+\t\t\tbatchSize: 100,
+\t\t});
+
+\t\treturn {
+\t\t\tports: {
+\t\t\t\tuow: createObservedUnitOfWork({
+\t\t\t\t\tunitOfWork: ports.uow,
+\t\t\t\t\tafterCommit: triggerOutboxDrain,
+\t\t\t\t}),
+\t\t\t},
+\t\t};
+\t},
+});
+`;
+    const withProvider = next.replace(
+      /\nexport const providers = \[/,
+      `\n${providerDefinition}\nexport const providers = [`,
+    );
+    if (withProvider === next) {
+      throw new Error(
+        `Could not find the exported providers array in ${file}. Register outboxDrainProvider manually, or restore the generated providers file before running make outbox.`,
+      );
+    }
+    next = withProvider;
+  }
+
+  const appended = appendToNamedArray(next, "providers", providerName);
+  if (appended.kind === "missing") {
+    throw new Error(
+      `Could not find the exported providers array in ${file}. Register outboxDrainProvider manually, or restore the generated providers file before running make outbox.`,
+    );
+  }
+  if (appended.kind === "updated") next = appended.source;
+
+  if (next === original) return false;
+  if (!options.dryRun) await writeFile(filePath, next);
+  return true;
+}
+
 async function updateOutboxRepositoriesReturnType(
   targetDir: string,
   config: ResolvedBeignetConfig,
@@ -2068,6 +2199,12 @@ export async function makeUpload(
     ? resolveConfig(options.config)
     : await loadBeignetConfig(targetDir);
 
+  assertNextFramework(
+    config,
+    "beignet make upload",
+    "a Next.js App Router upload handler",
+  );
+
   await assertFeatureArtifactApp(targetDir, config, "upload");
   if (options.ui) {
     await assertUploadUiApp(targetDir, config);
@@ -2168,6 +2305,12 @@ export async function makeOutbox(
     ? resolveConfig(options.config)
     : await loadBeignetConfig(targetDir);
 
+  assertNextFramework(
+    config,
+    "beignet make outbox",
+    "a Next.js App Router recovery drain handler",
+  );
+
   await assertServerRuntimeApp(targetDir, config, "outbox");
   await updateOutboxPortWiring(targetDir, config, { dryRun: true });
 
@@ -2219,6 +2362,9 @@ export async function makeOutbox(
       config.paths.ports,
       config.paths.portWiring,
       path.join(infrastructureDir(config), "db/provider.ts"),
+      ...((await projectSupportsNextAfter(targetDir))
+        ? [providersFilePath(config)]
+        : []),
       drizzleRepositoriesPath(config),
       outboxDrizzleSchemaFilePath(config),
       drizzleSchemaIndexPath(config),
@@ -3672,6 +3818,92 @@ async function applyOutboxRegistryUpdate(
   }
 }
 
+function inngestRegistryPath(config: ResolvedBeignetConfig): string {
+  return path.posix.join(path.posix.dirname(config.paths.server), "inngest.ts");
+}
+
+async function appUsesInngestJobs(targetDir: string): Promise<boolean> {
+  const source = await readOptionalFile(path.join(targetDir, "package.json"));
+  if (source === undefined) return false;
+
+  try {
+    const packageJson = JSON.parse(source) as PackageJsonLike;
+    return Boolean(
+      packageJson.dependencies?.["@beignet/provider-jobs-inngest"] ??
+        packageJson.devDependencies?.["@beignet/provider-jobs-inngest"],
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function updateInngestJobRegistry(
+  targetDir: string,
+  names: JobNames,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean },
+): Promise<WriteGeneratedFileResult | undefined> {
+  if (!(await appUsesInngestJobs(targetDir))) return undefined;
+
+  const registryPath = inngestRegistryPath(config);
+  const destination = path.join(targetDir, registryPath);
+  const existing = await readOptionalFile(destination);
+  if (existing === undefined) {
+    throw new Error(
+      `@beignet/provider-jobs-inngest is installed, but ${registryPath} is missing. Run \`beignet provider add jobs-inngest\` to create the execution registry before generating jobs.`,
+    );
+  }
+
+  const featureIndexPath = path.join(
+    featureArtifactDir(names, "jobs", config),
+    "index.ts",
+  );
+  const registryName = `${names.featureSingularCamel}Jobs`;
+  const importLine = `import { ${registryName} } from "${aliasModule(featureIndexPath)}";`;
+  let next = existing;
+  if (!next.includes(importLine)) next = insertAfterImports(next, importLine);
+
+  const registry = arrayInitializerInfo(next, "inngestJobs");
+  if (!registry) {
+    throw new Error(
+      `Could not find \`export const inngestJobs = [...]\` in ${registryPath}. Restore the generated registry or register ${registryName} manually.`,
+    );
+  }
+  if (!identifiersFromArrayExpression(registry.text).has(registryName)) {
+    const updatedArray = appendToArrayExpression(registry.text, [
+      `...${registryName}`,
+    ]);
+    next = `${next.slice(0, registry.start)}${updatedArray}${next.slice(
+      registry.end,
+    )}`;
+  }
+
+  if (next === existing) return "skipped";
+  if (!options.dryRun) await writeFile(destination, next);
+  return "updated";
+}
+
+async function applyInngestJobRegistryUpdate(
+  result: MakeJobResult,
+  targetDir: string,
+  names: JobNames,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean },
+): Promise<void> {
+  const registryResult = await updateInngestJobRegistry(
+    targetDir,
+    names,
+    config,
+    options,
+  );
+  if (registryResult === undefined) return;
+
+  const registryPath = inngestRegistryPath(config);
+  if (registryResult === "updated") result.updatedFiles.push(registryPath);
+  if (registryResult === "skipped") result.skippedFiles.push(registryPath);
+  if (!result.files.includes(registryPath)) result.files.push(registryPath);
+}
+
 function schemasFile(
   names: ResourceNames,
   mode: ResourceGenerationMode,
@@ -5003,8 +5235,6 @@ export const ${names.jobExportName} = defineJob("${names.jobName}", {
 \tpayload: ${names.payloadSchemaName},
 \tretry: retry.exponential({
 \t\tattempts: 3,
-\t\tinitialDelay: "1s",
-\t\tmaxDelay: "1m",
 \t}),
 \tasync handle({ payload, ctx }) {
 \t\tctx.ports.logger.info("Job handled", {

package/src/mcp.ts

@@ -2,7 +2,11 @@ import path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 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 { explainApp, explainTargetKinds } from "./explain.js";
 import { applyDoctorFixes, inspectApp } from "./inspect.js";
 import { lintApp } from "./lint.js";
 import {
@@ -68,6 +72,8 @@ const makeArtifactChoices = [
   "use-case",
 ] as const;
 
+const defaultMcpCheckTimeoutMs = 10 * 60 * 1_000;
+
 type MakeArtifact = (typeof makeArtifactChoices)[number];
 
 const makeInputSchema = {
@@ -325,7 +331,7 @@ async function runProviderAddTool(
 }
 
 /**
- * Build the Beignet MCP server with routes, doctor, lint, and make tools.
+ * Build the Beignet MCP server with app-map, validation, and generator tools.
  * Every tool resolves against the app directory captured at launch.
  */
 export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
@@ -335,6 +341,106 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
     version: options.version,
   });
 
+  server.registerTool(
+    "app_map",
+    {
+      description:
+        "Return a deterministic graph of this Beignet app: features, contracts, routes, use cases, authorization, workflows, ports, providers, OpenAPI, tests, dependency edges, and validation findings. Project by feature or node kind to keep agent context focused.",
+      inputSchema: {
+        feature: z
+          .string()
+          .optional()
+          .describe("Project one feature and its direct relationships."),
+        kinds: z
+          .array(z.enum(appMapNodeKinds))
+          .optional()
+          .describe("Include only these app-map node kinds."),
+        includeDiagnostics: z
+          .boolean()
+          .optional()
+          .describe("Include doctor and lint findings. Defaults to true."),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async (input) =>
+      safeToolResult(async () => {
+        const result = await mapApp({ cwd, strict: true });
+        return jsonResult(
+          projectAppMap(result, {
+            feature: input.feature,
+            kinds: input.kinds,
+            includeDiagnostics: input.includeDiagnostics,
+          }),
+        );
+      }),
+  );
+
+  server.registerTool(
+    "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.",
+      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.",
+          ),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async (input) =>
+      safeToolResult(async () =>
+        jsonResult(
+          await explainApp({ cwd, kind: input.kind, target: input.target }),
+        ),
+      ),
+  );
+
+  server.registerTool(
+    "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.",
+      inputSchema: {
+        preflight: z
+          .boolean()
+          .optional()
+          .describe(
+            "Include the environment preflight check before app package scripts. Defaults to false.",
+          ),
+        timeoutMs: z
+          .number()
+          .int()
+          .min(1_000)
+          .max(60 * 60 * 1_000)
+          .optional()
+          .describe(
+            "Maximum duration for each app package script in milliseconds. Defaults to 600000 (10 minutes).",
+          ),
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (input, extra) =>
+      safeToolResult(async () =>
+        jsonResult(
+          await checkApp({
+            cwd,
+            preflight: input.preflight ?? false,
+            scriptTimeoutMs: input.timeoutMs ?? defaultMcpCheckTimeoutMs,
+            signal: extra.signal,
+          }),
+        ),
+      ),
+  );
+
   server.registerTool(
     "routes",
     {

package/src/preflight.ts

@@ -245,6 +245,20 @@ export async function runPreflight(
     }
   }
 
+  const inngestDev = env.INNGEST_DEV?.trim().toLowerCase();
+  if (
+    env.NODE_ENV === "production" &&
+    inngestDev !== undefined &&
+    !["", "0", "false"].includes(inngestDev)
+  ) {
+    findings.push({
+      severity: "error",
+      code: "BEIGNET_PREFLIGHT_INNGEST_DEV_IN_PRODUCTION",
+      message:
+        "INNGEST_DEV enables the local Inngest dev server and must be disabled in production.",
+    });
+  }
+
   const exampleSource = await readFileIfExists(
     path.join(options.cwd, ".env.example"),
   );