@podosoft/podokit 0.17.4 → 1.0.2

package/dist/lockfile.d.ts

@@ -1,9 +1,11 @@
+import type { TemplateVars } from "@podosoft/podokit-template-engine";
+import { type Toolchain } from "./toolchain";
 /**
  * The generation lockfile (`.podokit/`) records how a project was assembled so
  * `podo update` can rebuild the same inputs and detect user edits. See
  * ADR-0009 (update mechanism) and ADR-0010 (ownership model).
  */
-export declare const LOCK_SCHEMA_VERSION = 2;
+export declare const LOCK_SCHEMA_VERSION = 3;
 /** File ownership tier. See ADR-0010. */
 export type Tier = "managed" | "assembled" | "owned";
 export interface ManifestModule {
@@ -29,7 +31,8 @@ export interface PodokitManifest {
     schemaVersion: number;
     podokitVersion: string;
     template: string;
-    packageManager: string;
+    /** Runtime and package manager selected for generated and converted projects. */
+    toolchain: Toolchain;
     /** Render vars / prompt answers, replayed on update (copier-style). */
     answers: Record<string, string>;
     modules: ManifestModule[];
@@ -63,6 +66,8 @@ export declare function manifestPath(projectRoot: string): string;
 export declare function filesLockPath(projectRoot: string): string;
 export declare function readManifest(projectRoot: string): PodokitManifest | null;
 export declare function writeManifest(projectRoot: string, manifest: PodokitManifest): void;
+/** Complete replay variables for a Bun-only v1 project. */
+export declare function manifestTemplateVars(manifest: PodokitManifest): TemplateVars;
 export declare function writeFilesLock(projectRoot: string, lock: FilesLock): void;
 /** Read the PodoKit CLI's own version to stamp into the manifest. */
 export declare function podokitVersion(): string;
@@ -89,7 +94,7 @@ export interface Drift {
 export declare function computeDrift(projectRoot: string): Drift;
 export interface InitLockOptions {
     template: string;
-    packageManager: string;
+    toolchain?: Toolchain;
     answers: Record<string, string>;
     version?: string;
     ownedGlobs?: string[];

package/dist/lockfile.js

@@ -5,6 +5,7 @@ exports.manifestPath = manifestPath;
 exports.filesLockPath = filesLockPath;
 exports.readManifest = readManifest;
 exports.writeManifest = writeManifest;
+exports.manifestTemplateVars = manifestTemplateVars;
 exports.writeFilesLock = writeFilesLock;
 exports.podokitVersion = podokitVersion;
 exports.matchGlob = matchGlob;
@@ -19,12 +20,13 @@ exports.recordModules = recordModules;
 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 toolchain_1 = require("./toolchain");
 /**
  * The generation lockfile (`.podokit/`) records how a project was assembled so
  * `podo update` can rebuild the same inputs and detect user edits. See
  * ADR-0009 (update mechanism) and ADR-0010 (ownership model).
  */
-exports.LOCK_SCHEMA_VERSION = 2;
+exports.LOCK_SCHEMA_VERSION = 3;
 const PODOKIT_DIR = ".podokit";
 const MANIFEST_FILE = "manifest.json";
 const FILES_LOCK_FILE = "files.lock";
@@ -48,7 +50,7 @@ exports.DEFAULT_OWNED_GLOBS = [
     // Locale definitions and app messages are application-owned extension points.
     "apps/web/src/lib/i18n/locales/**",
     "apps/web/src/lib/i18n/catalogs/app/**",
-    // Owned Nest DI extension slot — override providers here; update never touches it.
+    // Owned Elysia extension slot — register application services and plugins here.
     "apps/api/src/app.extensions.ts",
     // AI agent guidance — yours to customize; update never touches it.
     "AGENTS.md",
@@ -82,12 +84,24 @@ function filesLockPath(projectRoot) {
 }
 function readManifest(projectRoot) {
     const file = manifestPath(projectRoot);
-    return (0, node_fs_1.existsSync)(file) ? JSON.parse((0, node_fs_1.readFileSync)(file, "utf8")) : null;
+    if (!(0, node_fs_1.existsSync)(file))
+        return null;
+    const raw = JSON.parse((0, node_fs_1.readFileSync)(file, "utf8"));
+    if (raw.schemaVersion !== exports.LOCK_SCHEMA_VERSION
+        || raw.toolchain?.runtime !== "bun"
+        || raw.toolchain.packageManager !== "bun") {
+        throw new Error("This project was generated by PodoKit v0 and is not compatible with PodoKit v1 updates. Use @podosoft/podokit@0.17.4 for this project; create a new v1 project for Bun and Elysia.");
+    }
+    return raw;
 }
 function writeManifest(projectRoot, manifest) {
     (0, node_fs_1.mkdirSync)(podokitDir(projectRoot), { recursive: true });
     (0, node_fs_1.writeFileSync)(manifestPath(projectRoot), `${JSON.stringify({ ...manifest, schemaVersion: exports.LOCK_SCHEMA_VERSION }, null, 2)}\n`);
 }
+/** Complete replay variables for a Bun-only v1 project. */
+function manifestTemplateVars(manifest) {
+    return { ...manifest.answers, ...(0, toolchain_1.toolchainTemplateVars)(manifest.toolchain) };
+}
 function writeFilesLock(projectRoot, lock) {
     (0, node_fs_1.mkdirSync)(podokitDir(projectRoot), { recursive: true });
     (0, node_fs_1.writeFileSync)(filesLockPath(projectRoot), `${JSON.stringify({ ...lock, schemaVersion: exports.LOCK_SCHEMA_VERSION }, null, 2)}\n`);
@@ -196,7 +210,7 @@ function initLockfile(projectRoot, options) {
         schemaVersion: exports.LOCK_SCHEMA_VERSION,
         podokitVersion: options.version ?? podokitVersion(),
         template: options.template,
-        packageManager: options.packageManager,
+        toolchain: options.toolchain ?? (0, toolchain_1.resolveToolchain)(),
         answers: options.answers,
         modules: [],
         ownedGlobs,

package/dist/prompt.d.ts

@@ -1,20 +1,13 @@
-import { type PackageManager } from "./create";
-export declare const PACKAGE_MANAGERS: PackageManager[];
-/** Asks a single question and resolves to the trimmed answer (empty if skipped). */
+import { type Toolchain } from "./toolchain";
 export type Ask = (question: string) => Promise<string>;
 export interface RawCreateArgs {
     template?: string;
-    pm?: PackageManager;
+    pm?: string;
+    runtime?: string;
 }
 export interface ResolvedCreateOptions {
     template: string;
-    packageManager: PackageManager;
+    toolchain: Toolchain;
 }
-/**
- * Resolve the template and package manager for `create`.
- *
- * Precedence: an explicit flag wins; otherwise, when `interactive` is true the
- * user is prompted (blank answer = default); otherwise the default is used.
- * Kept free of I/O — the caller injects `ask` — so it is unit-testable.
- */
+/** Resolve a Bun-only v1 project create request without runtime/package prompts. */
 export declare function resolveCreateOptions(args: RawCreateArgs, ask: Ask, interactive: boolean): Promise<ResolvedCreateOptions>;

package/dist/prompt.js

@@ -1,19 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PACKAGE_MANAGERS = void 0;
 exports.resolveCreateOptions = resolveCreateOptions;
 const templates_1 = require("./templates");
-exports.PACKAGE_MANAGERS = ["npm", "pnpm", "yarn"];
-function isPackageManager(value) {
-    return exports.PACKAGE_MANAGERS.includes(value);
-}
-/**
- * Resolve the template and package manager for `create`.
- *
- * Precedence: an explicit flag wins; otherwise, when `interactive` is true the
- * user is prompted (blank answer = default); otherwise the default is used.
- * Kept free of I/O — the caller injects `ask` — so it is unit-testable.
- */
+const toolchain_1 = require("./toolchain");
+/** Resolve a Bun-only v1 project create request without runtime/package prompts. */
 async function resolveCreateOptions(args, ask, interactive) {
     let template = args.template;
     if (!template && interactive) {
@@ -24,14 +14,7 @@ async function resolveCreateOptions(args, ask, interactive) {
     if (!(0, templates_1.isKnownTemplate)(template)) {
         throw new Error(`Unknown template "${template}". Choose one of: ${templates_1.TEMPLATE_NAMES.join(", ")}.`);
     }
-    let pm = args.pm;
-    if (!pm && interactive) {
-        const answer = await ask(`Package manager (${exports.PACKAGE_MANAGERS.join(" / ")}) [npm]: `);
-        pm = answer || undefined;
-    }
-    pm = pm ?? "npm";
-    if (!isPackageManager(pm)) {
-        throw new Error(`Invalid package manager "${pm}". Choose one of: ${exports.PACKAGE_MANAGERS.join(", ")}.`);
-    }
-    return { template, packageManager: pm };
+    if (args.pm)
+        throw new Error("PodoKit v1 uses Bun as its package manager; remove --pm.");
+    return { template, toolchain: (0, toolchain_1.resolveToolchain)(args.runtime ?? "bun") };
 }

package/dist/remove.js

@@ -6,8 +6,10 @@ const node_path_1 = require("node:path");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const add_1 = require("./add");
 const lockfile_1 = require("./lockfile");
-function readModuleManifest(moduleDir) {
-    return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8"));
+const toolchain_1 = require("./toolchain");
+function readModuleManifest(moduleDir, vars) {
+    const source = (0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8");
+    return JSON.parse(vars ? (0, podokit_template_engine_1.renderTokens)(source, vars) : source);
 }
 function readJson(path) {
     return JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
@@ -47,14 +49,18 @@ function removeModule(options) {
     if (!moduleDir) {
         throw new Error(`Cannot resolve module "${module}" to un-apply it. Is it still installed/bundled?`);
     }
-    const targetManifest = readModuleManifest(moduleDir);
+    const vars = {
+        projectName: projectName(projectRoot),
+        ...(0, toolchain_1.toolchainTemplateVars)(manifest.toolchain),
+    };
+    const targetManifest = readModuleManifest(moduleDir, vars);
     // Resolve the manifests of the OTHER installed modules once — used for the
     // requires guard and to decide which files/deps/env are shared.
     const others = manifest.modules
         .filter((m) => m.name !== module)
         .map((m) => {
         const dir = (0, add_1.resolveModuleDir)(m.packageName ?? m.name, modulesDir, projectRoot);
-        return dir ? { name: m.name, dir, manifest: readModuleManifest(dir) } : null;
+        return dir ? { name: m.name, dir, manifest: readModuleManifest(dir, vars) } : null;
     })
         .filter((m) => m !== null);
     // Guard: refuse if another installed module requires this one.
@@ -62,7 +68,6 @@ function removeModule(options) {
     if (dependents.length) {
         throw new Error(`Cannot remove "${module}": required by ${dependents.join(", ")}. Remove ${dependents.length > 1 ? "those" : "that"} first.`);
     }
-    const vars = { projectName: projectName(projectRoot) };
     const sharedFiles = new Set(others.flatMap((o) => moduleFilePaths(o.dir, vars)));
     const lock = (0, lockfile_1.readFilesLock)(projectRoot);
     // 1) un-wire marker injections (idempotent; skips optional/absent).

package/dist/templates/base/AGENTS.md

@@ -5,17 +5,17 @@ by [PodoKit](https://github.com/podosoft-dev/podokit).
 
 ## Project overview
 
-A minimal npm-workspace starter. Build it up from here — add features with the
+A minimal Bun 1.4 workspace starter. Build it up from here — add features with the
 `podo` CLI (`podo add <module>`; run `podo add` with no argument to list them).
 
 ## Commands
 
 ```bash
-npm install
-npm run dev      # runs workspace dev scripts
-npm run build
-npm run lint     # type-check
-npm test
+{{packageManager}} install
+{{rootRun}} dev      # runs workspace dev scripts
+{{rootRun}} build
+{{rootRun}} lint     # type-check
+{{rootRun}} test
 ```
 
 ## Code style
@@ -28,3 +28,5 @@ npm test
 This project is managed by the `podo` CLI; `.podokit/` records how it was
 assembled (do not edit by hand). Use `podo status`/`podo diff` to see your local
 edits and `podo update` to pull in improvements without losing your work.
+PodoKit v1 projects are Bun-only. Projects created with PodoKit 0.x remain on
+their pinned 0.x CLI line and are not converted in place.

package/dist/templates/base/README.md

@@ -2,8 +2,8 @@
 
 Generated with [PodoKit](https://github.com/podosoft-dev/podokit).
 
-A full-stack TypeScript workspace with a NestJS API (`apps/api`) and a
-SvelteKit web app (`apps/web`).
+A minimal Bun 1.4 TypeScript workspace. Add the `fullstack` template when you
+need an Elysia API and SvelteKit web application.
 
 ## Getting started
 

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

@@ -1,5 +1,5 @@
 // Entry point placeholder for the {{projectName}} API.
-// The full NestJS starter is added by `templates/fullstack-nest-svelte`.
+// The Bun + Elysia starter is provided by `templates/fullstack`.
 export function health(): { status: string } {
   return { status: "ok" };
 }

package/dist/templates/base/bunfig.toml

@@ -0,0 +1,3 @@
+[install]
+linker = "hoisted"
+auto = "disable"

package/dist/templates/base/package.json

@@ -2,16 +2,17 @@
   "name": "{{projectName}}",
   "version": "0.0.0",
   "private": true,
+  "packageManager": "bun@1.4.0",
   "engines": {
-    "node": ">=20"
+    "bun": "1.4.0"
   },
   "workspaces": [
     "apps/*"
   ],
   "scripts": {
     "dev": "echo \"Run 'dev' in apps/api and apps/web\" && exit 0",
-    "build": "npm run build --workspaces --if-present",
-    "lint": "npm run lint --workspaces --if-present",
-    "test": "npm run test --workspaces --if-present"
+    "build": "bun run --workspaces --if-present build",
+    "lint": "bun run --workspaces --if-present lint",
+    "test": "bun run --workspaces --if-present test"
   }
 }

package/dist/templates/{fullstack-nest-svelte → fullstack}/AGENTS.md

@@ -6,28 +6,32 @@ Follow it so your changes match the project's conventions.
 
 ## Project overview
 
-A full-stack TypeScript monorepo (npm workspaces):
+A Bun 1.4 full-stack TypeScript monorepo ({{packageManager}} workspaces):
 
-- `apps/api` — **NestJS** backend (`{{projectName}}-api`), TypeORM + PostgreSQL, Swagger at `/api-docs`.
+- `apps/api` — **Elysia** backend (`{{projectName}}-api`), Bun.SQL + PostgreSQL, merged OpenAPI at `/api-docs`.
 - `apps/web` — **SvelteKit** frontend (`{{projectName}}-web`), Tailwind v4 + shadcn-svelte + typesafe-i18n.
 - `infra/` — Docker Compose (PostgreSQL/Redis) and example k3s manifests.
-- `.podokit/` — PodoKit's generation lockfile (see "PodoKit tooling" below). Do not edit by hand.
+- `.podokit/` — PodoKit generation metadata plus application-owned development and
+  deployment profiles (see "PodoKit tooling" below).
 
 ## Setup & commands
 
 ```bash
-npm install
+{{packageManager}} install
 cp .env.example .env
 docker compose -f infra/docker/docker-compose.yml up -d   # PostgreSQL (+ Redis)
-npm run dev        # api on http://localhost:5002, web on http://localhost:5001
+{{rootRun}} dev        # api on http://localhost:5002, web on http://localhost:5001
 ```
 
 - **Ports: web = 5001, api = 5002.** The web app reaches the API only through its
   SvelteKit server proxy (`/api/*`), never with a direct browser `fetch`.
-- Build: `npm run build`  ·  Type-check/lint: `npm run lint`  ·  Unit tests: `npm test`
-- Per workspace: `npm run build -w {{projectName}}-api` / `-w {{projectName}}-web`.
-- DB migrations (TypeORM): `npm run migration:run -w {{projectName}}-api`.
-- e2e (Playwright, ships in `tests/`): `npm run test:e2e`.
+- Build: `{{rootRun}} build`  ·  Type-check/lint: `{{rootRun}} lint`  ·  Unit tests: `{{rootRun}} test`
+- Per workspace: `{{apiRun}} build` / `{{webRun}} build`.
+- DB migrations (TypeORM migration layer only): `{{apiRun}} migration:run`.
+- e2e (Playwright, ships in `tests/`): `{{rootRun}} test:e2e`.
+- Playwright officially runs on Node, so `bunx playwright` respects its Node
+  shebang. Node LTS is a test-tool dependency only; API, web, worker, migrations,
+  builds, and unit tests run on Bun.
 
 **Always** verify a change by building the affected workspace (and `svelte-check`
 for web) before considering it done. UI changes need a Playwright test; API
@@ -37,7 +41,7 @@ changes need an e2e/unit test.
 
 ### TypeScript (both apps)
 - `strict` mode. **No `any`** — use `unknown` + narrowing. **No `@ts-ignore`/`@ts-expect-error`** and no `eslint-disable`.
-- Explicit function return types. DTOs use `class-validator` decorators.
+- Explicit function return types. Validate HTTP inputs with Elysia `t` schemas.
 - Keep `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noUncheckedIndexedAccess`.
 
 ### Svelte 5 (web)
@@ -59,12 +63,15 @@ changes need an e2e/unit test.
 This project is managed by the `podo` CLI. Files have an ownership tier recorded
 in `.podokit/files.lock` — respect it:
 
-- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. To add or override Nest providers/modules, use `app.extensions.ts` (spread into `AppModule` after the module-wired providers, so a same-token override wins) rather than editing `app.module.ts`.
-- **assembled** (e.g. `apps/api/src/app.module.ts`, `auth.ts`) — contain `// podokit:begin:… / …:end` fenced regions that the toolkit recomputes. Edit outside the fences only; **never hand-edit inside the fences**.
+- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. Add application-owned services or module descriptors through `app.extensions.ts` instead of changing toolkit registrations.
+- **assembled** (e.g. `apps/api/src/app.ts`, `auth.ts`) — contain `// podokit:begin:… / …:end` fenced regions that the toolkit recomputes. Edit outside the fences only; **never hand-edit inside the fences**.
 - **managed** (bootstrap/config like `main.ts`) — the toolkit may update these; avoid gratuitous edits.
 
 Useful commands:
 
+- `podo dev watch|up|ps|logs|exec|down` — run container development through the
+  shared loopback gateway. `.podokit/dev.json` owns the local/public hosts and the
+  exact API WebSocket allowlist; never use a prefix or wildcard for that allowlist.
 - `podo add <module>` — add a feature (auth, admin-dashboard, redis, bullmq, …). It wires itself into the app; run `podo add` with no argument to list modules.
 - `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.

package/dist/templates/fullstack/Dockerfile.dev

@@ -0,0 +1,31 @@
+# Development image for the Bun 1.4.0 PodoKit monorepo.
+FROM oven/bun:1.4.0-alpine AS manifests
+WORKDIR /src
+COPY . .
+RUN mkdir -p /app \
+    && cp package.json bun.lock bunfig.toml /app/ \
+    && find . -name package.json -not -path "*/node_modules/*" \
+         -exec sh -c 'mkdir -p "/app/$(dirname "$1")" && cp "$1" "/app/$1"' _ {} \;
+
+FROM oven/bun:1.4.0-alpine
+
+RUN apk add --no-cache git python3 make g++ ca-certificates
+
+WORKDIR /app
+COPY --from=manifests /app ./
+ARG PODOKIT_NPM_REGISTRY=""
+RUN if [ -n "$PODOKIT_NPM_REGISTRY" ]; then \
+      bun install --frozen-lockfile --registry "$PODOKIT_NPM_REGISTRY"; \
+    else \
+      bun install --frozen-lockfile; \
+    fi
+
+COPY . .
+RUN if [ -d packages ]; then \
+      for manifest in packages/*/package.json; do \
+        [ -e "$manifest" ] || continue; \
+        bun run --cwd "$(dirname "$manifest")" --if-present build; \
+      done; \
+    fi
+
+EXPOSE 5001 5002

package/dist/templates/{fullstack-nest-svelte → fullstack}/README.md

@@ -2,7 +2,7 @@
 
 Full-stack TypeScript starter generated with [PodoKit](https://github.com/podosoft-dev/podokit).
 
-- `apps/api` — NestJS API: schema-validated env (zod), `/health` + `/health/ready`, Swagger docs at `/api-docs`, a standard error envelope, and TypeORM + PostgreSQL wired up (no domain entities yet — add your own).
+- `apps/api` — Bun 1.4 + Elysia API: schema-validated env, `/health` + `/health/ready`, merged OpenAPI at `/api-docs`, a standard error envelope, and Bun.SQL + PostgreSQL. TypeORM is used only to execute migrations.
 - `apps/web` — SvelteKit app (TailwindCSS v4, shadcn-svelte, typesafe-i18n) that talks to the API through a server-side proxy.
 - `infra/` — Docker Compose (PostgreSQL, Redis) and k3s manifests.
 
@@ -13,7 +13,7 @@ Full-stack TypeScript starter generated with [PodoKit](https://github.com/podoso
 ```bash
 {{packageManager}} install
 cp .env.example .env
-npx @podosoft/podokit dev watch
+{{packageExecutor}} @podosoft/podokit dev watch
 ```
 
 Open the URL printed by the command; a new project defaults to
@@ -23,15 +23,20 @@ one user-level Traefik gateway on `127.0.0.1:80`; additional projects reuse it a
 route by that hostname. Even a single app uses
 the same topology, with one route and no project-specific host port.
 
+When the API exposes WebSocket endpoints, add their exact paths to
+`.podokit/dev.json` under `webSocketPaths`. The shared gateway sends only those paths
+directly to the API and leaves every other path on the web app. Add `publicUrl` to the
+same file when an HTTPS tunnel preserves its public `Host` header.
+
 Run lifecycle and container commands from a second terminal:
 
 ```bash
-npx @podosoft/podokit dev url
-npx @podosoft/podokit dev up -d # detached stack without source watching
-npx @podosoft/podokit dev ps
-npx @podosoft/podokit dev logs
-npx @podosoft/podokit dev exec api npm run migration:run -w {{projectName}}-api
-npx @podosoft/podokit dev down
+{{packageExecutor}} @podosoft/podokit dev url
+{{packageExecutor}} @podosoft/podokit dev up -d # detached stack without source watching
+{{packageExecutor}} @podosoft/podokit dev ps
+{{packageExecutor}} @podosoft/podokit dev logs
+{{packageExecutor}} @podosoft/podokit dev exec api {{apiRun}} migration:run
+{{packageExecutor}} @podosoft/podokit dev down
 ```
 
 `dev watch` reads `.podokit/manifest.json` and automatically activates `cache`,
@@ -41,7 +46,7 @@ Watch attached.
 You can still activate an additional Compose profile explicitly:
 
 ```bash
-npx @podosoft/podokit dev watch --profile dev
+{{packageExecutor}} @podosoft/podokit dev watch --profile dev
 ```
 
 Explicit profile flags are preserved for other lifecycle commands. `dev down`
@@ -66,17 +71,15 @@ docker compose -f infra/docker/docker-compose.yml up -d
 
 ## Database & migrations
 
-The API uses TypeORM with PostgreSQL and ships no domain entities yet. Add an
-entity under `apps/api/src`, register it in `src/database/data-source.ts`, then
-generate and run a migration:
+The API uses Bun.SQL for request-time queries and TypeORM only as a migration
+runner. Add a numbered migration under `apps/api/src/migrations`, then run it:
 
 ```bash
-{{packageManager}} run migration:generate -w {{projectName}}-api -- src/migrations/Init
-{{packageManager}} run migration:run -w {{projectName}}-api
+{{apiRun}} migration:run
 ```
 
 Want a worked example? Generate the `todo` template instead:
-`npx @podosoft/podokit create my-app --template todo`.
+`{{packageExecutor}} @podosoft/podokit create my-app --template todo`.
 
 For multi-project routing, container profiles, migrations, and OAuth over a
 stable HTTPS tunnel, see the PodoKit [development guide](https://github.com/podosoft-dev/podokit/blob/main/docs/development.md).
@@ -88,9 +91,9 @@ route every public path through the web proxy. For a managed release on an
 existing cluster, initialize an application-owned profile:
 
 ```bash
-npx @podosoft/podokit deploy init --profile production --context production --host app.example.com
-npx @podosoft/podokit deploy doctor --profile production
-npx @podosoft/podokit deploy plan --profile production --release v1.2.3
+{{packageExecutor}} @podosoft/podokit deploy init --profile production --context production --host app.example.com
+{{packageExecutor}} @podosoft/podokit deploy doctor --profile production
+{{packageExecutor}} @podosoft/podokit deploy plan --profile production --release v1.2.3
 ```
 
 Use existing Kubernetes Secrets and never commit their values. See the PodoKit
@@ -103,3 +106,17 @@ lockfile and all workspace package manifests:
 docker build -f apps/api/Dockerfile -t {{projectName}}-api .
 docker build -f apps/web/Dockerfile -t {{projectName}}-web .
 ```
+
+The generated Kubernetes deployment trusts the ingress-provided
+`x-forwarded-proto` and `x-forwarded-host` headers so the web server can enforce
+same-origin form submissions. If the web container is served directly over plain
+HTTP, fix its public origin at build time instead:
+
+```bash
+docker build --build-arg PODOKIT_BUILD_ORIGIN=https://example.com -f apps/web/Dockerfile -t {{projectName}}-web .
+```
+
+For a Docker Compose deployment behind a trusted reverse proxy, set
+`PROTOCOL_HEADER=x-forwarded-proto` and `HOST_HEADER=x-forwarded-host` in the
+deployment profile runtime configuration. Never trust client-controlled forwarded
+headers on a directly exposed container.

package/dist/templates/fullstack/apps/api/Dockerfile

@@ -0,0 +1,47 @@
+# syntax=docker/dockerfile:1
+
+FROM oven/bun:1.4.0-alpine AS manifests
+WORKDIR /src
+COPY . .
+RUN mkdir -p /app \
+    && cp package.json bun.lock bunfig.toml /app/ \
+    && find . -name package.json -not -path "*/node_modules/*" \
+         -exec sh -c 'mkdir -p "/app/$(dirname "$1")" && cp "$1" "/app/$1"' _ {} \;
+
+FROM oven/bun:1.4.0-alpine AS deps
+WORKDIR /app
+COPY --from=manifests /app ./
+RUN bun ci
+
+FROM oven/bun:1.4.0-alpine AS prod-deps
+WORKDIR /app
+COPY --from=manifests /app ./
+RUN bun install --production --frozen-lockfile --filter './apps/api'
+
+FROM oven/bun:1.4.0-alpine AS build
+WORKDIR /app
+COPY --from=deps /app ./
+COPY . .
+RUN if [ -d packages ]; then \
+      for manifest in packages/*/package.json; do \
+        [ -e "$manifest" ] || continue; \
+        bun run --cwd "$(dirname "$manifest")" --if-present build; \
+      done; \
+    fi
+RUN bun run --cwd apps/api build
+RUN mkdir -p /app/packages
+
+FROM oven/bun:1.4.0-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+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 bun
+EXPOSE 3000
+HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=6 \
+  CMD bun -e "fetch('http://127.0.0.1:' + (process.env.PORT ?? '3000') + '/health/ready').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
+CMD ["bun", "dist/main.js"]

package/dist/templates/fullstack/apps/api/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{projectName}}-api",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "bun --watch src/main.ts",
+    "build": "bun scripts/build.mjs",
+    "start": "bun dist/main.js",
+    "lint": "bunx tsc -p tsconfig.json --noEmit",
+    "test": "bun test src",
+    "contract": "bun scripts/verify-api-contract.ts",
+    "migrate:all": "bun dist/database/migrate.js",
+    "typeorm": "bunx typeorm-ts-node-commonjs -d src/database/data-source.ts",
+    "migration:run": "bun run typeorm -- migration:run",
+    "migration:revert": "bun run typeorm -- migration:revert",
+    "migration:generate": "bun run typeorm -- migration:generate"
+  },
+  "dependencies": {
+    "@podosoft/podokit-contracts": "^0.4.0",
+    "@elysia/cors": "^1.4.2",
+    "@elysia/openapi": "^1.4.15",
+    "dotenv": "^16.4.5",
+    "elysia": "^1.4.29",
+    "pg": "^8.12.0",
+    "pino": "^9.6.0",
+    "typeorm": "^0.3.20",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "@types/node": "^20.17.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3"
+  }
+}

package/dist/templates/fullstack/apps/api/scripts/build.mjs

@@ -0,0 +1,38 @@
+import { existsSync, readdirSync } from "node:fs";
+
+const targets = [
+  { entrypoint: "src/main.ts", outdir: "dist" },
+  { entrypoint: "src/database/migrate.ts", outdir: "dist/database" },
+  { entrypoint: "src/migrate.ts", outdir: "dist" },
+  { entrypoint: "src/main-worker.ts", outdir: "dist" },
+].filter((target) => existsSync(target.entrypoint));
+
+for (const target of targets) {
+  const result = await Bun.build({
+    entrypoints: [target.entrypoint],
+    outdir: target.outdir,
+    target: "bun",
+  });
+  if (!result.success) {
+    for (const log of result.logs) process.stderr.write(`${log}\n`);
+    process.exit(1);
+  }
+}
+
+if (existsSync("src/migrations")) {
+  const migrations = readdirSync("src/migrations")
+    .filter((file) => /^\d+-.+\.ts$/.test(file))
+    .map((file) => `src/migrations/${file}`);
+  if (migrations.length > 0) {
+    const result = await Bun.build({
+      entrypoints: migrations,
+      outdir: "dist/migrations",
+      target: "bun",
+      external: ["typeorm"],
+    });
+    if (!result.success) {
+      for (const log of result.logs) process.stderr.write(`${log}\n`);
+      process.exit(1);
+    }
+  }
+}