@beignet/cli 0.0.40 → 0.0.41

package/src/provider-add.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import {
   type ProviderPresetName,
@@ -10,6 +10,7 @@ import {
   loadBeignetConfig,
   type ResolvedBeignetConfig,
 } from "./config.js";
+import { aliasModule } from "./make/shared.js";
 import {
   appendToArrayExpression,
   appendToNamedArray,
@@ -64,6 +65,7 @@ type ProviderPreset = {
   docs: string;
   nextSteps: string[];
   conflictingProviderEntries?: string[];
+  additionalImports?: string[];
 };
 
 type PlannedFile = {
@@ -169,7 +171,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     displayName: "Inngest jobs",
     importName: "createInngestJobsProvider",
     importFrom: "@beignet/provider-jobs-inngest",
-    providerEntry: "createInngestJobsProvider()",
+    providerEntry: "createInngestJobsProvider({ client: inngest })",
     dependencies: (packageJson) => ({
       "@beignet/provider-jobs-inngest": beignetDependencyVersion(packageJson),
       inngest: externalVersions.inngest,
@@ -180,11 +182,20 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       importName: "JobDispatcherPort",
       importFrom: "@beignet/core/ports",
     },
-    envVars: ["INNGEST_APP_NAME", "INNGEST_EVENT_KEY"],
+    envVars: [
+      "INNGEST_APP_NAME",
+      "INNGEST_DEV",
+      "INNGEST_EVENT_KEY",
+      "INNGEST_SIGNING_KEY",
+      "INNGEST_SIGNING_KEY_FALLBACK",
+    ],
     envExample: [
       "# Inngest jobs provider",
       "INNGEST_APP_NAME=beignet-app",
+      "INNGEST_DEV=1",
       "# INNGEST_EVENT_KEY=",
+      "# INNGEST_SIGNING_KEY=",
+      "# INNGEST_SIGNING_KEY_FALLBACK=",
       "",
     ].join("\n"),
     docs: [
@@ -192,16 +203,16 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-jobs-inngest`",
       "- Peer dependency: `inngest`",
-      "- The preset wires `createInngestJobsProvider()` in `server/providers.ts` and defers `jobs` in `infra/port-wiring.ts`.",
+      "- The preset creates one shared Inngest client, a central Beignet job registry, and wires that client into `server/providers.ts`.",
       "- Define jobs with `defineJob(...)` and dispatch them through `ctx.ports.jobs.dispatch(...)`.",
-      "- Execution needs an Inngest serve route built from `createInngestJobFunction(...)` and `serve(...)`. See the jobs docs page.",
+      "- Next.js apps receive `app/api/inngest/route.ts`; other runtimes receive `createAppInngestFunctions(...)` so their host can bind an app-owned service context.",
       "- Use `ctx.ports.inngest` only as an escape hatch for Inngest-specific workflow APIs; prefer `ctx.ports.jobs.dispatch(...)` for Beignet jobs.",
       "",
     ].join("\n"),
     nextSteps: [
       "Run your package manager install command.",
-      "Set INNGEST_APP_NAME and, for Inngest cloud, INNGEST_EVENT_KEY in .env.local or your deployment environment.",
-      "Expose an Inngest serve route with createInngestJobFunction(...) so dispatched jobs execute. See the jobs docs page.",
+      "Use INNGEST_DEV=1 only with the local dev server. Set INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY in production.",
+      "For non-Next runtimes, call createAppInngestFunctions(...) after creating the app server, then mount the result with Inngest's host adapter.",
       "Run beignet provider audit and beignet doctor --strict.",
     ],
     conflictingProviderEntries: ["createBullMQJobsProvider"],
@@ -764,7 +775,12 @@ export async function addProviderPreset(
   const config = await loadBeignetConfig(targetDir);
   const readSource: ProviderSourceReader = (filePath) =>
     readOptionalAppFile(targetDir, filePath);
-  const filesToPlan = await providerPresetFiles(preset, config, readSource);
+  const filesToPlan = await providerPresetFiles(
+    preset,
+    config,
+    readSource,
+    targetDir,
+  );
   const plannedFiles = await planFiles(filesToPlan, readSource);
 
   if (!options.dryRun) {
@@ -802,7 +818,12 @@ export async function planProviderPresetsForCreate(options: {
 
   for (const name of options.names) {
     const preset = presets[name];
-    const filesToPlan = await providerPresetFiles(preset, config, readSource);
+    const filesToPlan = await providerPresetFiles(
+      preset,
+      config,
+      readSource,
+      options.targetDir,
+    );
     const plannedFiles = await planFiles(filesToPlan, readSource);
 
     for (const file of plannedFiles) {
@@ -827,6 +848,7 @@ async function providerPresetFiles(
   preset: ProviderPreset,
   config: ResolvedBeignetConfig,
   readSource: ProviderSourceReader,
+  targetDir: string,
 ): Promise<ProviderPlanFile[]> {
   const packageJsonPath = "package.json";
   const providersPath = serverProvidersPath(config);
@@ -840,6 +862,20 @@ async function providerPresetFiles(
     await readSource(".env.example"),
     preset,
   );
+  const effectivePreset =
+    preset.name === "jobs-inngest"
+      ? {
+          ...preset,
+          additionalImports: [
+            `import { inngest } from "${aliasModule(
+              path.posix.join(
+                directoryPath(path.posix.dirname(config.paths.portWiring)),
+                "inngest.ts",
+              ),
+            )}";`,
+          ],
+        }
+      : preset;
   const files = [
     {
       path: packageJsonPath,
@@ -849,7 +885,7 @@ async function providerPresetFiles(
       path: providersPath,
       content: updateServerProviders(
         await readRequiredSource(readSource, providersPath),
-        preset,
+        effectivePreset,
       ),
     },
     {
@@ -879,9 +915,167 @@ async function providerPresetFiles(
     });
   }
 
+  if (preset.name === "jobs-inngest") {
+    files.push(
+      ...(await inngestProviderFiles({ targetDir, config, readSource })),
+    );
+  }
+
+  return files;
+}
+
+async function inngestProviderFiles(options: {
+  targetDir: string;
+  config: ResolvedBeignetConfig;
+  readSource: ProviderSourceReader;
+}): Promise<ProviderPlanFile[]> {
+  const infrastructurePath = directoryPath(
+    path.posix.dirname(options.config.paths.portWiring),
+  );
+  const serverPath = directoryPath(
+    path.posix.dirname(options.config.paths.server),
+  );
+  const clientPath = path.posix.join(infrastructurePath, "inngest.ts");
+  const registryPath = path.posix.join(serverPath, "inngest.ts");
+  const jobRegistries = await discoverJobRegistries(
+    options.targetDir,
+    options.config,
+  );
+  const imports = jobRegistries
+    .map(({ name, file }) => `import { ${name} } from "${aliasModule(file)}";`)
+    .join("\n");
+  const entries = jobRegistries.map(({ name }) => `\t...${name},`).join("\n");
+
+  const files: ProviderPlanFile[] = [];
+  if ((await options.readSource(clientPath)) === undefined) {
+    files.push({
+      path: clientPath,
+      content: `import { Inngest } from "inngest";
+
+/** Shared by the Beignet jobs provider and the Inngest serve endpoint. */
+export const inngest = new Inngest({
+\tid: process.env.INNGEST_APP_NAME ?? "beignet-app",
+});
+`,
+    });
+  }
+  if ((await options.readSource(registryPath)) === undefined) {
+    files.push({
+      path: registryPath,
+      content:
+        options.config.framework === "next"
+          ? `import { createServiceActor } from "@beignet/core/ports";
+import { createInngestJobFunctions } from "@beignet/provider-jobs-inngest";
+import type { AppContext } from "${aliasModule(options.config.paths.appContext)}";
+import { inngest } from "${aliasModule(clientPath)}";
+${imports ? `${imports}\n` : ""}import { getServer } from "${aliasModule(options.config.paths.server)}";
+
+/** Central registry updated by \`beignet make job\`. */
+export const inngestJobs = [
+${entries}
+] as const;
+
+export const inngestFunctions = createInngestJobFunctions<AppContext>({
+\tclient: inngest,
+\tjobs: inngestJobs,
+\tctx: async () => {
+\t\tconst server = await getServer();
+\t\treturn server.createServiceContext({
+\t\t\tactor: createServiceActor("beignet-inngest"),
+\t\t});
+\t},
+\tinstrumentation: async () => (await getServer()).ports,
+\terrorReporter: async () => (await getServer()).ports.errorReporter,
+});
+`
+          : `import {
+\tcreateInngestJobFunctions,
+\ttype CreateInngestJobFunctionsOptions,
+} from "@beignet/provider-jobs-inngest";
+import type { AppContext } from "${aliasModule(options.config.paths.appContext)}";
+import { inngest } from "${aliasModule(clientPath)}";
+${imports ? `${imports}\n` : ""}
+/** Central registry updated by \`beignet make job\`. */
+export const inngestJobs = [
+${entries}
+] as const;
+
+export type AppInngestFunctionOptions = Omit<
+\tCreateInngestJobFunctionsOptions<AppContext>,
+\t"client" | "jobs" | "ctx"
+> & {
+\tctx: NonNullable<CreateInngestJobFunctionsOptions<AppContext>["ctx"]>;
+};
+
+/** Bind the app-owned runtime context when mounting an Inngest host adapter. */
+export function createAppInngestFunctions(
+\toptions: AppInngestFunctionOptions,
+) {
+\treturn createInngestJobFunctions<AppContext>({
+\t\t...options,
+\t\tclient: inngest,
+\t\tjobs: inngestJobs,
+\t});
+}
+`,
+    });
+  }
+  if (options.config.framework === "next") {
+    const routePath = path.posix.join(
+      directoryPath(options.config.paths.routes),
+      "inngest/route.ts",
+    );
+    if ((await options.readSource(routePath)) === undefined) {
+      files.push({
+        path: routePath,
+        content: `import { serve } from "inngest/next";
+import { inngest } from "${aliasModule(clientPath)}";
+import { inngestFunctions } from "${aliasModule(registryPath)}";
+
+export const { GET, POST, PUT } = serve({
+\tclient: inngest,
+\tfunctions: inngestFunctions,
+});
+`,
+      });
+    }
+  }
+
   return files;
 }
 
+async function discoverJobRegistries(
+  targetDir: string,
+  config: ResolvedBeignetConfig,
+): Promise<Array<{ name: string; file: string }>> {
+  const featuresDir = path.join(
+    targetDir,
+    directoryPath(config.paths.features),
+  );
+  let entries: string[];
+  try {
+    entries = await readdir(featuresDir, { recursive: true, encoding: "utf8" });
+  } catch {
+    return [];
+  }
+
+  const registries: Array<{ name: string; file: string }> = [];
+  for (const entry of entries) {
+    const normalized = entry.replaceAll(path.sep, "/");
+    if (!normalized.endsWith("/jobs/index.ts")) continue;
+    const absolutePath = path.join(featuresDir, entry);
+    const source = await readFile(absolutePath, "utf8");
+    const match = source.match(/export const\s+([A-Za-z_$][\w$]*Jobs)\s*=/);
+    if (!match?.[1]) continue;
+    registries.push({
+      name: match[1],
+      file: path.posix.join(directoryPath(config.paths.features), normalized),
+    });
+  }
+
+  return registries.sort((left, right) => left.file.localeCompare(right.file));
+}
+
 function providerPresetResult(
   preset: ProviderPreset,
   targetDir: string,
@@ -982,9 +1176,14 @@ function updatePackageJson(
 function updateServerProviders(source: string, preset: ProviderPreset): string {
   assertNoConflictingProviders(source, preset);
 
+  let next = source;
+  for (const importLine of preset.additionalImports ?? []) {
+    if (!next.includes(importLine)) next = insertAfterImports(next, importLine);
+  }
+
   const importLine = `import { ${preset.importName} } from "${preset.importFrom}";`;
   const result = appendToNamedArray(
-    source,
+    next,
     "providers",
     preset.providerEntry,
     hasNamedImport(source, preset.importName, preset.importFrom)
@@ -998,7 +1197,7 @@ function updateServerProviders(source: string, preset: ProviderPreset): string {
     );
   }
 
-  return result.kind === "updated" ? result.source : source;
+  return result.kind === "updated" ? result.source : next;
 }
 
 function assertNoConflictingProviders(

package/src/provider-audit.ts

@@ -59,6 +59,12 @@ export type ProviderRegistrationStatus =
   | "optional-missing"
   | "not-required";
 
+export type ProviderRegistrationSource = {
+  file: string;
+  line: number;
+  column: number;
+};
+
 export type ProviderMetadataAudit =
   | {
       status: "valid";
@@ -102,6 +108,7 @@ export type ProviderAuditEntry = {
   declared: boolean;
   metadata: ProviderMetadataAudit;
   registration: ProviderRegistrationStatus;
+  registrationSources: ProviderRegistrationSource[];
   requiredEnv: ProviderRequirementAudit;
   requiredTables: ProviderRequirementAudit;
   appPorts: ProviderAppPortsAudit;
@@ -138,12 +145,15 @@ export async function auditProviders(
   const packageJson = await readPackageJson(targetDir, files);
   const packageNames = await providerAuditPackageNames(targetDir, packageJson);
   const sourceCache = new Map<string, string>();
-  const providerEntries = await readProviderListEntries(
+  const providerEntryRecords = await readProviderListEntryRecords(
     targetDir,
     files,
     config,
     sourceCache,
   );
+  const providerEntries = providerEntryRecords.flatMap(
+    (entry) => entry.searchableText,
+  );
   const configFiles = providerOperationalConfigFiles(files, config);
   const portsSource = files.includes(config.paths.ports)
     ? await readCachedSource(targetDir, config.paths.ports, sourceCache)
@@ -191,6 +201,7 @@ export async function auditProviders(
         sourceCache,
         portsSource,
         providerEntries,
+        providerEntryRecords,
         sourceFile: source.file,
         packageJson,
         rule: providerDoctorRuleFromMetadata(packageName, parsed.metadata),
@@ -356,20 +367,47 @@ export async function readProviderListEntries(
   config: ResolvedBeignetConfig,
   sourceCache: Map<string, string>,
 ): Promise<string[]> {
+  const records = await readProviderListEntryRecords(
+    targetDir,
+    files,
+    config,
+    sourceCache,
+  );
+  return records.flatMap((entry) => entry.searchableText);
+}
+
+type ProviderListEntryRecord = {
+  searchableText: string[];
+  source: ProviderRegistrationSource;
+};
+
+async function readProviderListEntryRecords(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  sourceCache: Map<string, string>,
+): Promise<ProviderListEntryRecord[]> {
   const providerFiles = serverProviderFiles(files, config);
-  const providerSource = (
-    await Promise.all(
-      providerFiles.map((file) =>
-        readCachedSource(targetDir, file, sourceCache),
-      ),
-    )
-  ).join("\n");
-  const providerListSource = extractProviderListSource(providerSource);
-  const entries =
-    providerListSource === undefined
-      ? []
-      : providerListEntries(providerListSource);
-  return expandProviderEntryIdentifiers(entries, providerSource);
+  const records: ProviderListEntryRecord[] = [];
+  for (const file of providerFiles) {
+    const providerSource = await readCachedSource(targetDir, file, sourceCache);
+    for (const list of extractProviderLists(providerSource)) {
+      for (const entry of providerListEntries(list.source)) {
+        records.push({
+          searchableText: expandProviderEntryIdentifiers(
+            [entry.source],
+            providerSource,
+          ),
+          source: sourceLocation(
+            file,
+            providerSource,
+            list.start + entry.start,
+          ),
+        });
+      }
+    }
+  }
+  return records;
 }
 
 /**
@@ -1128,6 +1166,7 @@ async function providerAuditEntryForRule(options: {
   sourceCache: Map<string, string>;
   portsSource: string;
   providerEntries: string[];
+  providerEntryRecords: ProviderListEntryRecord[];
   sourceFile: string;
   packageJson: ProviderPackageJson | undefined;
   rule: ProviderDoctorRule;
@@ -1201,6 +1240,9 @@ async function providerAuditEntryForRule(options: {
     requiredTables,
     appPorts,
   });
+  const registrationTokens =
+    options.rule.variants?.flatMap((variant) => variant.tokens) ??
+    options.rule.tokens;
 
   return {
     packageName: options.rule.packageName,
@@ -1214,6 +1256,13 @@ async function providerAuditEntryForRule(options: {
       issues: [],
     },
     registration,
+    registrationSources:
+      registration === "registered"
+        ? registrationSourcesForTokens(
+            registrationTokens,
+            options.providerEntryRecords,
+          )
+        : [],
     requiredEnv,
     requiredTables,
     appPorts,
@@ -1294,6 +1343,7 @@ function providerAuditEntryForMissingMetadata(
     declared: installedPackageNames(packageJson).has(packageName),
     metadata: { status: "missing", issues: [] },
     registration: "not-required",
+    registrationSources: [],
     requiredEnv: emptyRequirement(),
     requiredTables: emptyRequirement(),
     appPorts: emptyAppPorts(),
@@ -1319,6 +1369,7 @@ function providerAuditEntryForInvalidMetadata(
       issues: [...issues],
     },
     registration: "not-required",
+    registrationSources: [],
     requiredEnv: emptyRequirement(),
     requiredTables: emptyRequirement(),
     appPorts: emptyAppPorts(),
@@ -1345,6 +1396,28 @@ function registrationAudit(
   return "not-required";
 }
 
+function registrationSourcesForTokens(
+  tokens: readonly string[],
+  entries: readonly ProviderListEntryRecord[],
+): ProviderRegistrationSource[] {
+  const sources = entries
+    .filter((entry) =>
+      tokens.some((token) =>
+        entry.searchableText.some((text) => text.includes(token)),
+      ),
+    )
+    .map((entry) => entry.source);
+  return sources.filter(
+    (source, index) =>
+      sources.findIndex(
+        (candidate) =>
+          candidate.file === source.file &&
+          candidate.line === source.line &&
+          candidate.column === source.column,
+      ) === index,
+  );
+}
+
 function variantRegistrationAudit(
   variants: readonly ProviderDoctorVariantRule[],
   detectedVariants: readonly ProviderDoctorVariantRule[],
@@ -1572,18 +1645,25 @@ export function serverProviderFiles(
   return candidates.filter((file) => files.includes(file));
 }
 
-function extractProviderListSource(source: string): string | undefined {
+function extractProviderLists(
+  source: string,
+): { source: string; start: number }[] {
   const listMatches = [
     ...source.matchAll(/\bproviders\s*=\s*\[([\s\S]*?)\]\s*(?:;|as const)/g),
     ...source.matchAll(/\bproviders\s*:\s*\[([\s\S]*?)\]/g),
-  ];
-  if (listMatches.length === 0) return undefined;
-  return listMatches.map((match) => match[1]).join("\n");
+  ].sort((left, right) => (left.index ?? 0) - (right.index ?? 0));
+  return listMatches.map((match) => ({
+    source: match[1] ?? "",
+    start: (match.index ?? 0) + match[0].indexOf("[") + 1,
+  }));
 }
 
-function providerListEntries(source: string): string[] {
-  const entries: string[] = [];
+function providerListEntries(
+  source: string,
+): { source: string; start: number }[] {
+  const entries: { source: string; start: number }[] = [];
   let current = "";
+  let currentStart: number | undefined;
   let depth = 0;
   let quote: '"' | "'" | "`" | undefined;
   let escaped = false;
@@ -1611,6 +1691,9 @@ function providerListEntries(source: string): string[] {
     }
 
     if (quote) {
+      if (currentStart === undefined && !/\s/.test(char)) {
+        currentStart = index;
+      }
       current += char;
       if (escaped) {
         escaped = false;
@@ -1640,10 +1723,15 @@ function providerListEntries(source: string): string[] {
 
     if (char === '"' || char === "'" || char === "`") {
       quote = char;
+      currentStart ??= index;
       current += char;
       continue;
     }
 
+    if (currentStart === undefined && !/\s/.test(char)) {
+      currentStart = index;
+    }
+
     if (char === "(" || char === "[" || char === "{") {
       depth += 1;
     } else if (char === ")" || char === "]" || char === "}") {
@@ -1652,8 +1740,9 @@ function providerListEntries(source: string): string[] {
 
     if (char === "," && depth === 0) {
       const entry = current.trim();
-      if (entry) entries.push(entry);
+      if (entry) entries.push({ source: entry, start: currentStart ?? index });
       current = "";
+      currentStart = undefined;
       continue;
     }
 
@@ -1661,10 +1750,26 @@ function providerListEntries(source: string): string[] {
   }
 
   const entry = current.trim();
-  if (entry) entries.push(entry);
+  if (entry) {
+    entries.push({ source: entry, start: currentStart ?? source.length });
+  }
   return entries;
 }
 
+function sourceLocation(
+  file: string,
+  source: string,
+  index: number,
+): ProviderRegistrationSource {
+  const prefix = source.slice(0, index);
+  const lastNewline = prefix.lastIndexOf("\n");
+  return {
+    file,
+    line: prefix.split("\n").length,
+    column: index - lastNewline,
+  };
+}
+
 function metadataSourcePath(targetDir: string, file: string): string {
   const targetRelative = normalizePath(path.relative(targetDir, file));
   if (!targetRelative.startsWith("../")) return targetRelative;

package/src/templates/agents.ts

@@ -107,6 +107,10 @@ formatting. The individual commands (\`${lint}\`, \`${cli} lint\`,
 \`${cli} doctor --strict\`, \`${test}\`, \`${typecheck}\`) still work when you
 need one check alone.
 
+Before exploring unfamiliar code, run \`${cli} map\` for the human inventory
+or \`${cli} map --json --feature <name>\` for an evidence-backed graph scoped
+to one feature.
+
 ## Package skills
 
 This app trusts Beignet's package-shipped agent skills through
@@ -142,10 +146,19 @@ skill-loading block.
 ## MCP server
 
 \`.mcp.json\` registers the app-local \`@beignet/cli\` bin at
-\`./node_modules/.bin/beignet mcp\`, which exposes routes/doctor/lint/make/provider_add as
-structured tools named exactly: \`routes\`, \`doctor\`, \`doctor_fix\`,
-\`lint\`, \`make\`, \`provider_add\`. Clients that do not read \`.mcp.json\` can use the same
-command from the app root; use \`${cli} mcp\` only for terminal debugging.
+\`./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
+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
+\`${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.
 `;
 }