create-basalt 1.9.0 → 1.11.0

package/dist/bin-template.js

@@ -0,0 +1,291 @@
+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
+}
+`;
+/**
+ * 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 }
+  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 (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')
+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 } = ${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
+// 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 }).catch(explainBootFailure))
+`;
+}
+/**
+ * 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',
+    // 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 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) {
+    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);
+        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')}`;
+}
+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) && 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 (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}`);
+    }
+    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

@@ -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) {
@@ -114,15 +152,17 @@ 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`);
+        // .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${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/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;

package/dist/dev-entry.js

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

package/dist/index.d.ts

@@ -64,8 +64,22 @@ 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';
+/**
+ * A random APP_SECRET for the development .env: 48 random bytes, base64url —
+ * redrawn in the (rare) case it happens to contain a word `secret()` rejects
+ * as a placeholder (`test`, `0000`, …).
+ */
+export declare function generateAppSecret(random?: (size: number) => Buffer): string;
+export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, DEFAULT_MINIMUM_RELEASE_AGE_MINUTES, describeResolution, resolveFileVersions, minimumReleaseAgeMinutes, resolveLatestVersions, registryUrl, type FreshVersion, type HeldBackVersion, type ResolveLatestOptions, type VersionResolution, } from './latest-versions.js';
+export { runProjectCommand, PROJECT_COMMANDS, isProjectCommand, type ProjectCommandDeps } from './project/run.js';
+export { planUpdate, type UpdatePlan, type UpdateEntry } from './project/update.js';
+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

@@ -1,8 +1,11 @@
+import { randomBytes } from 'node:crypto';
 import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { appTest, appTs, dbTs, devTs, dockerignore, envExample, envTs, gitignore, mcpJson, basaltBin, packageJson, pnpmWorkspaceYaml, prismaConfigTs, prismaSchema, prismaSeedTs, readme, routesTs, serverTs, tsconfigJson, } from './templates.js';
+import { appTest, appTs, dbTs, devEnvFile, devTs, 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 { INSECURE_SECRET } from './project/doctor.js';
+import { createManifest, MANIFEST_PATH, serializeManifest } from './project/manifest.js';
+import { resolveFileVersions } from './latest-versions.js';
 export class TargetNotEmptyError extends Error {
     constructor(dir) {
         super(`Target directory "${dir}" already exists and is not empty.`);
@@ -35,23 +38,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,20 +67,56 @@ 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));
+    // A ready-to-use .env for development, so `pnpm dev` / `pnpm basalt` boot
+    // without a copy step. Written after the manifest on purpose: it is
+    // git-ignored local state (with a generated secret), not a template file.
+    files['.env'] = devEnvFile(options, generateAppSecret());
     for (const [path, content] of Object.entries(files)) {
         const target = join(dir, path);
         await mkdir(dirname(target), { recursive: true });
-        await writeFile(target, content);
+        // .env holds a secret: owner-only, like `umask 077` would make it.
+        await writeFile(target, content, path === '.env' ? { mode: 0o600 } : undefined);
     }
     return { dir, files: Object.keys(files).sort(), options, ...(versions ? { versions } : {}) };
 }
-export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, DEFAULT_MINIMUM_RELEASE_AGE_MINUTES, describeResolution, minimumReleaseAgeMinutes, resolveLatestVersions, registryUrl, } from './latest-versions.js';
+/**
+ * A random APP_SECRET for the development .env: 48 random bytes, base64url —
+ * redrawn in the (rare) case it happens to contain a word `secret()` rejects
+ * as a placeholder (`test`, `0000`, …).
+ */
+export function generateAppSecret(random = randomBytes) {
+    for (;;) {
+        const value = random(48).toString('base64url');
+        if (!INSECURE_SECRET.test(value))
+            return value;
+    }
+}
+export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, DEFAULT_MINIMUM_RELEASE_AGE_MINUTES, describeResolution, resolveFileVersions, minimumReleaseAgeMinutes, resolveLatestVersions, registryUrl, } from './latest-versions.js';
+export { runProjectCommand, PROJECT_COMMANDS, isProjectCommand } from './project/run.js';
+export { planUpdate } from './project/update.js';
+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';

package/dist/latest-versions.d.ts

@@ -108,10 +108,34 @@ export declare function registryUrl(explicit?: string, env?: NodeJS.ProcessEnv):
 export declare const latestUrl: (registry: string, name: string) => string;
 /** `<registry>/<name>` — the packument (probed with HEAD for its `last-modified`). */
 export declare const packumentUrl: (registry: string, name: string) => string;
+/** What the registry says about one package (see {@link lookupLatestVersions}). */
+export interface LatestInfo {
+    /** The `latest` dist-tag (stable releases only), or undefined when the lookup failed. */
+    latest?: string;
+    /** `peerDependencies` declared by that latest version. */
+    peers: Record<string, string>;
+    /**
+     * Release age of `latest` against the window: `mature` (provably older, or
+     * not probed), `recent` (inside the window) or `unknown` (could not prove it).
+     */
+    age: 'mature' | 'recent' | 'unknown';
+}
+/**
+ * The shared registry primitive behind both the scaffold and `create-basalt
+ * update`: looks up `latest` for every name through a small pool of parallel
+ * requests (one retry on transient failures, a global time cap) and, when
+ * `shouldProbe(name, latest)` says the version would actually be used, probes
+ * its release age against the window. Never throws — a package the registry
+ * cannot answer for comes back without `latest`.
+ */
+export declare function lookupLatestVersions(names: readonly string[], shouldProbe: (name: string, latest: string) => boolean, options?: ResolveLatestOptions): Promise<{
+    results: Map<string, LatestInfo>;
+    registry: string;
+}>;
 /**
  * Resolves the latest published version of every package in `fallbacks`
- * (name → fallback range) through a small pool of parallel requests. Never throws: a package the registry
- * cannot answer for keeps its fallback range and is listed in `failed`.
+ * (name → fallback range). Never throws: a package the registry cannot answer
+ * for keeps its fallback range and is listed in `failed`.
  */
 export declare function resolveLatestVersions(fallbacks: Readonly<Record<string, string>>, options?: ResolveLatestOptions): Promise<VersionResolution>;
 /**
@@ -119,6 +143,11 @@ export declare function resolveLatestVersions(fallbacks: Readonly<Record<string,
  * resolved versions (keys, order and every other field untouched).
  */
 export declare function applyVersions(packageJsonText: string, versions: Readonly<Record<string, string>>): string;
+/**
+ * Resolves the latest published versions for every package.json in `files`
+ * (in place) — the scaffold's registry policy, shared with `create-basalt add`.
+ */
+export declare function resolveFileVersions(files: Record<string, string>, registry?: ResolveLatestOptions): Promise<VersionResolution>;
 /** Every dependency/devDependency name → range declared in the given package.json texts. */
 export declare function collectDependencies(packageJsonTexts: readonly string[]): Record<string, string>;
 /** Human-readable lines summarizing a resolution (for the CLI). */