create-basalt 1.10.0 → 1.12.0

package/dist/dev-entry.js

@@ -0,0 +1,49 @@
+import { hashContent } from './project/manifest.js';
+import { devTs, ENV_EXAMPLE_LEAD, LEGACY_ENV_EXAMPLE_LEAD } from './templates.js';
+/**
+ * `src/dev.ts` (the `pnpm dev` entrypoint) and the `.env.example` header across
+ * create-basalt releases. Up to 1.10, nothing loaded `.env`: `pnpm dev` booted
+ * without the variables the example told you to set. `update` brings untouched
+ * copies to the current templates; customised ones get the snippet instead.
+ */
+/** Hashes of every src/dev.ts an earlier create-basalt release generated (CRLF-insensitive). */
+export const LEGACY_DEV_HASHES = new Set([
+    // 2026-09-19 → create-basalt 1.10: NODE_ENV defaulted, no .env loading.
+    'sha256-f25f09fed1b36281a806e29f5aab139a1dda0c5fa898f7c4c71b6ac294326cb7',
+]);
+/** Marker proving a src/dev.ts already loads .env. */
+export const DEV_ENV_MARKER = 'process.loadEnvFile(';
+/** Where a src/dev.ts stands: loads .env already, an untouched old template, or user code. */
+export function devEntryStatus(content, manifestHash) {
+    if (content === undefined)
+        return 'absent';
+    if (content.includes(DEV_ENV_MARKER))
+        return 'current';
+    const hash = hashContent(content);
+    return LEGACY_DEV_HASHES.has(hash) || hash === manifestHash ? 'patchable' : 'modified';
+}
+/** The current src/dev.ts — what a patchable one becomes. */
+export const patchDevEntry = () => devTs();
+/** What to paste by hand into a customised src/dev.ts. */
+export const MANUAL_DEV_SNIPPET = `Paste this at the top of src/dev.ts, BEFORE the server is imported (keep that
+import dynamic — \`await import('./server.js')\` — so the variables are set first):
+
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+// Development loads .env (when present) like \`node --env-file=.env\`: a variable
+// already exported in your shell still wins, the file only fills in what is missing.
+const envFile = fileURLToPath(new URL('../.env', import.meta.url))
+if (existsSync(envFile)) process.loadEnvFile(envFile)
+`;
+/**
+ * `.env.example` with the old "nothing loads this file" lead swapped for the
+ * current one; undefined when the file does not start with the old lead (a
+ * newer or hand-written file is left alone — it is only comments).
+ */
+export function patchEnvExample(content) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith(`${LEGACY_ENV_EXAMPLE_LEAD}\n`))
+        return undefined;
+    return `${ENV_EXAMPLE_LEAD}${normalized.slice(LEGACY_ENV_EXAMPLE_LEAD.length)}`;
+}

package/dist/index.d.ts

@@ -68,6 +68,12 @@ export declare function resolveRunDefaults(input: {
 export declare function scaffoldFiles(options: ProjectOptions): Record<string, string>;
 /** Generates a ready-to-run Basalt app. Does not install dependencies. */
 export declare function createProject(input: CreateProjectInput): Promise<CreateProjectResult>;
+/**
+ * A random APP_SECRET for the development .env: 48 random bytes, base64url —
+ * redrawn in the (rare) case it happens to contain a word `secret()` rejects
+ * as a placeholder (`test`, `0000`, …).
+ */
+export declare function generateAppSecret(random?: (size: number) => Buffer): string;
 export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, DEFAULT_MINIMUM_RELEASE_AGE_MINUTES, describeResolution, resolveFileVersions, minimumReleaseAgeMinutes, resolveLatestVersions, registryUrl, type FreshVersion, type HeldBackVersion, type ResolveLatestOptions, type VersionResolution, } from './latest-versions.js';
 export { runProjectCommand, PROJECT_COMMANDS, isProjectCommand, type ProjectCommandDeps } from './project/run.js';
 export { planUpdate, type UpdatePlan, type UpdateEntry } from './project/update.js';

package/dist/index.js

@@ -1,7 +1,9 @@
+import { randomBytes } from 'node:crypto';
 import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { appTest, appTs, dbTs, 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';
 import { resolveFileVersions } from './latest-versions.js';
 export class TargetNotEmptyError extends Error {
@@ -41,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),
@@ -85,13 +89,30 @@ export async function createProject(input) {
     const files = scaffoldFiles(options);
     const versions = input.resolveLatest ? await resolveFileVersions(files, input.registry) : undefined;
     files[MANIFEST_PATH] = serializeManifest(createManifest(options, files));
+    // A ready-to-use .env for development, so `pnpm dev` / `pnpm basalt` boot
+    // without a copy step. Written after the manifest on purpose: it is
+    // git-ignored local state (with a generated secret), not a template file.
+    files['.env'] = devEnvFile(options, generateAppSecret());
     for (const [path, content] of Object.entries(files)) {
         const target = join(dir, path);
         await mkdir(dirname(target), { recursive: true });
-        await writeFile(target, content);
+        // .env holds a secret: owner-only, like `umask 077` would make it.
+        await writeFile(target, content, path === '.env' ? { mode: 0o600 } : undefined);
     }
     return { dir, files: Object.keys(files).sort(), options, ...(versions ? { versions } : {}) };
 }
+/**
+ * A random APP_SECRET for the development .env: 48 random bytes, base64url —
+ * redrawn in the (rare) case it happens to contain a word `secret()` rejects
+ * as a placeholder (`test`, `0000`, …).
+ */
+export function generateAppSecret(random = randomBytes) {
+    for (;;) {
+        const value = random(48).toString('base64url');
+        if (!INSECURE_SECRET.test(value))
+            return value;
+    }
+}
 export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, DEFAULT_MINIMUM_RELEASE_AGE_MINUTES, describeResolution, resolveFileVersions, minimumReleaseAgeMinutes, resolveLatestVersions, registryUrl, } from './latest-versions.js';
 export { runProjectCommand, PROJECT_COMMANDS, isProjectCommand } from './project/run.js';
 export { planUpdate } from './project/update.js';

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;
 }
@@ -23,6 +23,8 @@ export interface DoctorOptions {
     /** `<pm> --version` (injected; undefined when unavailable). */
     pmVersion?: string;
 }
+/** Mirrors the placeholder check of `secret()` in @basaltkit/env (src/secret.ts). */
+export declare const INSECURE_SECRET: RegExp;
 /** The Node range every @basaltkit package declares. */
 export declare const BASALT_NODE_RANGE = ">=22.5.0";
 /** Installed version of `name` as the app resolves it (top-level node_modules). */
@@ -31,6 +33,14 @@ export declare function installedVersion(dir: string, name: string): Promise<str
 export declare function parseDotenv(text: string): Record<string, string>;
 /** The env prefix src/env.ts passes to defineEnv (`prefix: 'X'` or `prefix: { value: 'X' … }`). */
 export declare function envPrefixOf(envTs: string | undefined, name: string): string | undefined;
+/**
+ * The variables src/env.ts requires: keys of the schema object passed to
+ * `defineEnv` whose declaration has no `.default(`, `.optional(`, `.catch(` or
+ * `.nullish(` (`secret()` is checked separately — it has a dev default).
+ * A light scan, not a parser: comments and strings are skipped, nesting is
+ * tracked. Undefined when there is no `defineEnv({ … })` to read.
+ */
+export declare function requiredEnvKeys(envTs: string | undefined): string[] | undefined;
 export declare function runDoctor(ctx: ProjectContext, options?: DoctorOptions): Promise<DoctorFinding[]>;
 export declare function renderFindings(findings: readonly DoctorFinding[], colors: Colors): string[];
 /** `create-basalt info`: a paste-able versions summary for bug reports. */

package/dist/project/doctor.js

@@ -1,15 +1,19 @@
 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). */
-const INSECURE_SECRET = /change.?me|changeme|placeholder|example|secret|password|default|test|xxxx+|0000+/i;
+export const INSECURE_SECRET = /change.?me|changeme|placeholder|example|secret|password|default|test|xxxx+|0000+/i;
 /** The Node range every @basaltkit package declares. */
 export const BASALT_NODE_RANGE = '>=22.5.0';
 async function readJson(path) {
@@ -87,6 +91,72 @@ export function envPrefixOf(envTs, name) {
     const match = /prefix:\s*(?:\{\s*value:\s*)?['"]([A-Z0-9_]+)['"]/.exec(envTs);
     return match ? match[1] : /prefix:/.test(envTs) ? undefined : '';
 }
+/**
+ * The variables src/env.ts requires: keys of the schema object passed to
+ * `defineEnv` whose declaration has no `.default(`, `.optional(`, `.catch(` or
+ * `.nullish(` (`secret()` is checked separately — it has a dev default).
+ * A light scan, not a parser: comments and strings are skipped, nesting is
+ * tracked. Undefined when there is no `defineEnv({ … })` to read.
+ */
+export function requiredEnvKeys(envTs) {
+    if (envTs === undefined)
+        return undefined;
+    const call = envTs.indexOf('defineEnv(');
+    const open = call < 0 ? -1 : envTs.indexOf('{', call);
+    if (open < 0)
+        return undefined;
+    const entries = [];
+    let depth = 0;
+    let current;
+    for (let i = open; i < envTs.length; i++) {
+        const char = envTs[i];
+        if (char === '/' && envTs[i + 1] === '/') {
+            const end = envTs.indexOf('\n', i);
+            i = end < 0 ? envTs.length : end - 1;
+            continue;
+        }
+        if (char === '/' && envTs[i + 1] === '*') {
+            const end = envTs.indexOf('*/', i + 2);
+            i = end < 0 ? envTs.length : end + 1;
+            continue;
+        }
+        if (char === "'" || char === '"' || char === '`') {
+            let end = i + 1;
+            while (end < envTs.length && envTs[end] !== char)
+                end += envTs[end] === '\\' ? 2 : 1;
+            if (current)
+                current.body += envTs.slice(i, end + 1);
+            i = end;
+            continue;
+        }
+        if (char === '{' || char === '(' || char === '[')
+            depth++;
+        else if (char === '}' || char === ')' || char === ']') {
+            depth--;
+            if (depth === 0)
+                break;
+        }
+        if (depth === 1 && (char === ',' || char === '{')) {
+            if (current)
+                entries.push(current);
+            current = undefined;
+            const start = skipTrivia(envTs, i + 1);
+            const match = /^([A-Z][A-Z0-9_]*)\s*:/.exec(envTs.slice(start, start + 200));
+            if (match) {
+                current = { key: match[1], body: '' };
+                i = start + match[0].length - 1;
+            }
+            continue;
+        }
+        if (current)
+            current.body += char;
+    }
+    if (current)
+        entries.push(current);
+    return entries
+        .filter(({ body }) => !/\.(default|optional|catch|nullish)\(|\bsecret\(/.test(body))
+        .map(({ key }) => key);
+}
 export async function runDoctor(ctx, options = {}) {
     const findings = [];
     const push = (level, area, message) => {
@@ -203,8 +273,10 @@ export async function runDoctor(ctx, options = {}) {
     const envTs = await readText(join(dir, 'src', 'env.ts'));
     const dotenvText = await readText(join(dir, '.env'));
     const dotenv = dotenvText ? parseDotenv(dotenvText) : {};
-    if (dotenvText === undefined && existsSync(join(dir, '.env.example'))) {
-        push('info', 'env', 'No .env — copy .env.example to .env (and start with --env-file=.env) or export the variables.');
+    const exampleText = await readText(join(dir, '.env.example'));
+    const example = exampleText ? parseDotenv(exampleText) : {};
+    if (dotenvText === undefined && exampleText !== undefined) {
+        push('warn', 'env', 'No .env — `dev` and `basalt` load it for development: `cp .env.example .env` (or export the variables).');
     }
     const prefix = envPrefixOf(envTs, ctx.options.name);
     const lookup = (name) => {
@@ -237,12 +309,25 @@ export async function runDoctor(ctx, options = {}) {
             push('ok', 'env', `${label} is set (${secret.from}, ${secret.value.length} characters).`);
         }
     }
-    if (ctx.options.prisma) {
-        const url = lookup('DATABASE_URL');
-        if (!url)
-            push('warn', 'env', `${prefix ? `${prefix}_` : ''}DATABASE_URL is not set — the app does not boot without it.`);
-        else
-            push('ok', 'env', `${prefix ? `${prefix}_` : ''}DATABASE_URL is set (${url.from}).`);
+    // Required variables: declared in src/env.ts without a default (from the
+    // environment or .env, the way the dev entrypoints load it). Without a
+    // readable schema, a Prisma app still needs DATABASE_URL.
+    const required = requiredEnvKeys(envTs) ?? (ctx.options.prisma ? ['DATABASE_URL'] : []);
+    for (const name of required) {
+        const label = prefix ? `${prefix}_${name}` : name;
+        const found = lookup(name);
+        if (found) {
+            push('ok', 'env', `${label} is set (${found.from}).`);
+            continue;
+        }
+        const inExample = [label, name].some((key) => example[key] !== undefined && example[key] !== '');
+        const fix = dotenvText === undefined
+            ? exampleText !== undefined
+                ? `\`cp .env.example .env\`${inExample ? '' : ` and set ${label} in it`}`
+                : `create .env with ${label}=…`
+            : `set ${label} in .env${inExample ? ' (.env.example has an example value)' : ''}`;
+        const database = name === 'DATABASE_URL' && ctx.options.prisma ? ' — and start PostgreSQL where it points' : '';
+        push('error', 'env', `${label} is not set (environment or .env) — the app does not boot without it. Fix: ${fix}, or export it${database}.`);
     }
     // --- Prisma -------------------------------------------------------------------
     const schemaPath = join(dir, 'prisma', 'schema.prisma');
@@ -262,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) {
@@ -293,14 +381,68 @@ export async function runDoctor(ctx, options = {}) {
     // --- Project tooling -------------------------------------------------------------
     const bin = await readText(join(dir, 'bin', 'basalt.ts'));
     const status = binStatus(bin, ctx.manifest?.files['bin/basalt.ts']);
-    if (status === 'patchable')
-        push('warn', 'tooling', 'bin/basalt.ts predates the project commands — `npx create-basalt@latest update` patches it.');
-    if (status === 'modified')
-        push('info', 'tooling', 'bin/basalt.ts is customised and does not delegate update/add/doctor/info — see `create-basalt update` for the snippet.');
+    if (status === 'patchable') {
+        push('warn', 'tooling', 'bin/basalt.ts is an older template (no .env loading / pre-boot project commands) — `npx create-basalt@latest update` patches it.');
+    }
+    if (status === 'modified') {
+        push('info', 'tooling', 'bin/basalt.ts is customised and lacks the current preludes (project commands, .env loading, pre-boot `upgrade`) — see `create-basalt update` for the snippet.');
+    }
+    const dev = await readText(join(dir, 'src', 'dev.ts'));
+    const devStatus = devEntryStatus(dev, ctx.manifest?.files['src/dev.ts']);
+    if (devStatus === 'patchable')
+        push('warn', 'tooling', 'src/dev.ts does not load .env (older template) — `npx create-basalt@latest update` patches it.');
+    if (devStatus === 'modified')
+        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('✓'),
@@ -348,3 +490,23 @@ export async function projectInfo(ctx, options = {}) {
     }
     return lines;
 }
+/** Index of the first character at or after `from` that is not whitespace or a comment (linear scan). */
+function skipTrivia(source, from) {
+    let i = from;
+    while (i < source.length) {
+        const char = source[i];
+        if (char === ' ' || char === '\t' || char === '\n' || char === '\r')
+            i++;
+        else if (source.startsWith('//', i)) {
+            const end = source.indexOf('\n', i);
+            i = end === -1 ? source.length : end + 1;
+        }
+        else if (source.startsWith('/*', i)) {
+            const end = source.indexOf('*/', i + 2);
+            i = end === -1 ? source.length : end + 2;
+        }
+        else
+            break;
+    }
+    return i;
+}

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/run.js

@@ -47,7 +47,9 @@ present) to their latest published versions, with the scaffold's policy:
 Range style (^, ~, exact) and package.json formatting are preserved. Then it
 installs, runs the @basaltkit/cli upgrade codemods, and suggests typecheck+test.
 It also upgrades project tooling: an unmodified old bin/basalt.ts gains the
-project commands; create-basalt becomes a devDependency (pnpm basalt update).
+project commands, .env loading for development and a pre-boot \`upgrade\`; an
+unmodified src/dev.ts loads .env; the .env.example header is refreshed;
+create-basalt becomes a devDependency (pnpm basalt update).
 
 Options:
   --dry           Show the plan, write nothing
@@ -56,7 +58,8 @@ Options:
   --only=@basaltkit
                   Only the framework packages (and create-basalt)
   --no-install    Write package.json, skip the install (and the codemods)
-  --no-tooling    Leave bin/basalt.ts and the create-basalt devDependency alone
+  --no-tooling    Leave bin/basalt.ts, src/dev.ts, .env.example and the
+                  create-basalt devDependency alone
 ${COMMON_FLAGS}
 `,
     add: `Usage: create-basalt add <feature> [options]   (in an app: pnpm basalt add <feature>)
@@ -85,8 +88,9 @@ ${COMMON_FLAGS}
 
 Read-only health check: Node vs engines, package manager and lockfiles,
 installed vs declared versions, duplicated @basaltkit versions and unmet peer
-ranges, framework packages behind latest, the auth secret and DATABASE_URL
-(from the environment or .env), Prisma client/migrations, .mcp.json.
+ranges, framework packages behind latest, the required variables of src/env.ts
+and the auth secret (from the environment or .env), Prisma client/migrations,
+.mcp.json, and whether bin/basalt.ts / src/dev.ts are current.
 Exits 1 when an error is found; warnings alone exit 0.
 
 Options:

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');
+}