@podosoft/podokit 0.7.0 → 0.8.0

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
@@ -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/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

@@ -66,6 +66,7 @@ in `.podokit/files.lock` — respect it:
 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/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/todo/AGENTS.md

@@ -67,6 +67,7 @@ in `.podokit/files.lock` — respect it:
 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/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.7.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": {