@podosoft/podokit 0.16.3 → 0.17.0

package/dist/templates/fullstack-nest-svelte/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/fullstack-nest-svelte/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/fullstack-nest-svelte/apps/web/Dockerfile

@@ -1,17 +1,61 @@
 # 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
@@ -20,10 +64,18 @@ ENV NODE_ENV=production
 # API can return stable validation codes after accounting for multipart framing.
 ENV BODY_SIZE_LIMIT=3M
 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/fullstack-nest-svelte/apps/web/package.json

@@ -8,7 +8,7 @@
     "build": "vite build",
     "preview": "vite preview",
     "lint": "svelte-check --tsconfig ./tsconfig.json",
-    "test": "echo \"unit: add vitest; e2e: npm run test:e2e (see tests/)\" && exit 0"
+    "test": "vitest run"
   },
   "dependencies": {
     "@internationalized/date": "^3.12.2",
@@ -32,6 +32,7 @@
     "typesafe-i18n": "^5.26.2",
     "typescript": "^6.0.3",
     "vite": "^5.4.0",
+    "vitest": "^4.1.10",
     "tw-animate-css": "^1.4.0"
   }
 }

package/dist/templates/fullstack-nest-svelte/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/fullstack-nest-svelte/apps/web/src/lib/server/api.ts

@@ -1,12 +1,12 @@
 import type { RequestEvent } from "@sveltejs/kit";
 import { createApiClient, type ApiClient } from "@podosoft/podokit-api-client";
-import { backendBaseUrl, normalizeClientIp } from "./backend-proxy";
+import { backendBaseUrl, resolveClientIp } 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 clientIp = normalizeClientIp(event.getClientAddress());
+  const clientIp = resolveClientIp(event.getClientAddress);
   const fetchWithCookies: typeof fetch = (input, init) => {
     const headers = new Headers(init?.headers);
     if (cookie) headers.set("cookie", cookie);

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

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { proxyRequest, resolveClientIp } from "./backend-proxy";
+
+describe("backend proxy client address handling", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("returns the normalized address from a trusted proxy chain", () => {
+    expect(resolveClientIp(() => "::ffff:203.0.113.9")).toBe("203.0.113.9");
+  });
+
+  it("omits the address when the proxy header is absent", () => {
+    expect(
+      resolveClientIp(() => {
+        throw new Error("address header is absent");
+      }),
+    ).toBeUndefined();
+  });
+
+  it("omits the address when the proxy chain is too short", () => {
+    expect(
+      resolveClientIp(() => {
+        throw new Error("configured depth exceeds address count");
+      }),
+    ).toBeUndefined();
+  });
+
+  it("does not trust an incoming forwarded header as a fallback", 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 request = new Request("http://app.localhost/api/health", {
+      headers: { "x-forwarded-for": "198.51.100.25" },
+    });
+    const response = await proxyRequest(request, "http://api:5002/health");
+
+    expect(response.status).toBe(204);
+    expect(upstreamHeaders?.get("x-forwarded-for")).toBeNull();
+  });
+
+  it("forwards a resolved client address", 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 request = new Request("http://app.localhost/api/health");
+    const response = await proxyRequest(request, "http://api:5002/health", "203.0.113.9");
+
+    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/fullstack-nest-svelte/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 {
@@ -19,6 +33,15 @@ export function normalizeClientIp(address: string | undefined): string | undefin
   return address;
 }
 
+export function resolveClientIp(getClientAddress: () => string): string | undefined {
+  try {
+    return normalizeClientIp(getClientAddress());
+  } catch {
+    // An absent or shorter-than-configured proxy chain is not a trusted source.
+    return undefined;
+  }
+}
+
 export async function proxyRequest(
   request: Request,
   targetUrl: string,