create-basalt 1.9.0 → 1.10.0

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). */

package/dist/latest-versions.js

@@ -140,6 +140,18 @@ async function probeAge(fetchImpl, registry, name, windowMs, now, signal) {
         return 'unknown';
     }
 }
+/** The `peerDependencies` of a `/latest` document (string values only). */
+function peersOf(body) {
+    const peers = {};
+    const raw = body?.peerDependencies;
+    if (raw && typeof raw === 'object') {
+        for (const [name, range] of Object.entries(raw)) {
+            if (typeof range === 'string')
+                peers[name] = range;
+        }
+    }
+    return peers;
+}
 async function lookupLatest(fetchImpl, registry, name, signal) {
     try {
         const response = await fetchImpl(latestUrl(registry, name), {
@@ -152,7 +164,7 @@ async function lookupLatest(fetchImpl, registry, name, signal) {
             return 'miss';
         const body = (await response.json());
         const version = body?.version;
-        return typeof version === 'string' && STABLE_SEMVER.test(version) ? { version } : 'miss';
+        return typeof version === 'string' && STABLE_SEMVER.test(version) ? { version, peers: peersOf(body) } : 'miss';
     }
     catch {
         // Network error, per-request timeout, or malformed JSON.
@@ -171,80 +183,97 @@ async function fetchLatest(fetchImpl, registry, name, timeoutMs, overall) {
         if (result === 'miss')
             return undefined;
         if (result !== 'transient')
-            return result.version;
+            return result;
     }
     return undefined;
 }
 /**
- * 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`.
+ * 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 async function resolveLatestVersions(fallbacks, options = {}) {
+export async function lookupLatestVersions(names, shouldProbe, options = {}) {
     const fetchImpl = options.fetch ?? globalThis.fetch;
     const registry = registryUrl(options.registry);
-    const versions = { ...fallbacks };
-    const resolved = [];
-    const failed = [];
-    const heldBack = [];
-    const tooFresh = [];
-    const names = Object.keys(fallbacks).sort();
+    const results = new Map();
+    if (typeof fetchImpl !== 'function') {
+        for (const name of names)
+            results.set(name, { peers: {}, age: 'mature' });
+        return { results, registry };
+    }
     const windowMs = minimumReleaseAgeMinutes(options.minimumReleaseAge) * 60_000;
     const now = options.now ?? Date.now;
     const timeoutMs = options.timeoutMs ?? PER_REQUEST_TIMEOUT_MS;
-    if (typeof fetchImpl !== 'function') {
-        return { versions, resolved, failed: names, heldBack, tooFresh, registry };
-    }
-    /** A third-party latest on the template-compatible major (else undefined). */
-    const compatible = (name, version) => {
-        if (alwaysLatest(name))
-            return true;
-        const major = compatibleMajor(fallbacks[name]);
-        return major !== undefined && Number(version.split('.')[0]) === major;
-    };
     const overall = new AbortController();
     const cap = setTimeout(() => overall.abort(), options.overallTimeoutMs ?? OVERALL_TIMEOUT_MS);
     try {
-        const latest = [];
-        const age = [];
         let next = 0;
         const worker = async () => {
             while (next < names.length) {
-                const i = next++;
-                const name = names[i];
-                const version = await fetchLatest(fetchImpl, registry, name, timeoutMs, overall.signal);
-                latest[i] = version;
-                age[i] =
-                    version === undefined || alwaysLatest(name) || windowMs === 0 || !compatible(name, version)
-                        ? 'mature'
-                        : await probeAge(fetchImpl, registry, name, windowMs, now, AbortSignal.any([AbortSignal.timeout(timeoutMs), overall.signal]));
+                const name = names[next++];
+                const found = await fetchLatest(fetchImpl, registry, name, timeoutMs, overall.signal);
+                if (found === undefined) {
+                    results.set(name, { peers: {}, age: 'mature' });
+                    continue;
+                }
+                const age = windowMs === 0 || !shouldProbe(name, found.version)
+                    ? 'mature'
+                    : await probeAge(fetchImpl, registry, name, windowMs, now, AbortSignal.any([AbortSignal.timeout(timeoutMs), overall.signal]));
+                results.set(name, { latest: found.version, peers: found.peers, age });
             }
         };
         const pool = Math.max(1, Math.min(options.concurrency ?? CONCURRENCY, names.length));
         await Promise.all(Array.from({ length: pool }, worker));
-        names.forEach((name, i) => {
-            const version = latest[i];
-            const fallback = fallbacks[name];
-            if (version === undefined) {
-                failed.push(name);
-                return;
-            }
-            if (!compatible(name, version)) {
-                heldBack.push({ name, latest: version, range: fallback });
-                return;
-            }
-            const verdict = age[i];
-            if (verdict === 'recent' || verdict === 'unknown') {
-                tooFresh.push({ name, latest: version, range: fallback, reason: verdict });
-                return;
-            }
-            versions[name] = `^${version}`;
-            resolved.push(name);
-        });
     }
     finally {
         clearTimeout(cap);
     }
+    return { results, registry };
+}
+/**
+ * Resolves the latest published version of every package in `fallbacks`
+ * (name → fallback range). Never throws: a package the registry cannot answer
+ * for keeps its fallback range and is listed in `failed`.
+ */
+export async function resolveLatestVersions(fallbacks, options = {}) {
+    const versions = { ...fallbacks };
+    const resolved = [];
+    const failed = [];
+    const heldBack = [];
+    const tooFresh = [];
+    const names = Object.keys(fallbacks).sort();
+    /** A third-party latest on the template-compatible major (else undefined). */
+    const compatible = (name, version) => {
+        if (alwaysLatest(name))
+            return true;
+        const major = compatibleMajor(fallbacks[name]);
+        return major !== undefined && Number(version.split('.')[0]) === major;
+    };
+    // @basaltkit/* is never probed: the scaffolded pnpm-workspace.yaml excludes
+    // that scope from the release-age policy.
+    const { results, registry } = await lookupLatestVersions(names, (name, version) => !alwaysLatest(name) && compatible(name, version), options);
+    for (const name of names) {
+        const info = results.get(name);
+        const version = info?.latest;
+        const fallback = fallbacks[name];
+        if (info === undefined || version === undefined) {
+            failed.push(name);
+            continue;
+        }
+        if (!compatible(name, version)) {
+            heldBack.push({ name, latest: version, range: fallback });
+            continue;
+        }
+        if (info.age === 'recent' || info.age === 'unknown') {
+            tooFresh.push({ name, latest: version, range: fallback, reason: info.age });
+            continue;
+        }
+        versions[name] = `^${version}`;
+        resolved.push(name);
+    }
     return { versions, resolved, failed, heldBack, tooFresh, registry };
 }
 /**
@@ -265,6 +294,17 @@ export function applyVersions(packageJsonText, versions) {
     }
     return `${JSON.stringify(pkg, null, 2)}\n`;
 }
+/**
+ * Resolves the latest published versions for every package.json in `files`
+ * (in place) — the scaffold's registry policy, shared with `create-basalt add`.
+ */
+export async function resolveFileVersions(files, registry) {
+    const manifests = Object.keys(files).filter((path) => path === 'package.json' || path.endsWith('/package.json'));
+    const versions = await resolveLatestVersions(collectDependencies(manifests.map((path) => files[path])), registry);
+    for (const path of manifests)
+        files[path] = applyVersions(files[path], versions.versions);
+    return versions;
+}
 /** Every dependency/devDependency name → range declared in the given package.json texts. */
 export function collectDependencies(packageJsonTexts) {
     const all = {};

package/dist/project/add.d.ts

@@ -0,0 +1,66 @@
+import { type ResolveLatestOptions, type VersionResolution } from '../latest-versions.js';
+import { type ProjectOptions } from '../templates.js';
+import type { ProjectContext } from './context.js';
+/**
+ * `create-basalt add <feature>`: give an existing app what the matching
+ * scaffold flag would have generated, adapted to the app as it is now.
+ *
+ * Rules: an existing file is never overwritten (skipped with a notice;
+ * `--force` overwrites); package.json, pnpm-workspace.yaml, .gitignore and the
+ * README are MERGED; user-owned code (src/app.ts, src/routes.ts) is
+ * regenerated only when the manifest proves it untouched, patched only where
+ * the template's anchors are still unambiguous, and otherwise left alone with
+ * the exact manual steps. Planning writes nothing — {@link applyAddPlan} does.
+ */
+export declare const ADDABLE_FEATURES: readonly ['ui', 'cli', 'mcp'];
+export type AddableFeature = (typeof ADDABLE_FEATURES)[number];
+export interface PlannedChange {
+    path: string;
+    /** create: new file · overwrite: --force over an existing file · update: merged/patched · skip: left alone. */
+    action: 'create' | 'overwrite' | 'update' | 'skip';
+    /** Content to write (absent for skip). */
+    content?: string;
+    /** Why (shown next to the path). */
+    note?: string;
+}
+export interface AddPlan {
+    feature: AddableFeature;
+    /** The app's options once the feature is on. */
+    options: ProjectOptions;
+    changes: PlannedChange[];
+    /** Steps printed for the user (code that could not be edited safely). */
+    manual: string[];
+    /** Informational lines (versions resolved, things kept). */
+    notes: string[];
+    /** Set when there is nothing to do (the feature is already there). */
+    alreadyPresent?: string;
+    versions?: VersionResolution;
+}
+export interface AddOptions {
+    force?: boolean;
+    /** Resolve the latest versions from the registry (default true; false = bundled ranges). */
+    resolveLatest?: boolean;
+    registry?: ResolveLatestOptions;
+}
+export declare class AddRefusedError extends Error {
+    constructor(message: string);
+}
+/** Ensures pnpm-workspace.yaml lists `member` under `packages:`; undefined when the shape is not one we can edit. */
+export declare function addWorkspaceMember(yaml: string, member: string): string | undefined;
+/** Appends missing ignore lines (`node_modules/` also matches an existing `node_modules` or `/node_modules/`). */
+export declare function ensureGitignore(text: string, lines: readonly string[]): string;
+/**
+ * Wires `commandsPlugin` into a scaffold-shaped src/app.ts (any adapter):
+ * the import, `commands?: CommandDefinition[]` on BuildAppOptions, and the
+ * plugin right before the adapter. Undefined when an anchor is missing or
+ * ambiguous — the caller prints manual steps instead.
+ */
+export declare function patchAppForCli(source: string): string | undefined;
+/**
+ * Wires the MCP server into a scaffold-shaped src/app.ts (any adapter):
+ * `mcpPlugin({ routes: <the adapter's routes> })` before the adapter, and
+ * `...mcpRoutes()` appended to the adapter's routes.
+ */
+export declare function patchAppForMcp(source: string, name: string): string | undefined;
+/** Plans `add <feature>` for the app in `ctx`. Writes nothing. */
+export declare function planAdd(ctx: ProjectContext, feature: AddableFeature, options?: AddOptions): Promise<AddPlan>;

package/dist/project/add.js

@@ -0,0 +1,322 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { basaltBin } from '../bin-template.js';
+import { collectDependencies, resolveFileVersions, resolveLatestVersions, } from '../latest-versions.js';
+import { appTs, BASALT_PROJECT_SCRIPT, gitignore, mcpJson, pnpmWorkspaceYaml, readme, readmeCliSection, readmeMcpSection, readmeUiSection, routesTs, versionOf, webDevScript, } from '../templates.js';
+import { uiFiles } from '../templates-ui.js';
+import { createManifest, extendManifest, isPristine, MANIFEST_PATH, serializeManifest } from './manifest.js';
+import { mergePackageJson } from './package-json.js';
+/**
+ * `create-basalt add <feature>`: give an existing app what the matching
+ * scaffold flag would have generated, adapted to the app as it is now.
+ *
+ * Rules: an existing file is never overwritten (skipped with a notice;
+ * `--force` overwrites); package.json, pnpm-workspace.yaml, .gitignore and the
+ * README are MERGED; user-owned code (src/app.ts, src/routes.ts) is
+ * regenerated only when the manifest proves it untouched, patched only where
+ * the template's anchors are still unambiguous, and otherwise left alone with
+ * the exact manual steps. Planning writes nothing — {@link applyAddPlan} does.
+ */
+export const ADDABLE_FEATURES = ['ui', 'cli', 'mcp'];
+export class AddRefusedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AddRefusedError';
+    }
+}
+async function readOptional(dir, path) {
+    try {
+        return await readFile(join(dir, path), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Safe edits of user-owned files
+/** Ensures pnpm-workspace.yaml lists `member` under `packages:`; undefined when the shape is not one we can edit. */
+export function addWorkspaceMember(yaml, member) {
+    const packages = /^packages:[ \t]*(.*)$/m.exec(yaml);
+    if (!packages)
+        return `packages:\n  - ${member}\n${yaml}`;
+    if ((packages[1] ?? '').trim() !== '')
+        return undefined; // flow style (packages: [a, b]) — leave to the user
+    const after = yaml.slice(packages.index + packages[0].length);
+    const items = /^((?:\n[ \t]+-.*|\n[ \t]*#.*)*)/.exec(after)?.[1] ?? '';
+    const listed = items
+        .split('\n')
+        .map((line) => /^\s*-\s*['"]?([^'"#\s]+)['"]?/.exec(line)?.[1])
+        .filter((entry) => entry !== undefined);
+    if (listed.includes(member) || listed.includes(`${member}/`))
+        return yaml;
+    const indent = /\n([ \t]+)-/.exec(items)?.[1] ?? '  ';
+    const end = packages.index + packages[0].length + items.length;
+    return `${yaml.slice(0, end)}\n${indent}- ${member}${yaml.slice(end)}`;
+}
+/** Appends missing ignore lines (`node_modules/` also matches an existing `node_modules` or `/node_modules/`). */
+export function ensureGitignore(text, lines) {
+    const normalize = (line) => line.trim().replace(/^\//, '').replace(/\/$/, '');
+    const present = new Set(text.split(/\r?\n/).map(normalize));
+    const missing = lines.filter((line) => !present.has(normalize(line)));
+    if (missing.length === 0)
+        return text;
+    const separator = text === '' || text.endsWith('\n') ? '' : '\n';
+    return `${text}${separator}${missing.join('\n')}\n`;
+}
+const ADAPTER_LINE = /^([ \t]*)(fastifyPlugin|expressPlugin|honoPlugin)\(\{ routes: (.+) \}\)(,?)[ \t]*$/gm;
+/** The single adapter-plugin line (`fastifyPlugin|expressPlugin|honoPlugin({ routes: … })`), or undefined when absent/ambiguous. */
+function adapterLine(source) {
+    const matches = [...source.matchAll(ADAPTER_LINE)];
+    return matches.length === 1 ? matches[0] : undefined;
+}
+/** Inserts an import line before the first import of the file. */
+function addImport(source, line) {
+    const first = /^import /m.exec(source);
+    if (!first)
+        return undefined;
+    return `${source.slice(0, first.index)}${line}\n${source.slice(first.index)}`;
+}
+/**
+ * Wires `commandsPlugin` into a scaffold-shaped src/app.ts (any adapter):
+ * the import, `commands?: CommandDefinition[]` on BuildAppOptions, and the
+ * plugin right before the adapter. Undefined when an anchor is missing or
+ * ambiguous — the caller prints manual steps instead.
+ */
+export function patchAppForCli(source) {
+    if (source.includes('commandsPlugin('))
+        return source;
+    if (!/export function buildApp\(options: BuildAppOptions = \{\}\)/.test(source))
+        return undefined;
+    const options = /export interface BuildAppOptions \{\n([\s\S]*?)\n\}/.exec(source);
+    const adapter = adapterLine(source);
+    if (!options || !adapter)
+        return undefined;
+    const indent = adapter[1] ?? '';
+    let out = source.slice(0, adapter.index) +
+        `${indent}...(options.commands && options.commands.length > 0 ? [commandsPlugin(options.commands)] : []),\n` +
+        source.slice(adapter.index);
+    out = out.replace(options[0], `export interface BuildAppOptions {\n${options[1]}\n  /** Dev/CLI commands (make:*, ai:*, prisma:sync) — passed ONLY by bin/basalt.ts. */\n  commands?: CommandDefinition[]\n}`);
+    return addImport(out, `import { commandsPlugin, type CommandDefinition } from '@basaltkit/cli'`);
+}
+/** `value` as a single-quoted TS string literal (backslashes, quotes and line breaks escaped). */
+function singleQuoted(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\r/g, '\\r').replace(/\n/g, '\\n')}'`;
+}
+/**
+ * Wires the MCP server into a scaffold-shaped src/app.ts (any adapter):
+ * `mcpPlugin({ routes: <the adapter's routes> })` before the adapter, and
+ * `...mcpRoutes()` appended to the adapter's routes.
+ */
+export function patchAppForMcp(source, name) {
+    if (source.includes('mcpPlugin('))
+        return source;
+    const adapter = adapterLine(source);
+    if (!adapter)
+        return undefined;
+    const [line, indent = '', plugin, routes = '', comma = ''] = adapter;
+    const expression = routes.trim();
+    let withMcp;
+    if (/^\[[\s\S]*\]$/.test(expression))
+        withMcp = `${expression.slice(0, -1)}, ...mcpRoutes()]`;
+    else if (/^[\w$.]+(\(\))?$/.test(expression))
+        withMcp = `[...${expression}, ...mcpRoutes()]`;
+    else
+        return undefined;
+    const replacement = `${indent}mcpPlugin({ routes: ${expression}, serverInfo: { name: ${singleQuoted(name)}, version: '0.1.0' } }),\n` +
+        `${indent}${plugin}({ routes: ${withMcp} })${comma}`;
+    const out = source.slice(0, adapter.index) + replacement + source.slice(adapter.index + line.length);
+    return addImport(out, `import { mcpPlugin, mcpRoutes } from '@basaltkit/mcp'`);
+}
+// ---------------------------------------------------------------------------
+// Planning
+/** Ranges for packages a feature adds to the ROOT package.json (latest, or the bundled ranges). */
+async function rootRanges(wanted, options) {
+    if (options.resolveLatest === false)
+        return { ranges: wanted };
+    const versions = await resolveLatestVersions(collectDependencies([JSON.stringify({ dependencies: wanted })]), options.registry);
+    return { ranges: versions.versions, versions };
+}
+/** A whole generated file: created, skipped when present, overwritten with --force. */
+async function plannedFile(b, path, content) {
+    const existing = await readOptional(b.ctx.dir, path);
+    if (existing === undefined) {
+        b.changes.push({ path, action: 'create', content });
+        b.generated[path] = content;
+    }
+    else if (existing === content) {
+        b.changes.push({ path, action: 'skip', note: 'already identical' });
+    }
+    else if (b.force) {
+        b.changes.push({ path, action: 'overwrite', content, note: '--force' });
+        b.generated[path] = content;
+    }
+    else {
+        b.changes.push({ path, action: 'skip', note: 'exists — kept yours (--force to overwrite)' });
+    }
+}
+/** A merged edit of an existing file (or its creation when absent). */
+function plannedEdit(b, path, before, after, note) {
+    if (before === after)
+        return;
+    b.changes.push({ path, action: before === undefined ? 'create' : 'update', content: after, note });
+    // A file create-basalt wrote and nobody touched stays "pristine" after our edit.
+    if (before === undefined || isPristine(b.ctx.manifest, path, before))
+        b.generated[path] = after;
+}
+/**
+ * A user-owned source file (src/app.ts, src/routes.ts): regenerated when the
+ * manifest proves it untouched, else patched by `patch`, else manual steps.
+ */
+async function plannedSource(b, path, regenerate, patch, manual) {
+    const existing = await readOptional(b.ctx.dir, path);
+    if (existing === undefined) {
+        b.manual.push(`${path} does not exist. ${manual}`);
+        return;
+    }
+    if (regenerate && isPristine(b.ctx.manifest, path, existing)) {
+        plannedEdit(b, path, existing, regenerate(), 'untouched template — regenerated with the feature on');
+        return;
+    }
+    const patched = patch(existing);
+    if (patched === undefined) {
+        b.changes.push({ path, action: 'skip', note: 'customised — see the manual steps' });
+        b.manual.push(`${path}: ${manual}`);
+    }
+    else if (patched !== existing) {
+        b.changes.push({ path, action: 'update', content: patched, note: 'patched at the template anchors' });
+    }
+}
+/** README: regenerated when untouched (features line included), else the feature's section appended. */
+async function plannedReadme(b, regenOptions, heading, section) {
+    const current = await readOptional(b.ctx.dir, 'README.md');
+    if (current === undefined || current.includes(heading))
+        return;
+    if (regenOptions && isPristine(b.ctx.manifest, 'README.md', current)) {
+        plannedEdit(b, 'README.md', current, readme(regenOptions), 'untouched template — regenerated with the feature on');
+        return;
+    }
+    plannedEdit(b, 'README.md', current, `${current}${current.endsWith('\n') ? '' : '\n'}${section}`, `+ "${heading}" section`);
+}
+async function plannedPackageJson(b, additions) {
+    const merged = mergePackageJson(b.ctx.packageJsonText, additions);
+    for (const kept of merged.kept)
+        b.notes.push(`package.json: ${kept}`);
+    if (merged.text !== b.ctx.packageJsonText) {
+        b.changes.push({ path: 'package.json', action: 'update', content: merged.text, note: merged.changes.join('; ') });
+    }
+}
+/** Plans `add <feature>` for the app in `ctx`. Writes nothing. */
+export async function planAdd(ctx, feature, options = {}) {
+    const present = {
+        ui: ctx.options.ui,
+        cli: ctx.options.cli,
+        mcp: ctx.options.mcp,
+    };
+    const next = { ...ctx.options, [feature]: true };
+    const b = { ctx, force: options.force === true, changes: [], manual: [], notes: [], generated: {} };
+    if (present[feature] && !b.force) {
+        return {
+            feature,
+            options: next,
+            changes: [],
+            manual: [],
+            notes: [],
+            alreadyPresent: {
+                ui: 'web/package.json already exists',
+                cli: 'bin/basalt.ts already exists',
+                mcp: '@basaltkit/mcp is already a dependency',
+            }[feature],
+        };
+    }
+    // Regeneration uses the options the pristine file was generated FROM, with the feature flipped on.
+    const regenOptions = ctx.manifest ? { ...ctx.manifest.options, [feature]: true } : undefined;
+    let versions;
+    if (feature === 'ui') {
+        if (ctx.pm !== 'pnpm') {
+            throw new AddRefusedError(`The web/ frontend is a pnpm workspace member (pnpm-workspace.yaml), and this project uses ${ctx.pm}. Switch the project to pnpm first (or pass --pm=pnpm if it already uses it).`);
+        }
+        const files = uiFiles(next);
+        if (options.resolveLatest !== false)
+            versions = await resolveFileVersions(files, options.registry);
+        for (const [path, content] of Object.entries(files))
+            await plannedFile(b, path, content);
+        const yaml = await readOptional(ctx.dir, 'pnpm-workspace.yaml');
+        if (yaml === undefined) {
+            plannedEdit(b, 'pnpm-workspace.yaml', undefined, pnpmWorkspaceYaml(next), 'web/ as a workspace member');
+        }
+        else {
+            const patched = addWorkspaceMember(yaml, 'web');
+            if (patched === undefined)
+                b.manual.push('pnpm-workspace.yaml: add `web` to `packages:` (it is written in a style this command does not edit).');
+            else
+                plannedEdit(b, 'pnpm-workspace.yaml', yaml, patched, 'web/ as a workspace member');
+        }
+        await plannedPackageJson(b, { scripts: { 'dev:web': webDevScript(next) } });
+        const ignore = await readOptional(ctx.dir, '.gitignore');
+        plannedEdit(b, '.gitignore', ignore, ignore === undefined ? gitignore(next) : ensureGitignore(ignore, ['node_modules/', 'dist/']), 'ignore web/ build output');
+        await plannedReadme(b, regenOptions, '## Web UI', readmeUiSection(next));
+        b.notes.push('No CORS change needed: the Vite dev server proxies /api to the API on :3000.');
+    }
+    if (feature === 'cli') {
+        const resolved = await rootRanges({
+            '@basaltkit/cli': versionOf('@basaltkit/cli'),
+            '@basaltkit/prisma': versionOf('@basaltkit/prisma'),
+            '@basaltkit/generator': versionOf('@basaltkit/generator'),
+            'create-basalt': versionOf('create-basalt'),
+        }, options);
+        versions = resolved.versions;
+        await plannedFile(b, 'bin/basalt.ts', basaltBin());
+        await plannedPackageJson(b, {
+            dependencies: {
+                '@basaltkit/cli': resolved.ranges['@basaltkit/cli'],
+                '@basaltkit/prisma': resolved.ranges['@basaltkit/prisma'],
+            },
+            devDependencies: {
+                '@basaltkit/generator': resolved.ranges['@basaltkit/generator'],
+                'create-basalt': resolved.ranges['create-basalt'],
+            },
+            replaceScripts: { basalt: { from: BASALT_PROJECT_SCRIPT, to: 'tsx bin/basalt.ts' } },
+        });
+        await plannedSource(b, 'src/app.ts', regenOptions ? () => appTs(regenOptions) : undefined, patchAppForCli, [
+            'wire the CLI commands into buildApp by hand:',
+            "  1. import { commandsPlugin, type CommandDefinition } from '@basaltkit/cli'",
+            '  2. add `commands?: CommandDefinition[]` to the options buildApp(options) accepts',
+            '  3. add `...(options.commands && options.commands.length > 0 ? [commandsPlugin(options.commands)] : [])` to its plugins, before the HTTP adapter plugin',
+            'bin/basalt.ts calls buildApp({ logLevel, commands }).',
+        ].join('\n'));
+        await plannedReadme(b, regenOptions, '## The `basalt` CLI', readmeCliSection(next));
+    }
+    if (feature === 'mcp') {
+        const resolved = await rootRanges({ '@basaltkit/mcp': versionOf('@basaltkit/mcp'), '@basaltkit/ai-mcp': versionOf('@basaltkit/ai-mcp') }, options);
+        versions = resolved.versions;
+        await plannedPackageJson(b, {
+            dependencies: { '@basaltkit/mcp': resolved.ranges['@basaltkit/mcp'] },
+            // Dev-only AI bridge — never a runtime dependency.
+            devDependencies: { '@basaltkit/ai-mcp': resolved.ranges['@basaltkit/ai-mcp'] },
+        });
+        await plannedFile(b, '.mcp.json', mcpJson(next));
+        await plannedSource(b, 'src/app.ts', regenOptions ? () => appTs(regenOptions) : undefined, (source) => patchAppForMcp(source, next.name), [
+            'wire the MCP server by hand:',
+            "  1. import { mcpPlugin, mcpRoutes } from '@basaltkit/mcp'",
+            `  2. add \`mcpPlugin({ routes: <your routes>, serverInfo: { name: '${next.name}', version: '0.1.0' } })\` to the plugins`,
+            '  3. append `...mcpRoutes()` to the routes your HTTP adapter plugin serves (POST /mcp)',
+        ].join('\n'));
+        const routes = await readOptional(ctx.dir, 'src/routes.ts');
+        if (routes !== undefined && regenOptions && isPristine(ctx.manifest, 'src/routes.ts', routes)) {
+            plannedEdit(b, 'src/routes.ts', routes, routesTs(regenOptions), 'untouched template — overview/health exposed as MCP tools');
+        }
+        else {
+            b.notes.push("Expose routes as MCP tools by adding `meta: { mcp: { name: '…', description: '…' } }` to read-only routes (none are exposed until you do).");
+        }
+        await plannedReadme(b, regenOptions, '## MCP server', readmeMcpSection(next));
+    }
+    // The manifest records what create-basalt wrote (old projects get one now).
+    const manifest = ctx.manifest ? extendManifest(ctx.manifest, next, b.generated) : createManifest(next, b.generated);
+    const writes = b.changes.some((change) => change.action !== 'skip');
+    if (writes) {
+        const before = await readOptional(ctx.dir, MANIFEST_PATH);
+        plannedEdit(b, MANIFEST_PATH, before, serializeManifest(manifest), 'records the generated files');
+        delete b.generated[MANIFEST_PATH];
+    }
+    return { feature, options: next, changes: b.changes, manual: b.manual, notes: b.notes, ...(versions ? { versions } : {}) };
+}