@beignet/cli 0.0.40 → 0.0.41

package/src/index.ts

@@ -13,6 +13,7 @@ import {
   type StricliProcess,
   text_en,
 } from "@stricli/core";
+import { type AppMapNodeKind, appMapNodeKinds } from "./app-map-schema.js";
 import {
   type CompletionShell,
   type CreateProviderName,
@@ -36,6 +37,7 @@ import {
 } from "./choices.js";
 // Type-only: the runtime module stays behind the create command's lazy loader.
 import type { CreateSelections } from "./create-prompts.js";
+import type { ExplainTargetKind } from "./explain.js";
 import type { AddProviderPresetResult } from "./provider-add.js";
 import { getCliVersion } from "./version.js";
 
@@ -106,6 +108,13 @@ type RoutesFlags = {
   cwd?: string;
 };
 
+type MapFlags = RoutesFlags & {
+  feature?: string;
+  kind?: readonly AppMapNodeKind[];
+};
+
+type ExplainFlags = RoutesFlags;
+
 type LintFlags = {
   json?: boolean;
   cwd?: string;
@@ -366,6 +375,21 @@ const routesFlagParameters = {
   cwd: cwdFlag,
 } satisfies FlagParametersForType<RoutesFlags, CliContext>;
 
+const mapFlagParameters = {
+  json: jsonFlag,
+  feature: parsedStringFlag(
+    "Project one feature and its direct relationships.",
+  ),
+  kind: {
+    kind: "enum",
+    values: appMapNodeKinds,
+    optional: true,
+    variadic: ",",
+    brief: "Include only these node kinds. Accepts comma-separated values.",
+  },
+  cwd: cwdFlag,
+} satisfies FlagParametersForType<MapFlags, CliContext>;
+
 const lintFlagParameters = {
   json: jsonFlag,
   cwd: cwdFlag,
@@ -585,6 +609,19 @@ const providerPresetPositional = {
   ],
 } as const;
 
+function explainTargetPositional(kind: ExplainTargetKind) {
+  return {
+    kind: "tuple",
+    parameters: [
+      {
+        parse: parseString,
+        placeholder: kind,
+        brief: `${kind[0]?.toUpperCase()}${kind.slice(1)} to explain.`,
+      },
+    ],
+  } as const;
+}
+
 function resolveOutputFormat(flags: {
   json?: boolean;
   format?: OutputFormat;
@@ -829,6 +866,77 @@ const routesCommand = buildCommand<RoutesFlags, [], CliContext>({
   },
 });
 
+const mapCommand = buildCommand<MapFlags, [], CliContext>({
+  docs: {
+    brief: "Map the app's architecture and registered workflows.",
+    fullDescription:
+      "Build a deterministic graph of features, HTTP contracts, routes, use cases, policies, workflows, ports, providers, OpenAPI, tests, dependencies, and doctor findings.",
+  },
+  parameters: {
+    flags: mapFlagParameters,
+  },
+  loader: async () => {
+    const { formatAppMap, mapApp, projectAppMap } = await import(
+      "./app-map.js"
+    );
+
+    return async function runMap(this: CliContext, flags: MapFlags) {
+      const result = projectAppMap(
+        await mapApp({ cwd: flags.cwd, strict: true }),
+        {
+          feature: flags.feature,
+          kinds: flags.kind,
+        },
+      );
+      writeOutput(
+        this,
+        flags.json ? JSON.stringify(result, null, 2) : formatAppMap(result),
+      );
+    };
+  },
+});
+
+function explainCommand(kind: ExplainTargetKind) {
+  return buildCommand<ExplainFlags, [string], CliContext>({
+    docs: {
+      brief: `Explain one mapped Beignet ${kind}.`,
+      fullDescription:
+        "Returns source-backed relationships, conventions, findings, suggested files, and follow-up commands without generating advice or changing the app.",
+    },
+    parameters: {
+      flags: routesFlagParameters,
+      positional: explainTargetPositional(kind),
+    },
+    loader: async () => {
+      const { explainApp, formatExplain } = await import("./explain.js");
+
+      return async function runExplain(
+        this: CliContext,
+        flags: ExplainFlags,
+        target: string,
+      ) {
+        const result = await explainApp({ kind, target, cwd: flags.cwd });
+        writeOutput(
+          this,
+          flags.json ? JSON.stringify(result, null, 2) : formatExplain(result),
+        );
+      };
+    },
+  });
+}
+
+const explainRoutes = buildRouteMap({
+  docs: {
+    brief: "Explain mapped Beignet app concepts with source evidence.",
+  },
+  routes: {
+    diagnostic: explainCommand("diagnostic"),
+    feature: explainCommand("feature"),
+    provider: explainCommand("provider"),
+    route: explainCommand("route"),
+  },
+});
+
 const doctorCommand = buildCommand<DoctorFlags, [], CliContext>({
   docs: {
     brief: "Inspect app wiring and framework conventions.",
@@ -1035,7 +1143,7 @@ const lintCommand = buildCommand<LintFlags, [], CliContext>({
 const mcpCommand = buildCommand<McpFlags, [], CliContext>({
   docs: {
     brief:
-      "Run a Model Context Protocol server exposing this app's routes, doctor, lint, and generators over stdio.",
+      "Run a Model Context Protocol server exposing the app map, validation, and generators over stdio.",
   },
   parameters: {
     flags: {
@@ -2109,7 +2217,7 @@ const makeRoutes = buildRouteMap({
 const rootRoutes = buildRouteMap({
   docs: {
     brief: "Beignet CLI",
-    fullDescription: `Create apps, generate framework files, inspect routes, and check Beignet conventions.
+    fullDescription: `Create apps, generate framework files, map and explain architecture, inspect routes, and check Beignet conventions.
 
 Run npm create beignet@latest (or bun create beignet) to scaffold a new app.`,
   },
@@ -2119,7 +2227,9 @@ Run npm create beignet@latest (or bun create beignet) to scaffold a new app.`,
     create: createCommand,
     db: dbRoutes,
     doctor: doctorCommand,
+    explain: explainRoutes,
     lint: lintCommand,
+    map: mapCommand,
     make: makeRoutes,
     mcp: mcpCommand,
     outbox: outboxRoutes,
@@ -2431,6 +2541,7 @@ ${openStep}
 
 Inspect the app:
   ${cli} routes
+  ${cli} map
   ${cli} check
 
 Generate a feature:

package/src/inspect.ts

@@ -618,7 +618,7 @@ function parseContracts(source: string, file: string): InspectedContract[] {
   for (const exportMatch of source.matchAll(exportRegex)) {
     const block = exportMatch[2];
     const methodMatch =
-      /([A-Za-z_$][\w$]*)(?:\s*\.\s*[A-Za-z_$][\w$]*\([^)]*\))*\s*\.\s*(get|post|put|patch|delete|head|options)\(\s*["']([^"']+)["']\s*\)/.exec(
+      /([A-Za-z_$][\w$]*)(?:\s*\.\s*[A-Za-z_$][\w$]*\([^)]*\))*\s*\.\s*(get|post|put|patch|delete|head|options)\(\s*["']([^"']+)["'](?:\s*,\s*["'][^"']+["'])?\s*\)/.exec(
         block,
       );
     if (methodMatch) {
@@ -1521,6 +1521,7 @@ async function inspectDiagnostics(
       config,
       convention,
     )),
+    ...(await inspectInngestProductionPath(targetDir, files, config)),
     ...(await inspectDatabaseLifecycleDrift(
       targetDir,
       files,
@@ -3095,6 +3096,73 @@ async function inspectProviderRegistrationDrift(
   return diagnostics;
 }
 
+async function inspectInngestProductionPath(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+): Promise<InspectDiagnostic[]> {
+  const packageJson = await readPackageJson(targetDir, files);
+  if (
+    !installedPackageNames(packageJson).has("@beignet/provider-jobs-inngest")
+  ) {
+    return [];
+  }
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const serverDir = directoryPath(path.dirname(config.paths.server));
+  const registryFile = `${serverDir}/inngest.ts`;
+  const routeFile = `${directoryPath(config.paths.routes)}/inngest/route.ts`;
+
+  if (!files.includes(registryFile)) {
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_INNGEST_REGISTRY_MISSING",
+      file: registryFile,
+      message: `@beignet/provider-jobs-inngest is installed, but ${registryFile} is missing. Run beignet provider add jobs-inngest or create a central createInngestJobFunctions(...) registry so dispatched jobs can execute.`,
+    });
+  } else {
+    const registrySource = await readFile(
+      path.join(targetDir, registryFile),
+      "utf8",
+    );
+    const registry = arrayInitializerInfo(registrySource, "inngestJobs");
+    const registeredJobs = registry
+      ? identifiersFromArrayExpression(registry.text)
+      : new Set<string>();
+    const featureRoot = directoryPath(config.paths.features);
+    const jobIndexes = files.filter((file) =>
+      new RegExp(`^${escapeRegExp(featureRoot)}/[^/]+/jobs/index\\.ts$`).test(
+        file,
+      ),
+    );
+    for (const jobIndex of jobIndexes) {
+      const source = await readFile(path.join(targetDir, jobIndex), "utf8");
+      const match = source.match(/export const\s+([A-Za-z_$][\w$]*Jobs)\s*=/);
+      const registryName = match?.[1];
+      if (!registryName || registeredJobs.has(registryName)) {
+        continue;
+      }
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_INNGEST_JOB_REGISTRATION_MISSING",
+        file: registryFile,
+        message: `${jobIndex} exports ${registryName}, but it is not registered in inngestJobs in ${registryFile}. Add ...${registryName} so Inngest can execute the job.`,
+      });
+    }
+  }
+
+  if (config.framework === "next" && !files.includes(routeFile)) {
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_INNGEST_ROUTE_MISSING",
+      file: routeFile,
+      message: `@beignet/provider-jobs-inngest is installed in a Next.js app, but ${routeFile} is missing. Expose the shared Inngest client and function registry with serve(...) so Inngest can discover and invoke jobs.`,
+    });
+  }
+
+  return diagnostics;
+}
+
 function isFeatureUploadDefinition(
   file: string,
   config: ResolvedBeignetConfig,
@@ -4358,7 +4426,7 @@ function callReferencesCentralListenerRegistry(args: {
 
   for (const identifier of args.callIdentifiers) {
     const imported = args.namedImports.get(identifier);
-    if (!imported || imported.importedName !== "listeners") continue;
+    if (imported?.importedName !== "listeners") continue;
 
     const importedFile = sourceFileFromImport(
       imported.sourcePath,

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.ts

@@ -1090,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,
@@ -1116,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;
 }
@@ -3814,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,
@@ -5145,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"),
   );