@podosoft/podokit 1.5.0 → 1.6.0

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 };
+}

package/dist/templates/fullstack/AGENTS.md

@@ -54,7 +54,20 @@ Merge added module settings from `.env.example` into an existing `.env`.
   `apps/web/src/lib/server/proxy-timeouts.ts` (`APP_PROXY_TIMEOUTS`, `null` for
   none); never edit the managed deadline. Both lists take path prefixes with
   `:name` parameters, such as `/api/hosts/:hostId/file-transfers`, and the most
-  specific prefix wins.
+  specific prefix wins. The proxy and `serverApiClient` send the request's public
+  origin to the API in `x-forwarded-host`/`x-forwarded-proto` only when
+  `CORS_ORIGIN` lists it; an API route may use them to choose among its configured
+  origins, never as a new origin.
+- `apps/web/src/app.css` is managed. Put application styles (theme variable
+  overrides, `@theme` entries, fonts, base styles, and `@source` for packages
+  whose built components use Tailwind classes) in the app-owned
+  `apps/web/src/app.extensions.css`, which `app.css` imports last.
+- `apps/web/vite.config.ts` is managed. Put Vite options (warmup, `optimizeDeps`,
+  `define`, plugins, allowed hosts) in `appViteConfig` and SvelteKit options
+  (`alias`, `csrf`) in `appSvelteKitConfig` of the app-owned
+  `apps/web/vite.extensions.ts`. `bun run dev` proxies the exact
+  `webSocketPaths` of `.podokit/dev.json` to the API like the `podo dev` gateway,
+  so do not add a WebSocket proxy of your own.
 - Server-side API calls (`serverApiClient`) give up after `BACKEND_TIMEOUT_MS`
   (2000), and the proxy answers 504 `BACKEND_TIMEOUT` when the API sends no
   response headers within `BACKEND_PROXY_TIMEOUT_MS` (30000). Once the API's
@@ -86,7 +99,17 @@ 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`.
+- Name a migration `apps/api/src/migrations/<timestamp>-<Name>.ts` with exactly one exported
+  migration class. The build lists compiled migrations in `dist/migrations/migrations.json` and
+  fails when one is lost; `{{apiRun}} migrate:list` prints what a build would run.
+- 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`. The managed specs
+  read the app's first screen, public pages, and seeded accounts from the owned
+  `tests/helpers/app-paths.ts` (and `app-accounts.ts` with admin-dashboard): change those
+  instead of editing or ejecting a managed spec, and test the app's own screens in specs of its own.
 - 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.
@@ -121,7 +144,7 @@ changes need an e2e/unit test.
 This project is managed by the `podo` CLI. Files have an ownership tier recorded
 in `.podokit/files.lock` — respect it:
 
-- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. Add application-owned services or module descriptors through `app.extensions.ts` instead of changing toolkit registrations. Set Bun server options (`maxRequestBodySize`, `idleTimeout`) with its `apiServerOptions` export rather than editing `main.ts`; `API_MAX_REQUEST_BODY_SIZE` and `API_IDLE_TIMEOUT` apply when the export leaves them out.
+- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. Add application-owned services or module descriptors through `app.extensions.ts` instead of changing toolkit registrations. Set Bun server options (`maxRequestBodySize`, `idleTimeout`) with its `apiServerOptions` export rather than editing `main.ts`; `API_MAX_REQUEST_BODY_SIZE` and `API_IDLE_TIMEOUT` apply when the export leaves them out. Declare application environment variables in the owned `apps/api/src/config/env.extensions.ts` (`appEnvShape`, `refineAppEnv`) instead of editing `env.validation.ts`, and TypeORM entities in `APP_ENTITIES` of the owned `apps/api/src/database/entities.ts` instead of editing `data-source.ts`. List the operations your API must keep in `APP_DOCUMENTED_ROUTES` of the owned `apps/api/src/core/api-contract.extensions.ts`; `{{apiRun}} contract` checks they are registered and documented. With `auth`, declare app on/off settings in `APP_FLAG_DEFAULTS` of the owned `apps/api/src/settings/app-flags.ts` instead of editing `flag-defaults.ts`.
 - **assembled** (e.g. `apps/api/src/app.ts`, `auth.ts`) — contain `// podokit:begin:… / …:end` fenced regions that the toolkit recomputes. Edit outside the fences only; **never hand-edit inside the fences**.
 - **managed** (bootstrap/config like `main.ts`) — the toolkit may update these; avoid gratuitous edits.
 
@@ -140,7 +163,8 @@ Useful commands:
 - `podo add <module>` — add a feature (auth, admin-dashboard, redis, bullmq, …). It wires itself into the app; run `podo add` with no argument to list modules.
 - `podo remove <module>` — un-apply a module (inverse of add; refuses if another module needs it, keeps files you edited).
 - `podo provider list` / `podo provider set <capability> <provider> [--apply]` — inspect or switch database, cache, object storage, events, and jobs. Set is dry-run by default and never migrates or deletes provider data. Local providers require one API process.
-- `podo status` / `podo diff` — see your local edits vs. what PodoKit generated.
+- `podo status` / `podo diff` — see your local edits vs. what PodoKit generated; `podo diff <path>` shows a file's line diff against the template, owned files included.
+- `podo restore <path>` — rewrite a managed file from the template, or hand an ejected file back to PodoKit.
 - `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
 - `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Production API WebSocket paths belong in the deployment profile's exact `exposure.webSocketPaths` allowlist, and API routes that take bodies above the web server's `BODY_SIZE_LIMIT` (file uploads) in `exposure.apiPaths` (and `.podokit/dev.json` `apiPaths` for `podo dev`; `podo add` and `podo deploy init` fill in the paths modules declare), which reach the API without the web proxy, so the API must check their size, session, and `Origin` itself; Compose trusts forwarding headers only from `exposure.trustedProxyCidrs`. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.
 - `podo deploy sync` — copy local build output into a running Compose deployment and restart it, for iterating without a release. Not a release: no image is published and the next `apply` discards it. Use `.agents/skills/podokit-deploy-fast`.

package/dist/templates/fullstack/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.
@@ -188,11 +189,11 @@ HTTP, fix its public origin at build time instead:
 docker build --build-arg PODOKIT_BUILD_ORIGIN=https://example.com -f apps/web/Dockerfile -t {{projectName}}-web .
 ```
 
-For a Docker Compose deployment behind a trusted reverse proxy, set
-`PROTOCOL_HEADER=x-forwarded-proto` and `HOST_HEADER=x-forwarded-host` in the
-deployment profile runtime configuration and list the proxy's direct CIDR blocks in
-`exposure.trustedProxyCidrs`. Never trust client-controlled forwarded headers on a
-directly exposed container.
+Set `exposure.edgeProxies` in the deployment profile to the number of reverse
+proxies in front of the deployment; PodoKit derives which forwarded headers web and
+API trust from it, and trusts none when it is `0`. With a Compose gateway, also list
+the proxy's direct CIDR blocks in `exposure.trustedProxyCidrs`. Never count a proxy
+that clients can bypass.
 
 If the production API exposes WebSocket endpoints, list their exact paths under
 `exposure.webSocketPaths` in the deployment profile. The Compose driver then keeps a

package/dist/templates/fullstack/apps/api/package.json

@@ -10,14 +10,15 @@
     "test": "bun test src",
     "contract": "bun scripts/verify-api-contract.ts",
     "migrate:all": "bun scripts/run-migrations.mjs",
-    "typeorm": "bunx typeorm-ts-node-commonjs -d src/database/data-source.ts",
+    "migrate:list": "bun scripts/run-migrations.mjs --list",
+    "typeorm": "bunx --bun typeorm -d src/database/data-source.ts",
     "migration:run": "bun src/database/migrate.ts",
     "migration:revert": "bun src/database/migrate.ts --revert",
     "migration:generate": "bun run typeorm -- migration:generate"
   },
   "dependencies": {
-    "@podosoft/podokit-contracts": "^0.5.0",
-    "@podosoft/podokit-runtime": "^0.4.1",
+    "@podosoft/podokit-contracts": "^0.6.0",
+    "@podosoft/podokit-runtime": "^0.5.0",
     "@elysia/cors": "^1.4.2",
     "@elysia/openapi": "^1.4.15",
     "dotenv": "^16.4.5",
@@ -30,7 +31,6 @@
   "devDependencies": {
     "@types/bun": "^1.3.9",
     "@types/node": "^20.17.0",
-    "ts-node": "^10.9.2",
     "typescript": "^6.0.3"
   }
 }

package/dist/templates/fullstack/apps/api/scripts/build.extensions.mjs

@@ -0,0 +1,6 @@
+// This owned file is never overwritten by `podo update`. List entry points the
+// API build bundles next to PodoKit's, such as a maintenance command run from
+// the image. Each must exist. For example:
+//
+//   export const appBuildTargets = [{ entrypoint: "scripts/repair-data.ts", outdir: "dist/scripts" }];
+export const appBuildTargets = [];