@podosoft/podokit 0.8.0 → 0.10.0

package/dist/add.d.ts

@@ -26,6 +26,9 @@ export interface ModuleManifest {
      *  they survive lock recompute. Use for public presentation pages a consumer
      *  restyles, while keeping the module's `$lib` logic managed. */
     ownedGlobs?: string[];
+    /** Paths that an existing app may explicitly hand back to this module with
+     *  `podo add --adopt`. Broad app-owned route globs are never removed. */
+    managedGlobs?: string[];
 }
 export interface AddOptions {
     projectRoot: string;
@@ -33,6 +36,8 @@ export interface AddOptions {
     modulesDir: string;
     /** PodoKit version stamped into the lockfile. Defaults to the CLI version. */
     podokitVersion?: string;
+    /** Adopt colliding files covered by the module's managedGlobs. */
+    adopt?: boolean;
 }
 export interface AddResult {
     module: string;
@@ -41,6 +46,18 @@ export interface AddResult {
     added: string[];
     /** ownedGlobs declared by this module and every module it pulled in. */
     ownedGlobs: string[];
+    /** Existing owned presentation files intentionally left untouched. */
+    preserved: string[];
+    /** Paths explicitly adopted as module-managed files. */
+    adopted: string[];
+    /** Files shipped, merged, or injected while applying the module. */
+    touched: string[];
+}
+export interface ResolvedModule {
+    dir: string;
+    name: string;
+    packageName?: string;
+    moduleVersion?: string;
 }
 /**
  * Resolve a module's directory by name: first the bundled `modulesDir`, then a
@@ -48,6 +65,9 @@ export interface AddResult {
  * 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;
+/** Resolve a module and capture the package identity needed to replay external
+ * modules during `podo update`. */
+export declare function resolveModule(name: string, modulesDir: string, projectRoot: string): ResolvedModule | 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. */

package/dist/add.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SUPPORTED_MANIFEST_VERSION = void 0;
 exports.resolveModuleDir = resolveModuleDir;
+exports.resolveModule = resolveModule;
 exports.listModules = listModules;
 exports.addModule = addModule;
 const node_fs_1 = require("node:fs");
@@ -31,6 +32,27 @@ function resolveModuleDir(name, modulesDir, projectRoot) {
         return null;
     }
 }
+/** Resolve a module and capture the package identity needed to replay external
+ * modules during `podo update`. */
+function resolveModule(name, modulesDir, projectRoot) {
+    const dir = resolveModuleDir(name, modulesDir, projectRoot);
+    if (!dir)
+        return null;
+    const manifest = readManifest(dir);
+    const bundled = (0, node_path_1.join)(modulesDir, manifest.name);
+    if (dir === bundled)
+        return { dir, name: manifest.name };
+    const packageFile = (0, node_path_1.join)(dir, "package.json");
+    if (!(0, node_fs_1.existsSync)(packageFile))
+        return { dir, name: manifest.name };
+    const pkg = readJson(packageFile);
+    return {
+        dir,
+        name: manifest.name,
+        packageName: typeof pkg.name === "string" ? pkg.name : undefined,
+        moduleVersion: typeof pkg.version === "string" ? pkg.version : undefined,
+    };
+}
 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.`);
@@ -105,18 +127,42 @@ function isApplied(projectRoot, modulesDir, module) {
  * and inject wiring at markers. Missing required modules are added first.
  */
 function addModule(options) {
-    const result = applyModule(options.projectRoot, options.module, options.modulesDir, new Set());
+    const previousLock = (0, lockfile_1.readFilesLock)(options.projectRoot);
+    const cleanPaths = previousLock
+        ? Object.entries(previousLock.files)
+            .filter(([path, entry]) => {
+            const target = (0, node_path_1.join)(options.projectRoot, path);
+            return (0, node_fs_1.existsSync)(target) && (0, podokit_template_engine_1.hashContent)((0, node_fs_1.readFileSync)(target)) === entry.outHash;
+        })
+            .map(([path]) => path)
+        : [];
+    const result = applyModule(options.projectRoot, options.module, options.modulesDir, new Set(), options.adopt ?? false);
+    if (options.adopt && result.adopted.length) {
+        releaseOwnedPaths(options.projectRoot, result.adopted);
+    }
     // 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);
+    const records = [...result.added, result.module]
+        .map((name) => resolveModule(name, options.modulesDir, options.projectRoot))
+        .filter((module) => module !== null)
+        .map(moduleRecord);
+    (0, lockfile_1.recordModules)(options.projectRoot, records, options.podokitVersion, result.ownedGlobs, previousLock
+        ? {
+            previous: previousLock,
+            cleanPaths,
+            modulePaths: [...new Set(result.touched)],
+            adoptedPaths: result.adopted,
+        }
+        : undefined);
     return result;
 }
-function applyModule(projectRoot, module, modulesDir, applied) {
-    const moduleDir = resolveModuleDir(module, modulesDir, projectRoot);
-    if (!moduleDir) {
+function applyModule(projectRoot, module, modulesDir, applied, adopt) {
+    const resolved = resolveModule(module, modulesDir, projectRoot);
+    if (!resolved) {
         const available = listModules(modulesDir, projectRoot).map((m) => m.name);
         throw new Error(`Unknown module "${module}".${available.length ? ` Available: ${available.join(", ")}.` : ""}`);
     }
+    const moduleDir = resolved.dir;
     const manifest = readManifest(moduleDir);
     assertManifestVersion(module, manifest);
     const appPkgPath = (0, node_path_1.join)(projectRoot, "apps", manifest.targetApp, "package.json");
@@ -127,19 +173,34 @@ function applyModule(projectRoot, module, modulesDir, applied) {
     // 0) apply required modules first (auto-add if missing)
     const added = [];
     const ownedGlobs = [...(manifest.ownedGlobs ?? [])];
+    const preserved = [];
+    const adopted = [];
+    const touched = [];
     for (const required of manifest.requires ?? []) {
         if (applied.has(required) || isApplied(projectRoot, modulesDir, required))
             continue;
-        const result = applyModule(projectRoot, required, modulesDir, applied);
+        const result = applyModule(projectRoot, required, modulesDir, applied, adopt);
         added.push(required, ...result.added);
         ownedGlobs.push(...result.ownedGlobs);
+        preserved.push(...result.preserved);
+        adopted.push(...result.adopted);
+        touched.push(...result.touched);
     }
     const appName = projectName(projectRoot);
     const vars = { projectName: appName };
     // 1) overlay files
     const filesDir = (0, node_path_1.join)(moduleDir, "files");
     if ((0, node_fs_1.existsSync)(filesDir)) {
-        (0, podokit_template_engine_1.copyTemplate)(filesDir, projectRoot, vars);
+        const copied = copyModuleFiles({
+            filesDir,
+            projectRoot,
+            vars,
+            managedGlobs: manifest.managedGlobs ?? [],
+            adopt,
+        });
+        preserved.push(...copied.preserved);
+        adopted.push(...copied.adopted);
+        touched.push(...copied.touched);
     }
     // 2) merge dependencies and scripts into the target app
     if (manifest.dependencies || manifest.devDependencies || manifest.scripts) {
@@ -152,10 +213,12 @@ function applyModule(projectRoot, module, modulesDir, applied) {
             overlay.scripts = manifest.scripts;
         const merged = (0, podokit_template_engine_1.mergePackageJson)(readJson(appPkgPath), overlay);
         (0, node_fs_1.writeFileSync)(appPkgPath, `${JSON.stringify(merged, null, 2)}\n`);
+        touched.push(`apps/${manifest.targetApp}/package.json`);
     }
     // 3) append env example lines
     if (manifest.env?.length) {
         appendEnv(projectRoot, manifest.env);
+        touched.push(".env.example");
     }
     // 4) inject wiring at markers
     for (const injection of manifest.inject ?? []) {
@@ -169,7 +232,57 @@ function applyModule(projectRoot, module, modulesDir, applied) {
         if (injection.optional && !content.includes(injection.marker))
             continue;
         (0, node_fs_1.writeFileSync)(target, (0, podokit_template_engine_1.insertAtMarker)(content, injection.marker, injection.text));
+        touched.push(injection.file);
     }
     const instructions = (manifest.instructions ?? []).map((line) => line.replace(/<app>/g, appName));
-    return { module, instructions, added, ownedGlobs };
+    return { module: manifest.name, instructions, added, ownedGlobs, preserved, adopted, touched };
+}
+function moduleRecord(module) {
+    return {
+        name: module.name,
+        packageName: module.packageName,
+        moduleVersion: module.moduleVersion,
+    };
+}
+/** Copy a module overlay without clobbering app-owned presentation files. */
+function copyModuleFiles(options) {
+    const tree = (0, podokit_template_engine_1.renderTemplate)(options.filesDir, options.vars);
+    const lock = (0, lockfile_1.readFilesLock)(options.projectRoot);
+    const preserved = [];
+    const adopted = [];
+    const touched = [];
+    for (const [rel, file] of tree) {
+        touched.push(rel);
+        const target = (0, node_path_1.join)(options.projectRoot, rel);
+        const existed = (0, node_fs_1.existsSync)(target);
+        const entry = lock?.files[rel];
+        const canAdopt = options.managedGlobs.some((glob) => (0, lockfile_1.matchGlob)(rel, glob));
+        if (existed && entry?.tier === "owned" && !(options.adopt && canAdopt)) {
+            preserved.push(rel);
+            continue;
+        }
+        if (existed && !entry && !(options.adopt && canAdopt)) {
+            const current = (0, node_fs_1.readFileSync)(target);
+            const next = Buffer.isBuffer(file.content) ? file.content : Buffer.from(file.content);
+            if (!current.equals(next)) {
+                throw new Error(`Cannot add module: ${rel} already exists outside PodoKit ownership. ` +
+                    "Move it, or re-run with --adopt when the module declares the path managed.");
+            }
+        }
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
+        (0, node_fs_1.writeFileSync)(target, file.content);
+        if (existed && options.adopt && canAdopt)
+            adopted.push(rel);
+    }
+    return { preserved, adopted, touched };
+}
+/** Remove only exact owned paths that an explicit adoption handed back. Broad
+ * ownership rules such as `apps/web/src/routes/**` remain intact. */
+function releaseOwnedPaths(projectRoot, adopted) {
+    const manifest = (0, lockfile_1.readManifest)(projectRoot);
+    if (!manifest)
+        return;
+    const adoptedSet = new Set(adopted);
+    manifest.ownedGlobs = manifest.ownedGlobs.filter((glob) => glob.includes("*") || !adoptedSet.has(glob));
+    (0, lockfile_1.writeManifest)(projectRoot, manifest);
 }

package/dist/assemble.d.ts

@@ -1,4 +1,5 @@
 import { type TemplateVars, type VfsTree } from "@podosoft/podokit-template-engine";
+import type { ManifestModule } from "./lockfile";
 /**
  * Reconstruct a generated project in memory (no disk writes) from a template
  * plus an ordered module list, mirroring `create` + `add`. `podo update` uses
@@ -8,7 +9,9 @@ export interface AssembleOptions {
     templatesDir: string;
     template: string;
     answers: TemplateVars;
-    modules: string[];
+    modules: (string | ManifestModule)[];
+    /** Generated project whose node_modules may contain external modules. */
+    projectRoot?: string;
 }
 /** Assemble the project tree for a template + ordered modules, in memory. */
 export declare function assembleProject(options: AssembleOptions): VfsTree;

package/dist/assemble.js

@@ -4,6 +4,7 @@ exports.assembleProject = assembleProject;
 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");
 function readManifest(moduleDir) {
     return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8"));
 }
@@ -53,11 +54,44 @@ function applyModuleToTree(tree, moduleDir, vars) {
         setText(tree, target, (0, podokit_template_engine_1.insertAtMarker)(content, injection.marker, injection.text));
     }
 }
+function preserveExternalPackageDependency(tree, projectRoot, packageName) {
+    const diskPackagePath = (0, node_path_1.join)(projectRoot, "package.json");
+    if (!(0, node_fs_1.existsSync)(diskPackagePath))
+        return;
+    const diskPackage = JSON.parse((0, node_fs_1.readFileSync)(diskPackagePath, "utf8"));
+    const rootPackage = JSON.parse(textOf(tree, "package.json") || "{}");
+    for (const section of ["dependencies", "devDependencies", "optionalDependencies"]) {
+        const diskSection = diskPackage[section];
+        if (!diskSection || typeof diskSection !== "object" || Array.isArray(diskSection))
+            continue;
+        const version = diskSection[packageName];
+        if (typeof version !== "string")
+            continue;
+        const current = rootPackage[section];
+        const dependencies = current && typeof current === "object" && !Array.isArray(current)
+            ? { ...current }
+            : {};
+        dependencies[packageName] = version;
+        rootPackage[section] = dependencies;
+        setText(tree, "package.json", `${JSON.stringify(rootPackage, null, 2)}\n`);
+        return;
+    }
+}
 /** Assemble the project tree for a template + ordered modules, in memory. */
 function assembleProject(options) {
     const tree = (0, podokit_template_engine_1.renderTemplate)((0, node_path_1.join)(options.templatesDir, options.template), options.answers);
     for (const mod of options.modules) {
-        applyModuleToTree(tree, (0, node_path_1.join)(options.templatesDir, "modules", mod), options.answers);
+        const name = typeof mod === "string" ? mod : (mod.packageName ?? mod.name);
+        const resolved = (0, add_1.resolveModule)(name, (0, node_path_1.join)(options.templatesDir, "modules"), options.projectRoot ?? options.templatesDir);
+        if (!resolved) {
+            const label = typeof mod === "string" ? mod : mod.name;
+            throw new Error(`Cannot resolve module "${label}" while assembling the project. ` +
+                "Install its package before running podo update.");
+        }
+        applyModuleToTree(tree, resolved.dir, options.answers);
+        if (typeof mod !== "string" && mod.packageName && options.projectRoot) {
+            preserveExternalPackageDependency(tree, options.projectRoot, mod.packageName);
+        }
     }
     return tree;
 }

package/dist/index.d.ts

@@ -8,6 +8,7 @@ interface ParsedArgs {
     pm?: PackageManager;
     from?: string;
     apply: boolean;
+    adopt: boolean;
     yes: boolean;
     help: boolean;
     ai: boolean;

package/dist/index.js

@@ -16,7 +16,7 @@ const HELP = `podo — PodoKit project generator
 
 Usage:
   podo create <name> [options]
-  podo add <module>
+  podo add <module> [--adopt]
   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
@@ -28,6 +28,7 @@ Options:
   --template <t> Template to scaffold (see below)
   --dir <path>   Target directory (default: ./<name>)
   --pm <name>    Package manager: npm | pnpm | yarn (default: npm)
+  --adopt        Adopt colliding paths explicitly declared managed by a module
   --no-ai        Skip AI agent guidance (AGENTS.md, CLAUDE.md, editor rules)
   -y, --yes      Skip prompts and accept defaults
   -h, --help     Show this help
@@ -41,7 +42,7 @@ Example:
   cd my-app && npx @podosoft/podokit add auth
 `;
 function parseArgs(argv) {
-    const parsed = { help: false, yes: false, apply: false, ai: true };
+    const parsed = { help: false, yes: false, apply: false, adopt: false, ai: true };
     const positionals = [];
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -57,6 +58,9 @@ function parseArgs(argv) {
         else if (arg === "--apply") {
             parsed.apply = true;
         }
+        else if (arg === "--adopt") {
+            parsed.adopt = true;
+        }
         else if (arg === "--template") {
             parsed.template = argv[++i];
         }
@@ -99,11 +103,22 @@ async function main(argv) {
             return;
         }
         try {
-            const result = (0, add_1.addModule)({ projectRoot: process.cwd(), module: moduleName, modulesDir });
+            const result = (0, add_1.addModule)({
+                projectRoot: process.cwd(),
+                module: moduleName,
+                modulesDir,
+                adopt: args.adopt,
+            });
             if (result.added.length) {
                 process.stdout.write(`\nAlso added required module(s): ${result.added.join(", ")}\n`);
             }
             process.stdout.write(`\nAdded ${result.module}.\n`);
+            if (result.preserved.length) {
+                process.stdout.write(`\nPreserved app-owned presentation file(s):\n${result.preserved.map((file) => `  ${file}`).join("\n")}\n`);
+            }
+            if (result.adopted.length) {
+                process.stdout.write(`\nAdopted as module-managed file(s):\n${result.adopted.map((file) => `  ${file}`).join("\n")}\n`);
+            }
             if (result.instructions.length) {
                 process.stdout.write(`\nNext steps:\n${result.instructions.map((i) => `  ${i}`).join("\n")}\n`);
             }
@@ -140,8 +155,9 @@ async function main(argv) {
         try {
             const s = (0, inspect_1.status)(process.cwd());
             const tiers = `managed ${s.tiers.managed}, assembled ${s.tiers.assembled}, owned ${s.tiers.owned}`;
+            const modules = s.moduleDetails.map((module) => module.version ? `${module.name}@${module.version}` : module.name);
             process.stdout.write(`PodoKit ${s.podokitVersion}  (template: ${s.template}, ${s.packageManager})\n` +
-                `Modules: ${s.modules.length ? s.modules.join(", ") : "(none)"}\n` +
+                `Modules: ${modules.length ? modules.join(", ") : "(none)"}\n` +
                 `Files:   ${tiers}\n` +
                 `Edited:  ${s.drifted.length} managed file(s)${s.missing.length ? `, ${s.missing.length} missing` : ""}\n` +
                 (s.drifted.length ? s.drifted.map((f) => `  ~ ${f}`).join("\n") + "\n" : ""));

package/dist/inspect.d.ts

@@ -8,6 +8,11 @@ export interface StatusReport {
     template: string;
     packageManager: string;
     modules: string[];
+    moduleDetails: {
+        name: string;
+        packageName?: string;
+        version?: string;
+    }[];
     tiers: Record<Tier, number>;
     drifted: string[];
     missing: string[];

package/dist/inspect.js

@@ -29,6 +29,11 @@ function status(projectRoot) {
         template: manifest.template,
         packageManager: manifest.packageManager,
         modules: manifest.modules.map((m) => m.name),
+        moduleDetails: manifest.modules.map((m) => ({
+            name: m.name,
+            packageName: m.packageName,
+            version: m.moduleVersion,
+        })),
         tiers,
         drifted,
         missing,

package/dist/lockfile.d.ts

@@ -12,6 +12,15 @@ export interface ManifestModule {
     order: number;
     /** PodoKit version that applied the module. */
     addedWith: string;
+    /** npm package backing an external module. Absent for bundled modules. */
+    packageName?: string;
+    /** Installed external-module version last applied to this project. */
+    moduleVersion?: string;
+}
+export interface ManifestModuleInput {
+    name: string;
+    packageName?: string;
+    moduleVersion?: string;
 }
 export interface PodokitManifest {
     schemaVersion: number;
@@ -33,6 +42,16 @@ export interface FilesLock {
     schemaVersion: number;
     files: Record<string, FileEntry>;
 }
+export interface RecordModulesLockSnapshot {
+    /** Lock state captured before module files are written. */
+    previous: FilesLock;
+    /** Previously locked paths whose working bytes still matched their baseline. */
+    cleanPaths: string[];
+    /** Files shipped, merged, or injected by the module application. */
+    modulePaths: string[];
+    /** Owned paths explicitly handed back with `podo add --adopt`. */
+    adoptedPaths: string[];
+}
 /** Default user-owned globs seeded into a new project. See ADR-0010. */
 export declare const DEFAULT_OWNED_GLOBS: string[];
 export declare function manifestPath(projectRoot: string): string;
@@ -82,4 +101,4 @@ export declare function mergeOwnedGlobs(existing: string[], add: string[]): stri
  * `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, ownedGlobs?: string[]): void;
+export declare function recordModules(projectRoot: string, moduleInputs: (string | ManifestModuleInput)[], version?: string, ownedGlobs?: string[], lockSnapshot?: RecordModulesLockSnapshot): void;

package/dist/lockfile.js

@@ -209,20 +209,62 @@ function mergeOwnedGlobs(existing, add) {
  * `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, ownedGlobs) {
+function recordModules(projectRoot, moduleInputs, version, ownedGlobs, lockSnapshot) {
     const manifest = readManifest(projectRoot);
     if (!manifest)
         return;
     const stampedWith = version ?? podokitVersion();
     const known = new Set(manifest.modules.map((m) => m.name));
-    for (const name of moduleNames) {
-        if (known.has(name))
+    for (const input of moduleInputs) {
+        const module = typeof input === "string" ? { name: input } : input;
+        const existing = manifest.modules.find((entry) => entry.name === module.name);
+        if (existing) {
+            existing.packageName = module.packageName ?? existing.packageName;
+            existing.moduleVersion = module.moduleVersion ?? existing.moduleVersion;
             continue;
-        manifest.modules.push({ name, order: manifest.modules.length, addedWith: stampedWith });
-        known.add(name);
+        }
+        manifest.modules.push({
+            name: module.name,
+            order: manifest.modules.length,
+            addedWith: stampedWith,
+            packageName: module.packageName,
+            moduleVersion: module.moduleVersion,
+        });
+        known.add(module.name);
     }
     if (ownedGlobs?.length)
         manifest.ownedGlobs = mergeOwnedGlobs(manifest.ownedGlobs, ownedGlobs);
     writeManifest(projectRoot, manifest);
-    writeFilesLock(projectRoot, computeFilesLock(projectRoot, manifest.ownedGlobs));
+    const computed = computeFilesLock(projectRoot, manifest.ownedGlobs);
+    if (!lockSnapshot) {
+        writeFilesLock(projectRoot, computed);
+        return;
+    }
+    const clean = new Set(lockSnapshot.cleanPaths);
+    const modulePaths = new Set(lockSnapshot.modulePaths);
+    const adopted = new Set(lockSnapshot.adoptedPaths);
+    const files = {};
+    for (const [path, previous] of Object.entries(lockSnapshot.previous.files)) {
+        const current = computed.files[path];
+        if (!current) {
+            // Preserve missing-file drift that existed before the add operation.
+            files[path] = previous;
+            continue;
+        }
+        if (current.tier === "owned" || adopted.has(path) || clean.has(path)) {
+            files[path] = current;
+        }
+        else {
+            // Adding a module must not teach the lock that pre-existing local edits
+            // are generated output. Keep the old baseline so update stays safe.
+            files[path] = previous;
+        }
+    }
+    for (const path of modulePaths) {
+        const current = computed.files[path];
+        if (!current || files[path])
+            continue;
+        files[path] = current;
+    }
+    writeFilesLock(projectRoot, { schemaVersion: exports.LOCK_SCHEMA_VERSION, files });
 }

package/dist/remove.js

@@ -42,7 +42,8 @@ function removeModule(options) {
         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);
+    const installedModule = manifest.modules.find((entry) => entry.name === module);
+    const moduleDir = (0, add_1.resolveModuleDir)(installedModule?.packageName ?? module, modulesDir, projectRoot);
     if (!moduleDir) {
         throw new Error(`Cannot resolve module "${module}" to un-apply it. Is it still installed/bundled?`);
     }
@@ -52,7 +53,7 @@ function removeModule(options) {
     const others = manifest.modules
         .filter((m) => m.name !== module)
         .map((m) => {
-        const dir = (0, add_1.resolveModuleDir)(m.name, modulesDir, projectRoot);
+        const dir = (0, add_1.resolveModuleDir)(m.packageName ?? m.name, modulesDir, projectRoot);
         return dir ? { name: m.name, dir, manifest: readModuleManifest(dir) } : null;
     })
         .filter((m) => m !== null);

package/dist/templates/fullstack-nest-svelte/apps/web/src/app.css

@@ -23,6 +23,14 @@
   --border: oklch(0.92 0.004 286.32);
   --input: oklch(0.92 0.004 286.32);
   --ring: oklch(0.705 0.015 286.067);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.141 0.005 285.823);
+  --sidebar-primary: oklch(0.21 0.006 285.885);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.967 0.001 286.375);
+  --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
+  --sidebar-border: oklch(0.92 0.004 286.32);
+  --sidebar-ring: oklch(0.705 0.015 286.067);
 }
 
 .dark {
@@ -44,6 +52,14 @@
   --border: oklch(1 0 0 / 10%);
   --input: oklch(1 0 0 / 15%);
   --ring: oklch(0.552 0.016 285.938);
+  --sidebar: oklch(0.21 0.006 285.885);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.92 0.004 286.32);
+  --sidebar-primary-foreground: oklch(0.21 0.006 285.885);
+  --sidebar-accent: oklch(0.274 0.006 286.033);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.552 0.016 285.938);
 }
 
 @theme inline {
@@ -69,6 +85,14 @@
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
 }
 
 @layer base {
@@ -79,3 +103,21 @@
     @apply bg-background text-foreground;
   }
 }
+
+/* shadcn-svelte sidebar active-state correction.
+ * Upstream (shadcn-svelte registry, `nova` style) styles the active item with
+ * the `data-active:` Tailwind variant, which matches attribute PRESENCE
+ * (`[data-active]`). The menu buttons always render `data-active="true|false"`,
+ * so the active look (accent background, accent text, medium weight) leaks onto
+ * EVERY item — nearly invisible in the default palette but glaring once a theme
+ * raises the contrast. We keep `ui/sidebar/*` as a pristine mirror of upstream
+ * (so `shadcn-svelte` updates apply cleanly) and correct the behaviour here:
+ * neutralize the resting state of non-active items, leaving hover/press feedback
+ * (their `:hover`/`:active` rules) untouched. Drop this once shadcn-svelte ships
+ * value-matching `data-[active=true]:` (canonical shadcn/ui already does). */
+[data-sidebar="menu-button"][data-active="false"]:not(:hover):not(:active),
+[data-sidebar="menu-sub-button"][data-active="false"]:not(:hover):not(:active) {
+  background-color: transparent;
+  color: var(--sidebar-foreground);
+  font-weight: 400;
+}

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/components/site-runtime.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+  // Modules can replace this managed component with global site behavior while
+  // the surrounding route layout remains application-owned.
+  import { ModeWatcher } from "mode-watcher";
+</script>
+
+<ModeWatcher />

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/server/backend-proxy.ts

@@ -37,7 +37,9 @@ export async function proxyRequest(
   const upstream = await fetch(targetUrl, {
     method: request.method,
     headers,
-    body: hasBody ? await request.text() : undefined,
+    // Preserve multipart uploads and other binary bodies byte-for-byte. Reading
+    // them as text corrupts bytes that are not valid UTF-8 before forwarding.
+    body: hasBody ? await request.arrayBuffer() : undefined,
     redirect: "manual",
   });
 

package/dist/templates/fullstack-nest-svelte/apps/web/src/routes/+layout.svelte

@@ -1,9 +1,9 @@
 <script lang="ts">
   import "../app.css";
-  import { ModeWatcher } from "mode-watcher";
+  import SiteRuntime from "$lib/components/site-runtime.svelte";
 
   let { children } = $props();
 </script>
 
-<ModeWatcher />
+<SiteRuntime />
 {@render children()}

package/dist/templates/fullstack-nest-svelte/dot-gitignore

@@ -12,3 +12,9 @@ build/
 tests/playwright/
 tests/playwright-report/
 tests/test-results/
+playwright/.auth/
+playwright-report/
+test-results/
+
+# local performance reports
+output/lighthouse/