@beignet/cli 0.0.32 → 0.0.33

package/src/outbox.ts

@@ -3,6 +3,10 @@ import path from "node:path";
 import type {
   DrainOutboxOptions,
   DrainOutboxResult,
+  OutboxAdminPort,
+  OutboxMessage,
+  OutboxMessageKind,
+  OutboxMessageStatus,
   OutboxRegistry,
 } from "@beignet/core/outbox";
 import { createJiti } from "jiti";
@@ -17,6 +21,61 @@ export type RunOutboxDrainOptions = {
   batchSize?: number;
 };
 
+/**
+ * Options for listing outbox messages.
+ */
+export type RunOutboxListOptions = {
+  cwd?: string;
+  modulePath?: string;
+  status?: OutboxMessageStatus;
+  kind?: OutboxMessageKind;
+  name?: string;
+  limit?: number;
+};
+
+/**
+ * Options for showing one outbox message.
+ */
+export type RunOutboxShowOptions = {
+  cwd?: string;
+  modulePath?: string;
+  id: string;
+};
+
+/**
+ * Options for requeueing one dead-lettered outbox message.
+ */
+export type RunOutboxRequeueOptions = {
+  cwd?: string;
+  modulePath?: string;
+  id: string;
+  availableAt?: Date;
+  resetAttempts?: boolean;
+};
+
+/**
+ * Options for purging dead-lettered outbox messages.
+ */
+export type RunOutboxPurgeOptions = {
+  cwd?: string;
+  modulePath?: string;
+  before?: Date;
+  all?: boolean;
+  limit?: number;
+  dryRun?: boolean;
+};
+
+/**
+ * Options for pruning delivered outbox messages.
+ */
+export type RunOutboxPruneOptions = {
+  cwd?: string;
+  modulePath?: string;
+  before: Date;
+  limit?: number;
+  dryRun?: boolean;
+};
+
 /**
  * Result returned by `beignet outbox drain`.
  */
@@ -28,6 +87,53 @@ export type RunOutboxDrainResult = {
   durationMs: number;
 };
 
+/**
+ * Result returned by `beignet outbox list`.
+ */
+export type RunOutboxListResult = {
+  schemaVersion: 1;
+  cwd: string;
+  modulePath: string;
+  messages: readonly OutboxMessage[];
+  count: number;
+  durationMs: number;
+};
+
+/**
+ * Result returned by `beignet outbox show`.
+ */
+export type RunOutboxShowResult = {
+  schemaVersion: 1;
+  cwd: string;
+  modulePath: string;
+  message: OutboxMessage;
+  durationMs: number;
+};
+
+/**
+ * Result returned by `beignet outbox requeue`.
+ */
+export type RunOutboxRequeueResult = {
+  schemaVersion: 1;
+  cwd: string;
+  modulePath: string;
+  message: OutboxMessage;
+  durationMs: number;
+};
+
+/**
+ * Result returned by destructive outbox admin commands.
+ */
+export type RunOutboxDeleteResult = {
+  schemaVersion: 1;
+  cwd: string;
+  modulePath: string;
+  dryRun: boolean;
+  matched: number;
+  deleted: number;
+  durationMs: number;
+};
+
 type OutboxDrainLogger = {
   error(message: string, meta?: Record<string, unknown>): unknown;
 };
@@ -47,6 +153,7 @@ type OutboxDrainInstrumentation = {
 
 type OutboxDrainPorts = {
   outbox: DrainOutboxOptions["outbox"];
+  outboxAdmin?: OutboxAdminPort;
   eventBus?: DrainOutboxOptions["eventBus"];
   jobs?: DrainOutboxOptions["jobs"];
   logger?: OutboxDrainLogger;
@@ -65,13 +172,24 @@ type OutboxDrainContextArgs = {
   batchSize?: number;
 };
 
+type OutboxAdminOperation = "list" | "show" | "requeue" | "purge" | "prune";
+
+type OutboxAdminContextArgs = {
+  operation: OutboxAdminOperation;
+};
+
 type OutboxModule = {
   outboxRegistry?: unknown;
   createOutboxDrainContext?: (args: OutboxDrainContextArgs) => unknown;
+  createOutboxAdminContext?: (args: OutboxAdminContextArgs) => unknown;
   stopOutboxDrainContext?: (
     ctx: OutboxDrainContext,
     args: OutboxDrainContextArgs,
   ) => unknown;
+  stopOutboxAdminContext?: (
+    ctx: OutboxDrainContext,
+    args: OutboxAdminContextArgs,
+  ) => unknown;
 };
 
 /**
@@ -138,6 +256,190 @@ export async function runOutboxDrain(
   }
 }
 
+/**
+ * List outbox messages through the app's outbox admin port.
+ */
+export async function runOutboxList(
+  options: RunOutboxListOptions = {},
+): Promise<RunOutboxListResult> {
+  return withOutboxAdminContext(options, "list", async ({ admin, base }) => {
+    const query = {
+      status: options.status,
+      kind: options.kind,
+      name: options.name,
+    };
+    const messages = await admin.listMessages({
+      ...query,
+      limit: options.limit,
+    });
+    const count = await admin.countMessages(query);
+
+    return {
+      ...base,
+      messages,
+      count,
+    };
+  });
+}
+
+/**
+ * Show one outbox message through the app's outbox admin port.
+ */
+export async function runOutboxShow(
+  options: RunOutboxShowOptions,
+): Promise<RunOutboxShowResult> {
+  return withOutboxAdminContext(options, "show", async ({ admin, base }) => {
+    const message = await admin.getMessage(options.id);
+    if (!message) {
+      throw new Error(`Outbox message "${options.id}" does not exist.`);
+    }
+
+    return {
+      ...base,
+      message,
+    };
+  });
+}
+
+/**
+ * Requeue one dead-lettered outbox message.
+ */
+export async function runOutboxRequeue(
+  options: RunOutboxRequeueOptions,
+): Promise<RunOutboxRequeueResult> {
+  return withOutboxAdminContext(options, "requeue", async ({ admin, base }) => {
+    const message = await admin.requeueMessage({
+      id: options.id,
+      availableAt: options.availableAt,
+      resetAttempts: options.resetAttempts,
+    });
+
+    return {
+      ...base,
+      message,
+    };
+  });
+}
+
+/**
+ * Purge dead-lettered outbox messages.
+ */
+export async function runOutboxPurge(
+  options: RunOutboxPurgeOptions = {},
+): Promise<RunOutboxDeleteResult> {
+  if (!options.before && !options.all) {
+    throw new Error(
+      "Pass --before <date> to purge old dead-lettered messages, or pass --all to purge every dead-lettered message.",
+    );
+  }
+
+  return withOutboxAdminContext(options, "purge", async ({ admin, base }) => {
+    const query = {
+      status: "deadLettered" as const,
+      updatedBefore: options.before,
+    };
+    const matched = await admin.countMessages(query);
+    const result = options.dryRun
+      ? { deleted: dryRunDeleteCount(matched, options.limit) }
+      : await admin.purgeDeadLettered({
+          before: options.before,
+          limit: options.limit,
+        });
+
+    return {
+      ...base,
+      dryRun: Boolean(options.dryRun),
+      matched,
+      deleted: result.deleted,
+    };
+  });
+}
+
+/**
+ * Prune delivered outbox messages.
+ */
+export async function runOutboxPrune(
+  options: RunOutboxPruneOptions,
+): Promise<RunOutboxDeleteResult> {
+  return withOutboxAdminContext(options, "prune", async ({ admin, base }) => {
+    const query = {
+      status: "delivered" as const,
+      deliveredBefore: options.before,
+    };
+    const matched = await admin.countMessages(query);
+    const result = options.dryRun
+      ? { deleted: dryRunDeleteCount(matched, options.limit) }
+      : await admin.pruneDelivered({
+          before: options.before,
+          limit: options.limit,
+        });
+
+    return {
+      ...base,
+      dryRun: Boolean(options.dryRun),
+      matched,
+      deleted: result.deleted,
+    };
+  });
+}
+
+async function withOutboxAdminContext<T extends object>(
+  options: { cwd?: string; modulePath?: string },
+  operation: OutboxAdminOperation,
+  run: (args: {
+    admin: OutboxAdminPort;
+    base: {
+      schemaVersion: 1;
+      cwd: string;
+      modulePath: string;
+    };
+  }) => Promise<T>,
+): Promise<T & { durationMs: number }> {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const config = await loadBeignetConfig(cwd);
+  const modulePath = normalizePath(options.modulePath ?? config.paths.outbox);
+  const startedAt = performance.now();
+  const outboxModule = await loadOutboxModule(cwd, modulePath);
+  const contextArgs = { operation };
+  const rawContext = outboxModule.createOutboxAdminContext
+    ? await outboxModule.createOutboxAdminContext(contextArgs)
+    : await createFallbackOutboxAdminContext(outboxModule);
+  const ctx = assertOutboxAdminContext(rawContext, modulePath);
+  const admin = resolveOutboxAdminPort(ctx, modulePath);
+
+  try {
+    const result = await run({
+      admin,
+      base: {
+        schemaVersion: 1,
+        cwd,
+        modulePath,
+      },
+    });
+    return {
+      ...result,
+      durationMs: Math.round(performance.now() - startedAt),
+    };
+  } finally {
+    if (outboxModule.stopOutboxAdminContext) {
+      await outboxModule.stopOutboxAdminContext(ctx, contextArgs);
+    } else {
+      await outboxModule.stopOutboxDrainContext?.(ctx, {
+        registry: maybeOutboxRegistry(outboxModule.outboxRegistry),
+      });
+    }
+  }
+}
+
+async function createFallbackOutboxAdminContext(
+  outboxModule: OutboxModule,
+): Promise<unknown> {
+  if (!outboxModule.createOutboxDrainContext) return undefined;
+  return outboxModule.createOutboxDrainContext({
+    registry: maybeOutboxRegistry(outboxModule.outboxRegistry),
+  });
+}
+
 async function loadOutboxModule(
   cwd: string,
   modulePath: string,
@@ -197,6 +499,19 @@ function assertOutboxDrainContext(
   return ctx as OutboxDrainContext;
 }
 
+function assertOutboxAdminContext(
+  ctx: unknown,
+  modulePath: string,
+): OutboxDrainContext {
+  if (!isRecord(ctx) || !isRecord(ctx.ports)) {
+    throw new Error(
+      `${modulePath} must export createOutboxAdminContext or createOutboxDrainContext that returns an app context with ports.outboxAdmin.`,
+    );
+  }
+
+  return ctx as OutboxDrainContext;
+}
+
 function isOutboxPort(value: unknown): value is DrainOutboxOptions["outbox"] {
   return (
     isRecord(value) &&
@@ -207,6 +522,48 @@ function isOutboxPort(value: unknown): value is DrainOutboxOptions["outbox"] {
   );
 }
 
+function isOutboxAdminPort(value: unknown): value is OutboxAdminPort {
+  return (
+    isRecord(value) &&
+    typeof value.listMessages === "function" &&
+    typeof value.countMessages === "function" &&
+    typeof value.getMessage === "function" &&
+    typeof value.requeueMessage === "function" &&
+    typeof value.purgeDeadLettered === "function" &&
+    typeof value.pruneDelivered === "function"
+  );
+}
+
+function resolveOutboxAdminPort(
+  ctx: OutboxDrainContext,
+  modulePath: string,
+): OutboxAdminPort {
+  if (isOutboxAdminPort(ctx.ports.outboxAdmin)) return ctx.ports.outboxAdmin;
+  if (isOutboxAdminPort(ctx.ports.outbox)) return ctx.ports.outbox;
+
+  throw new Error(
+    `${modulePath} createOutboxAdminContext must return ports.outboxAdmin, or ports.outbox must implement OutboxAdminPort.`,
+  );
+}
+
+function maybeOutboxRegistry(registry: unknown): OutboxRegistry {
+  if (
+    isRecord(registry) &&
+    registry.events instanceof Map &&
+    registry.jobs instanceof Map
+  ) {
+    return {
+      events: registry.events,
+      jobs: registry.jobs,
+    } as unknown as OutboxRegistry;
+  }
+
+  return {
+    events: new Map(),
+    jobs: new Map(),
+  };
+}
+
 async function recordOutboxDrain(
   ctx: OutboxDrainContext,
   result: DrainOutboxResult,
@@ -235,6 +592,12 @@ function assertPositiveInteger(name: string, value: number): void {
   }
 }
 
+function dryRunDeleteCount(matched: number, limit: number | undefined): number {
+  if (limit === undefined) return matched;
+  assertPositiveInteger("limit", limit);
+  return Math.min(matched, limit);
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }

package/src/preflight.ts

@@ -283,7 +283,7 @@ export async function runPreflight(
     severity: "note",
     code: "BEIGNET_PREFLIGHT_MANUAL_REVIEW",
     message:
-      "Manual review (no framework primitives yet): CSRF protection, secure headers, and tracing export — see the deployment docs hardening checklist.",
+      "Manual review: CSRF policy, CSP/HSTS values, trusted proxy topology, and tracing export — see the deployment docs hardening checklist.",
   });
 
   let envModuleChecked = false;

package/src/provider-add.ts

@@ -455,6 +455,53 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "Run beignet providers audit and beignet doctor --strict.",
     ],
   },
+  "event-bus-redis": {
+    name: "event-bus-redis",
+    displayName: "Redis event bus",
+    importName: "redisEventBusProvider",
+    importFrom: "@beignet/provider-event-bus-redis",
+    providerEntry: "redisEventBusProvider",
+    dependencies: (packageJson) => ({
+      "@beignet/provider-event-bus-redis":
+        beignetDependencyVersion(packageJson),
+      ioredis: externalVersions.ioredis,
+    }),
+    appPort: {
+      key: "eventBus",
+      typeName: "EventBusPort",
+      importName: "EventBusPort",
+      importFrom: "@beignet/core/ports",
+    },
+    envVars: ["REDIS_EVENT_BUS_URL"],
+    envExample: [
+      "# Redis event bus provider",
+      "REDIS_EVENT_BUS_URL=redis://localhost:6379",
+      "# REDIS_EVENT_BUS_DB=0",
+      "# REDIS_EVENT_BUS_CHANNEL_PREFIX=beignet:event-bus:",
+      "",
+    ].join("\n"),
+    docs: [
+      "## Redis event bus",
+      "",
+      "- Package: `@beignet/provider-event-bus-redis`",
+      "- Peer dependency: `ioredis`",
+      "- The preset wires `redisEventBusProvider` in `server/providers.ts` and defers `eventBus` in `infra/app-ports.ts`.",
+      "- Set `REDIS_EVENT_BUS_URL` before booting the app.",
+      "- Redis Pub/Sub delivery is best-effort and cross-process, but not durable: use outbox/jobs for side effects that need retry, replay, or dead-letter handling.",
+      "- Use `ctx.ports.eventBus` in app code; `ctx.ports.redisEventBus` is available as an escape hatch.",
+      "",
+    ].join("\n"),
+    nextSteps: [
+      "Run your package manager install command.",
+      "Set REDIS_EVENT_BUS_URL in .env.local or your deployment environment.",
+      "Keep durable side effects on the outbox/jobs path; Redis Pub/Sub does not replay missed events.",
+      "Run beignet providers audit and beignet doctor --strict.",
+    ],
+    conflictingProviderEntries: [
+      "createInMemoryEventBusProvider",
+      "createRedisEventBusProvider",
+    ],
+  },
   "redis-locks": {
     name: "redis-locks",
     displayName: "Redis locks",

package/src/task.ts

@@ -50,7 +50,7 @@ export async function runAppTask(
   const task = findTask(taskModule.tasks, options.name, modulePath);
   // Loaded lazily so CLI commands that never touch the app runtime, such as
   // `beignet lint`, work without a built @beignet/core.
-  const { parseTaskInput } = await import("@beignet/core/tasks");
+  const { parseTaskInput, runTask } = await import("@beignet/core/tasks");
   const parsedInput = await parseTaskInput(task, rawInput);
   const contextArgs: TaskRunContextArgs = {
     task,
@@ -63,8 +63,7 @@ export async function runAppTask(
     : {};
 
   try {
-    const output = await task.handle({
-      task,
+    const output = await runTask(task, {
       input: parsedInput,
       ctx,
     });

package/src/templates/agents.ts

@@ -27,7 +27,9 @@ export function agentsMd(ctx: TemplateContext): string {
   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. |";
+    : "\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. |" +
+      "\n| Server Component request context | Use an app-owned server-only helper such as `lib/server-context.ts` that wraps `server.createContextFromNext()` in React `cache(...)`. Layouts may read `ctx.auth`, `ctx.tenant`, and request metadata for redirects and shell state; feature data still belongs behind use cases. |" +
+      "\n| Server Component React Query prefetch | Use an app-owned helper such as `lib/server-react-query.ts` on top of the request context: keep the `rq(contract).queryOptions(...)` key, replace only the server `queryFn` with the direct use case call, and do not create a parallel `rqServer` abstraction. |";
   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`";
@@ -50,8 +52,8 @@ 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\`.
-- Listeners must be wired through a \`registerListeners(...)\` call in infra
-  wiring.
+- Listeners must be added to the \`listeners\` array in \`server/listeners.ts\`
+  and wired through a \`registerListeners(...)\` call in server provider wiring.
 
 The starter ships no workflow registries — generators create them on first
 use, so their absence is fine. \`${cli} make event\`, \`${cli} make job\`,
@@ -81,6 +83,7 @@ apps have reimplemented by accident:
 | 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. |
+| Tenant-owned repository access | Pass \`TenantScope\` through app-facing repository methods and unwrap it with \`tenantScopeId(scope)\` in adapters. Raw provider-correlation lookups such as webhook customer IDs are not tenant authorization. |
 | 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. |
 | The same lookup runs several times in one request — context, policy, use case | Wrap the repository read in \`createMemo(...)\` from \`@beignet/core/memo\` where the adapter is wired in infra. The cache lives for exactly one request; pair mutations with \`.invalidate(...)\`. Never hand-roll per-request caches. |

package/src/templates/base.ts

@@ -67,11 +67,11 @@ export function packageJson(ctx: TemplateContext): string {
     "@beignet/cli": ctx.beignetVersion,
     "@beignet/web": ctx.beignetVersion,
     "@biomejs/biome": externalVersions.biome,
-    "@types/bun": externalVersions.typesBun,
     "@types/node": externalVersions.typesNode,
     "@types/react": externalVersions.typesReact,
     "@types/react-dom": externalVersions.typesReactDom,
     "drizzle-kit": externalVersions.drizzleKit,
+    tsx: externalVersions.tsx,
     typescript: externalVersions.typescript,
   };
 
@@ -97,11 +97,11 @@ export function packageJson(ctx: TemplateContext): string {
     start: "next start",
     lint: "biome lint .",
     format: "biome format --write .",
-    test: "bun test",
+    test: "tsx lib/beignet-test-runner.ts",
     typecheck: "tsc --noEmit",
     "db:generate": "drizzle-kit generate",
     "db:migrate": "drizzle-kit migrate",
-    "db:reset": "bun infra/db/reset.ts",
+    "db:reset": "tsx infra/db/reset.ts",
   };
 
   return json({

package/src/templates/index.ts

@@ -28,6 +28,7 @@ import {
 import { shadcnTemplateFiles } from "./shadcn.js";
 import type { TemplateContext, TemplateFile } from "./shared.js";
 import { shellTemplateFiles } from "./shell.js";
+import { testSupportTemplateFiles } from "./testing.js";
 import { todosFiles } from "./todos.js";
 
 /**
@@ -133,6 +134,7 @@ export function getTemplateFiles(ctx: TemplateContext): TemplateFile[] {
     { path: "lib/auth.ts", content: serverFiles.authHelpers },
     { path: "lib/better-auth.ts", content: betterAuth(ctx) },
     { path: "lib/tenant.ts", content: serverFiles.tenantHelper },
+    ...testSupportTemplateFiles,
     { path: "lib/use-case.ts", content: serverFiles.useCaseBuilder },
     { path: "server/index.ts", content: server(ctx) },
     { path: "server/context.ts", content: serverFiles.serverContext },

package/src/templates/server.ts

@@ -297,7 +297,11 @@ export function server(ctx: TemplateContext): string {
 
   return `import "@beignet/core/server-only";
 import { createNextServer, createNextServerLoader } from "@beignet/next";
-import { createErrorReportingHooks, createIdempotencyHooks } from "@beignet/core/server";
+import {
+	createErrorReportingHooks,
+	createIdempotencyHooks,
+	createSecurityHeadersHooks,
+} from "@beignet/core/server";
 import type { AppContext } from "@/app-context";
 import { appPorts } from "@/infra/app-ports";
 import { env } from "@/lib/env";
@@ -314,6 +318,7 @@ export const getServer = createNextServerLoader(async () => {
 ${providerConfigEntries}
 	},
 	hooks: [
+		createSecurityHeadersHooks<AppContext>(),
 		createErrorReportingHooks<AppContext>(),
 		createIdempotencyHooks<AppContext>(),
 	],

package/src/templates/shared.ts

@@ -35,8 +35,8 @@ export const externalVersions = {
   next: "^16.2.4",
   react: "^19.2.5",
   reactDom: "^19.2.5",
+  tsx: "^4.22.4",
   typescript: "^5.3.0",
-  typesBun: "^1.3.13",
   typesNode: "^20.10.0",
   typesReact: "^19.0.0",
   typesReactDom: "^19.0.0",
@@ -67,6 +67,18 @@ export const externalVersions = {
   upstashRedis: "^1.0.0",
 };
 
+export const legacyGeneratedPackageScripts: Record<string, string> = {
+  "db:reset": "bun infra/db/reset.ts",
+  "db:seed": "bun server/seed.ts",
+  test: "bun test",
+};
+
+export const currentGeneratedPackageScripts: Record<string, string> = {
+  "db:reset": "tsx infra/db/reset.ts",
+  "db:seed": "tsx server/seed.ts",
+  test: "tsx lib/beignet-test-runner.ts",
+};
+
 /**
  * Dialect-specific names used when rendering database-aware templates.
  */