@voltro/cli 0.54.0 → 0.56.0

package/templates/apps/frontend-portal/package.json

@@ -12,18 +12,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.54.0",
-    "@voltro/cli": "0.54.0",
-    "@voltro/client": "0.54.0",
-    "@voltro/env": "0.54.0",
-    "@voltro/i18n": "0.54.0",
-    "@voltro/ui-shadcn": "0.54.0",
-    "@voltro/web": "0.54.0",
+    "@{{projectName}}/api": "0.56.0",
+    "@voltro/cli": "0.56.0",
+    "@voltro/client": "0.56.0",
+    "@voltro/env": "0.56.0",
+    "@voltro/i18n": "0.56.0",
+    "@voltro/web": "0.56.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.54.0",
+    "@voltro/devtools": "0.56.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-portal/src/pages/(portal)/layout.tsx

@@ -5,8 +5,7 @@
 // this runs per request.
 import type { ReactNode } from 'react'
 import { RedirectError, useLoaderData, useLocation, type LoaderFn } from '@voltro/web'
-import { T, useLocale, useT } from '@voltro/i18n'
-import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { T, useLocale, useT, LocaleSwitcher } from '@voltro/i18n'
 import { APP_NAME } from '../../config'
 import type { Identity } from '../../lib/api'
 

package/templates/apps/frontend-saas/package.json

@@ -12,18 +12,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.54.0",
-    "@voltro/cli": "0.54.0",
-    "@voltro/client": "0.54.0",
-    "@voltro/env": "0.54.0",
-    "@voltro/i18n": "0.54.0",
-    "@voltro/ui-shadcn": "0.54.0",
-    "@voltro/web": "0.54.0",
+    "@{{projectName}}/api": "0.56.0",
+    "@voltro/cli": "0.56.0",
+    "@voltro/client": "0.56.0",
+    "@voltro/env": "0.56.0",
+    "@voltro/i18n": "0.56.0",
+    "@voltro/web": "0.56.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.54.0",
+    "@voltro/devtools": "0.56.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-saas/src/pages/(marketing)/layout.tsx

@@ -3,8 +3,7 @@
 // `/login`. It gives the public pages a marketing header distinct from the
 // dashboard's sidebar shell.
 import type { ReactNode } from 'react'
-import { T, useLocale, useT } from '@voltro/i18n'
-import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { T, useLocale, useT, LocaleSwitcher } from '@voltro/i18n'
 import { APP_NAME } from '../../config'
 
 const LOCALES = [

package/templates/apps/frontend-saas/src/pages/dashboard/layout.tsx

@@ -6,8 +6,7 @@
 // per-visitor, and the build rejects a RedirectError there.
 import type { ReactNode } from 'react'
 import { RedirectError, useLoaderData, useLocation, type LoaderFn } from '@voltro/web'
-import { T, useLocale, useT } from '@voltro/i18n'
-import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { T, useLocale, useT, LocaleSwitcher } from '@voltro/i18n'
 import { APP_NAME } from '../../config'
 import type { Identity } from '../../lib/api'
 

package/templates/apps/frontend-spa/package.json

@@ -12,17 +12,16 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@voltro/cli": "0.54.0",
-    "@voltro/client": "0.54.0",
-    "@voltro/env": "0.54.0",
-    "@voltro/i18n": "0.54.0",
-    "@voltro/ui-shadcn": "0.54.0",
-    "@voltro/web": "0.54.0",
+    "@voltro/cli": "0.56.0",
+    "@voltro/client": "0.56.0",
+    "@voltro/env": "0.56.0",
+    "@voltro/i18n": "0.56.0",
+    "@voltro/web": "0.56.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.54.0",
+    "@voltro/devtools": "0.56.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-spa/src/pages/layout.tsx

@@ -6,8 +6,7 @@
 // chosen language.
 
 import type { ReactNode } from 'react'
-import { useLocale, useT } from '@voltro/i18n'
-import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { useLocale, useT, LocaleSwitcher } from '@voltro/i18n'
 import '../globals.css'
 
 const LOCALES = [

package/templates/apps/frontend-ssr/package.json

@@ -12,17 +12,16 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.54.0",
-    "@voltro/client": "0.54.0",
-    "@voltro/env": "0.54.0",
-    "@voltro/i18n": "0.54.0",
-    "@voltro/ui-shadcn": "0.54.0",
-    "@voltro/web": "0.54.0",
+    "@voltro/cli": "0.56.0",
+    "@voltro/client": "0.56.0",
+    "@voltro/env": "0.56.0",
+    "@voltro/i18n": "0.56.0",
+    "@voltro/web": "0.56.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.54.0",
+    "@voltro/devtools": "0.56.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-ssr/src/pages/layout.tsx

@@ -7,8 +7,7 @@
 // + reloads so the framework re-renders in the chosen language.
 
 import type { ReactNode } from 'react'
-import { T, useLocale, useT } from '@voltro/i18n'
-import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { T, useLocale, useT, LocaleSwitcher } from '@voltro/i18n'
 import '../globals.css'
 
 const LOCALES = [

package/templates/apps/frontend-ssr-api/package.json

@@ -12,18 +12,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.54.0",
-    "@voltro/cli": "0.54.0",
-    "@voltro/client": "0.54.0",
-    "@voltro/env": "0.54.0",
-    "@voltro/i18n": "0.54.0",
-    "@voltro/ui-shadcn": "0.54.0",
-    "@voltro/web": "0.54.0",
+    "@{{projectName}}/api": "0.56.0",
+    "@voltro/cli": "0.56.0",
+    "@voltro/client": "0.56.0",
+    "@voltro/env": "0.56.0",
+    "@voltro/i18n": "0.56.0",
+    "@voltro/web": "0.56.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.54.0",
+    "@voltro/devtools": "0.56.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-ssr-api/src/pages/layout.tsx

@@ -5,8 +5,7 @@
 // writes the `voltro:locale` cookie + reloads so the framework re-renders in the
 // chosen language.
 import type { ReactNode } from 'react'
-import { useLocale, useT } from '@voltro/i18n'
-import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { useLocale, useT, LocaleSwitcher } from '@voltro/i18n'
 import '../globals.css'
 
 const LOCALES = [

package/templates/apps/frontend-static-blog/package.json

@@ -12,19 +12,19 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.54.0",
-    "@voltro/client": "0.54.0",
-    "@voltro/content": "0.54.0",
-    "@voltro/env": "0.54.0",
-    "@voltro/i18n": "0.54.0",
-    "@voltro/ui-shadcn": "0.54.0",
-    "@voltro/web": "0.54.0",
+    "@voltro/cli": "0.56.0",
+    "@voltro/client": "0.56.0",
+    "@voltro/content": "0.56.0",
+    "@voltro/env": "0.56.0",
+    "@voltro/i18n": "0.56.0",
+    "@voltro/ui-shadcn": "0.56.0",
+    "@voltro/web": "0.56.0",
     "effect": "^3.22.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.54.0",
+    "@voltro/devtools": "0.56.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-static-blog/src/components/ReadingProgress.island.tsx

@@ -9,7 +9,7 @@
 
 import type { ReactNode } from 'react'
 import { useEffect, useState } from 'react'
-import { island } from '@voltro/web'
+import { island } from '@voltro/web/islands'
 
 function ReadingProgress(): ReactNode {
   const [pct, setPct] = useState(0)

package/templates/apps/frontend-static-blog/src/pages/[locale]/page.tsx

@@ -5,7 +5,13 @@
 import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../lib/locale'
 
 export { default } from '../page'
-export { renderMode, interactive, meta } from '../page'
+// `loader` belongs in this list: the re-exported component calls
+// `useLoaderData()`, and a mirror that forwards everything EXCEPT the loader
+// renders it at a level that declares none — which is a prerender failure, not
+// a missing-data warning. It was absent here while the `[slug]` mirror next
+// door forwarded it correctly, and no test could see the difference: a mirror
+// test asserts what IS re-exported, so an omission reads as a shorter list.
+export { renderMode, interactive, loader, meta } from '../page'
 
 export const getStaticPaths = async (): Promise<Array<{ params: { locale: string } }>> =>
   SUPPORTED_LOCALES

package/templates/apps/frontend-status/package.json

@@ -12,18 +12,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.54.0",
-    "@voltro/cli": "0.54.0",
-    "@voltro/client": "0.54.0",
-    "@voltro/env": "0.54.0",
-    "@voltro/i18n": "0.54.0",
-    "@voltro/ui-shadcn": "0.54.0",
-    "@voltro/web": "0.54.0",
+    "@{{projectName}}/api": "0.56.0",
+    "@voltro/cli": "0.56.0",
+    "@voltro/client": "0.56.0",
+    "@voltro/env": "0.56.0",
+    "@voltro/i18n": "0.56.0",
+    "@voltro/web": "0.56.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.54.0",
+    "@voltro/devtools": "0.56.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-status/src/pages/layout.tsx

@@ -1,8 +1,7 @@
 // Root layout — the status-page header (brand + language) and the stylesheet.
 // Don't render <html>/<head>/<body> here — the framework shell owns them.
 import type { ReactNode } from 'react'
-import { T, useLocale, useT } from '@voltro/i18n'
-import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { T, useLocale, useT, LocaleSwitcher } from '@voltro/i18n'
 import { APP_NAME } from '../config'
 import '../globals.css'
 

package/templates/apps/mobile-app/package.json

@@ -16,9 +16,9 @@
   "dependencies": {
     "@react-native-async-storage/async-storage": "1.23.1",
     "@react-native-community/netinfo": "11.4.1",
-    "@voltro/client": "0.54.0",
-    "@voltro/react-native": "0.54.0",
-    "@{{projectName}}/api": "0.54.0",
+    "@voltro/client": "0.56.0",
+    "@voltro/react-native": "0.56.0",
+    "@{{projectName}}/api": "0.56.0",
     "expo": "^52.0.0",
     "expo-constants": "~17.0.0",
     "expo-linking": "~7.0.0",
@@ -33,7 +33,7 @@
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@vitest/coverage-v8": "^4.1.10",
-    "@voltro/cli": "0.54.0",
+    "@voltro/cli": "0.56.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/baselines/compose/docker/api.Dockerfile

@@ -58,15 +58,71 @@ RUN APP_NAME=$(node -p "require('/workspace/${APP_PATH}/package.json').name") \
  && pnpm --filter="${APP_NAME}" --prod --no-optional --legacy deploy /deploy \
  ; cp -r /workspace/${APP_PATH}/.framework /deploy/.framework 2>/dev/null || echo "no .framework (serve loads from source)"
 
+
+# SLIM the runtime tree + BAKE the V8 code cache, and prove the image boots.
+#
+# The entrypoint below is `node <serveBundle>`, so the container never resolves
+# the @voltro/cli bin — `voltro prune-runtime` @vercel/nft-traces the reachable
+# set FROM that bundle and drops the rest (the used native SQL driver is traced
+# and kept automatically; an unused one is dropped). It runs in THIS stage,
+# where @vercel/nft is still installed.
+#
+# The boot smoke is the gate: it starts the PRUNED tree with the EXACT prod
+# entrypoint. `NODE_COMPILE_CACHE` makes that same run write node's compiled
+# bytecode into the image — a scale-from-zero container starts with an empty
+# temp dir, so baking it here is the only way it is warm when it matters.
+# Measured on the reference fixture: `voltro serve` boot 287 ms → 222 ms.
+#
+# The prune's `|| echo` covers an older framework without the command.
+#
+# Then TWO steps, and their being two instructions is the point.
+#
+# The LOAD is a hard gate. An api legitimately refuses to boot in this stage —
+# it has no database and no secrets — so demanding `serve: ready` here would
+# fail every honest build. But "cannot boot without a database" is not the same
+# sentence as "cannot be checked": every failure this step exists to catch — a
+# module `prune-runtime` traced away, a truncated artefact, a wrong entry path,
+# a missing export — happens at IMPORT, before anything connects. So the import
+# must succeed and `runServe` must be callable, or the build stops here.
+#
+# The SMOKE is not a gate. It reports how far the boot got, and both steps write
+# the V8 code cache into the image.
+#
+# They are separate RUN instructions on purpose. Chained into one shell command,
+# the smoke's trailing `|| echo` becomes the instruction's exit status, and a
+# failed load gate would ship a green build — the same shape as a pipe
+# swallowing the exit code of the check in front of it.
+RUN cd /deploy \
+ && (pnpm --filter="$(node -p "require('/deploy/package.json').name")" exec voltro prune-runtime /deploy \
+     || echo "prune-runtime unavailable — shipping the un-pruned tree") \
+ && NODE_COMPILE_CACHE=/deploy/.framework/.compile-cache node --input-type=module -e "\
+      const m = await import('/deploy/.framework/dist-api/serveBundle/serveEntry.js'); \
+      if (typeof m.runServe !== 'function') { \
+        console.error('load gate: the serve bundle exports no callable runServe'); \
+        process.exit(1); \
+      } \
+      console.log('load gate: the serve bundle imports, and runServe is callable');"
+
+RUN cd /deploy \
+ ; NODE_ENV=production NODE_COMPILE_CACHE=/deploy/.framework/.compile-cache \
+     timeout 20 node .framework/dist-api/serveBundle/serveEntry.js > /tmp/smoke.log 2>&1 \
+ ; grep -q 'serve: ready' /tmp/smoke.log \
+     && echo "boot smoke: ready (compile cache baked)" \
+     || echo "boot smoke: no DB/secrets in this stage — the load gate above is the one that had to pass"
+
 # ---------- prod runner ----------
 FROM node:${NODE_VERSION} AS prod
 ARG PNPM_VERSION
-RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
 WORKDIR /app
 COPY --from=builder /deploy /app
 EXPOSE 4000
 ENV NODE_ENV=production
-# `voltro serve` is the ONE production entrypoint — it auto-detects the app kind
-# and runs the API server. `voltro start` is web-only and aborts an API app at
-# boot with "no web app found at this path".
-CMD ["pnpm", "voltro", "serve", "."]
+# Reuse the cache the builder baked; node reads it before any user code runs.
+ENV NODE_COMPILE_CACHE=/app/.framework/.compile-cache
+# Direct-node entrypoint — boots the precompiled serve bundle IN THIS PROCESS.
+# No pnpm process, no @voltro/cli bin to resolve, which is what lets
+# `prune-runtime` drop the CLI from the runtime tree entirely. The bundle's
+# generated entry loads `.env` itself and chdir's to the app root, so it is
+# self-contained. (`pnpm voltro serve .` still works and does the same thing —
+# it just pays a second node startup and needs the CLI present.)
+CMD ["node", ".framework/dist-api/serveBundle/serveEntry.js"]

package/templates/baselines/compose/docker/web.Dockerfile

@@ -10,7 +10,8 @@
 #               Must match the app's app.config.ts `port` field.
 #
 # Targets:
-#   prod  — production image (`voltro build .` then `voltro start .`)
+#   prod  — production image: `voltro build` → `pnpm deploy` → `prune-runtime`
+#          → boot smoke (which also bakes the V8 code cache) → `node startEntry.js`
 #
 # Build:
 #   docker build \
@@ -41,19 +42,63 @@ RUN pnpm install --frozen-lockfile
 FROM deps AS builder
 ARG APP_PATH
 WORKDIR /workspace/${APP_PATH}
+# Builds the client assets, the SSR bundle and the start bundle. NOT
+# best-effort: an SSR-bundle failure is fatal by design, so an image whose
+# `voltro start` would fall back to compiling TSX per request never ships.
 RUN pnpm voltro build .
 
-# ---------- prod runner ----------
-FROM node:${NODE_VERSION} AS prod
-ARG PNPM_VERSION
-ARG APP_PATH
-ARG APP_PORT
-RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
+# Isolate a prod-only, self-contained tree for THIS app, then carry the build
+# OUTPUT into it — `pnpm deploy` copies package files, not generated output.
+#
+# `--no-optional` drops @voltro/cli's BUILD toolchain (tsx/esbuild/vite/tailwind
+# and their native tree), declared as optionalDependencies precisely so a
+# serve-only install sheds them. Nothing on the production start path is
+# TypeScript: `voltro build` precompiled `app.config.ts` next to the SSR bundle,
+# and the CMD below runs the start bundle directly.
 WORKDIR /workspace
+RUN APP_NAME=$(node -p "require('/workspace/${APP_PATH}/package.json').name") \
+ && pnpm --filter="${APP_NAME}" --prod --no-optional --legacy deploy /deploy \
+ && cp -r /workspace/${APP_PATH}/.framework /deploy/.framework \
+ && rm -f /deploy/app.config.ts \
+ && (pnpm --filter="${APP_NAME}" exec voltro prune-runtime /deploy \
+     || echo "prune-runtime unavailable — shipping the un-pruned tree")
+# The prune runs in THIS stage, where @vercel/nft (an @voltro/cli
+# optionalDependency) is still installed, and in the same RUN as the deploy so
+# `APP_NAME` is still in scope. The entrypoint is `node <startBundle>` (the CMD
+# below), so the container never resolves the @voltro/cli bin — nft traces the
+# reachable set FROM that bundle and drops everything else. A used native leaf
+# (a SQL driver an ISR/config path touches) is traced + kept automatically.
 
-COPY --from=builder /workspace /workspace
+# BAKE THE V8 CODE CACHE, and prove the image boots, in one step.
+#
+# The boot smoke is the gate: it starts the PRUNED tree with the EXACT prod
+# entrypoint and REQUIRES the framework's `start: ready` line, so a pruned-away
+# module or a broken artefact fails the BUILD instead of rolling out red. No
+# `|| true` — no ready line MUST fail the build.
+#
+# `NODE_COMPILE_CACHE` makes that same run write node's compiled-bytecode cache
+# into the image. A scale-from-zero container starts with an empty temp dir, so
+# without baking it here the cache would never be warm when it matters. Measured
+# on the reference fixture: `voltro start` boot 166 ms → 83 ms.
+RUN cd /deploy \
+ && NODE_ENV=production PORT=8099 VOLTRO_BOOT_TIMING=1 \
+      NODE_COMPILE_CACHE=/deploy/.framework/.compile-cache \
+      timeout 25 node .framework/dist-web/startBundle/startEntry.js 2>&1 \
+    | grep -m1 'start: ready'
 
-WORKDIR /workspace/${APP_PATH}
+# ---------- prod runner ----------
+FROM node:${NODE_VERSION} AS prod
+ARG APP_PORT
+# No pnpm/corepack here: the entrypoint is a direct `node` invocation of the
+# self-contained start bundle, so the runtime image needs only the node base
+# plus the pruned /deploy tree.
+WORKDIR /app
+COPY --from=builder /deploy /app
 EXPOSE ${APP_PORT}
 ENV NODE_ENV=production
-CMD ["pnpm", "voltro", "start", "."]
+# Reuse the cache the builder baked. Node reads it before any user code runs.
+ENV NODE_COMPILE_CACHE=/app/.framework/.compile-cache
+# Direct-node entrypoint — boots the precompiled start bundle IN THIS PROCESS,
+# no `pnpm voltro start` wrapper (no pnpm process, no @voltro/cli bin to
+# resolve). This is what lets `prune-runtime` drop the CLI from the runtime tree.
+CMD ["node", ".framework/dist-web/startBundle/startEntry.js"]

package/templates/baselines/compose-mariadb/docker/api.Dockerfile

@@ -58,15 +58,71 @@ RUN APP_NAME=$(node -p "require('/workspace/${APP_PATH}/package.json').name") \
  && pnpm --filter="${APP_NAME}" --prod --no-optional --legacy deploy /deploy \
  ; cp -r /workspace/${APP_PATH}/.framework /deploy/.framework 2>/dev/null || echo "no .framework (serve loads from source)"
 
+
+# SLIM the runtime tree + BAKE the V8 code cache, and prove the image boots.
+#
+# The entrypoint below is `node <serveBundle>`, so the container never resolves
+# the @voltro/cli bin — `voltro prune-runtime` @vercel/nft-traces the reachable
+# set FROM that bundle and drops the rest (the used native SQL driver is traced
+# and kept automatically; an unused one is dropped). It runs in THIS stage,
+# where @vercel/nft is still installed.
+#
+# The boot smoke is the gate: it starts the PRUNED tree with the EXACT prod
+# entrypoint. `NODE_COMPILE_CACHE` makes that same run write node's compiled
+# bytecode into the image — a scale-from-zero container starts with an empty
+# temp dir, so baking it here is the only way it is warm when it matters.
+# Measured on the reference fixture: `voltro serve` boot 287 ms → 222 ms.
+#
+# The prune's `|| echo` covers an older framework without the command.
+#
+# Then TWO steps, and their being two instructions is the point.
+#
+# The LOAD is a hard gate. An api legitimately refuses to boot in this stage —
+# it has no database and no secrets — so demanding `serve: ready` here would
+# fail every honest build. But "cannot boot without a database" is not the same
+# sentence as "cannot be checked": every failure this step exists to catch — a
+# module `prune-runtime` traced away, a truncated artefact, a wrong entry path,
+# a missing export — happens at IMPORT, before anything connects. So the import
+# must succeed and `runServe` must be callable, or the build stops here.
+#
+# The SMOKE is not a gate. It reports how far the boot got, and both steps write
+# the V8 code cache into the image.
+#
+# They are separate RUN instructions on purpose. Chained into one shell command,
+# the smoke's trailing `|| echo` becomes the instruction's exit status, and a
+# failed load gate would ship a green build — the same shape as a pipe
+# swallowing the exit code of the check in front of it.
+RUN cd /deploy \
+ && (pnpm --filter="$(node -p "require('/deploy/package.json').name")" exec voltro prune-runtime /deploy \
+     || echo "prune-runtime unavailable — shipping the un-pruned tree") \
+ && NODE_COMPILE_CACHE=/deploy/.framework/.compile-cache node --input-type=module -e "\
+      const m = await import('/deploy/.framework/dist-api/serveBundle/serveEntry.js'); \
+      if (typeof m.runServe !== 'function') { \
+        console.error('load gate: the serve bundle exports no callable runServe'); \
+        process.exit(1); \
+      } \
+      console.log('load gate: the serve bundle imports, and runServe is callable');"
+
+RUN cd /deploy \
+ ; NODE_ENV=production NODE_COMPILE_CACHE=/deploy/.framework/.compile-cache \
+     timeout 20 node .framework/dist-api/serveBundle/serveEntry.js > /tmp/smoke.log 2>&1 \
+ ; grep -q 'serve: ready' /tmp/smoke.log \
+     && echo "boot smoke: ready (compile cache baked)" \
+     || echo "boot smoke: no DB/secrets in this stage — the load gate above is the one that had to pass"
+
 # ---------- prod runner ----------
 FROM node:${NODE_VERSION} AS prod
 ARG PNPM_VERSION
-RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
 WORKDIR /app
 COPY --from=builder /deploy /app
 EXPOSE 4000
 ENV NODE_ENV=production
-# `voltro serve` is the ONE production entrypoint — it auto-detects the app kind
-# and runs the API server. `voltro start` is web-only and aborts an API app at
-# boot with "no web app found at this path".
-CMD ["pnpm", "voltro", "serve", "."]
+# Reuse the cache the builder baked; node reads it before any user code runs.
+ENV NODE_COMPILE_CACHE=/app/.framework/.compile-cache
+# Direct-node entrypoint — boots the precompiled serve bundle IN THIS PROCESS.
+# No pnpm process, no @voltro/cli bin to resolve, which is what lets
+# `prune-runtime` drop the CLI from the runtime tree entirely. The bundle's
+# generated entry loads `.env` itself and chdir's to the app root, so it is
+# self-contained. (`pnpm voltro serve .` still works and does the same thing —
+# it just pays a second node startup and needs the CLI present.)
+CMD ["node", ".framework/dist-api/serveBundle/serveEntry.js"]

package/templates/baselines/compose-mariadb/docker/web.Dockerfile

@@ -10,7 +10,8 @@
 #               Must match the app's app.config.ts `port` field.
 #
 # Targets:
-#   prod  — production image (`voltro build .` then `voltro start .`)
+#   prod  — production image: `voltro build` → `pnpm deploy` → `prune-runtime`
+#          → boot smoke (which also bakes the V8 code cache) → `node startEntry.js`
 #
 # Build:
 #   docker build \
@@ -41,19 +42,63 @@ RUN pnpm install --frozen-lockfile
 FROM deps AS builder
 ARG APP_PATH
 WORKDIR /workspace/${APP_PATH}
+# Builds the client assets, the SSR bundle and the start bundle. NOT
+# best-effort: an SSR-bundle failure is fatal by design, so an image whose
+# `voltro start` would fall back to compiling TSX per request never ships.
 RUN pnpm voltro build .
 
-# ---------- prod runner ----------
-FROM node:${NODE_VERSION} AS prod
-ARG PNPM_VERSION
-ARG APP_PATH
-ARG APP_PORT
-RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
+# Isolate a prod-only, self-contained tree for THIS app, then carry the build
+# OUTPUT into it — `pnpm deploy` copies package files, not generated output.
+#
+# `--no-optional` drops @voltro/cli's BUILD toolchain (tsx/esbuild/vite/tailwind
+# and their native tree), declared as optionalDependencies precisely so a
+# serve-only install sheds them. Nothing on the production start path is
+# TypeScript: `voltro build` precompiled `app.config.ts` next to the SSR bundle,
+# and the CMD below runs the start bundle directly.
 WORKDIR /workspace
+RUN APP_NAME=$(node -p "require('/workspace/${APP_PATH}/package.json').name") \
+ && pnpm --filter="${APP_NAME}" --prod --no-optional --legacy deploy /deploy \
+ && cp -r /workspace/${APP_PATH}/.framework /deploy/.framework \
+ && rm -f /deploy/app.config.ts \
+ && (pnpm --filter="${APP_NAME}" exec voltro prune-runtime /deploy \
+     || echo "prune-runtime unavailable — shipping the un-pruned tree")
+# The prune runs in THIS stage, where @vercel/nft (an @voltro/cli
+# optionalDependency) is still installed, and in the same RUN as the deploy so
+# `APP_NAME` is still in scope. The entrypoint is `node <startBundle>` (the CMD
+# below), so the container never resolves the @voltro/cli bin — nft traces the
+# reachable set FROM that bundle and drops everything else. A used native leaf
+# (a SQL driver an ISR/config path touches) is traced + kept automatically.
 
-COPY --from=builder /workspace /workspace
+# BAKE THE V8 CODE CACHE, and prove the image boots, in one step.
+#
+# The boot smoke is the gate: it starts the PRUNED tree with the EXACT prod
+# entrypoint and REQUIRES the framework's `start: ready` line, so a pruned-away
+# module or a broken artefact fails the BUILD instead of rolling out red. No
+# `|| true` — no ready line MUST fail the build.
+#
+# `NODE_COMPILE_CACHE` makes that same run write node's compiled-bytecode cache
+# into the image. A scale-from-zero container starts with an empty temp dir, so
+# without baking it here the cache would never be warm when it matters. Measured
+# on the reference fixture: `voltro start` boot 166 ms → 83 ms.
+RUN cd /deploy \
+ && NODE_ENV=production PORT=8099 VOLTRO_BOOT_TIMING=1 \
+      NODE_COMPILE_CACHE=/deploy/.framework/.compile-cache \
+      timeout 25 node .framework/dist-web/startBundle/startEntry.js 2>&1 \
+    | grep -m1 'start: ready'
 
-WORKDIR /workspace/${APP_PATH}
+# ---------- prod runner ----------
+FROM node:${NODE_VERSION} AS prod
+ARG APP_PORT
+# No pnpm/corepack here: the entrypoint is a direct `node` invocation of the
+# self-contained start bundle, so the runtime image needs only the node base
+# plus the pruned /deploy tree.
+WORKDIR /app
+COPY --from=builder /deploy /app
 EXPOSE ${APP_PORT}
 ENV NODE_ENV=production
-CMD ["pnpm", "voltro", "start", "."]
+# Reuse the cache the builder baked. Node reads it before any user code runs.
+ENV NODE_COMPILE_CACHE=/app/.framework/.compile-cache
+# Direct-node entrypoint — boots the precompiled start bundle IN THIS PROCESS,
+# no `pnpm voltro start` wrapper (no pnpm process, no @voltro/cli bin to
+# resolve). This is what lets `prune-runtime` drop the CLI from the runtime tree.
+CMD ["node", ".framework/dist-web/startBundle/startEntry.js"]