@podosoft/podokit 0.16.4 → 0.17.0

package/dist/templates/fullstack-nest-svelte/infra/k3s/README.md

@@ -0,0 +1,18 @@
+# Example k3s manifests
+
+These are **illustrative**. `podo deploy` does not read or apply them.
+
+For a real deployment, initialize a profile and let PodoKit render the manifests it
+will actually apply — with image digests, probes, disruption budgets, a migration
+Job, and a confirmation hash:
+
+```bash
+podo deploy init --profile production --context production --host app.example.com
+podo deploy render --profile production --release v1.2.3
+```
+
+Keep these files if you want a starting point for hand-managed manifests, or delete
+the directory if you deploy with `podo deploy`. If you do apply them by hand, replace
+every `example.com` and `ghcr.io/example/...` placeholder first, and note that the
+image tags below are placeholders too: the deployment tooling rejects `latest`,
+branch tags, and empty tags, and so should you.

package/dist/templates/fullstack-nest-svelte/infra/k3s/api-deployment.yaml

@@ -1,3 +1,4 @@
+# Example only. See README.md in this directory; `podo deploy` renders its own.
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -13,7 +14,8 @@ spec:
     spec:
       containers:
         - name: api
-          image: ghcr.io/example/podokit-api:latest
+          # Placeholder. Use one immutable, stable SemVer tag for api and web.
+          image: ghcr.io/example/podokit-api:v0.0.0
           ports:
             - containerPort: 3000
           envFrom:
@@ -22,3 +24,6 @@ spec:
           readinessProbe:
             httpGet: { path: /health/ready, port: 3000 }
             initialDelaySeconds: 5
+          livenessProbe:
+            httpGet: { path: /health, port: 3000 }
+            initialDelaySeconds: 15

package/dist/templates/fullstack-nest-svelte/infra/k3s/ingress.yaml

@@ -1,3 +1,4 @@
+# Example only. See README.md in this directory; `podo deploy` renders its own.
 apiVersion: traefik.io/v1alpha1
 kind: Middleware
 metadata:
@@ -14,6 +15,13 @@ metadata:
   annotations:
     traefik.ingress.kubernetes.io/router.middlewares: podokit-compression@kubernetescrd
 spec:
+  # Name the controller explicitly rather than relying on a default IngressClass.
+  ingressClassName: traefik
+  # app-config sets an https:// origin, so the route has to terminate TLS. Create the
+  # Secret out of band (cert-manager, or an existing certificate) and name it here.
+  tls:
+    - hosts: [example.com]
+      secretName: app-tls
   rules:
     - host: example.com
       http:

package/dist/templates/fullstack-nest-svelte/infra/k3s/web-deployment.yaml

@@ -1,3 +1,4 @@
+# Example only. See README.md in this directory; `podo deploy` renders its own.
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -13,8 +14,17 @@ spec:
     spec:
       containers:
         - name: web
-          image: ghcr.io/example/podokit-web:latest
+          # Placeholder. Use one immutable, stable SemVer tag for api and web.
+          image: ghcr.io/example/podokit-web:v0.0.0
           ports:
             - containerPort: 3000
           envFrom:
             - configMapRef: { name: app-config }
+          # Without these a rolling update sends traffic to a process that has not
+          # bound its port yet.
+          readinessProbe:
+            httpGet: { path: /, port: 3000 }
+            initialDelaySeconds: 5
+          livenessProbe:
+            httpGet: { path: /, port: 3000 }
+            initialDelaySeconds: 15

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

@@ -9,6 +9,7 @@
   import * as Table from "$lib/components/ui/table";
   import * as Dialog from "$lib/components/ui/dialog";
   import DataTable, { type DataTableColumn, type SortState, DEFAULT_PAGE_SIZE } from "$lib/components/data-table.svelte";
+  import { deviceLabel } from "$lib/device-label";
   import { toast } from "svelte-sonner";
   import { api } from "$lib/api";
   import { getI18n, fmt, formatDateTime } from "$lib/i18n";
@@ -382,7 +383,7 @@
   let sessionsSort = $state<SortState | null>(null);
   let busy = $state(false);
   const sessionsColumns: DataTableColumn<Session>[] = [
-    { key: "userAgent", label: i18n.t.sessions.device, sortable: true, value: (s) => s.userAgent ?? "" },
+    { key: "userAgent", label: i18n.t.sessions.device, sortable: true, value: (s) => deviceLabel(s.userAgent) ?? s.userAgent ?? "" },
     { key: "ipAddress", label: i18n.t.sessions.ip, sortable: true, value: (s) => s.ipAddress ?? "" },
     { key: "createdAt", label: i18n.t.sessions.since, sortable: true, value: (s) => new Date(s.createdAt).getTime() },
     { key: "status", label: i18n.t.sessions.status },
@@ -793,7 +794,7 @@
             >
               {#snippet row(s)}
                 {@const isCurrent = s.id === data.currentSessionId}
-                <Table.Cell class="max-w-xs truncate">{s.userAgent ?? i18n.t.sessions.unknown}</Table.Cell>
+                <Table.Cell class="max-w-xs truncate" title={s.userAgent ?? ""}>{deviceLabel(s.userAgent) ?? s.userAgent ?? i18n.t.sessions.unknown}</Table.Cell>
                 <Table.Cell class="text-muted-foreground">{s.ipAddress ?? "—"}</Table.Cell>
                 <Table.Cell class="text-muted-foreground">{formatDateTime(s.createdAt)}</Table.Cell>
                 <Table.Cell>{#if isCurrent}<Badge>{i18n.t.sessions.current}</Badge>{/if}</Table.Cell>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/device-label.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { deviceLabel } from "./device-label";
+
+describe("deviceLabel", () => {
+  it("names the browser and the machine", () => {
+    expect(
+      deviceLabel(
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",
+      ),
+    ).toBe("Chrome · macOS");
+    expect(
+      deviceLabel(
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",
+      ),
+    ).toBe("Chrome · Windows");
+  });
+
+  // Each of these contains an earlier engine's token, so a naive check in the wrong
+  // order reports every one of them as Chrome or Safari.
+  it("does not mistake a derivative for the engine it embeds", () => {
+    expect(deviceLabel("Mozilla/5.0 (Windows NT 10.0) Chrome/141.0.0.0 Safari/537.36 Edg/141.0.0.0")).toBe(
+      "Edge · Windows",
+    );
+    expect(deviceLabel("Mozilla/5.0 (Windows NT 10.0) Chrome/141.0.0.0 Safari/537.36 OPR/121.0.0.0")).toBe(
+      "Opera · Windows",
+    );
+    expect(
+      deviceLabel("Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/141.0.0.0 SamsungBrowser/28.0 Safari/537.36"),
+    ).toBe("Samsung Internet · Android");
+    expect(
+      deviceLabel("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Version/18.0 Safari/605.1.15"),
+    ).toBe("Safari · macOS");
+  });
+
+  it("names an iPhone and an iPad rather than the engine's host platform", () => {
+    expect(
+      deviceLabel("Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 Version/18.0 Mobile/15E148 Safari/604.1"),
+    ).toBe("Safari · iPhone");
+    // iPadOS reports Macintosh in the same string, so order decides this one.
+    expect(
+      deviceLabel("Mozilla/5.0 (iPad; CPU OS 18_0 like Mac OS X) AppleWebKit/605.1.15 Version/18.0 Mobile/15E148 Safari/604.1"),
+    ).toBe("Safari · iPad");
+    expect(deviceLabel("Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) CriOS/141.0.0.0 Mobile/15E148 Safari/604.1")).toBe(
+      "Chrome · iPhone",
+    );
+  });
+
+  it("gives up on something that is not a browser, so the caller can show it raw", () => {
+    // The exact value is the whole point for these: "node" is the symptom of a
+    // proxy that forgot to forward the header, and a CLI's name identifies it.
+    expect(deviceLabel("node")).toBeNull();
+    expect(deviceLabel("curl/8.7.1")).toBeNull();
+    expect(deviceLabel("")).toBeNull();
+    expect(deviceLabel(null)).toBeNull();
+    expect(deviceLabel(undefined)).toBeNull();
+  });
+
+  it("reports whichever half it can read", () => {
+    expect(deviceLabel("Mozilla/5.0 (Windows NT 10.0; Win64; x64)")).toBe("Windows");
+    expect(deviceLabel("Firefox/142.0")).toBe("Firefox");
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/device-label.ts

@@ -0,0 +1,50 @@
+/**
+ * A readable device name for a session's user agent.
+ *
+ * The sessions tables label this column "device", and a raw user agent does not
+ * answer that question — truncated to fit a cell, every modern browser starts with
+ * the same "Mozilla/5.0 (…" and the part that differs is off the end. This reduces
+ * it to the two things someone scanning their own sessions is looking for: which
+ * browser, on which machine.
+ *
+ * Returns null when the string is not a browser at all — a CLI, a script, or the
+ * proxy's own default. The caller shows the raw value then, because for those the
+ * exact string is the only useful information.
+ */
+
+/** Order matters: every one of these also contains an earlier engine's token. */
+const BROWSERS: Array<[RegExp, string]> = [
+  [/\bEdg(?:e|A|iOS)?\//, "Edge"],
+  [/\bOPR\/|\bOpera\//, "Opera"],
+  [/\bSamsungBrowser\//, "Samsung Internet"],
+  [/\bFirefox\/|\bFxiOS\//, "Firefox"],
+  [/\bCriOS\//, "Chrome"],
+  [/\bChrome\/|\bChromium\//, "Chrome"],
+  [/\bSafari\//, "Safari"],
+];
+
+/** iPadOS reports as Macintosh, so the iPad check has to come before macOS. */
+const PLATFORMS: Array<[RegExp, string]> = [
+  [/\biPhone\b/, "iPhone"],
+  [/\biPad\b/, "iPad"],
+  [/\bAndroid\b/, "Android"],
+  [/\bCrOS\b/, "ChromeOS"],
+  [/\bWindows NT\b/, "Windows"],
+  [/\bMacintosh\b|\bMac OS X\b/, "macOS"],
+  [/\bLinux\b/, "Linux"],
+];
+
+function match(candidates: Array<[RegExp, string]>, value: string): string | null {
+  for (const [pattern, label] of candidates) {
+    if (pattern.test(value)) return label;
+  }
+  return null;
+}
+
+export function deviceLabel(userAgent: string | null | undefined): string | null {
+  if (!userAgent) return null;
+  const browser = match(BROWSERS, userAgent);
+  const platform = match(PLATFORMS, userAgent);
+  if (browser && platform) return `${browser} · ${platform}`;
+  return browser ?? platform;
+}

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

@@ -9,6 +9,7 @@
   import { toast } from "svelte-sonner";
   import { api } from "$lib/api";
   import { getI18n, fmt, formatDateTime } from "$lib/i18n";
+  import { deviceLabel } from "$lib/device-label";
 
   const i18n = getI18n();
 
@@ -43,7 +44,7 @@
 
   const columns = $derived<DataTableColumn<Row>[]>([
     { key: "user", label: i18n.t.adminSessions.user, sortable: true, value: (r) => r.userName },
-    { key: "device", label: i18n.t.adminSessions.device, sortable: true, value: (r) => r.userAgent },
+    { key: "device", label: i18n.t.adminSessions.device, sortable: true, value: (r) => deviceLabel(r.userAgent) ?? r.userAgent ?? "" },
     { key: "ip", label: i18n.t.adminSessions.ip, sortable: true, value: (r) => r.ipAddress },
     { key: "createdAt", label: i18n.t.adminSessions.since, sortable: true },
     { key: "expiresAt", label: i18n.t.adminSessions.expires, sortable: true, value: (r) => (r.expiresAt ? new Date(r.expiresAt).getTime() : 0) },
@@ -134,7 +135,7 @@
         </div>
         <div class="text-muted-foreground text-xs">{r.userEmail}</div>
       </Table.Cell>
-      <Table.Cell class="max-w-xs truncate">{r.userAgent ?? i18n.t.adminSessions.unknown}</Table.Cell>
+      <Table.Cell class="max-w-xs truncate" title={r.userAgent ?? ""}>{deviceLabel(r.userAgent) ?? r.userAgent ?? i18n.t.adminSessions.unknown}</Table.Cell>
       <Table.Cell class="text-muted-foreground">{r.ipAddress ?? "—"}</Table.Cell>
       <Table.Cell class="text-muted-foreground">{formatDateTime(r.createdAt)}</Table.Cell>
       <Table.Cell class="text-muted-foreground">{r.expiresAt ? formatDateTime(r.expiresAt) : "—"}</Table.Cell>

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

@@ -17,6 +17,7 @@
   import { api } from "$lib/api";
   import { getI18n, fmt, formatDateTime } from "$lib/i18n";
   import { cn } from "$lib/utils";
+  import { deviceLabel } from "$lib/device-label";
   import type { PageData } from "./$types";
 
   let { data }: { data: PageData } = $props();
@@ -194,7 +195,7 @@
   let mSessionsPage = $state(1);
   let mSessionsSort = $state<SortState | null>(null);
   const mSessionsColumns: DataTableColumn<Session>[] = [
-    { key: "userAgent", label: i18n.t.adminSessions.device, sortable: true },
+    { key: "userAgent", label: i18n.t.adminSessions.device, sortable: true, value: (s) => deviceLabel(s.userAgent) ?? s.userAgent ?? "" },
     { key: "ipAddress", label: i18n.t.adminSessions.ip, sortable: true },
     { key: "createdAt", label: i18n.t.adminSessions.since, sortable: true, value: (s) => new Date(s.createdAt).getTime() },
     { key: "actions", label: "", class: "w-10" },
@@ -557,7 +558,7 @@
               empty={i18n.t.adminSessions.empty}
             >
               {#snippet row(s)}
-                <Table.Cell class="max-w-40 truncate">{s.userAgent ?? i18n.t.adminSessions.unknown}</Table.Cell>
+                <Table.Cell class="max-w-40 truncate" title={s.userAgent ?? ""}>{deviceLabel(s.userAgent) ?? s.userAgent ?? i18n.t.adminSessions.unknown}</Table.Cell>
                 <Table.Cell class="text-muted-foreground">{s.ipAddress ?? "—"}</Table.Cell>
                 <Table.Cell class="text-muted-foreground">{formatDateTime(s.createdAt)}</Table.Cell>
                 <Table.Cell><Button variant="ghost" size="sm" disabled={busy} onclick={() => revokeSession(s.token)}>{i18n.t.users.revokeSession}</Button></Table.Cell>

package/dist/templates/modules/bullmq/files/infra/k3s/worker-deployment.yaml

@@ -1,3 +1,4 @@
+# Example only. See infra/k3s/README.md; `podo deploy` renders its own.
 # BullMQ worker — runs the same API image with the worker entrypoint.
 # It has no HTTP server, so there is no Service or Ingress.
 apiVersion: apps/v1
@@ -15,7 +16,7 @@ spec:
     spec:
       containers:
         - name: worker
-          image: ghcr.io/example/podokit-api:latest
+          image: ghcr.io/example/podokit-api:v0.0.0
           command: ["node", "dist/main-worker"]
           envFrom:
             - configMapRef: { name: app-config }

package/dist/templates/todo/AGENTS.md

@@ -70,7 +70,8 @@ Useful commands:
 - `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).
-- `podo deploy` — plan, apply, verify, or roll back an immutable Kubernetes release. Use `.agents/skills/podokit-deploy`.
+- `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.
+- `podo deploy sync` — copy local build output into a running Compose deployment and restart it, for iterating without a release. Not a release: no image is published and the next `apply` discards it. Use `.agents/skills/podokit-deploy-fast`.
 
 ## Commit conventions
 

package/dist/templates/todo/Dockerfile.dev

@@ -1,6 +1,24 @@
 # Development image for the PodoKit monorepo (web + api).
 # Dependencies and source are baked in; `docker compose watch` syncs your
 # edits into the running container so the native file watchers fire.
+
+# Every workspace manifest, collected rather than listed.
+#
+# Listing them by hand only works for the workspaces this template starts with. A
+# project that adds `packages/*` then has workspace manifests that never reach the
+# image, so npm does not know those names are local and goes looking for them on the
+# public registry — `npm error 404 '@scope/thing' is not in this registry`, from an
+# install that succeeds on the developer's own machine. The production images
+# collect manifests for exactly this reason; this one was the exception until a
+# generated project with shared packages could not start its dev stack at all.
+FROM node:22-bookworm-slim AS manifests
+WORKDIR /src
+COPY . .
+RUN mkdir -p /app \
+    && cp package.json /app/ \
+    && find . -name package.json -not -path "*/node_modules/*" \
+         -exec sh -c 'mkdir -p "/app/$(dirname "$1")" && cp "$1" "/app/$1"' _ {} \;
+
 FROM node:22-bookworm-slim
 
 # git for the toolchain (editors, AI agents); build tools for native modules.
@@ -14,9 +32,7 @@ WORKDIR /app
 # NB: the host package-lock.json is intentionally NOT copied — a lockfile
 # generated on macOS/Windows prunes platform-specific optional deps and can drop
 # packages (e.g. @swc/cli) on linux. Resolving fresh in-container avoids that.
-COPY package.json ./
-COPY apps/api/package.json ./apps/api/package.json
-COPY apps/web/package.json ./apps/web/package.json
+COPY --from=manifests /app ./
 ARG PODOKIT_NPM_REGISTRY=""
 RUN if [ -n "$PODOKIT_NPM_REGISTRY" ]; then npm config set registry "$PODOKIT_NPM_REGISTRY"; fi \
   && npm install
@@ -24,4 +40,19 @@ RUN if [ -n "$PODOKIT_NPM_REGISTRY" ]; then npm config set registry "$PODOKIT_NP
 # Baked source (kept in sync during development by `docker compose watch`).
 COPY . .
 
+# Workspace packages compile before the apps that import them. Apps import them by
+# their published entry point (`dist/index.js`), so without this the API starts and
+# dies on MODULE_NOT_FOUND for a package whose symlink is right there — the link
+# resolves, the built file behind it does not exist. `--if-present` keeps a project
+# with no packages, or one whose packages need no build, working unchanged.
+#
+# `docker compose watch` syncs app source only, so a change under packages/* needs
+# this image rebuilt rather than a container restart.
+RUN if [ -d packages ]; then \
+      for manifest in packages/*/package.json; do \
+        [ -e "$manifest" ] || continue; \
+        npm run build --if-present --workspace "$(dirname "$manifest")"; \
+      done; \
+    fi
+
 EXPOSE 5001 5002

package/dist/templates/todo/apps/api/Dockerfile

@@ -1,27 +1,88 @@
 # syntax=docker/dockerfile:1
+
+# The npm that reads package-lock.json must be the major that wrote it. node:22
+# bundles npm 10, and a lockfile written by npm 11 records platform-specific
+# packages as extraneous with no `optional` flag; npm 10 rejects those with
+# EBADPLATFORM instead of skipping them, so `npm ci` fails inside the image while
+# `npm install` on the developer's machine is fine. Keep this in step with the npm
+# the project is developed with.
+ARG NPM_VERSION=11.17.0
+
+# Every workspace manifest, and nothing else.
+#
+# Listing them by hand only works for the workspaces this template starts with: npm
+# does NOT fail when a workspace's package.json is absent, it silently installs a
+# tree without that package's dependencies. A project that adds packages/* then
+# builds against different versions than it resolves locally, and only inside the
+# image. Collecting them keeps `npm ci` correct whatever the workspace layout is,
+# and the stages below still cache on the manifests' content.
+FROM node:22-alpine AS manifests
+WORKDIR /src
+COPY . .
+RUN mkdir -p /app \
+    && cp package.json package-lock.json /app/ \
+    && find . -name package.json -not -path "*/node_modules/*" \
+         -exec sh -c 'mkdir -p "/app/$(dirname "$1")" && cp "$1" "/app/$1"' _ {} \;
+
 FROM node:22-alpine AS deps
 WORKDIR /app
-COPY package.json package-lock.json ./
-COPY apps/api/package.json ./apps/api/package.json
-COPY apps/web/package.json ./apps/web/package.json
-COPY tests/package.json ./tests/package.json
+COPY --from=manifests /app ./
+ARG NPM_VERSION
+RUN npm i -g "npm@${NPM_VERSION}"
 RUN npm ci --no-audit --no-fund
 
+# Production dependencies only, resolved from the same lockfile. The runtime stage
+# copies node_modules from here and never from deps or build, so the shipped image
+# does not carry the TypeScript compiler, Vite, or the test tooling.
+FROM node:22-alpine AS prod-deps
+WORKDIR /app
+COPY --from=manifests /app ./
+ARG NPM_VERSION
+RUN npm i -g "npm@${NPM_VERSION}"
+# The runtime tree for this image only.
+#
+# Scoping to the one workspace matters: --omit=dev at the root still installs the
+# union of every workspace's production dependencies, so the API image carried Vite
+# and the web image carried Nest. Measured on a generated project, this is 198
+# packages instead of 283. TypeScript stays either way -- typeorm depends on ts-node,
+# which depends on it, so it is a production dependency and not bloat.
+RUN npm ci --omit=dev --no-audit --no-fund --workspace=apps/api --include-workspace-root
+
 FROM node:22-alpine AS build
 WORKDIR /app
-COPY --from=deps /app/node_modules ./node_modules
+# Everything npm ci produced, not just the root node_modules: npm nests any
+# dependency it cannot hoist, and copying only the root directory leaves a workspace
+# package compiling against the wrong version of it.
+COPY --from=deps /app ./
 COPY . .
+# Local workspace packages compile before the app that imports them. Apps import
+# them by their published entry points and .dockerignore excludes dist, so nothing
+# here has compiled output until it is compiled here.
+RUN if [ -d packages ]; then \
+      for manifest in packages/*/package.json; do \
+        [ -e "$manifest" ] || continue; \
+        npm run build --if-present --workspace "$(dirname "$manifest")"; \
+      done; \
+    fi
 RUN npm run build --workspace=apps/api
+# The runtime needs the real workspace package directories, not just the symlinks
+# npm leaves in node_modules pointing at them. Without this the image boots and
+# dies on "Cannot find module <package>" -- a dangling link, at runtime only.
+# mkdir keeps the COPY valid for a project that has no packages/ at all.
+RUN mkdir -p /app/packages
 
 FROM node:22-alpine AS runtime
 WORKDIR /app
 ENV NODE_ENV=production
 RUN addgroup -S -g 101 app && adduser -S -D -H -u 100 -G app app
-COPY --from=build /app/node_modules ./node_modules
-COPY --from=deps /app/apps/api ./apps/api
+COPY --from=prod-deps /app/node_modules ./node_modules
+COPY --from=manifests /app/apps/api ./apps/api
+COPY --from=build /app/packages ./packages
 COPY --from=build /app/apps/api/dist ./apps/api/dist
 COPY --from=build /app/apps/api/scripts ./apps/api/scripts
 WORKDIR /app/apps/api
 USER 100:101
 EXPOSE 3000
+HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=6 \
+  CMD node -e "fetch('http://127.0.0.1:3000/health/ready').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
 CMD ["node", "dist/main"]

package/dist/templates/todo/apps/web/Dockerfile

@@ -1,26 +1,78 @@
 # syntax=docker/dockerfile:1
+
+# The npm that reads package-lock.json must be the major that wrote it. node:22
+# bundles npm 10, and a lockfile written by npm 11 records platform-specific
+# packages as extraneous with no `optional` flag; npm 10 rejects those with
+# EBADPLATFORM instead of skipping them, so `npm ci` fails inside the image while
+# `npm install` on the developer's machine is fine. Keep this in step with the npm
+# the project is developed with.
+ARG NPM_VERSION=11.17.0
+
+# See apps/api/Dockerfile for why the workspace manifests are collected rather than
+# listed: an absent workspace package.json does not fail `npm ci`, it silently
+# changes the resolved dependency tree inside the image.
+FROM node:22-alpine AS manifests
+WORKDIR /src
+COPY . .
+RUN mkdir -p /app \
+    && cp package.json package-lock.json /app/ \
+    && find . -name package.json -not -path "*/node_modules/*" \
+         -exec sh -c 'mkdir -p "/app/$(dirname "$1")" && cp "$1" "/app/$1"' _ {} \;
+
 FROM node:22-alpine AS deps
 WORKDIR /app
-COPY package.json package-lock.json ./
-COPY apps/api/package.json ./apps/api/package.json
-COPY apps/web/package.json ./apps/web/package.json
-COPY tests/package.json ./tests/package.json
+COPY --from=manifests /app ./
+ARG NPM_VERSION
+RUN npm i -g "npm@${NPM_VERSION}"
 RUN npm ci --no-audit --no-fund
 
+FROM node:22-alpine AS prod-deps
+WORKDIR /app
+COPY --from=manifests /app ./
+ARG NPM_VERSION
+RUN npm i -g "npm@${NPM_VERSION}"
+# The runtime tree for this image only.
+#
+# Scoping to the one workspace matters: --omit=dev at the root still installs the
+# union of every workspace's production dependencies, so the API image carried Vite
+# and the web image carried Nest. Measured on a generated project, this is 198
+# packages instead of 283. TypeScript stays either way -- typeorm depends on ts-node,
+# which depends on it, so it is a production dependency and not bloat.
+RUN npm ci --omit=dev --no-audit --no-fund --workspace=apps/web --include-workspace-root
+
 FROM node:22-alpine AS build
 WORKDIR /app
-COPY --from=deps /app/node_modules ./node_modules
+COPY --from=deps /app ./
 COPY . .
+RUN if [ -d packages ]; then \
+      for manifest in packages/*/package.json; do \
+        [ -e "$manifest" ] || continue; \
+        npm run build --if-present --workspace "$(dirname "$manifest")"; \
+      done; \
+    fi
 RUN npm run build --workspace=apps/web
+# The runtime needs the real workspace package directories, not just the symlinks
+# npm leaves in node_modules pointing at them. Without this the image boots and
+# dies on "Cannot find module <package>" -- a dangling link, at runtime only.
+# mkdir keeps the COPY valid for a project that has no packages/ at all.
+RUN mkdir -p /app/packages
 
 FROM node:22-alpine AS runtime
 WORKDIR /app
 ENV NODE_ENV=production
 RUN addgroup -S -g 101 app && adduser -S -D -H -u 100 -G app app
-COPY --from=build /app/node_modules ./node_modules
-COPY --from=deps /app/apps/web ./apps/web
+COPY --from=prod-deps /app/node_modules ./node_modules
+COPY --from=manifests /app/apps/web ./apps/web
+COPY --from=build /app/packages ./packages
 COPY --from=build /app/apps/web/build ./apps/web/build
+# The entry and the modules it imports run OUTSIDE the bundle, so they ship as
+# source. Without them the image falls back to an entry that cannot answer a
+# WebSocket upgrade.
+COPY --from=build /app/apps/web/server.js ./apps/web/server.js
+COPY --from=build /app/apps/web/src/lib/server ./apps/web/src/lib/server
 WORKDIR /app/apps/web
 USER 100:101
 EXPOSE 3000
-CMD ["node", "build"]
+HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=6 \
+  CMD node -e "fetch('http://127.0.0.1:3000/').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
+CMD ["node", "server.js"]

package/dist/templates/todo/apps/web/server.js

@@ -0,0 +1,31 @@
+/**
+ * The production entry point: adapter-node's server plus WebSocket upgrades.
+ *
+ * `node build` — adapter-node's own entry — serves HTTP perfectly well and drops
+ * every WebSocket upgrade into SvelteKit, which cannot answer one. This entry keeps
+ * adapter-node in charge of listening, graceful shutdown, and the PORT/HOST/
+ * IDLE_TIMEOUT contract, and adds the one thing it cannot do.
+ *
+ * Nothing is proxied unless `WS_PROXY_PATHS` names a path, so a deployment that has
+ * no WebSocket behaves exactly as `node build` did.
+ *
+ * ⚠ Not type-checked: it imports `./build/`, which only exists after `npm run build`,
+ * and lint must not depend on a build. Everything with a decision in it lives in
+ * `src/lib/server/ws-upgrade.js`, which is unit-tested; this is wiring.
+ */
+import { server } from "./build/index.js";
+import { createUpgradeProxy, relayPaths } from "./src/lib/server/ws-upgrade.js";
+
+const allowed = relayPaths();
+if (allowed.size > 0) {
+  // polka exposes the http.Server it was handed. If a future adapter stops doing so,
+  // fail at boot: serving silently without upgrades is the bug this entry exists for.
+  const httpServer = server.server;
+  if (!httpServer || typeof httpServer.on !== "function") {
+    throw new Error(
+      "adapter-node did not expose its HTTP server; the WebSocket upgrade proxy cannot be mounted",
+    );
+  }
+  httpServer.on("upgrade", createUpgradeProxy({ allowed }));
+  console.log(`Mounted WebSocket upgrade proxy for ${[...allowed].join(", ")}`);
+}

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

@@ -55,4 +55,25 @@ describe("backend proxy client address handling", () => {
     expect(response.status).toBe(204);
     expect(upstreamHeaders?.get("x-forwarded-for")).toBe("203.0.113.9");
   });
+
+  // Not forwarding this does not leave the header unset: fetch substitutes its own
+  // default, so the API records "node" for every session and the account page shows
+  // that as the device for all of them.
+  it("forwards the browser's user agent so sessions record the real device", async () => {
+    let upstreamHeaders: Headers | undefined;
+    vi.stubGlobal("fetch", async (_input: RequestInfo | URL, init?: RequestInit) => {
+      upstreamHeaders = new Headers(init?.headers);
+      return new Response(null, { status: 204 });
+    });
+
+    const agent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/141.0.0.0 Safari/537.36";
+    const request = new Request("http://app.localhost/api/auth/sign-in/email", {
+      method: "POST",
+      headers: { "user-agent": agent },
+    });
+    const response = await proxyRequest(request, "http://api:5002/auth/sign-in/email");
+
+    expect(response.status).toBe(204);
+    expect(upstreamHeaders?.get("user-agent")).toBe(agent);
+  });
 });

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

@@ -1,7 +1,21 @@
 // Server-side proxy boundary. The browser never talks to the API directly:
 // 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"];
+//
+// `user-agent` is on the list for the same reason the client IP is forwarded
+// below: better-auth records it on the session and the account page shows it as
+// the device. Leaving it off does not produce an empty column -- fetch supplies
+// its own default, so every session in the database reads "node", and the list
+// of "your devices" becomes a list of identical rows that identify nothing.
+const FORWARDED_HEADERS = [
+  "authorization",
+  "cookie",
+  "content-type",
+  "accept",
+  "origin",
+  "referer",
+  "user-agent",
+];
 const RELAYED_RESPONSE_HEADERS = ["content-type", "location", "cache-control"];
 
 export function backendBaseUrl(): string {