@beignet/cli 0.0.27 → 0.0.29

package/src/make/shared.ts

@@ -7,6 +7,7 @@ import {
   type ResolvedBeignetConfig,
 } from "../config.js";
 import {
+  type AppendResult,
   appendToArrayExpression,
   appendToNamedArray,
   arrayInitializerInfo,
@@ -349,6 +350,93 @@ export function providersFilePath(config: ResolvedBeignetConfig): string {
   return `${directoryPath(path.dirname(config.paths.server))}/providers.ts`;
 }
 
+/**
+ * Wire a feature listener registry into the generated providers file by
+ * adding a `<registry>Provider` lifecycle provider whose setup calls
+ * `registerListeners(...)` and registering it in the providers array.
+ *
+ * Shared by `beignet make listener` and `beignet doctor --fix` so both write
+ * paths produce byte-identical wiring. Returns `missing` when the exported
+ * providers array anchor cannot be found; callers decide whether that is a
+ * hard error (make) or a keep-the-diagnostic bail (doctor).
+ */
+export function wireListenersProviderSource(
+  source: string,
+  options: {
+    registryName: string;
+    featureKebab: string;
+    listenerModule: string;
+    config: ResolvedBeignetConfig;
+  },
+): AppendResult {
+  const { registryName, featureKebab, listenerModule, config } = options;
+  const providerName = `${registryName}Provider`;
+  let next = source;
+  next = addNamedImport(next, "registerListeners", "@beignet/core/events");
+  next = addNamedImport(next, "createServiceActor", "@beignet/core/ports");
+  next = addNamedImport(next, "createProvider", "@beignet/core/providers");
+  next = addNamedTypeImport(
+    next,
+    "AppContext",
+    aliasModule(config.paths.appContext),
+  );
+  next = addNamedTypeImport(
+    next,
+    "AppServiceContextInput",
+    aliasModule(path.join(path.dirname(config.paths.server), "context.ts")),
+  );
+  next = addNamedTypeImport(next, "AppPorts", aliasModule(config.paths.ports));
+
+  const listenerImport = `import { ${registryName} } from "${listenerModule}";`;
+  if (!next.includes(listenerImport)) {
+    next = insertAfterImports(next, listenerImport);
+  }
+
+  if (!new RegExp(`\\bconst\\s+${providerName}\\b`).test(next)) {
+    const providerDefinition = `const ${providerName} = createProvider<
+\tPick<AppPorts, "eventBus" | "logger">,
+\tAppContext,
+\tAppServiceContextInput
+>()({
+\tname: "${featureKebab}-listeners",
+\tsetup({ ports, createServiceContext }) {
+\t\tconst unregister = registerListeners(ports.eventBus, ${registryName}, {
+\t\t\tctx: () =>
+\t\t\t\tcreateServiceContext({
+\t\t\t\t\tactor: createServiceActor("beignet-listener"),
+\t\t\t\t}),
+\t\t\tonError(error, listener) {
+\t\t\t\tports.logger.error("Event listener failed", {
+\t\t\t\t\terror,
+\t\t\t\t\tlistenerName: listener.name,
+\t\t\t\t});
+\t\t\t},
+\t\t});
+
+\t\treturn {
+\t\t\tstop() {
+\t\t\t\tunregister();
+\t\t\t},
+\t\t};
+\t},
+});
+`;
+    const withProvider = next.replace(
+      /\nexport const providers = \[/,
+      `\n${providerDefinition}\nexport const providers = [`,
+    );
+    if (withProvider === next) return { kind: "missing" };
+    next = withProvider;
+  }
+
+  const appended = appendToNamedArray(next, "providers", providerName);
+  if (appended.kind === "missing") return { kind: "missing" };
+  if (appended.kind === "updated") next = appended.source;
+
+  if (next === source) return { kind: "unchanged" };
+  return { kind: "updated", source: next };
+}
+
 /**
  * Wire provider-backed app ports a generator depends on.
  *

package/src/make.ts

@@ -131,6 +131,7 @@ import {
   usesFeatureOwnedPolicies,
   usesFeatureOwnedTests,
   type WriteGeneratedFileResult,
+  wireListenersProviderSource,
   wirePortProviders,
   writeGeneratedFile,
   writePlannedGeneratedFile,
@@ -1392,79 +1393,20 @@ async function updateListenerProviderWiring(
   }
 
   const listenerIndex = featureArtifactIndexFile("listener", names, config);
-  const providerName = `${names.featureSingularCamel}ListenersProvider`;
-  let next = original;
-  next = addNamedImport(next, "registerListeners", "@beignet/core/events");
-  next = addNamedImport(next, "createServiceActor", "@beignet/core/ports");
-  next = addNamedImport(next, "createProvider", "@beignet/core/providers");
-  next = addNamedTypeImport(
-    next,
-    "AppContext",
-    aliasModule(config.paths.appContext),
-  );
-  next = addNamedTypeImport(
-    next,
-    "AppServiceContextInput",
-    aliasModule(path.join(path.dirname(config.paths.server), "context.ts")),
-  );
-  next = addNamedTypeImport(next, "AppPorts", aliasModule(config.paths.ports));
-
-  const listenerImport = `import { ${listenerIndex.registryName} } from "${aliasModule(listenerIndex.path)}";`;
-  if (!next.includes(listenerImport)) {
-    next = insertAfterImports(next, listenerImport);
-  }
-
-  if (!new RegExp(`\\bconst\\s+${providerName}\\b`).test(next)) {
-    const providerDefinition = `const ${providerName} = createProvider<
-\tPick<AppPorts, "eventBus" | "logger">,
-\tAppContext,
-\tAppServiceContextInput
->()({
-\tname: "${names.feature.kebab}-listeners",
-\tsetup({ ports, createServiceContext }) {
-\t\tconst unregister = registerListeners(ports.eventBus, ${listenerIndex.registryName}, {
-\t\t\tctx: () =>
-\t\t\t\tcreateServiceContext({
-\t\t\t\t\tactor: createServiceActor("beignet-listener"),
-\t\t\t\t}),
-\t\t\tonError(error, listener) {
-\t\t\t\tports.logger.error("Event listener failed", {
-\t\t\t\t\terror,
-\t\t\t\t\tlistenerName: listener.name,
-\t\t\t\t});
-\t\t\t},
-\t\t});
-
-\t\treturn {
-\t\t\tstop() {
-\t\t\t\tunregister();
-\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 ${providersFile}. Register ${listenerIndex.registryName} manually with registerListeners(...), or restore the generated providers file before running make listener.`,
-      );
-    }
-    next = withProvider;
-  }
-
-  const appended = appendToNamedArray(next, "providers", providerName);
-  if (appended.kind === "missing") {
+  const result = wireListenersProviderSource(original, {
+    registryName: listenerIndex.registryName,
+    featureKebab: names.feature.kebab,
+    listenerModule: aliasModule(listenerIndex.path),
+    config,
+  });
+  if (result.kind === "missing") {
     throw new Error(
       `Could not find the exported providers array in ${providersFile}. Register ${listenerIndex.registryName} manually with registerListeners(...), or restore the generated providers file before running make listener.`,
     );
   }
-  if (appended.kind === "updated") next = appended.source;
 
-  if (next === original) return "skipped";
-  if (!options.dryRun) await writeFile(filePath, next);
+  if (result.kind === "unchanged") return "skipped";
+  if (!options.dryRun) await writeFile(filePath, result.source);
   return "updated";
 }
 

package/src/mcp.ts

@@ -380,7 +380,7 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
     "doctor_fix",
     {
       description:
-        "Apply low-risk doctor fixes, then re-check the app. Repairs route-group, schedule, task, and outbox registration drift; listener registration drift is report-only. Returns applied fixes and remaining diagnostics as JSON.",
+        "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.",
       inputSchema: {
         strict: z
           .boolean()

package/src/provider-add.ts

@@ -396,6 +396,57 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     conflictingProviderEntries: [
       "localStorageProvider",
       "createLocalStorageProvider",
+      "vercelBlobStorageProvider",
+      "createVercelBlobStorageProvider",
+    ],
+  },
+  "vercel-blob-storage": {
+    name: "vercel-blob-storage",
+    displayName: "Vercel Blob storage",
+    importName: "vercelBlobStorageProvider",
+    importFrom: "@beignet/provider-storage-vercel-blob",
+    providerEntry: "vercelBlobStorageProvider",
+    dependencies: (packageJson) => ({
+      "@beignet/provider-storage-vercel-blob":
+        beignetDependencyVersion(packageJson),
+      "@vercel/blob": externalVersions.vercelBlob,
+    }),
+    appPort: {
+      key: "storage",
+      typeName: "StoragePort",
+      importName: "StoragePort",
+      importFrom: "@beignet/core/storage",
+    },
+    envVars: ["BLOB_READ_WRITE_TOKEN"],
+    envExample: [
+      "# Vercel Blob storage provider. Vercel sets BLOB_READ_WRITE_TOKEN",
+      "# automatically on deployments with a connected Blob store.",
+      "# BLOB_READ_WRITE_TOKEN=vercel_blob_rw_...",
+      "# BLOB_ACCESS=private",
+      "# BLOB_KEY_PREFIX=",
+      "",
+    ].join("\n"),
+    docs: [
+      "## Vercel Blob storage",
+      "",
+      "- Package: `@beignet/provider-storage-vercel-blob`",
+      "- Peer dependency: `@vercel/blob`",
+      "- The preset wires `vercelBlobStorageProvider` in `server/providers.ts` and defers `storage` in `infra/app-ports.ts`.",
+      "- On Vercel, connect a Blob store to the project and `BLOB_READ_WRITE_TOKEN` is set automatically; set it manually elsewhere.",
+      "- The store is uniform-visibility (`BLOB_ACCESS`, default `private`): Vercel Blob does not report per-object access back, so mixed visibility needs a second store.",
+      "- Use `ctx.ports.storage` in app code; `ctx.ports.vercelBlob` is available as an escape hatch.",
+      "",
+    ].join("\n"),
+    nextSteps: [
+      "Run your package manager install command.",
+      "Connect a Vercel Blob store to the project (or set BLOB_READ_WRITE_TOKEN manually).",
+      "Run beignet providers audit and beignet doctor --strict.",
+    ],
+    conflictingProviderEntries: [
+      "localStorageProvider",
+      "createLocalStorageProvider",
+      "s3StorageProvider",
+      "createS3StorageProvider",
     ],
   },
   "upstash-rate-limit": {

package/src/provider-audit.ts

@@ -365,9 +365,101 @@ export async function readProviderListEntries(
     )
   ).join("\n");
   const providerListSource = extractProviderListSource(providerSource);
-  return providerListSource === undefined
-    ? []
-    : providerListEntries(providerListSource);
+  const entries =
+    providerListSource === undefined
+      ? []
+      : providerListEntries(providerListSource);
+  return expandProviderEntryIdentifiers(entries, providerSource);
+}
+
+/**
+ * Resolve identifiers referenced by provider list entries to their `const`
+ * initializers in the same providers module.
+ *
+ * Registration detection matches provider tokens against entry text, so an
+ * environment-switched provider extracted to a named constant —
+ * `const storage = env.TOKEN ? blobProvider : createLocalStorageProvider()`
+ * registered as `[storage]` — must contribute its initializer text too, not
+ * just the identifier. Resolution follows chains through a seen-set so
+ * self-referential constants cannot loop.
+ */
+function expandProviderEntryIdentifiers(
+  entries: string[],
+  source: string,
+): string[] {
+  const expanded = [...entries];
+  const seen = new Set<string>();
+  const queue = [...entries];
+
+  while (queue.length > 0) {
+    const entry = queue.pop() as string;
+    for (const match of entry.matchAll(/\b[A-Za-z_$][\w$]*\b/g)) {
+      const name = match[0];
+      if (seen.has(name)) continue;
+      seen.add(name);
+
+      const initializer = constInitializerText(source, name);
+      if (initializer !== undefined) {
+        expanded.push(initializer);
+        queue.push(initializer);
+      }
+    }
+  }
+
+  return expanded;
+}
+
+/**
+ * Extract the initializer text of `const <name> = ...;`, ending at the first
+ * top-level semicolon outside strings and brackets.
+ */
+function constInitializerText(
+  source: string,
+  name: string,
+): string | undefined {
+  const declaration = new RegExp(`\\bconst\\s+${name}\\s*=`).exec(source);
+  if (!declaration) return undefined;
+
+  const start = declaration.index + declaration[0].length;
+  let depth = 0;
+  let quote: '"' | "'" | "`" | undefined;
+  let escaped = false;
+
+  for (let index = start; index < source.length; index += 1) {
+    const char = source[index];
+
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === quote) {
+        quote = undefined;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+
+    if (char === "(" || char === "[" || char === "{") {
+      depth += 1;
+      continue;
+    }
+
+    if (char === ")" || char === "]" || char === "}") {
+      depth -= 1;
+      continue;
+    }
+
+    if (char === ";" && depth === 0) {
+      return source.slice(start, index).trim();
+    }
+  }
+
+  return source.slice(start).trim() || undefined;
 }
 
 export function registrationTokenHint(tokens: readonly string[]): string {

package/src/templates/agents.ts

@@ -25,6 +25,9 @@ export function agentsMd(ctx: TemplateContext): string {
       ? "npm run typecheck"
       : `${ctx.packageManager} run typecheck`;
   const intent = intentRunner(ctx);
+  const capabilityClientRow = ctx.api
+    ? ""
+    : "\n| Query cache keys and invalidation | `rq(contract).invalidate(queryClient, params?)`, `.key(...)`, `.filter(...)` from `client/` (`@beignet/react-query`). Thin named wrappers in `features/<feature>/client/` are the convention — hand-built key arrays are not. |";
   const specificSkills = ctx.api
     ? "`@beignet/next#routes-server`, `@beignet/provider-db-drizzle#database-provider`, `@beignet/provider-auth-better-auth#auth-provider`, or `@beignet/cli#app-structure`"
     : "`@beignet/next#routes-server`, `@beignet/react-query#client`, `@beignet/react-hook-form#forms`, `@beignet/provider-db-drizzle#database-provider`, `@beignet/provider-auth-better-auth#auth-provider`, or `@beignet/cli#app-structure`";
@@ -56,8 +59,7 @@ use, so their absence is fine. \`${cli} make event\`, \`${cli} make job\`,
 \`${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, and outbox registration; listener drift is
-report-only and must be fixed by hand.
+route-group, schedule, task, outbox, and listener registration.
 
 ## Prefer generators
 
@@ -68,20 +70,36 @@ 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\`.
 
+## The framework already solves these
+
+Check this table before hand-rolling. Every row is an existing API that
+apps have reimplemented by accident:
+
+| Need | Use |
+| --- | --- |${capabilityClientRow}
+| 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. |
+| Rate limiting or idempotency on a route | Declare \`metadata.rateLimit\` / \`metadata.idempotency\` on the contract (or the \`pipeline\` option on raw routes); hooks enforce it. |
+| Route-level tests that exercise real hooks | \`createTestApp\` / \`createTestRequester\` from \`@beignet/web/testing\`. Bind the rate-limit and idempotency ports in the test app when asserting 429s or replay. |
+| Environment configuration | \`lib/env.ts\` (\`createEnv\`), never ad-hoc \`process.env\` reads in app code. |
+| Request feels slow | Open devtools; every request span breaks down into per-stage bars (context creation is the usual serverless culprit). |
+
 ## Validation loop
 
 Run after every change:
 
 \`\`\`bash
-${lint}
-${cli} lint
-${cli} doctor --strict
-${test}
-${typecheck}
+${cli} check
 \`\`\`
 
-\`${lint}\` runs Biome's code lint. Use \`${format}\` to apply formatting.
-\`${cli} lint\` is Beignet's dependency-direction lint.
+It runs \`${cli} lint\` (Beignet's dependency-direction lint),
+\`${cli} doctor --strict\`, and the app's \`lint\` (Biome), \`typecheck\`, and
+\`test\` scripts in one pass, reporting every failure. Add \`--fix\` to apply
+doctor's low-risk registration fixes first. Use \`${format}\` to apply
+formatting. The individual commands (\`${lint}\`, \`${cli} lint\`,
+\`${cli} doctor --strict\`, \`${test}\`, \`${typecheck}\`) still work when you
+need one check alone.
 
 ## Package skills
 

package/src/templates/base.ts

@@ -209,6 +209,41 @@ The starter's shipped tests use in-memory ports and need no database server. Dat
 `
         : "";
 
+  const optionalAuthRedirects = ctx.api
+    ? ""
+    : `## Optional faster auth redirects
+
+The starter keeps real auth enforcement in \`app/(app)/layout.tsx\`,
+\`server/context.ts\`, route hooks, and protected use cases. After your product
+routes settle, you can add a root \`proxy.ts\` to redirect requests that do not
+have a Better Auth session cookie before rendering the protected app shell:
+
+\`\`\`ts
+import { getSessionCookie } from "better-auth/cookies";
+import { NextResponse, type NextRequest } from "next/server";
+
+export function proxy(request: NextRequest) {
+	const sessionCookie = getSessionCookie(request);
+
+	if (!sessionCookie) {
+		return NextResponse.redirect(new URL("/sign-in", request.url));
+	}
+
+	return NextResponse.next();
+}
+
+export const config = {
+	matcher: ["/dashboard/:path*", "/todos/:path*", "/settings/:path*"],
+};
+\`\`\`
+
+This is only an optimistic UX gate. A session cookie can be absent, stale, or
+manually created, so keep the layout/session checks and Beignet auth
+hooks/use-case helpers. Update the matcher to match your app's protected URLs;
+route groups such as \`app/(app)\` are not part of the URL.
+
+`;
+
   return `# ${ctx.name}
 
 Beignet app scaffolded with \`@beignet/cli\`.
@@ -241,15 +276,14 @@ ${firstOpen}
 \`\`\`bash
 # in another terminal
 ${cli} routes
-${lint}
-${cli} lint
-${cli} doctor
-${test}
-${typecheck}
+${cli} check
 \`\`\`
 
-\`routes\` shows the contracts Beignet can inspect. \`${cli} lint\` checks dependency direction. \`doctor\` catches route, OpenAPI, and resource drift.
-\`${lint}\` runs Biome over the starter; use \`${format}\` to apply formatting.
+\`routes\` shows the contracts Beignet can inspect. \`check\` runs the whole
+validation loop in one pass: \`${cli} lint\` (dependency direction),
+\`${cli} doctor --strict\` (route, OpenAPI, and resource drift), and the
+\`lint\`, \`typecheck\`, and \`test\` package scripts. Use \`${format}\` to
+apply Biome formatting.
 ${testingNotes}
 ## Coding agents
 
@@ -272,11 +306,7 @@ ${start}
 ${cli} make feature projects
 ${cli} db generate
 ${cli} db migrate
-${test}
-${lint}
-${typecheck}
-${cli} lint
-${cli} doctor
+${cli} check
 \`\`\`
 
 \`make feature\` creates a contract-to-test vertical slice with Drizzle schema and repository files, so regenerate and migrate the database before running the app against the new feature.
@@ -306,6 +336,7 @@ Use \`${cli} make feature projects --recipe full-slice\` when you want a richer
 - \`lib/auth.ts\` exposes \`requireUser(ctx)\` for protected use cases.
 - \`lib/better-auth.ts\` owns Better Auth setup and keeps provider-specific auth details outside use cases.
 ${shellMap}
+${optionalAuthRedirects}
 ## Before deploying
 
 - ${

package/src/templates/db/sqlite.ts

@@ -225,7 +225,13 @@ export function ensureDatabaseReady(client: Client): Promise<void> {
 }
 
 async function prepare(client: Client): Promise<void> {
-	await client.execute("PRAGMA busy_timeout = 5000");
+	// Remote libsql (Turso) runs over HTTP with no file locking and rejects
+	// the lock-wait pragma, so it only applies to local file databases.
+	if (client.protocol === "file") {
+		await client.execute("PRAGMA busy_timeout = 5000");
+	}
+	// SQLite leaves foreign keys off per connection unless asked.
+	await client.execute("PRAGMA foreign_keys = ON");
 
 	if (process.env.NODE_ENV === "production") {
 		const tables = await client.execute(

package/src/templates/shared.ts

@@ -49,6 +49,7 @@ export const externalVersions = {
   drizzleOrm: "^0.45.2",
   inngest: "^3.0.0",
   libsqlClient: "^0.14.0",
+  vercelBlob: "^2.5.0",
   mysql2: "^3.12.0",
   pg: "^8.13.0",
   pglite: "^0.5.2",