@podosoft/podokit 0.3.0 → 0.5.0

package/dist/templates/todo/apps/api/tsconfig.json

@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
-    "module": "CommonJS",
+    "module": "nodenext",
     "target": "ES2022",
-    "moduleResolution": "Node",
+    "moduleResolution": "nodenext",
     "outDir": "dist",
     "rootDir": "src",
     "declaration": false,
@@ -14,8 +14,17 @@
     "noImplicitReturns": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
+    "forceConsistentCasingInFileNames": true,
+    "types": [
+      "node"
+    ]
   },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist", "test"]
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "test"
+  ]
 }

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

@@ -4,15 +4,16 @@
   "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",
-    "test": "echo \"add Playwright tests here\" && exit 0"
+    "test": "echo \"unit: add vitest; e2e: npm run test:e2e (see tests/)\" && exit 0"
   },
   "dependencies": {
     "@internationalized/date": "^3.12.2",
     "@lucide/svelte": "^1.23.0",
+    "@podosoft/podokit-api-client": "^0.5.0",
     "bits-ui": "^2.18.1",
     "clsx": "^2.1.1",
     "mode-watcher": "^1.1.0",
@@ -29,7 +30,7 @@
     "svelte-check": "^4.0.0",
     "tailwindcss": "^4.0.0",
     "typesafe-i18n": "^5.26.2",
-    "typescript": "^5.6.3",
+    "typescript": "^6.0.3",
     "vite": "^5.4.0",
     "tw-animate-css": "^1.4.0"
   }

package/dist/templates/todo/apps/web/src/lib/api.ts

@@ -0,0 +1,5 @@
+import { createApiClient } from "@podosoft/podokit-api-client";
+
+// Browser client: same-origin. REST calls go to /api/* and auth to /api/auth/*,
+// both proxied to the backend by the SvelteKit server (see routes/api/**).
+export const api = createApiClient();

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/api.ts

@@ -0,0 +1,19 @@
+import type { RequestEvent } from "@sveltejs/kit";
+import { createApiClient, type ApiClient } from "@podosoft/podokit-api-client";
+import { backendBaseUrl } from "./backend-proxy";
+
+// Server-side client for load functions and hooks: points at the internal
+// backend URL and forwards the incoming request's cookies.
+export function serverApiClient(event: RequestEvent): ApiClient {
+  const cookie = event.request.headers.get("cookie") ?? "";
+  const fetchWithCookies: typeof fetch = (input, init) => {
+    const headers = new Headers(init?.headers);
+    if (cookie) headers.set("cookie", cookie);
+    return event.fetch(input, { ...init, headers });
+  };
+  return createApiClient({
+    baseUrl: backendBaseUrl(),
+    apiBasePath: "",
+    fetch: fetchWithCookies,
+  });
+}

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

@@ -1,16 +1,55 @@
 // Server-side proxy boundary. The browser never talks to the API directly:
-// only these allowlisted headers are forwarded to BACKEND_INTERNAL_URL.
-const FORWARDED_HEADERS = ["authorization", "cookie", "content-type"];
+// requests go through SvelteKit server routes, which forward an allowlist of
+// headers to BACKEND_INTERNAL_URL and relay the response (including Set-Cookie).
+const FORWARDED_HEADERS = ["authorization", "cookie", "content-type", "accept", "origin", "referer"];
+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";
 }
 
-export function backendProxyHeaders(request: Request): Headers {
+// Normalize the resolved client IP for the forwarded header. better-auth stores
+// IPv4 as-is but anonymizes IPv6 (masks the host bits), so an IPv6 loopback would
+// be recorded as "::" — map loopback to 127.0.0.1 for a clean local value, and
+// unwrap IPv4-mapped addresses.
+function normalizeClientIp(address: string | undefined): string | undefined {
+  if (!address) return undefined;
+  if (address === "::1" || address === "::") return "127.0.0.1";
+  if (address.startsWith("::ffff:")) return address.slice("::ffff:".length);
+  return address;
+}
+
+export async function proxyRequest(
+  request: Request,
+  targetUrl: string,
+  clientAddress?: string,
+): Promise<Response> {
   const headers = new Headers();
   for (const name of FORWARDED_HEADERS) {
     const value = request.headers.get(name);
     if (value) headers.set(name, value);
   }
-  return headers;
+  // Forward the resolved client IP so the API (better-auth) can record it.
+  const forwardedIp = normalizeClientIp(clientAddress);
+  if (forwardedIp) headers.set("x-forwarded-for", forwardedIp);
+
+  const hasBody = request.method !== "GET" && request.method !== "HEAD";
+  const upstream = await fetch(targetUrl, {
+    method: request.method,
+    headers,
+    body: hasBody ? await request.text() : undefined,
+    redirect: "manual",
+  });
+
+  const responseHeaders = new Headers();
+  for (const name of RELAYED_RESPONSE_HEADERS) {
+    const value = upstream.headers.get(name);
+    if (value) responseHeaders.set(name, value);
+  }
+  // Relay Set-Cookie so auth session cookies reach the browser.
+  for (const cookie of upstream.headers.getSetCookie()) {
+    responseHeaders.append("set-cookie", cookie);
+  }
+
+  return new Response(upstream.body, { status: upstream.status, headers: responseHeaders });
 }

package/dist/templates/todo/apps/web/src/routes/+page.svelte

@@ -3,6 +3,8 @@
   import { Input } from "$lib/components/ui/input";
   import { Checkbox } from "$lib/components/ui/checkbox";
   import * as Card from "$lib/components/ui/card";
+  import { api } from "$lib/api";
+  import { ApiError } from "@podosoft/podokit-api-client";
 
   type Todo = { id: string; title: string; completed: boolean };
 
@@ -10,40 +12,39 @@
   let title = $state("");
   let error = $state<string | null>(null);
 
+  function fail(err: unknown, action: string): void {
+    error = err instanceof ApiError ? `${action}: ${err.message}` : `${action} failed`;
+  }
+
   async function load(): Promise<void> {
-    const res = await fetch("/api/todos");
-    if (res.ok) todos = await res.json();
-    else error = `Failed to load (HTTP ${res.status})`;
+    try {
+      todos = await api.get<Todo[]>("/todos");
+      error = null;
+    } catch (err) {
+      fail(err, "Load");
+    }
   }
 
   async function add(event: SubmitEvent): Promise<void> {
     event.preventDefault();
     const value = title.trim();
     if (!value) return;
-    const res = await fetch("/api/todos", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ title: value }),
-    });
-    if (res.ok) {
+    try {
+      await api.post("/todos", { title: value });
       title = "";
       await load();
-    } else {
-      error = `Failed to add (HTTP ${res.status})`;
+    } catch (err) {
+      fail(err, "Add");
     }
   }
 
   async function toggle(todo: Todo): Promise<void> {
-    await fetch(`/api/todos/${todo.id}`, {
-      method: "PATCH",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ completed: !todo.completed }),
-    });
+    await api.patch(`/todos/${todo.id}`, { completed: !todo.completed });
     await load();
   }
 
   async function remove(todo: Todo): Promise<void> {
-    await fetch(`/api/todos/${todo.id}`, { method: "DELETE" });
+    await api.del(`/todos/${todo.id}`);
     await load();
   }
 
@@ -61,7 +62,7 @@
   <Card.Root>
     <Card.Header>
       <Card.Title>Todos</Card.Title>
-      <Card.Description>A NestJS + SvelteKit CRUD example.</Card.Description>
+      <Card.Description>A NestJS + SvelteKit CRUD example via the typed ApiClient.</Card.Description>
     </Card.Header>
     <Card.Content class="flex flex-col gap-4">
       <form class="flex gap-2" onsubmit={add}>

package/dist/templates/todo/apps/web/src/routes/api/[...path]/+server.ts

@@ -0,0 +1,12 @@
+import type { RequestHandler } from "@sveltejs/kit";
+import { backendBaseUrl, proxyRequest } from "$lib/server/backend-proxy";
+
+// Proxy the app's REST API, stripping the /api prefix (backend routes are at root).
+const handler: RequestHandler = ({ request, params, url, getClientAddress }) =>
+  proxyRequest(request, `${backendBaseUrl()}/${params.path}${url.search}`, getClientAddress());
+
+export const GET = handler;
+export const POST = handler;
+export const PUT = handler;
+export const PATCH = handler;
+export const DELETE = handler;

package/dist/templates/todo/apps/web/src/routes/api/auth/[...all]/+server.ts

@@ -0,0 +1,12 @@
+import type { RequestHandler } from "@sveltejs/kit";
+import { backendBaseUrl, proxyRequest } from "$lib/server/backend-proxy";
+
+// Proxy the better-auth handler, keeping the /api/auth prefix.
+const handler: RequestHandler = ({ request, params, url, getClientAddress }) =>
+  proxyRequest(request, `${backendBaseUrl()}/api/auth/${params.all}${url.search}`, getClientAddress());
+
+export const GET = handler;
+export const POST = handler;
+export const PUT = handler;
+export const PATCH = handler;
+export const DELETE = handler;

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/dot-gitignore

@@ -7,3 +7,8 @@ build/
 !.env.example
 .DS_Store
 *.log
+
+# e2e test artifacts
+tests/playwright/
+tests/playwright-report/
+tests/test-results/

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/package.json

@@ -2,12 +2,20 @@
   "name": "{{projectName}}",
   "version": "0.0.0",
   "private": true,
-  "engines": { "node": ">=20" },
-  "workspaces": ["apps/*"],
+  "engines": {
+    "node": ">=20"
+  },
+  "workspaces": [
+    "apps/*",
+    "tests"
+  ],
   "scripts": {
     "dev": "npm run dev --workspaces --if-present",
     "build": "npm run build --workspaces --if-present",
     "lint": "npm run lint --workspaces --if-present",
-    "test": "npm run test --workspaces --if-present"
+    "test": "npm run test --workspaces --if-present",
+    "test:e2e": "npm run test:e2e -w tests",
+    "test:e2e:ui": "npm run test:e2e:ui -w tests",
+    "test:e2e:api": "npm run test:e2e:api -w tests"
   }
 }

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

@@ -0,0 +1,15 @@
+# tests
+
+End-to-end tests for this app, run with [`@playwright/test`](https://playwright.dev):
+
+```bash
+npm run test:e2e         # all specs (api + ui)
+npm run test:e2e:api     # backend endpoints (request-only)
+npm run test:e2e:ui      # pages (chromium)
+npm run test:e2e:report  # open the HTML report
+```
+
+The suite runs against a live stack (web on `E2E_BASE_URL`, default
+`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/api/health.api.spec.ts

@@ -0,0 +1,14 @@
+import { expect, test } from "@playwright/test";
+
+// Health endpoints are public and present in every generated app.
+test("GET /health is public and ok @smoke", async ({ request }) => {
+  const res = await request.get("/api/health");
+  expect(res.ok()).toBeTruthy();
+  expect((await res.json()).status).toBe("ok");
+});
+
+test("GET /health/ready reports the database", async ({ request }) => {
+  const res = await request.get("/api/health/ready");
+  expect(res.status()).toBe(200);
+  expect((await res.json()).status).toBe("ready");
+});

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

@@ -0,0 +1,15 @@
+{
+  "name": "{{projectName}}-tests",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --project=ui",
+    "test:e2e:api": "playwright test --project=api",
+    "test:e2e:report": "playwright show-report"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "otpauth": "^9.5.1"
+  }
+}

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

@@ -0,0 +1,25 @@
+import { defineConfig, devices } from "@playwright/test";
+
+// The suite runs against a live stack: web on E2E_BASE_URL (proxying /api/* to
+// 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:5001";
+
+export default defineConfig({
+  testDir: ".",
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [["list"], ["html", { open: "never" }]],
+  use: {
+    baseURL,
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+  },
+  projects: [
+    { name: "api", testMatch: /.*\.api\.spec\.ts/ },
+    { name: "ui", testMatch: /.*\.ui\.spec\.ts/, use: { ...devices["Desktop Chrome"] } },
+  ],
+});

package/dist/templates/todo/tests/ui/smoke.ui.spec.ts

@@ -0,0 +1,8 @@
+import { expect, test } from "@playwright/test";
+
+// Module-agnostic: the app responds at "/" (a page or a redirect to it).
+test("app is reachable @smoke", async ({ page }) => {
+  const res = await page.goto("/");
+  expect(res?.status()).toBeLessThan(400);
+  await expect(page.locator("body")).toBeVisible();
+});

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