create-basalt 1.9.0 → 1.11.0

package/dist/templates.js

@@ -1,5 +1,6 @@
 import { THIRD_PARTY_VERSIONS } from './latest-versions.js';
 import { SCAFFOLD_VERSIONS } from './versions.js';
+export { basaltBin } from './bin-template.js';
 export { SCAFFOLD_VERSIONS } from './versions.js';
 export { THIRD_PARTY_VERSIONS } from './latest-versions.js';
 /**
@@ -28,6 +29,10 @@ export const thirdPartyVersionOf = (pkg) => {
     }
     return range;
 };
+/** The root `basalt` script of an app without `--cli`: create-basalt's project commands. */
+export const BASALT_PROJECT_SCRIPT = 'create-basalt --project';
+/** The root `dev:web` script of a `--ui` app (web/ is a pnpm workspace member). */
+export const webDevScript = (options) => `pnpm --filter ${options.name}-web dev`;
 /** True when the scaffold binds users to the tenant they act on (tenancy + auth). */
 export const enforcesMembership = (options) => options.tenancy && options.auth;
 export function packageJson(options) {
@@ -76,6 +81,9 @@ export function packageJson(options) {
     }
     const devDependencies = {
         '@basaltkit/testing': versionOf('@basaltkit/testing'),
+        // The project commands (\`pnpm basalt update | add | doctor | info\`) — dev
+        // tooling with no dependencies of its own, never imported by the app.
+        'create-basalt': versionOf('create-basalt'),
     };
     for (const pkg of ['@types/node', 'pino-pretty', 'tsx', 'typescript', 'vitest']) {
         devDependencies[pkg] = thirdPartyVersionOf(pkg);
@@ -107,7 +115,11 @@ export function packageJson(options) {
             start: 'tsx src/server.ts',
             test: 'vitest run',
             typecheck: 'tsc --noEmit',
-            ...(options.cli ? { basalt: 'tsx bin/basalt.ts' } : {}),
+            // With --cli, bin/basalt.ts serves the generators AND hands the project
+            // commands to create-basalt; without it, \`pnpm basalt update\` goes to
+            // create-basalt directly (\`create-basalt add cli\` swaps the script).
+            basalt: options.cli ? 'tsx bin/basalt.ts' : BASALT_PROJECT_SCRIPT,
+            ...(options.ui ? { 'dev:web': webDevScript(options) } : {}),
             ...(options.prisma
                 ? {
                     // Generate right after install so `pnpm typecheck` has the client
@@ -210,10 +222,19 @@ export function envPrefix(name) {
     base = base.slice(start, end);
     return base === '' || /^\d/.test(base) ? `APP_${base}` : base;
 }
+/**
+ * The opening lines of `.env.example`. Up to create-basalt 1.10 they read
+ * {@link LEGACY_ENV_EXAMPLE_LEAD} ("nothing loads this file"); `update`
+ * swaps that for this one in existing apps.
+ */
+export const ENV_EXAMPLE_LEAD = `# Development: copy this file to .env — \`pnpm dev\` and \`pnpm basalt\` load it
+# automatically (a new app already has one). \`pnpm start\` (production) does
+# NOT: there the variables come from the environment (or \`node --env-file\`).`;
+export const LEGACY_ENV_EXAMPLE_LEAD = `# Nothing loads this file for you: copy it to .env and start with
+# \`node --env-file=.env\` / \`tsx --env-file=.env\`, or export the variables.`;
 export function envExample(options) {
     const prefix = envPrefix(options.name);
-    return `# Nothing loads this file for you: copy it to .env and start with
-# \`node --env-file=.env\` / \`tsx --env-file=.env\`, or export the variables.
+    return `${ENV_EXAMPLE_LEAD}
 # --env-file NEVER overrides a variable already exported in your shell: if
 # another project exported PORT or DATABASE_URL, an app reading the generic
 # name would silently use THAT one. That is why src/env.ts reads app-prefixed
@@ -240,6 +261,20 @@ ${prefix}_DATABASE_URL=postgres://postgres:postgres@localhost:5432/${databaseNam
 # ${prefix}_DATABASE_URL=postgres://user:pass@localhost:5432/${options.name.replace(/^@[^/]+\//, '')}
 `}`;
 }
+/**
+ * The `.env` a new app starts with (git-ignored, never in the manifest): the
+ * values of `.env.example` for local development plus — with auth — a freshly
+ * generated APP_SECRET, so `pnpm dev` works without a copy step.
+ */
+export function devEnvFile(options, appSecret) {
+    const prefix = envPrefix(options.name);
+    const example = envExample(options);
+    const body = example.slice(example.indexOf(`${prefix}_PORT=`));
+    return `# Local development settings, generated by create-basalt from .env.example.
+# Git-ignored: never commit it. \`pnpm dev\` and \`pnpm basalt\` load it (a
+# variable exported in your shell wins); \`pnpm start\` (production) does not.
+${body.replace(`# ${prefix}_APP_SECRET=\n`, `${prefix}_APP_SECRET=${appSecret}\n`)}`;
+}
 /** A PostgreSQL-safe database name derived from the project name. */
 export function databaseName(name) {
     return name.replace(/^@[^/]+\//, '').replace(/[^a-zA-Z0-9]+/g, '_').toLowerCase();
@@ -514,45 +549,31 @@ for (const signal of ['SIGINT', 'SIGTERM'] as const) {
 `;
 }
 /**
- * `pnpm dev` entrypoint. Opts into NODE_ENV=development (dev secret defaults,
- * pretty logs) unless NODE_ENV is already set, then starts the server. Kept out
- * of server.ts on purpose: `pnpm start` runs server.ts directly, where an unset
- * NODE_ENV counts as production and secrets are required (fail-closed).
+ * `pnpm dev` entrypoint. Loads `.env` (when present) with `node --env-file`
+ * semantics — an exported variable wins, the file only fills in what is
+ * missing — and opts into NODE_ENV=development (dev secret defaults, pretty
+ * logs) unless NODE_ENV is already set, then starts the server. Kept out of
+ * server.ts on purpose: `pnpm start` runs server.ts directly, where nothing
+ * loads `.env` (production configuration comes from the real environment) and
+ * an unset NODE_ENV counts as production, so secrets are required (fail-closed).
  */
 export function devTs() {
     return `// Development entrypoint (\`pnpm dev\`). \`pnpm start\` runs server.ts directly,
 // where an unset NODE_ENV counts as production: secrets are then required.
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+// Development loads .env (when present) like \`node --env-file=.env\`: a variable
+// already exported in your shell still wins, the file only fills in what is
+// missing. \`pnpm start\` (production) never loads it — there the configuration
+// comes from the real environment.
+const envFile = fileURLToPath(new URL('../.env', import.meta.url))
+if (existsSync(envFile)) process.loadEnvFile(envFile)
+
 process.env['NODE_ENV'] ??= 'development'
 await import('./server.js')
 `;
 }
-export function basaltBin() {
-    return `#!/usr/bin/env node
-import { runCli } from '@basaltkit/cli'
-import { generatorCommands } from '@basaltkit/generator'
-import { prismaSyncCommand } from '@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 }))
-`;
-}
 /**
  * The models each `@basaltkit/<domain>-prisma` package needs, copied VERBATIM
  * from that package's reference `prisma/schema.prisma` — the same blocks
@@ -807,9 +828,9 @@ export function prismaConfigTs(options) {
     return `import { loadEnvFile } from 'node:process'
 import { defineConfig } from 'prisma/config'
 
-// Prisma loads no .env for you (neither does the app — see src/env.ts). This
-// mirrors \`node --env-file=.env\`: a variable already exported in your shell
-// still wins, the file only fills in what is missing.
+// Prisma loads no .env for you. Like the app's dev entrypoints (src/dev.ts,
+// bin/basalt.ts) this mirrors \`node --env-file=.env\`: a variable already
+// exported in your shell still wins, the file only fills in what is missing.
 try {
   loadEnvFile('.env')
 } catch {
@@ -962,7 +983,7 @@ Included: ${features.join(' · ')}.
 \`\`\`bash
 pnpm install${options.prisma
         ? `
-# point ${envPrefix(options.name)}_DATABASE_URL at a PostgreSQL database (.env.example), then
+# start PostgreSQL — .env points ${envPrefix(options.name)}_DATABASE_URL at localhost:5432 — then
 pnpm db:migrate # create the tables${options.tenancy ? ` (runs the seed too)` : ''}`
         : ''}
 pnpm dev        # API on http://localhost:3000
@@ -1020,16 +1041,18 @@ scaffold with \`--cli\` — \`pnpm basalt prisma:sync\` does the merge for you.)
         : ''}
 ## Environment
 
-\`src/env.ts\` validates \`process.env\` — nothing loads \`.env\` for you. Copy
-\`.env.example\` to \`.env\` and launch with \`--env-file=.env\` (Node/tsx), or
-export the variables.
+\`src/env.ts\` validates \`process.env\`. For development, ${options.cli ? '`pnpm dev` and `pnpm basalt` load' : '`pnpm dev` loads'} \`.env\`
+automatically — create-basalt wrote one for you: git-ignored, with local
+values${options.auth ? ' and a generated secret' : ''}. \`.env.example\` is its committed template.
+\`pnpm start\` (production, \`src/server.ts\`) loads **nothing**: there the
+variables come from the real environment (or \`node --env-file=.env\`).
 
 The variables are **app-prefixed**: \`${envPrefix(options.name)}_PORT\`,
 \`${envPrefix(options.name)}_HOST\`, \`${envPrefix(options.name)}_LOG_LEVEL\`${options.auth ? `, \`${envPrefix(options.name)}_APP_SECRET\`` : ''}${options.prisma ? `, \`${envPrefix(options.name)}_DATABASE_URL\`` : ''}. \`NODE_ENV\` is never prefixed.
 
-Why: **\`--env-file\` never overrides a variable that is already exported.** In a
-shell 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
+Why: **loading \`.env\` (like \`--env-file\`) never overrides a variable that is
+already exported.** In a shell 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. \`src/env.ts\` therefore passes \`prefix: '${envPrefix(options.name)}'\` to
 \`defineEnv\`: each variable is read as \`${envPrefix(options.name)}_<NAME>\` first and
 **falls back** to the bare \`<NAME>\`, so a deployment that already exports the
@@ -1044,8 +1067,24 @@ database and \`DATABASE_URL\` is read as \`${envPrefix(options.name)}_DATABASE_U
 To drop the fallback entirely (prefixed names only), write
 \`prefix: { value: '${envPrefix(options.name)}', fallback: false }\`. When in doubt about what
 your shell exports: \`env | grep DATABASE_URL\`.
-${options.cli
-        ? `
+
+## Keeping it up to date
+
+\`\`\`bash
+pnpm basalt update          # dependencies → latest (framework always; third-party within its major)
+pnpm basalt update --dry    # preview the table, write nothing
+pnpm basalt add ui          # add a feature later: ui, cli, mcp
+pnpm basalt doctor          # Node, package manager, versions, env and Prisma checks
+\`\`\`
+
+\`.basalt/project.json\` records what create-basalt generated (options and file
+hashes) — commit it: \`add\` and \`update\` use it to tell untouched template
+files from the ones you edited.
+${options.cli ? readmeCliSection(options) : ''}${options.ui ? readmeUiSection(options) : ''}${options.mcp ? readmeMcpSection(options) : ''}`;
+}
+/** README section for the \`basalt\` CLI (also appended by \`create-basalt add cli\`). */
+export function readmeCliSection(_options) {
+    return `
 ## The \`basalt\` CLI
 
 \`\`\`bash
@@ -1069,21 +1108,25 @@ node_modules/.bin/tsx bin/basalt.ts make:resource Project
 
 or set \`verifyDepsBeforeRun: warn\` in \`pnpm-workspace.yaml\` (a conscious
 choice: you then run \`pnpm install\` yourself after dependency changes).
-`
-        : ''}${options.ui
-        ? `
+`;
+}
+/** README section for the web/ frontend (also appended by \`create-basalt add ui\`). */
+export function readmeUiSection(options) {
+    return `
 ## Web UI
 
 \`\`\`bash
-pnpm dev                       # terminal 1 — API on :3000
-pnpm --filter ${options.name}-web dev   # terminal 2 — UI on http://localhost:5180
+pnpm dev        # terminal 1 — API on :3000
+pnpm dev:web    # terminal 2 — UI on http://localhost:5180 (pnpm --filter ${options.name}-web dev)
 \`\`\`
 
 Open <http://localhost:5180>. The Vite dev server proxies \`/api\` to the API,
 so there is no CORS to configure${options.auth ? '. Register, then sign in' : ''}.
-`
-        : ''}${options.mcp
-        ? `
+`;
+}
+/** README section for the MCP server (also appended by \`create-basalt add mcp\`). */
+export function readmeMcpSection(_options) {
+    return `
 ## MCP server
 
 Read-only routes marked with \`meta.mcp\` in \`src/routes.ts\` (the overview and
@@ -1109,8 +1152,7 @@ app's runtime) with MCP clients such as Claude Code and Claude Desktop. It expos
 \`basalt_make\` (preview by default, writes confined to this project) plus workflow
 prompts. Claude Code picks up \`.mcp.json\` automatically; for Claude Desktop add the
 same server to its config with \`--cwd=<absolute project path>\`.
-`
-        : ''}`;
+`;
 }
 /**
  * A Claude Code / generic MCP client config that registers the dev-only
@@ -1183,10 +1225,12 @@ export function pnpmWorkspaceYaml(options) {
         : ''}allowBuilds:
   esbuild: true
   msgpackr-extract: false
-# @basaltkit/* releases in lockstep, often within hours — exclude the scope from
-# pnpm's minimumReleaseAge policy so \`pnpm up\` is never blocked on a fresh release.
+# @basaltkit/* releases in lockstep, often within hours — exclude the scope (and
+# create-basalt, which serves \`pnpm basalt update\`) from pnpm's minimumReleaseAge
+# policy so an update is never blocked on a fresh release.
 minimumReleaseAgeExclude:
   - '@basaltkit/*'
+  - create-basalt
 # To let specific versions of ONE package bypass the policy, write ONE entry
 # with a \`||\` union. pnpm evaluates this list first match wins by package
 # name, so a second '<name>@<version>' entry for the same package is ignored:

package/dist/versions.js

@@ -4,10 +4,10 @@
 export const SCAFFOLD_VERSIONS = {
     '@basaltkit/admin': '^2.0.0',
     '@basaltkit/admin-shadcn': '^1.1.0',
-    '@basaltkit/ai-mcp': '^0.2.0',
-    '@basaltkit/auth': '^4.0.0',
+    '@basaltkit/ai-mcp': '^0.3.0',
+    '@basaltkit/auth': '^4.1.0',
     '@basaltkit/auth-prisma': '^2.0.0',
-    '@basaltkit/cli': '^1.2.0',
+    '@basaltkit/cli': '^1.3.0',
     '@basaltkit/config': '^1.1.0',
     '@basaltkit/core': '^1.5.0',
     '@basaltkit/env': '^3.1.0',
@@ -15,14 +15,15 @@ export const SCAFFOLD_VERSIONS = {
     '@basaltkit/fastify': '^2.5.0',
     '@basaltkit/generator': '^1.5.0',
     '@basaltkit/logger': '^1.3.0',
-    '@basaltkit/mcp': '^4.0.0',
+    '@basaltkit/mcp': '^5.0.0',
     '@basaltkit/prisma': '^3.0.0',
     '@basaltkit/sdk': '^2.1.0',
     '@basaltkit/subscriptions': '^5.0.0',
     '@basaltkit/subscriptions-prisma': '^3.0.0',
     '@basaltkit/teams': '^4.0.0',
     '@basaltkit/teams-prisma': '^1.1.0',
-    '@basaltkit/tenancy': '^3.0.0',
+    '@basaltkit/tenancy': '^3.1.0',
     '@basaltkit/tenancy-prisma': '^2.0.0',
     '@basaltkit/testing': '^2.0.0',
+    'create-basalt': '^1.11.0',
 };

package/dist/wizard.js

@@ -11,9 +11,9 @@ export const FEATURES = [
 ];
 export const PRESETS = [
     { value: 'saas', label: 'SaaS starter', hint: 'tenancy + auth + billing + database + CLI', features: ['tenancy', 'auth', 'billing', 'prisma', 'cli'] },
-    { value: 'api', label: 'API only', hint: 'auth + MCP, no tenancy or UI', features: ['auth', 'mcp'] },
+    { value: 'api', label: 'API only', hint: 'auth + MCP + CLI, no tenancy or UI', features: ['auth', 'mcp', 'cli'] },
     { value: 'full', label: 'Full stack', hint: 'everything + web UI', features: ['tenancy', 'auth', 'billing', 'prisma', 'ui', 'cli', 'mcp'] },
-    { value: 'minimal', label: 'Minimal', hint: 'no batteries, add them later', features: [] },
+    { value: 'minimal', label: 'Minimal', hint: 'just the CLI, add the rest later', features: ['cli'] },
     { value: 'custom', label: 'Custom', hint: 'pick features yourself', features: null },
 ];
 const PACKAGE_MANAGERS = [
@@ -59,7 +59,7 @@ export async function runWizard(prompter, options = {}) {
         (await prompter.multiselect({
             message: 'Select features',
             choices: FEATURES,
-            initial: ['tenancy', 'auth'],
+            initial: ['tenancy', 'auth', 'cli'],
         })));
     let pm = await prompter.select({
         message: 'Package manager',

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "create-basalt",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "engines": {
     "node": ">=22.5.0"
   },
-  "description": "Scaffold a production-shaped Basalt SaaS app: npm create basalt my-saas [--billing] [--ui] [--cli] [--install] [--git]",
+  "description": "Scaffold a production-shaped Basalt SaaS app (npm create basalt my-saas [--billing] [--ui] [--cli] [--install] [--git]) — then keep it current: create-basalt update | add | doctor | info",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -30,26 +30,26 @@
     "typescript": "^7.0.2",
     "vitest": "^5.0.1",
     "zod": "^4.6.5",
-    "@basaltkit/auth": "^4.0.0",
+    "@basaltkit/auth": "^4.1.0",
     "@basaltkit/auth-prisma": "^2.0.0",
-    "@basaltkit/cli": "^1.2.5",
     "@basaltkit/config": "^1.1.2",
+    "@basaltkit/cli": "^1.3.0",
     "@basaltkit/core": "^1.5.0",
     "@basaltkit/env": "^3.1.1",
     "@basaltkit/events": "^1.3.0",
     "@basaltkit/fastify": "^2.5.0",
     "@basaltkit/generator": "^1.5.0",
     "@basaltkit/logger": "^1.3.0",
-    "@basaltkit/mcp": "^4.0.0",
+    "@basaltkit/mcp": "^5.0.0",
     "@basaltkit/prisma": "^3.0.0",
     "@basaltkit/subscriptions": "^5.0.0",
     "@basaltkit/subscriptions-prisma": "^3.0.0",
     "@basaltkit/teams": "^4.0.0",
     "@basaltkit/teams-prisma": "^1.1.0",
-    "@basaltkit/tenancy": "^3.0.0",
-    "@basaltkit/tenancy-prisma": "^2.0.0",
+    "@basaltkit/tenancy": "^3.1.0",
+    "@basaltkit/tsconfig": "^0.24.0",
     "@basaltkit/testing": "^2.0.3",
-    "@basaltkit/tsconfig": "^0.24.0"
+    "@basaltkit/tenancy-prisma": "^2.0.0"
   },
   "publishConfig": {
     "access": "public"