@podosoft/podokit 1.6.1 → 1.6.2

package/dist/templates/modules/auth/files/apps/api/src/auth/empty-lists.spec.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "bun:test";
+import { DummyDriver, Kysely, PostgresAdapter, PostgresIntrospector, PostgresQueryCompiler } from "kysely";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { PROVIDERS } from "../config/providers";
+import { postgresAuthQueries } from "./db";
+import { EmptyListPlugin } from "./empty-lists";
+
+function databaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
+
+// A type alias, not an interface: withTables() needs an index signature.
+type Tables = {
+  user: { id: string; email: string };
+};
+
+const db = new Kysely<Tables>({
+  dialect: {
+    createAdapter: () => new PostgresAdapter(),
+    createDriver: () => new DummyDriver(),
+    createIntrospector: (kysely) => new PostgresIntrospector(kysely),
+    createQueryCompiler: () => new PostgresQueryCompiler(),
+  },
+  plugins: [new EmptyListPlugin()],
+});
+
+describe("empty lists in authentication queries", () => {
+  it("sends an empty in list as a condition that never holds", () => {
+    const query = db.selectFrom("user").selectAll().where("id", "in", []).limit(0).compile();
+    expect(query.sql).toBe('select * from "user" where 1 = 0 limit $1');
+    expect(query.parameters).toEqual([0]);
+  });
+
+  it("sends an empty not in list as a condition that always holds", () => {
+    const query = db
+      .selectFrom("user")
+      .select("id")
+      .where("email", "=", "a@example.com")
+      .where("id", "not in", [])
+      .compile();
+    expect(query.sql).toBe('select "id" from "user" where "email" = $1 and 1 = 1');
+    expect(query.parameters).toEqual(["a@example.com"]);
+  });
+
+  it("leaves lists with values and other operators as they are", () => {
+    const query = db
+      .deleteFrom("user")
+      .where((eb) => eb.or([eb("id", "in", ["a", "b"]), eb("email", "=", "c@example.com")]))
+      .compile();
+    expect(query.sql).toBe('delete from "user" where ("id" in ($1, $2) or "email" = $3)');
+    expect(query.parameters).toEqual(["a", "b", "c@example.com"]);
+  });
+
+  it("applies to the queries Better Auth sends to PostgreSQL", () => {
+    if (databaseProvider() !== "postgres") {
+      expect(postgresAuthQueries).toBeNull();
+      return;
+    }
+    const query = postgresAuthQueries
+      ?.withTables<Tables>()
+      .selectFrom("user")
+      .selectAll()
+      .where("id", "in", [])
+      .compile();
+    expect(query?.sql).toBe('select * from "user" where 1 = 0');
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/empty-lists.ts

@@ -0,0 +1,54 @@
+import {
+  BinaryOperationNode,
+  OperationNodeTransformer,
+  OperatorNode,
+  PrimitiveValueListNode,
+  ValueListNode,
+  ValueNode,
+  type KyselyPlugin,
+  type PluginTransformQueryArgs,
+  type PluginTransformResultArgs,
+  type QueryId,
+  type QueryResult,
+  type RootOperationNode,
+  type UnknownRow,
+} from "kysely";
+
+function constantComparison(holds: boolean): BinaryOperationNode {
+  return BinaryOperationNode.create(
+    ValueNode.createImmediate(1),
+    OperatorNode.create("="),
+    ValueNode.createImmediate(holds ? 1 : 0),
+  );
+}
+
+class EmptyListTransformer extends OperationNodeTransformer {
+  protected override transformBinaryOperation(node: BinaryOperationNode, queryId?: QueryId): BinaryOperationNode {
+    const list = node.rightOperand;
+    const empty = (PrimitiveValueListNode.is(list) || ValueListNode.is(list)) && list.values.length === 0;
+    if (empty && OperatorNode.is(node.operator)) {
+      if (node.operator.operator === "in") return constantComparison(false);
+      if (node.operator.operator === "not in") return constantComparison(true);
+    }
+    return super.transformBinaryOperation(node, queryId);
+  }
+}
+
+/**
+ * Better Auth's Kysely adapter sends an `in` filter on an empty array as
+ * `IN ()`, which PostgreSQL rejects as a syntax error. The organization
+ * plugin's list-members endpoint looks the members' users up that way, so a
+ * filter or page that matched no member answered 500. This plugin sends an
+ * empty `in` list as `1 = 0` and an empty `not in` list as `1 = 1`.
+ */
+export class EmptyListPlugin implements KyselyPlugin {
+  private readonly transformer = new EmptyListTransformer();
+
+  transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+    return this.transformer.transformNode(args.node, args.queryId);
+  }
+
+  transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+    return Promise.resolve(args.result);
+  }
+}

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

@@ -13,6 +13,7 @@
     "@podosoft/podokit-auth": "^0.6.0",
     "@podosoft/podokit-contracts": "^0.6.0",
     "better-auth": "^1.7.7",
+    "kysely": "^0.29.0",
     "pg": "^8.12.0",
     "@better-auth/api-key": "^1.7.7",
     "@better-auth/passkey": "^1.7.7",

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

@@ -9,21 +9,85 @@ import {
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
 
-// rate-limit installs a global throttler guard (default RATE_LIMIT_MAX requests
-// per RATE_LIMIT_TTL seconds, per client). This module ships a global guard, so
-// it never joins the shared Outer smoke app (it would throttle every other
-// spec); this spec ships with the module and runs against a dedicated app.
+// rate-limit installs a global guard that counts each request in one budget: the
+// general one (RATE_LIMIT_MAX requests per RATE_LIMIT_TTL seconds, per client),
+// the stricter authentication one for other /api/auth requests, or the runtime
+// one for session reads. This module ships a global guard, so it never joins the
+// shared Outer smoke app (it would throttle every other spec); this spec ships
+// with the module and runs against a dedicated app.
 //
-// Honor RATE_LIMIT_MAX when the test runner has it (a dedicated app sets a small
-// value so the window is crossed in a handful of requests); otherwise fall back
-// to the module default and allow a little headroom.
-// A local stack that raises the limits to run the whole suite quickly sets
-// E2E_SKIP_RATE_LIMIT=true and runs this file separately against the defaults.
-test.skip(process.env.E2E_SKIP_RATE_LIMIT === "true", "assumes the configured limits; run it on its own");
+// Every counted response names its budget's limit and what is left of it in the
+// RateLimit-Limit and RateLimit-Remaining headers. The spec reads the limits from
+// them, so it follows whatever limits the stack runs with. When the runner's
+// environment sets RATE_LIMIT_MAX, RATE_LIMIT_AUTH_MAX, or RATE_LIMIT_RUNTIME_MAX,
+// the spec also expects the stack to use that value. It sends one more request
+// than the general limit, so a run that should not spend that many on a raised
+// limit sets E2E_SKIP_RATE_LIMIT=true to skip the file.
+test.skip(process.env.E2E_SKIP_RATE_LIMIT === "true", "E2E_SKIP_RATE_LIMIT is true");
 
-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);
+/** Requires a session, so a session's requests count under its user from the first one. */
+const PROBE = "/api/account/me";
+const HEALTH = ["/api/health", "/api/health/ready"];
+
+interface Budget {
+  limit: number;
+  remaining: number;
+}
+
+/** The budget a response was counted in, from its RateLimit headers. */
+function budget(response: APIResponse): Budget {
+  const headers = response.headers();
+  const limit = Number(headers["ratelimit-limit"]);
+  const remaining = Number(headers["ratelimit-remaining"]);
+  const counted = Number.isInteger(limit) && Number.isInteger(remaining);
+  expect(counted, `RateLimit headers of ${response.url()}`).toBe(true);
+  return { limit, remaining };
+}
+
+/** Expects `limit` to be the value the runner's environment sets for `name`, if it sets one. */
+function expectConfigured(
+  name: "RATE_LIMIT_MAX" | "RATE_LIMIT_AUTH_MAX" | "RATE_LIMIT_RUNTIME_MAX",
+  limit: number,
+): void {
+  const configured = process.env[name];
+  if (configured) expect(limit, `${name} in the runner's environment`).toBe(Number(configured));
+}
+
+/**
+ * Runs a check that compares counts across several requests until it passes. A
+ * counter lasts its window from its first request, so with a short
+ * RATE_LIMIT_TTL a new window can start between two requests of the check and
+ * reset what it compares; the next attempt starts over in that window.
+ */
+async function inOneWindow(check: () => Promise<void>): Promise<void> {
+  await expect(check).toPass({ timeout: 30_000 });
+}
+
+/**
+ * Requests the probe until the limiter answers 429, or null when the general
+ * window keeps ending first. More remaining than on the request before means a
+ * new window started, which starts the count over.
+ */
+async function untilLimited(ctx: APIRequestContext, limit: number): Promise<APIResponse | null> {
+  let windows = 1;
+  let counted = 0;
+  let previous = Number.POSITIVE_INFINITY;
+  for (;;) {
+    const response = await ctx.get(PROBE);
+    if (response.status() === 429) return response;
+    expect(response.status(), `${PROBE} request ${counted + 1} of window ${windows}`).toBe(200);
+    const { remaining } = budget(response);
+    if (remaining >= previous) {
+      windows += 1;
+      counted = 0;
+      if (windows > 3) return null;
+    }
+    previous = remaining;
+    counted += 1;
+    // A window holds at most `limit` served requests.
+    expect(counted, `requests served in one general window`).toBeLessThanOrEqual(limit);
+  }
+}
 
 type Playwright = PlaywrightWorkerArgs["playwright"];
 const password = "Podokit3e-Str0ng!pw";
@@ -38,6 +102,8 @@ function uniqueEmail(): string {
 // anonymous: the later ones carry its session cookie, so the limiter counts them
 // against that session instead.
 let carrier: string | undefined;
+/** The authentication budget's limit, as the latest sign-up or sign-in reported it. */
+let authLimit = 0;
 
 /** Run one authentication write and return a context holding the session it set. */
 async function authenticated(
@@ -51,6 +117,7 @@ async function authenticated(
   });
   const response = await writer.post(path, { data });
   expect(response.ok(), `${path}: ${response.status()}`).toBeTruthy();
+  authLimit = budget(response).limit;
   const storageState = await writer.storageState();
   await writer.dispose();
   const token = storageState.cookies.find((cookie) => cookie.name.endsWith("session_token"));
@@ -67,34 +134,37 @@ test("rate limit: health probes stay available while ordinary routes return 429
   playwright,
 }) => {
   const ctx = await session(playwright);
-  for (const path of ["/api/health", "/api/health/ready"]) {
-    for (let i = 0; i < limit + 5; i++) {
-      const response = await ctx.get(path);
-      expect(response.status(), `${path} request ${i + 1}`).toBe(200);
+  const probe = await ctx.get(PROBE);
+  test.skip(probe.status() >= 500, "the limiter's storage is not reachable");
+  expect(probe.status()).toBe(200);
+  const { limit } = budget(probe);
+  expectConfigured("RATE_LIMIT_MAX", limit);
+  test.skip(limit > 10_000, `the general budget (${limit}) is too large to exhaust here`);
+
+  // Health probes are not counted: they carry no budget and leave the general one as it was.
+  await inOneWindow(async () => {
+    const before = budget(await ctx.get(PROBE)).remaining;
+    for (const path of HEALTH) {
+      for (let i = 0; i < 5; i++) {
+        const response = await ctx.get(path);
+        expect(response.status(), `${path} request ${i + 1}`).toBe(200);
+        expect(response.headers()["ratelimit-limit"], path).toBeUndefined();
+      }
     }
-  }
+    expect(budget(await ctx.get(PROBE)).remaining).toBe(before - 1);
+  });
 
-  // The redis module is added automatically and exposes a public demo cache
-  // route, so it provides a stable ordinary endpoint for the global limit.
-  const probe = await ctx.get("/api/cache/rate-limit-probe");
-  test.skip(probe.status() >= 500, "throttler storage (redis) not reachable");
-
-  let seen200 = probe.status() === 200;
-  let limitedResponse: APIResponse | undefined;
-  for (let i = 0; i < limit + 5 && !limitedResponse; i++) {
-    const response = await ctx.get("/api/cache/rate-limit-probe");
-    if (response.status() === 200) seen200 = true;
-    if (response.status() === 429) limitedResponse = response;
-  }
-  // A fresh window serves the first requests (200) and rejects once the limit is
-  // crossed (429).
-  expect(seen200).toBe(true);
-  expect(limitedResponse?.status()).toBe(429);
-  expect(limitedResponse?.headers()["retry-after"]).toBeTruthy();
-  expect(await limitedResponse?.json()).toMatchObject({
+  // A window serves `limit` requests and rejects the next one.
+  const limited = await untilLimited(ctx, limit);
+  test.skip(limited === null, `the general window ends before this client sends ${limit} requests`);
+  expect(limited?.headers()["retry-after"]).toBeTruthy();
+  expect(await limited?.json()).toMatchObject({
     success: false,
     error: { code: "RATE_LIMIT_EXCEEDED", statusCode: 429 },
   });
+  for (const path of HEALTH) {
+    expect((await ctx.get(path)).status(), `${path} while the session is limited`).toBe(200);
+  }
   await ctx.dispose();
 });
 
@@ -103,10 +173,10 @@ test("rate limit: a user's sessions share one counter and forged sessions do not
 }) => {
   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"]);
-  const ceiling = Number(probe.headers()["ratelimit-limit"]);
+  const probe = await first.get(PROBE);
+  test.skip(probe.status() >= 500, "the limiter's storage is not reachable");
+  const remaining = (response: APIResponse): number => budget(response).remaining;
+  const { limit } = budget(probe);
 
   // A second sign-in of the same user, and the signed bearer form of the first
   // session. The probe requires a session, so each request below resolves it; a
@@ -119,22 +189,24 @@ test("rate limit: a user's sessions share one counter and forged sessions do not
     baseURL: base,
     extraHTTPHeaders: { ...origin, authorization: `Bearer ${cookie?.value ?? ""}` },
   });
-  await second.get("/api/cache/rate-limit-probe");
+  await second.get(PROBE);
 
   // Both sessions now draw from one budget: each request lowers what the next
   // one, from either session, has left.
-  const fromFirst = remaining(await first.get("/api/cache/rate-limit-probe"));
-  expect(remaining(await second.get("/api/cache/rate-limit-probe"))).toBe(fromFirst - 1);
-  expect(remaining(await bearer.get("/api/cache/rate-limit-probe"))).toBe(fromFirst - 2);
-  expect(remaining(await first.get("/api/cache/rate-limit-probe"))).toBe(fromFirst - 3);
+  await inOneWindow(async () => {
+    const fromFirst = remaining(await first.get(PROBE));
+    expect(remaining(await second.get(PROBE))).toBe(fromFirst - 1);
+    expect(remaining(await bearer.get(PROBE))).toBe(fromFirst - 2);
+    expect(remaining(await first.get(PROBE))).toBe(fromFirst - 3);
+  });
 
   // Another user has a budget of their own.
   const other = await session(playwright);
-  expect(remaining(await other.get("/api/cache/rate-limit-probe"))).toBe(ceiling - 1);
+  expect(remaining(await other.get(PROBE))).toBe(limit - 1);
 
   // A session cookie without a valid signature is counted with anonymous traffic
-  // from the same client address instead of receiving a fresh counter. The cache
-  // probe requires a session, so compare on a public route with the general limit.
+  // from the same client address instead of receiving a fresh counter. The probe
+  // requires a session, so compare on a public route with the general limit.
   const token = decodeURIComponent(cookie?.value ?? "").split(".")[0] ?? "";
   const forged = await playwright.request.newContext({
     baseURL: base,
@@ -154,9 +226,21 @@ test("rate limit: a user's sessions share one counter and forged sessions do not
 test("rate limit: session reads do not consume the strict authentication budget", async ({
   playwright,
 }) => {
-  test.skip(authLimit > 1000, "the authentication budget is too large to exhaust here");
   const ctx = await session(playwright);
-  for (let i = 0; i < authLimit + 5; i++) {
+  const read = await ctx.get("/api/auth/get-session");
+  test.skip(read.status() >= 500, "the limiter's storage is not reachable");
+  const runtimeLimit = budget(read).limit;
+  expectConfigured("RATE_LIMIT_RUNTIME_MAX", runtimeLimit);
+  expectConfigured("RATE_LIMIT_AUTH_MAX", authLimit);
+  // Reading past the authentication budget shows the reads are not counted in
+  // it, but only while those reads fit in the runtime budget.
+  const reads = authLimit + 5;
+  test.skip(
+    reads + 1 > runtimeLimit,
+    `the authentication budget (${authLimit}) is not far enough below the runtime budget (${runtimeLimit})`,
+  );
+  test.skip(authLimit > 1000, `the authentication budget (${authLimit}) is too large to exhaust here`);
+  for (let i = 0; i < reads; i++) {
     const response = await ctx.get("/api/auth/get-session");
     expect(response.status(), `session request ${i + 1}`).toBe(200);
   }
@@ -167,17 +251,34 @@ test("rate limit: each route is counted in its most specific registered budget",
   playwright,
 }) => {
   const ctx = await session(playwright);
-  const probe = await ctx.get("/api/account/capabilities");
-  test.skip(probe.status() >= 500, "throttler storage (redis) not reachable");
-  const ceiling = (response: APIResponse): number => Number(response.headers()["ratelimit-limit"]);
-
-  // Ordinary routes fall back to the general budget registered at "/".
-  expect(ceiling(probe)).toBe(limit);
-  // Longer GET prefixes inside "/api/auth" win over its authentication budget:
-  // session reads use the runtime budget and administrator reads the general one.
-  expect(ceiling(await ctx.get("/api/auth/get-session"))).toBe(runtimeLimit);
-  expect(ceiling(await ctx.get("/api/auth/admin/list-users"))).toBe(limit);
-  // Other "/api/auth" requests carry the strict authentication budget.
-  expect(ceiling(await ctx.post("/api/auth/sign-out", { data: {} }))).toBe(authLimit);
+  const probe = await ctx.get(PROBE);
+  test.skip(probe.status() >= 500, "the limiter's storage is not reachable");
+  const generalLimit = budget(probe).limit;
+  expectConfigured("RATE_LIMIT_MAX", generalLimit);
+  expectConfigured("RATE_LIMIT_AUTH_MAX", authLimit);
+
+  await inOneWindow(async () => {
+    // Ordinary routes fall back to the general budget registered at "/".
+    const ordinary = budget(await ctx.get("/api/account/capabilities"));
+    // Longer GET prefixes inside "/api/auth" win over its authentication budget:
+    // administrator reads count in the general budget and session reads in the
+    // runtime one.
+    const adminRead = budget(await ctx.get("/api/auth/admin/list-users"));
+    const sessionRead = budget(await ctx.get("/api/auth/get-session"));
+    // Other "/api/auth" requests count in the strict authentication budget.
+    const authWrite = budget(await ctx.post("/api/auth/update-user", { data: { name: "Rate Limit" } }));
+    const sessionReadAgain = budget(await ctx.get("/api/auth/get-session"));
+    const ordinaryAgain = budget(await ctx.get("/api/account/capabilities"));
+
+    expect(ordinary.limit).toBe(generalLimit);
+    expect(adminRead).toEqual({ limit: generalLimit, remaining: ordinary.remaining - 1 });
+    // Neither the session reads nor the authentication write moved the general counter,
+    expect(ordinaryAgain).toEqual({ limit: generalLimit, remaining: ordinary.remaining - 2 });
+    // the authentication write did not move the runtime one,
+    expect(sessionReadAgain).toEqual({ limit: sessionRead.limit, remaining: sessionRead.remaining - 1 });
+    // and it was counted with sign-ups and sign-ins.
+    expect(authWrite.limit).toBe(authLimit);
+    expectConfigured("RATE_LIMIT_RUNTIME_MAX", sessionRead.limit);
+  });
   await ctx.dispose();
 });

package/dist/update.d.ts

@@ -96,8 +96,14 @@ export interface TargetProject {
 export declare function targetProject(projectRoot: string, templatesDir: string, targetAnswers?: TemplateVars): TargetProject;
 export declare function planUpdate(projectRoot: string, templatesDir: string, options?: PlanOptions): UpdatePlan;
 export interface ApplyOptions {
-    /** Templates for the version the project is currently on, for 3-way merges. */
+    /**
+     * Templates for the version the project is currently on, for 3-way merges.
+     * Without it, the update uses the installed templates when the project is on
+     * the installed version and otherwise fetches that version's.
+     */
     oldTemplatesDir?: string;
+    /** Fetches the templates a published PodoKit version ships. Defaults to npm. */
+    fetchTemplates?: (version: string) => PreviousTemplates;
     /** Preinstalled previous external modules. Primarily useful for offline updates. */
     oldExternalModulesRoot?: string;
     /** Replay variables and manifest value used by a runtime conversion. */
@@ -124,9 +130,22 @@ export interface ApplyResult {
     conflicts: string[];
     /** Owned files whose template changed; they are left as they are. */
     review: string[];
+    /** Edited managed files the update left as they are, and why. */
+    skipped: SkippedFile[];
     /** Direct API paths added to `.podokit/dev.json` and deployment profiles. */
     apiPaths: ApiPathResult;
 }
+export interface SkippedFile {
+    path: string;
+    reason: string;
+}
+/** A template set to merge against, and how to dispose of it. */
+export interface PreviousTemplates {
+    dir: string;
+    cleanup(): void;
+}
+/** Install a published PodoKit CLI into a temporary directory and return its templates. */
+export declare function publishedTemplates(version: string): PreviousTemplates;
 export interface UpstreamChange {
     path: string;
     /** Unified diff from the previous template to the new one; empty when the
@@ -141,10 +160,11 @@ export interface UpstreamChange {
 export declare function upstreamChanges(projectRoot: string, templatesDir: string, plan: UpdatePlan, oldTemplatesDir: string, oldExternalModulesRoot?: string): UpstreamChange[];
 /**
  * Apply an update to the working copy. Clean updates and additions are written,
- * upstream removals deleted, and user-edited files 3-way merged against the old
- * version (when `oldTemplatesDir` is given) or written with git-style conflict
- * markers otherwise. Owned files are never touched. Refreshes the lockfile and
- * stamps the new version.
+ * upstream removals deleted, and user-edited files 3-way merged against the
+ * templates of the version the project is on, with git-style conflict markers
+ * where both sides changed the same lines. Refuses before writing anything when
+ * those templates are unavailable. Owned files are never touched. Refreshes the
+ * lockfile and stamps the new version.
  */
 export declare function applyUpdate(projectRoot: string, templatesDir: string, options?: ApplyOptions): ApplyResult;
 /** One line per external module installed at an older version than recorded. */

package/dist/update.js

@@ -4,6 +4,7 @@ exports.compareVersions = compareVersions;
 exports.declaredOwnedGlobs = declaredOwnedGlobs;
 exports.targetProject = targetProject;
 exports.planUpdate = planUpdate;
+exports.publishedTemplates = publishedTemplates;
 exports.upstreamChanges = upstreamChanges;
 exports.applyUpdate = applyUpdate;
 exports.describeDowngrades = describeDowngrades;
@@ -334,6 +335,61 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
         ownedWithoutTemplate,
     };
 }
+const CLI_PACKAGE = "@podosoft/podokit";
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/** Install a published PodoKit CLI into a temporary directory and return its templates. */
+function publishedTemplates(version) {
+    if (!EXACT_VERSION.test(version)) {
+        throw new Error(`"${version}" is not a published ${CLI_PACKAGE} version.`);
+    }
+    const root = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "podokit-update-templates-"));
+    const cleanup = () => (0, node_fs_1.rmSync)(root, { recursive: true, force: true });
+    try {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, "package.json"), `${JSON.stringify({ name: "podokit-update-templates", private: true, devDependencies: { [CLI_PACKAGE]: version } }, null, 2)}\n`);
+        (0, node_child_process_1.execFileSync)("npm", ["install", "--ignore-scripts", "--no-audit", "--no-fund", "--package-lock=false"], { cwd: root, stdio: "pipe" });
+        const packageDir = (0, node_path_1.join)(root, "node_modules", ...CLI_PACKAGE.split("/"));
+        const installed = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(packageDir, "package.json"), "utf8")).version;
+        const dir = (0, node_path_1.join)(packageDir, "dist", "templates");
+        if (installed !== version || !(0, node_fs_1.existsSync)(dir)) {
+            throw new Error(`the installed package is not ${version} or ships no templates`);
+        }
+        return { dir, cleanup };
+    }
+    catch (error) {
+        cleanup();
+        throw new Error(`Cannot install ${CLI_PACKAGE}@${version} from the npm registry: ${npmFailure(error)}`);
+    }
+}
+/** npm's error code, such as ECONNREFUSED or ETARGET, rather than the command line. */
+function npmFailure(error) {
+    const stderr = error?.stderr;
+    const code = String(stderr ?? "").match(/^npm (?:error|ERR!) code (\S+)/m)?.[1];
+    if (code)
+        return `npm error ${code}`;
+    return error instanceof Error ? (error.message.split("\n")[0] ?? error.message) : String(error);
+}
+/**
+ * The templates the project's edited managed files were generated from, which
+ * a 3-way merge needs as its base: `--from` when given, the installed ones when
+ * the project is on the installed version, and the recorded version's otherwise.
+ */
+function mergeBaseTemplates(recordedVersion, templatesDir, options, paths) {
+    if (options.oldTemplatesDir)
+        return { dir: options.oldTemplatesDir, cleanup: () => { } };
+    if (recordedVersion === (0, lockfile_1.podokitVersion)())
+        return { dir: templatesDir, cleanup: () => { } };
+    try {
+        return (options.fetchTemplates ?? publishedTemplates)(recordedVersion);
+    }
+    catch (error) {
+        throw new Error(`${error instanceof Error ? error.message : String(error)}\n` +
+            `The 3-way merge of these edited files needs the templates of ${recordedVersion}, ` +
+            `the version this project was last generated or updated with:\n${paths
+                .map((path) => `  - ${path}`)
+                .join("\n")}\n` +
+            "Nothing was written. Check npm registry access, or pass that version's templates with --from <dir>.");
+    }
+}
 function assertRecordedExternalModules(moduleRoot, templatesDir, modules) {
     const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
     for (const module of modules) {
@@ -486,10 +542,11 @@ function updatedFilesLock(projectRoot, newTree, previous, ownedGlobs, managedOve
 }
 /**
  * Apply an update to the working copy. Clean updates and additions are written,
- * upstream removals deleted, and user-edited files 3-way merged against the old
- * version (when `oldTemplatesDir` is given) or written with git-style conflict
- * markers otherwise. Owned files are never touched. Refreshes the lockfile and
- * stamps the new version.
+ * upstream removals deleted, and user-edited files 3-way merged against the
+ * templates of the version the project is on, with git-style conflict markers
+ * where both sides changed the same lines. Refuses before writing anything when
+ * those templates are unavailable. Owned files are never touched. Refreshes the
+ * lockfile and stamps the new version.
  */
 function applyUpdate(projectRoot, templatesDir, options = {}) {
     const manifest = (0, lockfile_1.readManifest)(projectRoot);
@@ -528,10 +585,18 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     const migratedManagedOverrides = [
         ...new Set(managedOverrides.map((glob) => (0, module_migrations_1.migrateConfiguredPath)(glob, pendingMigrations))),
     ];
-    const needsMergeBase = plan.changes.some((change) => change.action === "conflict");
+    const mergePaths = plan.changes
+        .filter((change) => change.action === "conflict" && treeText(newTree, change.path) !== null)
+        .map((change) => change.path);
     let oldTree = null;
-    if (options.oldTemplatesDir && needsMergeBase) {
-        oldTree = previousTree(projectRoot, manifest, options.oldTemplatesDir, options.oldExternalModulesRoot);
+    if (mergePaths.length) {
+        const base = mergeBaseTemplates(manifest.podokitVersion, templatesDir, options, mergePaths);
+        try {
+            oldTree = previousTree(projectRoot, manifest, base.dir, options.oldExternalModulesRoot);
+        }
+        finally {
+            base.cleanup();
+        }
     }
     if (options.abortOnConflict) {
         const unresolved = [];
@@ -562,6 +627,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         merged: [],
         conflicts: [],
         review: plan.changes.filter((change) => change.action === "review").map((change) => change.path),
+        skipped: [],
         apiPaths: { changed: [], skipped: [] },
     };
     for (const change of plan.changes) {
@@ -574,12 +640,22 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
             (0, node_fs_1.rmSync)((0, node_path_1.join)(projectRoot, change.path), { force: true });
             result.removed.push(change.path);
         }
-        else if (change.action === "conflict" && newText !== null) {
+        else if (change.action === "conflict") {
+            if (newText === null) {
+                result.skipped.push({
+                    path: change.path,
+                    reason: "removed in this version but edited locally, so it was kept; delete it when you no longer need it",
+                });
+                continue;
+            }
             const disk = (0, node_fs_1.readFileSync)((0, node_path_1.join)(projectRoot, change.path), "utf8");
             const base = oldTree ? treeText(oldTree, change.path) : null;
             if (base === null) {
-                // No old version to merge against — never clobber the user's edits.
-                result.conflicts.push(change.path);
+                // Nothing to merge against: never clobber the application's version.
+                result.skipped.push({
+                    path: change.path,
+                    reason: `the previous version's templates do not generate it, so there is no merge base; compare it with podo diff ${change.path}`,
+                });
                 continue;
             }
             const merge = (0, podokit_template_engine_1.threeWayMerge)(base, disk, newText, { current: "current", next: "podokit" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "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": {