create-basalt 1.9.0 → 1.10.0

package/dist/project/term.js

@@ -0,0 +1,39 @@
+/**
+ * Output for the project commands: an injectable sink (tests capture it) and
+ * ANSI colors that switch off for `NO_COLOR`, `TERM=dumb` and non-TTY output
+ * (`FORCE_COLOR` forces them on).
+ */
+export function colorsEnabled(env, isTTY) {
+    if (env['NO_COLOR'] !== undefined && env['NO_COLOR'] !== '')
+        return false;
+    const force = env['FORCE_COLOR'];
+    if (force !== undefined)
+        return force !== '0' && force !== 'false';
+    if (env['TERM'] === 'dumb')
+        return false;
+    return isTTY;
+}
+export function makeColors(enabled) {
+    const wrap = (open, close) => (text) => enabled ? `\x1b[${open}m${text}\x1b[${close}m` : text;
+    return {
+        enabled,
+        bold: wrap(1, 22),
+        dim: wrap(2, 22),
+        red: wrap(31, 39),
+        green: wrap(32, 39),
+        yellow: wrap(33, 39),
+        cyan: wrap(36, 39),
+    };
+}
+/** Visible width of a string (ANSI escapes excluded). */
+// eslint-disable-next-line no-control-regex
+const visible = (text) => text.replace(/\x1b\[\d+m/g, '').length;
+/** A plain left-aligned table (header row + rows), two spaces between columns. */
+export function table(header, rows, colors) {
+    const widths = header.map((cell, i) => Math.max(visible(cell), ...rows.map((row) => visible(row[i] ?? ''))));
+    const line = (cells) => cells
+        .map((cell, i) => (i === cells.length - 1 ? cell : cell + ' '.repeat((widths[i] ?? 0) - visible(cell))))
+        .join('  ')
+        .trimEnd();
+    return [colors.dim(line(header)), ...rows.map(line)];
+}

package/dist/project/update.d.ts

@@ -0,0 +1,101 @@
+import { type ResolveLatestOptions } from '../latest-versions.js';
+import type { ProjectContext } from './context.js';
+import { type DependencySection } from './package-json.js';
+import { type Colors } from './term.js';
+import { type UpdateKind } from './semver.js';
+/**
+ * `create-basalt update`: move an existing app's dependencies to the latest
+ * published versions under the SAME registry policy as a new scaffold
+ * (`lookupLatestVersions`, shared with latest-versions.ts):
+ *
+ * - `@basaltkit/*` and `create-basalt` → the registry's `latest`, across majors
+ *   (each framework major is flagged with a pointer to its changelog);
+ * - third-party → the newest release on the app's CURRENT major; a newer major
+ *   is reported and only taken with `--major`;
+ * - a third-party version not provably older than the release-age window
+ *   (pnpm `minimumReleaseAge`) keeps the current range — the install would
+ *   otherwise refuse it.
+ *
+ * Planning is pure (no writes); {@link UpdatePlan.files} holds the full
+ * before/after of every file the plan would write.
+ */
+export declare const DOCS_UPGRADING_URL = "https://basaltkit-docs.pages.dev/guide/whats-new#upgrading";
+/** The CHANGELOG of a framework package in the Basalt repository. */
+export declare function changelogUrl(name: string): string;
+export type EntryStatus = 
+/** Will be written. */
+'update'
+/** Already at latest. */
+ | 'current'
+/** Third-party latest is a new major (needs --major). */
+ | 'held-major'
+/** Third-party latest is inside the release-age window (or its age is unknown). */
+ | 'too-fresh'
+/** The registry did not answer. */
+ | 'failed'
+/** A range `update` does not rewrite (workspace:, tags, git, >=, …). */
+ | 'unmanaged'
+/** The app is already ahead of `latest` (a pre-release, a local build). */
+ | 'ahead'
+/** Filtered out by --only. */
+ | 'skipped';
+export interface UpdateEntry {
+    file: string;
+    section: DependencySection;
+    name: string;
+    current: string;
+    latest?: string;
+    /** New range (same style as `current`) when status is `update`. */
+    target?: string;
+    kind?: UpdateKind;
+    status: EntryStatus;
+    framework: boolean;
+    /** For `too-fresh`: proven recent, or age unknown. */
+    freshness?: 'recent' | 'unknown';
+}
+export interface FileWrite {
+    before: string | undefined;
+    after: string;
+}
+export interface UpdatePlan {
+    entries: UpdateEntry[];
+    /** Entries that change (status `update`). */
+    updates: UpdateEntry[];
+    /** Every file this plan writes, keyed by project-relative path. */
+    files: Record<string, FileWrite>;
+    /** Project tooling the plan also upgrades (bin/basalt.ts, create-basalt devDependency, …). */
+    tooling: string[];
+    /** Steps the user has to do by hand (printed, never applied). */
+    manual: string[];
+    /** Peer-range conflicts and registry failures worth reading before applying. */
+    warnings: string[];
+    /** Framework packages crossing a major: name → changelog URL. */
+    majors: {
+        name: string;
+        from: string;
+        to: string;
+        changelog: string;
+    }[];
+    registry: string;
+}
+export interface UpdateOptions {
+    /** Allow third-party packages to cross a major. */
+    major?: boolean;
+    /** `@basaltkit`: only the framework packages (and create-basalt). */
+    only?: 'basaltkit';
+    /** Also upgrade project tooling (default true). */
+    tooling?: boolean;
+    registry?: ResolveLatestOptions;
+}
+export declare class RegistryUnavailableError extends Error {
+    constructor(registry: string);
+}
+/** `minimumReleaseAge: <n>` from pnpm-workspace.yaml, when set. */
+export declare function workspaceReleaseAge(yaml: string | undefined): number | undefined;
+/** Whether pnpm-workspace.yaml's minimumReleaseAgeExclude lists `entry`. */
+export declare function workspaceExcludes(yaml: string | undefined, entry: string): boolean;
+/** Adds `entry` to minimumReleaseAgeExclude right after the `@basaltkit/*` line; undefined when that line is absent. */
+export declare function addWorkspaceExclude(yaml: string, entry: string): string | undefined;
+export declare function planUpdate(ctx: ProjectContext, options?: UpdateOptions): Promise<UpdatePlan>;
+/** The plan as terminal lines: the update table, then notes, tooling, warnings and majors. */
+export declare function renderUpdatePlan(plan: UpdatePlan, colors: Colors): string[];

package/dist/project/update.js

@@ -0,0 +1,302 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { binStatus, MANUAL_BIN_SNIPPET, patchBasaltBin } from '../bin-template.js';
+import { alwaysLatest, lookupLatestVersions, minimumReleaseAgeMinutes, } from '../latest-versions.js';
+import { BASALT_PROJECT_SCRIPT } from '../templates.js';
+import { extendManifest, MANIFEST_PATH, serializeManifest } from './manifest.js';
+import { DEPENDENCY_SECTIONS, mergePackageJson, setDependencyRange, } from './package-json.js';
+import { table } from './term.js';
+import { compareVersions, parseSimpleRange, parseVersion, satisfies, updateKind } from './semver.js';
+/**
+ * `create-basalt update`: move an existing app's dependencies to the latest
+ * published versions under the SAME registry policy as a new scaffold
+ * (`lookupLatestVersions`, shared with latest-versions.ts):
+ *
+ * - `@basaltkit/*` and `create-basalt` → the registry's `latest`, across majors
+ *   (each framework major is flagged with a pointer to its changelog);
+ * - third-party → the newest release on the app's CURRENT major; a newer major
+ *   is reported and only taken with `--major`;
+ * - a third-party version not provably older than the release-age window
+ *   (pnpm `minimumReleaseAge`) keeps the current range — the install would
+ *   otherwise refuse it.
+ *
+ * Planning is pure (no writes); {@link UpdatePlan.files} holds the full
+ * before/after of every file the plan would write.
+ */
+export const DOCS_UPGRADING_URL = 'https://basaltkit-docs.pages.dev/guide/whats-new#upgrading';
+const REPO_URL = 'https://github.com/basaltkit/basalt';
+/** The CHANGELOG of a framework package in the Basalt repository. */
+export function changelogUrl(name) {
+    const dir = name === 'create-basalt' ? 'create-app' : name.replace(/^@basaltkit\//, '');
+    return `${REPO_URL}/blob/main/packages/${dir}/CHANGELOG.md`;
+}
+export class RegistryUnavailableError extends Error {
+    constructor(registry) {
+        super(`Could not reach ${registry} for any package — update needs the npm registry. Check your connection (or npm_config_registry) and retry.`);
+        this.name = 'RegistryUnavailableError';
+    }
+}
+const isFramework = (name) => alwaysLatest(name);
+/** `minimumReleaseAge: <n>` from pnpm-workspace.yaml, when set. */
+export function workspaceReleaseAge(yaml) {
+    const match = yaml ? /^minimumReleaseAge:\s*(\d+)\s*$/m.exec(yaml) : null;
+    return match ? Number(match[1]) : undefined;
+}
+/** Whether pnpm-workspace.yaml's minimumReleaseAgeExclude lists `entry`. */
+export function workspaceExcludes(yaml, entry) {
+    if (!yaml)
+        return false;
+    const block = /^minimumReleaseAgeExclude:\s*\n((?:[ \t]+-.*\n?|[ \t]*#.*\n?)*)/m.exec(yaml);
+    if (!block)
+        return false;
+    return (block[1] ?? '')
+        .split('\n')
+        .map((line) => /^\s*-\s*['"]?([^'"#\s]+)['"]?/.exec(line)?.[1])
+        .includes(entry);
+}
+/** Adds `entry` to minimumReleaseAgeExclude right after the `@basaltkit/*` line; undefined when that line is absent. */
+export function addWorkspaceExclude(yaml, entry) {
+    const line = /^([ \t]+)-[ \t]*['"]?@basaltkit\/\*['"]?[ \t]*$/m.exec(yaml);
+    if (!line)
+        return undefined;
+    const end = line.index + line[0].length;
+    return `${yaml.slice(0, end)}\n${line[1]}- ${entry}${yaml.slice(end)}`;
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function planUpdate(ctx, options = {}) {
+    const manifests = [{ file: 'package.json', text: ctx.packageJsonText, json: ctx.packageJson }];
+    if (ctx.web)
+        manifests.push({ file: 'web/package.json', text: ctx.web.text, json: ctx.web.json });
+    const workspaceYaml = await readOptional(join(ctx.dir, 'pnpm-workspace.yaml'));
+    const tooling = options.tooling !== false;
+    // Every declared dependency, per file and section.
+    const entries = [];
+    for (const manifest of manifests) {
+        for (const section of DEPENDENCY_SECTIONS) {
+            for (const [name, current] of Object.entries(manifest.json[section] ?? {})) {
+                const framework = isFramework(name);
+                const status = options.only === 'basaltkit' && !framework ? 'skipped' : parseSimpleRange(current) ? 'update' : 'unmanaged';
+                entries.push({ file: manifest.file, section, name, current, status, framework });
+            }
+        }
+    }
+    const rootHasCreateBasalt = entries.some((entry) => entry.file === 'package.json' && entry.name === 'create-basalt');
+    // Tooling: an app without create-basalt as a devDependency gets one, so
+    // `pnpm basalt update` resolves locally next time.
+    const addCreateBasalt = tooling && !rootHasCreateBasalt;
+    const managed = entries.filter((entry) => entry.status === 'update');
+    const names = [...new Set([...managed.map((entry) => entry.name), ...(addCreateBasalt ? ['create-basalt'] : [])])].sort();
+    // The release-age window and who is exempt from it: the project's own pnpm
+    // config decides (non-pnpm managers have no exclude list → nobody exempt).
+    const window = minimumReleaseAgeMinutes(options.registry?.minimumReleaseAge ?? workspaceReleaseAge(workspaceYaml));
+    const exempt = (name) => ctx.pm === 'pnpm' &&
+        ((name.startsWith('@basaltkit/') && workspaceExcludes(workspaceYaml, '@basaltkit/*')) ||
+            (name === 'create-basalt' &&
+                (workspaceExcludes(workspaceYaml, 'create-basalt') ||
+                    (tooling && workspaceYaml !== undefined && addWorkspaceExclude(workspaceYaml, 'create-basalt') !== undefined))));
+    const majorsOf = new Map();
+    for (const entry of managed) {
+        const range = parseSimpleRange(entry.current);
+        if (!range)
+            continue;
+        const set = majorsOf.get(entry.name) ?? new Set();
+        set.add(range.parsed[0]);
+        majorsOf.set(entry.name, set);
+    }
+    /** Whether `latest` would be taken for `name` from a range on `major`. */
+    const acceptsMajor = (name, major, latest) => isFramework(name) || options.major === true || Number(latest.split('.')[0]) === major;
+    const { results, registry } = await lookupLatestVersions(names, (name, latest) => !exempt(name) && (majorsOf.get(name) === undefined || [...(majorsOf.get(name) ?? [])].some((major) => acceptsMajor(name, major, latest))), { ...options.registry, minimumReleaseAge: window });
+    if (names.length > 0 && names.every((name) => results.get(name)?.latest === undefined)) {
+        throw new RegistryUnavailableError(registry);
+    }
+    for (const entry of managed) {
+        const info = results.get(entry.name);
+        const range = parseSimpleRange(entry.current);
+        if (!range)
+            continue;
+        if (info.latest === undefined) {
+            entry.status = 'failed';
+            continue;
+        }
+        entry.latest = info.latest;
+        const latest = parseVersion(info.latest);
+        if (!latest) {
+            entry.status = 'failed';
+            continue;
+        }
+        const order = compareVersions(latest, range.parsed);
+        if (order === 0) {
+            entry.status = 'current';
+            continue;
+        }
+        if (order < 0) {
+            entry.status = 'ahead';
+            continue;
+        }
+        entry.kind = updateKind(range.parsed, latest);
+        if (!acceptsMajor(entry.name, range.parsed[0], info.latest)) {
+            entry.status = 'held-major';
+            continue;
+        }
+        if (info.age !== 'mature') {
+            entry.status = 'too-fresh';
+            entry.freshness = info.age;
+            continue;
+        }
+        entry.status = 'update';
+        entry.target = `${range.style}${info.latest}`;
+    }
+    const updates = entries.filter((entry) => entry.status === 'update' && entry.target !== undefined);
+    const files = {};
+    for (const manifest of manifests) {
+        let text = manifest.text;
+        for (const entry of updates.filter((candidate) => candidate.file === manifest.file)) {
+            text = setDependencyRange(text, entry.section, entry.name, entry.target);
+        }
+        if (text !== manifest.text)
+            files[manifest.file] = { before: manifest.text, after: text };
+    }
+    const toolingNotes = [];
+    const manual = [];
+    const warnings = [];
+    if (tooling) {
+        // create-basalt devDependency + the `basalt` script that reaches it.
+        const createBasaltLatest = results.get('create-basalt');
+        const rootText = files['package.json']?.after ?? ctx.packageJsonText;
+        if (addCreateBasalt && createBasaltLatest?.latest !== undefined) {
+            const fresh = createBasaltLatest.age !== 'mature';
+            if (fresh) {
+                warnings.push(`create-basalt ${createBasaltLatest.latest} is inside the release-age window — not added as a devDependency this time.`);
+            }
+            else {
+                const hasBin = ctx.options.cli;
+                const merged = mergePackageJson(rootText, {
+                    devDependencies: { 'create-basalt': `^${createBasaltLatest.latest}` },
+                    scripts: { basalt: hasBin ? 'tsx bin/basalt.ts' : BASALT_PROJECT_SCRIPT },
+                });
+                if (merged.changes.length > 0) {
+                    files['package.json'] = { before: ctx.packageJsonText, after: merged.text };
+                    toolingNotes.push(`package.json: create-basalt ^${createBasaltLatest.latest} as a devDependency${merged.changes.some((change) => change.startsWith('scripts:')) ? ' + a "basalt" script' : ''} — so \`${ctx.pm === 'npm' ? 'npm run' : ctx.pm} basalt update\` works from now on`);
+                }
+                if (workspaceYaml !== undefined && !workspaceExcludes(workspaceYaml, 'create-basalt')) {
+                    const patched = addWorkspaceExclude(workspaceYaml, 'create-basalt');
+                    if (patched !== undefined) {
+                        files['pnpm-workspace.yaml'] = { before: workspaceYaml, after: patched };
+                        toolingNotes.push('pnpm-workspace.yaml: create-basalt joins minimumReleaseAgeExclude (like @basaltkit/*)');
+                    }
+                }
+            }
+        }
+        // bin/basalt.ts from an earlier template: make it delegate the project commands.
+        const bin = await readOptional(join(ctx.dir, 'bin', 'basalt.ts'));
+        const status = binStatus(bin, ctx.manifest?.files['bin/basalt.ts']);
+        if (status === 'patchable' && bin !== undefined) {
+            const after = patchBasaltBin(bin);
+            files['bin/basalt.ts'] = { before: bin, after };
+            toolingNotes.push('bin/basalt.ts: unmodified template from an earlier release — gains update/add/doctor/info');
+            if (ctx.manifest) {
+                files[MANIFEST_PATH] = {
+                    before: serializeManifest(ctx.manifest),
+                    after: serializeManifest(extendManifest(ctx.manifest, ctx.options, { 'bin/basalt.ts': after })),
+                };
+            }
+        }
+        else if (status === 'modified') {
+            manual.push(`bin/basalt.ts was customised, so it was not patched. To give it the project commands:\n${MANUAL_BIN_SNIPPET}`);
+        }
+    }
+    // Peer ranges of the framework versions we end up on vs the app's resulting ranges.
+    const resulting = new Map();
+    for (const entry of entries) {
+        if (entry.file !== 'package.json' && resulting.has(entry.name))
+            continue;
+        resulting.set(entry.name, entry.target ?? entry.current);
+    }
+    for (const entry of entries) {
+        if (!entry.framework || (entry.status !== 'update' && entry.status !== 'current') || entry.file !== 'package.json')
+            continue;
+        const info = results.get(entry.name);
+        for (const [peer, wanted] of Object.entries(info?.peers ?? {})) {
+            const range = resulting.get(peer);
+            const floor = range ? parseSimpleRange(range) : undefined;
+            if (!floor)
+                continue;
+            if (satisfies(floor.version, wanted) === false) {
+                const peerEntry = entries.find((candidate) => candidate.name === peer);
+                const hint = peerEntry?.status === 'held-major' ? ' — re-run with --major' : '';
+                warnings.push(`${entry.name}@${info?.latest} expects ${peer} ${wanted}, but the app will have ${range}${hint}`);
+            }
+        }
+    }
+    const failed = entries.filter((entry) => entry.status === 'failed').map((entry) => entry.name);
+    if (failed.length > 0)
+        warnings.push(`The registry did not answer for ${[...new Set(failed)].join(', ')} — left unchanged.`);
+    const majors = updates
+        .filter((entry) => entry.framework && entry.kind === 'major')
+        .map((entry) => ({
+        name: entry.name,
+        from: parseSimpleRange(entry.current)?.version ?? entry.current,
+        to: entry.latest,
+        changelog: changelogUrl(entry.name),
+    }))
+        .filter((major, i, all) => all.findIndex((other) => other.name === major.name) === i);
+    return { entries, updates, files, tooling: toolingNotes, manual, warnings, majors, registry };
+}
+/** The plan as terminal lines: the update table, then notes, tooling, warnings and majors. */
+export function renderUpdatePlan(plan, colors) {
+    const lines = [];
+    const kindLabel = (kind) => kind === 'major' ? colors.red(colors.bold('MAJOR')) : kind === 'minor' ? colors.yellow('minor') : colors.green('patch');
+    const multiFile = new Set(plan.entries.map((entry) => entry.file)).size > 1;
+    if (plan.updates.length === 0) {
+        lines.push(colors.green('Every dependency is already on its latest allowed version.'));
+    }
+    else {
+        lines.push(colors.bold(`${plan.updates.length} update(s):`), '');
+        lines.push(...table(['package', ...(multiFile ? ['in'] : []), 'current', '', 'target', 'kind'], plan.updates.map((entry) => [
+            entry.framework ? colors.cyan(entry.name) : entry.name,
+            ...(multiFile ? [entry.file === 'package.json' ? '.' : entry.file.replace(/\/package\.json$/, '/')] : []),
+            entry.current,
+            '→',
+            colors.bold(entry.target),
+            kindLabel(entry.kind),
+        ]), colors).map((line) => `  ${line}`));
+    }
+    const held = plan.entries.filter((entry) => entry.status === 'held-major');
+    const fresh = plan.entries.filter((entry) => entry.status === 'too-fresh');
+    if (held.length > 0 || fresh.length > 0)
+        lines.push('');
+    for (const entry of dedupe(held)) {
+        lines.push(colors.dim(`  kept ${entry.name} ${entry.current}: ${entry.latest} is a new major — pass --major to take it`));
+    }
+    for (const entry of dedupe(fresh)) {
+        lines.push(colors.dim(entry.freshness === 'recent'
+            ? `  kept ${entry.name} ${entry.current}: ${entry.latest} is inside the release-age window (minimumReleaseAge) — retry later`
+            : `  kept ${entry.name} ${entry.current}: could not prove ${entry.latest} is older than the release-age window`));
+    }
+    if (plan.majors.length > 0) {
+        lines.push('', colors.bold('Framework majors — read before applying:'));
+        for (const major of plan.majors)
+            lines.push(`  ${major.name} ${major.from} → ${major.to}: ${major.changelog}`);
+        lines.push(`  Upgrade notes: ${DOCS_UPGRADING_URL}`);
+    }
+    if (plan.tooling.length > 0) {
+        lines.push('', colors.bold('Project tooling:'));
+        for (const note of plan.tooling)
+            lines.push(`  ${note}`);
+    }
+    for (const warning of plan.warnings)
+        lines.push('', colors.yellow(`Warning: ${warning}`));
+    for (const step of plan.manual)
+        lines.push('', colors.yellow('Manual step:'), step);
+    return lines;
+}
+function dedupe(entries) {
+    return entries.filter((entry, i) => entries.findIndex((other) => other.name === entry.name && other.current === entry.current) === i);
+}

package/dist/templates.d.ts

@@ -16,6 +16,7 @@ export interface ProjectOptions {
      */
     prisma: boolean;
 }
+export { basaltBin } from './bin-template.js';
 export { SCAFFOLD_VERSIONS } from './versions.js';
 export { THIRD_PARTY_VERSIONS } from './latest-versions.js';
 /**
@@ -32,6 +33,10 @@ export declare const versionOf: (pkg: string) => string;
  * unknown package so every emitted range lives in that single table.
  */
 export declare const thirdPartyVersionOf: (pkg: string) => string;
+/** The root `basalt` script of an app without `--cli`: create-basalt's project commands. */
+export declare const BASALT_PROJECT_SCRIPT = "create-basalt --project";
+/** The root `dev:web` script of a `--ui` app (web/ is a pnpm workspace member). */
+export declare const webDevScript: (options: Pick<ProjectOptions, 'name'>) => string;
 /** True when the scaffold binds users to the tenant they act on (tenancy + auth). */
 export declare const enforcesMembership: (options: ProjectOptions) => boolean;
 export declare function packageJson(options: ProjectOptions): string;
@@ -56,7 +61,6 @@ export declare function serverTs(): string;
  * NODE_ENV counts as production and secrets are required (fail-closed).
  */
 export declare function devTs(): string;
-export declare function basaltBin(): string;
 /**
  * `prisma/schema.prisma` — the datasource, the client generator, the models of
  * every Basalt domain this app enables, and the app's own first model.
@@ -87,6 +91,12 @@ export declare function dbTs(options: ProjectOptions): string;
 export declare function prismaSeedTs(options: ProjectOptions): string;
 export declare function appTest(options: ProjectOptions): string;
 export declare function readme(options: ProjectOptions): string;
+/** README section for the \`basalt\` CLI (also appended by \`create-basalt add cli\`). */
+export declare function readmeCliSection(_options: ProjectOptions): string;
+/** README section for the web/ frontend (also appended by \`create-basalt add ui\`). */
+export declare function readmeUiSection(options: ProjectOptions): string;
+/** README section for the MCP server (also appended by \`create-basalt add mcp\`). */
+export declare function readmeMcpSection(_options: ProjectOptions): string;
 /**
  * A Claude Code / generic MCP client config that registers the dev-only
  * `basalt-ai-mcp` bridge for this project. Claude Code reads `.mcp.json` at the

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
@@ -526,33 +538,6 @@ 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
@@ -1044,8 +1029,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 +1070,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 +1114,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 +1187,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: