@beignet/cli 0.0.48 → 0.0.49

package/src/provider-add.ts

@@ -1,5 +1,6 @@
 import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import ts from "typescript";
 import {
   type ProviderPresetName,
   providerPresetChoices,
@@ -164,7 +165,10 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "Add a worker entrypoint that runs createBullMQJobWorker(...) in a worker process; dispatched jobs do not execute without one. See the jobs docs page.",
       "Run beignet provider audit and beignet doctor --strict.",
     ],
-    conflictingProviderEntries: ["createInngestJobsProvider"],
+    conflictingProviderEntries: [
+      "createInngestJobsProvider",
+      "inlineJobsProvider",
+    ],
   },
   "jobs-inngest": {
     name: "jobs-inngest",
@@ -215,7 +219,10 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "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"],
+    conflictingProviderEntries: [
+      "createBullMQJobsProvider",
+      "inlineJobsProvider",
+    ],
   },
   "mail-resend": {
     name: "mail-resend",
@@ -276,7 +283,14 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       importName: "MailerPort",
       importFrom: "@beignet/core/mail",
     },
-    envVars: ["MAIL_HOST", "MAIL_PORT", "MAIL_USER", "MAIL_PASS", "MAIL_FROM"],
+    envVars: [
+      "MAIL_HOST",
+      "MAIL_PORT",
+      "MAIL_USER",
+      "MAIL_PASS",
+      "MAIL_FROM",
+      "MAIL_REQUIRE_TLS",
+    ],
     envExample: [
       "# SMTP mail provider",
       "MAIL_HOST=smtp.example.com",
@@ -284,6 +298,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "MAIL_USER=dev-placeholder-change-me",
       "MAIL_PASS=dev-placeholder-change-me",
       "MAIL_FROM=Beignet App <noreply@example.com>",
+      "MAIL_REQUIRE_TLS=true",
       "",
     ].join("\n"),
     docs: [
@@ -293,12 +308,13 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "- Peer dependency: `nodemailer`",
       "- The preset wires `createSmtpMailProvider()` in `server/providers.ts` and defers `mailer` in `infra/port-wiring.ts`.",
       "- `.env.example` ships dev placeholders so the app boots; set real `MAIL_*` values before sending mail.",
+      "- Encrypted transport is required by default: port 465 uses implicit TLS and other ports must negotiate STARTTLS.",
       "- Use `ctx.ports.mailer` in app code; `ctx.ports.smtp` is available as an escape hatch.",
       "",
     ].join("\n"),
     nextSteps: [
       "Run your package manager install command.",
-      "Set MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASS, and MAIL_FROM in .env.local or your deployment environment.",
+      "Set MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASS, and MAIL_FROM in .env.local or your deployment environment; keep MAIL_REQUIRE_TLS=true outside trusted local capture services.",
       "Run beignet provider audit and beignet doctor --strict.",
     ],
     conflictingProviderEntries: [
@@ -561,6 +577,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     dependencies: (packageJson) => ({
       "@beignet/provider-storage-s3": beignetDependencyVersion(packageJson),
       "@aws-sdk/client-s3": externalVersions.awsSdkS3,
+      "@aws-sdk/lib-storage": externalVersions.awsSdkLibStorage,
       "@aws-sdk/s3-request-presigner": externalVersions.awsSdkS3,
     }),
     appPort: {
@@ -601,7 +618,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "## S3-compatible storage",
       "",
       "- Package: `@beignet/provider-storage-s3`",
-      "- Peer dependencies: `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`",
+      "- Peer dependencies: `@aws-sdk/client-s3`, `@aws-sdk/lib-storage`, and `@aws-sdk/s3-request-presigner`",
       "- The preset wires `createS3StorageProvider()` in `server/providers.ts` and defers `storage` in `infra/port-wiring.ts`.",
       "- Set `STORAGE_S3_BUCKET` before booting the app; set endpoint and credentials when using an S3-compatible host outside AWS defaults.",
       "- Use `ctx.ports.storage` in app code; `ctx.ports.s3Storage` is available as an escape hatch.",
@@ -1179,9 +1196,13 @@ function updatePackageJson(
 }
 
 function updateServerProviders(source: string, preset: ProviderPreset): string {
-  assertNoConflictingProviders(source, preset);
+  const withoutGeneratedFallback =
+    preset.appPort.key === "jobs"
+      ? removeGeneratedInlineJobsProvider(source)
+      : source;
+  assertNoConflictingProviders(withoutGeneratedFallback, preset);
 
-  let next = source;
+  let next = withoutGeneratedFallback;
   for (const importLine of preset.additionalImports ?? []) {
     if (!next.includes(importLine)) next = insertAfterImports(next, importLine);
   }
@@ -1205,6 +1226,164 @@ function updateServerProviders(source: string, preset: ProviderPreset): string {
   return result.kind === "updated" ? result.source : next;
 }
 
+function removeGeneratedInlineJobsProvider(source: string): string {
+  const marker = "// beignet:generated-inline-jobs-provider";
+  const sourceFile = ts.createSourceFile(
+    "providers.ts",
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const statement = sourceFile.statements.find((candidate) => {
+    if (!ts.isVariableStatement(candidate)) return false;
+    if (candidate.declarationList.declarations.length !== 1) return false;
+    const statementStart = candidate.getStart(sourceFile);
+    const markerStart = source.lastIndexOf(marker, statementStart);
+    if (
+      markerStart < 0 ||
+      source.slice(markerStart + marker.length, statementStart).trim() !== ""
+    ) {
+      return false;
+    }
+    const declaration = candidate.declarationList.declarations.find(
+      (item) =>
+        ts.isIdentifier(item.name) && item.name.text === "inlineJobsProvider",
+    );
+    if (!declaration?.initializer) return false;
+    const text = declaration.initializer.getText(sourceFile);
+    return (
+      /\bcreateProvider\b/.test(text) &&
+      /\bcreateInlineJobDispatcher\b/.test(text) &&
+      /\bname\s*:\s*["']inline-jobs["']/.test(text)
+    );
+  });
+  if (!statement) return source;
+
+  const statementStart = statement.getStart(sourceFile);
+  const markerStart = source.lastIndexOf(marker, statementStart);
+  const removeStart =
+    markerStart >= 0 &&
+    source.slice(markerStart + marker.length, statementStart).trim() === ""
+      ? markerStart
+      : statementStart;
+  let next = `${source.slice(0, removeStart)}${source.slice(statement.end)}`;
+  const registry = arrayInitializerInfo(next, "providers");
+  if (!registry) {
+    throw new Error(
+      "Could not remove the generated inline jobs provider because `export const providers = [...]` is missing.",
+    );
+  }
+  const lines = registry.text.split(/\r?\n/);
+  const entryIndex = lines.findIndex(
+    (line) =>
+      line.trim() === "inlineJobsProvider," ||
+      line.trim() === "inlineJobsProvider",
+  );
+  let nextRegistry: string | undefined;
+  if (entryIndex >= 0) {
+    lines.splice(entryIndex, 1);
+    nextRegistry = lines.join(registry.text.includes("\r\n") ? "\r\n" : "\n");
+  } else if (!registry.text.includes("\n")) {
+    const beforeFollowingEntry = /\binlineJobsProvider\s*,\s*/;
+    const afterPreviousEntry = /,\s*inlineJobsProvider\b/;
+    const onlyEntry = /^\[\s*inlineJobsProvider\s*\]$/;
+    if (onlyEntry.test(registry.text)) nextRegistry = "[]";
+    else if (beforeFollowingEntry.test(registry.text)) {
+      nextRegistry = registry.text.replace(beforeFollowingEntry, "");
+    } else if (afterPreviousEntry.test(registry.text)) {
+      nextRegistry = registry.text.replace(afterPreviousEntry, "");
+    }
+  }
+  if (nextRegistry === undefined) {
+    throw new Error(
+      "Could not remove the generated inline jobs provider from `export const providers = [...]`.",
+    );
+  }
+  next = `${next.slice(0, registry.start)}${nextRegistry}${next.slice(registry.end)}`;
+
+  return removeNamedProviderImport(
+    next,
+    "createInlineJobDispatcher",
+    "@beignet/core/jobs",
+  );
+}
+
+function removeNamedProviderImport(
+  source: string,
+  name: string,
+  moduleName: string,
+): string {
+  const escapedModule = moduleName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(
+    `import \\{([^}]*)\\} from ["']${escapedModule}["'];`,
+  );
+  const match = pattern.exec(source);
+  if (!match) return source;
+  const names = match[1]
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  if (!names.includes(name)) return source;
+  if (hasIdentifierReferenceOutsideImport(source, name, moduleName)) {
+    return source;
+  }
+  const remaining = names.filter((entry) => entry !== name);
+  if (remaining.length === 0) {
+    const lineBreak = source.startsWith("\r\n", match.index + match[0].length)
+      ? "\r\n"
+      : source[match.index + match[0].length] === "\n"
+        ? "\n"
+        : "";
+    return `${source.slice(0, match.index)}${source.slice(match.index + match[0].length + lineBreak.length)}`;
+  }
+  const indent = match[1].match(/\n([\t ]+)/)?.[1] ?? "\t";
+  const replacement = match[1].includes("\n")
+    ? `import {\n${indent}${remaining.join(`,\n${indent}`)},\n} from "${moduleName}";`
+    : `import { ${remaining.join(", ")} } from "${moduleName}";`;
+  return `${source.slice(0, match.index)}${replacement}${source.slice(match.index + match[0].length)}`;
+}
+
+function hasIdentifierReferenceOutsideImport(
+  source: string,
+  name: string,
+  moduleName: string,
+): boolean {
+  const sourceFile = ts.createSourceFile(
+    "providers.ts",
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const importDeclaration = sourceFile.statements.find(
+    (statement): statement is ts.ImportDeclaration =>
+      ts.isImportDeclaration(statement) &&
+      ts.isStringLiteral(statement.moduleSpecifier) &&
+      statement.moduleSpecifier.text === moduleName &&
+      Boolean(
+        statement.importClause?.namedBindings &&
+          ts.isNamedImports(statement.importClause.namedBindings) &&
+          statement.importClause.namedBindings.elements.some(
+            (element) => !element.propertyName && element.name.text === name,
+          ),
+      ),
+  );
+  if (!importDeclaration) return true;
+
+  let referenced = false;
+  const visit = (node: ts.Node): void => {
+    if (node === importDeclaration || referenced) return;
+    if (ts.isIdentifier(node) && node.text === name) {
+      referenced = true;
+      return;
+    }
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(sourceFile, visit);
+  return referenced;
+}
+
 function assertNoConflictingProviders(
   source: string,
   preset: ProviderPreset,

package/src/registry-edits.ts

@@ -308,24 +308,324 @@ export function outboxRegistryValueInfo(
   source: string,
   property: "events" | "jobs",
 ): InitializerInfo | undefined {
-  const call = /\bdefineOutboxRegistry\s*(?:<[^>]*>\s*)?\(/.exec(source);
-  if (!call) return undefined;
+  const match = outboxRegistryPropertyAnalysis(source, property);
+  if (!match?.value || match.indeterminate) return undefined;
+  const start = match.value.getStart(match.sourceFile);
+  return {
+    text: source.slice(start, match.value.end),
+    start,
+    end: match.value.end,
+  };
+}
+
+export type OutboxRegistryEntryState =
+  | "absent"
+  | "empty"
+  | "present"
+  | "indeterminate";
+
+/** Static state of one outbox registry property. */
+export function outboxRegistryEntryState(
+  source: string,
+  property: "events" | "jobs",
+): OutboxRegistryEntryState {
+  const match = outboxRegistryPropertyAnalysis(source, property);
+  if (!match) return "absent";
+  if (match.indeterminate) return "indeterminate";
+  if (!match.value) return "empty";
+  return resolvedRegistryExpressions(match.value, match.sourceFile).length > 0
+    ? "present"
+    : "empty";
+}
 
-  const openBrace = source.indexOf("{", call.index);
-  if (openBrace === -1) return undefined;
+/** Whether a registry property is non-empty or cannot be proven empty. */
+export function outboxRegistryHasEntries(
+  source: string,
+  property: "events" | "jobs",
+): boolean {
+  const state = outboxRegistryEntryState(source, property);
+  return state === "present" || state === "indeterminate";
+}
 
-  const closeBrace = matchingDelimiterIndex(source, openBrace, "{", "}");
-  if (closeBrace === -1) return undefined;
+/** Identifiers referenced by a registry property after resolving local array aliases. */
+export function outboxRegistryIdentifiers(
+  source: string,
+  property: "events" | "jobs",
+): Set<string> {
+  const match = outboxRegistryPropertyAnalysis(source, property);
+  if (!match?.value || match.indeterminate) return new Set();
+
+  const identifiers = new Set<string>();
+  for (const expression of resolvedRegistryExpressions(
+    match.value,
+    match.sourceFile,
+  )) {
+    const start = expression.getStart(match.sourceFile);
+    for (const identifier of identifiersFromArrayExpression(
+      source.slice(start, expression.end),
+    )) {
+      identifiers.add(identifier);
+    }
+  }
+  return identifiers;
+}
 
-  const objectText = source.slice(openBrace, closeBrace + 1);
-  const propertyMatch = new RegExp(`\\b${property}\\s*:`).exec(objectText);
-  if (!propertyMatch) return undefined;
+type OutboxRegistryPropertyAnalysis = {
+  sourceFile: ts.SourceFile;
+  value?: ts.Expression;
+  indeterminate: boolean;
+};
 
-  const valueStart = openBrace + propertyMatch.index + propertyMatch[0].length;
-  const value = topLevelValueSlice(source, valueStart, closeBrace);
-  if (!value) return undefined;
+function outboxRegistryPropertyAnalysis(
+  source: string,
+  property: "events" | "jobs",
+): OutboxRegistryPropertyAnalysis | undefined {
+  const sourceFile = ts.createSourceFile(
+    "outbox-registry.ts",
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const initializers = registryInitializers(sourceFile);
+  const selected = selectOutboxRegistryCall(sourceFile);
+  if (!selected.call) {
+    return selected.indeterminate
+      ? { sourceFile, indeterminate: true }
+      : undefined;
+  }
 
-  return value;
+  const firstArgument = selected.call.arguments[0];
+  const object = firstArgument
+    ? resolveRegistryExpression(firstArgument, initializers)
+    : undefined;
+  if (!object || !ts.isObjectLiteralExpression(object)) {
+    return { sourceFile, indeterminate: true };
+  }
+
+  let value: ts.Expression | undefined;
+  let indeterminate = false;
+  for (const member of object.properties) {
+    if (ts.isSpreadAssignment(member)) {
+      value = undefined;
+      indeterminate = true;
+      continue;
+    }
+    const name = member.name ? registryPropertyName(member.name) : undefined;
+    if (!name) {
+      value = undefined;
+      indeterminate = true;
+      continue;
+    }
+    if (name !== property) continue;
+    if (
+      ts.isPropertyAssignment(member) ||
+      ts.isShorthandPropertyAssignment(member)
+    ) {
+      value = ts.isPropertyAssignment(member)
+        ? member.initializer
+        : member.name;
+      indeterminate = false;
+    } else {
+      value = undefined;
+      indeterminate = true;
+    }
+  }
+  if (value && !isStaticRegistryValue(value, initializers)) {
+    return { sourceFile, indeterminate: true };
+  }
+  return { sourceFile, value, indeterminate };
+}
+
+function isStaticRegistryValue(
+  expression: ts.Expression,
+  initializers: Map<string, ts.Expression>,
+  visited = new Set<string>(),
+): boolean {
+  const current = unwrapRegistryExpression(expression);
+  if (ts.isArrayLiteralExpression(current)) return true;
+  if (!ts.isIdentifier(current)) return false;
+
+  const initializer = initializers.get(current.text);
+  if (!initializer) return true;
+  if (visited.has(current.text)) return false;
+
+  const nextVisited = new Set(visited);
+  nextVisited.add(current.text);
+  return isStaticRegistryValue(initializer, initializers, nextVisited);
+}
+
+function selectOutboxRegistryCall(sourceFile: ts.SourceFile): {
+  call?: ts.CallExpression;
+  indeterminate: boolean;
+} {
+  const exportedNames = locallyExportedRegistryNames(sourceFile);
+  const candidates: {
+    name?: string;
+    exported: boolean;
+    calls: ts.CallExpression[];
+  }[] = [];
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    const statementExported = Boolean(
+      statement.modifiers?.some(
+        (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,
+      ),
+    );
+    for (const declaration of statement.declarationList.declarations) {
+      if (!declaration.initializer) continue;
+      const calls = outboxRegistryCalls(declaration.initializer);
+      if (calls.length === 0) continue;
+      const name = ts.isIdentifier(declaration.name)
+        ? declaration.name.text
+        : undefined;
+      candidates.push({
+        ...(name ? { name } : {}),
+        exported: statementExported || (name ? exportedNames.has(name) : false),
+        calls,
+      });
+    }
+  }
+
+  const canonical = candidates.filter(
+    (candidate) => candidate.name === "outboxRegistry" && candidate.exported,
+  );
+  const exported = candidates.filter((candidate) => candidate.exported);
+  const selected =
+    canonical.length > 0
+      ? canonical
+      : exported.length > 0
+        ? exported
+        : candidates;
+  if (selected.length === 1 && selected[0].calls.length === 1) {
+    return { call: selected[0].calls[0], indeterminate: false };
+  }
+  if (selected.length > 0) return { indeterminate: true };
+
+  const fallback = outboxRegistryCalls(sourceFile);
+  return fallback.length === 1
+    ? { call: fallback[0], indeterminate: false }
+    : { indeterminate: fallback.length > 0 };
+}
+
+function locallyExportedRegistryNames(sourceFile: ts.SourceFile): Set<string> {
+  const names = new Set<string>();
+  for (const statement of sourceFile.statements) {
+    if (
+      !ts.isExportDeclaration(statement) ||
+      !statement.exportClause ||
+      !ts.isNamedExports(statement.exportClause) ||
+      statement.moduleSpecifier
+    ) {
+      continue;
+    }
+    for (const element of statement.exportClause.elements) {
+      names.add(element.propertyName?.text ?? element.name.text);
+    }
+  }
+  return names;
+}
+
+function outboxRegistryCalls(node: ts.Node): ts.CallExpression[] {
+  const calls: ts.CallExpression[] = [];
+  const visit = (child: ts.Node): void => {
+    if (
+      ts.isCallExpression(child) &&
+      ((ts.isIdentifier(child.expression) &&
+        child.expression.text === "defineOutboxRegistry") ||
+        (ts.isPropertyAccessExpression(child.expression) &&
+          child.expression.name.text === "defineOutboxRegistry"))
+    ) {
+      calls.push(child);
+    }
+    ts.forEachChild(child, visit);
+  };
+  visit(node);
+  return calls;
+}
+
+function resolvedRegistryExpressions(
+  expression: ts.Expression,
+  sourceFile: ts.SourceFile,
+): ts.Expression[] {
+  const initializers = registryInitializers(sourceFile);
+
+  const resolve = (
+    candidate: ts.Expression,
+    visited: Set<string>,
+  ): ts.Expression[] => {
+    const current = unwrapRegistryExpression(candidate);
+    if (ts.isArrayLiteralExpression(current)) {
+      return current.elements.flatMap((element) =>
+        ts.isSpreadElement(element)
+          ? resolve(element.expression, new Set(visited))
+          : ts.isExpression(element)
+            ? [element]
+            : [],
+      );
+    }
+    if (ts.isIdentifier(current) && !visited.has(current.text)) {
+      const initializer = initializers.get(current.text);
+      if (initializer) {
+        const nextVisited = new Set(visited);
+        nextVisited.add(current.text);
+        return resolve(initializer, nextVisited);
+      }
+    }
+    return [current];
+  };
+
+  return resolve(expression, new Set());
+}
+
+function registryInitializers(
+  sourceFile: ts.SourceFile,
+): Map<string, ts.Expression> {
+  const initializers = new Map<string, ts.Expression>();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.initializer) {
+        initializers.set(declaration.name.text, declaration.initializer);
+      }
+    }
+  }
+  return initializers;
+}
+
+function resolveRegistryExpression(
+  expression: ts.Expression,
+  initializers: Map<string, ts.Expression>,
+  visited = new Set<string>(),
+): ts.Expression {
+  const current = unwrapRegistryExpression(expression);
+  if (!ts.isIdentifier(current) || visited.has(current.text)) return current;
+  const initializer = initializers.get(current.text);
+  if (!initializer) return current;
+  const nextVisited = new Set(visited);
+  nextVisited.add(current.text);
+  return resolveRegistryExpression(initializer, initializers, nextVisited);
+}
+
+function unwrapRegistryExpression(expression: ts.Expression): ts.Expression {
+  let current = expression;
+  while (
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isSatisfiesExpression(current) ||
+    ts.isTypeAssertionExpression(current) ||
+    ts.isNonNullExpression(current)
+  ) {
+    current = current.expression;
+  }
+  return current;
+}
+
+function registryPropertyName(name: ts.PropertyName): string | undefined {
+  return ts.isIdentifier(name) || ts.isStringLiteralLike(name)
+    ? name.text
+    : undefined;
 }
 
 /**
@@ -390,53 +690,3 @@ function appendEntry(
   if (next === source) return { kind: "unchanged" };
   return { kind: "updated", source: next };
 }
-
-function topLevelValueSlice(
-  source: string,
-  valueStart: number,
-  hardEnd: number,
-): InitializerInfo | undefined {
-  let start = valueStart;
-  while (start < hardEnd && /\s/.test(source[start])) start++;
-  if (start >= hardEnd) return undefined;
-
-  let depth = 0;
-
-  for (const index of codeCharacterIndexes(source, start, hardEnd + 1)) {
-    const char = source[index];
-
-    if (char === "[" || char === "(" || char === "{") {
-      depth++;
-      continue;
-    }
-
-    if (char === "]" || char === ")" || char === "}") {
-      if (depth === 0) {
-        return trimmedInfo(source, start, index);
-      }
-      depth--;
-      continue;
-    }
-
-    if (char === "," && depth === 0) {
-      return trimmedInfo(source, start, index);
-    }
-  }
-
-  return undefined;
-}
-
-function trimmedInfo(
-  source: string,
-  start: number,
-  end: number,
-): InitializerInfo {
-  let trimmedEnd = end;
-  while (trimmedEnd > start && /\s/.test(source[trimmedEnd - 1])) trimmedEnd--;
-
-  return {
-    text: source.slice(start, trimmedEnd),
-    start,
-    end: trimmedEnd,
-  };
-}

package/src/templates/agents.ts

@@ -41,6 +41,9 @@ https://beignetjs.com (agent-friendly index at https://beignetjs.com/llms.txt).
 README.md covers setup and the app map; this file covers what is not
 discoverable from the code.
 
+This app requires Node.js 22.12 or newer. Bun 1.3.14 or newer is supported for
+Beignet commands.
+
 ## Registration is explicit
 
 Hand-writing an artifact file does not wire it into the app. Non-registration
@@ -54,6 +57,11 @@ is a silent failure — the file exists but never runs:
 - Tasks must be added to \`defineTasks([...])\` in \`server/tasks.ts\`.
 - Outbox events and jobs must be registered in \`defineOutboxRegistry({...})\`
   in \`server/outbox.ts\`.
+- An outbox registry containing jobs also requires \`jobs: JobDispatcherPort\`
+  to be bound directly or deferred to a provider. \`${cli} make job\` installs
+  an app-owned inline dispatcher only when no dispatcher is already wired;
+  adding an Inngest or BullMQ preset later replaces only that marked generated
+  fallback and rejects unmarked custom inline wiring as a conflict.
 - Listeners must be added to the \`listeners\` array in \`server/listeners.ts\`
   and wired through a \`registerListeners(...)\` call in server provider wiring.
 - Apps using Inngest must also spread feature job registries into
@@ -106,6 +114,7 @@ apps have reimplemented by accident:
 
 | Need | Use |
 | --- | --- |${capabilityClientRow}
+| Query parameters on an HTTP contract | Pass both the Standard Schema and an explicit \`defineQueryTransport({ ... })\` to \`.query(schema, transport)\`. Use \`query.string()\`, \`query.number()\`, \`query.integer()\`, \`query.boolean()\`, \`query.dateTime()\`, \`query.date()\`, repeated scalar arrays, or one flat \`deepObject\`; never make schema coercion define the URL format. |
 | App context outside HTTP — agents, queues, scripts, backfills | \`server.createServiceContext(input)\`, or \`server.runServiceContext(input, fn)\` in one-off scripts. Never hand-assemble a context or call \`gate.attach(...)\` — the server owns gate attachment. |
 | Ports outside a request — auth callbacks, module-level helpers | \`const { ports } = await getServer()\` (dynamic \`import("@/server")\` breaks module cycles). Do not construct parallel provider clients or fall back to \`console.*\` when \`ports.logger\` exists. |
 | Routes that cannot be contracts — webhooks, third-party callbacks, streaming | \`createWebhookRoute\`, \`createPaymentWebhookRoute\`, \`createScheduleRoute\`, \`createOutboxDrainRoute\` from \`@beignet/next\`; \`server.rawRoute(...)\` for anything else. All run the hooks pipeline — never hand-enforce rate limits in a route body. |
@@ -133,6 +142,13 @@ formatting. The individual commands (\`${lint}\`, \`${cli} lint\`,
 \`${cli} doctor --strict\`, \`${test}\`, \`${typecheck}\`) still work when you
 need one check alone.
 
+Beignet's architecture lint parses TypeScript imports and re-exports,
+\`require()\`, import assignments, and literal dynamic imports, then follows
+local value imports through feature-root helpers. When lint cannot verify a
+computed module reference inside a constrained layer, use a string-literal
+specifier or move runtime loading behind an allowed boundary. Move near-miss
+feature layers to the canonical path named in the diagnostic.
+
 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. The graph honors the app's complete TypeScript \`baseUrl\` and