@podosoft/podokit 1.6.0 → 1.6.1

package/dist/deploy-checks.js

@@ -123,9 +123,9 @@ function connectionBudget(profile, modules) {
         perProcessTerms.push(`DB_AUTH_POOL_MAX ${authPool}`);
         perProcess += authPool;
     }
-    for (const pool of postgres.appPools ?? []) {
-        const size = poolSize(config, pool.sizeKey, 0);
-        perProcessTerms.push(`${pool.sizeKey} ${size}${pool.extraConnections ? ` + ${pool.extraConnections}` : ""}`);
+    for (const [index, pool] of (postgres.appPools ?? []).entries()) {
+        const [label, size] = "sizeKey" in pool ? [pool.sizeKey, poolSize(config, pool.sizeKey, 0)] : [`appPools[${index}]`, pool.size];
+        perProcessTerms.push(`${label} ${size}${pool.extraConnections ? ` + ${pool.extraConnections}` : ""}`);
         perProcess += size + pool.extraConnections;
     }
     const worker = profile.workloads.worker;

package/dist/deploy-schema.d.ts

@@ -70,14 +70,18 @@ export declare function parseReleaseProfile(release: Record<string, unknown>): R
 export declare function parseRuntimeConfig(runtimeConfig: Record<string, unknown>): Record<string, string>;
 /**
  * An application-owned PostgreSQL pool each API or worker process opens beside
- * PodoKit's own: `sizeKey` names the runtimeConfig key that caps it, and
+ * PodoKit's own. Either `sizeKey` names the runtimeConfig key that caps it, or
+ * `size` is the cap the application's code sets, such as a driver's default.
  * `extraConnections` counts connections it opens beyond that cap, such as one to
  * check a server that stopped answering.
  */
-export interface AppConnectionPool {
+export type AppConnectionPool = {
     sizeKey: string;
     extraConnections: number;
-}
+} | {
+    size: number;
+    extraConnections: number;
+};
 /** What the connection budget needs to know about the database, beyond its mode. */
 export interface PostgresBudgetProfile {
     /** The server's max_connections; PodoKit sets it on a database it runs. */

package/dist/deploy-schema.js

@@ -270,7 +270,22 @@ function parsePostgresBudget(value, field, runtimeConfig) {
             const entryField = `${field}.appPools[${index}]`;
             if (!isRecord(entry))
                 throw new Error(`Deployment profile field "${entryField}" must be an object.`);
-            assertOnlyKeys(entry, ["sizeKey", "extraConnections"], entryField);
+            assertOnlyKeys(entry, ["sizeKey", "size", "extraConnections"], entryField);
+            if ((entry.sizeKey === undefined) === (entry.size === undefined)) {
+                throw new Error(`Deployment profile field "${entryField}" must set either sizeKey, the runtimeConfig key that caps the pool, ` +
+                    "or size, the cap the application sets itself.");
+            }
+            const extraConnections = entry.extraConnections ?? 0;
+            if (typeof extraConnections !== "number" || !Number.isInteger(extraConnections) || extraConnections < 0) {
+                throw new Error(`Deployment profile field "${entryField}.extraConnections" must be a non-negative integer.`);
+            }
+            if (entry.size !== undefined) {
+                const size = entry.size;
+                if (typeof size !== "number" || !Number.isInteger(size) || size < 1 || size > MAX_POSTGRES_CONNECTIONS) {
+                    throw new Error(`Deployment profile field "${entryField}.size" must be an integer from 1 to ${MAX_POSTGRES_CONNECTIONS}.`);
+                }
+                return { size, extraConnections };
+            }
             const sizeKey = requiredString(entry, "sizeKey");
             if (!/^[A-Z][A-Z0-9_]*$/.test(sizeKey) || PODOKIT_POOL_KEYS.includes(sizeKey) || seen.has(sizeKey)) {
                 throw new Error(`Deployment profile field "${entryField}.sizeKey" must name another pool's runtimeConfig key, once; ` +
@@ -280,10 +295,6 @@ function parsePostgresBudget(value, field, runtimeConfig) {
             if (!/^[1-9][0-9]*$/.test(runtimeConfig[sizeKey] ?? "")) {
                 throw new Error(`Deployment profile field "${entryField}.sizeKey" names ${sizeKey}, which runtimeConfig must set to a positive integer.`);
             }
-            const extraConnections = entry.extraConnections ?? 0;
-            if (typeof extraConnections !== "number" || !Number.isInteger(extraConnections) || extraConnections < 0) {
-                throw new Error(`Deployment profile field "${entryField}.extraConnections" must be a non-negative integer.`);
-            }
             return { sizeKey, extraConnections };
         });
     }

package/dist/templates/fullstack/AGENTS.md

@@ -105,7 +105,9 @@ Merge added module settings from `.env.example` into an existing `.env`.
 - e2e (Playwright, ships in `tests/`): `{{rootRun}} test:e2e`. Run the whole suite on more
   workers with `E2E_WORKERS=2`, never `--workers`. Tag a test `{ tag: "@exclusive" }` when
   it changes state other tests rely on (a server-wide setting, a seeded account's profile);
-  tagged tests run alone after the rest. Give each test its own mail and SMS recipients and
+  tagged tests run alone after the rest, in a second Playwright run that `test:e2e` starts
+  even when the first one failed, so run the suite through `test:e2e`, not
+  `bunx playwright test`, on more workers. Give each test its own mail and SMS recipients and
   never empty the shared Mailpit inbox or SMS sink. See `tests/README.md`. The managed specs
   read the app's first screen, public pages, and seeded accounts from the owned
   `tests/helpers/app-paths.ts` (and `app-accounts.ts` with admin-dashboard): change those

package/dist/templates/fullstack/apps/api/package.json

@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@podosoft/podokit-contracts": "^0.6.0",
-    "@podosoft/podokit-runtime": "^0.5.0",
+    "@podosoft/podokit-runtime": "^0.5.1",
     "@elysia/cors": "^1.4.2",
     "@elysia/openapi": "^1.4.15",
     "dotenv": "^16.4.5",

package/dist/templates/fullstack/apps/api/scripts/verify-api-contract.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createApp } from "../src/app";
 import { validateEnv } from "../src/config/env.validation";
+import { PROVIDERS } from "../src/config/providers";
 import {
   assertApiContract,
   assertApplicationRoutes,
@@ -30,7 +31,7 @@ try {
   }
   const document: unknown = await response.json();
   const modules = manifest.modules.map((module) => module.name);
-  assertApiContract(document, manifest.template, modules);
+  assertApiContract(document, manifest.template, modules, PROVIDERS);
   assertApplicationRoutes(document, app.routes, APP_DOCUMENTED_ROUTES);
   process.stdout.write(
     `Verified ${documentedApiRoutes(document).size} documented API operations for ${manifest.template}, ` +

package/dist/templates/fullstack/apps/api/src/build.spec.ts

@@ -4,14 +4,17 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
 const BUILD = join(__dirname, "../scripts/build.mjs");
-const EXTENSIONS = join(__dirname, "../scripts/build.extensions.mjs");
+// The application's own build.extensions.mjs names entry points this temporary
+// layout does not contain, so each build starts without application targets. A
+// test that needs some passes its own scripts/build.extensions.mjs.
+const NO_APP_TARGETS = "export const appBuildTargets = [];\n";
 
 /** Builds an API layout made of `files` with the app's build script. */
 async function build(files: Record<string, string>): Promise<{ root: string; code: number; stderr: string }> {
   const root = mkdtempSync(join(tmpdir(), "api-build-"));
   mkdirSync(join(root, "scripts"));
   cpSync(BUILD, join(root, "scripts/build.mjs"));
-  cpSync(EXTENSIONS, join(root, "scripts/build.extensions.mjs"));
+  writeFileSync(join(root, "scripts/build.extensions.mjs"), NO_APP_TARGETS);
   for (const [path, content] of Object.entries(files)) {
     mkdirSync(dirname(join(root, path)), { recursive: true });
     writeFileSync(join(root, path), content);

package/dist/templates/fullstack/apps/api/src/core/api-contract.spec.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "bun:test";
+import { LOCAL_PROVIDER_SELECTIONS, SERVER_PROVIDER_SELECTIONS } from "@podosoft/podokit-runtime";
 import {
   assertApiContract,
   assertApplicationRoutes,
@@ -12,7 +13,7 @@ import {
 
 describe("API contract inventory", () => {
   it("covers the core, Todo, module, and Better Auth routes", () => {
-    const expected = expectedApiRoutes("todo", ["auth", "redis", "file-upload"]);
+    const expected = expectedApiRoutes("todo", ["auth", "redis", "file-upload"], SERVER_PROVIDER_SELECTIONS);
 
     expect(expected).toContain("GET /health/ready");
     expect(expected).toContain("PATCH /todos/{id}");
@@ -23,7 +24,7 @@ describe("API contract inventory", () => {
   });
 
   it("uses one structural parameter name for every public blog post route", () => {
-    const expected = expectedApiRoutes("fullstack", ["blog"]);
+    const expected = expectedApiRoutes("fullstack", ["blog"], SERVER_PROVIDER_SELECTIONS);
 
     expect(expected).toContain("GET /blog/{postRef}");
     expect(expected).toContain("PATCH /blog/{postRef}");
@@ -32,15 +33,53 @@ describe("API contract inventory", () => {
     expect(expected).not.toContain("PATCH /blog/{id}");
   });
 
+  it("expects a provider module's routes only while its provider is selected", () => {
+    const modules = [
+      "object-storage-s3",
+      "object-storage-local",
+      "redis",
+      "cache-memory",
+      "bullmq",
+      "jobs-local",
+    ];
+    const server = expectedApiRoutes("fullstack", modules, SERVER_PROVIDER_SELECTIONS);
+    const local = expectedApiRoutes("fullstack", modules, LOCAL_PROVIDER_SELECTIONS);
+
+    expect(server).toContain("PUT /storage/{key}");
+    expect(server).not.toContain("GET /files/content/*");
+    expect(server).toContain("PUT /cache/{key}");
+    expect(server).toContain("POST /jobs");
+    expect(local).toContain("PUT /storage/{key}");
+    expect(local).toContain("GET /files/content/*");
+    expect(local).not.toContain("PUT /cache/{key}");
+    expect(local).not.toContain("GET /cache/{key}");
+    expect(local).toContain("GET /jobs/{id}");
+
+    const s3Document = {
+      paths: {
+        "/health": { get: {} },
+        "/health/ready": { get: {} },
+        "/storage/{key}": { get: {}, put: {} },
+        "/storage/{key}/presigned": { get: {} },
+      },
+    };
+    const storage = ["object-storage-s3", "object-storage-local"];
+    expect(() => assertApiContract(s3Document, "fullstack", storage, SERVER_PROVIDER_SELECTIONS)).not.toThrow();
+    expect(() => assertApiContract(s3Document, "fullstack", storage, {
+      ...SERVER_PROVIDER_SELECTIONS,
+      "object-storage": "local",
+    })).toThrow("GET /files/content/*");
+  });
+
   it("normalizes OpenAPI operations and reports an exact missing route", () => {
     const document = { paths: { "/health": { get: {} }, "/health/ready": { get: {} } } };
 
     expect(documentedApiRoutes(document)).toEqual(new Set(["GET /health", "GET /health/ready"]));
-    expect(missingApiRoutes(document, "fullstack", ["redis"])).toEqual([
+    expect(missingApiRoutes(document, "fullstack", ["redis"], SERVER_PROVIDER_SELECTIONS)).toEqual([
       "GET /cache/{key}",
       "PUT /cache/{key}",
     ]);
-    expect(() => assertApiContract(document, "fullstack", ["redis"])).toThrow(
+    expect(() => assertApiContract(document, "fullstack", ["redis"], SERVER_PROVIDER_SELECTIONS)).toThrow(
       "OpenAPI contract is missing routes",
     );
   });

package/dist/templates/fullstack/apps/api/src/core/api-contract.ts

@@ -1,3 +1,5 @@
+import type { ProviderCapability, ProviderSelections } from "@podosoft/podokit-runtime";
+
 const OPERATIONS = new Set(["get", "post", "put", "patch", "delete", "options", "head"]);
 
 const CORE_ROUTES = [
@@ -81,6 +83,7 @@ const MODULE_ROUTES: Record<string, string[]> = {
     "DELETE /files/uploads/{id}",
   ],
   "job-progress": ["POST /progress"],
+  "jobs-local": ["POST /jobs", "GET /jobs/{id}"],
   "object-storage-local": [
     "GET /files/content/*",
     "PUT /storage/{key}",
@@ -96,6 +99,22 @@ const MODULE_ROUTES: Record<string, string[]> = {
   sse: ["GET /events/stream", "POST /events"],
 };
 
+/**
+ * The provider each provider module implements. Such a module registers its
+ * routes only while its provider is selected, so an app may keep, say, both
+ * object-storage modules installed and serve the routes of one.
+ */
+export const MODULE_PROVIDERS: Readonly<Record<string, readonly [ProviderCapability, string]>> = {
+  bullmq: ["jobs", "bullmq"],
+  "cache-memory": ["cache", "memory"],
+  "events-memory": ["events", "memory"],
+  "events-redis": ["events", "redis"],
+  "jobs-local": ["jobs", "local"],
+  "object-storage-local": ["object-storage", "local"],
+  "object-storage-s3": ["object-storage", "s3"],
+  redis: ["cache", "redis"],
+};
+
 interface RuntimeRoute {
   method?: string;
   path: string;
@@ -195,10 +214,20 @@ export function documentedApiRoutes(document: unknown): Set<string> {
   return routes;
 }
 
-export function expectedApiRoutes(template: string, modules: string[]): Set<string> {
+/**
+ * The routes the template and the installed modules serve. A provider module
+ * counts only when `providers`, the app's PROVIDERS, selects its provider.
+ */
+export function expectedApiRoutes(
+  template: string,
+  modules: string[],
+  providers: Readonly<ProviderSelections>,
+): Set<string> {
   const routes = new Set(CORE_ROUTES);
   for (const route of TEMPLATE_ROUTES[template] ?? []) routes.add(route);
   for (const module of modules) {
+    const provider = MODULE_PROVIDERS[module];
+    if (provider && providers[provider[0]] !== provider[1]) continue;
     for (const route of MODULE_ROUTES[module] ?? []) routes.add(route);
   }
   return routes;
@@ -208,15 +237,21 @@ export function missingApiRoutes(
   document: unknown,
   template: string,
   modules: string[],
+  providers: Readonly<ProviderSelections>,
 ): string[] {
   const documented = documentedApiRoutes(document);
-  return [...expectedApiRoutes(template, modules)]
+  return [...expectedApiRoutes(template, modules, providers)]
     .filter((route) => !documented.has(route))
     .sort();
 }
 
-export function assertApiContract(document: unknown, template: string, modules: string[]): void {
-  const missing = missingApiRoutes(document, template, modules);
+export function assertApiContract(
+  document: unknown,
+  template: string,
+  modules: string[],
+  providers: Readonly<ProviderSelections>,
+): void {
+  const missing = missingApiRoutes(document, template, modules, providers);
   if (missing.length > 0) {
     throw new Error(`OpenAPI contract is missing routes:\n${missing.join("\n")}`);
   }

package/dist/templates/fullstack/dot-agents/skills/podokit-deploy/references/profile.md

@@ -32,7 +32,8 @@ Review these fields before planning:
 - `workloads`: API/web replicas and resources plus an optional worker
 - `dependencies`: PostgreSQL, Redis, and object storage mode, image, Secret name, and storage.
   PostgreSQL also takes `maxConnections` (default 100) and `appPools` for pools the
-  application opens itself; the doctor and the plan check the connection budget
+  application opens itself, each sized by a `runtimeConfig` key (`sizeKey`) or a
+  fixed `size` when the code sets it; the doctor and the plan check the connection budget
   against them, so lower `DB_POOL_MAX`/`DB_AUTH_POOL_MAX` or replicas when they warn.
 - `secrets`: API/optional web Secret names and required key names, plus image-pull Secret
 - `runtimeConfig`: non-sensitive environment values only

package/dist/templates/fullstack/tests/README.md

@@ -45,16 +45,26 @@ Tag a test when it changes a server-wide setting (a feature flag, the
 authentication configuration such as SMTP, social providers, or sign-up
 approval, the site settings, or a module's settings) or the profile of a seeded
 account. Each project has an `<name>-exclusive` twin, such as `ui-exclusive`,
-that runs only the tagged tests, one at a time. With more than one worker the
-twins wait for every other test, so an exclusive test never runs alongside
-another one. Never empty the shared mail catcher or SMS sink in a test: send to
-an address or number of the test's own instead.
-
-More than one worker suits the whole suite. When a run selects exclusive tests
-with a file name, `--grep`, or `--project`, Playwright also runs every other test
-first, because the twins depend on them, and a test that fails there marks the
-exclusive tests as not run. Use the default single worker for a few files, and
-do not combine `--no-deps` with `E2E_WORKERS` above 1.
+that runs only the tagged tests, one at a time. Never empty the shared mail
+catcher or SMS sink in a test: send to an address or number of the test's own
+instead.
+
+The `test:e2e` scripts run `run-e2e.ts`, which hands its arguments (a file,
+`--grep`, `--project`) to Playwright. With more than one worker it runs
+Playwright twice: first every test not tagged `@exclusive` on those workers,
+then the tagged tests on one worker, even when a test failed in the first run.
+The suite fails when either run fails. The second run reports to
+`playwright-report/exclusive` and `test-results/exclusive`:
+
+```bash
+bunx playwright show-report playwright-report/exclusive
+```
+
+A plain `bunx playwright test` with `E2E_WORKERS` above 1 makes one run in which
+the twins depend on every other test: a failing test there leaves the exclusive
+tests not run, and selecting an exclusive test runs every other test first. Use
+`{{rootRun}} test:e2e` on more workers, and do not combine `--no-deps` with
+`E2E_WORKERS` above 1.
 
 Application-owned projects in `playwright.projects.cjs` get twins too. A project
 that another project depends on is a setup project and keeps a single copy.

package/dist/templates/fullstack/tests/helpers/seeded-admin.ts

@@ -0,0 +1,15 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The administrator the admin-dashboard Playwright setup seeds, with the address
+ * and password `accounts.ts` reads from `E2E_*` variables and the application's
+ * `app-accounts.ts`, or null in an app without that module. Specs of modules
+ * that do not require admin-dashboard sign in with this instead of importing
+ * `accounts.ts`, which only admin-dashboard installs.
+ */
+export async function seededAdmin(): Promise<{ email: string; password: string } | null> {
+  if (!existsSync(join(__dirname, "accounts.ts"))) return null;
+  const { ADMIN } = await import("./accounts");
+  return { email: ADMIN.email, password: ADMIN.password };
+}

package/dist/templates/fullstack/tests/package.json

@@ -3,9 +3,9 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "test:e2e": "bunx playwright test",
-    "test:e2e:ui": "bunx playwright test --project=ui --project=ui-exclusive",
-    "test:e2e:api": "bunx playwright test --project=api --project=api-exclusive",
+    "test:e2e": "bun run-e2e.ts",
+    "test:e2e:ui": "bun run-e2e.ts --project=ui --project=ui-exclusive",
+    "test:e2e:api": "bun run-e2e.ts --project=api --project=api-exclusive",
     "test:e2e:report": "bunx playwright show-report"
   },
   "devDependencies": {

package/dist/templates/fullstack/tests/playwright.config.ts

@@ -1,14 +1,15 @@
 import { defineConfig, devices } from "@playwright/test";
-import { e2eWorkers, loadPlaywrightProjects, withExclusivePhase } from "./playwright.extensions";
+import { e2eRunSettings, loadPlaywrightProjects, withExclusivePhase } from "./playwright.extensions";
 
 // The suite runs against a live stack: web on E2E_BASE_URL (proxying /api/* to
 // the API). Start it first (see docs/testing.md) — locally via the dev harness,
 // in CI via scripts/e2e-ci.mjs. Two projects: `api` (request-only, backend e2e)
 // and `ui` (chromium, pages). Files are routed by suffix (*.api/*.ui.spec.ts).
 // E2E_WORKERS sets the worker count (default 1); tests tagged @exclusive run in
-// `<project>-exclusive` twins after the others (see playwright.extensions.ts).
+// `<project>-exclusive` twins after the others, in a second run when run-e2e.ts
+// starts the suite on more workers (see playwright.extensions.ts).
 const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
-const workers = e2eWorkers();
+const run = e2eRunSettings();
 const coreProjects = [
   { name: "api", testMatch: /.*\.api\.spec\.ts/ },
   { name: "ui", testMatch: /.*\.ui\.spec\.ts/, use: { ...devices["Desktop Chrome"] } },
@@ -19,13 +20,14 @@ export default defineConfig({
   fullyParallel: true,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
-  workers,
+  workers: run.workers,
+  outputDir: run.outputDir,
   globalSetup: "./playwright.extensions.ts",
-  reporter: [["list"], ["html", { open: "never" }]],
+  reporter: [["list"], ["html", { open: "never", outputFolder: run.reportFolder }]],
   use: {
     baseURL,
     trace: "on-first-retry",
     screenshot: "only-on-failure",
   },
-  projects: withExclusivePhase([...coreProjects, ...loadPlaywrightProjects(coreProjects)], workers),
+  projects: withExclusivePhase([...coreProjects, ...loadPlaywrightProjects(coreProjects)], run.workers, run.phase),
 });

package/dist/templates/fullstack/tests/playwright.extensions.ts

@@ -17,6 +17,13 @@ const requireFromTests = createRequire(__filename);
 // the test's tags, separated by spaces.
 const TAGGED = /(?:^|\s)@exclusive(?=\s|$)/;
 const UNTAGGED = /^(?![\s\S]*(?:^|\s)@exclusive(?=\s|$))/;
+const EVERY_FILE = /.*/;
+
+/**
+ * One of the two Playwright runs `run-e2e.ts` makes with more than one worker:
+ * `shared` runs the tests not tagged `@exclusive`, `exclusive` the tagged ones.
+ */
+export type E2ePhase = "shared" | "exclusive";
 
 function projectName(project: unknown): string | null {
   if (typeof project !== "object" || project === null || !("name" in project)) return null;
@@ -69,29 +76,74 @@ export function e2eWorkers(value = process.env.E2E_WORKERS): number {
   return workers;
 }
 
+/** The run `run-e2e.ts` started, from `E2E_PHASE`, or undefined for a single run. */
+export function e2ePhase(value = process.env.E2E_PHASE): E2ePhase | undefined {
+  if (value === undefined || value === "") return undefined;
+  if (value === "shared" || value === "exclusive") return value;
+  throw new Error(`E2E_PHASE must be "shared" or "exclusive", got "${value}".`);
+}
+
+/**
+ * Workers and output folders for this Playwright run. The exclusive phase runs
+ * on one worker and keeps its results and HTML report in `exclusive/` folders,
+ * because each run empties its own.
+ */
+export function e2eRunSettings(
+  phase = e2ePhase(),
+  workers = e2eWorkers(),
+): { phase: E2ePhase | undefined; workers: number; outputDir: string; reportFolder: string } {
+  return phase === "exclusive"
+    ? { phase, workers: 1, outputDir: "test-results/exclusive", reportFolder: "playwright-report/exclusive" }
+    : { phase, workers, outputDir: "test-results", reportFolder: "playwright-report" };
+}
+
+/**
+ * The Playwright runs for `run-e2e.ts` with these command-line arguments. One
+ * worker needs a single run. With more workers, the tests not tagged
+ * `@exclusive` run first and the tagged ones second, in a run of their own that
+ * starts even when the first one failed. Either run may find no tests: a filter
+ * can select tests of one kind only, and an app may have no exclusive tests.
+ */
+export function e2eRuns(args: string[], workers = e2eWorkers()): Array<{ phase?: E2ePhase; args: string[] }> {
+  if (workers === 1) return [{ args }];
+  return [
+    { phase: "shared", args: args.length > 0 ? ["--pass-with-no-tests", ...args] : args },
+    { phase: "exclusive", args: ["--pass-with-no-tests", ...args] },
+  ];
+}
+
 /**
  * Splits each test project into one that skips tests tagged `@exclusive` and an
  * `<name>-exclusive` twin that runs only them on one worker. Projects that
  * another project depends on, or that tear one down, are setup and cleanup
  * projects and stay as they are.
  *
- * With more than one worker the twins depend on every other test project, and
- * each twin on the one before it, so an exclusive test never runs alongside
- * another test. A dependency runs in full, though: a run that selects only
- * exclusive tests, with a file, `--grep`, or `--project`, then also runs every
- * other test first, and a test that fails there skips the exclusive tests. Use
- * more than one worker for the whole suite. With one worker no dependency is
- * needed, so filtered runs stay small.
+ * With one worker no ordering is needed. With more, `run-e2e.ts` runs
+ * Playwright twice: in the `shared` phase the twins find no tests, and in the
+ * `exclusive` phase, on one worker, the other test projects find none. A single
+ * run with more than one worker (no phase) makes the twins depend on every
+ * other test project, and each twin on the one before it, so an exclusive test
+ * still never runs alongside another test; but there a failing test skips every
+ * twin after it, and a filter that selects exclusive tests runs all other tests
+ * first.
  */
-export function withExclusivePhase(projects: Projects, workers: number): Projects {
+export function withExclusivePhase(projects: Projects, workers: number, phase?: E2ePhase): Projects {
   const support = new Set(
     projects.flatMap((project) => [...(project.dependencies ?? []), ...(project.teardown ? [project.teardown] : [])]),
   );
   const tested = projects.filter((project) => !support.has(projectName(project) ?? ""));
   const shared = new Map(
-    tested.map((project) => [project, { ...project, grepInvert: [...patterns(project.grepInvert), TAGGED] }]),
+    tested.map((project) => [
+      project,
+      {
+        ...project,
+        grepInvert: [...patterns(project.grepInvert), TAGGED],
+        ...(phase === "exclusive" ? { testIgnore: EVERY_FILE } : {}),
+      },
+    ]),
   );
 
+  const chained = workers > 1 && phase === undefined;
   let before = [...shared.values()].map((project) => projectName(project) ?? "");
   const twins = tested.map((project) => {
     const name = `${projectName(project) ?? ""}-exclusive`;
@@ -100,7 +152,8 @@ export function withExclusivePhase(projects: Projects, workers: number): Project
       name,
       grepInvert: [...patterns(project.grepInvert), UNTAGGED],
       workers: 1,
-      dependencies: workers > 1 ? [...(project.dependencies ?? []), ...before] : project.dependencies,
+      dependencies: chained ? [...(project.dependencies ?? []), ...before] : project.dependencies,
+      ...(phase === "shared" ? { testIgnore: EVERY_FILE } : {}),
     };
     before = [name];
     return twin;
@@ -119,13 +172,21 @@ export function withExclusivePhase(projects: Projects, workers: number): Project
 /**
  * Global setup: refuses more workers than `E2E_WORKERS` allows for. `--workers`
  * changes the count after the projects were built, so with it the exclusive
- * twins would run alongside the other tests.
+ * twins would run alongside the other tests. Warns when more than one worker
+ * runs without `run-e2e.ts`, where a failing test skips the exclusive tests.
  */
-export default function checkWorkers(config: FullConfig): void {
+export default function checkWorkers(config: FullConfig, warn = console.warn): void {
   if (config.workers > 1 && e2eWorkers() === 1) {
     throw new Error(
       `Set the worker count with E2E_WORKERS=${config.workers} instead of --workers. ` +
         "Tests tagged @exclusive run after the others only when E2E_WORKERS is above 1.",
     );
   }
+  if (config.workers > 1 && e2ePhase() === undefined) {
+    warn(
+      "E2E_WORKERS is above 1 in a single Playwright run: a failing test makes Playwright skip " +
+        "the tests tagged @exclusive. Run the suite with `bun run test:e2e` (run-e2e.ts), which " +
+        "runs them in a second run instead.",
+    );
+  }
 }

package/dist/templates/fullstack/tests/run-e2e.ts

@@ -0,0 +1,28 @@
+import { spawnSync } from "node:child_process";
+import { e2eRuns } from "./playwright.extensions";
+
+// Runs the suite with the arguments it is given, such as `--grep` or a file.
+// With E2E_WORKERS above 1, Playwright runs twice: the tests not tagged
+// @exclusive on that many workers, then the tagged ones on one worker. The
+// second run starts even when the first one failed, so a failing test cannot
+// hide the exclusive tests, and the exit code is that of the first failed run.
+const runs = e2eRuns(process.argv.slice(2));
+let status = 0;
+for (const run of runs) {
+  if (run.phase) {
+    console.log(
+      run.phase === "shared"
+        ? "\nRunning the tests not tagged @exclusive\n"
+        : "\nRunning the tests tagged @exclusive on one worker (report: playwright-report/exclusive)\n",
+    );
+  }
+  const result = spawnSync("bunx", ["playwright", "test", ...run.args], {
+    stdio: "inherit",
+    env: run.phase ? { ...process.env, E2E_PHASE: run.phase } : process.env,
+  });
+  if (result.error) throw result.error;
+  // Playwright exits with 130 when it is interrupted: stop instead of starting the next run.
+  if (result.signal !== null || result.status === 130) process.exit(result.status ?? 130);
+  if (status === 0) status = result.status ?? 1;
+}
+process.exit(status);

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/nav.test.ts

@@ -13,8 +13,20 @@ vi.mock("./app-nav", async () => {
   };
 });
 
+// Stands in for the entries installed modules add to registry.svelte.ts, so the
+// expected order does not depend on which modules an application installs.
+vi.mock("./registry.svelte.js", async () => {
+  const { default: icon } = await import("@lucide/svelte/icons/newspaper");
+  return {
+    moduleNavEntries: [
+      { href: "/admin/blog", label: () => "Blog", icon, adminOnly: true },
+      { href: "/admin/reports", label: () => "Reports", icon },
+    ],
+  };
+});
+
 describe("admin navigation", () => {
-  it("places the application's entries before Settings", () => {
+  it("places the application's entries, then module entries, before Settings", () => {
     const hrefs = adminNavEntries({ auditLog: true }, "admin").map((entry) => entry.href);
 
     expect(hrefs).toEqual([
@@ -24,6 +36,8 @@ describe("admin navigation", () => {
       "/admin/audit",
       "/admin/specs",
       "/admin/help",
+      "/admin/blog",
+      "/admin/reports",
       "/admin/settings",
     ]);
     expect(adminNavEntries(undefined, "admin").find((entry) => entry.href === "/admin/specs")?.icon).toBe(
@@ -31,9 +45,9 @@ describe("admin navigation", () => {
     );
   });
 
-  it("hides admin-only application entries from other roles", () => {
+  it("hides admin-only application and module entries from other roles", () => {
     const hrefs = adminNavEntries(undefined, "moderator").map((entry) => entry.href);
 
-    expect(hrefs).toEqual(["/admin", "/admin/help"]);
+    expect(hrefs).toEqual(["/admin", "/admin/help", "/admin/reports"]);
   });
 });

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/theme-toggle.svelte

@@ -13,7 +13,7 @@
 <DropdownMenu.Root>
   <DropdownMenu.Trigger>
     {#snippet child({ props })}
-      <Button {...props} variant="ghost" size="icon" aria-label={i18n.t.theme.toggle}>
+      <Button {...props} variant="ghost" size="icon" aria-label={i18n.t.theme.toggle} data-testid="theme-toggle">
         <SunIcon class="size-4 dark:hidden" />
         <MoonIcon class="hidden size-4 dark:block" />
       </Button>

package/dist/templates/modules/admin-dashboard/files/tests/helpers/hydration.ts

@@ -1,9 +1,18 @@
 import type { Page } from "@playwright/test";
 
-// Wait for SvelteKit to attach client event handlers before driving forms. The
-// root layout adds this marker from onMount, so no fixed timing assumption is
-// needed even while the development server compiles a route for the first time.
+/**
+ * Waits until SvelteKit has attached the current document's event handlers. The
+ * root layout adds this marker from onMount, so no fixed timing assumption is
+ * needed even while the development server compiles a route for the first time.
+ * Call it after `page.reload()` too: the reloaded document is visible, and
+ * clickable, before its handlers exist, so an early click does nothing.
+ */
+export async function hydrated(page: Page): Promise<void> {
+  await page.locator('html[data-hydrated="true"]').waitFor();
+}
+
+/** Opens `path` and waits for hydration before a test drives the page. */
 export async function ready(page: Page, path: string): Promise<void> {
   await page.goto(path);
-  await page.locator('html[data-hydrated="true"]').waitFor();
+  await hydrated(page);
 }

package/dist/templates/modules/admin-dashboard/files/tests/playwright.config.ts

@@ -1,5 +1,5 @@
 import { defineConfig, devices } from "@playwright/test";
-import { e2eWorkers, loadPlaywrightProjects, withExclusivePhase } from "./playwright.extensions";
+import { e2eRunSettings, loadPlaywrightProjects, withExclusivePhase } from "./playwright.extensions";
 
 // admin-dashboard overlay: adds a `setup` project that seeds admin/user sessions
 // (storageState) which the `ui` project reuses, and a `cleanup` project that
@@ -7,9 +7,10 @@ import { e2eWorkers, loadPlaywrightProjects, withExclusivePhase } from "./playwr
 // E2E_BASE_URL. Tests share one backend and database: E2E_WORKERS sets the
 // worker count (default 1), and tests tagged @exclusive, which change state the
 // others rely on, run one at a time in `<project>-exclusive` twins after the
-// others (see playwright.extensions.ts). Each file runs on one worker in order.
+// others, in a second run when run-e2e.ts starts the suite on more workers (see
+// playwright.extensions.ts). Each file runs on one worker in order.
 const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
-const workers = e2eWorkers();
+const run = e2eRunSettings();
 const coreProjects = [
   { name: "api", testMatch: /.*\.api\.spec\.ts/, dependencies: ["setup"] },
   { name: "setup", testMatch: /.*\.setup\.ts/, teardown: "cleanup" },
@@ -27,9 +28,10 @@ export default defineConfig({
   fullyParallel: false,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
-  workers,
+  workers: run.workers,
+  outputDir: run.outputDir,
   globalSetup: "./playwright.extensions.ts",
-  reporter: [["list"], ["html", { open: "never" }]],
+  reporter: [["list"], ["html", { open: "never", outputFolder: run.reportFolder }]],
   use: { baseURL, trace: "on-first-retry", screenshot: "only-on-failure" },
-  projects: withExclusivePhase([...coreProjects, ...loadPlaywrightProjects(coreProjects)], workers),
+  projects: withExclusivePhase([...coreProjects, ...loadPlaywrightProjects(coreProjects)], run.workers, run.phase),
 });

package/dist/templates/modules/admin-dashboard/files/tests/ui/theme-mode.ui.spec.ts

@@ -1,29 +1,35 @@
-import { expect, test } from "@playwright/test";
-import { ready } from "../helpers/hydration";
+import { expect, test, type Page } from "@playwright/test";
+import { hydrated, ready } from "../helpers/hydration";
+import { paths } from "../helpers/paths";
+
+async function chooseTheme(page: Page, mode: "Light" | "Dark" | "System"): Promise<void> {
+  await page.getByTestId("theme-toggle").click();
+  await page.getByRole("menuitem", { name: mode }).click();
+}
 
 // mode-watcher marks <html> with `.dark` or `.light`, so component libraries
 // that follow either class, and fall back to the OS setting otherwise, match the
-// theme the visitor chose rather than the system one.
+// theme the visitor chose rather than the system one. The managed ThemeToggle
+// renders on the page app-paths.ts names as the account menu page.
 test("the chosen theme is named on <html> in both modes", async ({ page }) => {
+  test.skip(paths.accountMenu === null, "no page renders the theme toggle (tests/helpers/app-paths.ts)");
   await page.emulateMedia({ colorScheme: "dark" });
-  await ready(page, "/account");
+  await ready(page, paths.accountMenu ?? "/");
   const html = page.locator("html");
 
-  await page.getByRole("button", { name: "Toggle theme" }).click();
-  await page.getByRole("menuitem", { name: "Light" }).click();
+  await chooseTheme(page, "Light");
   await expect(html).toHaveClass(/(^|\s)light(\s|$)/);
   await expect(html).not.toHaveClass(/(^|\s)dark(\s|$)/);
 
   // The class is set before the page renders, not only after a choice.
   await page.reload();
   await expect(html).toHaveClass(/(^|\s)light(\s|$)/);
+  await hydrated(page);
 
-  await page.getByRole("button", { name: "Toggle theme" }).click();
-  await page.getByRole("menuitem", { name: "Dark" }).click();
+  await chooseTheme(page, "Dark");
   await expect(html).toHaveClass(/(^|\s)dark(\s|$)/);
   await expect(html).not.toHaveClass(/(^|\s)light(\s|$)/);
 
-  await page.getByRole("button", { name: "Toggle theme" }).click();
-  await page.getByRole("menuitem", { name: "System" }).click();
+  await chooseTheme(page, "System");
   await expect(html).toHaveClass(/(^|\s)dark(\s|$)/);
 });

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/bullmq-job.queue.spec.ts

@@ -136,6 +136,9 @@ describe("BullMqJobQueue schedules", () => {
       await expect(queue.schedule("bad", "report", {}, { cron: "61 * * * *" })).rejects.toThrow();
       await expect(queue.schedule("bad", "report", {}, { cron: "0 3 * * *", timezone: "Mars/Olympus" })).rejects.toThrow();
       await expect(queue.schedule("bad", "report", {}, { everyMs: 10 })).rejects.toThrow("at least 1000");
+      await expect(queue.schedule("bad", "report", {}, { everyMs: 1_000 }, { keepFailed: 1.5 })).rejects.toThrow(
+        "keepFailed must be a whole number of at least 0",
+      );
     } finally {
       await queue.close();
     }
@@ -183,4 +186,51 @@ describe.skipIf(!process.env.REDIS_URL && !process.env.REDIS_HOST)("BullMqJobQue
       await inspect.close();
     }
   });
+
+  it("limits the finished jobs a schedule's runs leave, 100 completed and 1000 failed by default", async () => {
+    const name = `schedule-test-${crypto.randomUUID()}`;
+    const queue = new BullMqJobQueue(producerConnection(REDIS));
+    const inspect = new Queue(name, { connection: redisConnection(REDIS) });
+    try {
+      await queue.connect();
+      await queue.schedule("default", name, {}, { cron: "0 3 * * *" });
+      await queue.schedule("custom", name, {}, { everyMs: 3_600_000 }, { keepCompleted: 0, keepFailed: 20 });
+      expect((await inspect.getJobScheduler("default"))?.template?.opts).toMatchObject({
+        removeOnComplete: { count: 100 },
+        removeOnFail: { count: 1_000 },
+      });
+      expect((await inspect.getJobScheduler("custom"))?.template?.opts).toMatchObject({
+        removeOnComplete: { count: 0 },
+        removeOnFail: { count: 20 },
+      });
+    } finally {
+      await queue.close();
+      await inspect.obliterate({ force: true });
+      await inspect.close();
+    }
+  });
+
+  it("removes finished runs beyond the schedule's limits", async () => {
+    const name = `schedule-test-${crypto.randomUUID()}`;
+    const queue = new BullMqJobQueue(producerConnection(REDIS));
+    const inspect = new Queue(name, { connection: redisConnection(REDIS) });
+    let runs = 0;
+    try {
+      await queue.connect();
+      await queue.process(name, () => {
+        runs += 1;
+        if (runs % 2 === 0) throw new Error("expected failure");
+      });
+      await queue.schedule("tick", name, {}, { everyMs: 1_000 }, { keepCompleted: 1, keepFailed: 1 });
+      for (let waited = 0; runs < 4 && waited < 10_000; waited += 100) await Bun.sleep(100);
+      expect(runs).toBeGreaterThanOrEqual(4);
+      // The last run's job moves to its finished set just after the handler returns.
+      await Bun.sleep(200);
+      expect(await inspect.getJobCounts("completed", "failed")).toEqual({ completed: 1, failed: 1 });
+    } finally {
+      await queue.close();
+      await inspect.obliterate({ force: true });
+      await inspect.close();
+    }
+  }, 15_000);
 });

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/bullmq-job.queue.ts

@@ -10,6 +10,9 @@ import {
   type JobSnapshot,
   type JobStatus,
   type RepeatOptions,
+  type ScheduleOptions,
+  type ScheduleRetention,
+  scheduleRetention,
   type Unsubscribe,
 } from "@podosoft/podokit-runtime";
 import type { SupervisedConnection } from "../core/services";
@@ -56,6 +59,7 @@ interface Schedule {
   name: string;
   payload: unknown;
   repeat: RepeatOptions;
+  retention: ScheduleRetention;
 }
 
 /** Rejects a schedule BullMQ could not run, before it is kept. */
@@ -141,13 +145,20 @@ export class BullMqJobQueue implements JobQueue, SupervisedConnection {
     };
   }
 
-  async schedule(id: string, name: string, payload: unknown, repeat: RepeatOptions): Promise<void> {
+  async schedule(
+    id: string,
+    name: string,
+    payload: unknown,
+    repeat: RepeatOptions,
+    options?: ScheduleOptions,
+  ): Promise<void> {
     assertSchedule(repeat);
+    const retention = scheduleRetention(options);
     const previous = this.schedules.get(id);
     // A scheduler lives in its queue, so a schedule that moves leaves the old one.
     if (previous && previous.name !== name) this.removals.set(id, previous.name);
     if (this.removals.get(id) === name) this.removals.delete(id);
-    this.schedules.set(id, { name, payload, repeat });
+    this.schedules.set(id, { name, payload, repeat, retention });
     await this.whenConnected(async (client) => {
       if (this.removals.has(id)) await this.removeSchedule(client, id);
       await this.applySchedule(client, id);
@@ -196,10 +207,19 @@ export class BullMqJobQueue implements JobQueue, SupervisedConnection {
     const schedule = this.schedules.get(id);
     if (!schedule) return;
     const { cron, everyMs, timezone } = schedule.repeat;
+    // A count above 0 trims the queue's whole completed or failed set to that
+    // many jobs; 0 removes only the finished run.
     await this.queue(schedule.name, client).upsertJobScheduler(
       id,
       cron !== undefined ? { pattern: cron, tz: timezone ?? "UTC" } : { every: everyMs },
-      { name: schedule.name, data: schedule.payload },
+      {
+        name: schedule.name,
+        data: schedule.payload,
+        opts: {
+          removeOnComplete: { count: schedule.retention.keepCompleted },
+          removeOnFail: { count: schedule.retention.keepFailed },
+        },
+      },
     );
   }
 

package/dist/templates/modules/jobs-local/files/apps/api/src/jobs-local/local-job.queue.spec.ts

@@ -149,6 +149,93 @@ describe("local job schedules", () => {
     await expect(queue.schedule("bad", "report", {}, { cron: "61 * * * *" })).rejects.toThrow();
     await expect(queue.schedule("bad", "report", {}, { cron: "0 3 * * *", timezone: "Mars/Olympus" })).rejects.toThrow();
     await expect(queue.schedule("bad", "report", {}, { everyMs: 10 })).rejects.toThrow("at least 1000");
+    await expect(queue.schedule("bad", "report", {}, { everyMs: 1_000 }, { keepCompleted: -1 })).rejects.toThrow(
+      "keepCompleted must be a whole number of at least 0",
+    );
+    queue.close();
+  });
+});
+
+/** Moves the clock to each time and runs the job the schedule added then. */
+async function runScheduled(queue: LocalJobQueue, time: ReturnType<typeof manualTime>, times: number[]): Promise<void> {
+  for (const at of times) {
+    time.advance(at);
+    // The schedule adds its job without waiting; let the insert finish.
+    await Bun.sleep(1);
+    expect(await queue.runOnce()).toBe(true);
+  }
+}
+
+async function finishedJobs(database: SQL): Promise<string[]> {
+  const rows = await database<Array<{ id: string; status: string }>>`
+    SELECT "id", "status" FROM "podokit_job" ORDER BY "updatedAt", "id"
+  `;
+  return rows.map((row) => `${row.id} ${row.status}`);
+}
+
+describe("local job schedule cleanup", () => {
+  it("keeps the newest finished jobs of a scheduled run's name up to the schedule's limits", async () => {
+    sql = new SQL(":memory:");
+    const time = manualTime(0);
+    const queue = new LocalJobQueue(sql, { pollIntervalMs: 60_000, now: time.now, timer: time.timer });
+    await queue.process("report", (_payload, job) => {
+      if (job.id.endsWith(":3000") || job.id.endsWith(":5000")) throw new Error("expected failure");
+    });
+    await queue.process("other", () => undefined);
+    const other = await queue.enqueue("other", {});
+    const adHoc = await queue.enqueue("report", {});
+    while (await queue.runOnce());
+    await queue.schedule("tick", "report", {}, { everyMs: 1_000 }, { keepCompleted: 2, keepFailed: 1 });
+    await queue.start();
+    await Bun.sleep(5);
+
+    await runScheduled(queue, time, [1_000, 2_000, 3_000, 4_000, 5_000, 6_000]);
+
+    // As BullMQ trims a queue: the job enqueue() added goes too, another name's stays.
+    expect(await finishedJobs(sql)).toEqual([
+      `${other.id} completed`,
+      "report:schedule:tick:4000 completed",
+      "report:schedule:tick:5000 failed",
+      "report:schedule:tick:6000 completed",
+    ]);
+    expect(await queue.get(adHoc.id)).toBeNull();
+    queue.close();
+  });
+
+  it("removes only the run itself when a limit is 0", async () => {
+    sql = new SQL(":memory:");
+    const time = manualTime(0);
+    const queue = new LocalJobQueue(sql, { pollIntervalMs: 60_000, now: time.now, timer: time.timer });
+    await queue.process("report", (_payload, job) => {
+      if (job.id.endsWith(":2000")) throw new Error("expected failure");
+    });
+    const adHoc = await queue.enqueue("report", {});
+    while (await queue.runOnce());
+    await queue.schedule("tick", "report", {}, { everyMs: 1_000 }, { keepCompleted: 0, keepFailed: 0 });
+    await queue.start();
+    await Bun.sleep(5);
+
+    await runScheduled(queue, time, [1_000, 2_000, 3_000]);
+
+    expect(await finishedJobs(sql)).toEqual([`${adHoc.id} completed`]);
+    queue.close();
+  });
+
+  it("keeps 100 completed runs of a schedule by default", async () => {
+    sql = new SQL(":memory:");
+    const time = manualTime(0);
+    const queue = new LocalJobQueue(sql, { pollIntervalMs: 60_000, now: time.now, timer: time.timer });
+    await queue.process("report", () => undefined);
+    await queue.schedule("tick", "report", {}, { everyMs: 1_000 });
+    await queue.start();
+    await Bun.sleep(5);
+
+    await runScheduled(queue, time, Array.from({ length: 105 }, (_, index) => (index + 1) * 1_000));
+
+    const kept = await finishedJobs(sql);
+    expect(kept).toHaveLength(100);
+    expect(kept[0]).toBe("report:schedule:tick:6000 completed");
+    expect(kept.at(-1)).toBe("report:schedule:tick:105000 completed");
     queue.close();
   });
 });

package/dist/templates/modules/jobs-local/files/apps/api/src/jobs-local/local-job.queue.ts

@@ -9,6 +9,9 @@ import {
   type JobSnapshot,
   type JobStatus,
   type RepeatOptions,
+  type ScheduleOptions,
+  type ScheduleRetention,
+  scheduleRetention,
   type Unsubscribe,
 } from "@podosoft/podokit-runtime";
 
@@ -42,9 +45,15 @@ interface Schedule {
   name: string;
   payload: unknown;
   repeat: RepeatOptions;
+  retention: ScheduleRetention;
   cancel?: () => void;
 }
 
+type FinishedStatus = "completed" | "failed";
+
+// A scheduled job's deduplication key: this prefix, the schedule id, ":", and the time.
+const SCHEDULE_KEY = "schedule:";
+
 // setTimeout fires at once for a delay above 2^31 - 1 ms, so longer waits are split.
 const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
 
@@ -160,13 +169,20 @@ export class LocalJobQueue implements JobQueue {
     });
   }
 
-  async schedule(id: string, name: string, payload: unknown, repeat: RepeatOptions): Promise<void> {
+  async schedule(
+    id: string,
+    name: string,
+    payload: unknown,
+    repeat: RepeatOptions,
+    options?: ScheduleOptions,
+  ): Promise<void> {
     assertRepeatOptions(repeat);
+    const retention = scheduleRetention(options);
     // Rejects an invalid cron expression or time zone now rather than at the first run.
     nextScheduledTime(repeat, this.now());
     if (JSON.stringify(payload) === undefined) throw new Error("Job payload must be JSON serializable");
     this.schedules.get(id)?.cancel?.();
-    const schedule: Schedule = { id, name, payload, repeat };
+    const schedule: Schedule = { id, name, payload, repeat, retention };
     this.schedules.set(id, schedule);
     if (this.started) this.arm(schedule);
   }
@@ -205,6 +221,7 @@ export class LocalJobQueue implements JobQueue {
         SET "status" = 'completed', "updatedAt" = ${completedAt}, "error" = NULL
         WHERE "id" = ${row.id}
       `;
+      await this.removeFinished(row, "completed");
     } catch (error) {
       await this.fail(row, error);
     }
@@ -227,7 +244,7 @@ export class LocalJobQueue implements JobQueue {
     const at = nextScheduledTime(schedule.repeat, after);
     schedule.cancel = this.waitUntil(at, () => {
       if (!this.started || this.schedules.get(schedule.id) !== schedule) return;
-      void this.enqueue(schedule.name, schedule.payload, { deduplicationKey: `schedule:${schedule.id}:${at}` })
+      void this.enqueue(schedule.name, schedule.payload, { deduplicationKey: `${SCHEDULE_KEY}${schedule.id}:${at}` })
         .catch((error: unknown) => {
           const message = error instanceof Error ? error.message : String(error);
           process.stderr.write(`Add scheduled job failed: ${schedule.id} ${message}\n`);
@@ -269,6 +286,45 @@ export class LocalJobQueue implements JobQueue {
       CREATE INDEX IF NOT EXISTS "podokit_job_pending"
       ON "podokit_job" ("status", "availableAt", "createdAt")
     `;
+    await this.sql`
+      CREATE INDEX IF NOT EXISTS "podokit_job_finished"
+      ON "podokit_job" ("name", "status", "updatedAt")
+    `;
+  }
+
+  /** The schedule whose job id `row` has, while that schedule is kept. */
+  private scheduleOf(row: JobRow): Schedule | undefined {
+    for (const schedule of this.schedules.values()) {
+      const prefix = `${schedule.name}:${SCHEDULE_KEY}${schedule.id}:`;
+      if (schedule.name === row.name && row.id.startsWith(prefix) && /^\d+$/.test(row.id.slice(prefix.length))) {
+        return schedule;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * After a scheduled run finishes, keeps the newest finished jobs of its name
+   * up to the schedule's limit, as BullMQ trims a queue, or removes only the
+   * run when the limit is 0.
+   */
+  private async removeFinished(row: JobRow, status: FinishedStatus): Promise<void> {
+    const schedule = this.scheduleOf(row);
+    if (!schedule) return;
+    const keep = status === "completed" ? schedule.retention.keepCompleted : schedule.retention.keepFailed;
+    if (keep === 0) {
+      await this.sql`DELETE FROM "podokit_job" WHERE "id" = ${row.id}`;
+      return;
+    }
+    await this.sql`
+      DELETE FROM "podokit_job"
+      WHERE "name" = ${row.name} AND "status" = ${status} AND "id" NOT IN (
+        SELECT "id" FROM "podokit_job"
+        WHERE "name" = ${row.name} AND "status" = ${status}
+        ORDER BY "updatedAt" DESC, "id" DESC
+        LIMIT ${keep}
+      )
+    `;
   }
 
   private poll(delay: number): void {
@@ -296,6 +352,7 @@ export class LocalJobQueue implements JobQueue {
           "error" = ${message.slice(0, 2_000)}
       WHERE "id" = ${row.id}
     `;
+    if (!retry) await this.removeFinished(row, "failed");
   }
 
   private snapshot(row: JobRow): JobSnapshot {

package/dist/templates/modules/object-storage-local/files/tests/api/storage-local.api.spec.ts

@@ -1,13 +1,8 @@
 import { expect, test, type APIRequestContext, type PlaywrightWorkerArgs } from "@playwright/test";
+import { seededAdmin } from "../helpers/seeded-admin";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
-// The administrator seeded by the admin-dashboard Playwright setup. Inlined so this
-// spec also compiles in apps that do not install that module.
-const admin = {
-  email: process.env.E2E_ADMIN_EMAIL || "admin@example.com",
-  password: process.env.E2E_ADMIN_PASSWORD || "Podokit3e-Str0ng!pw",
-};
 
 type Playwright = PlaywrightWorkerArgs["playwright"];
 
@@ -36,6 +31,8 @@ async function signUp(ctx: APIRequestContext): Promise<boolean> {
 
 /** Resolves false when no administrator session is available. */
 async function signInAdmin(ctx: APIRequestContext): Promise<boolean> {
+  const admin = await seededAdmin();
+  if (!admin) return false;
   const response = await ctx.post("/api/auth/sign-in/email", { data: admin });
   return response.ok() && ((await sessionRoles(ctx)) ?? []).includes("admin");
 }

package/dist/templates/modules/object-storage-s3/files/tests/api/storage.api.spec.ts

@@ -1,13 +1,8 @@
 import { expect, test, type APIRequestContext, type PlaywrightWorkerArgs } from "@playwright/test";
+import { seededAdmin } from "../helpers/seeded-admin";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
-// The administrator seeded by the admin-dashboard Playwright setup. Inlined so this
-// spec also compiles in apps that do not install that module.
-const admin = {
-  email: process.env.E2E_ADMIN_EMAIL || "admin@example.com",
-  password: process.env.E2E_ADMIN_PASSWORD || "Podokit3e-Str0ng!pw",
-};
 
 type Playwright = PlaywrightWorkerArgs["playwright"];
 
@@ -36,6 +31,8 @@ async function signUp(ctx: APIRequestContext): Promise<boolean> {
 
 /** Resolves false when no administrator session is available. */
 async function signInAdmin(ctx: APIRequestContext): Promise<boolean> {
+  const admin = await seededAdmin();
+  if (!admin) return false;
   const response = await ctx.post("/api/auth/sign-in/email", { data: admin });
   return response.ok() && ((await sessionRoles(ctx)) ?? []).includes("admin");
 }

package/dist/templates/modules/sse/files/tests/api/events.api.spec.ts

@@ -1,14 +1,9 @@
 import { expect, test, type APIRequestContext, type PlaywrightWorkerArgs } from "@playwright/test";
+import { seededAdmin } from "../helpers/seeded-admin";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const secondaryApi = process.env.E2E_SECONDARY_API_URL;
 const origin = { origin: base };
-// The administrator seeded by the admin-dashboard Playwright setup. Inlined so this
-// spec also compiles in apps that do not install that module.
-const admin = {
-  email: process.env.E2E_ADMIN_EMAIL || "admin@example.com",
-  password: process.env.E2E_ADMIN_PASSWORD || "Podokit3e-Str0ng!pw",
-};
 
 type Playwright = PlaywrightWorkerArgs["playwright"];
 
@@ -39,6 +34,8 @@ async function signUp(ctx: APIRequestContext): Promise<SessionUser | undefined>
 
 /** Resolves false when no administrator session is available. */
 async function signInAdmin(ctx: APIRequestContext): Promise<boolean> {
+  const admin = await seededAdmin();
+  if (!admin) return false;
   const response = await ctx.post("/api/auth/sign-in/email", { data: admin });
   return response.ok() && ((await sessionUser(ctx))?.roles ?? []).includes("admin");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "An opinionated Bun and Elysia full-stack TypeScript starter toolkit and CLI with SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {
@@ -45,7 +45,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@podosoft/podokit-runtime": "^0.5.0",
+    "@podosoft/podokit-runtime": "^0.5.1",
     "@podosoft/podokit-template-engine": "^0.4.2"
   }
 }