@podosoft/podokit 1.5.0 → 1.6.0

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",
 };
 

package/dist/templates/modules/object-storage-s3/files/infra/docker/minio.compose.yml

@@ -24,12 +24,13 @@ services:
     profiles: ["dev"]
     depends_on:
       - minio
+    # -e stops at the first failing command, so a bucket that cannot be
+    # created fails this service instead of leaving uploads to fail later.
     entrypoint: >
-      /bin/sh -c "
+      /bin/sh -ec "
       until mc alias set local http://minio:9000 ${S3_ACCESS_KEY_ID:-podokit} ${S3_SECRET_ACCESS_KEY:-podokitsecret}; do echo 'waiting for minio'; sleep 1; done;
-      mc mb -p local/${S3_BUCKET:-podokit};
-      echo 'bucket ready';
-      exit 0"
+      mc mb --ignore-existing local/${S3_BUCKET:-podokit};
+      echo 'bucket ready'"
 
 volumes:
   minio-data:

package/dist/templates/modules/object-storage-s3/files/tests/api/storage.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",
 };
 

package/dist/templates/modules/rate-limit/files/tests/api/rate-limit.api.spec.ts

@@ -1,4 +1,10 @@
-import { expect, test, type APIResponse } from "@playwright/test";
+import {
+  expect,
+  test,
+  type APIRequestContext,
+  type APIResponse,
+  type PlaywrightWorkerArgs,
+} from "@playwright/test";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
@@ -19,20 +25,42 @@ const limit = Number(process.env.RATE_LIMIT_MAX ?? 300);
 const authLimit = Number(process.env.RATE_LIMIT_AUTH_MAX ?? 20);
 const runtimeLimit = Number(process.env.RATE_LIMIT_RUNTIME_MAX ?? 1000);
 
-async function session(
-  playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"],
-) {
-  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  const email = `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
-  const signup = await ctx.post("/api/auth/sign-up/email", {
-    data: {
-      email,
-      password: "Podokit3e-Str0ng!pw",
-      name: "Rate Limit",
-    },
+type Playwright = PlaywrightWorkerArgs["playwright"];
+const password = "Podokit3e-Str0ng!pw";
+
+function uniqueEmail(): string {
+  return `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+}
+
+// Sign-ups and sign-ins are authentication writes. From an anonymous client the
+// limiter counts them against the per-address budget that the setup project's
+// and every other spec's sign-ins share. Only this worker's first one is
+// anonymous: the later ones carry its session cookie, so the limiter counts them
+// against that session instead.
+let carrier: string | undefined;
+
+/** Run one authentication write and return a context holding the session it set. */
+async function authenticated(
+  playwright: Playwright,
+  path: "/api/auth/sign-up/email" | "/api/auth/sign-in/email",
+  data: Record<string, string>,
+): Promise<APIRequestContext> {
+  const writer = await playwright.request.newContext({
+    baseURL: base,
+    extraHTTPHeaders: { ...origin, ...(carrier ? { cookie: carrier } : {}) },
   });
-  expect(signup.ok()).toBeTruthy();
-  return ctx;
+  const response = await writer.post(path, { data });
+  expect(response.ok(), `${path}: ${response.status()}`).toBeTruthy();
+  const storageState = await writer.storageState();
+  await writer.dispose();
+  const token = storageState.cookies.find((cookie) => cookie.name.endsWith("session_token"));
+  carrier ??= token ? `${token.name}=${token.value}` : undefined;
+  return playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin, storageState });
+}
+
+/** A new account, signed in. */
+async function session(playwright: Playwright, email = uniqueEmail()): Promise<APIRequestContext> {
+  return authenticated(playwright, "/api/auth/sign-up/email", { email, password, name: "Rate Limit" });
 }
 
 test("rate limit: health probes stay available while ordinary routes return 429 @smoke", async ({
@@ -73,10 +101,8 @@ test("rate limit: health probes stay available while ordinary routes return 429
 test("rate limit: a user's sessions share one counter and forged sessions do not get one", async ({
   playwright,
 }) => {
-  const email = `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
-  const password = "Podokit3e-Str0ng!pw";
-  const first = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  expect((await first.post("/api/auth/sign-up/email", { data: { email, password, name: "Rate Limit" } })).ok()).toBeTruthy();
+  const email = uniqueEmail();
+  const first = await session(playwright, email);
   const probe = await first.get("/api/cache/rate-limit-probe");
   test.skip(probe.status() >= 500, "throttler storage (redis) not reachable");
   const remaining = (response: APIResponse): number => Number(response.headers()["ratelimit-remaining"]);
@@ -86,8 +112,7 @@ test("rate limit: a user's sessions share one counter and forged sessions do not
   // session. The probe requires a session, so each request below resolves it; a
   // session counts under its user from the request after the API first resolves
   // it (or from that request when authentication runs before the limiter).
-  const second = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  expect((await second.post("/api/auth/sign-in/email", { data: { email, password } })).ok()).toBeTruthy();
+  const second = await authenticated(playwright, "/api/auth/sign-in/email", { email, password });
   const cookie = (await first.storageState()).cookies.find((c) => c.name.endsWith("session_token"));
   expect(cookie, "sign-up set a session cookie").toBeTruthy();
   const bearer = await playwright.request.newContext({

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

@@ -6,7 +6,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",
 };
 

package/dist/templates/todo/AGENTS.md

@@ -87,7 +87,11 @@ Merge added module settings from `.env.example` into an existing `.env`.
   Better Auth schema before the application migrations. `{{apiRun}} migration:run` runs
   only the application migrations and never creates Better Auth tables;
   `{{apiRun}} migration:revert` reverts the latest application migration.
-- e2e (Playwright, ships in `tests/`): `{{rootRun}} test:e2e`.
+- 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
+  never empty the shared Mailpit inbox or SMS sink. See `tests/README.md`.
 - Playwright officially runs on Node, so `bunx playwright` respects its Node
   shebang. Node LTS is a test-tool dependency only; API, web, worker, migrations,
   builds, and unit tests run on Bun.

package/dist/templates/todo/README.md

@@ -55,8 +55,9 @@ cp .env.example .env
 ```
 
 Open the URL printed by the command; a new project defaults to
-**http://{{projectName}}.localhost**. The committed `.podokit/dev.json` is the
-source of truth if you change the hostname. The first running PodoKit project starts
+**http://{{devHostname}}**. The committed `.podokit/dev.json` is the
+source of truth if you change the hostname: `podo dev` sets `CORS_ORIGIN` and
+`BETTER_AUTH_URL` for the web and API containers from it. The first running PodoKit project starts
 one user-level Traefik gateway on `127.0.0.1:80`; additional projects reuse it and
 route by that hostname. Even a single app uses
 the same topology, with one route and no project-specific host port.
@@ -164,5 +165,6 @@ PodoKit [deployment guide](https://github.com/podosoft-dev/podokit/blob/main/doc
 For a Docker Compose deployment with API WebSockets, list their exact paths under
 `exposure.webSocketPaths`. The driver keeps one published port, routes those paths
 to API, and sends every other request to web. Large-upload routes listed under
-`exposure.apiPaths` reach the API the same way, with `/api` removed. If an external reverse proxy supplies
-forwarding headers, list only its direct CIDR blocks in `exposure.trustedProxyCidrs`.
+`exposure.apiPaths` reach the API the same way, with `/api` removed. Set `exposure.edgeProxies` to the
+number of reverse proxies in front of the deployment, and with the gateway list only their direct CIDR
+blocks in `exposure.trustedProxyCidrs`.

package/dist/text-diff.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Line-based unified diff for `podo diff <path>`. It is dependency-free and
+ * meant for source files of a few thousand lines; above `MAX_CELLS` it reports
+ * the whole file as replaced instead of building the LCS table.
+ */
+export interface UnifiedDiffOptions {
+    fromLabel: string;
+    toLabel: string;
+    context?: number;
+}
+/** Unified diff from `from` to `to`, or an empty string when they are equal. */
+export declare function unifiedDiff(from: string, to: string, options: UnifiedDiffOptions): string;

package/dist/text-diff.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Line-based unified diff for `podo diff <path>`. It is dependency-free and
+ * meant for source files of a few thousand lines; above `MAX_CELLS` it reports
+ * the whole file as replaced instead of building the LCS table.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unifiedDiff = unifiedDiff;
+const MAX_CELLS = 25_000_000;
+function splitLines(text) {
+    if (text === "")
+        return [];
+    const lines = text.split("\n");
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}
+function operations(a, b) {
+    let start = 0;
+    while (start < a.length && start < b.length && a[start] === b[start])
+        start += 1;
+    let endA = a.length;
+    let endB = b.length;
+    while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+        endA -= 1;
+        endB -= 1;
+    }
+    const head = a.slice(0, start).map((line) => ({ kind: " ", line }));
+    const tail = a.slice(endA).map((line) => ({ kind: " ", line }));
+    const midA = a.slice(start, endA);
+    const midB = b.slice(start, endB);
+    const m = midA.length;
+    const n = midB.length;
+    const middle = [];
+    if ((m + 1) * (n + 1) > MAX_CELLS) {
+        middle.push(...midA.map((line) => ({ kind: "-", line })));
+        middle.push(...midB.map((line) => ({ kind: "+", line })));
+        return [...head, ...middle, ...tail];
+    }
+    const width = n + 1;
+    const table = new Uint32Array((m + 1) * width);
+    for (let i = m - 1; i >= 0; i -= 1) {
+        for (let j = n - 1; j >= 0; j -= 1) {
+            table[i * width + j] = midA[i] === midB[j]
+                ? table[(i + 1) * width + j + 1] + 1
+                : Math.max(table[(i + 1) * width + j], table[i * width + j + 1]);
+        }
+    }
+    let i = 0;
+    let j = 0;
+    while (i < m || j < n) {
+        if (i < m && j < n && midA[i] === midB[j]) {
+            middle.push({ kind: " ", line: midA[i] });
+            i += 1;
+            j += 1;
+        }
+        else if (i < m && (j === n || table[(i + 1) * width + j] >= table[i * width + j + 1])) {
+            middle.push({ kind: "-", line: midA[i] });
+            i += 1;
+        }
+        else {
+            middle.push({ kind: "+", line: midB[j] });
+            j += 1;
+        }
+    }
+    return [...head, ...middle, ...tail];
+}
+function range(start, count) {
+    if (count === 0)
+        return `${start},0`;
+    return count === 1 ? `${start + 1}` : `${start + 1},${count}`;
+}
+/** Unified diff from `from` to `to`, or an empty string when they are equal. */
+function unifiedDiff(from, to, options) {
+    if (from === to)
+        return "";
+    const context = options.context ?? 3;
+    const ops = operations(splitLines(from), splitLines(to));
+    const changed = ops.flatMap((op, index) => (op.kind === " " ? [] : [index]));
+    const out = [`--- ${options.fromLabel}`, `+++ ${options.toLabel}`];
+    if (!changed.length) {
+        // Only the trailing newline differs.
+        out.push(from.endsWith("\n") ? "\\ the template ends with a newline" : "\\ the template has no newline at end of file", to.endsWith("\n") ? "\\ the file ends with a newline" : "\\ the file has no newline at end of file");
+        return `${out.join("\n")}\n`;
+    }
+    let hunkStart = 0;
+    while (hunkStart < changed.length) {
+        let hunkEnd = hunkStart;
+        while (hunkEnd + 1 < changed.length &&
+            changed[hunkEnd + 1] - changed[hunkEnd] <= context * 2 + 1) {
+            hunkEnd += 1;
+        }
+        const first = Math.max(0, changed[hunkStart] - context);
+        const last = Math.min(ops.length - 1, changed[hunkEnd] + context);
+        let fromLine = 0;
+        let toLine = 0;
+        for (let index = 0; index < first; index += 1) {
+            if (ops[index].kind !== "+")
+                fromLine += 1;
+            if (ops[index].kind !== "-")
+                toLine += 1;
+        }
+        const body = ops.slice(first, last + 1);
+        const fromCount = body.filter((op) => op.kind !== "+").length;
+        const toCount = body.filter((op) => op.kind !== "-").length;
+        out.push(`@@ -${range(fromLine, fromCount)} +${range(toLine, toCount)} @@`);
+        out.push(...body.map((op) => `${op.kind}${op.line}`));
+        hunkStart = hunkEnd + 1;
+    }
+    return `${out.join("\n")}\n`;
+}