@podosoft/podokit 1.5.0 → 1.6.1

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

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

package/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`;
+}

package/dist/update.d.ts

@@ -1,5 +1,5 @@
-import { type TemplateVars } from "@podosoft/podokit-template-engine";
-import { type Tier } from "./lockfile";
+import { type TemplateVars, type VfsTree } from "@podosoft/podokit-template-engine";
+import { type Tier, type FilesLock, type ManifestModule, type PodokitManifest } from "./lockfile";
 import type { ProviderCapability } from "@podosoft/podokit-runtime";
 import type { Toolchain } from "./toolchain";
 import { type ApiPathResult } from "./module-api-paths";
@@ -9,7 +9,7 @@ import { type ApiPathResult } from "./module-api-paths";
  * working copy, classifying each file. Applying the plan (writing files, 3-way
  * merging) is a later step (see ADR-0009).
  */
-export type Action = "update" | "merge" | "conflict" | "add" | "move" | "remove" | "skip" | "up-to-date";
+export type Action = "review" | "update" | "merge" | "conflict" | "add" | "move" | "remove" | "skip" | "up-to-date";
 export interface FileChange {
     path: string;
     /** Previous path when this change is an update migration move. */
@@ -36,10 +36,38 @@ export interface UpdatePlan {
     modules: string[];
     /** Modules the update adds, ordered ahead of the modules that need them. */
     addedModules: AddedModule[];
+    /**
+     * External modules whose installed package is older than the version the
+     * project last applied. Applying would write the older module's files, so
+     * `applyUpdate` refuses while this is not empty.
+     */
+    moduleDowngrades: ModuleDowngrade[];
     changes: FileChange[];
     /** Direct API paths that modules newly declare, per configuration file. */
     apiPaths: ApiPathResult;
+    /**
+     * Owned files that differ from this version's template while the lock has no
+     * record of the template they came from, so PodoKit cannot tell whether the
+     * template changed. Applying the update records it for the next one.
+     */
+    ownedWithoutTemplate: string[];
 }
+/** An external module installed at an older version than the project last applied. */
+export interface ModuleDowngrade {
+    name: string;
+    packageName: string;
+    /** Version recorded in the manifest. */
+    recorded: string;
+    /** Version installed in node_modules. */
+    installed: string;
+}
+/** Semantic version order of two exact versions: negative when `a` is older. */
+export declare function compareVersions(a: string, b: string): number;
+/** Owned paths the template and the installed modules declare, without the app's own. */
+export declare function declaredOwnedGlobs(projectRoot: string, templatesDir: string, modules: {
+    name: string;
+    packageName?: string;
+}[]): string[];
 /**
  * Build the update plan. `templatesDir` is the installed CLI's template set (the
  * new version); the lock records what PodoKit last wrote (to detect user edits).
@@ -52,6 +80,20 @@ export interface PlanOptions {
     /** Restrict planning to selected paths, used by focused conversions. */
     onlyPaths?: string[];
 }
+/** The project as the installed CLI's templates would generate it. */
+export interface TargetProject {
+    manifest: PodokitManifest;
+    lock: FilesLock;
+    /** Recorded modules plus any the target version requires, in configure order. */
+    modules: ManifestModule[];
+    addedModules: AddedModule[];
+    /** External modules installed at an older version than the project applied. */
+    moduleDowngrades: ModuleDowngrade[];
+    tree: VfsTree;
+    ownedGlobs: string[];
+    managedOverrides: string[];
+}
+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. */
@@ -80,9 +122,23 @@ export interface ApplyResult {
     merged: string[];
     /** Files written with conflict markers for manual resolution. */
     conflicts: string[];
+    /** Owned files whose template changed; they are left as they are. */
+    review: string[];
     /** Direct API paths added to `.podokit/dev.json` and deployment profiles. */
     apiPaths: ApiPathResult;
 }
+export interface UpstreamChange {
+    path: string;
+    /** Unified diff from the previous template to the new one; empty when the
+     *  previous templates did not generate the file. */
+    diff: string;
+}
+/**
+ * What the template changed between the project's version and this one for
+ * each owned file the plan marks for review, given the previous version's
+ * templates.
+ */
+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
@@ -91,6 +147,8 @@ export interface ApplyResult {
  * 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. */
+export declare function describeDowngrades(downgrades: ModuleDowngrade[]): string;
 /** Why an update adds a module, for the plan report. */
 export declare function addedModuleReason(module: AddedModule): string;
 /** Count actions for a one-line summary. */

package/dist/update.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareVersions = compareVersions;
+exports.declaredOwnedGlobs = declaredOwnedGlobs;
+exports.targetProject = targetProject;
 exports.planUpdate = planUpdate;
+exports.upstreamChanges = upstreamChanges;
 exports.applyUpdate = applyUpdate;
+exports.describeDowngrades = describeDowngrades;
 exports.addedModuleReason = addedModuleReason;
 exports.summarize = summarize;
 const node_child_process_1 = require("node:child_process");
@@ -10,6 +15,7 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const assemble_1 = require("./assemble");
+const text_diff_1 = require("./text-diff");
 const lockfile_1 = require("./lockfile");
 const inspect_1 = require("./inspect");
 const add_1 = require("./add");
@@ -25,6 +31,31 @@ function diskContent(projectRoot, path) {
     const abs = (0, node_path_1.join)(projectRoot, path);
     return (0, node_fs_1.existsSync)(abs) ? (0, node_fs_1.readFileSync)(abs) : null;
 }
+function versionParts(version) {
+    const [withoutBuild = ""] = version.split("+");
+    const dash = withoutBuild.indexOf("-");
+    const core = (dash === -1 ? withoutBuild : withoutBuild.slice(0, dash))
+        .split(".")
+        .map((part) => Number.parseInt(part, 10) || 0);
+    return { core, prerelease: dash === -1 ? null : withoutBuild.slice(dash + 1) };
+}
+/** Semantic version order of two exact versions: negative when `a` is older. */
+function compareVersions(a, b) {
+    const left = versionParts(a);
+    const right = versionParts(b);
+    for (let index = 0; index < Math.max(left.core.length, right.core.length); index += 1) {
+        const difference = (left.core[index] ?? 0) - (right.core[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    if (left.prerelease === right.prerelease)
+        return 0;
+    if (left.prerelease === null)
+        return 1;
+    if (right.prerelease === null)
+        return -1;
+    return left.prerelease.localeCompare(right.prerelease, "en", { numeric: true });
+}
 /**
  * Expand the recorded module list against the target manifests. A module may
  * gain a new requirement after it was first added to a project, either another
@@ -39,6 +70,7 @@ function targetModules(projectRoot, templatesDir, modules, providers) {
     const recorded = new Map(modules.map((module) => [module.name, module]));
     const ordered = [];
     const added = [];
+    const downgrades = [];
     const visiting = new Set();
     const visited = new Set();
     const visit = (name, requiredBy, capability) => {
@@ -54,6 +86,17 @@ function targetModules(projectRoot, templatesDir, modules, providers) {
                 ? `Module "${requiredBy}" requires unknown module "${name}".`
                 : `Cannot resolve module "${name}" while updating the project.`);
         }
+        if (existing?.moduleVersion &&
+            resolved.packageName &&
+            resolved.moduleVersion &&
+            compareVersions(resolved.moduleVersion, existing.moduleVersion) < 0) {
+            downgrades.push({
+                name: resolved.name,
+                packageName: resolved.packageName,
+                recorded: existing.moduleVersion,
+                installed: resolved.moduleVersion,
+            });
+        }
         visiting.add(name);
         const moduleManifest = (0, add_1.readModuleManifest)(resolved.dir);
         for (const required of moduleManifest.requires ?? [])
@@ -89,7 +132,7 @@ function targetModules(projectRoot, templatesDir, modules, providers) {
     for (const module of [...modules].sort((a, b) => a.order - b.order)) {
         visit(module.name);
     }
-    return { modules: ordered, added };
+    return { modules: ordered, added, downgrades };
 }
 function targetApiPaths(projectRoot, templatesDir, modules) {
     const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
@@ -104,7 +147,7 @@ function targetApiPaths(projectRoot, templatesDir, modules) {
     return { declared, pending };
 }
 function targetManagedOverrides(projectRoot, templatesDir, modules, current = []) {
-    const overrides = new Set(current);
+    const overrides = new Set([...lockfile_1.DEFAULT_MANAGED_OVERRIDES, ...current]);
     const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
     for (const module of modules) {
         const resolved = (0, add_1.resolveModule)(module.packageName ?? module.name, modulesDir, projectRoot);
@@ -127,21 +170,36 @@ function targetOwnedGlobs(projectRoot, templatesDir, modules, current) {
     }
     return [...owned];
 }
-function planUpdate(projectRoot, templatesDir, options = {}) {
+/** Owned paths the template and the installed modules declare, without the app's own. */
+function declaredOwnedGlobs(projectRoot, templatesDir, modules) {
+    return targetOwnedGlobs(projectRoot, templatesDir, modules, []);
+}
+function targetProject(projectRoot, templatesDir, targetAnswers) {
     const manifest = (0, lockfile_1.readManifest)(projectRoot);
     const lock = (0, lockfile_1.readFilesLock)(projectRoot);
     if (!manifest || !lock)
         throw new inspect_1.NotAProjectError();
-    const { modules, added } = targetModules(projectRoot, templatesDir, manifest.modules, manifest.providers);
-    const newTree = (0, assemble_1.assembleProject)({
+    const { modules, added, downgrades } = targetModules(projectRoot, templatesDir, manifest.modules, manifest.providers);
+    const tree = (0, assemble_1.assembleProject)({
         templatesDir,
         template: manifest.template,
-        answers: options.targetAnswers ?? (0, lockfile_1.manifestTemplateVars)(manifest),
+        answers: targetAnswers ?? (0, lockfile_1.manifestTemplateVars)(manifest),
         modules,
         projectRoot,
     });
-    const managedOverrides = targetManagedOverrides(projectRoot, templatesDir, modules, manifest.managedOverrides);
-    const ownedGlobs = targetOwnedGlobs(projectRoot, templatesDir, modules, manifest.ownedGlobs);
+    return {
+        manifest,
+        lock,
+        modules,
+        addedModules: added,
+        moduleDowngrades: downgrades,
+        tree,
+        ownedGlobs: targetOwnedGlobs(projectRoot, templatesDir, modules, manifest.ownedGlobs),
+        managedOverrides: targetManagedOverrides(projectRoot, templatesDir, modules, manifest.managedOverrides),
+    };
+}
+function planUpdate(projectRoot, templatesDir, options = {}) {
+    const { manifest, lock, modules, addedModules: added, moduleDowngrades, tree: newTree, ownedGlobs, managedOverrides, } = targetProject(projectRoot, templatesDir, options.targetAnswers);
     const pendingMigrations = (0, module_migrations_1.collectPendingMigrations)(projectRoot, templatesDir, modules);
     const migrationPlan = (0, module_migrations_1.planModuleMigrations)(projectRoot, newTree, lock, pendingMigrations);
     const changes = migrationPlan.moves.map((move) => ({
@@ -159,6 +217,7 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
             note: conflict,
         });
     }
+    const ownedWithoutTemplate = [];
     const movedSources = new Set(migrationPlan.moves.map((move) => move.from));
     const movedTargets = new Set(migrationPlan.moves.map((move) => move.to));
     const paths = new Set([...newTree.keys(), ...Object.keys(lock.files)]);
@@ -192,6 +251,24 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
                 changes.push({ path, tier, action: "add", note: "new owned seed in this version" });
                 continue;
             }
+            if (newText !== null && disk !== null) {
+                const newHash = (0, podokit_template_engine_1.hashContent)(newText);
+                const recorded = (0, lockfile_1.recordedTemplateHash)(locked);
+                if ((0, podokit_template_engine_1.hashContent)(disk) !== newHash) {
+                    if (recorded && recorded !== newHash) {
+                        changes.push({
+                            path,
+                            tier,
+                            action: "review",
+                            note: `owned; the template changed, see podo diff ${path}`,
+                        });
+                        continue;
+                    }
+                    // The lock never records files under .podokit/, so only judge tracked files.
+                    if (!recorded && locked)
+                        ownedWithoutTemplate.push(path);
+                }
+            }
             const explicitlyOwned = ownedGlobs.some((glob) => !glob.includes("*") && (0, lockfile_1.matchGlob)(path, glob));
             changes.push({
                 path,
@@ -251,8 +328,10 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
         template: manifest.template,
         modules: modules.map((module) => module.name),
         addedModules: added,
+        moduleDowngrades,
         changes,
         apiPaths,
+        ownedWithoutTemplate,
     };
 }
 function assertRecordedExternalModules(moduleRoot, templatesDir, modules) {
@@ -297,6 +376,48 @@ function previousExternalModules(projectRoot, templatesDir, modules, providedRoo
     }
     return { root, cleanup: true };
 }
+/** The project as the templates of the version it is on generated it. */
+function previousTree(projectRoot, manifest, oldTemplatesDir, oldExternalModulesRoot) {
+    const previousModules = previousExternalModules(projectRoot, oldTemplatesDir, manifest.modules, oldExternalModulesRoot);
+    try {
+        return (0, assemble_1.assembleProject)({
+            templatesDir: oldTemplatesDir,
+            template: manifest.template,
+            answers: (0, lockfile_1.manifestTemplateVars)(manifest),
+            modules: manifest.modules,
+            projectRoot: previousModules.root,
+        });
+    }
+    finally {
+        if (previousModules.cleanup)
+            (0, node_fs_1.rmSync)(previousModules.root, { recursive: true, force: true });
+    }
+}
+/**
+ * What the template changed between the project's version and this one for
+ * each owned file the plan marks for review, given the previous version's
+ * templates.
+ */
+function upstreamChanges(projectRoot, templatesDir, plan, oldTemplatesDir, oldExternalModulesRoot) {
+    const review = plan.changes.filter((change) => change.action === "review");
+    if (!review.length)
+        return [];
+    const target = targetProject(projectRoot, templatesDir);
+    const oldTree = previousTree(projectRoot, target.manifest, oldTemplatesDir, oldExternalModulesRoot);
+    return review.map((change) => {
+        const before = treeText(oldTree, change.path);
+        const after = treeText(target.tree, change.path) ?? "";
+        return {
+            path: change.path,
+            diff: before === null
+                ? ""
+                : (0, text_diff_1.unifiedDiff)(before, after, {
+                    fromLabel: `podokit-${plan.fromVersion}/${change.path}`,
+                    toLabel: `podokit-${plan.toVersion}/${change.path}`,
+                }),
+        };
+    });
+}
 function writeFile(projectRoot, path, content) {
     const abs = (0, node_path_1.join)(projectRoot, path);
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(abs), { recursive: true });
@@ -328,6 +449,8 @@ function updatedFilesLock(projectRoot, newTree, previous, ownedGlobs, managedOve
                 }
                 entry.outHash = (0, podokit_template_engine_1.hashContent)(newText);
             }
+            if (entry.tier === "owned")
+                entry.templateHash = (0, podokit_template_engine_1.hashContent)(newText);
             continue;
         }
         if (entry.tier === "owned")
@@ -344,16 +467,19 @@ function updatedFilesLock(projectRoot, newTree, previous, ownedGlobs, managedOve
             delete next.files[path];
         }
     }
-    // Keep a tombstone for an owned seed that the application deleted or moved.
-    // Without the previous entry, the next update would mistake the missing path
-    // for a newly introduced seed and recreate it.
+    // Keep a tombstone for an owned seed that the application deleted or moved,
+    // including a file this update turns from managed into owned. Without the
+    // entry, the next update would mistake the missing path for a newly
+    // introduced seed and recreate it.
     for (const [path, entry] of Object.entries(previous.files)) {
-        if (entry.tier !== "owned" || next.files[path])
+        if (next.files[path])
             continue;
         const newText = treeText(newTree, path);
         if (newText !== null &&
             (0, lockfile_1.classifyTier)(path, newText, ownedGlobs, managedOverrides) === "owned") {
-            next.files[path] = entry;
+            next.files[path] = entry.tier === "owned"
+                ? entry
+                : { tier: "owned", outHash: entry.outHash, templateHash: (0, podokit_template_engine_1.hashContent)(newText) };
         }
     }
     return next;
@@ -375,6 +501,10 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         forceManagedPaths: options.forceManagedPaths,
         onlyPaths: options.onlyPaths,
     });
+    if (plan.moduleDowngrades.length) {
+        throw new Error(`Refusing to downgrade external modules:\n${describeDowngrades(plan.moduleDowngrades)}\n` +
+            "Install at least the recorded version (for example bun install), then run podo update again.");
+    }
     const { modules } = targetModules(projectRoot, templatesDir, manifest.modules, manifest.providers);
     const newTree = (0, assemble_1.assembleProject)({
         templatesDir,
@@ -401,20 +531,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     const needsMergeBase = plan.changes.some((change) => change.action === "conflict");
     let oldTree = null;
     if (options.oldTemplatesDir && needsMergeBase) {
-        const previousModules = previousExternalModules(projectRoot, options.oldTemplatesDir, manifest.modules, options.oldExternalModulesRoot);
-        try {
-            oldTree = (0, assemble_1.assembleProject)({
-                templatesDir: options.oldTemplatesDir,
-                template: manifest.template,
-                answers: (0, lockfile_1.manifestTemplateVars)(manifest),
-                modules: manifest.modules,
-                projectRoot: previousModules.root,
-            });
-        }
-        finally {
-            if (previousModules.cleanup)
-                (0, node_fs_1.rmSync)(previousModules.root, { recursive: true, force: true });
-        }
+        oldTree = previousTree(projectRoot, manifest, options.oldTemplatesDir, options.oldExternalModulesRoot);
     }
     if (options.abortOnConflict) {
         const unresolved = [];
@@ -444,6 +561,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         removed: [],
         merged: [],
         conflicts: [],
+        review: plan.changes.filter((change) => change.action === "review").map((change) => change.path),
         apiPaths: { changed: [], skipped: [] },
     };
     for (const change of plan.changes) {
@@ -523,6 +641,12 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     });
     return result;
 }
+/** One line per external module installed at an older version than recorded. */
+function describeDowngrades(downgrades) {
+    return downgrades
+        .map((entry) => `  ${entry.packageName} ${entry.installed} is installed; the project applied ${entry.recorded}`)
+        .join("\n");
+}
 /** Why an update adds a module, for the plan report. */
 function addedModuleReason(module) {
     return module.capability
@@ -532,6 +656,7 @@ function addedModuleReason(module) {
 /** Count actions for a one-line summary. */
 function summarize(plan) {
     const counts = {
+        review: 0,
         update: 0,
         merge: 0,
         conflict: 0,

package/package.json

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