create-basalt 1.11.0 → 1.13.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` /
@@ -267,7 +273,11 @@ newest release **on the app's current major** (a newer major is listed as
 `minimumReleaseAge`, read from the project's `pnpm-workspace.yaml` when set) is
 left for later so the install cannot refuse it. When a framework release
 declares a peer range the app would not meet (say `zod ^5` while zod is held on
-4), the plan warns before anything is written.
+4), the plan warns before anything is written. When a framework release
+requires an `@basaltkit/*` peer the app does not list (`@basaltkit/testing` 3
+takes `@basaltkit/mailer`), the plan adds it at its latest version (in
+`dependencies` when a runtime dependency needs it, else `devDependencies`), or
+warns when it cannot; optional peers are never added.
 
 Both `package.json` and `web/package.json` are updated, **in place**: only the
 version strings change — order, indentation and range style (`^`, `~`, exact)
@@ -288,6 +298,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 +347,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
@@ -447,7 +470,7 @@ Detects the manager that invoked the command from `npm_config_user_agent` (or th
 | --- | --- |
 | `runProjectCommand(argv, deps)` | Runs `update`/`add`/`doctor`/`info` and returns the exit code; every side effect (output, prompts, package-manager runs, registry fetch, codemods) is injected through `deps` |
 | `loadProject(dir, pm?)` | Reads an app: package.json (+ `web/`), manifest, detected features and package manager. Throws `NotABasaltAppError` |
-| `planUpdate(ctx, { major?, only?, tooling?, registry? })` | The update plan — entries, the full before/after of every file, tooling, warnings, framework majors. Writes nothing |
+| `planUpdate(ctx, { major?, only?, tooling?, registry? })` | The update plan — entries, the full before/after of every file, tooling, warnings, framework majors, required peers it adds (`addedPeers`). Writes nothing |
 | `planAdd(ctx, feature, { force?, resolveLatest?, registry? })` | The add plan — created/merged/skipped files and manual steps. Writes nothing |
 | `runDoctor(ctx, options)` | Doctor findings (`{ level: 'ok' \| 'info' \| 'warn' \| 'error', area, message }`) |
 | `MANIFEST_PATH`, `readManifest(dir)`, `hashContent(text)` | The scaffold manifest |

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.d.ts

@@ -114,6 +114,8 @@ export interface LatestInfo {
     latest?: string;
     /** `peerDependencies` declared by that latest version. */
     peers: Record<string, string>;
+    /** The peers its `peerDependenciesMeta` marks optional (absent: none). */
+    optionalPeers?: string[];
     /**
      * Release age of `latest` against the window: `mature` (provably older, or
      * not probed), `recent` (inside the window) or `unknown` (could not prove it).

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',
@@ -152,6 +153,15 @@ function peersOf(body) {
     }
     return peers;
 }
+/** The peers `peerDependenciesMeta` marks `optional: true`. */
+function optionalPeersOf(body) {
+    const raw = body?.peerDependenciesMeta;
+    if (!raw || typeof raw !== 'object')
+        return [];
+    return Object.entries(raw)
+        .filter(([, meta]) => typeof meta === 'object' && meta !== null && meta.optional === true)
+        .map(([name]) => name);
+}
 async function lookupLatest(fetchImpl, registry, name, signal) {
     try {
         const response = await fetchImpl(latestUrl(registry, name), {
@@ -164,7 +174,9 @@ async function lookupLatest(fetchImpl, registry, name, signal) {
             return 'miss';
         const body = (await response.json());
         const version = body?.version;
-        return typeof version === 'string' && STABLE_SEMVER.test(version) ? { version, peers: peersOf(body) } : 'miss';
+        return typeof version === 'string' && STABLE_SEMVER.test(version)
+            ? { version, peers: peersOf(body), optionalPeers: optionalPeersOf(body) }
+            : 'miss';
     }
     catch {
         // Network error, per-request timeout, or malformed JSON.
@@ -222,7 +234,7 @@ export async function lookupLatestVersions(names, shouldProbe, options = {}) {
                 const age = windowMs === 0 || !shouldProbe(name, found.version)
                     ? 'mature'
                     : await probeAge(fetchImpl, registry, name, windowMs, now, AbortSignal.any([AbortSignal.timeout(timeoutMs), overall.signal]));
-                results.set(name, { latest: found.version, peers: found.peers, age });
+                results.set(name, { latest: found.version, peers: found.peers, optionalPeers: found.optionalPeers, age });
             }
         };
         const pool = Math.max(1, Math.min(options.concurrency ?? CONCURRENCY, names.length));

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.d.ts

@@ -76,6 +76,17 @@ export interface UpdatePlan {
         to: string;
         changelog: string;
     }[];
+    /**
+     * Required `@basaltkit/*` peers of the framework releases the app ends up on
+     * that its package.json did not list (testing 3 takes mailer): added at their
+     * latest version, in `dependencies` when a runtime dependency needs them.
+     */
+    addedPeers: {
+        name: string;
+        range: string;
+        section: 'dependencies' | 'devDependencies';
+        requiredBy: string[];
+    }[];
     registry: string;
 }
 export interface UpdateOptions {

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),
@@ -258,6 +277,50 @@ export async function planUpdate(ctx, options = {}) {
             }
         }
     }
+    // A required @basaltkit peer the app never declared: pnpm and npm may
+    // auto-install it, but yarn PnP, `auto-install-peers=false` or
+    // `--legacy-peer-deps` do not, and `doctor` checks installed versions, not
+    // the manifest. Add it at its latest version; when that is impossible
+    // (registry, release-age window, out of range), say so.
+    const declared = new Set(entries.filter((entry) => entry.file === 'package.json').map((entry) => entry.name));
+    const missing = new Map();
+    for (const entry of entries) {
+        if (!entry.framework || (entry.status !== 'update' && entry.status !== 'current') || entry.file !== 'package.json')
+            continue;
+        const info = results.get(entry.name);
+        for (const [peer, wanted] of Object.entries(info?.peers ?? {})) {
+            if (!isFramework(peer) || declared.has(peer) || info?.optionalPeers?.includes(peer))
+                continue;
+            const prior = missing.get(peer);
+            const section = entry.section === 'dependencies' || prior?.section === 'dependencies' ? 'dependencies' : 'devDependencies';
+            const requiredBy = [...(prior?.requiredBy ?? []), `${entry.name}@${info?.latest}`];
+            missing.set(peer, { wanted: prior?.wanted ?? wanted, requiredBy: [...new Set(requiredBy)], section });
+        }
+    }
+    const addedPeers = [];
+    if (missing.size > 0) {
+        const peerLookup = await lookupLatestVersions([...missing.keys()].sort(), (name) => !exempt(name), {
+            ...options.registry,
+            minimumReleaseAge: window,
+        });
+        const additions = { dependencies: {}, devDependencies: {} };
+        for (const [peer, need] of missing) {
+            const found = peerLookup.results.get(peer);
+            if (found?.latest !== undefined && found.age === 'mature' && satisfies(found.latest, need.wanted) === true) {
+                const range = `^${found.latest}`;
+                additions[need.section][peer] = range;
+                addedPeers.push({ name: peer, range, section: need.section, requiredBy: need.requiredBy });
+            }
+            else {
+                warnings.push(`${need.requiredBy.join(', ')} requires ${peer} ${need.wanted}, which package.json does not list — add it (${ctx.pm} add ${need.section === 'devDependencies' ? '-D ' : ''}${peer})`);
+            }
+        }
+        if (addedPeers.length > 0) {
+            const merged = mergePackageJson(files['package.json']?.after ?? ctx.packageJsonText, additions);
+            if (merged.changes.length > 0)
+                files['package.json'] = { before: ctx.packageJsonText, after: merged.text };
+        }
+    }
     const failed = entries.filter((entry) => entry.status === 'failed').map((entry) => entry.name);
     if (failed.length > 0)
         warnings.push(`The registry did not answer for ${[...new Set(failed)].join(', ')} — left unchanged.`);
@@ -270,7 +333,7 @@ export async function planUpdate(ctx, options = {}) {
         changelog: changelogUrl(entry.name),
     }))
         .filter((major, i, all) => all.findIndex((other) => other.name === major.name) === i);
-    return { entries, updates, files, tooling: toolingNotes, manual, warnings, majors, registry };
+    return { entries, updates, files, tooling: toolingNotes, manual, warnings, majors, addedPeers, registry };
 }
 /** The plan as terminal lines: the update table, then notes, tooling, warnings and majors. */
 export function renderUpdatePlan(plan, colors) {
@@ -309,6 +372,12 @@ export function renderUpdatePlan(plan, colors) {
             lines.push(`  ${major.name} ${major.from} → ${major.to}: ${major.changelog}`);
         lines.push(`  Upgrade notes: ${DOCS_UPGRADING_URL}`);
     }
+    if (plan.addedPeers.length > 0) {
+        lines.push('', colors.bold('Required peers the app did not list (added):'));
+        for (const peer of plan.addedPeers) {
+            lines.push(`  ${colors.cyan(peer.name)} ${peer.range} (${peer.section}) — required by ${peer.requiredBy.join(', ')}`);
+        }
+    }
     if (plan.tooling.length > 0) {
         lines.push('', colors.bold('Project tooling:'));
         for (const note of plan.tooling)

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";