@podosoft/podokit 1.5.0 → 1.6.1

package/dist/index.js

@@ -12,12 +12,14 @@ const remove_1 = require("./remove");
 const inspect_1 = require("./inspect");
 const update_1 = require("./update");
 const eject_1 = require("./eject");
+const template_files_1 = require("./template-files");
 const dev_1 = require("./dev");
 const locale_1 = require("./locale");
 const deploy_1 = require("./deploy");
 const deploy_profile_1 = require("./deploy-profile");
 const deploy_render_1 = require("./deploy-render");
 const deploy_driver_1 = require("./deploy-driver");
+const deploy_checks_1 = require("./deploy-checks");
 const deploy_compose_profile_1 = require("./deploy-compose-profile");
 const deploy_compose_render_1 = require("./deploy-compose-render");
 const deploy_compose_1 = require("./deploy-compose");
@@ -33,7 +35,7 @@ Usage:
   podo provider set <capability> <provider> [--apply]
   podo remove <module>     Un-apply a module (inverse of add)
   podo status              Show version, modules, file tiers, and local edits
-  podo diff                List PodoKit-managed files you have edited
+  podo diff [path...]      List edited managed files, or diff files against the template
   podo doctor              Check framework versions against supported ranges
   podo dev <action> [...]  Run the shared, portless container development gateway
   podo deploy <action>     Plan, apply, verify, or roll back a deployment
@@ -41,6 +43,7 @@ Usage:
   podo locale <command>    Add, validate, activate, or list JSON locales
   podo update [--apply]    Preview (or apply) what a version update would change
   podo eject <path...>     Take ownership of managed files (update skips them)
+  podo restore <path...>   Rewrite managed or ejected files from the template
 
 Options:
   --template <t> Template to scaffold (see below)
@@ -220,6 +223,26 @@ function parseArgs(argv) {
     parsed.positionals = positionals;
     return parsed;
 }
+/** Explain owned files whose template changed, with the upstream diff when the previous templates are given. */
+function writeOwnedTemplateNotes(plan, templatesDir, from) {
+    if (plan.changes.some((change) => change.action === "review")) {
+        if (from) {
+            process.stdout.write("\nTemplate changes to files you own (not applied):\n");
+            for (const change of (0, update_1.upstreamChanges)(process.cwd(), templatesDir, plan, from)) {
+                process.stdout.write(change.diff || `${change.path}: new in this version's template.\n`);
+            }
+        }
+        else {
+            process.stdout.write("\nreview: the template changed for a file you own. podo update never writes it; " +
+                "podo diff <path> compares it with the new template, and --from <previous templates> shows what changed upstream.\n");
+        }
+    }
+    if (plan.ownedWithoutTemplate.length) {
+        process.stdout.write(`\n${plan.ownedWithoutTemplate.length} owned file(s) differ from this version's templates, and the lock does not record ` +
+            "the template they came from. podo diff <path> shows the difference; applying this update records the template " +
+            "so the next update reports only real template changes.\n");
+    }
+}
 function writeApiPaths(heading, result, verb) {
     const lines = (0, module_api_paths_1.describeApiPaths)(result, verb);
     if (lines.length)
@@ -258,7 +281,7 @@ async function runComposeDeploy(action, args, profileName) {
         const findings = (0, deploy_compose_1.doctorComposeDeployment)(cwd, profileName, undefined, args.release);
         process.stdout.write(args.json
             ? `${JSON.stringify(findings, null, 2)}\n`
-            : `${findings.map((f) => `${f.ok ? "ok  " : "FAIL"} ${f.message}`).join("\n")}\n`);
+            : `${findings.map(deploy_checks_1.formatFinding).join("\n")}\n`);
         if (findings.some((finding) => !finding.ok))
             process.exitCode = 1;
         return;
@@ -461,7 +484,33 @@ async function main(argv) {
         return;
     }
     if (args.command === "diff") {
+        const targets = args.positionals.slice(1);
         try {
+            if (targets.length) {
+                const result = (0, template_files_1.templateDiff)(process.cwd(), (0, node_path_1.join)(__dirname, "templates"), targets);
+                if (result.projectVersion !== result.templateVersion) {
+                    process.stdout.write(`Comparing with PodoKit ${result.templateVersion} templates; this project is on ${result.projectVersion}.\n`);
+                }
+                for (const file of result.files) {
+                    const tier = file.tier ? ` (${file.tier})` : "";
+                    if (file.status === "not-generated") {
+                        process.stdout.write(`${file.path}: PodoKit does not generate this file.\n`);
+                    }
+                    else if (file.status === "missing") {
+                        process.stdout.write(`${file.path}${tier}: missing; podo restore ${file.path} writes the template's version.\n`);
+                    }
+                    else if (file.status === "same") {
+                        process.stdout.write(`${file.path}${tier}: same as the template.\n`);
+                    }
+                    else if (file.binary) {
+                        process.stdout.write(`${file.path}${tier}: binary file differs from the template.\n`);
+                    }
+                    else {
+                        process.stdout.write(file.diff);
+                    }
+                }
+                return;
+            }
             const { drifted, missing } = (0, inspect_1.diff)(process.cwd());
             if (!drifted.length && !missing.length) {
                 process.stdout.write("No local edits to PodoKit-managed files.\n");
@@ -539,7 +588,7 @@ async function main(argv) {
                 const findings = (0, deploy_1.doctorDeployment)(process.cwd(), profileName);
                 process.stdout.write(args.json
                     ? `${JSON.stringify(findings, null, 2)}\n`
-                    : `${findings.map((finding) => `${finding.ok ? "ok  " : "FAIL"} ${finding.message}`).join("\n")}\n`);
+                    : `${findings.map(deploy_checks_1.formatFinding).join("\n")}\n`);
                 if (findings.some((finding) => !finding.ok))
                     process.exitCode = 1;
                 return;
@@ -561,7 +610,9 @@ async function main(argv) {
                 const plan = (0, deploy_1.planDeployment)(process.cwd(), profileName, args.release);
                 process.stdout.write(args.json
                     ? `${JSON.stringify(plan, null, 2)}\n`
-                    : `${plan.actions.map((entry) => `${entry.order}. ${entry.description}`).join("\n")}\nPlan hash: ${plan.planHash}\n`);
+                    : `${plan.actions.map((entry) => `${entry.order}. ${entry.description}`).join("\n")}\n` +
+                        `${plan.warnings.map((warning) => `warning: ${warning}`).join("\n")}\n` +
+                        `Plan hash: ${plan.planHash}\n`);
                 return;
             }
             if (action === "apply") {
@@ -672,12 +723,23 @@ async function main(argv) {
                         result.conflicts.map((f) => `  ${f}`).join("\n") +
                         "\n");
                 }
+                if (result.review.length) {
+                    process.stdout.write("\nThe template changed for these files you own; they were left as they are. " +
+                        "Compare each with podo diff <path>:\n" +
+                        result.review.map((f) => `  ${f}`).join("\n") +
+                        "\n");
+                }
                 return;
             }
             const plan = (0, update_1.planUpdate)(process.cwd(), templatesDir);
             const counts = (0, update_1.summarize)(plan);
             const shown = plan.changes.filter((c) => c.action !== "up-to-date" && c.action !== "skip");
             process.stdout.write(`podo update ${plan.fromVersion} -> ${plan.toVersion}  (template: ${plan.template}; modules: ${plan.modules.join(", ") || "none"})\n\n`);
+            if (plan.moduleDowngrades.length) {
+                process.stdout.write("WARN older external modules are installed than this project applied:\n" +
+                    `${(0, update_1.describeDowngrades)(plan.moduleDowngrades)}\n` +
+                    "--apply refuses until you install the recorded versions; the plan below would downgrade them.\n\n");
+            }
             if (plan.addedModules.length) {
                 process.stdout.write("Modules to add:\n" +
                     plan.addedModules.map((module) => `  ${module.name}  (${(0, update_1.addedModuleReason)(module)})`).join("\n") +
@@ -696,9 +758,10 @@ async function main(argv) {
                     process.stdout.write(`  ${c.action.padEnd(9)} ${path}  (${c.note})\n`);
                 }
                 process.stdout.write(`${shown.length ? "\n" : ""}${counts.update} update, ${counts.add} add, ${counts.move} move, ` +
-                    `${counts.remove} remove, ${counts.conflict} conflict. ` +
+                    `${counts.remove} remove, ${counts.conflict} conflict, ${counts.review} review. ` +
                     `Dry-run — nothing was written. Re-run with --apply to write (use --from <dir> for a 3-way merge).\n`);
             }
+            writeOwnedTemplateNotes(plan, templatesDir, args.from);
         }
         catch (err) {
             fail(err.message);
@@ -727,6 +790,23 @@ async function main(argv) {
         }
         return;
     }
+    if (args.command === "restore") {
+        const targets = args.positionals.slice(1);
+        if (!targets.length) {
+            fail("Usage: podo restore <path...>");
+        }
+        try {
+            const result = (0, template_files_1.restore)(process.cwd(), (0, node_path_1.join)(__dirname, "templates"), targets);
+            process.stdout.write(`Restored from the template: ${result.restored.join(", ")}\n`);
+            if (result.remanaged.length) {
+                process.stdout.write(`Managed by PodoKit again: ${result.remanaged.join(", ")}\n`);
+            }
+        }
+        catch (err) {
+            fail(err.message);
+        }
+        return;
+    }
     if (args.command !== "create") {
         fail(`Unknown command "${args.command}". Run "podo --help".`);
     }

package/dist/lib.d.ts

@@ -11,6 +11,8 @@ export { describeApiPaths } from "./module-api-paths";
 export { status, diff, doctor, SUPPORTED_FRAMEWORKS } from "./inspect";
 export type { StatusReport, DoctorFinding } from "./inspect";
 export { addedModuleReason, planUpdate, summarize } from "./update";
+export { restore, templateDiff } from "./template-files";
+export type { RestoreResult, TemplateDiffResult, TemplateFileDiff } from "./template-files";
 export type { AddedModule, UpdatePlan, FileChange } from "./update";
 export { readDevConfig, renderRoute, renderRuntimeCompose, resolveDevRuntime, runDevCommand } from "./dev";
 export type { CommandRunner, DevConfig, DevRuntime } from "./dev";

package/dist/lib.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyComposeDeployment = exports.renderComposeDeployment = exports.parseComposeProfile = exports.initializeComposeProfile = exports.readDeploymentDriver = exports.loadKubernetesProfile = exports.loadComposeProfile = exports.loadAnyDeploymentProfile = exports.listAnyDeploymentProfiles = exports.assertAnyReleaseTag = exports.DEPLOY_DRIVERS = exports.renderDeployment = exports.loadDeploymentProfile = exports.listDeploymentProfiles = exports.initializeDeploymentProfile = exports.deploymentProfileDigest = exports.assertReleaseTag = exports.verifyDeployment = exports.rollbackDeployment = exports.planRollback = exports.planDeployment = exports.inspectClusterFingerprint = exports.getDeploymentStatus = exports.doctorDeployment = exports.applyDeployment = exports.runDevCommand = exports.resolveDevRuntime = exports.renderRuntimeCompose = exports.renderRoute = exports.readDevConfig = exports.summarize = exports.planUpdate = exports.addedModuleReason = exports.SUPPORTED_FRAMEWORKS = exports.doctor = exports.diff = exports.status = exports.describeApiPaths = exports.addModule = exports.listModules = exports.isKnownTemplate = exports.TEMPLATE_NAMES = exports.DEFAULT_TEMPLATE = exports.TEMPLATES = exports.PROVIDERS_SOURCE = exports.providerSource = exports.planProviderChange = exports.listProviders = exports.applyProviderChange = exports.create = void 0;
-exports.verifyAnyDeployment = exports.planAnyDeployment = exports.getAnyDeploymentStatus = exports.doctorAnyDeployment = exports.describeDeploymentTarget = exports.verifyComposeDeployment = exports.rollbackComposeDeployment = exports.planComposeRollback = exports.planComposeDeployment = exports.inspectComposeEndpointFingerprint = exports.getComposeStatus = exports.doctorComposeDeployment = void 0;
+exports.parseComposeProfile = exports.initializeComposeProfile = exports.readDeploymentDriver = exports.loadKubernetesProfile = exports.loadComposeProfile = exports.loadAnyDeploymentProfile = exports.listAnyDeploymentProfiles = exports.assertAnyReleaseTag = exports.DEPLOY_DRIVERS = exports.renderDeployment = exports.loadDeploymentProfile = exports.listDeploymentProfiles = exports.initializeDeploymentProfile = exports.deploymentProfileDigest = exports.assertReleaseTag = exports.verifyDeployment = exports.rollbackDeployment = exports.planRollback = exports.planDeployment = exports.inspectClusterFingerprint = exports.getDeploymentStatus = exports.doctorDeployment = exports.applyDeployment = exports.runDevCommand = exports.resolveDevRuntime = exports.renderRuntimeCompose = exports.renderRoute = exports.readDevConfig = exports.templateDiff = exports.restore = exports.summarize = exports.planUpdate = exports.addedModuleReason = exports.SUPPORTED_FRAMEWORKS = exports.doctor = exports.diff = exports.status = exports.describeApiPaths = exports.addModule = exports.listModules = exports.isKnownTemplate = exports.TEMPLATE_NAMES = exports.DEFAULT_TEMPLATE = exports.TEMPLATES = exports.PROVIDERS_SOURCE = exports.providerSource = exports.planProviderChange = exports.listProviders = exports.applyProviderChange = exports.create = void 0;
+exports.verifyAnyDeployment = exports.planAnyDeployment = exports.getAnyDeploymentStatus = exports.doctorAnyDeployment = exports.describeDeploymentTarget = exports.verifyComposeDeployment = exports.rollbackComposeDeployment = exports.planComposeRollback = exports.planComposeDeployment = exports.inspectComposeEndpointFingerprint = exports.getComposeStatus = exports.doctorComposeDeployment = exports.applyComposeDeployment = exports.renderComposeDeployment = void 0;
 exports.builtinTemplatesDir = builtinTemplatesDir;
 exports.builtinModulesDir = builtinModulesDir;
 // Library entry point: the reusable functions behind the `podo` CLI, for other
@@ -34,6 +34,9 @@ var update_1 = require("./update");
 Object.defineProperty(exports, "addedModuleReason", { enumerable: true, get: function () { return update_1.addedModuleReason; } });
 Object.defineProperty(exports, "planUpdate", { enumerable: true, get: function () { return update_1.planUpdate; } });
 Object.defineProperty(exports, "summarize", { enumerable: true, get: function () { return update_1.summarize; } });
+var template_files_1 = require("./template-files");
+Object.defineProperty(exports, "restore", { enumerable: true, get: function () { return template_files_1.restore; } });
+Object.defineProperty(exports, "templateDiff", { enumerable: true, get: function () { return template_files_1.templateDiff; } });
 var dev_1 = require("./dev");
 Object.defineProperty(exports, "readDevConfig", { enumerable: true, get: function () { return dev_1.readDevConfig; } });
 Object.defineProperty(exports, "renderRoute", { enumerable: true, get: function () { return dev_1.renderRoute; } });

package/dist/lockfile.d.ts

@@ -51,6 +51,12 @@ export interface FileEntry {
     tier: Tier;
     /** Hash of the exact bytes PodoKit last wrote; user-edit detector. */
     outHash: string;
+    /**
+     * Owned files only: hash of what the template generated for the path when
+     * PodoKit last rendered it, so `podo update` can tell the application that
+     * the template changed without touching the file.
+     */
+    templateHash?: string;
 }
 export interface FilesLock {
     schemaVersion: number;
@@ -68,6 +74,12 @@ export interface RecordModulesLockSnapshot {
 }
 /** Default user-owned globs seeded into a new project. See ADR-0010. */
 export declare const DEFAULT_OWNED_GLOBS: string[];
+/**
+ * PodoKit's own agent skills stay managed inside the owned `.claude/**` and
+ * `.agents/**` trees, so updates keep their commands and APIs current. Skills an
+ * application adds under other names stay owned.
+ */
+export declare const DEFAULT_MANAGED_OVERRIDES: string[];
 export declare function manifestPath(projectRoot: string): string;
 export declare function filesLockPath(projectRoot: string): string;
 export declare function readManifest(projectRoot: string): PodokitManifest | null;
@@ -93,6 +105,18 @@ export declare function isLocalEnvFile(relPath: string): boolean;
 export declare function walkFiles(projectRoot: string, prefix?: string): string[];
 /** Recompute the files.lock by hashing and classifying every project file. */
 export declare function computeFilesLock(projectRoot: string, ownedGlobs: string[], managedOverrides?: string[]): FilesLock;
+/**
+ * The template content an earlier lock knew for a path: the recorded template
+ * hash of an owned file, or the generated baseline of a managed one.
+ */
+export declare function recordedTemplateHash(entry: FileEntry | undefined): string | undefined;
+/**
+ * Carry the template hashes of an earlier lock into a recomputed one for files
+ * that are owned now. Paths in `changed` were just rewritten from a different
+ * template, such as the files a module added to or removed from, so their old
+ * hash would be wrong and is dropped.
+ */
+export declare function keepTemplateHashes(next: FilesLock, previous: FilesLock | null, changed?: Iterable<string>): FilesLock;
 export declare function readFilesLock(projectRoot: string): FilesLock | null;
 export interface Drift {
     /** Managed/assembled files whose content differs from what PodoKit wrote. */

package/dist/lockfile.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_OWNED_GLOBS = exports.LOCK_SCHEMA_VERSION = void 0;
+exports.DEFAULT_MANAGED_OVERRIDES = exports.DEFAULT_OWNED_GLOBS = exports.LOCK_SCHEMA_VERSION = void 0;
 exports.manifestPath = manifestPath;
 exports.filesLockPath = filesLockPath;
 exports.readManifest = readManifest;
@@ -14,6 +14,8 @@ exports.classifyTier = classifyTier;
 exports.isLocalEnvFile = isLocalEnvFile;
 exports.walkFiles = walkFiles;
 exports.computeFilesLock = computeFilesLock;
+exports.recordedTemplateHash = recordedTemplateHash;
+exports.keepTemplateHashes = keepTemplateHashes;
 exports.readFilesLock = readFilesLock;
 exports.computeDrift = computeDrift;
 exports.initLockfile = initLockfile;
@@ -55,11 +57,23 @@ exports.DEFAULT_OWNED_GLOBS = [
     "apps/web/src/lib/i18n/catalogs/app/**",
     // Owned Elysia extension slot — register application services and plugins here.
     "apps/api/src/app.extensions.ts",
+    // Owned application environment variables, validated with PodoKit's.
+    "apps/api/src/config/env.extensions.ts",
+    // Owned TypeORM entities the migration data source loads.
+    "apps/api/src/database/entities.ts",
+    // Owned application operations that `bun run contract` requires.
+    "apps/api/src/core/api-contract.extensions.ts",
+    // Owned entry points the API build bundles next to PodoKit's.
+    "apps/api/scripts/build.extensions.mjs",
     // Owned additions to the managed /api proxy's header lists, body limits, and
     // response deadlines.
     "apps/web/src/lib/server/proxy-headers.ts",
     "apps/web/src/lib/server/body-limits.ts",
     "apps/web/src/lib/server/proxy-timeouts.ts",
+    // Owned additions to the managed Vite and SvelteKit configuration.
+    "apps/web/vite.extensions.ts",
+    // Owned styles the managed app.css imports last.
+    "apps/web/src/app.extensions.css",
     // Owned fallback page SvelteKit serves when the root layout or a hook fails.
     "apps/web/src/error.html",
     // AI agent guidance — yours to customize; update never touches it.
@@ -81,6 +95,27 @@ exports.DEFAULT_OWNED_GLOBS = [
     ".podokit/dev.json",
     // Optional application-owned Playwright device/browser projects.
     "tests/playwright.projects.cjs",
+    // Application screens the managed e2e specs visit.
+    "tests/helpers/app-paths.ts",
+    // Project documents, ignore rules, environment examples, and example
+    // manifests every application rewrites. PodoKit seeds them once, `podo add`
+    // still appends module environment lines and wiring, and `podo update`
+    // reports their template changes for review instead of merging them.
+    "README.md",
+    "tests/README.md",
+    ".gitignore",
+    ".env.example",
+    ".env.docker.example",
+    "infra/k3s/**",
+];
+/**
+ * PodoKit's own agent skills stay managed inside the owned `.claude/**` and
+ * `.agents/**` trees, so updates keep their commands and APIs current. Skills an
+ * application adds under other names stay owned.
+ */
+exports.DEFAULT_MANAGED_OVERRIDES = [
+    ".claude/skills/podokit-*/**",
+    ".agents/skills/podokit-*/**",
 ];
 const TEXT_EXT = /\.(json|md|ts|tsx|js|mjs|cjs|css|html|yml|yaml|txt|env|svelte|gitignore|example)$/i;
 function podokitDir(projectRoot) {
@@ -209,6 +244,34 @@ function computeFilesLock(projectRoot, ownedGlobs, managedOverrides = []) {
     }
     return { schemaVersion: exports.LOCK_SCHEMA_VERSION, files };
 }
+/**
+ * The template content an earlier lock knew for a path: the recorded template
+ * hash of an owned file, or the generated baseline of a managed one.
+ */
+function recordedTemplateHash(entry) {
+    if (!entry)
+        return undefined;
+    return entry.tier === "owned" ? entry.templateHash : entry.outHash;
+}
+/**
+ * Carry the template hashes of an earlier lock into a recomputed one for files
+ * that are owned now. Paths in `changed` were just rewritten from a different
+ * template, such as the files a module added to or removed from, so their old
+ * hash would be wrong and is dropped.
+ */
+function keepTemplateHashes(next, previous, changed = []) {
+    if (!previous)
+        return next;
+    const skip = new Set(changed);
+    for (const [path, entry] of Object.entries(next.files)) {
+        if (entry.tier !== "owned" || entry.templateHash || skip.has(path))
+            continue;
+        const templateHash = recordedTemplateHash(previous.files[path]);
+        if (templateHash)
+            entry.templateHash = templateHash;
+    }
+    return next;
+}
 function readFilesLock(projectRoot) {
     const file = filesLockPath(projectRoot);
     if (!(0, node_fs_1.existsSync)(file))
@@ -246,6 +309,7 @@ function computeDrift(projectRoot) {
 /** Write the initial `.podokit/` lockfile for a freshly created project. */
 function initLockfile(projectRoot, options) {
     const ownedGlobs = options.ownedGlobs ?? exports.DEFAULT_OWNED_GLOBS;
+    const managedOverrides = [...exports.DEFAULT_MANAGED_OVERRIDES];
     const providers = (0, podokit_runtime_1.resolveProviderSelections)(options.providers ?? podokit_runtime_1.SERVER_PROVIDER_SELECTIONS);
     const manifest = {
         schemaVersion: exports.LOCK_SCHEMA_VERSION,
@@ -256,10 +320,16 @@ function initLockfile(projectRoot, options) {
         providers,
         modules: [],
         ownedGlobs,
-        managedOverrides: [],
+        managedOverrides,
     };
     writeManifest(projectRoot, manifest);
-    writeFilesLock(projectRoot, computeFilesLock(projectRoot, ownedGlobs));
+    const lock = computeFilesLock(projectRoot, ownedGlobs, managedOverrides);
+    // Create wrote every file straight from the template.
+    for (const entry of Object.values(lock.files)) {
+        if (entry.tier === "owned")
+            entry.templateHash = entry.outHash;
+    }
+    writeFilesLock(projectRoot, lock);
 }
 /** Union two glob lists, preserving order and dropping duplicates. Used to fold
  *  module-declared and ejected owned paths into the project's `ownedGlobs`, which
@@ -359,5 +429,5 @@ insertBefore) {
             continue;
         files[path] = current;
     }
-    writeFilesLock(projectRoot, { schemaVersion: exports.LOCK_SCHEMA_VERSION, files });
+    writeFilesLock(projectRoot, keepTemplateHashes({ schemaVersion: exports.LOCK_SCHEMA_VERSION, files }, lockSnapshot.previous, modulePaths));
 }

package/dist/provider.js

@@ -29,16 +29,20 @@ function assertProvider(capability, provider) {
 }
 /** The managed provider source; it must render byte for byte like the template's copy. */
 function providerSource(providers) {
-    return `import type { ProviderSelections } from "@podosoft/podokit-runtime";\n\n` +
-        `// Typed with every provider name, not the selected ones: the module of a\n` +
+    return `import type { ProviderSelections } from "@podosoft/podokit-runtime";\n` +
+        `import { providersFromEnvironment } from "./provider-selection";\n\n` +
+        `// The providers selected when the project was generated or by \`podo provider\n` +
+        `// set\`. Typed with every provider name, not the selected ones: the module of a\n` +
         `// provider that stays installed after a switch compares against its own name.\n` +
-        `export const PROVIDERS: Readonly<ProviderSelections> = {\n` +
+        `// A <CAPABILITY>_PROVIDER variable replaces one at startup; see\n` +
+        `// provider-selection.ts.\n` +
+        `export const PROVIDERS: Readonly<ProviderSelections> = providersFromEnvironment({\n` +
         `  database: "${providers.database}",\n` +
         `  cache: "${providers.cache}",\n` +
         `  "object-storage": "${providers["object-storage"]}",\n` +
         `  events: "${providers.events}",\n` +
         `  jobs: "${providers.jobs}",\n` +
-        `};\n`;
+        `});\n`;
 }
 function listProviders(projectRoot) {
     const manifest = requireManifest(projectRoot);
@@ -122,6 +126,7 @@ function applyProviderChange(projectRoot, capabilityInput, provider, options = {
         [manifestFile, (0, node_fs_1.readFileSync)(manifestFile, "utf8")],
         [lockFile, (0, node_fs_1.existsSync)(lockFile) ? (0, node_fs_1.readFileSync)(lockFile, "utf8") : null],
     ]);
+    const previousLock = (0, lockfile_1.readFilesLock)(projectRoot);
     const temporary = `${sourcePath}.podokit-provider-${process.pid}`;
     try {
         manifest.providers[plan.capability] = plan.to;
@@ -129,7 +134,7 @@ function applyProviderChange(projectRoot, capabilityInput, provider, options = {
         (0, node_fs_1.writeFileSync)(temporary, providerSource(manifest.providers), { mode: 0o600 });
         (0, node_fs_1.renameSync)(temporary, sourcePath);
         (0, lockfile_1.writeManifest)(projectRoot, manifest);
-        (0, lockfile_1.writeFilesLock)(projectRoot, (0, lockfile_1.computeFilesLock)(projectRoot, manifest.ownedGlobs, manifest.managedOverrides ?? []));
+        (0, lockfile_1.writeFilesLock)(projectRoot, (0, lockfile_1.keepTemplateHashes)((0, lockfile_1.computeFilesLock)(projectRoot, manifest.ownedGlobs, manifest.managedOverrides ?? []), previousLock));
     }
     catch (error) {
         (0, node_fs_1.rmSync)(temporary, { force: true });

package/dist/remove.js

@@ -135,7 +135,7 @@ function removeModule(options) {
         sharedOwnedGlobs.has(glob) ||
         keptEdited.some((path) => (0, lockfile_1.matchGlob)(path, glob)));
     (0, lockfile_1.writeManifest)(projectRoot, manifest);
-    (0, lockfile_1.writeFilesLock)(projectRoot, (0, lockfile_1.computeFilesLock)(projectRoot, manifest.ownedGlobs, manifest.managedOverrides));
+    (0, lockfile_1.writeFilesLock)(projectRoot, (0, lockfile_1.keepTemplateHashes)((0, lockfile_1.computeFilesLock)(projectRoot, manifest.ownedGlobs, manifest.managedOverrides), lock, [...unwired, ".env.example"]));
     return { module, removed, keptEdited, keptShared, unwired, apiPaths };
 }
 /** Remove now-empty directories left behind by a deleted file, up to the root. */

package/dist/template-files.d.ts

@@ -0,0 +1,42 @@
+import { type Tier } from "./lockfile";
+/**
+ * `podo diff <path>` and `podo restore <path>`: compare a working file with
+ * what the installed CLI's templates generate for it, and put a managed or
+ * ejected file back to that content.
+ */
+export type TemplateFileStatus = "same" | "differs" | "missing" | "not-generated";
+export interface TemplateFileDiff {
+    path: string;
+    /** Ownership tier the lock records, or null for a file the lock does not track. */
+    tier: Tier | null;
+    status: TemplateFileStatus;
+    /** Unified diff from the template to the working file; empty unless it differs. */
+    diff: string;
+    /** Whether either side is binary, so no line diff is shown. */
+    binary: boolean;
+}
+export interface TemplateDiffResult {
+    /** PodoKit version the project was generated or last updated with. */
+    projectVersion: string;
+    /** Version of the CLI whose templates were rendered. */
+    templateVersion: string;
+    files: TemplateFileDiff[];
+}
+/** Normalize a user-supplied path to the lock's POSIX project-relative form. */
+export declare function projectPath(path: string): string;
+export declare function templateDiff(projectRoot: string, templatesDir: string, paths: string[]): TemplateDiffResult;
+export interface RestoreResult {
+    /** Files rewritten from the template. */
+    restored: string[];
+    /** Files that were ejected and are managed again. */
+    remanaged: string[];
+}
+/**
+ * Rewrite managed or assembled files with the template's content and record
+ * that content as the lock baseline. A file that `podo eject` made owned is
+ * handed back to PodoKit: its exact path leaves the manifest's owned paths, so
+ * future updates manage it again. Files owned because a template or module
+ * declares them owned, such as routes, are refused. Nothing is written unless
+ * every path can be restored.
+ */
+export declare function restore(projectRoot: string, templatesDir: string, paths: string[]): RestoreResult;

package/dist/template-files.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectPath = projectPath;
+exports.templateDiff = templateDiff;
+exports.restore = restore;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
+const lockfile_1 = require("./lockfile");
+const update_1 = require("./update");
+const text_diff_1 = require("./text-diff");
+/** Normalize a user-supplied path to the lock's POSIX project-relative form. */
+function projectPath(path) {
+    const normalized = (0, node_path_1.normalize)(path).split(node_path_1.sep).join("/").replace(/^\.\//, "");
+    if (normalized.startsWith("../") || normalized === ".." || normalized.startsWith("/")) {
+        throw new Error(`${path} is outside the project.`);
+    }
+    return normalized;
+}
+function isUtf8Text(content) {
+    return !content.includes(0) && Buffer.from(content.toString("utf8"), "utf8").equals(content);
+}
+function fileBuffer(file) {
+    return typeof file.content === "string" ? Buffer.from(file.content, "utf8") : file.content;
+}
+function templateDiff(projectRoot, templatesDir, paths) {
+    const target = (0, update_1.targetProject)(projectRoot, templatesDir);
+    const templateVersion = (0, lockfile_1.podokitVersion)();
+    const files = paths.map((input) => {
+        const path = projectPath(input);
+        const tier = target.lock.files[path]?.tier ?? null;
+        const generated = target.tree.get(path);
+        const abs = (0, node_path_1.join)(projectRoot, path);
+        if (!generated) {
+            return { path, tier, status: "not-generated", diff: "", binary: false };
+        }
+        if (!(0, node_fs_1.existsSync)(abs))
+            return { path, tier, status: "missing", diff: "", binary: false };
+        const templateBytes = fileBuffer(generated);
+        const diskBytes = (0, node_fs_1.readFileSync)(abs);
+        if (templateBytes.equals(diskBytes)) {
+            return { path, tier, status: "same", diff: "", binary: false };
+        }
+        const binary = !isUtf8Text(templateBytes) || !isUtf8Text(diskBytes);
+        return {
+            path,
+            tier,
+            status: "differs",
+            binary,
+            diff: binary
+                ? ""
+                : (0, text_diff_1.unifiedDiff)(templateBytes.toString("utf8"), diskBytes.toString("utf8"), {
+                    fromLabel: `podokit-${templateVersion}/${path}`,
+                    toLabel: path,
+                }),
+        };
+    });
+    return { projectVersion: target.manifest.podokitVersion, templateVersion, files };
+}
+/**
+ * Rewrite managed or assembled files with the template's content and record
+ * that content as the lock baseline. A file that `podo eject` made owned is
+ * handed back to PodoKit: its exact path leaves the manifest's owned paths, so
+ * future updates manage it again. Files owned because a template or module
+ * declares them owned, such as routes, are refused. Nothing is written unless
+ * every path can be restored.
+ */
+function restore(projectRoot, templatesDir, paths) {
+    const target = (0, update_1.targetProject)(projectRoot, templatesDir);
+    const cliVersion = (0, lockfile_1.podokitVersion)();
+    if (target.manifest.podokitVersion !== cliVersion) {
+        throw new Error(`This project is on PodoKit ${target.manifest.podokitVersion} and this CLI renders ${cliVersion}. ` +
+            "Run podo update --apply first, or restore with the CLI version the project is on.");
+    }
+    const declared = new Set((0, update_1.declaredOwnedGlobs)(projectRoot, templatesDir, target.modules));
+    const requested = [...new Set(paths.map(projectPath))];
+    const ejected = requested.filter((path) => target.manifest.ownedGlobs.includes(path) && !declared.has(path));
+    const ownedGlobs = target.manifest.ownedGlobs.filter((glob) => !ejected.includes(glob));
+    const classifyGlobs = [...new Set([...declared, ...ownedGlobs])];
+    const writes = [];
+    for (const path of requested) {
+        const file = target.tree.get(path);
+        if (!file)
+            throw new Error(`PodoKit does not generate ${path}, so there is nothing to restore.`);
+        const tier = (0, lockfile_1.classifyTier)(path, fileBuffer(file), classifyGlobs, target.managedOverrides);
+        if (tier === "owned") {
+            throw new Error(`${path} is owned by the application through the template or a module, so PodoKit never manages it. ` +
+                `Run podo diff ${path} to see the template's version.`);
+        }
+        writes.push({ path, file, tier });
+    }
+    for (const { path, file, tier } of writes) {
+        const abs = (0, node_path_1.join)(projectRoot, path);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(abs), { recursive: true });
+        (0, node_fs_1.writeFileSync)(abs, file.content);
+        target.lock.files[path] = { tier, outHash: (0, podokit_template_engine_1.hashContent)(fileBuffer(file)) };
+    }
+    (0, lockfile_1.writeFilesLock)(projectRoot, target.lock);
+    if (ejected.length)
+        (0, lockfile_1.writeManifest)(projectRoot, { ...target.manifest, ownedGlobs });
+    return { restored: writes.map((write) => write.path), remanaged: ejected };
+}