create-basalt 1.10.0 → 1.12.0

package/README.md

@@ -93,7 +93,7 @@ Usage: npm create basalt <name> [options]
 | `--no-auth` | auth **on** | Removes authentication (`@basaltkit/auth`, `APP_SECRET`, `/auth/*` routes) |
 | `--billing` | off | Includes subscriptions/plans (`@basaltkit/subscriptions`, example `free` and `pro` plans) |
 | `--ui` | off | Generates the `web/` frontend (React + shadcn via `@basaltkit/admin-shadcn` + `@basaltkit/sdk`). **Forces pnpm** — see note below |
-| `--cli` | off | Generates the `basalt` CLI (`bin/basalt.ts`, `pnpm basalt` script, `make:*` generators from `@basaltkit/generator`) |
+| `--no-cli` | CLI on | Skips the `basalt` CLI (by default every app gets it: `bin/basalt.ts`, the `pnpm basalt` script, `make:*` generators from `@basaltkit/generator`) |
 | `--mcp` | off | Exposes read-only routes as MCP tools (`@basaltkit/mcp`) over HTTP at `POST /mcp` — the overview and health endpoints are opted in via `meta.mcp` |
 | `--prisma` (alias `--db`) | off | Backs the app with PostgreSQL through Prisma: `prisma/schema.prisma`, `prisma.config.ts`, `src/db.ts`, the `@basaltkit/*-prisma` stores instead of the in-memory ones, a required `<APP>_DATABASE_URL`, the `db:*` scripts and `prismaPlugin({ assertMigrated: true })` — see *With `--prisma`* below |
 | `--install` | off | Installs dependencies at the end (with the detected/chosen manager) |
@@ -120,7 +120,7 @@ Behavior notes (faithful to the code):
 pnpm create basalt
 
 # Full project, no questions, with everything:
-pnpm create basalt my-app --billing --ui --cli --prisma --install --git
+pnpm create basalt my-app --billing --ui --prisma --install --git
 
 # Minimal API (no tenancy or auth), in another folder:
 npm create basalt service-api --no-tenancy --no-auth --dir=./apps/service-api
@@ -138,10 +138,14 @@ 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
-├── .env.example          # MY_APP_PORT, MY_APP_HOST, MY_APP_LOG_LEVEL, NODE_ENV (+ MY_APP_APP_SECRET with auth) + the --env-file precedence warning
+├── 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
 ├── README.md             # instructions adapted to the chosen options
 ├── pnpm-workspace.yaml   # esbuild allowBuilds, @basaltkit/* + create-basalt release-age exclusion (+ "web" member with --ui) + pnpm 11 notes
@@ -149,11 +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
+│   ├── 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` without `--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
 
@@ -185,11 +190,14 @@ the next restart.
 ```bash
 pnpm create basalt my-app --prisma
 cd my-app && pnpm install     # postinstall runs `prisma generate`
-cp .env.example .env          # point MY_APP_DATABASE_URL at your database
-pnpm db:migrate               # prisma migrate dev — creates the tables and seeds `demo`
+# .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
+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` /
@@ -201,9 +209,9 @@ the database and host instead of a `500` on the first request. In production:
 The generated `tests/app.test.ts` skips itself when no database is configured, so
 `pnpm test` stays green on a machine without PostgreSQL. To add another Basalt
 domain later, install its `@basaltkit/<domain>-prisma` package, run
-`pnpm basalt prisma:sync` (with `--cli`) and then `pnpm db:migrate`.
+`pnpm basalt prisma:sync` (unless `--no-cli`) and then `pnpm db:migrate`.
 
-### With `--cli`: the `basalt` command line
+### The `basalt` command line (default; `--no-cli` skips it)
 
 ```bash
 pnpm basalt list                    # available commands
@@ -215,7 +223,7 @@ With pnpm 11, every `pnpm <script>` and `pnpm exec` first verifies dependencies
 
 ## Project commands: update, add, doctor, info
 
-Run inside an existing Basalt app — any app, created with or without `--cli`,
+Run inside an existing Basalt app — any app, created with or without the CLI (`--no-cli`),
 by any create-basalt release:
 
 ```bash
@@ -235,7 +243,7 @@ field, then the lockfile), and output is colored unless `NO_COLOR` is set,
 `--no-color` is passed or stdout is not a terminal.
 
 **How `pnpm basalt <command>` reaches them.** New apps list `create-basalt` as a
-devDependency. Without `--cli` the `basalt` script is `create-basalt --project`;
+devDependency. With `--no-cli` the `basalt` script is `create-basalt --project`;
 with `--cli`, `bin/basalt.ts` handles `update`/`add`/`doctor`/`info` **before**
 importing anything of the app (they must work while the app is broken
 mid-upgrade) and runs the installed create-basalt — or `pnpm dlx` /
@@ -255,7 +263,7 @@ pnpm basalt update            # asks, writes, installs, runs the codemods
 | `--major` | Lets third-party packages cross a major too |
 | `--only=@basaltkit` | Only the framework packages (and `create-basalt`) |
 | `--no-install` | Writes `package.json`, skips the install and the codemods |
-| `--no-tooling` | Leaves `bin/basalt.ts` and the `create-basalt` devDependency alone |
+| `--no-tooling` | Leaves `bin/basalt.ts`, `src/dev.ts`, `.env.example` and the `create-basalt` devDependency alone |
 
 The policy is the scaffold's own (the same registry code): `@basaltkit/*` and
 `create-basalt` go to `latest` across majors — each framework major prints a
@@ -278,10 +286,20 @@ edits stay and the command says how to revert (`git checkout -- package.json …
 
 Project tooling rides along (skip with `--no-tooling`): an app without the
 `create-basalt` devDependency gets it plus a `basalt` script (and a
-`create-basalt` entry in `minimumReleaseAgeExclude`), and a `bin/basalt.ts`
-generated by an earlier release gains the project commands — **only** when it is
-byte-for-byte a known template (or the manifest records it untouched); a
-customised one is left alone and the exact snippet to paste is printed.
+`create-basalt` entry in `minimumReleaseAgeExclude`); a `bin/basalt.ts`
+generated by an earlier release gains the project commands, `.env` loading, a
+pre-boot `upgrade` and the readable env error; a `src/dev.ts` from 1.9/1.10 gains
+`.env` loading; and the `.env.example` header stops saying "nothing loads this
+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
 
@@ -320,10 +338,20 @@ lockfiles; installed versus declared versions, duplicated `@basaltkit/*`
 versions and unmet peer ranges; framework packages behind `latest` (skip with
 `--offline`); the auth secret (`<PREFIX>_APP_SECRET`, from the environment or
 `.env`, against the `minLength` in `src/env.ts` and the placeholder rules of
-`secret()`) and `DATABASE_URL`; whether the Prisma client is generated and
+`secret()`); every variable `src/env.ts` **requires** (declared without a
+default — `DATABASE_URL` with `--prisma`) that is set neither in the environment
+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`.
+`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
@@ -345,7 +373,9 @@ yours; the first `add` creates the manifest.
 
 ### Environment variables and `--env-file`
 
-Nothing loads `.env` for you. `node --env-file=.env` / `tsx --env-file=.env` **never override a variable already exported in the shell** — in a terminal where another project exported `DATABASE_URL` or `PORT`, an app reading the generic name boots against that value and only fails on the first request that touches it.
+**Development loads `.env`; production does not.** `pnpm dev` (`src/dev.ts`) and `pnpm basalt` (`bin/basalt.ts`, scaffolded unless `--no-cli`) load `.env` from the project root when it exists, with `node --env-file` semantics. `pnpm start` (`src/server.ts`) loads **nothing**: in production the configuration comes from the real environment (or start it yourself with `node --env-file=…`). A new app gets a ready-made `.env` — a copy of `.env.example` with local values and, with auth, a generated `APP_SECRET` — git-ignored (`.gitignore` and `.dockerignore`) and written with mode `0600`; `.env.example` stays the committed template. `prisma.config.ts` loads the same file for the Prisma CLI.
+
+Loading `.env` — like `node --env-file=.env` / `tsx --env-file=.env` — **never overrides a variable already exported in the shell**: in a terminal where another project exported `DATABASE_URL` or `PORT`, an app reading the generic name boots against that value and only fails on the first request that touches it.
 
 The scaffold closes that trap instead of only warning about it: `src/env.ts` passes an **app-specific prefix** derived from the project name (`my-saas` → `MY_SAAS`) to `defineEnv`, and `.env.example` uses the prefixed names.
 
@@ -366,6 +396,8 @@ NODE_ENV=development          # never prefixed — a Node-wide convention
 # MY_SAAS_APP_SECRET=         # with auth
 ```
 
+When a variable is invalid or missing, `pnpm basalt <command>` does not print a stack trace: it lists the variables (`EnvValidationError.report`), says where they were read from (the environment, and `.env` when it exists) and how to fix it — `cp .env.example .env`, fill them in, and for `DATABASE_URL` start PostgreSQL — then exits 1. `BASALT_DEBUG=1` (or `--debug`) shows the stack. The database gets the same treatment: PostgreSQL not answering (`ECONNREFUSED`, Prisma `P1001`, or an `assertMigrated` that could not query it) and an unmigrated database (`PRISMA_NOT_MIGRATED`) print what failed, the database in use — `postgres://host:port/name` and the variable it came from, never the credentials — and the fix (start PostgreSQL, e.g. `docker compose up -d`; check `MY_SAAS_DATABASE_URL`; `pnpm db:migrate`). Any other boot error keeps its stack trace. `pnpm basalt upgrade` (the `@basaltkit/cli` codemods) never boots the app, so it runs even when the environment is incomplete.
+
 Each variable is read as `MY_SAAS_<NAME>` first and **falls back** to the bare `<NAME>`, so a deployment that already exports the generic names keeps booting — while a stray `PORT` in your shell no longer wins. The rest of the app is unchanged: the keys stay bare (`env.PORT`). To require the prefixed names only, edit the generated file to `prefix: { value: 'MY_SAAS', fallback: false }`. Full rules: [`@basaltkit/env`](https://github.com/basaltkit/basalt/tree/main/packages/env#app-specific-prefix-prefix).
 
 ### Programmatic usage (Advanced)
@@ -418,7 +450,7 @@ Exported from `create-basalt` (in addition to the `create-basalt` executable):
 | Field | Type | Description |
 | --- | --- | --- |
 | `dir` | `string` | Absolute path of the created folder |
-| `files` | `string[]` | Files written (relative, sorted) |
+| `files` | `string[]` | Files written (relative, sorted) — includes the development `.env` |
 | `options` | `ProjectOptions` | The options actually applied (with defaults resolved) |
 | `versions` | `VersionResolution \| undefined` | With `resolveLatest`: `{ versions, resolved, failed, heldBack, tooFresh, registry }` — the final ranges, which packages got `^<latest>`, which kept the fallback after a registry failure, third-party packages held back because their latest is a new major, and third-party packages whose latest is not provably older than the release-age window (`{ name, latest, range, reason: 'recent' \| 'unknown' }`) |
 
@@ -469,9 +501,12 @@ Outside an interactive terminal (no TTY) the questions are skipped. Always pass
 Automatic installation failed (network, Node version, etc.). Go into the folder and run `pnpm install` (or the indicated manager) to see the real error.
 
 **I started the app and `GET /auth/login` gives a secret error.**
-With auth on, `src/env.ts` requires `APP_SECRET` — read as `MY_SAAS_APP_SECRET`, with at least 32 characters (`secret()` supplies a development default only when `NODE_ENV` is explicitly `development`/`test`). Copy `.env.example` to `.env` and set your own secret before going to production.
+With auth on, `src/env.ts` requires `APP_SECRET` — read as `MY_SAAS_APP_SECRET`, with at least 32 characters (`secret()` supplies a development default only when `NODE_ENV` is explicitly `development`/`test`). For development the scaffold's `.env` carries a generated one; in production export your own (`openssl rand -base64 48`) — `pnpm start` does not read `.env`.
 
-**With `--prisma`, the app refuses to boot: `PRISMA_NOT_MIGRATED`.**
+**`The app cannot start — the database did not answer`.**
+PostgreSQL is not running, or `MY_SAAS_DATABASE_URL` points at the wrong host/port (the message shows which, without credentials). Start it (`docker compose up -d`, or your local service) or fix the URL in `.env`; on a fresh database, `pnpm db:migrate`. `pnpm dev` still prints the raw error (the explainer lives in `bin/basalt.ts` only, so `src/dev.ts` stays a few lines); `pnpm basalt routes` gives the explained version.
+
+**With `--prisma`, the app refuses to boot: `PRISMA_NOT_MIGRATED`** (from `pnpm basalt`: `The app cannot start — the database is not migrated`).
 `assertMigrated` reached a database without the `_prisma_migrations` table. The
 message names the database and host it actually reached (never the
 credentials): either it is not the database you meant — check
@@ -486,7 +521,10 @@ The Prisma client is generated code, not a checked-in file. `pnpm install` runs
 or after editing the schema, run `pnpm db:generate`.
 
 **My app connects to the wrong database / port.**
-A variable exported in your shell beats `--env-file`. The generated `src/env.ts` already reads app-prefixed names (`MY_SAAS_PORT`), so set those rather than the generic ones — the bare names are only a fallback. Check `env | grep DATABASE_URL`, and see *Environment variables and `--env-file`*.
+A variable exported in your shell beats `.env` (as with `--env-file`). The generated `src/env.ts` already reads app-prefixed names (`MY_SAAS_PORT`), so set those rather than the generic ones — the bare names are only a fallback. Check `env | grep DATABASE_URL`, and see *Environment variables and `--env-file`*.
+
+**`The app cannot start — invalid environment variables` (or `EnvValidationError: … expected string, received undefined`).**
+A required variable is set neither in your shell nor in `.env`. Apps from create-basalt ≤ 1.10 did not load `.env` at all in `pnpm dev` / `pnpm basalt`: run `npx create-basalt@latest update` once — it patches an unmodified `bin/basalt.ts` and `src/dev.ts`. Then `cp .env.example .env` if there is no `.env`, fill the variables listed, and run `pnpm basalt doctor` to check. `pnpm start` never reads `.env`: export the variables there.
 
 **`pnpm basalt …` starts by running `pnpm install` (or fails offline).**
 pnpm 11's `verifyDepsBeforeRun` (default `install`). Run `node_modules/.bin/tsx bin/basalt.ts …` instead, or set `verifyDepsBeforeRun: warn` in `pnpm-workspace.yaml`.
@@ -515,6 +553,6 @@ The app's `bin/basalt.ts` predates the project commands. Run `npx create-basalt@
 - **`@basaltkit/auth`** — included by default (remove with `--no-auth`): `/auth/*` routes and `APP_SECRET` validated in `env.ts`.
 - **`@basaltkit/subscriptions`** — with `--billing`: example `free`/`pro` plans with trial and feature limits.
 - **`@basaltkit/prisma` + `@basaltkit/{tenancy,auth,teams,subscriptions}-prisma`** — with `--prisma`: the PostgreSQL layer — `prismaPlugin` (tenant-scoped client, boot-time `assertMigrated`), the composed `prisma/schema.prisma` and the Prisma-backed stores for whichever domains are on.
-- **`@basaltkit/cli` + `@basaltkit/generator`** — with `--cli`: `bin/basalt.ts` calls `runCli`, and `commandsPlugin(generatorCommands())` registers the `make:*` generators. `update` runs the installed `@basaltkit/cli` upgrade codemods after an install.
+- **`@basaltkit/cli` + `@basaltkit/generator`** — by default (not with `--no-cli`): `bin/basalt.ts` calls `runCli`, and `commandsPlugin(generatorCommands())` registers the `make:*` generators. `update` runs the installed `@basaltkit/cli` upgrade codemods after an install.
 - **`@basaltkit/sdk` + `@basaltkit/admin-shadcn` + `@basaltkit/admin`** — with `--ui`: the `web/` frontend calls the API through a typed client and uses the shadcn components.
 - **`@basaltkit/testing`** — always present in `devDependencies`, with a generated smoke test in `tests/app.test.ts`.

package/dist/args.d.ts

@@ -1,5 +1,5 @@
 import type { PackageManager } from './index.js';
-export declare const USAGE = "Usage: npm create basalt <name> [options]\n\nOptions:\n  --name=<name>   Project name (the way to create a project named like a\n                  project command: update, add, doctor, info)\n  --dir=<path>    Target directory (default: ./<name>)\n  --no-tenancy    Skip multi-tenancy\n  --no-auth       Skip authentication\n  --billing       Include subscriptions/billing\n  --ui            Scaffold a web/ frontend (React + shadcn + SDK)\n  --cli           Scaffold the 'basalt' CLI (code generators + commands)\n  --mcp           Expose read-only routes as MCP tools at /mcp\n  --prisma, --db  Back the app with PostgreSQL through Prisma: schema,\n                  migrations, prisma-backed stores and a boot-time check\n                  that the database is the migrated one\n  --install       Install dependencies (default: yes in an interactive\n                  terminal, skipped in CI/non-TTY; --no-install to opt out)\n  --no-install    Never install dependencies\n  --git           Initialize a git repository with a first commit\n                  (same default rule as --install; --no-git to opt out)\n  --no-git        Never initialize a git repository\n  --offline       Don't query the npm registry for the latest versions;\n                  use the ranges bundled with this create-basalt release\n  --pm=<manager>  Package manager: pnpm | npm | yarn | bun (default: auto-detect)\n  -y, --yes       Skip prompts and accept defaults\n  -h, --help      Show this help\n\nRun with no name in a terminal to be prompted interactively.\n\nProject commands \u2014 inside an existing app (in a scaffolded app: pnpm basalt <command>):\n  create-basalt update            Update dependencies to the latest versions (--dry, --major, \u2026)\n  create-basalt add <feature>     Add ui | cli | mcp to the app\n  create-basalt doctor            Check the project's health\n  create-basalt info              Versions summary for bug reports\n  create-basalt <command> --help  Options of one command\n";
+export declare const USAGE = "Usage: npm create basalt <name> [options]\n\nOptions:\n  --name=<name>   Project name (the way to create a project named like a\n                  project command: update, add, doctor, info)\n  --dir=<path>    Target directory (default: ./<name>)\n  --no-tenancy    Skip multi-tenancy\n  --no-auth       Skip authentication\n  --billing       Include subscriptions/billing\n  --ui            Scaffold a web/ frontend (React + shadcn + SDK)\n  --no-cli        Skip the 'basalt' CLI (code generators + commands;\n                  on by default)\n  --mcp           Expose read-only routes as MCP tools at /mcp\n  --prisma, --db  Back the app with PostgreSQL through Prisma: schema,\n                  migrations, prisma-backed stores and a boot-time check\n                  that the database is the migrated one\n  --install       Install dependencies (default: yes in an interactive\n                  terminal, skipped in CI/non-TTY; --no-install to opt out)\n  --no-install    Never install dependencies\n  --git           Initialize a git repository with a first commit\n                  (same default rule as --install; --no-git to opt out)\n  --no-git        Never initialize a git repository\n  --offline       Don't query the npm registry for the latest versions;\n                  use the ranges bundled with this create-basalt release\n  --pm=<manager>  Package manager: pnpm | npm | yarn | bun (default: auto-detect)\n  -y, --yes       Skip prompts and accept defaults\n  -h, --help      Show this help\n\nRun with no name in a terminal to be prompted interactively.\n\nProject commands \u2014 inside an existing app (in a scaffolded app: pnpm basalt <command>):\n  create-basalt update            Update dependencies to the latest versions (--dry, --major, \u2026)\n  create-basalt add <feature>     Add ui | cli | mcp to the app\n  create-basalt doctor            Check the project's health\n  create-basalt info              Versions summary for bug reports\n  create-basalt <command> --help  Options of one command\n";
 export interface Flags {
     name?: string;
     dir?: string;

package/dist/args.js

@@ -9,7 +9,8 @@ Options:
   --no-auth       Skip authentication
   --billing       Include subscriptions/billing
   --ui            Scaffold a web/ frontend (React + shadcn + SDK)
-  --cli           Scaffold the 'basalt' CLI (code generators + commands)
+  --no-cli        Skip the 'basalt' CLI (code generators + commands;
+                  on by default)
   --mcp           Expose read-only routes as MCP tools at /mcp
   --prisma, --db  Back the app with PostgreSQL through Prisma: schema,
                   migrations, prisma-backed stores and a boot-time check
@@ -41,7 +42,7 @@ export function parseArgs(argv) {
         auth: true,
         billing: false,
         ui: false,
-        cli: false,
+        cli: true,
         mcp: false,
         prisma: false,
         yes: false,
@@ -58,6 +59,8 @@ export function parseArgs(argv) {
             flags.ui = true;
         else if (token === '--cli')
             flags.cli = true;
+        else if (token === '--no-cli')
+            flags.cli = false;
         else if (token === '--mcp')
             flags.mcp = true;
         // `--db` reads naturally in a sentence ("scaffold it with a db") and is the

package/dist/bin-template.d.ts

@@ -1,5 +1,7 @@
 /** Marker proving a bin/basalt.ts already delegates the project commands. */
 export declare const PROJECT_COMMANDS_MARKER = "['update', 'add', 'doctor', 'info'].includes(process.argv[2]";
+/** Marker proving a bin/basalt.ts already has the dev prelude (.env loading, `upgrade`, env errors). */
+export declare const DEV_PRELUDE_MARKER = "process.loadEnvFile(envFile)";
 export declare function basaltBin(): string;
 /**
  * Hashes of every bin/basalt.ts an earlier create-basalt release generated
@@ -8,16 +10,19 @@ export declare function basaltBin(): string;
  */
 export declare const LEGACY_BIN_HASHES: ReadonlySet<string>;
 export declare const hasProjectCommands: (content: string) => boolean;
+export declare const hasDevPrelude: (content: string) => boolean;
 /**
- * Upgrades a template-generated bin/basalt.ts to delegate the project
- * commands: inserts the prelude after the shebang and turns the remaining
- * static imports into dynamic ones (so they no longer run before it).
- * Deterministic for the known templates — for the latest one the result is
- * exactly {@link basaltBin}.
+ * Upgrades a template-generated bin/basalt.ts to the current template, step by
+ * step: (1) without the project commands, inserts their prelude after the
+ * shebang and turns the remaining static imports into dynamic ones (so they no
+ * longer run before it); (2) without the dev prelude, inserts it right after
+ * the project commands and routes the app import through `explainBootFailure`.
+ * Deterministic for the known templates — for the latest ones (1.9, 1.10) the
+ * result is exactly {@link basaltBin}.
  */
 export declare function patchBasaltBin(content: string): string;
 export type BinStatus = 'current' | 'patchable' | 'modified' | 'absent';
-/** Where a bin/basalt.ts stands: already delegating, an untouched old template, or user code. */
+/** Where a bin/basalt.ts stands: already current, an untouched old template, or user code. */
 export declare function binStatus(content: string | undefined, manifestHash?: string): BinStatus;
-/** What to paste by hand into a customised bin/basalt.ts. */
-export declare const MANUAL_BIN_SNIPPET = "Paste this right after the shebang line of bin/basalt.ts, then turn its\nstatic imports of @basaltkit/* and ../src/app.js into dynamic ones\n(`import { runCli } from '@basaltkit/cli'` \u2192 `const { runCli } = await import('@basaltkit/cli')`)\nso they no longer run before it:\n\nimport { spawnSync } from 'node:child_process'\nimport { existsSync, readFileSync } from 'node:fs'\nimport { join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\n// Project commands run BEFORE anything of the app is imported, so they keep\n// working while the app is broken mid-upgrade. create-basalt provides them \u2014\n// the project's devDependency when installed, else its latest release:\n//   pnpm basalt update                  \u2014 update dependencies to the latest versions (--dry to preview)\n//   pnpm basalt add ui                  \u2014 add a feature later (ui, cli, mcp)\n//   pnpm basalt doctor                  \u2014 check the project's health\n//   pnpm basalt info                    \u2014 versions summary for bug reports\nconst root = fileURLToPath(new URL('..', import.meta.url))\nif (['update', 'add', 'doctor', 'info'].includes(process.argv[2] ?? '')) {\n  process.exit(createBasalt(process.argv.slice(2)))\n}\n\n/** Runs create-basalt: the installed devDependency, else `<pm> dlx create-basalt@latest`. */\nfunction createBasalt(args: string[]): number {\n  const local = join(root, 'node_modules', 'create-basalt', 'dist', 'cli.js')\n  if (existsSync(local)) {\n    return spawnSync(process.execPath, [local, ...args], { cwd: root, stdio: 'inherit' }).status ?? 1\n  }\n  let declared = ''\n  try {\n    declared = String(JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).packageManager ?? '')\n  } catch {\n    // No readable package.json: the lockfiles decide.\n  }\n  const uses = (pm: string, ...lockfiles: string[]): boolean =>\n    declared.startsWith(`${pm}@`) || lockfiles.some((file) => existsSync(join(root, file)))\n  const [command, prefix]: [string, string[]] = uses('pnpm', 'pnpm-lock.yaml')\n    ? ['pnpm', ['dlx']]\n    : uses('bun', 'bun.lock', 'bun.lockb')\n      ? ['bunx', []]\n      : ['npx', ['--yes']]\n  const result = spawnSync(command, [...prefix, 'create-basalt@latest', ...args], {\n    cwd: root,\n    stdio: 'inherit',\n    shell: process.platform === 'win32',\n  })\n  return result.status ?? 1\n}\n";
+/** What to paste by hand into a customised bin/basalt.ts (only the parts it lacks). */
+export declare function manualBinSnippet(content: string): string;

package/dist/bin-template.js

@@ -55,11 +55,136 @@ function createBasalt(args: string[]): number {
   return result.status ?? 1
 }
 `;
+/**
+ * The DEV PRELUDE, right after the project commands and still before anything
+ * of the app is imported:
+ *
+ * - `upgrade` (the @basaltkit/cli codemods) only rewrites source files, so it
+ *   runs without booting the app — it must keep working while the app cannot
+ *   start (that is usually why you are upgrading);
+ * - `.env` is loaded for development with `node --env-file` semantics: a
+ *   variable already exported in the shell wins, the file only fills in what
+ *   is missing (the app-prefixed names in src/env.ts exist because of exactly
+ *   that rule). `pnpm start` / src/server.ts never loads it;
+ * - a boot-time `EnvValidationError` becomes a fix (which variables, where they
+ *   are read from, what to do) instead of a stack trace.
+ */
+const DEV_PRELUDE = `// \`upgrade\` (framework codemods) only rewrites source files: it runs without
+// booting the app, so it works even while the app cannot start.
+if (process.argv[2] === 'upgrade') {
+  const { consoleIo, parseArgv, upgradeCommand } = await import('@basaltkit/cli')
+  const { args, flags } = parseArgv(process.argv.slice(2))
+  // upgradeCommand reads only io/args/flags — there is no app to hand it.
+  const context = { io: consoleIo(), args, flags } as unknown as Parameters<typeof upgradeCommand.handle>[0]
+  process.exit((await upgradeCommand.handle(context)) ?? 0)
+}
+
+// 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. \`pnpm start\` (production) never loads it — there the configuration
+// comes from the real environment.
+const envFile = join(root, '.env')
+if (existsSync(envFile)) process.loadEnvFile(envFile)
+
+/**
+ * A boot failure as a fix instead of a stack trace (stack: BASALT_DEBUG=1 or --debug):
+ * invalid environment variables, a database that does not answer, one that is not
+ * 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; 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 ?? ''),
+  )
+  const unreachable =
+    codes.some((code) => /^(ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|ETIMEDOUT|EAI_AGAIN|P1001|P1002)$/.test(code)) ||
+    /ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|Can't reach database server/.test(message) ||
+    // assertMigrated could not even query the database (down, wrong host/port or credentials).
+    (failure.code === 'PRISMA_NOT_MIGRATED' && message.startsWith('Could not verify'))
+  const debugHint = 'BASALT_DEBUG=1 shows the stack trace.'
+  let explanation: string | undefined
+  if (failure.code === 'ENV_INVALID' && Array.isArray(failure.report)) {
+    const hasEnvFile = existsSync(envFile)
+    explanation = [
+      'The app cannot start — invalid environment variables:',
+      ...failure.report.map((line) => '  - ' + String(line)),
+      '',
+      "Read from: your shell's environment" +
+        (hasEnvFile ? ' and ' + envFile + ' (exported variables win).' : ' only — there is no ' + envFile + '.'),
+      'Fix: ' + (hasEnvFile ? 'set them in .env' : 'cp .env.example .env, then fill them in') + ' (or export them)' +
+        (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).'
+    explanation = unreachable
+      ? [
+          'The app cannot start — the database did not answer.',
+          where,
+          'Fix: start PostgreSQL (e.g. \`docker compose up -d\`, or your local service) and check that ' +
+            database.name + ' in .env points at it (host, port, user, password); on a new database, then run \`pnpm db:migrate\`. ' + debugHint,
+        ].join('\\n')
+      : [
+          'The app cannot start — the database is not migrated:',
+          '  ' + message,
+          where,
+          'Fix: run \`pnpm db:migrate\` (development; \`pnpm db:deploy\` in production) — or, if this is not the database you meant, check ' +
+            database.name + ' (a shell may have exported another project\\'s). ' + debugHint,
+        ].join('\\n')
+  }
+  if (explanation === undefined || process.env['BASALT_DEBUG'] === '1' || process.argv.includes('--debug')) throw error
+  console.error(explanation)
+  process.exit(1)
+}
+
+/** The database URL the app booted with — protocol, host, port and database only, never the credentials. */
+async function databaseInUse(): Promise<{ name: string; target: string }> {
+  let url: unknown
+  try {
+    url = ((await import('../src/env.js')).env as unknown as Record<string, unknown>)['DATABASE_URL']
+  } catch {
+    // env.ts itself failed: there is no URL to show.
+  }
+  // The variable it came from: the app-prefixed name first (it wins in src/env.ts).
+  const name =
+    Object.keys(process.env)
+      .filter((key) => key.endsWith('DATABASE_URL') && process.env[key] === url)
+      .sort((a, b) => b.length - a.length)[0] ?? 'DATABASE_URL'
+  try {
+    const parsed = new URL(String(url))
+    return { name, target: parsed.protocol + '//' + parsed.hostname + ':' + (parsed.port || '5432') + parsed.pathname }
+  } catch {
+    return { name, target: '(no valid URL)' }
+  }
+}
+`;
 /** Marker proving a bin/basalt.ts already delegates the project commands. */
 export const PROJECT_COMMANDS_MARKER = "['update', 'add', 'doctor', 'info'].includes(process.argv[2]";
+/** Marker proving a bin/basalt.ts already has the dev prelude (.env loading, `upgrade`, env errors). */
+export const DEV_PRELUDE_MARKER = 'process.loadEnvFile(envFile)';
+const APP_IMPORT = "await import('../src/app.js')";
+const APP_IMPORT_EXPLAINED = `${APP_IMPORT}.catch(explainBootFailure)`;
+const RUN_CLI = 'process.exit(await runCli({ app })';
 export function basaltBin() {
     return `#!/usr/bin/env node
 ${PRELUDE}
+${DEV_PRELUDE}
 // The dev tools are imported dynamically, after the project commands above.
 const { runCli } = await import('@basaltkit/cli')
 const { generatorCommands } = await import('@basaltkit/generator')
@@ -68,7 +193,7 @@ const { prismaSyncCommand } = await import('@basaltkit/prisma')
 // Dev tooling: opt into development defaults unless NODE_ENV is already set
 // (imported dynamically below so env.ts is evaluated after this line).
 process.env['NODE_ENV'] ??= 'development'
-const { buildApp } = await import('../src/app.js')
+const { buildApp } = ${APP_IMPORT_EXPLAINED}
 
 // The 'basalt' CLI: boots the app WITH the dev/CLI commands, runs one, shuts down.
 // The dev tools (@basaltkit/generator; add @basaltkit/ai for ai:*) are imported
@@ -83,7 +208,7 @@ const app = buildApp({
   logLevel: 'silent',
   commands: [...generatorCommands(), prismaSyncCommand()],
 })
-process.exit(await runCli({ app }))
+process.exit(await runCli({ app }).catch(explainBootFailure))
 `;
 }
 /**
@@ -100,17 +225,31 @@ export const LEGACY_BIN_HASHES = new Set([
     'sha256-d09d583f1a39bffcb72f302c5f6c3e2651badea358ba38019238a4aa4b842545',
     // 2026-09-19 (create-basalt ≤ 1.9): NODE_ENV defaulted before the app import.
     'sha256-a0df89dee04091a9470f67968ff72cfc3bf64076c1bf3d141ae657c7438a94c8',
+    // 2026-10-01 (create-basalt 1.10): project commands (update/add/doctor/info)
+    // delegated before boot — but no .env loading and `upgrade` booted the app.
+    'sha256-9091e137a5de39929d0e70b2fd973386b9cc1c2f996e130989a22c795b9d0893',
 ]);
 export const hasProjectCommands = (content) => content.includes(PROJECT_COMMANDS_MARKER);
+export const hasDevPrelude = (content) => content.includes(DEV_PRELUDE_MARKER);
 /**
- * Upgrades a template-generated bin/basalt.ts to delegate the project
- * commands: inserts the prelude after the shebang and turns the remaining
- * static imports into dynamic ones (so they no longer run before it).
- * Deterministic for the known templates — for the latest one the result is
- * exactly {@link basaltBin}.
+ * Upgrades a template-generated bin/basalt.ts to the current template, step by
+ * step: (1) without the project commands, inserts their prelude after the
+ * shebang and turns the remaining static imports into dynamic ones (so they no
+ * longer run before it); (2) without the dev prelude, inserts it right after
+ * the project commands and routes the app import through `explainBootFailure`.
+ * Deterministic for the known templates — for the latest ones (1.9, 1.10) the
+ * result is exactly {@link basaltBin}.
  */
 export function patchBasaltBin(content) {
-    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    let text = content.replace(/\r\n/g, '\n');
+    if (!hasProjectCommands(text))
+        text = addProjectCommands(text);
+    if (!hasDevPrelude(text))
+        text = addDevPrelude(text);
+    return text;
+}
+function addProjectCommands(content) {
+    const lines = content.split('\n');
     const shebang = lines[0]?.startsWith('#!') ? `${lines.shift()}\n` : '';
     const body = lines.map((line) => {
         const match = /^import \{ ([^}]+) \} from '([^']+)'$/.exec(line);
@@ -122,19 +261,45 @@ export function patchBasaltBin(content) {
     }
     return `${shebang}${PRELUDE}\n${body.join('\n')}`;
 }
-/** Where a bin/basalt.ts stands: already delegating, an untouched old template, or user code. */
+function addDevPrelude(content) {
+    const at = content.indexOf(PRELUDE);
+    // A file without the template's prelude block is not ours to rearrange.
+    if (at < 0)
+        return content;
+    const end = at + PRELUDE.length + (content.startsWith('\n', at + PRELUDE.length) ? 1 : 0);
+    const rest = content
+        .slice(end)
+        .replace(`= ${APP_IMPORT}\n`, `= ${APP_IMPORT_EXPLAINED}\n`)
+        .replace(`${RUN_CLI})\n`, `${RUN_CLI}.catch(explainBootFailure))\n`);
+    return `${content.slice(0, end)}${DEV_PRELUDE}\n${rest}`;
+}
+/** Where a bin/basalt.ts stands: already current, an untouched old template, or user code. */
 export function binStatus(content, manifestHash) {
     if (content === undefined)
         return 'absent';
-    if (hasProjectCommands(content))
+    if (hasProjectCommands(content) && hasDevPrelude(content))
         return 'current';
     const hash = hashContent(content);
     return LEGACY_BIN_HASHES.has(hash) || hash === manifestHash ? 'patchable' : 'modified';
 }
-/** What to paste by hand into a customised bin/basalt.ts. */
-export const MANUAL_BIN_SNIPPET = `Paste this right after the shebang line of bin/basalt.ts, then turn its
+/** What to paste by hand into a customised bin/basalt.ts (only the parts it lacks). */
+export function manualBinSnippet(content) {
+    const steps = [];
+    if (!hasProjectCommands(content)) {
+        steps.push(`Paste this right after the shebang line of bin/basalt.ts, then turn its
 static imports of @basaltkit/* and ../src/app.js into dynamic ones
 (\`import { runCli } from '@basaltkit/cli'\` → \`const { runCli } = await import('@basaltkit/cli')\`)
 so they no longer run before it:
 
-${PRELUDE}`;
+${PRELUDE}`);
+    }
+    if (!hasDevPrelude(content)) {
+        steps.push(`${steps.length > 0 ? 'Then paste' : 'Paste'} this after the project-commands block (before anything of the app is
+imported) — it runs \`upgrade\` without booting the app, loads .env for development
+and explains env errors — and change the app import to
+\`const { buildApp } = ${APP_IMPORT_EXPLAINED}\`:
+
+${DEV_PRELUDE}`);
+    }
+    return steps.join('\n');
+}

package/dist/cli.js

@@ -152,8 +152,12 @@ try {
     if (flags.prisma) {
         // Nothing boots before the database exists: env.DATABASE_URL is required and
         // the app asserts at boot that it reached the MIGRATED database.
-        steps.push(`cp .env.example .env   # then point ${envPrefix(result.options.name)}_DATABASE_URL at your database`);
-        steps.push(`${pm} run db:migrate${flags.tenancy ? '   # creates the tables and seeds the demo tenant' : '   # creates the tables'}`);
+        // .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   # 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/dev-entry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `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 declare const LEGACY_DEV_HASHES: ReadonlySet<string>;
+/** Marker proving a src/dev.ts already loads .env. */
+export declare const DEV_ENV_MARKER = "process.loadEnvFile(";
+export type DevEntryStatus = 'current' | 'patchable' | 'modified' | 'absent';
+/** Where a src/dev.ts stands: loads .env already, an untouched old template, or user code. */
+export declare function devEntryStatus(content: string | undefined, manifestHash?: string): DevEntryStatus;
+/** The current src/dev.ts — what a patchable one becomes. */
+export declare const patchDevEntry: () => string;
+/** What to paste by hand into a customised src/dev.ts. */
+export declare const MANUAL_DEV_SNIPPET = "Paste this at the top of src/dev.ts, BEFORE the server is imported (keep that\nimport dynamic \u2014 `await import('./server.js')` \u2014 so the variables are set first):\n\nimport { existsSync } from 'node:fs'\nimport { fileURLToPath } from 'node:url'\n\n// Development loads .env (when present) like `node --env-file=.env`: a variable\n// already exported in your shell still wins, the file only fills in what is missing.\nconst envFile = fileURLToPath(new URL('../.env', import.meta.url))\nif (existsSync(envFile)) process.loadEnvFile(envFile)\n";
+/**
+ * `.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 declare function patchEnvExample(content: string): string | undefined;