@podosoft/podokit 1.4.2 → 1.6.0

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

@@ -1,13 +1,16 @@
 import { AppException } from "@podosoft/podokit-contracts";
 import { Queue, RedisConnection, Worker, type ConnectionOptions, type RedisClient } from "bullmq";
-import type {
-  EnqueueOptions,
-  JobHandler,
-  JobQueue,
-  JobReference,
-  JobSnapshot,
-  JobStatus,
-  Unsubscribe,
+import cronParser from "cron-parser";
+import {
+  assertRepeatOptions,
+  type EnqueueOptions,
+  type JobHandler,
+  type JobQueue,
+  type JobReference,
+  type JobSnapshot,
+  type JobStatus,
+  type RepeatOptions,
+  type Unsubscribe,
 } from "@podosoft/podokit-runtime";
 import type { SupervisedConnection } from "../core/services";
 import { producerConnection, redisConnection } from "./queue";
@@ -45,6 +48,24 @@ export function jobsUnavailable(): AppException {
   return new AppException("JOBS_UNAVAILABLE", "Background jobs are temporarily unavailable.", 503);
 }
 
+function isJobsUnavailable(error: unknown): boolean {
+  return error instanceof AppException && error.code === "JOBS_UNAVAILABLE";
+}
+
+interface Schedule {
+  name: string;
+  payload: unknown;
+  repeat: RepeatOptions;
+}
+
+/** Rejects a schedule BullMQ could not run, before it is kept. */
+function assertSchedule(repeat: RepeatOptions): void {
+  assertRepeatOptions(repeat);
+  if (repeat.cron !== undefined) {
+    cronParser.parseExpression(repeat.cron, { tz: repeat.timezone ?? "UTC" }).next();
+  }
+}
+
 /**
  * Adds and reads jobs over one producer connection that the service registry
  * supervises, and runs in-process handlers on BullMQ workers, which keep their
@@ -53,6 +74,9 @@ export function jobsUnavailable(): AppException {
 export class BullMqJobQueue implements JobQueue, SupervisedConnection {
   private readonly queues = new Map<string, Queue>();
   private readonly workers = new Map<string, Worker>();
+  private readonly schedules = new Map<string, Schedule>();
+  // Schedules to delete from Redis once it is reachable: id to queue name.
+  private readonly removals = new Map<string, string>();
   private producer: RedisConnection;
   private lostListener?: (reason: unknown) => void;
   private closed = false;
@@ -65,10 +89,17 @@ export class BullMqJobQueue implements JobQueue, SupervisedConnection {
     this.lostListener = listener;
   }
 
-  /** Opens the producer connection. */
+  /**
+   * Opens the producer connection and applies every schedule, so a Redis that
+   * lost them, such as one restarted without persistence, gets them back.
+   */
   async connect(): Promise<void> {
     const client = await this.producer.client;
     if (client.status !== "ready") await client.connect();
+    await this.command(async (ready) => {
+      for (const id of [...this.removals.keys()]) await this.removeSchedule(ready, id);
+      for (const id of this.schedules.keys()) await this.applySchedule(ready, id);
+    });
   }
 
   /** Rejects while Redis is unreachable or slower to answer than `REDIS_COMMAND_TIMEOUT_MS`. */
@@ -110,6 +141,27 @@ export class BullMqJobQueue implements JobQueue, SupervisedConnection {
     };
   }
 
+  async schedule(id: string, name: string, payload: unknown, repeat: RepeatOptions): Promise<void> {
+    assertSchedule(repeat);
+    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 });
+    await this.whenConnected(async (client) => {
+      if (this.removals.has(id)) await this.removeSchedule(client, id);
+      await this.applySchedule(client, id);
+    });
+  }
+
+  async unschedule(id: string): Promise<void> {
+    const schedule = this.schedules.get(id);
+    if (!schedule) return;
+    this.schedules.delete(id);
+    this.removals.set(id, schedule.name);
+    await this.whenConnected((client) => this.removeSchedule(client, id));
+  }
+
   process(name: string, handler: JobHandler): Promise<Unsubscribe> {
     if (this.workers.has(name)) throw new Error(`A handler is already registered for job ${name}`);
     const worker = new Worker(
@@ -140,6 +192,38 @@ export class BullMqJobQueue implements JobQueue, SupervisedConnection {
     await this.producer.close(true);
   }
 
+  private async applySchedule(client: RedisClient, id: string): Promise<void> {
+    const schedule = this.schedules.get(id);
+    if (!schedule) return;
+    const { cron, everyMs, timezone } = schedule.repeat;
+    await this.queue(schedule.name, client).upsertJobScheduler(
+      id,
+      cron !== undefined ? { pattern: cron, tz: timezone ?? "UTC" } : { every: everyMs },
+      { name: schedule.name, data: schedule.payload },
+    );
+  }
+
+  private async removeSchedule(client: RedisClient, id: string): Promise<void> {
+    const name = this.removals.get(id);
+    if (name === undefined) return;
+    await this.queue(name, client).removeJobScheduler(id);
+    if (this.removals.get(id) === name) this.removals.delete(id);
+  }
+
+  /**
+   * Runs `send` while the producer is connected. Otherwise, or when Redis goes
+   * away during it, the next connect() applies the change instead.
+   */
+  private async whenConnected(send: (client: RedisClient) => Promise<void>): Promise<void> {
+    const client = await this.producer.client;
+    if (client.status !== "ready") return;
+    try {
+      await this.command(send);
+    } catch (error) {
+      if (!isJobsUnavailable(error)) throw error;
+    }
+  }
+
   /**
    * Runs `send` on the producer connection and fails it with JOBS_UNAVAILABLE
    * while the connection is closed or when Redis does not answer in time.

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/worker.module.spec.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "bun:test";
+import type { Processor } from "bullmq";
+import { DEMO_QUEUE } from "./queue";
+import { collectWorkers, type WorkerDefinition } from "./worker.module";
+
+const processor: Processor = async () => undefined;
+
+describe("worker definitions", () => {
+  it("adds the application's queues after PodoKit's and releases them last first", async () => {
+    const released: string[] = [];
+    const collected = await collectWorkers(async (setup) => {
+      setup.onClose(() => { released.push("database"); });
+      setup.onClose(async () => { released.push("cache"); });
+      return [{ queue: "reports", processor, options: { concurrency: 2 } }];
+    });
+    expect(collected.definitions.map((definition) => definition.queue)).toEqual([DEMO_QUEUE, "reports"]);
+    expect(collected.definitions[1]?.options).toEqual({ concurrency: 2 });
+    await collected.release();
+    expect(released).toEqual(["cache", "database"]);
+  });
+
+  it("refuses two workers for one queue and releases what was opened", async () => {
+    const released: string[] = [];
+    const duplicate: WorkerDefinition = { queue: DEMO_QUEUE, processor };
+    await expect(collectWorkers(async (setup) => {
+      setup.onClose(() => { released.push("database"); });
+      return [duplicate];
+    })).rejects.toThrow(`More than one worker for queue ${DEMO_QUEUE}`);
+    expect(released).toEqual(["database"]);
+  });
+
+  it("releases what was opened when the application setup fails", async () => {
+    const released: string[] = [];
+    await expect(collectWorkers(async (setup) => {
+      setup.onClose(() => { released.push("database"); });
+      throw new Error("no database");
+    })).rejects.toThrow("no database");
+    expect(released).toEqual(["database"]);
+  });
+});

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/worker.module.ts

@@ -1,12 +1,25 @@
-import { Worker, type Processor } from "bullmq";
+import { Worker, type Processor, type WorkerOptions } from "bullmq";
+import { configureWorkers } from "../worker.extensions";
 import { processDemoJob } from "./demo.processor";
 import { DEMO_QUEUE, redisConnection } from "./queue";
 // podokit:begin:worker-imports
 // podokit:end:worker-imports
 
-interface WorkerDefinition {
+export interface WorkerDefinition {
   queue: string;
   processor: Processor;
+  /** BullMQ worker options other than the connection, such as `concurrency`. */
+  options?: Omit<WorkerOptions, "connection">;
+}
+
+export interface WorkerSetup {
+  /** Runs `close` when the worker process stops, after its workers; the last one registered runs first. */
+  onClose(close: () => void | Promise<void>): void;
+}
+
+export interface WorkerRuntime {
+  workers: Worker[];
+  close(): Promise<void>;
 }
 
 const definitions: WorkerDefinition[] = [
@@ -15,8 +28,42 @@ const definitions: WorkerDefinition[] = [
   // podokit:end:worker-processors
 ];
 
-export function startWorkers(): Worker[] {
-  return definitions.map(({ queue, processor }) =>
-    new Worker(queue, processor, { connection: redisConnection() })
+export interface CollectedWorkers {
+  definitions: WorkerDefinition[];
+  /** Releases what `configure` opened. */
+  release(): Promise<void>;
+}
+
+/** PodoKit's queues followed by the application's from worker.extensions.ts; one worker per queue. */
+export async function collectWorkers(
+  configure: (setup: WorkerSetup) => Promise<WorkerDefinition[]> = configureWorkers,
+): Promise<CollectedWorkers> {
+  const closers: Array<() => void | Promise<void>> = [];
+  const release = async (): Promise<void> => {
+    for (const close of closers.splice(0).reverse()) await close();
+  };
+  try {
+    const all = [...definitions, ...await configure({ onClose: (close) => closers.push(close) })];
+    const queues = all.map((definition) => definition.queue);
+    const repeated = queues.filter((queue, index) => queues.indexOf(queue) !== index);
+    if (repeated.length > 0) throw new Error(`More than one worker for queue ${[...new Set(repeated)].join(", ")}`);
+    return { definitions: all, release };
+  } catch (error) {
+    await release();
+    throw error;
+  }
+}
+
+export async function startWorkers(): Promise<WorkerRuntime> {
+  const { definitions: all, release } = await collectWorkers();
+  const workers = all.map(({ queue, processor, options }) =>
+    new Worker(queue, processor, { ...options, connection: redisConnection() })
   );
+  return {
+    workers,
+    close: async (): Promise<void> => {
+      await Promise.all(workers.map((worker) => worker.close()));
+      await release();
+    },
+  };
 }

package/dist/templates/modules/bullmq/files/apps/api/src/main-worker.ts

@@ -6,16 +6,18 @@ if (PROVIDERS.jobs !== "bullmq") {
   throw new Error("The BullMQ worker cannot start unless jobs=bullmq is selected");
 }
 
-const workers = startWorkers();
+const runtime = startWorkers();
 
-for (const worker of workers) {
-  worker.on("failed", (job, error) => {
-    process.stderr.write(`Process job failed: ${job?.id ?? "unknown"} ${error.message}\n`);
-  });
-}
+void runtime.then(({ workers }) => {
+  for (const worker of workers) {
+    worker.on("failed", (job, error) => {
+      process.stderr.write(`Process job failed: ${job?.id ?? "unknown"} ${error.message}\n`);
+    });
+  }
+});
 
 for (const signal of ["SIGINT", "SIGTERM"] as const) {
   process.once(signal, () => {
-    void Promise.all(workers.map((worker) => worker.close())).finally(() => process.exit(0));
+    void runtime.then((started) => started.close()).finally(() => process.exit(0));
   });
 }

package/dist/templates/modules/bullmq/files/apps/api/src/worker.extensions.ts

@@ -0,0 +1,13 @@
+import type { WorkerDefinition, WorkerSetup } from "./jobs/worker.module";
+
+// This owned file is never overwritten by `podo update`. Return the queues the
+// BullMQ worker process (`main-worker.ts`) consumes for the application, next to
+// PodoKit's. Open what the processors need here and release it with
+// `setup.onClose`, which runs after the workers stop. For example:
+//
+//   const database = new Database(validateEnv(process.env));
+//   setup.onClose(() => database.close());
+//   return [{ queue: "reports", processor: (job) => buildReport(database, job.data), options: { concurrency: 2 } }];
+export async function configureWorkers(_setup: WorkerSetup): Promise<WorkerDefinition[]> {
+  return [];
+}

package/dist/templates/modules/bullmq/module.manifest.json

@@ -16,9 +16,13 @@
     "apps/api/src/jobs/**",
     "apps/api/src/main-worker.ts"
   ],
+  "ownedGlobs": [
+    "apps/api/src/worker.extensions.ts"
+  ],
   "targetApp": "api",
   "dependencies": {
-    "bullmq": "^5.57.0"
+    "bullmq": "^5.57.0",
+    "cron-parser": "^4.9.0"
   },
   "scripts": {
     "start:worker": "bun dist/main-worker.js",

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.worker.spec.ts

@@ -41,6 +41,8 @@ function fakeQueue(): FakeQueue {
       if (!handler) throw new Error(`no handler for ${job.name}`);
       await handler(payload, job);
     },
+    schedule: async () => undefined,
+    unschedule: async () => undefined,
     close: () => undefined,
   };
 }

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

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from "bun:test";
 import { SQL } from "bun";
-import { LocalJobQueue } from "./local-job.queue";
+import { LocalJobQueue, nextScheduledTime, type ScheduleTimer } from "./local-job.queue";
 
 let sql: SQL | undefined;
 
@@ -66,3 +66,89 @@ describe("local job queue", () => {
     queue.close();
   });
 });
+
+/** A clock and timer the test moves by hand. */
+function manualTime(start: number): { now: () => number; timer: ScheduleTimer; advance: (to: number) => void; waiting: () => number } {
+  let now = start;
+  const timers: Array<{ at: number; task: () => void; done: boolean }> = [];
+  return {
+    now: () => now,
+    timer: {
+      after: (delayMs, task) => {
+        const entry = { at: now + delayMs, task, done: false };
+        timers.push(entry);
+        return () => { entry.done = true; };
+      },
+    },
+    advance: (to) => {
+      for (;;) {
+        const due = timers.filter((entry) => !entry.done && entry.at <= to).sort((a, b) => a.at - b.at)[0];
+        if (!due) break;
+        due.done = true;
+        now = due.at;
+        due.task();
+      }
+      now = to;
+    },
+    waiting: () => timers.filter((entry) => !entry.done).length,
+  };
+}
+
+async function scheduledJobs(database: SQL): Promise<string[]> {
+  // Scheduled jobs are added without waiting; let those inserts finish.
+  await Bun.sleep(5);
+  const rows = await database<Array<{ id: string }>>`SELECT "id" FROM "podokit_job" ORDER BY "createdAt", "id"`;
+  return rows.map((row) => row.id);
+}
+
+describe("local job schedules", () => {
+  it("adds one job for each time of an interval and keeps going", async () => {
+    sql = new SQL(":memory:");
+    const time = manualTime(10_500);
+    const queue = new LocalJobQueue(sql, { pollIntervalMs: 60_000, now: time.now, timer: time.timer });
+    await queue.schedule("nightly", "report", { scope: "all" }, { everyMs: 1_000 });
+    await queue.start();
+    time.advance(11_000);
+    expect(await scheduledJobs(sql)).toEqual(["report:schedule:nightly:11000"]);
+    time.advance(13_200);
+    expect(await scheduledJobs(sql)).toEqual([
+      "report:schedule:nightly:11000",
+      "report:schedule:nightly:12000",
+      "report:schedule:nightly:13000",
+    ]);
+    await expect(queue.get("report:schedule:nightly:12000")).resolves.toMatchObject({ name: "report", status: "waiting" });
+    queue.close();
+    expect(time.waiting()).toBe(0);
+  });
+
+  it("replaces a schedule with the same id and stops one on unschedule", 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.start();
+    await queue.schedule("sync", "sync", {}, { everyMs: 1_000 });
+    await queue.schedule("sync", "sync", {}, { everyMs: 5_000 });
+    time.advance(5_000);
+    expect(await scheduledJobs(sql)).toEqual(["sync:schedule:sync:5000"]);
+    await queue.unschedule("sync");
+    time.advance(20_000);
+    expect(await scheduledJobs(sql)).toEqual(["sync:schedule:sync:5000"]);
+    queue.close();
+  });
+
+  it("reads cron expressions in the schedule's time zone, UTC by default", () => {
+    const after = Date.UTC(2026, 0, 1, 0, 0);
+    expect(nextScheduledTime({ cron: "0 3 * * *" }, after)).toBe(Date.UTC(2026, 0, 1, 3, 0));
+    expect(nextScheduledTime({ cron: "0 3 * * *", timezone: "Asia/Seoul" }, after)).toBe(Date.UTC(2026, 0, 1, 18, 0));
+    expect(nextScheduledTime({ everyMs: 60_000 }, after + 1)).toBe(after + 60_000);
+  });
+
+  it("rejects an invalid schedule before it is kept", async () => {
+    sql = new SQL(":memory:");
+    const queue = new LocalJobQueue(sql);
+    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");
+    queue.close();
+  });
+});

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

@@ -1,11 +1,14 @@
 import type { SQL } from "bun";
+import cronParser from "cron-parser";
 import {
+  assertRepeatOptions,
   type EnqueueOptions,
   type JobHandler,
   type JobQueue,
   type JobReference,
   type JobSnapshot,
   type JobStatus,
+  type RepeatOptions,
   type Unsubscribe,
 } from "@podosoft/podokit-runtime";
 
@@ -22,15 +25,52 @@ interface JobRow {
   error: string | null;
 }
 
+export interface ScheduleTimer {
+  /** Runs `task` once after `delayMs`; the returned function cancels it. */
+  after(delayMs: number, task: () => void): () => void;
+}
+
 export interface LocalJobQueueOptions {
   pollIntervalMs?: number;
   now?: () => number;
+  /** Waits for schedules; an unref'd setTimeout by default. */
+  timer?: ScheduleTimer;
+}
+
+interface Schedule {
+  id: string;
+  name: string;
+  payload: unknown;
+  repeat: RepeatOptions;
+  cancel?: () => void;
+}
+
+// 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;
+
+const unrefTimer: ScheduleTimer = {
+  after: (delayMs, task) => {
+    const timer = setTimeout(task, delayMs);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+  },
+};
+
+/** The first time after `after` (epoch milliseconds) that `repeat` adds a job. */
+export function nextScheduledTime(repeat: RepeatOptions, after: number): number {
+  if (repeat.everyMs !== undefined) return (Math.floor(after / repeat.everyMs) + 1) * repeat.everyMs;
+  return cronParser
+    .parseExpression(repeat.cron ?? "", { currentDate: new Date(after), tz: repeat.timezone ?? "UTC" })
+    .next()
+    .getTime();
 }
 
 export class LocalJobQueue implements JobQueue {
   private readonly handlers = new Map<string, JobHandler>();
+  private readonly schedules = new Map<string, Schedule>();
   private readonly pollIntervalMs: number;
   private readonly now: () => number;
+  private readonly scheduleTimer: ScheduleTimer;
   private timer?: ReturnType<typeof setTimeout>;
   private started = false;
   private initialized?: Promise<void>;
@@ -44,6 +84,7 @@ export class LocalJobQueue implements JobQueue {
       throw new Error("pollIntervalMs must be an integer of at least 10");
     }
     this.now = options.now ?? Date.now;
+    this.scheduleTimer = options.timer ?? unrefTimer;
   }
 
   initialize(): Promise<void> {
@@ -63,7 +104,8 @@ export class LocalJobQueue implements JobQueue {
     if (this.started) return;
     await this.initialize();
     this.started = true;
-    this.schedule(0);
+    this.poll(0);
+    for (const schedule of this.schedules.values()) this.arm(schedule);
   }
 
   async enqueue(
@@ -118,6 +160,22 @@ export class LocalJobQueue implements JobQueue {
     });
   }
 
+  async schedule(id: string, name: string, payload: unknown, repeat: RepeatOptions): Promise<void> {
+    assertRepeatOptions(repeat);
+    // 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 };
+    this.schedules.set(id, schedule);
+    if (this.started) this.arm(schedule);
+  }
+
+  async unschedule(id: string): Promise<void> {
+    this.schedules.get(id)?.cancel?.();
+    this.schedules.delete(id);
+  }
+
   async runOnce(): Promise<boolean> {
     await this.initialize();
     const now = this.now();
@@ -157,9 +215,41 @@ export class LocalJobQueue implements JobQueue {
     this.started = false;
     if (this.timer) clearTimeout(this.timer);
     this.timer = undefined;
+    for (const schedule of this.schedules.values()) schedule.cancel?.();
     this.handlers.clear();
   }
 
+  /**
+   * Adds the schedule's next job when its time comes. The job id names the
+   * schedule and the time, so a job is added once for each time.
+   */
+  private arm(schedule: Schedule, after = this.now()): void {
+    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}` })
+        .catch((error: unknown) => {
+          const message = error instanceof Error ? error.message : String(error);
+          process.stderr.write(`Add scheduled job failed: ${schedule.id} ${message}\n`);
+        });
+      this.arm(schedule, Math.max(this.now(), at));
+    });
+  }
+
+  private waitUntil(at: number, task: () => void): () => void {
+    let cancel = (): void => undefined;
+    const step = (): void => {
+      const delay = at - this.now();
+      if (delay <= 0) {
+        task();
+        return;
+      }
+      cancel = this.scheduleTimer.after(Math.min(delay, MAX_TIMER_DELAY_MS), step);
+    };
+    cancel = this.scheduleTimer.after(Math.max(0, Math.min(at - this.now(), MAX_TIMER_DELAY_MS)), step);
+    return () => cancel();
+  }
+
   private async createTables(): Promise<void> {
     await this.sql`
       CREATE TABLE IF NOT EXISTS "podokit_job" (
@@ -181,7 +271,7 @@ export class LocalJobQueue implements JobQueue {
     `;
   }
 
-  private schedule(delay: number): void {
+  private poll(delay: number): void {
     if (!this.started) return;
     this.timer = setTimeout(() => {
       void this.runOnce()
@@ -189,7 +279,7 @@ export class LocalJobQueue implements JobQueue {
           const message = error instanceof Error ? error.message : String(error);
           process.stderr.write(`Process local job failed: ${message}\n`);
         })
-        .finally(() => this.schedule(this.pollIntervalMs));
+        .finally(() => this.poll(this.pollIntervalMs));
     }, delay);
     this.timer.unref?.();
   }

package/dist/templates/modules/jobs-local/module.manifest.json

@@ -15,6 +15,9 @@
     "apps/api/src/jobs-local/**"
   ],
   "targetApp": "api",
+  "dependencies": {
+    "cron-parser": "^4.9.0"
+  },
   "env": [
     "LOCAL_JOBS_POLL_INTERVAL_MS=250"
   ],

package/dist/templates/modules/logging/files/apps/api/src/logging/logging.module.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { validateEnv } from "../config/env.validation";
+import { loggingOptions } from "./logging.module";
+
+describe("logging options", () => {
+  test("writes JSON without the development transport in production", () => {
+    expect(loggingOptions(validateEnv({ NODE_ENV: "production" })).transport).toBeUndefined();
+  });
+
+  test("pretty-prints single lines in development", () => {
+    expect(loggingOptions(validateEnv({})).transport).toEqual({
+      target: "pino-pretty",
+      options: { singleLine: true },
+    });
+  });
+});

package/dist/templates/modules/logging/files/apps/api/src/logging/logging.module.ts

@@ -1,16 +1,21 @@
-import pino from "pino";
+import pino, { type LoggerOptions } from "pino";
+import type { AppEnv } from "../config/env.validation";
 import { LOGGER, type PodokitModule } from "../core/services";
 
+/** Pretty single-line logs in development, JSON in production. */
+export function loggingOptions(env: Pick<AppEnv, "NODE_ENV">): LoggerOptions {
+  return {
+    level: process.env.LOG_LEVEL ?? "info",
+    // pino-pretty is a development dependency, so production must not ask for it.
+    transport: env.NODE_ENV === "production"
+      ? undefined
+      : { target: "pino-pretty", options: { singleLine: true } },
+  };
+}
+
 export const loggingModule: PodokitModule = {
   name: "logging",
-  configure: (_env, services): void => {
-    const isProduction = process.env.NODE_ENV === "production";
-    const logger = pino({
-      level: process.env.LOG_LEVEL ?? "info",
-      transport: isProduction
-        ? undefined
-        : { target: "pino-pretty", options: { singleLine: true } },
-    });
-    services.override(LOGGER, logger);
+  configure: (env, services): void => {
+    services.override(LOGGER, pino(loggingOptions(env)));
   },
 };

package/dist/templates/modules/mailer/module.manifest.json

@@ -5,7 +5,7 @@
   "targetApp": "api",
   "dependencies": {
     "nodemailer": "^9.0.5",
-    "@podosoft/podokit-auth": "^0.5.0"
+    "@podosoft/podokit-auth": "^0.6.0"
   },
   "devDependencies": {
     "@types/nodemailer": "^8.0.1"

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

@@ -5,7 +5,7 @@ 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: "admin@example.com",
+  email: process.env.E2E_ADMIN_EMAIL || "admin@example.com",
   password: process.env.E2E_ADMIN_PASSWORD || "Podokit3e-Str0ng!pw",
 };