create-basalt 1.9.0 → 1.10.0

package/dist/project/context.d.ts

@@ -0,0 +1,53 @@
+import type { PackageManager } from '../index.js';
+import type { ProjectOptions } from '../templates.js';
+import { type ProjectManifest } from './manifest.js';
+import type { PackageJson } from './package-json.js';
+/** A Basalt app on disk, as the project commands see it. */
+export interface ProjectContext {
+    dir: string;
+    /** Raw root package.json text (edits preserve its formatting). */
+    packageJsonText: string;
+    packageJson: PackageJson;
+    /** web/package.json, when the app has the frontend. */
+    web?: {
+        text: string;
+        json: PackageJson;
+    };
+    manifest?: ProjectManifest;
+    /** Features the app has now (manifest options, corrected by what package.json/the tree show). */
+    options: ProjectOptions;
+    pm: PackageManager;
+    /** Where `pm` came from — shown by doctor/info. */
+    pmSource: 'flag' | 'packageManager' | 'lockfile' | 'user-agent' | 'default';
+    /** Lockfiles present in the project root. */
+    lockfiles: string[];
+}
+export declare class NotABasaltAppError extends Error {
+    constructor(message: string);
+}
+export declare const LOCKFILES: ReadonlyArray<readonly [string, PackageManager]>;
+/**
+ * The package manager of an existing project: `--pm`, then the
+ * `packageManager` field, then the lockfile, then the manager that launched us
+ * (`npm_config_user_agent`), else npm. pnpm-workspace.yaml is deliberately not
+ * a signal — every scaffold writes it, whatever the manager.
+ */
+export declare function detectProjectPackageManager(pkg: PackageJson, lockfiles: readonly string[], flag?: PackageManager, userAgent?: string): {
+    pm: PackageManager;
+    source: ProjectContext['pmSource'];
+};
+export declare const allDependencies: (pkg: PackageJson) => Record<string, string>;
+/** Whether a package.json belongs to a Basalt app (any @basaltkit/* — or legacy @machize/* — dependency). */
+export declare const isBasaltPackage: (pkg: PackageJson) => boolean;
+/**
+ * The features an app has, from what is actually there: dependencies for the
+ * framework domains, the tree for ui (web/) and cli (bin/basalt.ts). The
+ * manifest supplies nothing the tree contradicts — a dependency removed since
+ * the scaffold turns its feature off.
+ */
+export declare function inferOptions(dir: string, pkg: PackageJson, manifest: ProjectManifest | undefined): ProjectOptions;
+/**
+ * Loads the app at `dir`. Throws {@link NotABasaltAppError} with an actionable
+ * message when there is no package.json or it has no @basaltkit dependency.
+ */
+export declare function loadProject(dir: string, pmFlag?: PackageManager, userAgent?: string | undefined): Promise<ProjectContext>;

package/dist/project/context.js

@@ -0,0 +1,112 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readManifest } from './manifest.js';
+export class NotABasaltAppError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NotABasaltAppError';
+    }
+}
+export const LOCKFILES = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['package-lock.json', 'npm'],
+    ['npm-shrinkwrap.json', 'npm'],
+    ['yarn.lock', 'yarn'],
+    ['bun.lock', 'bun'],
+    ['bun.lockb', 'bun'],
+];
+const MANAGERS = ['pnpm', 'npm', 'yarn', 'bun'];
+/**
+ * The package manager of an existing project: `--pm`, then the
+ * `packageManager` field, then the lockfile, then the manager that launched us
+ * (`npm_config_user_agent`), else npm. pnpm-workspace.yaml is deliberately not
+ * a signal — every scaffold writes it, whatever the manager.
+ */
+export function detectProjectPackageManager(pkg, lockfiles, flag, userAgent) {
+    if (flag)
+        return { pm: flag, source: 'flag' };
+    const declared = typeof pkg.packageManager === 'string' ? pkg.packageManager.split('@')[0] : undefined;
+    if (declared && MANAGERS.includes(declared)) {
+        return { pm: declared, source: 'packageManager' };
+    }
+    for (const [file, pm] of LOCKFILES)
+        if (lockfiles.includes(file))
+            return { pm, source: 'lockfile' };
+    const agent = userAgent?.split(' ')[0]?.split('/')[0];
+    if (agent && MANAGERS.includes(agent))
+        return { pm: agent, source: 'user-agent' };
+    return { pm: 'npm', source: 'default' };
+}
+export const allDependencies = (pkg) => ({
+    ...pkg.optionalDependencies,
+    ...pkg.devDependencies,
+    ...pkg.dependencies,
+});
+/** Whether a package.json belongs to a Basalt app (any @basaltkit/* — or legacy @machize/* — dependency). */
+export const isBasaltPackage = (pkg) => Object.keys(allDependencies(pkg)).some((name) => name.startsWith('@basaltkit/') || name.startsWith('@machize/'));
+/**
+ * The features an app has, from what is actually there: dependencies for the
+ * framework domains, the tree for ui (web/) and cli (bin/basalt.ts). The
+ * manifest supplies nothing the tree contradicts — a dependency removed since
+ * the scaffold turns its feature off.
+ */
+export function inferOptions(dir, pkg, manifest) {
+    const deps = allDependencies(pkg);
+    const has = (name) => deps[name] !== undefined;
+    return {
+        name: typeof pkg.name === 'string' && pkg.name !== '' ? pkg.name : (manifest?.options.name ?? 'app'),
+        tenancy: has('@basaltkit/tenancy'),
+        auth: has('@basaltkit/auth'),
+        billing: has('@basaltkit/subscriptions'),
+        ui: existsSync(join(dir, 'web', 'package.json')),
+        cli: existsSync(join(dir, 'bin', 'basalt.ts')),
+        mcp: has('@basaltkit/mcp'),
+        prisma: has('@prisma/client') || has('prisma'),
+    };
+}
+/**
+ * Loads the app at `dir`. Throws {@link NotABasaltAppError} with an actionable
+ * message when there is no package.json or it has no @basaltkit dependency.
+ */
+export async function loadProject(dir, pmFlag, userAgent = process.env['npm_config_user_agent']) {
+    let packageJsonText;
+    try {
+        packageJsonText = await readFile(join(dir, 'package.json'), 'utf8');
+    }
+    catch {
+        throw new NotABasaltAppError(`No package.json in ${dir}. Run this inside a Basalt app (or pass --cwd=<app dir>). To create one: npm create basalt <name>`);
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(packageJsonText);
+    }
+    catch (error) {
+        throw new NotABasaltAppError(`${join(dir, 'package.json')} is not valid JSON: ${error.message}`);
+    }
+    if (!isBasaltPackage(packageJson)) {
+        throw new NotABasaltAppError(`${join(dir, 'package.json')} has no @basaltkit/* dependency — this does not look like a Basalt app. To create one: npm create basalt <name>`);
+    }
+    let web;
+    try {
+        const text = await readFile(join(dir, 'web', 'package.json'), 'utf8');
+        web = { text, json: JSON.parse(text) };
+    }
+    catch {
+        web = undefined;
+    }
+    const manifest = await readManifest(dir);
+    const lockfiles = LOCKFILES.map(([file]) => file).filter((file) => existsSync(join(dir, file)));
+    const { pm, source } = detectProjectPackageManager(packageJson, lockfiles, pmFlag, userAgent);
+    return {
+        dir,
+        packageJsonText,
+        packageJson,
+        ...(web ? { web } : {}),
+        ...(manifest ? { manifest } : {}),
+        options: inferOptions(dir, packageJson, manifest),
+        pm,
+        pmSource: source,
+        lockfiles,
+    };
+}

package/dist/project/doctor.d.ts

@@ -0,0 +1,40 @@
+import { type ResolveLatestOptions } from '../latest-versions.js';
+import { type ProjectContext } from './context.js';
+import type { Colors } from './term.js';
+/**
+ * `create-basalt doctor`: a read-only health check of an app — nothing is
+ * written, nothing is installed. Errors make the exit code non-zero; warnings
+ * and notes do not.
+ */
+export type Level = 'ok' | 'info' | 'warn' | 'error';
+export interface DoctorFinding {
+    level: Level;
+    /** Short area label: node, pm, deps, env, prisma, mcp, tooling. */
+    area: string;
+    message: string;
+}
+export interface DoctorOptions {
+    /** Node version to check (default: the running one). */
+    nodeVersion?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Skip the registry ("behind latest" check). */
+    offline?: boolean;
+    registry?: ResolveLatestOptions;
+    /** `<pm> --version` (injected; undefined when unavailable). */
+    pmVersion?: string;
+}
+/** The Node range every @basaltkit package declares. */
+export declare const BASALT_NODE_RANGE = ">=22.5.0";
+/** Installed version of `name` as the app resolves it (top-level node_modules). */
+export declare function installedVersion(dir: string, name: string): Promise<string | undefined>;
+/** Parses a dotenv file (KEY=VALUE, optional quotes, # comments). */
+export declare function parseDotenv(text: string): Record<string, string>;
+/** The env prefix src/env.ts passes to defineEnv (`prefix: 'X'` or `prefix: { value: 'X' … }`). */
+export declare function envPrefixOf(envTs: string | undefined, name: string): string | undefined;
+export declare function runDoctor(ctx: ProjectContext, options?: DoctorOptions): Promise<DoctorFinding[]>;
+export declare function renderFindings(findings: readonly DoctorFinding[], colors: Colors): string[];
+/** `create-basalt info`: a paste-able versions summary for bug reports. */
+export declare function projectInfo(ctx: ProjectContext, options?: {
+    nodeVersion?: string;
+    pmVersion?: string;
+}): Promise<string[]>;

package/dist/project/doctor.js

@@ -0,0 +1,350 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { arch, platform } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { binStatus } from '../bin-template.js';
+import { alwaysLatest, lookupLatestVersions } from '../latest-versions.js';
+import { envPrefix } from '../templates.js';
+import { allDependencies } from './context.js';
+import { ownVersion } from './manifest.js';
+import { compareVersions, parseSimpleRange, parseVersion, satisfies } from './semver.js';
+/** Mirrors the placeholder check of `secret()` in @basaltkit/env (src/secret.ts). */
+const INSECURE_SECRET = /change.?me|changeme|placeholder|example|secret|password|default|test|xxxx+|0000+/i;
+/** The Node range every @basaltkit package declares. */
+export const BASALT_NODE_RANGE = '>=22.5.0';
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Installed version of `name` as the app resolves it (top-level node_modules). */
+export async function installedVersion(dir, name) {
+    const pkg = await readJson(join(dir, 'node_modules', ...name.split('/'), 'package.json'));
+    return typeof pkg?.version === 'string' ? pkg.version : undefined;
+}
+/**
+ * Every installed version of each @basaltkit package: pnpm's virtual store
+ * (`node_modules/.pnpm/@basaltkit+core@1.5.0…`) plus npm/yarn nesting one level deep.
+ */
+async function installedFrameworkVersions(dir) {
+    const found = new Map();
+    const add = (name, version) => {
+        const set = found.get(name) ?? new Set();
+        set.add(version);
+        found.set(name, set);
+    };
+    const store = await readdir(join(dir, 'node_modules', '.pnpm')).catch(() => []);
+    for (const entry of store) {
+        const match = /^@basaltkit\+([^@]+)@(\d+\.\d+\.\d+[^_]*)/.exec(entry);
+        if (match)
+            add(`@basaltkit/${match[1]}`, match[2]);
+    }
+    const scope = join(dir, 'node_modules', '@basaltkit');
+    for (const entry of await readdir(scope).catch(() => [])) {
+        const version = await installedVersion(dir, `@basaltkit/${entry}`);
+        if (version)
+            add(`@basaltkit/${entry}`, version);
+        for (const nested of await readdir(join(scope, entry, 'node_modules', '@basaltkit')).catch(() => [])) {
+            const pkg = await readJson(join(scope, entry, 'node_modules', '@basaltkit', nested, 'package.json'));
+            if (typeof pkg?.version === 'string')
+                add(`@basaltkit/${nested}`, pkg.version);
+        }
+    }
+    return found;
+}
+/** Parses a dotenv file (KEY=VALUE, optional quotes, # comments). */
+export function parseDotenv(text) {
+    const out = {};
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        let value = (match[2] ?? '').trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+            value = value.slice(1, -1);
+        out[match[1]] = value;
+    }
+    return out;
+}
+/** The env prefix src/env.ts passes to defineEnv (`prefix: 'X'` or `prefix: { value: 'X' … }`). */
+export function envPrefixOf(envTs, name) {
+    if (envTs === undefined)
+        return envPrefix(name);
+    const match = /prefix:\s*(?:\{\s*value:\s*)?['"]([A-Z0-9_]+)['"]/.exec(envTs);
+    return match ? match[1] : /prefix:/.test(envTs) ? undefined : '';
+}
+export async function runDoctor(ctx, options = {}) {
+    const findings = [];
+    const push = (level, area, message) => {
+        findings.push({ level, area, message });
+    };
+    const env = options.env ?? process.env;
+    const deps = allDependencies(ctx.packageJson);
+    const { dir } = ctx;
+    // --- Node -----------------------------------------------------------------
+    const node = options.nodeVersion ?? process.versions.node;
+    const engines = ctx.packageJson.engines?.['node'];
+    for (const [range, origin] of [
+        ...(engines ? [[engines, 'package.json engines.node']] : []),
+        [BASALT_NODE_RANGE, 'Basalt'],
+    ]) {
+        const ok = satisfies(node, range);
+        if (ok === false)
+            push('error', 'node', `Node ${node} does not satisfy ${range} (${origin}).`);
+        else if (ok === true)
+            push('ok', 'node', `Node ${node} satisfies ${range} (${origin}).`);
+    }
+    // --- Package manager --------------------------------------------------------
+    push('ok', 'pm', `Package manager: ${ctx.pm}${options.pmVersion ? ` ${options.pmVersion}` : ''} (from ${ctx.pmSource}).`);
+    if (ctx.lockfiles.length > 1)
+        push('warn', 'pm', `Several lockfiles (${ctx.lockfiles.join(', ')}) — keep the one of ${ctx.pm}.`);
+    if (ctx.lockfiles.length === 0)
+        push('warn', 'pm', `No lockfile — run \`${ctx.pm} install\` and commit it.`);
+    const declaredPm = ctx.packageJson.packageManager?.split('@')[0];
+    const lockPm = ctx.lockfiles[0] ? ctx.lockfiles[0].split(/[-.]/)[0] : undefined;
+    if (declaredPm && lockPm && ctx.lockfiles.length === 1 && !ctx.lockfiles[0]?.startsWith(declaredPm) && !(declaredPm === 'npm' && lockPm === 'npm')) {
+        push('warn', 'pm', `packageManager says ${declaredPm}, but the lockfile is ${ctx.lockfiles[0]}.`);
+    }
+    if (ctx.options.ui && ctx.pm !== 'pnpm') {
+        push('error', 'pm', `web/ is a pnpm workspace member, but this project uses ${ctx.pm}.`);
+    }
+    // --- Dependencies -----------------------------------------------------------
+    const installedRoot = existsSync(join(dir, 'node_modules'));
+    if (!installedRoot) {
+        push('error', 'deps', `Dependencies are not installed — run \`${ctx.pm} install\`.`);
+    }
+    else {
+        const missing = [];
+        const outOfSync = [];
+        for (const [name, range] of Object.entries(deps)) {
+            const version = await installedVersion(dir, name);
+            if (version === undefined) {
+                if (!(ctx.packageJson.optionalDependencies && name in ctx.packageJson.optionalDependencies))
+                    missing.push(name);
+                continue;
+            }
+            if (satisfies(version, range) === false)
+                outOfSync.push(`${name} (${version} installed, ${range} declared)`);
+        }
+        if (missing.length > 0)
+            push('error', 'deps', `Not installed: ${missing.join(', ')} — run \`${ctx.pm} install\`.`);
+        if (outOfSync.length > 0)
+            push('error', 'deps', `Installed versions do not match package.json: ${outOfSync.join('; ')} — run \`${ctx.pm} install\`.`);
+        const framework = await installedFrameworkVersions(dir);
+        const duplicates = [...framework].filter(([, versions]) => versions.size > 1);
+        for (const [name, versions] of duplicates) {
+            push('warn', 'deps', `${name} is installed in ${versions.size} versions (${[...versions].sort().join(', ')}) — framework singletons (DI tokens, context) may not line up; align the ranges (\`basalt update\`).`);
+        }
+        let peerProblems = 0;
+        for (const name of Object.keys(deps).filter((dep) => dep.startsWith('@basaltkit/'))) {
+            const pkg = await readJson(join(dir, 'node_modules', ...name.split('/'), 'package.json'));
+            const optional = (pkg?.['peerDependenciesMeta'] ?? {});
+            for (const [peer, range] of Object.entries(pkg?.peerDependencies ?? {})) {
+                const version = await installedVersion(dir, peer);
+                if (version === undefined) {
+                    if (!optional[peer]?.optional && peer.startsWith('@basaltkit/')) {
+                        peerProblems++;
+                        push('warn', 'deps', `${name} expects ${peer} ${range}, which is not installed.`);
+                    }
+                    continue;
+                }
+                if (satisfies(version, range) === false) {
+                    peerProblems++;
+                    push('error', 'deps', `${name} expects ${peer} ${range}, but ${version} is installed.`);
+                }
+            }
+        }
+        if (missing.length === 0 && outOfSync.length === 0 && duplicates.length === 0 && peerProblems === 0) {
+            push('ok', 'deps', 'Installed dependencies match package.json; @basaltkit peer ranges are satisfied.');
+        }
+    }
+    for (const name of ['@basaltkit/ai-mcp', '@basaltkit/ai', '@basaltkit/generator', 'create-basalt']) {
+        if (ctx.packageJson.dependencies?.[name] !== undefined) {
+            push('warn', 'deps', `${name} is a runtime dependency — it is dev tooling; move it to devDependencies.`);
+        }
+    }
+    // --- Behind latest ----------------------------------------------------------
+    if (!options.offline) {
+        const framework = Object.entries(deps).filter(([name]) => alwaysLatest(name));
+        const { results } = await lookupLatestVersions(framework.map(([name]) => name), () => false, options.registry ?? {});
+        if (framework.length > 0 && framework.every(([name]) => results.get(name)?.latest === undefined)) {
+            push('info', 'updates', 'Registry unreachable — skipped the "behind latest" check.');
+        }
+        else {
+            const behind = framework.filter(([name, range]) => {
+                const latest = parseVersion(results.get(name)?.latest ?? '');
+                const floor = parseSimpleRange(range);
+                return latest !== undefined && floor !== undefined && compareVersions(latest, floor.parsed) > 0;
+            });
+            if (behind.length > 0) {
+                push('warn', 'updates', `${behind.length} framework package(s) behind latest: ${behind
+                    .map(([name, range]) => `${name} ${range} → ${results.get(name)?.latest}`)
+                    .join(', ')} — run \`basalt update\` (or npx create-basalt@latest update).`);
+            }
+            else if (framework.length > 0)
+                push('ok', 'updates', 'Framework packages are on their latest versions.');
+        }
+    }
+    // --- Environment ------------------------------------------------------------
+    const envTs = await readText(join(dir, 'src', 'env.ts'));
+    const dotenvText = await readText(join(dir, '.env'));
+    const dotenv = dotenvText ? parseDotenv(dotenvText) : {};
+    if (dotenvText === undefined && existsSync(join(dir, '.env.example'))) {
+        push('info', 'env', 'No .env — copy .env.example to .env (and start with --env-file=.env) or export the variables.');
+    }
+    const prefix = envPrefixOf(envTs, ctx.options.name);
+    const lookup = (name) => {
+        const names = prefix ? [`${prefix}_${name}`, name] : [name];
+        for (const key of names) {
+            if (env[key] !== undefined && env[key] !== '')
+                return { value: env[key], from: `$${key}` };
+        }
+        for (const key of names) {
+            if (dotenv[key] !== undefined && dotenv[key] !== '')
+                return { value: dotenv[key], from: `.env ${key}` };
+        }
+        return undefined;
+    };
+    if (ctx.options.auth) {
+        const declared = envTs ? /APP_SECRET:\s*secret\(\{[^}]*minLength:\s*(\d+)/.exec(envTs) : null;
+        const minLength = declared ? Number(declared[1]) : 32;
+        const secret = lookup('APP_SECRET');
+        const label = prefix ? `${prefix}_APP_SECRET` : 'APP_SECRET';
+        if (!secret) {
+            push('warn', 'env', `${label} is not set — fine for \`dev\` (development default), required by \`start\`/production (≥ ${minLength} chars: openssl rand -base64 48).`);
+        }
+        else if (secret.value.length < minLength) {
+            push('error', 'env', `${label} (${secret.from}) is ${secret.value.length} characters — the app requires at least ${minLength}.`);
+        }
+        else if (INSECURE_SECRET.test(secret.value)) {
+            push('error', 'env', `${label} (${secret.from}) looks like a placeholder — the app rejects it outside development.`);
+        }
+        else {
+            push('ok', 'env', `${label} is set (${secret.from}, ${secret.value.length} characters).`);
+        }
+    }
+    if (ctx.options.prisma) {
+        const url = lookup('DATABASE_URL');
+        if (!url)
+            push('warn', 'env', `${prefix ? `${prefix}_` : ''}DATABASE_URL is not set — the app does not boot without it.`);
+        else
+            push('ok', 'env', `${prefix ? `${prefix}_` : ''}DATABASE_URL is set (${url.from}).`);
+    }
+    // --- Prisma -------------------------------------------------------------------
+    const schemaPath = join(dir, 'prisma', 'schema.prisma');
+    const schema = await readText(schemaPath);
+    if (schema !== undefined) {
+        const output = /generator\s+\w+\s*\{[^}]*output\s*=\s*"([^"]+)"/.exec(schema)?.[1];
+        const clientDir = output ? resolve(dirname(schemaPath), output) : join(dir, 'node_modules', '.prisma', 'client');
+        if (!existsSync(clientDir)) {
+            push('error', 'prisma', `Prisma client not generated (${clientDir.slice(dir.length + 1) || clientDir}) — run \`${ctx.pm === 'npm' ? 'npm run' : ctx.pm} db:generate\` (prisma generate).`);
+        }
+        else {
+            push('ok', 'prisma', 'Prisma client is generated.');
+        }
+        const migrations = await readdir(join(dir, 'prisma', 'migrations'), { withFileTypes: true }).catch(() => []);
+        const count = migrations.filter((entry) => entry.isDirectory()).length;
+        if (count === 0)
+            push('warn', 'prisma', `No migrations yet — run \`${ctx.pm === 'npm' ? 'npm run' : ctx.pm} db:migrate\` (the app boots with assertMigrated).`);
+        else
+            push('info', 'prisma', `${count} migration(s) on disk; whether they are applied needs the database: \`prisma migrate status\`.`);
+    }
+    // --- MCP -------------------------------------------------------------------------
+    if (deps['@basaltkit/ai-mcp'] !== undefined) {
+        const text = await readText(join(dir, '.mcp.json'));
+        if (text === undefined) {
+            push('warn', 'mcp', '@basaltkit/ai-mcp is installed but there is no .mcp.json — MCP clients will not find the dev bridge.');
+        }
+        else {
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch (error) {
+                push('error', 'mcp', `.mcp.json is not valid JSON: ${error.message}`);
+            }
+            if (parsed) {
+                const servers = Object.values(parsed.mcpServers ?? {});
+                const bridge = servers.some((server) => {
+                    const parts = [server.command, ...(Array.isArray(server.args) ? server.args : [])].map(String);
+                    return parts.some((part) => part.includes('@basaltkit/ai-mcp') || part.includes('basalt-ai-mcp'));
+                });
+                if (bridge)
+                    push('ok', 'mcp', '.mcp.json registers the basalt-ai-mcp dev bridge.');
+                else
+                    push('warn', 'mcp', '.mcp.json has no server running @basaltkit/ai-mcp (basalt-ai-mcp).');
+            }
+        }
+    }
+    // --- Project tooling -------------------------------------------------------------
+    const bin = await readText(join(dir, 'bin', 'basalt.ts'));
+    const status = binStatus(bin, ctx.manifest?.files['bin/basalt.ts']);
+    if (status === 'patchable')
+        push('warn', 'tooling', 'bin/basalt.ts predates the project commands — `npx create-basalt@latest update` patches it.');
+    if (status === 'modified')
+        push('info', 'tooling', 'bin/basalt.ts is customised and does not delegate update/add/doctor/info — see `create-basalt update` for the snippet.');
+    if (!ctx.manifest)
+        push('info', 'tooling', 'No .basalt/project.json (scaffolded before create-basalt 1.10) — features are inferred from package.json.');
+    return findings;
+}
+export function renderFindings(findings, colors) {
+    const icon = {
+        ok: colors.green('✓'),
+        info: colors.cyan('i'),
+        warn: colors.yellow('!'),
+        error: colors.red('✗'),
+    };
+    const lines = findings.map((finding) => `${icon[finding.level]} ${colors.dim(finding.area.padEnd(8))} ${finding.message}`);
+    const errors = findings.filter((finding) => finding.level === 'error').length;
+    const warnings = findings.filter((finding) => finding.level === 'warn').length;
+    lines.push('', errors > 0
+        ? colors.red(`${errors} error(s), ${warnings} warning(s).`)
+        : warnings > 0
+            ? colors.yellow(`No errors, ${warnings} warning(s).`)
+            : colors.green('All checks passed.'));
+    return lines;
+}
+/** `create-basalt info`: a paste-able versions summary for bug reports. */
+export async function projectInfo(ctx, options = {}) {
+    const deps = allDependencies(ctx.packageJson);
+    const enabled = ['tenancy', 'auth', 'billing', 'ui', 'cli', 'mcp', 'prisma'].filter((key) => ctx.options[key]);
+    const lines = [
+        `create-basalt  ${ownVersion()}`,
+        `node           ${options.nodeVersion ?? process.versions.node}`,
+        `os             ${platform()} ${arch()}`,
+        `pm             ${ctx.pm}${options.pmVersion ? ` ${options.pmVersion}` : ''} (${ctx.pmSource})`,
+        `app            ${ctx.options.name}${ctx.manifest ? ` (created with create-basalt ${ctx.manifest.createdWith})` : ''}`,
+        `features       ${enabled.length > 0 ? enabled.join(', ') : 'none'}`,
+        '',
+        'package                       declared        installed',
+    ];
+    const interesting = Object.keys(deps)
+        .filter((name) => alwaysLatest(name) || ['typescript', 'zod', 'prisma', '@prisma/client', 'tsx', 'vitest'].includes(name))
+        .sort();
+    for (const name of interesting) {
+        const installed = (await installedVersion(ctx.dir, name)) ?? '-';
+        lines.push(`${name.padEnd(30)}${deps[name].padEnd(16)}${installed}`);
+    }
+    if (ctx.web) {
+        const webDeps = allDependencies(ctx.web.json);
+        for (const name of Object.keys(webDeps).filter((dep) => dep.startsWith('@basaltkit/') || ['react', 'vite'].includes(dep)).sort()) {
+            const installed = (await installedVersion(join(ctx.dir, 'web'), name)) ?? '-';
+            lines.push(`${`web: ${name}`.padEnd(30)}${webDeps[name].padEnd(16)}${installed}`);
+        }
+    }
+    return lines;
+}

package/dist/project/manifest.d.ts

@@ -0,0 +1,36 @@
+import type { ProjectOptions } from '../templates.js';
+/**
+ * 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 declare const MANIFEST_PATH = ".basalt/project.json";
+export interface ProjectManifest {
+    /** Bumped only on an incompatible change of this file's shape. */
+    manifestVersion: 1;
+    generator: 'create-basalt';
+    /** create-basalt version that created the project. */
+    createdWith: string;
+    /** create-basalt version that last updated this manifest. */
+    updatedWith: string;
+    options: ProjectOptions;
+    /** Project-relative path → `sha256-<hex>` of the content create-basalt wrote. */
+    files: Record<string, string>;
+}
+/** Content hash, insensitive to CRLF/LF (git autocrlf must not make a file look edited). */
+export declare function hashContent(content: string): string;
+/** This create-basalt release's version (from its own package.json). */
+export declare function ownVersion(): string;
+export declare function createManifest(options: ProjectOptions, files: Readonly<Record<string, string>>): ProjectManifest;
+/** Records newly written files (and the options now on) in an existing manifest. */
+export declare function extendManifest(manifest: ProjectManifest, options: ProjectOptions, written: Readonly<Record<string, string>>): ProjectManifest;
+export declare const serializeManifest: (manifest: ProjectManifest) => string;
+/** Reads `.basalt/project.json`; undefined when absent or unreadable (treated as "no manifest"). */
+export declare function readManifest(dir: string): Promise<ProjectManifest | undefined>;
+/** Whether `content` is exactly what create-basalt wrote at `path` (per the manifest). */
+export declare function isPristine(manifest: ProjectManifest | undefined, path: string, content: string): boolean;