@podosoft/podokit 0.6.0 → 0.8.0

package/dist/add.d.ts

@@ -5,7 +5,12 @@ interface Injection {
     /** Skip (instead of failing) if the target file or marker is absent. */
     optional?: boolean;
 }
+/** Highest `module.manifest.json` schema version this CLI understands. A package
+ *  module declaring a higher version is rejected rather than mis-applied. */
+export declare const SUPPORTED_MANIFEST_VERSION = 1;
 export interface ModuleManifest {
+    /** Manifest schema version. Absent (bundled modules) means "same as the CLI". */
+    manifestVersion?: number;
     name: string;
     description: string;
     requires?: string[];
@@ -16,6 +21,11 @@ export interface ModuleManifest {
     env?: string[];
     inject?: Injection[];
     instructions?: string[];
+    /** App-relative globs this module's files should own (durably user-editable,
+     *  never touched by `podo update`). Merged into the project's ownedGlobs so
+     *  they survive lock recompute. Use for public presentation pages a consumer
+     *  restyles, while keeping the module's `$lib` logic managed. */
+    ownedGlobs?: string[];
 }
 export interface AddOptions {
     projectRoot: string;
@@ -29,9 +39,19 @@ export interface AddResult {
     instructions: string[];
     /** Required modules that were auto-added because they were missing. */
     added: string[];
+    /** ownedGlobs declared by this module and every module it pulled in. */
+    ownedGlobs: string[];
 }
-/** List modules available under `modulesDir` (each has a module.manifest.json). */
-export declare function listModules(modulesDir: string): {
+/**
+ * Resolve a module's directory by name: first the bundled `modulesDir`, then a
+ * node-resolvable npm package `@podosoft/podokit-module-<name>` installed in the
+ * project (or a fully-qualified `@scope/pkg` name). Returns null if not found.
+ */
+export declare function resolveModuleDir(name: string, modulesDir: string, projectRoot: string): string | null;
+/** List modules available to a project: the bundled ones under `modulesDir` plus,
+ *  when `projectRoot` is given, any `@podosoft/podokit-module-*` packages installed
+ *  in it. Bundled names take precedence on a clash. */
+export declare function listModules(modulesDir: string, projectRoot?: string): {
     name: string;
     description: string;
 }[];

package/dist/add.js

@@ -1,21 +1,69 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_MANIFEST_VERSION = void 0;
+exports.resolveModuleDir = resolveModuleDir;
 exports.listModules = listModules;
 exports.addModule = addModule;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const node_module_1 = require("node:module");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const lockfile_1 = require("./lockfile");
-/** List modules available under `modulesDir` (each has a module.manifest.json). */
-function listModules(modulesDir) {
-    if (!(0, node_fs_1.existsSync)(modulesDir))
-        return [];
-    return (0, node_fs_1.readdirSync)(modulesDir)
-        .filter((name) => (0, node_fs_1.existsSync)((0, node_path_1.join)(modulesDir, name, "module.manifest.json")))
-        .map((name) => {
-        const manifest = readManifest((0, node_path_1.join)(modulesDir, name));
-        return { name, description: manifest.description };
-    });
+/** Highest `module.manifest.json` schema version this CLI understands. A package
+ *  module declaring a higher version is rejected rather than mis-applied. */
+exports.SUPPORTED_MANIFEST_VERSION = 1;
+const PACKAGE_PREFIX = "@podosoft/podokit-module-";
+/**
+ * Resolve a module's directory by name: first the bundled `modulesDir`, then a
+ * node-resolvable npm package `@podosoft/podokit-module-<name>` installed in the
+ * project (or a fully-qualified `@scope/pkg` name). Returns null if not found.
+ */
+function resolveModuleDir(name, modulesDir, projectRoot) {
+    const bundled = (0, node_path_1.join)(modulesDir, name);
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(bundled, "module.manifest.json")))
+        return bundled;
+    const pkg = name.includes("/") ? name : `${PACKAGE_PREFIX}${name}`;
+    try {
+        const req = (0, node_module_1.createRequire)((0, node_path_1.join)(projectRoot, "package.json"));
+        return (0, node_path_1.dirname)(req.resolve(`${pkg}/module.manifest.json`));
+    }
+    catch {
+        return null;
+    }
+}
+function assertManifestVersion(name, manifest) {
+    if ((manifest.manifestVersion ?? exports.SUPPORTED_MANIFEST_VERSION) > exports.SUPPORTED_MANIFEST_VERSION) {
+        throw new Error(`Module "${name}" needs a newer PodoKit (manifest v${manifest.manifestVersion}, this CLI supports v${exports.SUPPORTED_MANIFEST_VERSION}). Update @podosoft/podokit.`);
+    }
+}
+/** List modules available to a project: the bundled ones under `modulesDir` plus,
+ *  when `projectRoot` is given, any `@podosoft/podokit-module-*` packages installed
+ *  in it. Bundled names take precedence on a clash. */
+function listModules(modulesDir, projectRoot) {
+    const out = new Map();
+    if ((0, node_fs_1.existsSync)(modulesDir)) {
+        for (const name of (0, node_fs_1.readdirSync)(modulesDir)) {
+            if ((0, node_fs_1.existsSync)((0, node_path_1.join)(modulesDir, name, "module.manifest.json"))) {
+                out.set(name, readManifest((0, node_path_1.join)(modulesDir, name)).description);
+            }
+        }
+    }
+    if (projectRoot) {
+        const scope = (0, node_path_1.join)(projectRoot, "node_modules", "@podosoft");
+        if ((0, node_fs_1.existsSync)(scope)) {
+            for (const dir of (0, node_fs_1.readdirSync)(scope)) {
+                if (!dir.startsWith("podokit-module-"))
+                    continue;
+                const manifestPath = (0, node_path_1.join)(scope, dir, "module.manifest.json");
+                if (!(0, node_fs_1.existsSync)(manifestPath))
+                    continue;
+                const manifest = readManifest((0, node_path_1.join)(scope, dir));
+                if (!out.has(manifest.name))
+                    out.set(manifest.name, manifest.description);
+            }
+        }
+    }
+    return [...out].map(([name, description]) => ({ name, description }));
 }
 function readManifest(moduleDir) {
     return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8"));
@@ -40,10 +88,10 @@ function appendEnv(projectRoot, lines) {
 }
 /** Heuristic: is `module` already applied to the project? */
 function isApplied(projectRoot, modulesDir, module) {
-    const manifestPath = (0, node_path_1.join)(modulesDir, module, "module.manifest.json");
-    if (!(0, node_fs_1.existsSync)(manifestPath))
+    const moduleDir = resolveModuleDir(module, modulesDir, projectRoot);
+    if (!moduleDir)
         return false;
-    const manifest = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf8"));
+    const manifest = readManifest(moduleDir);
     const firstInject = manifest.inject?.[0];
     if (firstInject) {
         const target = (0, node_path_1.join)(projectRoot, firstInject.file);
@@ -58,17 +106,19 @@ function isApplied(projectRoot, modulesDir, module) {
  */
 function addModule(options) {
     const result = applyModule(options.projectRoot, options.module, options.modulesDir, new Set());
-    // Record the module (and any auto-added requirements) and refresh the lock.
-    (0, lockfile_1.recordModules)(options.projectRoot, [...result.added, result.module], options.podokitVersion);
+    // Record the module (and any auto-added requirements), fold in the modules'
+    // declared ownedGlobs, and refresh the lock.
+    (0, lockfile_1.recordModules)(options.projectRoot, [...result.added, result.module], options.podokitVersion, result.ownedGlobs);
     return result;
 }
 function applyModule(projectRoot, module, modulesDir, applied) {
-    const moduleDir = (0, node_path_1.join)(modulesDir, module);
-    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"))) {
-        const available = listModules(modulesDir).map((m) => m.name);
+    const moduleDir = resolveModuleDir(module, modulesDir, projectRoot);
+    if (!moduleDir) {
+        const available = listModules(modulesDir, projectRoot).map((m) => m.name);
         throw new Error(`Unknown module "${module}".${available.length ? ` Available: ${available.join(", ")}.` : ""}`);
     }
     const manifest = readManifest(moduleDir);
+    assertManifestVersion(module, manifest);
     const appPkgPath = (0, node_path_1.join)(projectRoot, "apps", manifest.targetApp, "package.json");
     if (!(0, node_fs_1.existsSync)(appPkgPath)) {
         throw new Error(`This does not look like a PodoKit project: ${(0, node_path_1.join)("apps", manifest.targetApp, "package.json")} not found. Run inside a generated project.`);
@@ -76,11 +126,13 @@ function applyModule(projectRoot, module, modulesDir, applied) {
     applied.add(module);
     // 0) apply required modules first (auto-add if missing)
     const added = [];
+    const ownedGlobs = [...(manifest.ownedGlobs ?? [])];
     for (const required of manifest.requires ?? []) {
         if (applied.has(required) || isApplied(projectRoot, modulesDir, required))
             continue;
         const result = applyModule(projectRoot, required, modulesDir, applied);
         added.push(required, ...result.added);
+        ownedGlobs.push(...result.ownedGlobs);
     }
     const appName = projectName(projectRoot);
     const vars = { projectName: appName };
@@ -119,5 +171,5 @@ function applyModule(projectRoot, module, modulesDir, applied) {
         (0, node_fs_1.writeFileSync)(target, (0, podokit_template_engine_1.insertAtMarker)(content, injection.marker, injection.text));
     }
     const instructions = (manifest.instructions ?? []).map((line) => line.replace(/<app>/g, appName));
-    return { module, instructions, added };
+    return { module, instructions, added, ownedGlobs };
 }

package/dist/eject.js

@@ -21,7 +21,15 @@ function eject(projectRoot, paths) {
             result.ejected.push(path);
         }
     }
-    if (result.ejected.length)
+    if (result.ejected.length) {
         (0, lockfile_1.writeFilesLock)(projectRoot, lock);
+        // Persist ejected paths into the manifest's ownedGlobs so they stay owned
+        // across the next add/update, which rebuilds every tier from ownedGlobs.
+        const manifest = (0, lockfile_1.readManifest)(projectRoot);
+        if (manifest) {
+            manifest.ownedGlobs = (0, lockfile_1.mergeOwnedGlobs)(manifest.ownedGlobs, result.ejected);
+            (0, lockfile_1.writeManifest)(projectRoot, manifest);
+        }
+    }
     return result;
 }

package/dist/index.js

@@ -8,6 +8,7 @@ const create_1 = require("./create");
 const prompt_1 = require("./prompt");
 const templates_1 = require("./templates");
 const add_1 = require("./add");
+const remove_1 = require("./remove");
 const inspect_1 = require("./inspect");
 const update_1 = require("./update");
 const eject_1 = require("./eject");
@@ -16,6 +17,7 @@ const HELP = `podo — PodoKit project generator
 Usage:
   podo create <name> [options]
   podo add <module>
+  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 doctor              Check framework versions against supported ranges
@@ -89,7 +91,7 @@ async function main(argv) {
     if (args.command === "add") {
         const moduleName = args.name;
         if (!moduleName) {
-            const available = (0, add_1.listModules)(modulesDir);
+            const available = (0, add_1.listModules)(modulesDir, process.cwd());
             const list = available.length
                 ? available.map((m) => `  ${m.name}  ${m.description}`).join("\n")
                 : "  (none available)";
@@ -111,6 +113,29 @@ async function main(argv) {
         }
         return;
     }
+    if (args.command === "remove") {
+        const moduleName = args.name;
+        if (!moduleName) {
+            fail("Usage: podo remove <module>");
+        }
+        try {
+            const result = (0, remove_1.removeModule)({ projectRoot: process.cwd(), module: moduleName, modulesDir });
+            process.stdout.write(`\nRemoved ${result.module}: ${result.removed.length} file(s) deleted` +
+                `${result.unwired.length ? `, un-wired ${result.unwired.length} target(s)` : ""}.\n`);
+            if (result.keptShared.length) {
+                process.stdout.write(`\nKept (shared with another module): ${result.keptShared.join(", ")}\n`);
+            }
+            if (result.keptEdited.length) {
+                process.stdout.write(`\nKept (you edited these — delete manually if you want them gone):\n` +
+                    result.keptEdited.map((f) => `  ${f}`).join("\n") +
+                    "\n");
+            }
+        }
+        catch (err) {
+            fail(err.message);
+        }
+        return;
+    }
     if (args.command === "status") {
         try {
             const s = (0, inspect_1.status)(process.cwd());

package/dist/lockfile.d.ts

@@ -72,9 +72,14 @@ export interface InitLockOptions {
 }
 /** Write the initial `.podokit/` lockfile for a freshly created project. */
 export declare function initLockfile(projectRoot: string, options: InitLockOptions): void;
+/** Union two glob lists, preserving order and dropping duplicates. Used to fold
+ *  module-declared and ejected owned paths into the project's `ownedGlobs`, which
+ *  is the durable source of truth `computeFilesLock` re-reads on every recompute. */
+export declare function mergeOwnedGlobs(existing: string[], add: string[]): string[];
 /**
  * Record applied modules in the manifest and recompute the files.lock. Modules
  * already present are left in place (idempotent); the lock always reflects disk.
- * No-op on projects without a manifest (pre-lockfile projects; see `podo adopt`).
+ * `ownedGlobs` a module declares are merged into the manifest so its owned paths
+ * survive every future recompute. No-op on projects without a manifest.
  */
-export declare function recordModules(projectRoot: string, moduleNames: string[], version?: string): void;
+export declare function recordModules(projectRoot: string, moduleNames: string[], version?: string, ownedGlobs?: string[]): void;

package/dist/lockfile.js

@@ -14,6 +14,7 @@ exports.computeFilesLock = computeFilesLock;
 exports.readFilesLock = readFilesLock;
 exports.computeDrift = computeDrift;
 exports.initLockfile = initLockfile;
+exports.mergeOwnedGlobs = mergeOwnedGlobs;
 exports.recordModules = recordModules;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -44,6 +45,8 @@ const WALK_IGNORE = new Set([
 exports.DEFAULT_OWNED_GLOBS = [
     "apps/web/src/routes/**",
     "apps/web/src/lib/components/ui/**",
+    // Owned Nest DI extension slot — override providers here; update never touches it.
+    "apps/api/src/app.extensions.ts",
     // AI agent guidance — yours to customize; update never touches it.
     "AGENTS.md",
     "CLAUDE.md",
@@ -186,12 +189,27 @@ function initLockfile(projectRoot, options) {
     writeManifest(projectRoot, manifest);
     writeFilesLock(projectRoot, computeFilesLock(projectRoot, ownedGlobs));
 }
+/** Union two glob lists, preserving order and dropping duplicates. Used to fold
+ *  module-declared and ejected owned paths into the project's `ownedGlobs`, which
+ *  is the durable source of truth `computeFilesLock` re-reads on every recompute. */
+function mergeOwnedGlobs(existing, add) {
+    const seen = new Set(existing);
+    const out = [...existing];
+    for (const glob of add) {
+        if (seen.has(glob))
+            continue;
+        seen.add(glob);
+        out.push(glob);
+    }
+    return out;
+}
 /**
  * Record applied modules in the manifest and recompute the files.lock. Modules
  * already present are left in place (idempotent); the lock always reflects disk.
- * No-op on projects without a manifest (pre-lockfile projects; see `podo adopt`).
+ * `ownedGlobs` a module declares are merged into the manifest so its owned paths
+ * survive every future recompute. No-op on projects without a manifest.
  */
-function recordModules(projectRoot, moduleNames, version) {
+function recordModules(projectRoot, moduleNames, version, ownedGlobs) {
     const manifest = readManifest(projectRoot);
     if (!manifest)
         return;
@@ -203,6 +221,8 @@ function recordModules(projectRoot, moduleNames, version) {
         manifest.modules.push({ name, order: manifest.modules.length, addedWith: stampedWith });
         known.add(name);
     }
+    if (ownedGlobs?.length)
+        manifest.ownedGlobs = mergeOwnedGlobs(manifest.ownedGlobs, ownedGlobs);
     writeManifest(projectRoot, manifest);
     writeFilesLock(projectRoot, computeFilesLock(projectRoot, manifest.ownedGlobs));
 }

package/dist/remove.d.ts

@@ -0,0 +1,28 @@
+export interface RemoveOptions {
+    projectRoot: string;
+    module: string;
+    modulesDir: string;
+    /** PodoKit version stamped into the lockfile. Defaults to the CLI version. */
+    podokitVersion?: string;
+}
+export interface RemoveResult {
+    module: string;
+    /** Module overlay files deleted from the project. */
+    removed: string[];
+    /** Module files kept because the user edited them (delete manually if desired). */
+    keptEdited: string[];
+    /** Module files kept because another installed module also ships them. */
+    keptShared: string[];
+    /** Injection targets whose wiring was removed. */
+    unwired: string[];
+}
+/**
+ * Remove a previously-added module from a generated project: the inverse of
+ * `podo add`. Un-wires the module's marker injections, deletes its overlay files
+ * (keeping any the user edited or another installed module also ships), prunes
+ * the package.json deps/scripts and .env.example lines it introduced that no
+ * other installed module still needs, then drops it from the manifest and
+ * recomputes the lock. Does not cascade: a module still required by another
+ * installed module is refused rather than force-removed.
+ */
+export declare function removeModule(options: RemoveOptions): RemoveResult;

package/dist/remove.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeModule = removeModule;
+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 add_1 = require("./add");
+const lockfile_1 = require("./lockfile");
+function readModuleManifest(moduleDir) {
+    return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8"));
+}
+function readJson(path) {
+    return JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+}
+function projectName(projectRoot) {
+    const pkg = readJson((0, node_path_1.join)(projectRoot, "package.json"));
+    return typeof pkg.name === "string" ? pkg.name : "app";
+}
+/** Output paths a module writes into a project (dot- convention applied). */
+function moduleFilePaths(moduleDir, vars) {
+    const filesDir = (0, node_path_1.join)(moduleDir, "files");
+    if (!(0, node_fs_1.existsSync)(filesDir))
+        return [];
+    return [...(0, podokit_template_engine_1.renderTemplate)(filesDir, vars).keys()];
+}
+/**
+ * Remove a previously-added module from a generated project: the inverse of
+ * `podo add`. Un-wires the module's marker injections, deletes its overlay files
+ * (keeping any the user edited or another installed module also ships), prunes
+ * the package.json deps/scripts and .env.example lines it introduced that no
+ * other installed module still needs, then drops it from the manifest and
+ * recomputes the lock. Does not cascade: a module still required by another
+ * installed module is refused rather than force-removed.
+ */
+function removeModule(options) {
+    const { projectRoot, module, modulesDir } = options;
+    const manifest = (0, lockfile_1.readManifest)(projectRoot);
+    if (!manifest) {
+        throw new Error("Not a PodoKit project: .podokit/manifest.json not found.");
+    }
+    if (!manifest.modules.some((m) => m.name === module)) {
+        const installed = manifest.modules.map((m) => m.name).join(", ") || "(none)";
+        throw new Error(`Module "${module}" is not installed. Installed: ${installed}.`);
+    }
+    const moduleDir = (0, add_1.resolveModuleDir)(module, modulesDir, projectRoot);
+    if (!moduleDir) {
+        throw new Error(`Cannot resolve module "${module}" to un-apply it. Is it still installed/bundled?`);
+    }
+    const targetManifest = readModuleManifest(moduleDir);
+    // Resolve the manifests of the OTHER installed modules once — used for the
+    // requires guard and to decide which files/deps/env are shared.
+    const others = manifest.modules
+        .filter((m) => m.name !== module)
+        .map((m) => {
+        const dir = (0, add_1.resolveModuleDir)(m.name, modulesDir, projectRoot);
+        return dir ? { name: m.name, dir, manifest: readModuleManifest(dir) } : null;
+    })
+        .filter((m) => m !== null);
+    // Guard: refuse if another installed module requires this one.
+    const dependents = others.filter((o) => (o.manifest.requires ?? []).includes(module)).map((o) => o.name);
+    if (dependents.length) {
+        throw new Error(`Cannot remove "${module}": required by ${dependents.join(", ")}. Remove ${dependents.length > 1 ? "those" : "that"} first.`);
+    }
+    const vars = { projectName: projectName(projectRoot) };
+    const sharedFiles = new Set(others.flatMap((o) => moduleFilePaths(o.dir, vars)));
+    const lock = (0, lockfile_1.readFilesLock)(projectRoot);
+    // 1) un-wire marker injections (idempotent; skips optional/absent).
+    const unwired = [];
+    for (const injection of targetManifest.inject ?? []) {
+        const target = (0, node_path_1.join)(projectRoot, injection.file);
+        if (!(0, node_fs_1.existsSync)(target))
+            continue;
+        const content = (0, node_fs_1.readFileSync)(target, "utf8");
+        const next = (0, podokit_template_engine_1.removeAtMarker)(content, injection.text);
+        if (next !== content) {
+            (0, node_fs_1.writeFileSync)(target, next);
+            unwired.push(injection.file);
+        }
+    }
+    // 2) delete overlay files, preserving edited and shared ones.
+    const removed = [];
+    const keptEdited = [];
+    const keptShared = [];
+    for (const rel of moduleFilePaths(moduleDir, vars)) {
+        const abs = (0, node_path_1.join)(projectRoot, rel);
+        if (!(0, node_fs_1.existsSync)(abs))
+            continue;
+        if (sharedFiles.has(rel)) {
+            keptShared.push(rel);
+            continue;
+        }
+        const locked = lock?.files[rel];
+        if (locked && (0, podokit_template_engine_1.hashContent)((0, node_fs_1.readFileSync)(abs)) !== locked.outHash) {
+            keptEdited.push(rel);
+            continue;
+        }
+        (0, node_fs_1.rmSync)(abs);
+        pruneEmptyDirs(projectRoot, (0, node_path_1.dirname)(rel));
+        removed.push(rel);
+    }
+    // 3) prune package.json deps/scripts this module added that no other needs.
+    pruneAppPackage(projectRoot, targetManifest, others);
+    // 4) prune .env.example lines this module added that no other needs.
+    pruneEnvExample(projectRoot, targetManifest, others);
+    // 5) drop from the manifest (re-number order) and recompute the lock.
+    manifest.modules = manifest.modules
+        .filter((m) => m.name !== module)
+        .map((m, i) => ({ ...m, order: i }));
+    (0, lockfile_1.writeManifest)(projectRoot, manifest);
+    (0, lockfile_1.writeFilesLock)(projectRoot, (0, lockfile_1.computeFilesLock)(projectRoot, manifest.ownedGlobs));
+    return { module, removed, keptEdited, keptShared, unwired };
+}
+/** Remove now-empty directories left behind by a deleted file, up to the root. */
+function pruneEmptyDirs(projectRoot, relDir) {
+    let dir = relDir;
+    while (dir && dir !== "." && dir !== "/") {
+        const abs = (0, node_path_1.join)(projectRoot, dir);
+        try {
+            (0, node_fs_1.rmdirSync)(abs); // removes only an empty directory; throws otherwise
+        }
+        catch {
+            return; // not empty (or gone) — stop climbing
+        }
+        dir = (0, node_path_1.dirname)(dir);
+    }
+}
+function pruneAppPackage(projectRoot, target, others) {
+    if (!(target.dependencies || target.devDependencies || target.scripts))
+        return;
+    const appPkgPath = (0, node_path_1.join)(projectRoot, "apps", target.targetApp, "package.json");
+    if (!(0, node_fs_1.existsSync)(appPkgPath))
+        return;
+    const keep = (section) => new Set(others.flatMap((o) => Object.keys(o.manifest[section] ?? {})));
+    const pkg = readJson(appPkgPath);
+    let changed = false;
+    for (const section of ["dependencies", "devDependencies", "scripts"]) {
+        const declared = target[section];
+        const current = pkg[section];
+        if (!declared || !current)
+            continue;
+        const shared = keep(section);
+        for (const name of Object.keys(declared)) {
+            if (shared.has(name))
+                continue;
+            if (name in current) {
+                delete current[name];
+                changed = true;
+            }
+        }
+        if (current && Object.keys(current).length === 0)
+            delete pkg[section];
+    }
+    if (changed)
+        (0, node_fs_1.writeFileSync)(appPkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+function pruneEnvExample(projectRoot, target, others) {
+    if (!target.env?.length)
+        return;
+    const file = (0, node_path_1.join)(projectRoot, ".env.example");
+    if (!(0, node_fs_1.existsSync)(file))
+        return;
+    const shared = new Set(others.flatMap((o) => o.manifest.env ?? []));
+    const drop = new Set(target.env.filter((line) => !shared.has(line)));
+    if (!drop.size)
+        return;
+    const kept = (0, node_fs_1.readFileSync)(file, "utf8")
+        .split("\n")
+        .filter((line) => !drop.has(line));
+    (0, node_fs_1.writeFileSync)(file, kept.join("\n"));
+}

package/dist/templates/fullstack-nest-svelte/AGENTS.md

@@ -59,13 +59,14 @@ 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, and this `AGENTS.md`) — edit freely.
+- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. To add or override Nest providers/modules, use `app.extensions.ts` (spread into `AppModule` after the module-wired providers, so a same-token override wins) rather than editing `app.module.ts`.
 - **assembled** (e.g. `apps/api/src/app.module.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.
 
 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 status` / `podo diff` — see your local edits vs. what PodoKit generated.
 - `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
 

package/dist/templates/fullstack-nest-svelte/apps/api/src/app.extensions.ts

@@ -0,0 +1,21 @@
+import type { DynamicModule, Provider, Type } from "@nestjs/common";
+
+// Owned extension slot for the Nest app. This file is yours — PodoKit never
+// writes to it, so `podo update` leaves it alone. Use it to add your own modules
+// or providers, or to override a PodoKit-provided provider without editing
+// managed code. Because these are spread in *after* the module-wired providers,
+// an override here takes precedence.
+//
+// Example — swap the mailer transport for your own implementation:
+//   import { Mailer } from "./mailer/mailer";
+//   import { MyMailer } from "./my-mailer";
+//   export const extensionProviders: Provider[] = [
+//     { provide: Mailer, useClass: MyMailer },
+//   ];
+
+/** Extra modules to import into AppModule (or DynamicModule overrides). */
+export const extensionImports: (Type | DynamicModule)[] = [];
+
+/** Extra or overriding providers for AppModule. Same-token providers listed here
+ *  win over the ones PodoKit modules registered. */
+export const extensionProviders: Provider[] = [];

package/dist/templates/fullstack-nest-svelte/apps/api/src/app.module.ts

@@ -4,6 +4,7 @@ import { TypeOrmModule } from "@nestjs/typeorm";
 import { validateEnv } from "./config/env.validation";
 import { dataSourceOptions } from "./database/data-source";
 import { HealthModule } from "./health/health.module";
+import { extensionImports, extensionProviders } from "./app.extensions";
 // podokit:begin:imports
 // podokit:end:imports
 
@@ -14,10 +15,12 @@ import { HealthModule } from "./health/health.module";
     HealthModule,
     // podokit:begin:module-imports
     // podokit:end:module-imports
+    ...extensionImports,
   ],
   providers: [
     // podokit:begin:providers
     // podokit:end:providers
+    ...extensionProviders,
   ],
 })
 export class AppModule {}

package/dist/templates/fullstack-nest-svelte/apps/web/vite.config.ts

@@ -3,8 +3,14 @@ import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
 
 // Inside the dev container (compose.dev.yaml sets VITE_DOCKER=1): bind to all
-// interfaces, allow the Traefik hostname, and route HMR through Traefik on :80.
+// interfaces, allow the Traefik hostname, and route HMR's WebSocket back through
+// Traefik. The browser reaches the app at Traefik's published host port, so the
+// HMR client must target that same port — otherwise the ws connects to :80,
+// fails, and Vite silently falls back to a full page reload on every change
+// (which wipes in-progress form input). compose.dev.yaml injects
+// VITE_HMR_CLIENT_PORT to match the published Traefik port (default 80).
 const inDocker = process.env.VITE_DOCKER === "1";
+const hmrClientPort = Number(process.env.VITE_HMR_CLIENT_PORT) || 80;
 
 export default defineConfig({
   plugins: [tailwindcss(), sveltekit()],
@@ -13,7 +19,7 @@ export default defineConfig({
         host: true,
         port: 5001,
         allowedHosts: true,
-        hmr: { clientPort: 80 },
+        hmr: { clientPort: hmrClientPort },
       }
     : undefined,
 });

package/dist/templates/fullstack-nest-svelte/compose.dev.yaml

@@ -4,7 +4,10 @@
 #   docker compose -f compose.dev.yaml --profile cache \
 #     --profile storage --profile queue watch                     # with modules
 #
-# Only Traefik binds a host port (80). The app is at http://app.localhost.
+# Only Traefik binds a host port (default 80). The app is at http://app.localhost.
+# Set TRAEFIK_PORT to publish on another port (e.g. TRAEFIK_PORT=8001) so several
+# containerized stacks can run at once without colliding — the web container reads
+# the same value as VITE_HMR_CLIENT_PORT so Vite HMR follows automatically.
 # api/postgres/redis/minio have NO published ports — they talk by service name
 # on the internal network, so this stack never collides with other projects.
 #
@@ -29,8 +32,8 @@ services:
       - --api.dashboard=true
       - --api.insecure=true
     ports:
-      - "80:80"
-      - "127.0.0.1:8080:8080" # Traefik dashboard (dev only)
+      - "${TRAEFIK_PORT:-80}:80"
+      - "127.0.0.1:${TRAEFIK_DASHBOARD_PORT:-8080}:8080" # Traefik dashboard (dev only)
     volumes:
       - ./infra/traefik/dynamic.yml:/etc/traefik/dynamic.yml:ro
     networks: [podokit]
@@ -45,6 +48,10 @@ services:
     environment:
       - VITE_DOCKER=1
       - BACKEND_INTERNAL_URL=http://api:5002
+      # Match Traefik's published port so HMR's WebSocket targets the right port
+      # (default 80). Without this, HMR connects to :80 and a non-80 stack falls
+      # back to a full page reload on every edit.
+      - VITE_HMR_CLIENT_PORT=${TRAEFIK_PORT:-80}
     depends_on: [api]
     networks: [podokit]
     develop:

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/registry.svelte.ts

@@ -0,0 +1,37 @@
+import type { Component } from "svelte";
+import type { Messages } from "$lib/i18n/messages";
+// Modules import their nav-entry icons here.
+// podokit:begin:admin-nav-imports
+// podokit:end:admin-nav-imports
+
+// Module-driven admin menu registry. Modules append their sidebar nav entries and
+// settings tabs at the markers below via `podo add` injection, so the admin menu
+// grows and shrinks with the installed module set — no edits to app-sidebar or
+// the settings page. Empty until a module registers.
+
+/** A sidebar nav entry contributed by a module: a link, a label resolved from the
+ *  current locale (from the module's own i18n block), and an icon. */
+export type AdminNavEntry = {
+  href: string;
+  label: (t: Messages) => string;
+  icon: Component;
+  adminOnly?: boolean;
+};
+
+/** A settings tab contributed by a module: a tab value, a label resolved from the
+ *  current locale, and the panel component. */
+export type AdminSettingsSection = {
+  value: string;
+  label: (t: Messages) => string;
+  component: Component;
+};
+
+export const moduleNavEntries: AdminNavEntry[] = [
+  // podokit:begin:admin-nav-entries
+  // podokit:end:admin-nav-entries
+];
+
+export const moduleSettingsSections: AdminSettingsSection[] = [
+  // podokit:begin:admin-settings
+  // podokit:end:admin-settings
+];

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/app-sidebar.svelte

@@ -10,25 +10,26 @@
   import SettingsIcon from "@lucide/svelte/icons/settings";
   import HouseIcon from "@lucide/svelte/icons/house";
   import { getI18n } from "$lib/i18n";
+  import { moduleNavEntries, type AdminNavEntry } from "$lib/admin/registry.svelte";
   import type { SessionUser } from "../../app.d.ts";
-  import type { Messages } from "$lib/i18n/messages";
-  import type { Component } from "svelte";
 
   let { user, capabilities }: { user: SessionUser; capabilities?: { auditLog?: boolean; organization?: boolean } } = $props();
   const i18n = getI18n();
 
-  type NavItem = { href: string; key: keyof Messages["nav"]; icon: Component; adminOnly?: boolean };
+  type NavItem = AdminNavEntry;
   const items = $derived<NavItem[]>([
-    { href: "/admin", key: "overview", icon: LayoutDashboardIcon },
-    { href: "/admin/users", key: "users", icon: UsersIcon, adminOnly: true },
-    { href: "/admin/sessions", key: "sessions", icon: MonitorSmartphoneIcon, adminOnly: true },
+    { href: "/admin", label: (t) => t.nav.overview, icon: LayoutDashboardIcon },
+    { href: "/admin/users", label: (t) => t.nav.users, icon: UsersIcon, adminOnly: true },
+    { href: "/admin/sessions", label: (t) => t.nav.sessions, icon: MonitorSmartphoneIcon, adminOnly: true },
     ...(capabilities?.organization
-      ? [{ href: "/admin/organizations", key: "organizations", icon: Building2Icon, adminOnly: true } as NavItem]
+      ? [{ href: "/admin/organizations", label: (t) => t.nav.organizations, icon: Building2Icon, adminOnly: true } as NavItem]
       : []),
     ...(capabilities?.auditLog
-      ? [{ href: "/admin/audit", key: "audit", icon: ScrollTextIcon, adminOnly: true } as NavItem]
+      ? [{ href: "/admin/audit", label: (t) => t.nav.audit, icon: ScrollTextIcon, adminOnly: true } as NavItem]
       : []),
-    { href: "/admin/settings", key: "settings", icon: SettingsIcon, adminOnly: true },
+    // Module-contributed entries (present only for installed modules).
+    ...moduleNavEntries,
+    { href: "/admin/settings", label: (t) => t.nav.settings, icon: SettingsIcon, adminOnly: true },
   ]);
   const visible = $derived(items.filter((item) => !item.adminOnly || user.role === "admin"));
 </script>
@@ -47,11 +48,11 @@
       <Sidebar.Menu>
         {#each visible as item (item.href)}
           <Sidebar.MenuItem>
-            <Sidebar.MenuButton isActive={page.url.pathname === item.href} tooltipContent={i18n.t.nav[item.key]}>
+            <Sidebar.MenuButton isActive={page.url.pathname === item.href} tooltipContent={item.label(i18n.t)}>
               {#snippet child({ props })}
                 <a href={item.href} {...props}>
                   <item.icon />
-                  <span>{i18n.t.nav[item.key]}</span>
+                  <span>{item.label(i18n.t)}</span>
                 </a>
               {/snippet}
             </Sidebar.MenuButton>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/i18n/messages.ts

@@ -307,6 +307,9 @@ const en = {
     verified: "Verified",
     unverified: "Unverified",
   },
+  // Modules add their i18n blocks here.
+  // podokit:begin:messages-en
+  // podokit:end:messages-en
 };
 
 export type Messages = typeof en;
@@ -610,6 +613,9 @@ const ko: Messages = {
     verified: "인증됨",
     unverified: "미인증",
   },
+  // Modules add their i18n blocks here.
+  // podokit:begin:messages-ko
+  // podokit:end:messages-ko
 };
 
 export const messages: Record<Locale, Messages> = { en, ko };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/settings/+page.svelte

@@ -9,6 +9,7 @@
   import * as Dialog from "$lib/components/ui/dialog";
   import * as Tabs from "$lib/components/ui/tabs";
   import GeneralSettings from "./general-settings.svelte";
+  import { moduleSettingsSections } from "$lib/admin/registry.svelte";
   import { toast } from "svelte-sonner";
   import { api } from "$lib/api";
   import { getI18n } from "$lib/i18n";
@@ -226,6 +227,9 @@
     <Tabs.List>
       <Tabs.Trigger value="general">{i18n.t.general.tab}</Tabs.Trigger>
       <Tabs.Trigger value="auth">{i18n.t.settings.tab}</Tabs.Trigger>
+      {#each moduleSettingsSections as s (s.value)}
+        <Tabs.Trigger value={s.value}>{s.label(i18n.t)}</Tabs.Trigger>
+      {/each}
     </Tabs.List>
 
     <Tabs.Content value="general" class="mt-6">
@@ -247,6 +251,12 @@
         </section>
       {/each}
     </Tabs.Content>
+
+    {#each moduleSettingsSections as s (s.value)}
+      <Tabs.Content value={s.value} class="mt-6">
+        <s.component />
+      </Tabs.Content>
+    {/each}
   </Tabs.Root>
 </div>
 

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/+layout.server.ts

@@ -4,7 +4,17 @@ import { redirect } from "@sveltejs/kit";
 // "/" is a public landing page. Auth pages send signed-in users to /admin, and
 // the admin area requires a session. /maintenance is public so it renders while
 // the rest of the site is held back.
-const PUBLIC_PATHS = ["/", "/login", "/signup", "/forgot-password", "/reset-password", "/maintenance"];
+const PUBLIC_PATHS = [
+  "/",
+  "/login",
+  "/signup",
+  "/forgot-password",
+  "/reset-password",
+  "/maintenance",
+  // Modules add their public (no-session) page prefixes here.
+  // podokit:begin:public-paths
+  // podokit:end:public-paths
+];
 const AUTH_PATHS = ["/login", "/signup", "/forgot-password", "/reset-password"];
 
 function isPublic(pathname: string): boolean {

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -59,7 +59,7 @@
     "Set ADMIN_EMAILS in .env (comma-separated). Those emails become admins on sign-up.",
     "Re-run the auth migration to add the admin columns:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
     "Start the app (npm run dev), open /signup, register an ADMIN_EMAILS address, then sign in.",
-    "Admin pages: /dashboard/users (list, ban, set role, revoke sessions). Everyone: /dashboard/sessions, /dashboard/account.",
-    "Password reset: the reset link is logged to the API console in dev; wire a real mailer via emailAndPassword.sendResetPassword for production."
+    "Admin pages: /admin/users (list, ban, set role, revoke sessions). Everyone: /admin/sessions, /admin/account.",
+    "Password reset emails go through the mailer module (installed automatically with auth); in dev without SMTP they are logged to the API console. Configure SMTP in admin settings or via SMTP_* env for production."
   ]
 }

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

@@ -1,7 +1,7 @@
 {
   "name": "auth",
   "description": "Full authentication (better-auth): email/password, sessions, and \u2014 via config \u2014 OAuth and 2FA. Installs a global guard so the API is secure by default; health and /api/auth stay public.",
-  "requires": [],
+  "requires": ["mailer"],
   "targetApp": "api",
   "dependencies": {
     "@podosoft/podokit-auth": "^0.1.0",
@@ -9,14 +9,12 @@
     "better-auth": "^1.6.23",
     "@thallesp/nestjs-better-auth": "^2.7.0",
     "pg": "^8.12.0",
-    "nodemailer": "^7.0.9",
     "@better-auth/api-key": "^1.6.23",
     "@better-auth/passkey": "^1.6.23",
     "@better-auth/oauth-provider": "^1.6.23"
   },
   "devDependencies": {
-    "@types/pg": "^8.11.10",
-    "@types/nodemailer": "^7.0.4"
+    "@types/pg": "^8.11.10"
   },
   "env": [
     "# \u2500\u2500 Auth (better-auth) \u2014 the only required secrets \u2500\u2500",
@@ -32,10 +30,7 @@
     "# override (e.g. for secrets-manager injection in production); the DB takes",
     "# precedence when set.",
     "# --- Optional overrides / local development ---",
-    "# Email (Mailpit in local dev: docker compose --profile dev up \u2192 http://localhost:8025)",
-    "# SMTP_HOST=localhost",
-    "# SMTP_PORT=1025",
-    "# MAIL_FROM=PodoKit <no-reply@example.com>",
+    "# Email/SMTP is provided by the mailer module (see its .env block).",
     "# Phone-number SMS webhook (dev: SMS sink on port 8095)",
     "# SMS_WEBHOOK_URL=http://localhost:8095/sms",
     "# AUTH_HIBP=false",

package/dist/templates/modules/mailer/files/apps/api/src/mail/db.ts

@@ -0,0 +1,13 @@
+import { Pool } from "pg";
+
+// The mailer's own pg pool, in its own module so the mailer stays independent of
+// any other module. Used only to read the optional admin-configured SMTP settings
+// from `auth_config` when the auth module is present; with no such table the read
+// fails softly and the mailer falls back to SMTP_* env (see mailer.ts).
+export const pool = new Pool({
+  host: process.env.POSTGRES_HOST ?? "localhost",
+  port: Number(process.env.POSTGRES_PORT ?? 5432),
+  user: process.env.POSTGRES_USER ?? "podokit",
+  password: process.env.POSTGRES_PASSWORD ?? "podokit",
+  database: process.env.POSTGRES_DB ?? "podokit",
+});

package/dist/templates/modules/{auth → mailer}/files/apps/api/src/mail/mailer.ts

@@ -1,14 +1,40 @@
 import nodemailer, { type Transporter } from "nodemailer";
-import { pool } from "../auth/db";
+import { pool } from "./db";
 import { createConfigStore, type SmtpConfig } from "@podosoft/podokit-auth";
 
-// SMTP is admin-configurable in the DB (auth_config), falling back to SMTP_* env,
-// and applied live: the transport is rebuilt when the config changes (short TTL),
-// so no restart is needed. With neither DB nor env config, fall back to a transport
-// that just logs the message so nothing crashes for lack of mail config.
+// Reusable email sending. SMTP is resolved in priority order, applied live (short
+// TTL) so no restart is needed:
+//   1. admin-configured DB settings (auth_config) — only when the auth module is
+//      installed; read via the config store, which decrypts the SMTP password;
+//   2. SMTP_* env (fallback / production secrets-manager injection);
+//   3. none → a JSON transport that logs the message so dev links are grabbable.
+// The whole transport can also be overridden from app code (setMailTransport),
+// e.g. from apps/api/src/app.extensions.ts, to plug in a provider SDK.
 const store = createConfigStore(pool);
 const TTL_MS = 3_000;
 
+function envSmtp(): SmtpConfig | null {
+  if (!process.env.SMTP_HOST) return null;
+  return {
+    host: process.env.SMTP_HOST,
+    port: Number(process.env.SMTP_PORT ?? 1025),
+    secure: process.env.SMTP_SECURE === "true",
+    user: process.env.SMTP_USER,
+    pass: process.env.SMTP_PASS,
+    from: process.env.MAIL_FROM,
+  };
+}
+
+async function resolveSmtp(): Promise<SmtpConfig | null> {
+  try {
+    // Reads auth_config and falls back to env internally when auth is installed.
+    return await store.smtpConfig();
+  } catch {
+    // No auth_config table (auth not installed) — use env directly.
+    return envSmtp();
+  }
+}
+
 function buildTransport(smtp: SmtpConfig | null): Transporter {
   if (!smtp) return nodemailer.createTransport({ jsonTransport: true });
   return nodemailer.createTransport({
@@ -24,12 +50,20 @@ let transportFrom = process.env.MAIL_FROM ?? "PodoKit <no-reply@example.com>";
 let hasSmtp = false;
 let checkedAt = 0;
 let signature = "";
+let override: Transporter | null = null;
+
+/** Override the transport from app code (e.g. a provider SDK). Pass null to
+ *  restore the config-driven transport. Set this from app.extensions.ts. */
+export function setMailTransport(custom: Transporter | null): void {
+  override = custom;
+}
 
 async function getTransport(): Promise<Transporter> {
+  if (override) return override;
   if (checkedAt !== 0 && Date.now() - checkedAt < TTL_MS) return transport;
   checkedAt = Date.now();
   try {
-    const smtp = await store.smtpConfig();
+    const smtp = await resolveSmtp();
     const next = JSON.stringify(smtp ?? null);
     if (next !== signature) {
       transport = buildTransport(smtp);
@@ -48,7 +82,7 @@ export type Mail = { to: string; subject: string; text: string; html?: string };
 export async function sendMail(mail: Mail): Promise<void> {
   const t = await getTransport();
   const info = await t.sendMail({ from: transportFrom, ...mail });
-  if (!hasSmtp) {
+  if (!override && !hasSmtp) {
     // JSON transport: surface the message so the link is grabbable from logs.
     console.log(`[mailer] no SMTP configured; message not delivered:\n${info.message as string}`);
   }

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

@@ -0,0 +1,38 @@
+{
+  "name": "mailer",
+  "description": "Reusable email sending (nodemailer). Resolves SMTP from the admin-configured DB settings when auth is installed, else SMTP_* env, else logs to the console. Used by auth and contact-form; the transport is overridable from app.extensions.ts.",
+  "requires": [],
+  "targetApp": "api",
+  "dependencies": {
+    "nodemailer": "^7.0.9",
+    "@podosoft/podokit-auth": "^0.1.0",
+    "pg": "^8.12.0"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^7.0.4",
+    "@types/pg": "^8.11.10"
+  },
+  "env": [
+    "# ── Mailer (SMTP) — optional ──",
+    "# With auth installed, configure SMTP on the admin Settings page (stored",
+    "# encrypted in the DB, applied live). These env vars are a fallback/override;",
+    "# with no SMTP configured at all the mailer logs messages to the console.",
+    "# Local dev uses Mailpit: docker compose --profile dev up → http://localhost:8025",
+    "# SMTP_HOST=localhost",
+    "# SMTP_PORT=1025",
+    "# MAIL_FROM=PodoKit <no-reply@example.com>"
+  ],
+  "inject": [
+    {
+      "file": "AGENTS.md",
+      "marker": "<!-- podokit:end:agents-modules -->",
+      "optional": true,
+      "text": "### mailer\n- Send email with `import { sendMail, actionEmail } from \"../mail/mailer\"` (path relative to your file). `sendMail({ to, subject, text, html? })`.\n- SMTP comes from the admin Settings page (when auth is installed) or `SMTP_*` env; with neither, messages are logged to the console (dev links are grabbable from logs).\n- To use a provider SDK instead of SMTP, call `setMailTransport(...)` from `apps/api/src/app.extensions.ts`.\n"
+    }
+  ],
+  "instructions": [
+    "Send mail from anywhere in the API:  import { sendMail } from \"../mail/mailer\"  then  await sendMail({ to, subject, text }).",
+    "SMTP is optional: with auth installed, configure it on the admin Settings page (DB, applied live); otherwise set SMTP_HOST/SMTP_PORT/MAIL_FROM in .env. With none set, messages are logged to the console.",
+    "To send through a provider SDK, override the transport in apps/api/src/app.extensions.ts:  import { setMailTransport } from \"./mail/mailer\";  setMailTransport(myTransport)."
+  ]
+}

package/dist/templates/todo/AGENTS.md

@@ -60,13 +60,14 @@ 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, and this `AGENTS.md`) — edit freely.
+- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. To add or override Nest providers/modules, use `app.extensions.ts` (spread into `AppModule` after the module-wired providers, so a same-token override wins) rather than editing `app.module.ts`.
 - **assembled** (e.g. `apps/api/src/app.module.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.
 
 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 status` / `podo diff` — see your local edits vs. what PodoKit generated.
 - `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
 

package/dist/templates/todo/apps/api/src/app.extensions.ts

@@ -0,0 +1,21 @@
+import type { DynamicModule, Provider, Type } from "@nestjs/common";
+
+// Owned extension slot for the Nest app. This file is yours — PodoKit never
+// writes to it, so `podo update` leaves it alone. Use it to add your own modules
+// or providers, or to override a PodoKit-provided provider without editing
+// managed code. Because these are spread in *after* the module-wired providers,
+// an override here takes precedence.
+//
+// Example — override a provider with your own implementation:
+//   import { SomeService } from "./some/some.service";
+//   import { MyService } from "./my-service";
+//   export const extensionProviders: Provider[] = [
+//     { provide: SomeService, useClass: MyService },
+//   ];
+
+/** Extra modules to import into AppModule (or DynamicModule overrides). */
+export const extensionImports: (Type | DynamicModule)[] = [];
+
+/** Extra or overriding providers for AppModule. Same-token providers listed here
+ *  win over the ones PodoKit modules registered. */
+export const extensionProviders: Provider[] = [];

package/dist/templates/todo/apps/api/src/app.module.ts

@@ -5,6 +5,7 @@ import { validateEnv } from "./config/env.validation";
 import { dataSourceOptions } from "./database/data-source";
 import { HealthModule } from "./health/health.module";
 import { TodosModule } from "./todos/todos.module";
+import { extensionImports, extensionProviders } from "./app.extensions";
 // podokit:begin:imports
 // podokit:end:imports
 
@@ -16,10 +17,12 @@ import { TodosModule } from "./todos/todos.module";
     TodosModule,
     // podokit:begin:module-imports
     // podokit:end:module-imports
+    ...extensionImports,
   ],
   providers: [
     // podokit:begin:providers
     // podokit:end:providers
+    ...extensionProviders,
   ],
 })
 export class AppModule {}

package/dist/templates/todo/apps/web/vite.config.ts

@@ -3,8 +3,14 @@ import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
 
 // Inside the dev container (compose.dev.yaml sets VITE_DOCKER=1): bind to all
-// interfaces, allow the Traefik hostname, and route HMR through Traefik on :80.
+// interfaces, allow the Traefik hostname, and route HMR's WebSocket back through
+// Traefik. The browser reaches the app at Traefik's published host port, so the
+// HMR client must target that same port — otherwise the ws connects to :80,
+// fails, and Vite silently falls back to a full page reload on every change
+// (which wipes in-progress form input). compose.dev.yaml injects
+// VITE_HMR_CLIENT_PORT to match the published Traefik port (default 80).
 const inDocker = process.env.VITE_DOCKER === "1";
+const hmrClientPort = Number(process.env.VITE_HMR_CLIENT_PORT) || 80;
 
 export default defineConfig({
   plugins: [tailwindcss(), sveltekit()],
@@ -13,7 +19,7 @@ export default defineConfig({
         host: true,
         port: 5001,
         allowedHosts: true,
-        hmr: { clientPort: 80 },
+        hmr: { clientPort: hmrClientPort },
       }
     : undefined,
 });

package/dist/templates/todo/compose.dev.yaml

@@ -4,7 +4,10 @@
 #   docker compose -f compose.dev.yaml --profile cache \
 #     --profile storage --profile queue watch                     # with modules
 #
-# Only Traefik binds a host port (80). The app is at http://app.localhost.
+# Only Traefik binds a host port (default 80). The app is at http://app.localhost.
+# Set TRAEFIK_PORT to publish on another port (e.g. TRAEFIK_PORT=8001) so several
+# containerized stacks can run at once without colliding — the web container reads
+# the same value as VITE_HMR_CLIENT_PORT so Vite HMR follows automatically.
 # api/postgres/redis/minio have NO published ports — they talk by service name
 # on the internal network, so this stack never collides with other projects.
 #
@@ -29,8 +32,8 @@ services:
       - --api.dashboard=true
       - --api.insecure=true
     ports:
-      - "80:80"
-      - "127.0.0.1:8080:8080" # Traefik dashboard (dev only)
+      - "${TRAEFIK_PORT:-80}:80"
+      - "127.0.0.1:${TRAEFIK_DASHBOARD_PORT:-8080}:8080" # Traefik dashboard (dev only)
     volumes:
       - ./infra/traefik/dynamic.yml:/etc/traefik/dynamic.yml:ro
     networks: [podokit]
@@ -45,6 +48,10 @@ services:
     environment:
       - VITE_DOCKER=1
       - BACKEND_INTERNAL_URL=http://api:5002
+      # Match Traefik's published port so HMR's WebSocket targets the right port
+      # (default 80). Without this, HMR connects to :80 and a non-80 stack falls
+      # back to a full page reload on every edit.
+      - VITE_HMR_CLIENT_PORT=${TRAEFIK_PORT:-80}
     depends_on: [api]
     networks: [podokit]
     develop:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "An opinionated but extensible starter toolkit and CLI for full-stack TypeScript apps with NestJS, SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {