create-basalt 1.11.0 → 1.12.0

package/README.md

@@ -138,9 +138,12 @@ Always:
 
 ```
 my-app/
-├── package.json          # scripts: dev, start, test, typecheck, basalt (+ dev:web with --ui); create-basalt as a devDependency
+├── package.json          # scripts: dev, build, start (node dist/src/server.js), start:dev (tsx), test, typecheck, basalt (+ dev:web with --ui); create-basalt as a devDependency
 ├── .basalt/project.json  # scaffold manifest: create-basalt version, options, a hash per generated file — commit it
 ├── tsconfig.json         # strict TypeScript, ESM
+├── tsconfig.build.json   # what `pnpm build` compiles: src/ → dist/ (rootDir ".", so dist/src/server.js)
+├── Dockerfile            # multi-stage: build with the dev toolchain, run dist/src/server.js on plain node as USER node
+├── .dockerignore         # keeps .env, keys, node_modules and dist out of the build context
 ├── .env.example          # MY_APP_PORT, MY_APP_HOST, MY_APP_LOG_LEVEL, NODE_ENV (+ MY_APP_APP_SECRET with auth) + the precedence warning — committed
 ├── .env                  # the same values for local development (+ a generated MY_APP_APP_SECRET with auth) — git-ignored, loaded by dev/basalt
 ├── .gitignore
@@ -150,12 +153,12 @@ my-app/
 │   ├── env.ts            # environment variables validated with Zod (@basaltkit/env), app-prefixed
 │   ├── app.ts            # buildApp() with the chosen plugins
 │   ├── routes.ts         # GET / (friendly index) and GET /health
-│   ├── server.ts         # startup + clean shutdown on SIGINT/SIGTERM (`pnpm start` — loads no .env)
+│   ├── server.ts         # startup + clean shutdown on SIGINT/SIGTERM (`pnpm start` runs it compiled — loads no .env)
 │   └── dev.ts            # `pnpm dev`: loads .env, defaults NODE_ENV=development, starts server.ts
 └── tests/app.test.ts     # smoke test adapted to the options
 ```
 
-With `--prisma`, adds `prisma/schema.prisma`, `prisma.config.ts`, `src/db.ts`, `prisma/seed.ts` (with tenancy) and the `db:generate` / `db:migrate` / `db:deploy` / `db:seed` scripts. The `basalt` script is `create-basalt --project` with `--no-cli` (so `pnpm basalt update|add|doctor|info` works in every app); with `--cli` it is `tsx bin/basalt.ts`, and `bin/basalt.ts` forwards those four commands to create-basalt before booting the app. With `--ui`, adds the `web/` folder (Vite 8 + React 19 + Tailwind CSS 4 via `@tailwindcss/vite` + shadcn — Tailwind is configured in `web/src/index.css`, no `tailwind.config.js`/PostCSS — with `web/src/api.ts` built on top of `@basaltkit/sdk`; with auth on it includes a login/register screen).
+With `--prisma`, adds `prisma/schema.prisma`, `prisma.config.ts`, `src/db.ts`, `prisma/seed.ts` (with tenancy) and the `db:generate` / `db:migrate` / `db:deploy` / `db:seed` scripts. The client is generated into `generated/prisma` (outside `src/`, so the build never copies it) and imported as `#db/client.js` through a package.json `imports` alias; `@prisma/client-runtime-utils` is a direct dependency (the generated runtime requires it by name), and `pnpm-workspace.yaml` approves the `prisma` / `@prisma/engines` build scripts. The `basalt` script is `create-basalt --project` with `--no-cli` (so `pnpm basalt update|add|doctor|info` works in every app); with `--cli` it is `tsx bin/basalt.ts`, and `bin/basalt.ts` forwards those four commands to create-basalt before booting the app. With `--ui`, adds the `web/` folder (Vite 8 + React 19 + Tailwind CSS 4 via `@tailwindcss/vite` + shadcn — Tailwind is configured in `web/src/index.css`, no `tailwind.config.js`/PostCSS — with `web/src/api.ts` built on top of `@basaltkit/sdk`; with auth on it includes a login/register screen).
 
 ### With `--ui`: running the API and frontend
 
@@ -188,10 +191,13 @@ the next restart.
 pnpm create basalt my-app --prisma
 cd my-app && pnpm install     # postinstall runs `prisma generate`
 # .env already points MY_APP_DATABASE_URL at postgres://…@localhost:5432/my_app — start PostgreSQL or edit it
-pnpm db:migrate               # prisma migrate dev — creates the tables and seeds `demo`
+pnpm db:migrate               # prisma migrate dev — creates the tables
+pnpm db:seed                  # prisma db seed — the `demo` tenant
 pnpm dev
 ```
 
+After a schema change: `pnpm db:migrate --name <change>` writes and applies the migration (without `--name` Prisma prompts for one), then `pnpm db:generate` — Prisma 7's `migrate dev` does not regenerate the client.
+
 **Migrations, never `prisma db push`.** The generated app boots with
 `assertMigrated: true`, which refuses to start unless the database it reached has
 the `_prisma_migrations` table — written by `prisma migrate dev` /
@@ -288,6 +294,13 @@ file". Files are patched **only** when they are byte-for-byte a known template
 (or the manifest records them untouched); a customised one is left alone and the
 exact snippet to paste is printed.
 
+An app from before the production path is **offered** what it lacks:
+`tsconfig.build.json`, a `build` script, the `Dockerfile` (pnpm apps) and
+`.dockerignore`, and with Prisma `@prisma/client-runtime-utils`. Existing files
+are never touched and an existing `start` script is never rewritten — the two
+script lines to paste are printed instead. A Prisma client still generated under
+`src/generated` gets the move instructions and no Dockerfile until it is moved.
+
 ### Adding features later
 
 ```bash
@@ -330,9 +343,15 @@ default — `DATABASE_URL` with `--prisma`) that is set neither in the environme
 nor in `.env` — an error, with the fix (`cp .env.example .env`, set it, start
 PostgreSQL); a missing `.env` next to a `.env.example` (warning); whether the Prisma client is generated and
 migrations exist (whether they are *applied* needs a database —
-`prisma migrate status`); `.mcp.json` when `@basaltkit/ai-mcp` is installed; dev
-tooling declared as a runtime dependency; and an outdated `bin/basalt.ts` or
-`src/dev.ts`.
+`prisma migrate status`); the `db:seed` script of create-basalt 1.8–1.11
+(`tsx prisma/seed.ts`, which loads no `.env` — a warning with the exact
+replacement, `"db:seed": "prisma db seed"`; `update` prints the same line and
+never rewrites the script); `.mcp.json` when `@basaltkit/ai-mcp` is installed; dev
+tooling declared as a runtime dependency; an outdated `bin/basalt.ts` or
+`src/dev.ts`; and, statically, the production path (a `start` running tsx while
+tsx is a devDependency, no `build` script, `dist/src/server.js` older than
+`src/`, a Prisma client generated under `src/`, a missing
+`@prisma/client-runtime-utils`). It never builds or starts the app.
 
 `info` prints create-basalt, Node, OS, package manager, the app's features and
 the declared/installed versions of the framework and key tools — paste it into

package/dist/bin-template.js

@@ -92,7 +92,11 @@ if (existsSync(envFile)) process.loadEnvFile(envFile)
  * migrated. Anything else is rethrown untouched.
  */
 async function explainBootFailure(error: unknown): Promise<never> {
-  const failure = (error ?? {}) as { code?: unknown; report?: unknown; message?: unknown; cause?: unknown; errors?: unknown }
+  const failure = (error ?? {}) as {
+    code?: unknown; report?: unknown; message?: unknown; cause?: unknown; errors?: unknown; details?: unknown
+  }
+  // @basaltkit/prisma's describeDbError diagnosis (assertMigrated attaches it): the cause and its one-line fix.
+  const diagnosis = (failure.details as { diagnosis?: { code?: unknown; cause?: unknown; fix?: unknown } } | undefined)?.diagnosis
   const message = String(failure.message ?? '')
   const codes = [failure, failure.cause, ...(Array.isArray(failure.errors) ? failure.errors : [])].map((item) =>
     String((item as { code?: unknown } | null | undefined)?.code ?? ''),
@@ -116,6 +120,16 @@ async function explainBootFailure(error: unknown): Promise<never> {
         (existsSync(join(root, 'prisma')) ? ' — for DATABASE_URL, start PostgreSQL and point the URL at it' : '') +
         '. \`pnpm basalt doctor\` checks the environment; ' + debugHint,
     ].join('\\n')
+  } else if (diagnosis && (diagnosis.code === 'DB_PERMISSION_DENIED' || diagnosis.code === 'DB_NOT_EMPTY_BASELINE')) {
+    const database = await databaseInUse()
+    explanation = [
+      diagnosis.code === 'DB_PERMISSION_DENIED'
+        ? 'The app cannot start — the database refused the app database role (permission denied):'
+        : 'The app cannot start — the database has tables but no migration history:',
+      '  ' + String(diagnosis.cause),
+      'Database: ' + database.target + ' (from ' + database.name + '; credentials never shown).',
+      'Fix: ' + String(diagnosis.fix) + ' ' + debugHint,
+    ].join('\\n')
   } else if (unreachable || failure.code === 'PRISMA_NOT_MIGRATED') {
     const database = await databaseInUse()
     const where = 'Database: ' + database.target + ' (from ' + database.name + '; credentials never shown).'

package/dist/cli.js

@@ -154,7 +154,10 @@ try {
         // the app asserts at boot that it reached the MIGRATED database.
         // .env is already written with a local URL (pnpm dev / pnpm basalt load it).
         steps.push(`# start PostgreSQL, or edit ${envPrefix(result.options.name)}_DATABASE_URL in .env`);
-        steps.push(`${pm} run db:migrate${flags.tenancy ? '   # creates the tables and seeds the demo tenant' : '   # creates the tables'}`);
+        steps.push(`${pm} run db:migrate   # creates the tables`);
+        // Prisma 7's `migrate dev` no longer seeds: the demo tenant is its own step.
+        if (flags.tenancy)
+            steps.push(`${pm} run db:seed      # the demo tenant the resolvers expect`);
     }
     steps.push(`${pm} run dev${flags.ui ? '        # API on :3000' : ''}`);
     // `web` is a pnpm workspace member (pnpm-workspace.yaml); `dev:web` runs its

package/dist/index.js

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { appTest, appTs, dbTs, devEnvFile, devTs, dockerignore, envExample, envTs, gitignore, mcpJson, basaltBin, packageJson, pnpmWorkspaceYaml, prismaConfigTs, prismaSchema, prismaSeedTs, readme, routesTs, serverTs, tsconfigJson, } from './templates.js';
+import { appTest, appTs, dbTs, devEnvFile, devTs, dockerfile, dockerignore, envExample, envTs, gitignore, mcpJson, basaltBin, packageJson, pnpmWorkspaceYaml, prismaConfigTs, prismaSchema, prismaSeedTs, readme, routesTs, serverTs, tsconfigBuildJson, tsconfigJson, } from './templates.js';
 import { uiFiles } from './templates-ui.js';
 import { INSECURE_SECRET } from './project/doctor.js';
 import { createManifest, MANIFEST_PATH, serializeManifest } from './project/manifest.js';
@@ -43,8 +43,10 @@ export function scaffoldFiles(options) {
     return {
         'package.json': packageJson(options),
         'tsconfig.json': tsconfigJson(options),
+        'tsconfig.build.json': tsconfigBuildJson(),
         '.env.example': envExample(options),
         '.gitignore': gitignore(options),
+        Dockerfile: dockerfile(),
         '.dockerignore': dockerignore(),
         'README.md': readme(options),
         'pnpm-workspace.yaml': pnpmWorkspaceYaml(options),

package/dist/latest-versions.js

@@ -33,6 +33,7 @@
 export const THIRD_PARTY_VERSIONS = {
     '@prisma/adapter-pg': '^7.10.0',
     '@prisma/client': '^7.10.0',
+    '@prisma/client-runtime-utils': '^7.10.0',
     '@tailwindcss/vite': '^4.3.3',
     '@types/node': '^26.6.2',
     '@types/pg': '^8.15.6',

package/dist/project/doctor.d.ts

@@ -9,7 +9,7 @@ import type { Colors } from './term.js';
 export type Level = 'ok' | 'info' | 'warn' | 'error';
 export interface DoctorFinding {
     level: Level;
-    /** Short area label: node, pm, deps, env, prisma, mcp, tooling. */
+    /** Short area label: node, pm, deps, env, prisma, mcp, tooling, build. */
     area: string;
     message: string;
 }

package/dist/project/doctor.js

@@ -1,13 +1,16 @@
 import { existsSync } from 'node:fs';
-import { readdir, readFile } from 'node:fs/promises';
+import { readdir, readFile, stat } from 'node:fs/promises';
 import { arch, platform } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { binStatus } from '../bin-template.js';
 import { devEntryStatus } from '../dev-entry.js';
 import { alwaysLatest, lookupLatestVersions } from '../latest-versions.js';
+import { PRODUCTION_ENTRY } from '../stubs.js';
 import { envPrefix } from '../templates.js';
 import { allDependencies } from './context.js';
 import { ownVersion } from './manifest.js';
+import { LEGACY_PRISMA_OUTPUT, RUNS_TSX } from './production.js';
+import { legacySeedScriptFix } from './seed-script.js';
 import { compareVersions, parseSimpleRange, parseVersion, satisfies } from './semver.js';
 /** Mirrors the placeholder check of `secret()` in @basaltkit/env (src/secret.ts). */
 export const INSECURE_SECRET = /change.?me|changeme|placeholder|example|secret|password|default|test|xxxx+|0000+/i;
@@ -344,6 +347,9 @@ export async function runDoctor(ctx, options = {}) {
             push('warn', 'prisma', `No migrations yet — run \`${ctx.pm === 'npm' ? 'npm run' : ctx.pm} db:migrate\` (the app boots with assertMigrated).`);
         else
             push('info', 'prisma', `${count} migration(s) on disk; whether they are applied needs the database: \`prisma migrate status\`.`);
+        const seedFix = legacySeedScriptFix(ctx.packageJson, await readText(join(dir, 'prisma.config.ts')));
+        if (seedFix !== undefined)
+            push('warn', 'prisma', seedFix);
     }
     // --- MCP -------------------------------------------------------------------------
     if (deps['@basaltkit/ai-mcp'] !== undefined) {
@@ -389,8 +395,54 @@ export async function runDoctor(ctx, options = {}) {
         push('info', 'tooling', 'src/dev.ts is customised and does not load .env — see `create-basalt update` for the snippet.');
     if (!ctx.manifest)
         push('info', 'tooling', 'No .basalt/project.json (scaffolded before create-basalt 1.10) — features are inferred from package.json.');
+    // --- Production path (BK-026) — static: nothing is built or started ----------
+    const scripts = ctx.packageJson.scripts ?? {};
+    const run = (script) => `${ctx.pm === 'npm' ? 'npm run' : ctx.pm} ${script}`;
+    const start = scripts['start'];
+    const tsxIsDevOnly = ctx.packageJson.dependencies?.['tsx'] === undefined && ctx.packageJson.devDependencies?.['tsx'] !== undefined;
+    if (start !== undefined && RUNS_TSX.test(start) && tsxIsDevOnly) {
+        push('warn', 'build', `\`start\` runs tsx ("${start}"), but tsx is only a devDependency — a production install (--prod) has no tsx. Build and run the compiled server: \`npx create-basalt@latest update\` prints the scripts.`);
+    }
+    if (scripts['build'] === undefined) {
+        push('warn', 'build', `No \`build\` script — there is no tested way to run the app on plain node. \`npx create-basalt@latest update\` adds tsconfig.build.json and \`build\`.`);
+    }
+    else {
+        const built = await mtimeOf(join(dir, PRODUCTION_ENTRY));
+        const source = await newestMtime(join(dir, 'src'));
+        if (built !== undefined && source !== undefined && source > built) {
+            push('info', 'build', `${PRODUCTION_ENTRY} is older than src/ — run \`${run('build')}\` before \`${run('start')}\`.`);
+        }
+    }
+    if (schema !== undefined) {
+        if (LEGACY_PRISMA_OUTPUT.test(schema)) {
+            push('warn', 'build', 'The Prisma client is generated under src/ — `tsc` does not copy its .js files, so the built app cannot load it. `npx create-basalt@latest update` prints how to move it to ./generated.');
+        }
+        if (deps['@prisma/client'] !== undefined && deps['@prisma/client-runtime-utils'] === undefined) {
+            push('warn', 'build', 'The generated Prisma client requires @prisma/client-runtime-utils by name — declare it as a dependency (same range as @prisma/client), or plain `node` cannot load the client under pnpm.');
+        }
+    }
     return findings;
 }
+async function mtimeOf(path) {
+    try {
+        return (await stat(path)).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Newest modification time of the .ts files under `dir` (recursive), or undefined. */
+async function newestMtime(dir) {
+    let newest;
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        const time = entry.isDirectory() ? await newestMtime(path) : entry.name.endsWith('.ts') ? await mtimeOf(path) : undefined;
+        if (time !== undefined && (newest === undefined || time > newest))
+            newest = time;
+    }
+    return newest;
+}
 export function renderFindings(findings, colors) {
     const icon = {
         ok: colors.green('✓'),

package/dist/project/production.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The production path (BK-026) for an app scaffolded before create-basalt
+ * shipped one: `create-basalt update` OFFERS what is missing — it is part of
+ * the printed plan, applied only on confirmation — and never rewrites what the
+ * app already has. In particular an existing `start` script is never changed:
+ * switching it from tsx to the compiled server changes how the app is
+ * deployed, so that is printed as a manual step.
+ */
+export interface ProductionPathPlan {
+    /** New files: path → content (only files that do not exist yet). */
+    files: Record<string, string>;
+    /** package.json after the additions (the input text when nothing changes). */
+    packageJsonText: string;
+    /** One line per change, for the plan's "Project tooling" section. */
+    notes: string[];
+    /** Steps printed for the user, never applied. */
+    manual: string[];
+}
+/** A Prisma generator that still writes the client under src/ — tsc does not copy its .js files to dist/. */
+export declare const LEGACY_PRISMA_OUTPUT: RegExp;
+/** `start` (or any script) that runs TypeScript through tsx. */
+export declare const RUNS_TSX: RegExp;
+export declare const MANUAL_START_SNIPPET = "In package.json, run the compiled server in production (build first: `pnpm build`):\n  \"start\": \"node --enable-source-maps dist/src/server.js\",\n  \"start:dev\": \"tsx src/server.ts\"";
+export declare const MANUAL_PRISMA_LAYOUT_SNIPPET: string;
+/**
+ * What an existing app lacks of the production path: tsconfig.build.json, a
+ * `build` script, the Dockerfile and .dockerignore, and — for a Prisma app —
+ * a direct `@prisma/client-runtime-utils` dependency. Pure apart from reading
+ * the app's files. The Dockerfile is offered to pnpm apps only, and not
+ * while the Prisma client is still generated under src/.
+ */
+export declare function planProductionPath(dir: string, packageJsonText: string, pm?: string): Promise<ProductionPathPlan>;

package/dist/project/production.js

@@ -0,0 +1,74 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DOCKERFILE, DOCKERIGNORE, PRODUCTION_ENTRY } from '../stubs.js';
+import { BUILD_SCRIPT, PRISMA_IMPORTS, START_DEV_SCRIPT, START_SCRIPT, tsconfigBuildJson } from '../templates.js';
+import { mergePackageJson } from './package-json.js';
+/** A Prisma generator that still writes the client under src/ — tsc does not copy its .js files to dist/. */
+export const LEGACY_PRISMA_OUTPUT = /generator\s+\w+\s*\{[^}]*output\s*=\s*"\.\.\/src\/[^"]*"/;
+/** `start` (or any script) that runs TypeScript through tsx. */
+export const RUNS_TSX = /(^|[\s;&|])(?:npx\s+|pnpm\s+(?:exec\s+)?)?tsx(\s|$)|--import[= ]tsx\b/;
+async function readOptional(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+const exists = async (path) => (await readOptional(path)) !== undefined;
+export const MANUAL_START_SNIPPET = `In package.json, run the compiled server in production (build first: \`pnpm build\`):
+  "start": "${START_SCRIPT}",
+  "start:dev": "${START_DEV_SCRIPT}"`;
+export const MANUAL_PRISMA_LAYOUT_SNIPPET = `The Prisma client is generated under src/, where \`tsc\` does not copy its .js files — \`node ${PRODUCTION_ENTRY}\` cannot load it. Move it out of src/:
+  prisma/schema.prisma   output = "../generated/prisma"
+  package.json           "imports": ${JSON.stringify(PRISMA_IMPORTS)}
+  src/db.ts              import { PrismaClient } from '#db/client.js'
+  .gitignore             generated/   (instead of src/generated/)
+then \`pnpm db:generate\` and delete src/generated/. The Dockerfile is offered once this is done.`;
+/**
+ * What an existing app lacks of the production path: tsconfig.build.json, a
+ * `build` script, the Dockerfile and .dockerignore, and — for a Prisma app —
+ * a direct `@prisma/client-runtime-utils` dependency. Pure apart from reading
+ * the app's files. The Dockerfile is offered to pnpm apps only, and not
+ * while the Prisma client is still generated under src/.
+ */
+export async function planProductionPath(dir, packageJsonText, pm = 'pnpm') {
+    const pkg = JSON.parse(packageJsonText);
+    const files = {};
+    const notes = [];
+    const manual = [];
+    if (!(await exists(join(dir, 'tsconfig.build.json')))) {
+        files['tsconfig.build.json'] = tsconfigBuildJson();
+        notes.push('tsconfig.build.json: what `build` compiles (src/ → dist/, rootDir `.`)');
+    }
+    const schema = await readOptional(join(dir, 'prisma', 'schema.prisma'));
+    const prismaClient = pkg.dependencies?.['@prisma/client'];
+    const merged = mergePackageJson(packageJsonText, {
+        scripts: { build: BUILD_SCRIPT },
+        ...(schema !== undefined && prismaClient !== undefined
+            ? { dependencies: { '@prisma/client-runtime-utils': prismaClient } }
+            : {}),
+    });
+    for (const change of merged.changes) {
+        if (change.startsWith('scripts:'))
+            notes.push(`package.json: a "build" script (${BUILD_SCRIPT})`);
+        else
+            notes.push(`package.json: @prisma/client-runtime-utils ${prismaClient} — the generated client requires it by name; plain node cannot reach it as a transitive dependency`);
+    }
+    const start = pkg.scripts?.['start'];
+    if (start !== undefined && RUNS_TSX.test(start))
+        manual.push(MANUAL_START_SNIPPET);
+    const legacyPrisma = schema !== undefined && LEGACY_PRISMA_OUTPUT.test(schema);
+    if (legacyPrisma)
+        manual.push(MANUAL_PRISMA_LAYOUT_SNIPPET);
+    // The Dockerfile installs with pnpm (frozen pnpm-lock.yaml): offered to pnpm apps only.
+    else if (pm === 'pnpm' && !(await exists(join(dir, 'Dockerfile')))) {
+        files['Dockerfile'] = DOCKERFILE;
+        notes.push(`Dockerfile: build stage + plain-node runtime running ${PRODUCTION_ENTRY} (same as \`basalt publish dockerfile\`)`);
+    }
+    if (!(await exists(join(dir, '.dockerignore')))) {
+        files['.dockerignore'] = DOCKERIGNORE;
+        notes.push('.dockerignore: keeps .env, keys and node_modules out of the image');
+    }
+    return { files, packageJsonText: merged.text, notes, manual };
+}

package/dist/project/seed-script.d.ts

@@ -0,0 +1,18 @@
+import type { PackageJson } from './package-json.js';
+/**
+ * The `db:seed` script create-basalt 1.8.0–1.11.0 generated for `--prisma`
+ * apps: `tsx prisma/seed.ts` loads no .env, so on a fresh app it fails in
+ * src/env.ts (`ENV_INVALID`: database URL / app secret missing) unless the
+ * variables are exported. `prisma db seed` goes through prisma.config.ts,
+ * which loads .env and runs the `migrations.seed` command it declares.
+ *
+ * Only the exact old template is matched: a customised script is the app's.
+ * Nothing here rewrites package.json — `doctor` reports it and `update`
+ * prints the replacement.
+ */
+export declare const LEGACY_DB_SEED: RegExp;
+/**
+ * The fix for an old `db:seed` script, as printed lines; undefined when the
+ * app does not have the old script (or no prisma.config.ts to load .env).
+ */
+export declare function legacySeedScriptFix(pkg: PackageJson, prismaConfig: string | undefined): string | undefined;

package/dist/project/seed-script.js

@@ -0,0 +1,32 @@
+import { DB_SEED_SCRIPT } from '../templates.js';
+/**
+ * The `db:seed` script create-basalt 1.8.0–1.11.0 generated for `--prisma`
+ * apps: `tsx prisma/seed.ts` loads no .env, so on a fresh app it fails in
+ * src/env.ts (`ENV_INVALID`: database URL / app secret missing) unless the
+ * variables are exported. `prisma db seed` goes through prisma.config.ts,
+ * which loads .env and runs the `migrations.seed` command it declares.
+ *
+ * Only the exact old template is matched: a customised script is the app's.
+ * Nothing here rewrites package.json — `doctor` reports it and `update`
+ * prints the replacement.
+ */
+export const LEGACY_DB_SEED = /^\s*tsx\s+(?:\.\/)?prisma\/seed\.ts\s*$/;
+/** Whether prisma.config.ts declares a seed command (`migrations: { seed: … }`). */
+const DECLARES_SEED = /migrations\s*:\s*\{[^}]*\bseed\s*:/;
+/**
+ * The fix for an old `db:seed` script, as printed lines; undefined when the
+ * app does not have the old script (or no prisma.config.ts to load .env).
+ */
+export function legacySeedScriptFix(pkg, prismaConfig) {
+    const script = pkg.scripts?.['db:seed'];
+    if (script === undefined || prismaConfig === undefined || !LEGACY_DB_SEED.test(script))
+        return undefined;
+    const lines = [
+        `\`db:seed\` runs "${script}", which does not load .env — it fails with ENV_INVALID unless the variables are exported. Run it through Prisma (prisma.config.ts loads .env):`,
+        `  package.json       "db:seed": "${DB_SEED_SCRIPT}"`,
+    ];
+    if (!DECLARES_SEED.test(prismaConfig)) {
+        lines.push(`  prisma.config.ts   migrations: { seed: '${script.trim()}' },   (inside defineConfig)`);
+    }
+    return lines.join('\n');
+}

package/dist/project/update.js

@@ -4,6 +4,8 @@ import { binStatus, hasProjectCommands, manualBinSnippet, patchBasaltBin } from
 import { devEntryStatus, MANUAL_DEV_SNIPPET, patchDevEntry, patchEnvExample } from '../dev-entry.js';
 import { alwaysLatest, lookupLatestVersions, minimumReleaseAgeMinutes, } from '../latest-versions.js';
 import { BASALT_PROJECT_SCRIPT } from '../templates.js';
+import { planProductionPath } from './production.js';
+import { legacySeedScriptFix } from './seed-script.js';
 import { extendManifest, MANIFEST_PATH, serializeManifest } from './manifest.js';
 import { DEPENDENCY_SECTIONS, mergePackageJson, setDependencyRange, } from './package-json.js';
 import { table } from './term.js';
@@ -228,6 +230,23 @@ export async function planUpdate(ctx, options = {}) {
             patched['.env.example'] = exampleAfter;
             toolingNotes.push('.env.example: header now says dev/CLI load .env automatically and `start` does not');
         }
+        // The production path (BK-026): tsconfig.build.json, a `build` script, the
+        // Dockerfile — offered when missing, never overwriting what the app has.
+        const production = await planProductionPath(ctx.dir, files['package.json']?.after ?? ctx.packageJsonText, ctx.pm);
+        if (production.packageJsonText !== (files['package.json']?.after ?? ctx.packageJsonText)) {
+            files['package.json'] = { before: ctx.packageJsonText, after: production.packageJsonText };
+        }
+        for (const [path, content] of Object.entries(production.files)) {
+            files[path] = { before: undefined, after: content };
+            patched[path] = content;
+        }
+        toolingNotes.push(...production.notes);
+        manual.push(...production.manual);
+        // db:seed from create-basalt 1.8–1.11 does not load .env: printed, never
+        // rewritten — package.json scripts are the app's.
+        const seedFix = legacySeedScriptFix(ctx.packageJson, await readOptional(join(ctx.dir, 'prisma.config.ts')));
+        if (seedFix !== undefined)
+            manual.push(seedFix);
         if (ctx.manifest && Object.keys(patched).length > 0) {
             files[MANIFEST_PATH] = {
                 before: serializeManifest(ctx.manifest),

package/dist/stubs.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The production stubs `basalt publish` copies into an app — the SINGLE source
+ * of truth. create-basalt ships the same files in every new scaffold and offers
+ * them from `create-basalt update`: its build copies this file verbatim to
+ * `packages/create-app/src/stubs.ts` (scripts/sync-stubs.mjs), and a test there
+ * fails if the copy drifts. Keep this module free of imports for that reason.
+ *
+ * The layout these stubs assume is the create-basalt scaffold's (BK-026):
+ * `pnpm build` runs `tsc -p tsconfig.build.json` (rootDir `.`, outDir `dist`),
+ * so `src/server.ts` compiles to {@link PRODUCTION_ENTRY}; `pnpm start` runs it
+ * with plain `node` — no tsx, no TypeScript at runtime. A Prisma client, when
+ * there is one, is generated OUTSIDE `src/` (`generated/prisma`) and imported
+ * through the package.json `imports` alias `#db/*`, so it resolves the same
+ * from `src/` (tsx) and from `dist/src/` (node).
+ */
+/** The compiled server entry the Dockerfile runs and the scaffold's `start` script points at. */
+export declare const PRODUCTION_ENTRY = "dist/src/server.js";
+/** Multi-stage production image: build with the dev toolchain, run on plain node as a non-root user. */
+export declare const DOCKERFILE = "# syntax=docker/dockerfile:1\n# Production image for a Basalt app (the create-basalt layout): `pnpm build`\n# compiles src/ to dist/ and the image runs dist/src/server.js on plain\n# node \u2014 no tsx, no TypeScript at runtime.\n#\n#   docker build -t my-app .\n#   docker run -p 3000:3000 -e APP_SECRET=\u2026 -e DATABASE_URL=\u2026 my-app\n#\n# Configuration comes from the environment (nothing loads .env here, and\n# .dockerignore keeps it out of the image). Database migrations are NOT run\n# by the image: apply them before rolling out (`pnpm db:deploy` in CI).\n#\n# Installs with pnpm from pnpm-lock.yaml. An app on npm/yarn/bun replaces the\n# pnpm install / exec / run / prune lines with its own package manager's.\nARG NODE_VERSION=22\nARG PNPM_VERSION=11\n\nFROM node:${NODE_VERSION}-slim AS build\nARG PNPM_VERSION\n# Non-interactive pnpm: without it `pnpm prune` in a workspace (a --ui app's\n# web/) aborts with ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY.\nENV CI=true\nWORKDIR /app\nRUN npm install -g pnpm@${PNPM_VERSION}\nCOPY . .\n# Full install: the build needs the devDependencies (typescript, prisma).\nRUN pnpm install --frozen-lockfile\n# The Prisma client (when the app has a schema) is generated into ./generated.\nRUN if [ -f prisma/schema.prisma ]; then pnpm exec prisma generate; fi && mkdir -p generated\nRUN pnpm run build\n# Drop the devDependencies (tsx, typescript, prisma CLI, generators, the AI\n# bridge): none of them may ship. --ignore-scripts keeps the app's postinstall\n# (`prisma generate`, a dev tool) from running again.\nRUN pnpm prune --prod --ignore-scripts\n\nFROM node:${NODE_VERSION}-slim AS run\nENV NODE_ENV=production\nENV PORT=3000\n# Path the HEALTHCHECK probes: the scaffold's /health route by default; set\n# /readyz when the app registers healthPlugin().\nENV HEALTHCHECK_PATH=/health\nWORKDIR /app\nCOPY --from=build --chown=node:node /app/package.json ./package.json\nCOPY --from=build --chown=node:node /app/node_modules ./node_modules\nCOPY --from=build --chown=node:node /app/generated ./generated\nCOPY --from=build --chown=node:node /app/dist ./dist\nUSER node\nEXPOSE 3000\nHEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \\\n  CMD node -e \"fetch('http://127.0.0.1:' + (process.env.PORT || 3000) + process.env.HEALTHCHECK_PATH).then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))\"\nCMD [\"node\", \"--enable-source-maps\", \"dist/src/server.js\"]\n";
+/**
+ * Published with the Dockerfile: its \`COPY . .\` would otherwise bake \`.env\`,
+ * private keys and VCS metadata into an image layer. Every secret rule is
+ * \`**\/\`-prefixed: .dockerignore patterns are anchored at the context root, so
+ * a bare \`.env\` or \`*.pem\` would still let \`prisma/.env\` or
+ * \`certs/server.key\` through. \`dist\` is rebuilt inside the image.
+ */
+export declare const DOCKERIGNORE = "**/.env\n**/.env.*\n!**/.env.example\n**/.npmrc\n**/.git\n**/node_modules\n**/coverage\n**/*.log\n**/*.pem\n**/*.key\n**/*.p12\n**/*.pfx\n**/.DS_Store\ndist\n";
+/** GitHub Actions CI: install, typecheck, build (the production path), test. */
+export declare const CI_WORKFLOW = "name: ci\non:\n  push: { branches: [main] }\n  pull_request:\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      # Drop `with: version` if package.json declares a packageManager.\n      - uses: pnpm/action-setup@v4\n        with: { version: 11 }\n      - uses: actions/setup-node@v4\n        with: { node-version: 22, cache: pnpm }\n      - run: pnpm install --frozen-lockfile\n      - run: pnpm run typecheck\n      - run: pnpm run build\n      - run: pnpm run test\n";
+export declare const EDITORCONFIG = "root = true\n\n[*]\ncharset = utf-8\nend_of_line = lf\ninsert_final_newline = true\nindent_style = space\nindent_size = 2\ntrim_trailing_whitespace = true\n";

package/dist/stubs.js

@@ -0,0 +1,123 @@
+// GENERATED by scripts/sync-stubs.mjs from packages/cli/src/stubs.ts (runs before every build) — do not edit.
+/**
+ * The production stubs `basalt publish` copies into an app — the SINGLE source
+ * of truth. create-basalt ships the same files in every new scaffold and offers
+ * them from `create-basalt update`: its build copies this file verbatim to
+ * `packages/create-app/src/stubs.ts` (scripts/sync-stubs.mjs), and a test there
+ * fails if the copy drifts. Keep this module free of imports for that reason.
+ *
+ * The layout these stubs assume is the create-basalt scaffold's (BK-026):
+ * `pnpm build` runs `tsc -p tsconfig.build.json` (rootDir `.`, outDir `dist`),
+ * so `src/server.ts` compiles to {@link PRODUCTION_ENTRY}; `pnpm start` runs it
+ * with plain `node` — no tsx, no TypeScript at runtime. A Prisma client, when
+ * there is one, is generated OUTSIDE `src/` (`generated/prisma`) and imported
+ * through the package.json `imports` alias `#db/*`, so it resolves the same
+ * from `src/` (tsx) and from `dist/src/` (node).
+ */
+/** The compiled server entry the Dockerfile runs and the scaffold's `start` script points at. */
+export const PRODUCTION_ENTRY = 'dist/src/server.js';
+/** Multi-stage production image: build with the dev toolchain, run on plain node as a non-root user. */
+export const DOCKERFILE = `# syntax=docker/dockerfile:1
+# Production image for a Basalt app (the create-basalt layout): \`pnpm build\`
+# compiles src/ to dist/ and the image runs ${PRODUCTION_ENTRY} on plain
+# node — no tsx, no TypeScript at runtime.
+#
+#   docker build -t my-app .
+#   docker run -p 3000:3000 -e APP_SECRET=… -e DATABASE_URL=… my-app
+#
+# Configuration comes from the environment (nothing loads .env here, and
+# .dockerignore keeps it out of the image). Database migrations are NOT run
+# by the image: apply them before rolling out (\`pnpm db:deploy\` in CI).
+#
+# Installs with pnpm from pnpm-lock.yaml. An app on npm/yarn/bun replaces the
+# pnpm install / exec / run / prune lines with its own package manager's.
+ARG NODE_VERSION=22
+ARG PNPM_VERSION=11
+
+FROM node:\${NODE_VERSION}-slim AS build
+ARG PNPM_VERSION
+# Non-interactive pnpm: without it \`pnpm prune\` in a workspace (a --ui app's
+# web/) aborts with ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY.
+ENV CI=true
+WORKDIR /app
+RUN npm install -g pnpm@\${PNPM_VERSION}
+COPY . .
+# Full install: the build needs the devDependencies (typescript, prisma).
+RUN pnpm install --frozen-lockfile
+# The Prisma client (when the app has a schema) is generated into ./generated.
+RUN if [ -f prisma/schema.prisma ]; then pnpm exec prisma generate; fi && mkdir -p generated
+RUN pnpm run build
+# Drop the devDependencies (tsx, typescript, prisma CLI, generators, the AI
+# bridge): none of them may ship. --ignore-scripts keeps the app's postinstall
+# (\`prisma generate\`, a dev tool) from running again.
+RUN pnpm prune --prod --ignore-scripts
+
+FROM node:\${NODE_VERSION}-slim AS run
+ENV NODE_ENV=production
+ENV PORT=3000
+# Path the HEALTHCHECK probes: the scaffold's /health route by default; set
+# /readyz when the app registers healthPlugin().
+ENV HEALTHCHECK_PATH=/health
+WORKDIR /app
+COPY --from=build --chown=node:node /app/package.json ./package.json
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/generated ./generated
+COPY --from=build --chown=node:node /app/dist ./dist
+USER node
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \\
+  CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT || 3000) + process.env.HEALTHCHECK_PATH).then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"
+CMD ["node", "--enable-source-maps", "${PRODUCTION_ENTRY}"]
+`;
+/**
+ * Published with the Dockerfile: its \`COPY . .\` would otherwise bake \`.env\`,
+ * private keys and VCS metadata into an image layer. Every secret rule is
+ * \`**\/\`-prefixed: .dockerignore patterns are anchored at the context root, so
+ * a bare \`.env\` or \`*.pem\` would still let \`prisma/.env\` or
+ * \`certs/server.key\` through. \`dist\` is rebuilt inside the image.
+ */
+export const DOCKERIGNORE = `**/.env
+**/.env.*
+!**/.env.example
+**/.npmrc
+**/.git
+**/node_modules
+**/coverage
+**/*.log
+**/*.pem
+**/*.key
+**/*.p12
+**/*.pfx
+**/.DS_Store
+dist
+`;
+/** GitHub Actions CI: install, typecheck, build (the production path), test. */
+export const CI_WORKFLOW = `name: ci
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Drop \`with: version\` if package.json declares a packageManager.
+      - uses: pnpm/action-setup@v4
+        with: { version: 11 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run typecheck
+      - run: pnpm run build
+      - run: pnpm run test
+`;
+export const EDITORCONFIG = `root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+`;

package/dist/templates.d.ts

@@ -33,6 +33,24 @@ export declare const versionOf: (pkg: string) => string;
  * unknown package so every emitted range lives in that single table.
  */
 export declare const thirdPartyVersionOf: (pkg: string) => string;
+/**
+ * The production path (BK-026): `build` compiles src/ with tsconfig.build.json
+ * (rootDir `.`, outDir `dist`) and `start` runs the result on plain node — the
+ * same entry the Dockerfile's CMD runs. `start:dev` keeps the old tsx start.
+ */
+export declare const BUILD_SCRIPT = "tsc -p tsconfig.build.json";
+/** The `db:seed` script of a `--prisma` scaffold with tenancy (prisma.config.ts loads .env, then runs `migrations.seed`). */
+export declare const DB_SEED_SCRIPT = "prisma db seed";
+export declare const START_SCRIPT = "node --enable-source-maps dist/src/server.js";
+export declare const START_DEV_SCRIPT = "tsx src/server.ts";
+/** The `start` script every create-basalt release before the production path wrote. */
+export declare const LEGACY_START_SCRIPT = "tsx src/server.ts";
+/**
+ * package.json `imports` alias for the generated Prisma client. It lives in
+ * ./generated/prisma — outside src/, so tsc never has to copy its .js files —
+ * and `#db/*` resolves to it from src/ (tsx, vitest) and dist/src/ (node) alike.
+ */
+export declare const PRISMA_IMPORTS: Readonly<Record<string, string>>;
 /** The root `basalt` script of an app without `--cli`: create-basalt's project commands. */
 export declare const BASALT_PROJECT_SCRIPT = "create-basalt --project";
 /** The root `dev:web` script of a `--ui` app (web/ is a pnpm workspace member). */
@@ -41,6 +59,15 @@ export declare const webDevScript: (options: Pick<ProjectOptions, 'name'>) => st
 export declare const enforcesMembership: (options: ProjectOptions) => boolean;
 export declare function packageJson(options: ProjectOptions): string;
 export declare function tsconfigJson(options: ProjectOptions): string;
+/**
+ * `tsconfig.build.json` — what `pnpm build` compiles: src/ only (tests and
+ * bin/ stay dev-only), emitted to dist/ with rootDir `.`, so src/server.ts
+ * becomes dist/src/server.js. Extends tsconfig.json, so the compiler options
+ * (and `pnpm typecheck`) never diverge.
+ */
+export declare function tsconfigBuildJson(): string;
+/** The production Dockerfile — the same file `basalt publish dockerfile` writes. */
+export declare function dockerfile(): string;
 export declare function envTs(options: ProjectOptions): string;
 /**
  * An app-specific env-var prefix derived from the project name
@@ -101,8 +128,9 @@ export declare function prismaConfigTs(options: ProjectOptions): string;
 export declare function dbTs(options: ProjectOptions): string;
 /**
  * `prisma/seed.ts` — creates the `demo` tenant the scaffolded resolvers expect
- * (`x-tenant-id: demo`, `demo.localhost`). Runs from `pnpm db:seed` and after
- * `prisma migrate dev` (prisma.config.ts declares it).
+ * (`x-tenant-id: demo`, `demo.localhost`). Runs from `pnpm db:seed`
+ * (`prisma db seed`, the command prisma.config.ts declares) — Prisma 7's
+ * `migrate dev` does not run it.
  */
 export declare function prismaSeedTs(options: ProjectOptions): string;
 export declare function appTest(options: ProjectOptions): string;
@@ -129,7 +157,9 @@ export declare function mcpJson(_options: ProjectOptions): string;
 export declare function dockerignore(): string;
 export declare function gitignore(options: ProjectOptions): string;
 /**
- * pnpm settings: esbuild's build script is required by tsx;
+ * pnpm settings: esbuild's build script is required by tsx; with --prisma,
+ * the Prisma CLI's build scripts (prisma, @prisma/engines) are approved too — pnpm 11 fails
+ * the install on an unapproved build;
  * msgpackr-extract (optional native accelerator via BullMQ) is declined —
  * msgpackr falls back to pure JS. With --ui, `web` is a workspace member so
  * its own dependencies resolve.

package/dist/templates.js

@@ -1,4 +1,5 @@
 import { THIRD_PARTY_VERSIONS } from './latest-versions.js';
+import { DOCKERFILE, DOCKERIGNORE, PRODUCTION_ENTRY } from './stubs.js';
 import { SCAFFOLD_VERSIONS } from './versions.js';
 export { basaltBin } from './bin-template.js';
 export { SCAFFOLD_VERSIONS } from './versions.js';
@@ -29,6 +30,24 @@ export const thirdPartyVersionOf = (pkg) => {
     }
     return range;
 };
+/**
+ * The production path (BK-026): `build` compiles src/ with tsconfig.build.json
+ * (rootDir `.`, outDir `dist`) and `start` runs the result on plain node — the
+ * same entry the Dockerfile's CMD runs. `start:dev` keeps the old tsx start.
+ */
+export const BUILD_SCRIPT = 'tsc -p tsconfig.build.json';
+/** The `db:seed` script of a `--prisma` scaffold with tenancy (prisma.config.ts loads .env, then runs `migrations.seed`). */
+export const DB_SEED_SCRIPT = 'prisma db seed';
+export const START_SCRIPT = `node --enable-source-maps ${PRODUCTION_ENTRY}`;
+export const START_DEV_SCRIPT = 'tsx src/server.ts';
+/** The `start` script every create-basalt release before the production path wrote. */
+export const LEGACY_START_SCRIPT = 'tsx src/server.ts';
+/**
+ * package.json `imports` alias for the generated Prisma client. It lives in
+ * ./generated/prisma — outside src/, so tsc never has to copy its .js files —
+ * and `#db/*` resolves to it from src/ (tsx, vitest) and dist/src/ (node) alike.
+ */
+export const PRISMA_IMPORTS = { '#db/*': './generated/prisma/*' };
 /** The root `basalt` script of an app without `--cli`: create-basalt's project commands. */
 export const BASALT_PROJECT_SCRIPT = 'create-basalt --project';
 /** The root `dev:web` script of a `--ui` app (web/ is a pnpm workspace member). */
@@ -75,7 +94,11 @@ export function packageJson(options) {
     if (options.prisma) {
         // Prisma 7 talks to PostgreSQL through a driver adapter, so `pg` is a real
         // runtime dependency (see src/db.ts); the `prisma` CLI is dev-only.
-        for (const pkg of ['@prisma/adapter-pg', '@prisma/client', 'pg']) {
+        // @prisma/client-runtime-utils is required BY NAME from the generated
+        // client's runtime/ (./generated/prisma/runtime/client.js). Under pnpm it is
+        // only a transitive dependency of @prisma/client, out of reach of plain
+        // `node` — so the app declares it directly (BK-026).
+        for (const pkg of ['@prisma/adapter-pg', '@prisma/client', '@prisma/client-runtime-utils', 'pg']) {
             dependencies[pkg] = thirdPartyVersionOf(pkg);
         }
     }
@@ -108,11 +131,15 @@ export function packageJson(options) {
         version: '0.1.0',
         private: true,
         type: 'module',
+        ...(options.prisma ? { imports: PRISMA_IMPORTS } : {}),
         scripts: {
             // dev opts into NODE_ENV=development (src/dev.ts); start does not, so an
             // unset NODE_ENV counts as production and secrets are required.
             dev: 'tsx watch src/dev.ts',
-            start: 'tsx src/server.ts',
+            // Production: compile once, run on plain node (no tsx at runtime).
+            build: BUILD_SCRIPT,
+            start: START_SCRIPT,
+            'start:dev': START_DEV_SCRIPT,
             test: 'vitest run',
             typecheck: 'tsc --noEmit',
             // With --cli, bin/basalt.ts serves the generators AND hands the project
@@ -132,7 +159,11 @@ export function packageJson(options) {
                     // is deliberately no `db:push` script.
                     'db:migrate': 'prisma migrate dev',
                     'db:deploy': 'prisma migrate deploy',
-                    ...(options.tenancy ? { 'db:seed': 'tsx prisma/seed.ts' } : {}),
+                    // Through Prisma, not `tsx prisma/seed.ts`: prisma.config.ts loads
+                    // .env (the seed imports src/env.ts, which needs the database URL),
+                    // then runs the `migrations.seed` command it declares. Prisma 7's
+                    // `migrate dev` no longer seeds on its own.
+                    ...(options.tenancy ? { 'db:seed': DB_SEED_SCRIPT } : {}),
                 }
                 : {}),
         },
@@ -153,12 +184,34 @@ export function tsconfigJson(options) {
             noEmit: true,
             types: ['node'],
         },
-        // The generated Prisma client lives under src/generated (git-ignored, and
-        // re-created by `prisma generate`); the seed script under prisma/ is
-        // type-checked too.
+        // The generated Prisma client lives in ./generated (git-ignored,
+        // re-created by `prisma generate`, reached through the `#db/*` import
+        // alias); the seed script under prisma/ is type-checked too.
         include: ['src', 'tests', ...(options.prisma && options.tenancy ? ['prisma/seed.ts'] : [])],
     }, null, 2)}\n`;
 }
+/**
+ * `tsconfig.build.json` — what `pnpm build` compiles: src/ only (tests and
+ * bin/ stay dev-only), emitted to dist/ with rootDir `.`, so src/server.ts
+ * becomes dist/src/server.js. Extends tsconfig.json, so the compiler options
+ * (and `pnpm typecheck`) never diverge.
+ */
+export function tsconfigBuildJson() {
+    return `${JSON.stringify({
+        extends: './tsconfig.json',
+        compilerOptions: {
+            noEmit: false,
+            rootDir: '.',
+            outDir: 'dist',
+            sourceMap: true,
+        },
+        include: ['src'],
+    }, null, 2)}\n`;
+}
+/** The production Dockerfile — the same file `basalt publish dockerfile` writes. */
+export function dockerfile() {
+    return DOCKERFILE;
+}
 export function envTs(options) {
     const prefix = envPrefix(options.name);
     return `import { defineEnv${options.auth ? ', secret' : ''} } from '@basaltkit/env'
@@ -534,7 +587,15 @@ import { env } from './env.js'
 const app = await buildApp({
   logLevel: env.LOG_LEVEL,
   pretty: env.NODE_ENV === 'development',
-}).boot()
+})
+  .boot()
+  .catch((error: unknown) => {
+    // A database failure diagnosed by @basaltkit/prisma (permission denied, not
+    // migrated, unreachable…) carries its one-line fix: print it above the stack.
+    const diagnosis = (error as { details?: { diagnosis?: { cause?: string; fix?: string } } } | null)?.details?.diagnosis
+    if (diagnosis) console.error('Cannot start: ' + diagnosis.cause + '\\nFix: ' + diagnosis.fix)
+    throw error
+  })
 
 const server = app.container.get(FASTIFY)
 await server.listen({ port: env.PORT, host: env.HOST })
@@ -594,9 +655,17 @@ const PRISMA_MODELS = {
 }
 
 model TenantDomain {
-  domain   String @id
-  tenantId String
-  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  domain            String    @id
+  tenantId          String
+  // Custom-domain verification (PrismaDomainStore). A row with a NULL token
+  // mirrors \`tenant.domains\` and is written by PrismaTenantSource; a row with a
+  // token is a CustomDomains claim, which the source never deletes, and which
+  // only resolves a request once \`verified\` is true.
+  verificationToken String?
+  verified          Boolean   @default(true)
+  createdAt         DateTime  @default(now())
+  verifiedAt        DateTime?
+  tenant            Tenant    @relation(fields: [tenantId], references: [id], onDelete: Cascade)
 
   @@index([tenantId])
   @@map("tenant_domains")
@@ -611,9 +680,11 @@ model TenantDomain {
 }
 
 model AuthSession {
-  id        String   @id
-  userId    String
-  expiresAt DateTime
+  id         String    @id
+  userId     String
+  expiresAt  DateTime
+  /// Last use, for the idle timeout (trackSessionActivity: true).
+  lastSeenAt DateTime?
 
   @@index([userId])
   @@map("auth_sessions")
@@ -792,7 +863,9 @@ export function prismaSchema(options) {
 
 generator client {
   provider = "prisma-client-js"
-  output   = "../src/generated/prisma"
+  // Outside src/ on purpose: src/db.ts imports it as \`#db/client.js\` (the
+  // package.json "imports" alias), which resolves from src/ and dist/src/ alike.
+  output   = "../generated/prisma"
 }
 
 datasource db {
@@ -840,7 +913,7 @@ try {
 export default defineConfig({
   schema: 'prisma/schema.prisma',${options.tenancy
         ? `
-  // Runs after \`prisma migrate dev\` / \`prisma migrate reset\`.
+  // Run by \`prisma db seed\` (\`pnpm db:seed\`), with the .env loaded above.
   migrations: { seed: 'tsx prisma/seed.ts' },`
         : ''}
   datasource: {
@@ -860,7 +933,9 @@ export default defineConfig({
  */
 export function dbTs(options) {
     return `import { PrismaPg } from '@prisma/adapter-pg'${options.tenancy ? `\nimport { tenancyExtension } from '@basaltkit/prisma'` : ''}
-import { PrismaClient } from './generated/prisma/client.js'
+// The generated client (./generated/prisma), through the package.json
+// "imports" alias — the same specifier works under tsx and from dist/.
+import { PrismaClient } from '#db/client.js'
 import { env } from './env.js'
 
 /**
@@ -896,8 +971,9 @@ export const db = prisma
 }
 /**
  * `prisma/seed.ts` — creates the `demo` tenant the scaffolded resolvers expect
- * (`x-tenant-id: demo`, `demo.localhost`). Runs from `pnpm db:seed` and after
- * `prisma migrate dev` (prisma.config.ts declares it).
+ * (`x-tenant-id: demo`, `demo.localhost`). Runs from `pnpm db:seed`
+ * (`prisma db seed`, the command prisma.config.ts declares) — Prisma 7's
+ * `migrate dev` does not run it.
  */
 export function prismaSeedTs(options) {
     return `import { prismaTenantSource } from '@basaltkit/tenancy-prisma'
@@ -984,7 +1060,8 @@ Included: ${features.join(' · ')}.
 pnpm install${options.prisma
         ? `
 # start PostgreSQL — .env points ${envPrefix(options.name)}_DATABASE_URL at localhost:5432 — then
-pnpm db:migrate # create the tables${options.tenancy ? ` (runs the seed too)` : ''}`
+pnpm db:migrate # create the tables${options.tenancy ? `
+pnpm db:seed    # the 'demo' tenant the resolvers expect` : ''}`
         : ''}
 pnpm dev        # API on http://localhost:3000
 pnpm test
@@ -998,11 +1075,11 @@ the models this app needs — the reference models of the \`@basaltkit/*-prisma\
 packages it uses, plus your own \`Project\` at the end.
 
 \`\`\`bash
-pnpm db:migrate     # prisma migrate dev  — change the schema, write a migration${options.tenancy
+pnpm db:migrate --name <change>  # prisma migrate dev — writes AND applies a migration (asks for a name without --name)${options.tenancy
             ? `
-pnpm db:seed        # the 'demo' tenant the resolvers expect (also run by db:migrate)`
+pnpm db:seed        # prisma db seed — the 'demo' tenant the resolvers expect`
             : ''}
-pnpm db:generate    # prisma generate — refresh src/generated/prisma (also runs on install)
+pnpm db:generate    # prisma generate — refresh generated/prisma after a schema change (also runs on install; migrate dev does not)
 pnpm db:deploy      # prisma migrate deploy — apply pending migrations in production
 \`\`\`
 
@@ -1044,7 +1121,7 @@ scaffold with \`--cli\` — \`pnpm basalt prisma:sync\` does the merge for you.)
 \`src/env.ts\` validates \`process.env\`. For development, ${options.cli ? '`pnpm dev` and `pnpm basalt` load' : '`pnpm dev` loads'} \`.env\`
 automatically — create-basalt wrote one for you: git-ignored, with local
 values${options.auth ? ' and a generated secret' : ''}. \`.env.example\` is its committed template.
-\`pnpm start\` (production, \`src/server.ts\`) loads **nothing**: there the
+\`pnpm start\` (production, \`${PRODUCTION_ENTRY}\`) loads **nothing**: there the
 variables come from the real environment (or \`node --env-file=.env\`).
 
 The variables are **app-prefixed**: \`${envPrefix(options.name)}_PORT\`,
@@ -1068,6 +1145,24 @@ To drop the fallback entirely (prefixed names only), write
 \`prefix: { value: '${envPrefix(options.name)}', fallback: false }\`. When in doubt about what
 your shell exports: \`env | grep DATABASE_URL\`.
 
+## Build & ship
+
+\`\`\`bash
+pnpm build          # tsc -p tsconfig.build.json → dist/ (src only)
+pnpm start          # node --enable-source-maps ${PRODUCTION_ENTRY} — no tsx at runtime
+pnpm start:dev      # the server from source with tsx, without building
+docker build -t ${options.name} .   # the Dockerfile: build stage + plain-node runtime
+\`\`\`
+
+\`pnpm start\` runs the compiled server, so build first. The \`Dockerfile\` (also
+what \`basalt publish dockerfile\` writes) installs, ${options.prisma ? 'generates the Prisma client, ' : ''}builds, drops the
+devDependencies and runs ${PRODUCTION_ENTRY} as the \`node\` user, with a
+\`HEALTHCHECK\` on \`/health\`. Pass the configuration as environment variables${options.prisma ? ', and apply migrations (\`pnpm db:deploy\`) before rolling out — the image does not run them' : ''}.${options.prisma
+        ? ` The Prisma client is generated into \`generated/prisma\` (outside \`src/\`) and
+imported as \`#db/client.js\` through the package.json \`imports\` alias, so the same
+import works under tsx and from \`dist/\`.`
+        : ''}
+
 ## Keeping it up to date
 
 \`\`\`bash
@@ -1177,20 +1272,7 @@ export function mcpJson(_options) {
  * `certs/server.key` through.
  */
 export function dockerignore() {
-    return `**/.env
-**/.env.*
-!**/.env.example
-**/.npmrc
-**/.git
-**/node_modules
-**/coverage
-**/*.log
-**/*.pem
-**/*.key
-**/*.p12
-**/*.pfx
-**/.DS_Store
-`;
+    return DOCKERIGNORE;
 }
 export function gitignore(options) {
     return `node_modules/
@@ -1201,12 +1283,14 @@ dist/
 *.log
 ${options.prisma
         ? `# Generated by \`prisma generate\` (runs on install) — never edit or commit it.
-src/generated/
+generated/
 `
         : ''}`;
 }
 /**
- * pnpm settings: esbuild's build script is required by tsx;
+ * pnpm settings: esbuild's build script is required by tsx; with --prisma,
+ * the Prisma CLI's build scripts (prisma, @prisma/engines) are approved too — pnpm 11 fails
+ * the install on an unapproved build;
  * msgpackr-extract (optional native accelerator via BullMQ) is declined —
  * msgpackr falls back to pure JS. With --ui, `web` is a workspace member so
  * its own dependencies resolve.
@@ -1224,7 +1308,13 @@ export function pnpmWorkspaceYaml(options) {
 `
         : ''}allowBuilds:
   esbuild: true
-  msgpackr-extract: false
+  msgpackr-extract: false${options.prisma
+        ? `
+  # The Prisma CLI's install scripts fetch its engines; pnpm 11 refuses to finish
+  # an install (ERR_PNPM_IGNORED_BUILDS) while a dependency's build is unapproved.
+  '@prisma/engines': true
+  prisma: true`
+        : ''}
 # @basaltkit/* releases in lockstep, often within hours — exclude the scope (and
 # create-basalt, which serves \`pnpm basalt update\`) from pnpm's minimumReleaseAge
 # policy so an update is never blocked on a fresh release.

package/dist/versions.js

@@ -4,26 +4,26 @@
 export const SCAFFOLD_VERSIONS = {
     '@basaltkit/admin': '^2.0.0',
     '@basaltkit/admin-shadcn': '^1.1.0',
-    '@basaltkit/ai-mcp': '^0.3.0',
-    '@basaltkit/auth': '^4.1.0',
-    '@basaltkit/auth-prisma': '^2.0.0',
-    '@basaltkit/cli': '^1.3.0',
+    '@basaltkit/ai-mcp': '^0.4.0',
+    '@basaltkit/auth': '^4.2.0',
+    '@basaltkit/auth-prisma': '^2.1.0',
+    '@basaltkit/cli': '^1.4.0',
     '@basaltkit/config': '^1.1.0',
-    '@basaltkit/core': '^1.5.0',
+    '@basaltkit/core': '^1.6.0',
     '@basaltkit/env': '^3.1.0',
     '@basaltkit/events': '^1.3.0',
-    '@basaltkit/fastify': '^2.5.0',
-    '@basaltkit/generator': '^1.5.0',
+    '@basaltkit/fastify': '^2.6.0',
+    '@basaltkit/generator': '^1.6.0',
     '@basaltkit/logger': '^1.3.0',
-    '@basaltkit/mcp': '^5.0.0',
-    '@basaltkit/prisma': '^3.0.0',
+    '@basaltkit/mcp': '^5.1.0',
+    '@basaltkit/prisma': '^3.1.0',
     '@basaltkit/sdk': '^2.1.0',
     '@basaltkit/subscriptions': '^5.0.0',
     '@basaltkit/subscriptions-prisma': '^3.0.0',
-    '@basaltkit/teams': '^4.0.0',
+    '@basaltkit/teams': '^4.1.0',
     '@basaltkit/teams-prisma': '^1.1.0',
-    '@basaltkit/tenancy': '^3.1.0',
-    '@basaltkit/tenancy-prisma': '^2.0.0',
+    '@basaltkit/tenancy': '^3.2.0',
+    '@basaltkit/tenancy-prisma': '^2.1.0',
     '@basaltkit/testing': '^2.0.0',
-    'create-basalt': '^1.11.0',
+    'create-basalt': '^1.12.0',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-basalt",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -23,33 +23,35 @@
   "devDependencies": {
     "@prisma/adapter-pg": "^7.10.0",
     "@prisma/client": "^7.10.0",
+    "@prisma/client-runtime-utils": "^7.10.0",
     "@types/node": "^26.6.1",
     "@types/pg": "^8.23.1",
     "pg": "^8.23.0",
     "prisma": "^7.10.0",
+    "tsx": "^4.23.13",
     "typescript": "^7.0.2",
     "vitest": "^5.0.1",
     "zod": "^4.6.5",
-    "@basaltkit/auth": "^4.1.0",
-    "@basaltkit/auth-prisma": "^2.0.0",
-    "@basaltkit/config": "^1.1.2",
-    "@basaltkit/cli": "^1.3.0",
-    "@basaltkit/core": "^1.5.0",
-    "@basaltkit/env": "^3.1.1",
+    "@basaltkit/auth": "^4.2.0",
+    "@basaltkit/auth-prisma": "^2.1.0",
+    "@basaltkit/cli": "^1.4.0",
+    "@basaltkit/core": "^1.6.0",
     "@basaltkit/events": "^1.3.0",
-    "@basaltkit/fastify": "^2.5.0",
-    "@basaltkit/generator": "^1.5.0",
+    "@basaltkit/fastify": "^2.6.0",
+    "@basaltkit/config": "^1.1.2",
+    "@basaltkit/generator": "^1.6.0",
     "@basaltkit/logger": "^1.3.0",
-    "@basaltkit/mcp": "^5.0.0",
-    "@basaltkit/prisma": "^3.0.0",
+    "@basaltkit/env": "^3.1.1",
+    "@basaltkit/mcp": "^5.1.0",
+    "@basaltkit/prisma": "^3.1.0",
     "@basaltkit/subscriptions": "^5.0.0",
     "@basaltkit/subscriptions-prisma": "^3.0.0",
-    "@basaltkit/teams": "^4.0.0",
+    "@basaltkit/teams": "^4.1.0",
+    "@basaltkit/tenancy": "^3.2.0",
     "@basaltkit/teams-prisma": "^1.1.0",
-    "@basaltkit/tenancy": "^3.1.0",
+    "@basaltkit/tenancy-prisma": "^2.1.0",
     "@basaltkit/tsconfig": "^0.24.0",
-    "@basaltkit/testing": "^2.0.3",
-    "@basaltkit/tenancy-prisma": "^2.0.0"
+    "@basaltkit/testing": "^2.0.3"
   },
   "publishConfig": {
     "access": "public"
@@ -71,8 +73,9 @@
     "boilerplate"
   ],
   "scripts": {
-    "build": "node scripts/sync-versions.mjs && tsc -p tsconfig.build.json",
+    "build": "node scripts/sync-versions.mjs && node scripts/sync-stubs.mjs && tsc -p tsconfig.build.json",
     "sync-versions": "node scripts/sync-versions.mjs",
+    "sync-stubs": "node scripts/sync-stubs.mjs",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }