create-basalt 1.9.0 → 1.10.0

package/dist/project/manifest.js

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * The scaffold manifest, `.basalt/project.json`: which create-basalt release
+ * generated the project, with which options, and a content hash of every file
+ * it wrote. `add` and `update` use the hashes to tell a template file nobody
+ * touched (safe to regenerate or patch) from one the user edited (left alone,
+ * with manual steps printed instead). Commit it with the project.
+ *
+ * Projects scaffolded before the manifest existed have none: their features
+ * are inferred from package.json and every file counts as user-owned.
+ */
+export const MANIFEST_PATH = '.basalt/project.json';
+/** Content hash, insensitive to CRLF/LF (git autocrlf must not make a file look edited). */
+export function hashContent(content) {
+    return `sha256-${createHash('sha256').update(content.replace(/\r\n/g, '\n')).digest('hex')}`;
+}
+let cachedVersion;
+/** This create-basalt release's version (from its own package.json). */
+export function ownVersion() {
+    if (cachedVersion === undefined) {
+        try {
+            const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+            cachedVersion = pkg.version ?? '0.0.0';
+        }
+        catch {
+            cachedVersion = '0.0.0';
+        }
+    }
+    return cachedVersion;
+}
+/** Files never hashed: package.json files are rewritten by every install/update, the manifest by itself. */
+const UNTRACKED = (path) => path === MANIFEST_PATH || path === 'package.json' || path.endsWith('/package.json');
+export function createManifest(options, files) {
+    const version = ownVersion();
+    return {
+        manifestVersion: 1,
+        generator: 'create-basalt',
+        createdWith: version,
+        updatedWith: version,
+        options,
+        files: Object.fromEntries(Object.entries(files)
+            .filter(([path]) => !UNTRACKED(path))
+            .map(([path, content]) => [path, hashContent(content)])
+            .sort(([a], [b]) => (a < b ? -1 : 1))),
+    };
+}
+/** Records newly written files (and the options now on) in an existing manifest. */
+export function extendManifest(manifest, options, written) {
+    const files = { ...manifest.files };
+    for (const [path, content] of Object.entries(written)) {
+        if (!UNTRACKED(path))
+            files[path] = hashContent(content);
+    }
+    return {
+        ...manifest,
+        updatedWith: ownVersion(),
+        options,
+        files: Object.fromEntries(Object.entries(files).sort(([a], [b]) => (a < b ? -1 : 1))),
+    };
+}
+export const serializeManifest = (manifest) => `${JSON.stringify(manifest, null, 2)}\n`;
+/** Reads `.basalt/project.json`; undefined when absent or unreadable (treated as "no manifest"). */
+export async function readManifest(dir) {
+    try {
+        const parsed = JSON.parse(await readFile(join(dir, MANIFEST_PATH), 'utf8'));
+        if (parsed.generator !== 'create-basalt' || typeof parsed.files !== 'object' || parsed.files === null)
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether `content` is exactly what create-basalt wrote at `path` (per the manifest). */
+export function isPristine(manifest, path, content) {
+    const recorded = manifest?.files[path];
+    return recorded !== undefined && recorded === hashContent(content);
+}

package/dist/project/package-json.d.ts

@@ -0,0 +1,57 @@
+/**
+ * package.json edits that keep the file looking like the user left it.
+ *
+ * - {@link setDependencyRange} rewrites ONE range in place (text-level): key
+ *   order, indentation, line endings and every other byte stay untouched.
+ * - {@link mergePackageJson} adds dependencies/scripts (structural): the file is
+ *   re-serialized with its own indentation and trailing newline, new keys of an
+ *   alphabetically sorted dependency section are slotted in order, and an
+ *   existing entry is never changed.
+ */
+export declare const DEPENDENCY_SECTIONS: readonly ['dependencies', 'devDependencies', 'optionalDependencies'];
+export type DependencySection = (typeof DEPENDENCY_SECTIONS)[number];
+export interface PackageJson {
+    name?: string;
+    version?: string;
+    packageManager?: string;
+    engines?: Record<string, string>;
+    scripts?: Record<string, string>;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * The `[start, end)` span of a top-level key's VALUE in a JSON object text, or
+ * undefined. Walks the top level only, so a nested key of the same name (an
+ * `overrides.dependencies`) never matches.
+ */
+export declare function topLevelValueSpan(text: string, key: string): [number, number] | undefined;
+/**
+ * Rewrites `section[name]` to `range`, touching only that string. Returns the
+ * text unchanged when the entry is not there.
+ */
+export declare function setDependencyRange(text: string, section: string, name: string, range: string): string;
+/** The indentation unit of a JSON text (default two spaces). */
+export declare function detectIndent(text: string): string;
+export interface PackageJsonAdditions {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    /** New scripts. An existing script of the same name is kept (see `replaceScripts`). */
+    scripts?: Record<string, string>;
+    /** Scripts to overwrite: name → { from, to }; replaced only while still `from`. */
+    replaceScripts?: Record<string, {
+        from: string;
+        to: string;
+    }>;
+}
+export interface MergeResult {
+    text: string;
+    /** What was added/changed, for the plan. */
+    changes: string[];
+    /** What was left alone because the user already has something else there. */
+    kept: string[];
+}
+/** Adds dependencies and scripts; never changes an existing entry. */
+export declare function mergePackageJson(text: string, additions: PackageJsonAdditions): MergeResult;

package/dist/project/package-json.js

@@ -0,0 +1,161 @@
+/**
+ * package.json edits that keep the file looking like the user left it.
+ *
+ * - {@link setDependencyRange} rewrites ONE range in place (text-level): key
+ *   order, indentation, line endings and every other byte stay untouched.
+ * - {@link mergePackageJson} adds dependencies/scripts (structural): the file is
+ *   re-serialized with its own indentation and trailing newline, new keys of an
+ *   alphabetically sorted dependency section are slotted in order, and an
+ *   existing entry is never changed.
+ */
+export const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies'];
+/** Index just past the value starting at `start` (a string, object, array or literal). */
+function skipValue(text, start) {
+    let i = start;
+    while (/\s/.test(text[i] ?? ''))
+        i++;
+    const first = text[i];
+    if (first === '"') {
+        i++;
+        while (i < text.length && text[i] !== '"')
+            i += text[i] === '\\' ? 2 : 1;
+        return i + 1;
+    }
+    if (first === '{' || first === '[') {
+        let depth = 0;
+        for (; i < text.length; i++) {
+            const ch = text[i];
+            if (ch === '"') {
+                i = skipValue(text, i) - 1;
+            }
+            else if (ch === '{' || ch === '[')
+                depth++;
+            else if (ch === '}' || ch === ']') {
+                depth--;
+                if (depth === 0)
+                    return i + 1;
+            }
+        }
+        return text.length;
+    }
+    while (i < text.length && !/[,}\]\s]/.test(text[i] ?? ''))
+        i++;
+    return i;
+}
+/**
+ * The `[start, end)` span of a top-level key's VALUE in a JSON object text, or
+ * undefined. Walks the top level only, so a nested key of the same name (an
+ * `overrides.dependencies`) never matches.
+ */
+export function topLevelValueSpan(text, key) {
+    let i = text.indexOf('{');
+    if (i === -1)
+        return undefined;
+    i++;
+    while (i < text.length) {
+        while (/[\s,]/.test(text[i] ?? ''))
+            i++;
+        if (text[i] !== '"')
+            return undefined;
+        const keyEnd = skipValue(text, i);
+        const name = JSON.parse(text.slice(i, keyEnd));
+        i = keyEnd;
+        while (/\s/.test(text[i] ?? ''))
+            i++;
+        if (text[i] !== ':')
+            return undefined;
+        i++;
+        while (/\s/.test(text[i] ?? ''))
+            i++;
+        const valueEnd = skipValue(text, i);
+        if (name === key)
+            return [i, valueEnd];
+        i = valueEnd;
+    }
+    return undefined;
+}
+/**
+ * Rewrites `section[name]` to `range`, touching only that string. Returns the
+ * text unchanged when the entry is not there.
+ */
+export function setDependencyRange(text, section, name, range) {
+    const span = topLevelValueSpan(text, section);
+    if (!span)
+        return text;
+    const [start, end] = span;
+    const body = text.slice(start, end);
+    const inner = topLevelValueSpan(body, name);
+    if (!inner)
+        return text;
+    const [valueStart, valueEnd] = inner;
+    return text.slice(0, start) + body.slice(0, valueStart) + JSON.stringify(range) + body.slice(valueEnd) + text.slice(end);
+}
+/** The indentation unit of a JSON text (default two spaces). */
+export function detectIndent(text) {
+    const match = /^[ \t]+(?=")/m.exec(text);
+    return match ? match[0] : '  ';
+}
+const isSorted = (keys) => keys.every((key, i) => i === 0 || keys[i - 1] <= key);
+/** Adds dependencies and scripts; never changes an existing entry. */
+export function mergePackageJson(text, additions) {
+    const pkg = JSON.parse(text);
+    const changes = [];
+    const kept = [];
+    for (const section of ['dependencies', 'devDependencies']) {
+        const wanted = additions[section];
+        if (!wanted)
+            continue;
+        const current = { ...(pkg[section] ?? {}) };
+        const sorted = isSorted(Object.keys(current));
+        let added = false;
+        for (const [name, range] of Object.entries(wanted)) {
+            const elsewhere = section === 'dependencies' ? pkg.devDependencies?.[name] : pkg.dependencies?.[name];
+            if (current[name] !== undefined || elsewhere !== undefined) {
+                if ((current[name] ?? elsewhere) !== range)
+                    kept.push(`${name} (kept ${current[name] ?? elsewhere})`);
+                continue;
+            }
+            current[name] = range;
+            changes.push(`${section}: + ${name}@${range}`);
+            added = true;
+        }
+        if (added)
+            pkg[section] = sorted ? Object.fromEntries(Object.entries(current).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : current;
+    }
+    const scripts = { ...(pkg.scripts ?? {}) };
+    let scriptsChanged = false;
+    for (const [name, command] of Object.entries(additions.scripts ?? {})) {
+        if (scripts[name] !== undefined) {
+            if (scripts[name] !== command)
+                kept.push(`script "${name}" (kept "${scripts[name]}")`);
+            continue;
+        }
+        scripts[name] = command;
+        changes.push(`scripts: + ${name}: ${command}`);
+        scriptsChanged = true;
+    }
+    for (const [name, { from, to }] of Object.entries(additions.replaceScripts ?? {})) {
+        if (scripts[name] === from) {
+            scripts[name] = to;
+            changes.push(`scripts: ${name}: ${from} → ${to}`);
+            scriptsChanged = true;
+        }
+        else if (scripts[name] === undefined) {
+            scripts[name] = to;
+            changes.push(`scripts: + ${name}: ${to}`);
+            scriptsChanged = true;
+        }
+        else if (scripts[name] !== to) {
+            kept.push(`script "${name}" (kept "${scripts[name]}")`);
+        }
+    }
+    if (scriptsChanged)
+        pkg.scripts = scripts;
+    if (changes.length === 0)
+        return { text, changes, kept };
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    let out = JSON.stringify(pkg, null, detectIndent(text));
+    if (eol !== '\n')
+        out = out.replaceAll('\n', eol);
+    return { text: text.endsWith('\n') ? out + eol : out, changes, kept };
+}

package/dist/project/run.d.ts

@@ -0,0 +1,55 @@
+import type { PackageManager } from '../index.js';
+import type { ResolveLatestOptions } from '../latest-versions.js';
+import { type AddPlan } from './add.js';
+import { type Colors, type Out } from './term.js';
+/**
+ * The project commands — `create-basalt update | add | doctor | info` — run
+ * inside an EXISTING app (any app, with or without `--cli`). In a scaffolded
+ * app they are also reachable as `pnpm basalt <command>`: bin/basalt.ts (with
+ * `--cli`) or the `basalt` script (`create-basalt --project`) hands them here.
+ *
+ * Every side effect goes through {@link ProjectCommandDeps}, so the commands
+ * are tested with temp dirs, a fake registry and a fake package manager.
+ */
+export declare const PROJECT_COMMANDS: readonly ['update', 'add', 'doctor', 'info'];
+export type ProjectCommand = (typeof PROJECT_COMMANDS)[number];
+export declare const isProjectCommand: (token: string | undefined) => token is ProjectCommand;
+export interface ProjectCommandDeps {
+    /** Directory to operate in (overridden by --cwd). */
+    cwd: string;
+    out: Out;
+    env: NodeJS.ProcessEnv;
+    /** Whether a human can answer a prompt (stdin is a TTY and not CI). */
+    interactive: boolean;
+    /** Whether stdout is a terminal (colors). */
+    isTTY: boolean;
+    /** Registry knobs (fetch, registry URL, clock, release-age window) — tests inject a fake fetch. */
+    registry?: ResolveLatestOptions;
+    /** Runs a command with inherited stdio; resolves false on failure (never throws). */
+    run(command: string, args: string[], cwd: string): Promise<boolean>;
+    /** Runs a command and returns its trimmed stdout (undefined on failure). */
+    capture(command: string, args: string[], cwd: string): Promise<string | undefined>;
+    /** Asks a yes/no question (default yes). */
+    confirm(message: string): Promise<boolean>;
+    /** Applies the installed @basaltkit/cli upgrade codemods. Default: {@link runInstalledCodemods}. */
+    codemods?(dir: string, out: Out, colors: Colors): Promise<void>;
+    nodeVersion?: string;
+}
+export declare const PROJECT_USAGE = "Project commands \u2014 run inside an existing Basalt app:\n\n  create-basalt update [options]      Update dependencies to their latest versions\n  create-basalt add <feature>         Add ui | cli | mcp to the app\n  create-basalt doctor                Check the project's health (read-only)\n  create-basalt info                  Versions summary for bug reports\n\nIn a scaffolded app: pnpm basalt <command>. Each command has --help.\n";
+export declare const COMMAND_USAGE: Record<ProjectCommand, string>;
+/** `pnpm basalt <args>` in that manager's spelling (npm needs `--` before flags). */
+export declare const basaltCommand: (pm: PackageManager, args: string) => string;
+/** Runs one project command; returns the process exit code. */
+export declare function runProjectCommand(argv: readonly string[], deps: ProjectCommandDeps): Promise<number>;
+export declare function renderAddPlan(plan: AddPlan, colors: Colors): string[];
+/**
+ * Runs the upgrade codemods of the app's INSTALLED @basaltkit/cli (the version
+ * just installed knows the migrations for itself) without booting the app.
+ */
+export declare function runInstalledCodemods(dir: string, out: Out, colors: Colors): Promise<void>;
+/** An @basaltkit/cli UpgradeFs rooted at `dir` (relative paths resolve against it, not process.cwd()). */
+export declare function projectUpgradeFs(dir: string): {
+    list(root: string): Promise<string[]>;
+    read(path: string): Promise<string>;
+    write(path: string, content: string): Promise<void>;
+};