create-basalt 1.10.0 → 1.12.0

package/dist/project/update.js

@@ -1,8 +1,11 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { binStatus, MANUAL_BIN_SNIPPET, patchBasaltBin } from '../bin-template.js';
+import { binStatus, hasProjectCommands, manualBinSnippet, patchBasaltBin } from '../bin-template.js';
+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';
@@ -194,22 +197,61 @@ export async function planUpdate(ctx, options = {}) {
                 }
             }
         }
-        // bin/basalt.ts from an earlier template: make it delegate the project commands.
+        // Template files from an earlier release: bring them to the current
+        // templates when untouched (known hash or the manifest's), else print the
+        // snippet. Patched files get their manifest hash refreshed.
+        const patched = {};
         const bin = await readOptional(join(ctx.dir, 'bin', 'basalt.ts'));
         const status = binStatus(bin, ctx.manifest?.files['bin/basalt.ts']);
         if (status === 'patchable' && bin !== undefined) {
             const after = patchBasaltBin(bin);
             files['bin/basalt.ts'] = { before: bin, after };
-            toolingNotes.push('bin/basalt.ts: unmodified template from an earlier release — gains update/add/doctor/info');
-            if (ctx.manifest) {
-                files[MANIFEST_PATH] = {
-                    before: serializeManifest(ctx.manifest),
-                    after: serializeManifest(extendManifest(ctx.manifest, ctx.options, { 'bin/basalt.ts': after })),
-                };
-            }
+            patched['bin/basalt.ts'] = after;
+            toolingNotes.push(`bin/basalt.ts: unmodified template from an earlier release — ${hasProjectCommands(bin) ? '' : 'gains update/add/doctor/info; '}loads .env for development, runs \`upgrade\` without booting the app, explains env errors`);
+        }
+        else if (status === 'modified' && bin !== undefined) {
+            manual.push(`bin/basalt.ts was customised, so it was not patched. To bring it up to date:\n${manualBinSnippet(bin)}`);
+        }
+        const dev = await readOptional(join(ctx.dir, 'src', 'dev.ts'));
+        const devStatus = devEntryStatus(dev, ctx.manifest?.files['src/dev.ts']);
+        if (devStatus === 'patchable' && dev !== undefined) {
+            const after = patchDevEntry();
+            files['src/dev.ts'] = { before: dev, after };
+            patched['src/dev.ts'] = after;
+            toolingNotes.push('src/dev.ts: unmodified template from an earlier release — `dev` loads .env (exported variables still win)');
+        }
+        else if (devStatus === 'modified') {
+            manual.push(`src/dev.ts was customised, so it was not patched. To load .env in development:\n${MANUAL_DEV_SNIPPET}`);
+        }
+        const example = await readOptional(join(ctx.dir, '.env.example'));
+        const exampleAfter = example === undefined ? undefined : patchEnvExample(example);
+        if (example !== undefined && exampleAfter !== undefined) {
+            files['.env.example'] = { before: example, after: exampleAfter };
+            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;
         }
-        else if (status === 'modified') {
-            manual.push(`bin/basalt.ts was customised, so it was not patched. To give it the project commands:\n${MANUAL_BIN_SNIPPET}`);
+        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),
+                after: serializeManifest(extendManifest(ctx.manifest, ctx.options, patched)),
+            };
         }
     }
     // Peer ranges of the framework versions we end up on vs the app's resulting ranges.

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
@@ -48,17 +75,33 @@ export declare function envTs(options: ProjectOptions): string;
  * (`DATABASE_URL`, …) other projects export too.
  */
 export declare function envPrefix(name: string): string;
+/**
+ * The opening lines of `.env.example`. Up to create-basalt 1.10 they read
+ * {@link LEGACY_ENV_EXAMPLE_LEAD} ("nothing loads this file"); `update`
+ * swaps that for this one in existing apps.
+ */
+export declare const ENV_EXAMPLE_LEAD = "# Development: copy this file to .env \u2014 `pnpm dev` and `pnpm basalt` load it\n# automatically (a new app already has one). `pnpm start` (production) does\n# NOT: there the variables come from the environment (or `node --env-file`).";
+export declare const LEGACY_ENV_EXAMPLE_LEAD = "# Nothing loads this file for you: copy it to .env and start with\n# `node --env-file=.env` / `tsx --env-file=.env`, or export the variables.";
 export declare function envExample(options: ProjectOptions): string;
+/**
+ * The `.env` a new app starts with (git-ignored, never in the manifest): the
+ * values of `.env.example` for local development plus — with auth — a freshly
+ * generated APP_SECRET, so `pnpm dev` works without a copy step.
+ */
+export declare function devEnvFile(options: ProjectOptions, appSecret: string): string;
 /** A PostgreSQL-safe database name derived from the project name. */
 export declare function databaseName(name: string): string;
 export declare function appTs(options: ProjectOptions): string;
 export declare function routesTs(options: ProjectOptions): string;
 export declare function serverTs(): string;
 /**
- * `pnpm dev` entrypoint. Opts into NODE_ENV=development (dev secret defaults,
- * pretty logs) unless NODE_ENV is already set, then starts the server. Kept out
- * of server.ts on purpose: `pnpm start` runs server.ts directly, where an unset
- * NODE_ENV counts as production and secrets are required (fail-closed).
+ * `pnpm dev` entrypoint. Loads `.env` (when present) with `node --env-file`
+ * semantics — an exported variable wins, the file only fills in what is
+ * missing — and opts into NODE_ENV=development (dev secret defaults, pretty
+ * logs) unless NODE_ENV is already set, then starts the server. Kept out of
+ * server.ts on purpose: `pnpm start` runs server.ts directly, where nothing
+ * loads `.env` (production configuration comes from the real environment) and
+ * an unset NODE_ENV counts as production, so secrets are required (fail-closed).
  */
 export declare function devTs(): string;
 /**
@@ -85,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;
@@ -113,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.