@podosoft/podokit 0.4.0 → 0.5.0

package/dist/templates/todo/apps/api/src/main.ts

@@ -22,7 +22,7 @@ async function bootstrap(): Promise<void> {
     .build();
   SwaggerModule.setup("api-docs", app, SwaggerModule.createDocument(app, config));
 
-  const port = Number(process.env.PORT ?? 3000);
+  const port = Number(process.env.PORT ?? 5002);
   await app.listen(port);
 }
 

package/dist/templates/todo/apps/web/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "vite dev --port 5173",
+    "dev": "vite dev --port 5001",
     "build": "vite build",
     "preview": "vite preview",
     "lint": "svelte-check --tsconfig ./tsconfig.json",
@@ -13,7 +13,7 @@
   "dependencies": {
     "@internationalized/date": "^3.12.2",
     "@lucide/svelte": "^1.23.0",
-    "@podosoft/podokit-api-client": "^0.4.0",
+    "@podosoft/podokit-api-client": "^0.5.0",
     "bits-ui": "^2.18.1",
     "clsx": "^2.1.1",
     "mode-watcher": "^1.1.0",

package/dist/templates/todo/apps/web/src/lib/components/ui/switch/index.ts

@@ -0,0 +1,7 @@
+import Root from "./switch.svelte";
+
+export {
+	Root,
+	//
+	Root as Switch,
+};

package/dist/templates/todo/apps/web/src/lib/components/ui/switch/switch.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+	import { Switch as SwitchPrimitive } from "bits-ui";
+	import { cn, type WithoutChildrenOrChild } from "$lib/utils.js";
+
+	let {
+		ref = $bindable(null),
+		checked = $bindable(false),
+		class: className,
+		...restProps
+	}: WithoutChildrenOrChild<SwitchPrimitive.RootProps> = $props();
+</script>
+
+<SwitchPrimitive.Root
+	bind:ref
+	data-slot="switch"
+	class={cn(
+		"peer focus-visible:border-ring focus-visible:ring-ring/50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input inline-flex h-[1.15rem] w-8 shrink-0 items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50",
+		className
+	)}
+	bind:checked
+	{...restProps}
+>
+	<SwitchPrimitive.Thumb
+		data-slot="switch-thumb"
+		class={cn(
+			"bg-background pointer-events-none block size-4 rounded-full ring-0 transition-transform data-[state=checked]:translate-x-[calc(100%-2px)] data-[state=unchecked]:translate-x-0"
+		)}
+	/>
+</SwitchPrimitive.Root>

package/dist/templates/todo/apps/web/src/lib/server/backend-proxy.ts

@@ -5,7 +5,7 @@ const FORWARDED_HEADERS = ["authorization", "cookie", "content-type", "accept",
 const RELAYED_RESPONSE_HEADERS = ["content-type", "location", "cache-control"];
 
 export function backendBaseUrl(): string {
-  return process.env.BACKEND_INTERNAL_URL ?? "http://localhost:3000";
+  return process.env.BACKEND_INTERNAL_URL ?? "http://localhost:5002";
 }
 
 // Normalize the resolved client IP for the forwarded header. better-auth stores

package/dist/templates/todo/dot-env.example

@@ -1,6 +1,8 @@
 # Copy to .env and adjust. Never commit real secrets.
+
+# ── Required (runtime) ───────────────────────────────────────────────
 NODE_ENV=development
-PORT=3000
+PORT=5002
 
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
@@ -8,9 +10,12 @@ POSTGRES_USER=podokit
 POSTGRES_PASSWORD=podokit
 POSTGRES_DB=podokit
 
+# Web -> API boundary (server-side only; not exposed to the browser)
+BACKEND_INTERNAL_URL=http://localhost:5002
+CORS_ORIGIN=http://localhost:5001
+
+# ── Optional / development ───────────────────────────────────────────
+# Redis — only needed by cache/queue modules. Start it with:
+# docker compose --profile cache up
 REDIS_HOST=localhost
 REDIS_PORT=6379
-
-# Web -> API boundary (server-side only; not exposed to the browser)
-BACKEND_INTERNAL_URL=http://localhost:3000
-CORS_ORIGIN=http://localhost:5173

package/dist/templates/todo/infra/docker/docker-compose.yml

@@ -1,4 +1,5 @@
 services:
+  # --- Runtime (always started by `docker compose up`) ---
   postgres:
     image: postgres:16-alpine
     environment:
@@ -15,8 +16,11 @@ services:
       timeout: 5s
       retries: 5
 
+  # --- Runtime, but only needed by cache/queue modules. Start with:
+  #     docker compose --profile cache up
   redis:
     image: redis:7-alpine
+    profiles: ["cache"]
     ports:
       - "${REDIS_PORT:-6379}:6379"
     healthcheck:

package/dist/templates/todo/tests/README.md

@@ -10,6 +10,6 @@ npm run test:e2e:report  # open the HTML report
 ```
 
 The suite runs against a live stack (web on `E2E_BASE_URL`, default
-`http://localhost:5173`, proxying `/api/*` to the API). Start PostgreSQL, run the
+`http://localhost:5001`, proxying `/api/*` to the API). Start PostgreSQL, run the
 auth migration, and start the API + web first. Files ending in `*.api.spec.ts` run
 in the request-only `api` project; `*.ui.spec.ts` run in the chromium `ui` project.

package/dist/templates/todo/tests/package.json

@@ -9,6 +9,7 @@
     "test:e2e:report": "playwright show-report"
   },
   "devDependencies": {
-    "@playwright/test": "^1.61.1"
+    "@playwright/test": "^1.61.1",
+    "otpauth": "^9.5.1"
   }
 }

package/dist/templates/todo/tests/playwright.config.ts

@@ -4,7 +4,7 @@ import { defineConfig, devices } from "@playwright/test";
 // the API). Start it first (see docs/testing.md) — locally via the dev harness,
 // in CI via scripts/e2e-ci.mjs. Two projects: `api` (request-only, backend e2e)
 // and `ui` (chromium, pages). Files are routed by suffix (*.api/*.ui.spec.ts).
-const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5173";
+const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 
 export default defineConfig({
   testDir: ".",

package/dist/update.d.ts

@@ -0,0 +1,49 @@
+import { type Tier } from "./lockfile";
+/**
+ * `podo update` planner. For now it produces a dry-run plan only: it assembles
+ * the new-version tree from the installed CLI's templates and compares it to the
+ * working copy, classifying each file. Applying the plan (writing files, 3-way
+ * merging) is a later step (see ADR-0009).
+ */
+export type Action = "update" | "merge" | "conflict" | "add" | "remove" | "skip" | "up-to-date";
+export interface FileChange {
+    path: string;
+    tier: Tier;
+    action: Action;
+    /** Why the action was chosen (for the report). */
+    note: string;
+}
+export interface UpdatePlan {
+    fromVersion: string;
+    toVersion: string;
+    template: string;
+    modules: string[];
+    changes: FileChange[];
+}
+/**
+ * Build the update plan. `templatesDir` is the installed CLI's template set (the
+ * new version); the lock records what PodoKit last wrote (to detect user edits).
+ */
+export declare function planUpdate(projectRoot: string, templatesDir: string): UpdatePlan;
+export interface ApplyOptions {
+    /** Templates for the version the project is currently on, for 3-way merges. */
+    oldTemplatesDir?: string;
+}
+export interface ApplyResult {
+    written: string[];
+    removed: string[];
+    /** Files 3-way merged cleanly. */
+    merged: string[];
+    /** Files written with conflict markers for manual resolution. */
+    conflicts: string[];
+}
+/**
+ * Apply an update to the working copy. Clean updates and additions are written,
+ * upstream removals deleted, and user-edited files 3-way merged against the old
+ * version (when `oldTemplatesDir` is given) or written with git-style conflict
+ * markers otherwise. Owned files are never touched. Refreshes the lockfile and
+ * stamps the new version.
+ */
+export declare function applyUpdate(projectRoot: string, templatesDir: string, options?: ApplyOptions): ApplyResult;
+/** Count actions for a one-line summary. */
+export declare function summarize(plan: UpdatePlan): Record<Action, number>;

package/dist/update.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planUpdate = planUpdate;
+exports.applyUpdate = applyUpdate;
+exports.summarize = summarize;
+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 assemble_1 = require("./assemble");
+const lockfile_1 = require("./lockfile");
+const inspect_1 = require("./inspect");
+function treeText(tree, path) {
+    const file = tree.get(path);
+    if (!file)
+        return null;
+    return typeof file.content === "string" ? file.content : file.content.toString("utf8");
+}
+function diskContent(projectRoot, path) {
+    const abs = (0, node_path_1.join)(projectRoot, path);
+    return (0, node_fs_1.existsSync)(abs) ? (0, node_fs_1.readFileSync)(abs) : null;
+}
+/**
+ * Build the update plan. `templatesDir` is the installed CLI's template set (the
+ * new version); the lock records what PodoKit last wrote (to detect user edits).
+ */
+function planUpdate(projectRoot, templatesDir) {
+    const manifest = (0, lockfile_1.readManifest)(projectRoot);
+    const lock = (0, lockfile_1.readFilesLock)(projectRoot);
+    if (!manifest || !lock)
+        throw new inspect_1.NotAProjectError();
+    const newTree = (0, assemble_1.assembleProject)({
+        templatesDir,
+        template: manifest.template,
+        answers: manifest.answers,
+        modules: manifest.modules.map((m) => m.name),
+    });
+    const changes = [];
+    const paths = new Set([...newTree.keys(), ...Object.keys(lock.files)]);
+    for (const path of [...paths].sort()) {
+        const locked = lock.files[path];
+        const newText = treeText(newTree, path);
+        const disk = diskContent(projectRoot, path);
+        // tier: prefer the lock; else classify the new file.
+        const tier = locked?.tier ??
+            (newText !== null ? (0, lockfile_1.classifyTier)(path, newText, manifest.ownedGlobs) : "managed");
+        if (tier === "owned") {
+            changes.push({ path, tier, action: "skip", note: "owned — never modified" });
+            continue;
+        }
+        // File removed upstream.
+        if (newText === null) {
+            if (disk === null)
+                continue; // already gone
+            const edited = locked && (0, podokit_template_engine_1.hashContent)(disk) !== locked.outHash;
+            changes.push({
+                path,
+                tier,
+                action: edited ? "conflict" : "remove",
+                note: edited ? "removed upstream but edited locally" : "removed upstream",
+            });
+            continue;
+        }
+        const newHash = (0, podokit_template_engine_1.hashContent)(newText);
+        // New file added upstream.
+        if (disk === null) {
+            changes.push({ path, tier, action: "add", note: "new in this version" });
+            continue;
+        }
+        const diskHash = (0, podokit_template_engine_1.hashContent)(disk);
+        if (diskHash === newHash) {
+            changes.push({ path, tier, action: "up-to-date", note: "already current" });
+            continue;
+        }
+        const edited = !locked || diskHash !== locked.outHash;
+        changes.push({
+            path,
+            tier,
+            action: edited ? "conflict" : "update",
+            note: edited ? "you edited this; update would need a merge" : "clean update",
+        });
+    }
+    return {
+        fromVersion: manifest.podokitVersion,
+        toVersion: (0, lockfile_1.podokitVersion)(),
+        template: manifest.template,
+        modules: manifest.modules.map((m) => m.name),
+        changes,
+    };
+}
+function writeFile(projectRoot, path, content) {
+    const abs = (0, node_path_1.join)(projectRoot, path);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(abs), { recursive: true });
+    (0, node_fs_1.writeFileSync)(abs, content);
+}
+/**
+ * Apply an update to the working copy. Clean updates and additions are written,
+ * upstream removals deleted, and user-edited files 3-way merged against the old
+ * version (when `oldTemplatesDir` is given) or written with git-style conflict
+ * markers otherwise. Owned files are never touched. Refreshes the lockfile and
+ * stamps the new version.
+ */
+function applyUpdate(projectRoot, templatesDir, options = {}) {
+    const manifest = (0, lockfile_1.readManifest)(projectRoot);
+    if (!manifest)
+        throw new inspect_1.NotAProjectError();
+    const plan = planUpdate(projectRoot, templatesDir);
+    const modules = manifest.modules.map((m) => m.name);
+    const newTree = (0, assemble_1.assembleProject)({ templatesDir, template: manifest.template, answers: manifest.answers, modules });
+    const oldTree = options.oldTemplatesDir
+        ? (0, assemble_1.assembleProject)({ templatesDir: options.oldTemplatesDir, template: manifest.template, answers: manifest.answers, modules })
+        : null;
+    const result = { written: [], removed: [], merged: [], conflicts: [] };
+    for (const change of plan.changes) {
+        const newText = treeText(newTree, change.path);
+        if (change.action === "update" || change.action === "add") {
+            writeFile(projectRoot, change.path, newText ?? "");
+            result.written.push(change.path);
+        }
+        else if (change.action === "remove") {
+            (0, node_fs_1.rmSync)((0, node_path_1.join)(projectRoot, change.path), { force: true });
+            result.removed.push(change.path);
+        }
+        else if (change.action === "conflict" && newText !== null) {
+            const disk = (0, node_fs_1.readFileSync)((0, node_path_1.join)(projectRoot, change.path), "utf8");
+            const base = oldTree ? treeText(oldTree, change.path) : null;
+            if (base === null) {
+                // No old version to merge against — never clobber the user's edits.
+                result.conflicts.push(change.path);
+                continue;
+            }
+            const merge = (0, podokit_template_engine_1.threeWayMerge)(base, disk, newText, { current: "current", next: "podokit" });
+            writeFile(projectRoot, change.path, merge.merged);
+            if (merge.conflicts > 0)
+                result.conflicts.push(change.path);
+            else
+                result.merged.push(change.path);
+        }
+    }
+    // Refresh the lock to match what we just wrote and stamp the new version.
+    (0, lockfile_1.writeFilesLock)(projectRoot, (0, lockfile_1.computeFilesLock)(projectRoot, manifest.ownedGlobs));
+    (0, lockfile_1.writeManifest)(projectRoot, { ...manifest, podokitVersion: (0, lockfile_1.podokitVersion)() });
+    return result;
+}
+/** Count actions for a one-line summary. */
+function summarize(plan) {
+    const counts = {
+        update: 0,
+        merge: 0,
+        conflict: 0,
+        add: 0,
+        remove: 0,
+        skip: 0,
+        "up-to-date": 0,
+    };
+    for (const change of plan.changes)
+        counts[change.action] += 1;
+    return counts;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.4.0",
+  "version": "0.5.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": {
@@ -36,6 +36,6 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@podosoft/podokit-template-engine": "^0.3.0"
+    "@podosoft/podokit-template-engine": "^0.4.0"
   }
 }