@podosoft/podokit 1.6.1 → 1.6.3

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

@@ -9,21 +9,124 @@ 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. A test that sends a budget's
+// worth of requests times the first ones and skips, with the reason, when the
+// rest would not fit in its time, as with raised local limits. A run that should
+// not send them at all 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);
+/** Requests a test times before it judges whether the rest fit in its time. */
+const PACE_SAMPLE = 50;
+
+let testStarted = Date.now();
+test.beforeEach(() => {
+  testStarted = Date.now();
+});
+
+function seconds(ms: number): string {
+  return `${(ms / 1000).toFixed(1)} s`;
+}
+
+/**
+ * Why `left` more requests, sent at the pace of the `sent` ones since `since`,
+ * would not end within half of the time this test has left, or undefined when
+ * they would. The other half leaves room for a slower stretch.
+ */
+function outOfTime(sent: number, since: number, left: number): string | undefined {
+  const { timeout } = test.info();
+  if (timeout === 0) return undefined;
+  const now = Date.now();
+  const perRequest = (now - since) / sent;
+  const needed = perRequest * left;
+  const available = timeout - (now - testStarted);
+  if (needed <= available / 2) return undefined;
+  const pace = Math.round(1000 / perRequest);
+  return `${left} more requests at ${pace} per second take about ${seconds(needed)}, more than half of the ${seconds(available)} this test has left`;
+}
+
+/** 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 returns why it stopped
+ * first: the general window kept ending first, or the requests left to the
+ * limit would not fit in the test's time. 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 | string> {
+  const started = Date.now();
+  let sent = 0;
+  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);
+    sent += 1;
+    if (remaining >= previous) {
+      windows += 1;
+      counted = 0;
+      if (windows > 3) return `the general window ends before this client sends ${limit} requests`;
+    }
+    previous = remaining;
+    counted += 1;
+    // A window holds at most `limit` served requests.
+    expect(counted, `requests served in one general window`).toBeLessThanOrEqual(limit);
+    // Judged in each window, since a new one needs the whole limit again.
+    if (counted === PACE_SAMPLE) {
+      const late = outOfTime(sent, started, remaining + 1);
+      if (late) return `reaching the general limit (${limit}): ${late}`;
+    }
+  }
+}
 
 type Playwright = PlaywrightWorkerArgs["playwright"];
 const password = "Podokit3e-Str0ng!pw";
@@ -38,6 +141,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 +156,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 +173,39 @@ 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);
+
+  // 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 window serves `limit` requests and rejects the next one.
+  const limited = await untilLimited(ctx, limit);
+  if (typeof limited === "string") {
+    test.skip(true, limited);
+    return;
   }
-  // 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({
+  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 +214,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 +230,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,11 +267,27 @@ 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})`,
+  );
+  const started = Date.now();
+  for (let i = 1; i <= reads; i++) {
     const response = await ctx.get("/api/auth/get-session");
-    expect(response.status(), `session request ${i + 1}`).toBe(200);
+    expect(response.status(), `session request ${i}`).toBe(200);
+    if (i === PACE_SAMPLE) {
+      const late = outOfTime(i, started, reads - i);
+      test.skip(late !== undefined, `reading past the authentication budget (${authLimit}): ${late}`);
+    }
   }
   await ctx.dispose();
 });
@@ -167,17 +296,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.3",
   "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": {