create-basalt 1.8.0 → 1.10.0

package/README.md

@@ -16,6 +16,8 @@ Starting a backend project from scratch involves dozens of decisions and files b
 
 It works in two ways: interactive mode (answers questions in the terminal) or direct mode with flags (ideal for scripts). It doesn't install dependencies or touch git unless you ask it to (`--install`, `--git`).
 
+It also stays useful **after** the project exists: `create-basalt update` moves an app to the latest dependency versions, `create-basalt add ui|cli|mcp` adds a feature you didn't pick at creation time, and `create-basalt doctor` / `info` check the project — see [Project commands](#project-commands-update-add-doctor-info). In a scaffolded app they are simply `pnpm basalt update`, `pnpm basalt add ui`, …
+
 ## Installation
 
 You don't need to install anything — your package manager's `create` command downloads and runs the package on the spot:
@@ -84,7 +86,8 @@ Usage: npm create basalt <name> [options]
 
 | Flag | Default | What it does |
 | --- | --- | --- |
-| `<name>` | — (asked in interactive mode) | Project name (and folder name, unless `--dir`) |
+| `<name>` | — (asked in interactive mode) | Project name (and folder name, unless `--dir`). `update`, `add`, `doctor` and `info` are reserved for the [project commands](#project-commands-update-add-doctor-info) |
+| `--name=<name>` | — | Project name as a flag — the way to create a project literally called `update`/`add`/`doctor`/`info` |
 | `--dir=<path>` | `./<name>` | Destination folder |
 | `--no-tenancy` | tenancy **on** | Removes multi-tenancy (`@basaltkit/tenancy`) |
 | `--no-auth` | auth **on** | Removes authentication (`@basaltkit/auth`, `APP_SECRET`, `/auth/*` routes) |
@@ -135,12 +138,13 @@ Always:
 
 ```
 my-app/
-├── package.json          # scripts: dev, start, test, typecheck (+ basalt with --cli)
+├── package.json          # scripts: dev, start, 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
 ├── .gitignore
 ├── README.md             # instructions adapted to the chosen options
-├── pnpm-workspace.yaml   # esbuild allowBuilds, @basaltkit/* release-age exclusion (+ "web" member with --ui) + pnpm 11 notes
+├── pnpm-workspace.yaml   # esbuild allowBuilds, @basaltkit/* + create-basalt release-age exclusion (+ "web" member with --ui) + pnpm 11 notes
 ├── src/
 │   ├── env.ts            # environment variables validated with Zod (@basaltkit/env), app-prefixed
 │   ├── app.ts            # buildApp() with the chosen plugins
@@ -149,14 +153,14 @@ my-app/
 └── 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. With `--cli`, adds `bin/basalt.ts` and the `"basalt": "tsx bin/basalt.ts"` script. 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 `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 `--ui`: running the API and frontend
 
 ```bash
 pnpm install
-pnpm dev                              # terminal 1 — API on :3000
-pnpm --filter my-app-web dev       # terminal 2 — UI at http://localhost:5180
+pnpm dev        # terminal 1 — API on :3000
+pnpm dev:web    # terminal 2 — UI at http://localhost:5180 (= pnpm --filter my-app-web dev)
 ```
 
 Vite's dev server proxies `/api` to the API — there's no CORS to configure.
@@ -209,6 +213,131 @@ pnpm basalt make:resource Project   # generates schema → repository → servic
 
 With pnpm 11, every `pnpm <script>` and `pnpm exec` first verifies dependencies (`verifyDepsBeforeRun`, default `install`) and runs `pnpm install` when any workspace project is out of sync — so `pnpm basalt …` can need the network. `node_modules/.bin/tsx bin/basalt.ts …` skips that check; `verifyDepsBeforeRun: warn` (commented out in the generated `pnpm-workspace.yaml`) turns it into a warning for the whole project.
 
+## Project commands: update, add, doctor, info
+
+Run inside an existing Basalt app — any app, created with or without `--cli`,
+by any create-basalt release:
+
+```bash
+npx create-basalt@latest update        # or, in a scaffolded app: pnpm basalt update
+npx create-basalt@latest add ui        # pnpm basalt add ui
+npx create-basalt@latest doctor        # pnpm basalt doctor
+npx create-basalt@latest info          # pnpm basalt info
+```
+
+The first positional argument picks the mode: `update`, `add`, `doctor` and
+`info` are project commands; anything else is a new project's name (use
+`--name=update` to create a project with one of those names). Outside a Basalt
+app (no `package.json`, or no `@basaltkit/*` dependency) they stop with an
+actionable error. Every command has `--help`; `--cwd=<dir>` targets another
+directory, `--pm=` overrides the detected package manager (`packageManager`
+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`;
+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` /
+`bunx` / `npx create-basalt@latest` when it isn't installed.
+
+### Updating an app
+
+```bash
+pnpm basalt update --dry      # the table, nothing written
+pnpm basalt update            # asks, writes, installs, runs the codemods
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--dry` | Prints the plan; writes nothing |
+| `-y`, `--yes` | Applies without asking (required when stdin is not a terminal) |
+| `--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 |
+
+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
+link to its CHANGELOG and to the upgrade notes; third-party packages go to the
+newest release **on the app's current major** (a newer major is listed as
+"kept … pass --major"); a version younger than the release-age window (pnpm
+`minimumReleaseAge`, read from the project's `pnpm-workspace.yaml` when set) is
+left for later so the install cannot refuse it. When a framework release
+declares a peer range the app would not meet (say `zod ^5` while zod is held on
+4), the plan warns before anything is written.
+
+Both `package.json` and `web/package.json` are updated, **in place**: only the
+version strings change — order, indentation and range style (`^`, `~`, exact)
+are kept, and ranges `update` does not manage (`workspace:`, tags, git, `>=`) are
+left alone. The lockfile is never edited by hand: the detected package manager
+installs, then the installed `@basaltkit/cli` upgrade codemods run (no app
+boot), then it suggests `pnpm typecheck && pnpm test`. If the install fails the
+edits stay and the command says how to revert (`git checkout -- package.json …`).
+`--offline` is refused: update needs the registry.
+
+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.
+
+### Adding features later
+
+```bash
+pnpm basalt add ui --dry       # what would be created/merged/skipped
+pnpm basalt add ui             # web/ exactly as --ui scaffolds it
+pnpm basalt add cli            # bin/basalt.ts + @basaltkit/cli, generator, prisma
+pnpm basalt add mcp            # @basaltkit/mcp at POST /mcp + the dev-only ai-mcp bridge + .mcp.json
+```
+
+`add` adapts the templates to the project as it is now (name, auth/tenancy from
+its dependencies) and plans every change before applying any:
+
+- **Existing files are never overwritten** — skipped with a notice; `--force`
+  overwrites generated files.
+- **Merged, not replaced:** `package.json` (new dependencies in sorted
+  position, scripts such as `dev:web`; an existing entry is never changed),
+  `pnpm-workspace.yaml` (`web` added to `packages:`), `.gitignore`, `README.md`.
+- **Your code** (`src/app.ts`, `src/routes.ts`) is regenerated only when
+  `.basalt/project.json` proves it untouched, patched where the template's
+  anchors are still unambiguous (works with `fastifyPlugin`, `expressPlugin` or
+  `honoPlugin`), and otherwise left alone with the exact manual steps printed.
+- `add ui` needs a pnpm project (`web/` is a pnpm workspace member) and touches
+  no API code: the Vite dev server proxies `/api`, so there is no CORS to set up.
+- Dependencies are installed afterwards unless `--no-install`; `--offline` uses
+  the ranges bundled with this create-basalt instead of the registry.
+
+A project created without `--ui` followed by `add ui` ends up with the same
+files as one created with `--ui` (the test suite checks exactly that).
+
+### doctor and info
+
+`doctor` is read-only and exits non-zero only on errors (warnings exit 0). It
+checks Node against `engines` and Basalt's `>=22.5.0`; the package manager and
+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
+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`.
+
+`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
+bug reports.
+
+### The scaffold manifest
+
+`.basalt/project.json` records the create-basalt version, the options and a
+`sha256` of every file the scaffold wrote (`package.json` excluded — installs
+rewrite it). Commit it: it is how `add` and `update` tell an untouched template
+file from one you edited. Projects created before it existed are handled too —
+features are inferred from `package.json` and the tree, and every file counts as
+yours; the first `add` creates the manifest.
+
 ### `pnpm-workspace.yaml` and pnpm 11
 
 - `minimumReleaseAgeExclude` is evaluated **first-match-wins by package name**. To exclude several versions of one package, write ONE entry with a union — `'@types/node@22.20.4 || 26.6.2'` — never two `@types/node@…` entries (only the first would apply). The generated file carries this example as a comment.
@@ -299,6 +428,17 @@ Throws `TargetNotEmptyError` if the destination folder exists and isn't empty.
 
 Detects the manager that invoked the command from `npm_config_user_agent` (or the string passed in). Returns `'pnpm' | 'yarn' | 'bun'` when recognized; otherwise `'npm'`.
 
+### Project commands (programmatic)
+
+| Export | What it does |
+| --- | --- |
+| `runProjectCommand(argv, deps)` | Runs `update`/`add`/`doctor`/`info` and returns the exit code; every side effect (output, prompts, package-manager runs, registry fetch, codemods) is injected through `deps` |
+| `loadProject(dir, pm?)` | Reads an app: package.json (+ `web/`), manifest, detected features and package manager. Throws `NotABasaltAppError` |
+| `planUpdate(ctx, { major?, only?, tooling?, registry? })` | The update plan — entries, the full before/after of every file, tooling, warnings, framework majors. Writes nothing |
+| `planAdd(ctx, feature, { force?, resolveLatest?, registry? })` | The add plan — created/merged/skipped files and manual steps. Writes nothing |
+| `runDoctor(ctx, options)` | Doctor findings (`{ level: 'ok' \| 'info' \| 'warn' \| 'error', area, message }`) |
+| `MANIFEST_PATH`, `readManifest(dir)`, `hashContent(text)` | The scaffold manifest |
+
 ### `TargetNotEmptyError`
 
 Error (extends `Error`) with the message `Target directory "<dir>" already exists and is not empty.`
@@ -351,8 +491,20 @@ A variable exported in your shell beats `--env-file`. The generated `src/env.ts`
 **`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`.
 
-**I want to change my mind after generating (e.g. add billing).**
-There's no "re-scaffold" command. Either generate a new project with the right flags and compare, or add it by hand: install `@basaltkit/subscriptions` and add the `subscriptionsPlugin` to `src/app.ts` (the generated README and the templates serve as reference).
+**I want to change my mind after generating (e.g. add the frontend).**
+`pnpm basalt add ui` (or `npx create-basalt@latest add ui`) — likewise `cli` and `mcp`; see [Adding features later](#adding-features-later). Billing, tenancy and auth are not `add`-able (they reshape `src/app.ts` and the schema): install `@basaltkit/subscriptions` and add the `subscriptionsPlugin` to `src/app.ts` by hand (the generated README and the templates serve as reference).
+
+**`npm create basalt update` did not create a project called "update".**
+`update`, `add`, `doctor` and `info` are project commands. Use `npm create basalt -- --name=update`.
+
+**`update cannot run with --offline` / `Could not reach https://registry.npmjs.org for any package`.**
+`update` resolves versions from the registry. Drop `--offline`, check the connection, or point `npm_config_registry` at your mirror.
+
+**`Not a terminal — nothing written. Re-run with --yes`.**
+`update` and `add` only apply after a confirmation; in CI or a pipe, pass `--yes`.
+
+**`pnpm basalt update` says `Unknown command "update"`.**
+The app's `bin/basalt.ts` predates the project commands. Run `npx create-basalt@latest update` once — it patches an unmodified `bin/basalt.ts` (or prints the snippet for a customised one).
 
 ## How it connects to other modules
 
@@ -363,6 +515,6 @@ There's no "re-scaffold" command. Either generate a new project with the right f
 - **`@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.
+- **`@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/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  --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";
+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 interface Flags {
     name?: string;
     dir?: string;

package/dist/args.js

@@ -2,6 +2,8 @@ import { stdout } from 'node:process';
 export const USAGE = `Usage: npm create basalt <name> [options]
 
 Options:
+  --name=<name>   Project name (the way to create a project named like a
+                  project command: update, add, doctor, info)
   --dir=<path>    Target directory (default: ./<name>)
   --no-tenancy    Skip multi-tenancy
   --no-auth       Skip authentication
@@ -25,6 +27,13 @@ Options:
   -h, --help      Show this help
 
 Run with no name in a terminal to be prompted interactively.
+
+Project commands — inside an existing app (in a scaffolded app: pnpm basalt <command>):
+  create-basalt update            Update dependencies to the latest versions (--dry, --major, …)
+  create-basalt add <feature>     Add ui | cli | mcp to the app
+  create-basalt doctor            Check the project's health
+  create-basalt info              Versions summary for bug reports
+  create-basalt <command> --help  Options of one command
 `;
 export function parseArgs(argv) {
     const flags = {
@@ -69,6 +78,8 @@ export function parseArgs(argv) {
             flags.offline = true;
         else if (token.startsWith('--dir='))
             flags.dir = token.slice('--dir='.length);
+        else if (token.startsWith('--name='))
+            flags.name = token.slice('--name='.length);
         else if (token.startsWith('--pm='))
             flags.pm = token.slice('--pm='.length);
         else if (token === '--help' || token === '-h') {

package/dist/bin-template.d.ts

@@ -0,0 +1,23 @@
+/** 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]";
+export declare function basaltBin(): string;
+/**
+ * Hashes of every bin/basalt.ts an earlier create-basalt release generated
+ * (CRLF-insensitive). Only these — or a file the project's manifest records as
+ * untouched — are patched automatically.
+ */
+export declare const LEGACY_BIN_HASHES: ReadonlySet<string>;
+export declare const hasProjectCommands: (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}.
+ */
+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. */
+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";

package/dist/bin-template.js

@@ -0,0 +1,140 @@
+import { hashContent } from './project/manifest.js';
+/**
+ * `bin/basalt.ts` — the app's `basalt` CLI (scaffolded with `--cli`, or added
+ * later with `create-basalt add cli`).
+ *
+ * The file opens with the PROJECT-COMMANDS PRELUDE: `update`, `add`, `doctor`
+ * and `info` are handed to create-basalt BEFORE anything of the app is
+ * imported — those commands exist precisely for the moments the app does not
+ * boot (mid-upgrade, a missing dependency). That is also why the dev tools
+ * below are imported dynamically: a static import is evaluated before the
+ * first statement, so a broken `@basaltkit/generator` would take `pnpm basalt
+ * update` down with it.
+ */
+const PRELUDE = `import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Project commands run BEFORE anything of the app is imported, so they keep
+// working while the app is broken mid-upgrade. create-basalt provides them —
+// the project's devDependency when installed, else its latest release:
+//   pnpm basalt update                  — update dependencies to the latest versions (--dry to preview)
+//   pnpm basalt add ui                  — add a feature later (ui, cli, mcp)
+//   pnpm basalt doctor                  — check the project's health
+//   pnpm basalt info                    — versions summary for bug reports
+const root = fileURLToPath(new URL('..', import.meta.url))
+if (['update', 'add', 'doctor', 'info'].includes(process.argv[2] ?? '')) {
+  process.exit(createBasalt(process.argv.slice(2)))
+}
+
+/** Runs create-basalt: the installed devDependency, else \`<pm> dlx create-basalt@latest\`. */
+function createBasalt(args: string[]): number {
+  const local = join(root, 'node_modules', 'create-basalt', 'dist', 'cli.js')
+  if (existsSync(local)) {
+    return spawnSync(process.execPath, [local, ...args], { cwd: root, stdio: 'inherit' }).status ?? 1
+  }
+  let declared = ''
+  try {
+    declared = String(JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).packageManager ?? '')
+  } catch {
+    // No readable package.json: the lockfiles decide.
+  }
+  const uses = (pm: string, ...lockfiles: string[]): boolean =>
+    declared.startsWith(\`\${pm}@\`) || lockfiles.some((file) => existsSync(join(root, file)))
+  const [command, prefix]: [string, string[]] = uses('pnpm', 'pnpm-lock.yaml')
+    ? ['pnpm', ['dlx']]
+    : uses('bun', 'bun.lock', 'bun.lockb')
+      ? ['bunx', []]
+      : ['npx', ['--yes']]
+  const result = spawnSync(command, [...prefix, 'create-basalt@latest', ...args], {
+    cwd: root,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  })
+  return result.status ?? 1
+}
+`;
+/** Marker proving a bin/basalt.ts already delegates the project commands. */
+export const PROJECT_COMMANDS_MARKER = "['update', 'add', 'doctor', 'info'].includes(process.argv[2]";
+export function basaltBin() {
+    return `#!/usr/bin/env node
+${PRELUDE}
+// The dev tools are imported dynamically, after the project commands above.
+const { runCli } = await import('@basaltkit/cli')
+const { generatorCommands } = await import('@basaltkit/generator')
+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')
+
+// 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
+// ONLY here — the runtime server (src/server.ts) never loads them, so the SaaS
+// runs without the codegen/AI layer.
+//   pnpm basalt dev                     — dev server: route table + watch (--worker for a queue worker)
+//   pnpm basalt list                    — show available commands
+//   pnpm basalt routes                  — list registered HTTP routes
+//   pnpm basalt make:resource Project   — generate a full resource vertical
+//   pnpm basalt make:service Project    — generate a single artifact (schema/service/…)
+const app = buildApp({
+  logLevel: 'silent',
+  commands: [...generatorCommands(), prismaSyncCommand()],
+})
+process.exit(await runCli({ app }))
+`;
+}
+/**
+ * Hashes of every bin/basalt.ts an earlier create-basalt release generated
+ * (CRLF-insensitive). Only these — or a file the project's manifest records as
+ * untouched — are patched automatically.
+ */
+export const LEGACY_BIN_HASHES = new Set([
+    // create-basalt 0.x (rebrand, 2026-08-09): static imports, no dev commands.
+    'sha256-78537f4bf21ca44d78dc50f8841f39898b86300c4eb2c696f3d1a6e6c9921cbd',
+    // 2026-08-13: generator + prisma:sync passed via `commands`.
+    'sha256-0c898eb1faf32792fc9d2593070c8421905882ba8d8f2aba9a69c74ce2dfa5d8',
+    // 2026-08-22: `basalt dev` documented.
+    'sha256-d09d583f1a39bffcb72f302c5f6c3e2651badea358ba38019238a4aa4b842545',
+    // 2026-09-19 (create-basalt ≤ 1.9): NODE_ENV defaulted before the app import.
+    'sha256-a0df89dee04091a9470f67968ff72cfc3bf64076c1bf3d141ae657c7438a94c8',
+]);
+export const hasProjectCommands = (content) => content.includes(PROJECT_COMMANDS_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}.
+ */
+export function patchBasaltBin(content) {
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    const shebang = lines[0]?.startsWith('#!') ? `${lines.shift()}\n` : '';
+    const body = lines.map((line) => {
+        const match = /^import \{ ([^}]+) \} from '([^']+)'$/.exec(line);
+        return match ? `const { ${match[1]} } = await import('${match[2]}')` : line;
+    });
+    const firstDynamic = body.findIndex((line) => line.startsWith('const {') && line.includes('= await import('));
+    if (firstDynamic >= 0 && !(body[firstDynamic] ?? '').includes("'../src/app.js'")) {
+        body.splice(firstDynamic, 0, '// The dev tools are imported dynamically, after the project commands above.');
+    }
+    return `${shebang}${PRELUDE}\n${body.join('\n')}`;
+}
+/** Where a bin/basalt.ts stands: already delegating, an untouched old template, or user code. */
+export function binStatus(content, manifestHash) {
+    if (content === undefined)
+        return 'absent';
+    if (hasProjectCommands(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
+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}`;

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { stdin, stdout } from 'node:process';
 import { createProject, describeResolution, detectPackageManager, resolveRunDefaults, runWizard, ttyPrompter, TargetNotEmptyError, WizardCancelledError, } from './index.js';
+import { basaltCommand, isProjectCommand, runProjectCommand } from './project/run.js';
 import { parseArgs, resolvesLatest, USAGE } from './args.js';
 import { envPrefix } from './templates.js';
 /** Runs a command inheriting stdio; resolves false on non-zero exit (never throws). */
@@ -16,12 +17,49 @@ function run(command, args, cwd) {
         child.on('close', (code) => resolve(code === 0));
     });
 }
+/** Runs a command and returns its trimmed stdout, or undefined (never throws). */
+function capture(command, args, cwd) {
+    return new Promise((resolve) => {
+        execFile(command, args, { cwd, shell: process.platform === 'win32', timeout: 10_000 }, (error, out) => {
+            resolve(error ? undefined : String(out).trim() || undefined);
+        });
+    });
+}
 /** Cleanly abort on Ctrl+C instead of dumping a Node AbortError stack trace. */
 function cancel() {
     stdout.write('\nCancelled.\n');
     process.exit(130); // 128 + SIGINT
 }
-const flags = parseArgs(process.argv.slice(2));
+const argv = process.argv.slice(2);
+// Project commands (update | add | doctor | info) operate on an EXISTING app.
+// They are selected by the first positional argument — those four words are
+// reserved, so a project literally named "update" is created with
+// --name=update. `--project` (the `basalt` script of apps without --cli) forces
+// project mode: `pnpm basalt` alone then prints the project-command help.
+const firstPositional = argv.find((token) => !token.startsWith('-'));
+if (argv.includes('--project') || isProjectCommand(firstPositional)) {
+    const code = await runProjectCommand(argv.filter((token) => token !== '--project'), {
+        cwd: process.cwd(),
+        out: { log: (line = '') => stdout.write(`${line}\n`), error: (line) => process.stderr.write(`${line}\n`) },
+        env: process.env,
+        interactive: Boolean(stdin.isTTY) && !process.env['CI'],
+        isTTY: Boolean(stdout.isTTY),
+        run,
+        capture,
+        confirm: async (message) => {
+            try {
+                return await ttyPrompter().confirm({ message, initial: true });
+            }
+            catch (error) {
+                if (error instanceof WizardCancelledError)
+                    cancel();
+                throw error;
+            }
+        },
+    });
+    process.exit(code);
+}
+const flags = parseArgs(argv);
 // Rich interactive wizard when nothing was specified in a terminal. CI, piped
 // input, and `--yes` keep the flag-driven path.
 if (!flags.yes && flags.name === undefined && stdin.isTTY) {
@@ -118,11 +156,12 @@ try {
         steps.push(`${pm} run db:migrate${flags.tenancy ? '   # creates the tables and seeds the demo tenant' : '   # creates the tables'}`);
     }
     steps.push(`${pm} run dev${flags.ui ? '        # API on :3000' : ''}`);
-    // `web` is wired as a pnpm workspace member (pnpm-workspace.yaml), so its dev
-    // server is launched with a pnpm filter regardless of the root package manager.
+    // `web` is a pnpm workspace member (pnpm-workspace.yaml); `dev:web` runs its
+    // dev server through a pnpm filter.
     if (flags.ui)
-        steps.push(`pnpm --filter ${result.options.name}-web dev   # UI on :5180`);
+        steps.push(`pnpm dev:web        # UI on :5180`);
     console.log(`\nNext steps:\n${steps.map((s) => `  ${s}`).join('\n')}\n`);
+    console.log(`Later: \`${basaltCommand(pm, 'update')}\` updates the dependencies, \`${basaltCommand(pm, 'add ui|cli|mcp')}\` adds a feature, \`${basaltCommand(pm, 'doctor')}\` checks the project.\n`);
 }
 catch (error) {
     if (error instanceof TargetNotEmptyError) {

package/dist/index.d.ts

@@ -64,8 +64,16 @@ export declare function resolveRunDefaults(input: {
     git: boolean;
     interactive: boolean;
 };
+/** Every file a scaffold with `options` writes (dependency ranges = the bundled fallbacks). */
+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>;
-export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, DEFAULT_MINIMUM_RELEASE_AGE_MINUTES, describeResolution, minimumReleaseAgeMinutes, resolveLatestVersions, registryUrl, type FreshVersion, type HeldBackVersion, type ResolveLatestOptions, type VersionResolution, } from './latest-versions.js';
+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';
+export { planAdd, ADDABLE_FEATURES, type AddPlan, type AddableFeature } from './project/add.js';
+export { runDoctor, type DoctorFinding } from './project/doctor.js';
+export { loadProject, NotABasaltAppError, type ProjectContext } from './project/context.js';
+export { MANIFEST_PATH, readManifest, hashContent, type ProjectManifest } from './project/manifest.js';
 export { runWizard, validateProjectName, PRESETS, FEATURES, type WizardResult, type WizardOptions, type FeatureKey } from './wizard.js';
 export { ttyPrompter, scriptedPrompter, WizardCancelledError, type Prompter, type Choice } from './prompt.js';

package/dist/index.js

@@ -2,7 +2,8 @@ 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 { uiFiles } from './templates-ui.js';
-import { applyVersions, collectDependencies, resolveLatestVersions, } from './latest-versions.js';
+import { createManifest, MANIFEST_PATH, serializeManifest } from './project/manifest.js';
+import { resolveFileVersions } from './latest-versions.js';
 export class TargetNotEmptyError extends Error {
     constructor(dir) {
         super(`Target directory "${dir}" already exists and is not empty.`);
@@ -35,23 +36,9 @@ export function resolveRunDefaults(input) {
         git: input.git ?? interactive,
     };
 }
-/** Generates a ready-to-run Basalt app. Does not install dependencies. */
-export async function createProject(input) {
-    const options = {
-        name: input.name,
-        tenancy: input.tenancy ?? true,
-        auth: input.auth ?? true,
-        billing: input.billing ?? false,
-        ui: input.ui ?? false,
-        cli: input.cli ?? false,
-        mcp: input.mcp ?? false,
-        prisma: input.prisma ?? false,
-    };
-    const dir = resolve(input.dir ?? input.name);
-    const existing = await readdir(dir).catch(() => null);
-    if (existing && existing.length > 0)
-        throw new TargetNotEmptyError(dir);
-    const files = {
+/** Every file a scaffold with `options` writes (dependency ranges = the bundled fallbacks). */
+export function scaffoldFiles(options) {
+    return {
         'package.json': packageJson(options),
         'tsconfig.json': tsconfigJson(options),
         '.env.example': envExample(options),
@@ -78,13 +65,26 @@ export async function createProject(input) {
         ...(options.mcp ? { '.mcp.json': mcpJson(options) } : {}),
         ...(options.ui ? uiFiles(options) : {}),
     };
-    let versions;
-    if (input.resolveLatest) {
-        const manifests = Object.keys(files).filter((path) => path === 'package.json' || path.endsWith('/package.json'));
-        versions = await resolveLatestVersions(collectDependencies(manifests.map((path) => files[path])), input.registry);
-        for (const path of manifests)
-            files[path] = applyVersions(files[path], versions.versions);
-    }
+}
+/** Generates a ready-to-run Basalt app. Does not install dependencies. */
+export async function createProject(input) {
+    const options = {
+        name: input.name,
+        tenancy: input.tenancy ?? true,
+        auth: input.auth ?? true,
+        billing: input.billing ?? false,
+        ui: input.ui ?? false,
+        cli: input.cli ?? false,
+        mcp: input.mcp ?? false,
+        prisma: input.prisma ?? false,
+    };
+    const dir = resolve(input.dir ?? input.name);
+    const existing = await readdir(dir).catch(() => null);
+    if (existing && existing.length > 0)
+        throw new TargetNotEmptyError(dir);
+    const files = scaffoldFiles(options);
+    const versions = input.resolveLatest ? await resolveFileVersions(files, input.registry) : undefined;
+    files[MANIFEST_PATH] = serializeManifest(createManifest(options, files));
     for (const [path, content] of Object.entries(files)) {
         const target = join(dir, path);
         await mkdir(dirname(target), { recursive: true });
@@ -92,6 +92,12 @@ export async function createProject(input) {
     }
     return { dir, files: Object.keys(files).sort(), options, ...(versions ? { versions } : {}) };
 }
-export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, DEFAULT_MINIMUM_RELEASE_AGE_MINUTES, describeResolution, minimumReleaseAgeMinutes, resolveLatestVersions, registryUrl, } from './latest-versions.js';
+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';
+export { planAdd, ADDABLE_FEATURES } from './project/add.js';
+export { runDoctor } from './project/doctor.js';
+export { loadProject, NotABasaltAppError } from './project/context.js';
+export { MANIFEST_PATH, readManifest, hashContent } from './project/manifest.js';
 export { runWizard, validateProjectName, PRESETS, FEATURES } from './wizard.js';
 export { ttyPrompter, scriptedPrompter, WizardCancelledError } from './prompt.js';