@beignet/cli 0.0.26 → 0.0.28

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/registry-edits.ts

@@ -94,6 +94,53 @@ export function insertAfterImports(source: string, line: string): string {
   return lines.join("\n");
 }
 
+/**
+ * Add a name to an `import { ... } from "<module>";` value import, creating
+ * the import when the module is not imported yet. Names are inserted in
+ * sorted position and single-line versus multiline formatting is preserved.
+ *
+ * Mirrors the `addNamedTypeImport` helper for value imports; type-only
+ * imports (`import type { ... }`) from the same module are left untouched.
+ */
+export function addNamedValueImport(
+  source: string,
+  name: string,
+  moduleName: string,
+): string {
+  const escapedModule = moduleName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const importPattern = new RegExp(
+    `import \\{([^}]*)\\} from "${escapedModule}";`,
+  );
+  const match = importPattern.exec(source);
+  if (!match) {
+    return insertAfterImports(
+      source,
+      `import { ${name} } from "${moduleName}";`,
+    );
+  }
+
+  const names = match[1]
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  if (names.includes(name)) return source;
+
+  const insertIndex = names.findIndex(
+    (existing) => existing.localeCompare(name) > 0,
+  );
+  if (insertIndex === -1) names.push(name);
+  else names.splice(insertIndex, 0, name);
+
+  const indent = match[1].match(/\n([\t ]+)/)?.[1] ?? "\t";
+  const replacement = match[1].includes("\n")
+    ? `import {\n${indent}${names.join(`,\n${indent}`)},\n} from "${moduleName}";`
+    : `import { ${names.join(", ")} } from "${moduleName}";`;
+
+  return `${source.slice(0, match.index)}${replacement}${source.slice(
+    match.index + match[0].length,
+  )}`;
+}
+
 /**
  * Collect every identifier referenced inside an array (or object) expression.
  */

package/src/task.ts

@@ -1,6 +1,6 @@
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import type { TaskDef } from "@beignet/core/tasks";
+import type { TaskDef, TaskRunContextArgs } from "@beignet/core/tasks";
 import { createJiti } from "jiti";
 import { loadBeignetConfig, normalizePath } from "./config.js";
 
@@ -11,6 +11,7 @@ export type RunAppTaskOptions = {
   name: string;
   cwd?: string;
   input?: string | Record<string, unknown>;
+  tenant?: string;
   modulePath?: string;
 };
 
@@ -23,20 +24,15 @@ export type RunAppTaskResult = {
   cwd: string;
   modulePath: string;
   input: unknown;
+  tenant?: string;
   output: unknown;
   durationMs: number;
 };
 
-type TaskContextArgs = {
-  task: TaskDef;
-  taskName: string;
-  input: unknown;
-};
-
 type TaskModule = {
   tasks?: readonly unknown[];
-  createTaskContext?: (args: TaskContextArgs) => unknown;
-  stopTaskContext?: (ctx: unknown, args: TaskContextArgs) => unknown;
+  createTaskContext?: (args: TaskRunContextArgs) => unknown;
+  stopTaskContext?: (ctx: unknown, args: TaskRunContextArgs) => unknown;
 };
 
 /**
@@ -56,10 +52,11 @@ export async function runAppTask(
   // `beignet lint`, work without a built @beignet/core.
   const { parseTaskInput } = await import("@beignet/core/tasks");
   const parsedInput = await parseTaskInput(task, rawInput);
-  const contextArgs = {
+  const contextArgs: TaskRunContextArgs = {
     task,
     taskName: task.name,
     input: parsedInput,
+    tenant: options.tenant,
   };
   const ctx = taskModule.createTaskContext
     ? await taskModule.createTaskContext(contextArgs)
@@ -78,6 +75,7 @@ export async function runAppTask(
       cwd,
       modulePath,
       input: parsedInput,
+      ...(options.tenant !== undefined ? { tenant: options.tenant } : {}),
       output,
       durationMs: Math.round(performance.now() - startedAt),
     };

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
 
@@ -118,9 +136,9 @@ 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 as
+\`./node_modules/.bin/beignet mcp\`, which exposes routes/doctor/lint/make/provider_add as
 structured tools named exactly: \`routes\`, \`doctor\`, \`doctor_fix\`,
-\`lint\`, \`make\`. Clients that do not read \`.mcp.json\` can use the same
+\`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.
 `;
 }

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

@@ -296,16 +296,18 @@ export function server(ctx: TemplateContext): string {
 \t\t},`;
 
   return `import "@beignet/core/server-only";
-import { createNextServer } from "@beignet/next";
+import { createNextServer, createNextServerLoader } from "@beignet/next";
 import { createErrorReportingHooks, createIdempotencyHooks } from "@beignet/core/server";
 import type { AppContext } from "@/app-context";
 import { appPorts } from "@/infra/app-ports";
 import { env } from "@/lib/env";
 import { appContext } from "./context";
-import { providers } from "./providers";
 import { routes } from "./routes";
 
-export const server = await createNextServer({
+export const getServer = createNextServerLoader(async () => {
+	const { providers } = await import("./providers");
+
+	return createNextServer({
 	ports: appPorts,
 	providers,
 	providerConfig: {
@@ -333,6 +335,7 @@ ${providerConfigEntries}
 			},
 		};
 	},
+	});
 });
 `;
 }
@@ -557,15 +560,11 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
 `,
-  apiCatchAllRoute: `import { server } from "@/server";
-
-export const GET = server.api;
-export const HEAD = server.api;
-export const OPTIONS = server.api;
-export const PATCH = server.api;
-export const POST = server.api;
-export const PUT = server.api;
-export const DELETE = server.api;
+  apiCatchAllRoute: `import { createApiRoute } from "@beignet/next";
+import { getServer } from "@/server";
+
+export const { DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT } =
+	createApiRoute(getServer);
 `,
   healthRoute: `import { env } from "@/lib/env";
 
@@ -584,12 +583,12 @@ export function GET() {
 	);
 }
 `,
-  readyRoute: `import { createHealthHandler } from "@beignet/core/server";
+  readyRoute: `import { createHealthRoute } from "@beignet/next";
 import { env } from "@/lib/env";
-import { server } from "@/server";
+import { getServer } from "@/server";
 
-const readiness = createHealthHandler(
-	server.ports,
+export const { GET } = createHealthRoute(
+	getServer,
 	{
 		checks: {
 			database: (ports) => ports.db.checkHealth(),
@@ -598,42 +597,50 @@ const readiness = createHealthHandler(
 	},
 	env.NODE_ENV,
 );
-
-export async function GET(request: Request) {
-	const response = await readiness(request);
-
-	return Response.json(response.body, {
-		status: response.status,
-		headers: {
-			...response.headers,
-			"cache-control": "no-store",
-		},
-	});
-}
 `,
   devtoolsRoute: `import { createDevtoolsRoute } from "@beignet/devtools";
 import { env } from "@/lib/env";
-import { server } from "@/server";
+import { getServer } from "@/server";
 
-export const { GET, POST } = createDevtoolsRoute(server.ports.devtools, {
-	basePath: "/api/devtools",
-	enabled: env.DEVTOOLS_ENABLED,
-});
+export const { GET, POST } = createDevtoolsRoute(
+	async () => (await getServer()).ports.devtools,
+	{
+		basePath: "/api/devtools",
+		enabled: env.DEVTOOLS_ENABLED,
+	},
+);
 `,
   openApiRoute: `import { createOpenAPIHandler } from "@beignet/next";
 import { env } from "@/lib/env";
-import { server } from "@/server";
+import { contracts } from "@/server/routes";
 
-export const GET = createOpenAPIHandler(server.contracts, {
+export const GET = createOpenAPIHandler(contracts, {
 	title: "Beignet starter API",
 	version: "0.1.0",
 	servers: [{ url: env.APP_URL }],
 });
 `,
   authRoute: `import { toNextJsHandler } from "better-auth/next-js";
-import { auth } from "@/lib/better-auth";
 
-export const { GET, POST } = toNextJsHandler(auth);
+type AuthRouteMethod = "GET" | "POST";
+
+async function handleAuthRoute(
+	method: AuthRouteMethod,
+	request: Request,
+): Promise<Response> {
+	const { auth } = await import("@/lib/better-auth");
+	const handlers = toNextJsHandler(auth);
+
+	return handlers[method](request);
+}
+
+export function GET(request: Request): Promise<Response> {
+	return handleAuthRoute("GET", request);
+}
+
+export function POST(request: Request): Promise<Response> {
+	return handleAuthRoute("POST", request);
+}
 `,
   // API-only scaffold frontend: a minimal layout and landing page that point
   // at the contract-backed API surface, plus a typed client without React

package/src/templates/shared.ts

@@ -54,7 +54,12 @@ export const externalVersions = {
   pglite: "^0.5.2",
   pino: "^9.7.0",
   resend: "^6.14.0",
+  sentryNode: "^10.58.0",
+  nodemailer: "^8.0.5",
+  openFeatureServerSdk: "^1.22.0",
   typesPg: "^8.11.0",
+  ioredis: "^5.0.0",
+  awsSdkS3: "^3.955.0",
   upstashRateLimit: "^2.0.0",
   upstashRedis: "^1.0.0",
 };