toiljs 0.0.116 → 0.0.117

package/src/cli/doctor.ts

@@ -1,982 +0,0 @@
-/**
- * `toiljs doctor`, read-only project diagnostics. Gathers facts from disk (package.json, lockfiles,
- * the resolved `toil.config`, the app entry, `index.html`, the scanned routes, client source files,
- * and the server target), runs the pure checks in `diagnostics.ts`, and prints a grouped human
- * report (or `--json` for CI). Never throws on a partial/non-toiljs project: missing inputs become
- * fail/warn checks. Sets a non-zero exit code when any check fails.
- */
-import fs from 'node:fs';
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import {
-    loadConfig,
-    type ResolvedToilConfig,
-    scanRoutes,
-    TOIL_SERVER_ENV_DTS,
-} from 'toiljs/compiler';
-
-import {
-    type AuthFacts,
-    type Check,
-    checkAuthSecrets,
-    checkBasePath,
-    checkConfigLoads,
-    checkDevScripts,
-    checkDir,
-    checkDuplicatePatterns,
-    type CheckGroup,
-    checkMigrationsDir,
-    checkMountSlots,
-    checkNode,
-    checkPackageManager,
-    checkPeer,
-    checkPrettierPlugin,
-    checkRelativeAssets,
-    checkRestDispatch,
-    checkRootElement,
-    checkRoutesPresent,
-    checkRpcWiring,
-    checkSeoUrl,
-    checkServerEntry,
-    checkServerTsPlugin,
-    type CheckStatus,
-    checkStyling,
-    checkToilconfig,
-    checkToiljsInstalled,
-    checkToilscriptInstalled,
-    checkTypeScript,
-    checkWasmBuilt,
-    findRelativeAssets,
-    hasFailures,
-    rangeMajor,
-    type RestFacts,
-    RPC_TOILSCRIPT_MIN,
-    type RpcFacts,
-    satisfiesMin,
-    type SourceFile,
-    summarize,
-    TYPESCRIPT_FIX_RANGE,
-} from './diagnostics.js';
-import {
-    detectTailwind,
-    type Preprocessor,
-    PREPROCESSOR_PKG,
-    preprocessorForExt,
-    TAILWIND_ENTRY,
-} from './features.js';
-import { accent, bold, danger, dim, success, version, warn } from './ui.js';
-
-export interface DoctorOptions {
-    readonly root?: string;
-    readonly cwd: string;
-    /** Emit machine-readable JSON instead of the human report. */
-    readonly json?: boolean;
-    /** Auto-fix what can be fixed in place (the typed-RPC wiring, and an unsupported typescript). */
-    readonly fix?: boolean;
-}
-
-/** Parses a JSON file into a plain object, or null on any error / non-object. */
-function readJsonObject(file: string): Record<string, unknown> | null {
-    try {
-        const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
-        return typeof parsed === 'object' && parsed !== null
-            ? (parsed as Record<string, unknown>)
-            : null;
-    } catch {
-        return null;
-    }
-}
-
-/** Coerces a value to a `Record<string, string>` (drops non-string entries). */
-function stringRecord(value: unknown): Record<string, string> {
-    if (typeof value !== 'object' || value === null) return {};
-    const out: Record<string, string> = {};
-    for (const [k, v] of Object.entries(value)) if (typeof v === 'string') out[k] = v;
-    return out;
-}
-
-function readFile(file: string): string | null {
-    try {
-        return fs.readFileSync(file, 'utf8');
-    } catch {
-        return null;
-    }
-}
-
-function writeFile(file: string, content: string): void {
-    fs.writeFileSync(file, content);
-}
-
-/**
- * Whether `name` is installed for the project at `root`. Tries Node resolution first (handles
- * hoisting), then falls back to walking `node_modules`, since a strict `exports` map can make
- * `require.resolve('<pkg>')` throw even when the package is present (the toilscript false positive).
- */
-function isPackageInstalled(root: string, name: string): boolean {
-    const require = createRequire(path.join(root, 'package.json'));
-    for (const id of [`${name}/package.json`, name]) {
-        try {
-            require.resolve(id);
-            return true;
-        } catch {
-            // try the next resolution strategy
-        }
-    }
-    for (let dir = root; ; ) {
-        if (fs.existsSync(path.join(dir, 'node_modules', name, 'package.json'))) return true;
-        const parent = path.dirname(dir);
-        if (parent === dir) return false;
-        dir = parent;
-    }
-}
-
-/**
- * The version of `name` actually installed for the project at `root`, or null when absent. Reads the
- * resolved package.json rather than trusting the declared range, since the installed copy is what
- * the compiler API consumers load. Falls back to walking `node_modules` (see `isPackageInstalled`).
- */
-function installedVersion(root: string, name: string): string | null {
-    const require = createRequire(path.join(root, 'package.json'));
-    let pkgPath: string | null = null;
-    try {
-        pkgPath = require.resolve(`${name}/package.json`);
-    } catch {
-        for (let dir = root; pkgPath === null; ) {
-            const candidate = path.join(dir, 'node_modules', name, 'package.json');
-            if (fs.existsSync(candidate)) pkgPath = candidate;
-            const parent = path.dirname(dir);
-            if (parent === dir) break;
-            dir = parent;
-        }
-    }
-    if (pkgPath === null) return null;
-    const pkg = readJsonObject(pkgPath);
-    return pkg && typeof pkg.version === 'string' ? pkg.version : null;
-}
-
-/**
- * Pins an unsupported TypeScript (the native 7.x, which ships no JavaScript compiler API) back to a
- * range toiljs can drive. Rewrites whichever of `devDependencies`/`dependencies` declares it; a
- * project with no declaration at all is left alone (nothing to pin), and the reinstall is left to
- * the user since only they know their package manager.
- */
-function applyTypeScriptFix(root: string): RpcFixResult {
-    const changed: string[] = [];
-    const skipped: string[] = [];
-
-    const pkgPath = path.join(root, 'package.json');
-    const pkg = readJsonObject(pkgPath);
-    if (pkg === null) return { changed, skipped };
-
-    const field = (['devDependencies', 'dependencies'] as const).find((f) => {
-        const deps = asRecord(pkg[f]);
-        return deps !== null && typeof deps.typescript === 'string';
-    });
-    if (field === undefined) {
-        // Nothing declares typescript: it is either absent or hoisted from a workspace root.
-        if (installedVersion(root, 'typescript') !== null) {
-            skipped.push('typescript (installed but not declared in package.json; pin it by hand)');
-        }
-        return { changed, skipped };
-    }
-
-    const deps = asRecord(pkg[field]);
-    if (deps === null) return { changed, skipped };
-    const declared = deps.typescript as string;
-    const declaredMajor = rangeMajor(declared);
-    const installedMajor = rangeMajor(installedVersion(root, 'typescript') ?? '');
-    const unsupported =
-        (declaredMajor !== null && declaredMajor >= 7) ||
-        (installedMajor !== null && installedMajor >= 7);
-    if (!unsupported) return { changed, skipped };
-
-    deps.typescript = TYPESCRIPT_FIX_RANGE;
-    writeFile(pkgPath, JSON.stringify(pkg, null, 4) + '\n');
-    changed.push(`package.json (typescript ${declared} -> ${TYPESCRIPT_FIX_RANGE})`);
-    return { changed, skipped };
-}
-
-/** Narrows a value to a plain (non-array) object, or null. */
-function asRecord(value: unknown): Record<string, unknown> | null {
-    return typeof value === 'object' && value !== null && !Array.isArray(value)
-        ? (value as Record<string, unknown>)
-        : null;
-}
-
-const RPC_MODULE_FLAG = '--rpcModule shared/server.ts';
-const RPC_GITIGNORE_LINE = 'shared/server.ts';
-const RPC_GITIGNORE_RE = /(^|\n)\s*shared\/server\.ts\s*(\r?\n|$)/;
-
-/**
- * Whether a dependency range is an ordinary registry semver range (so a deliberate
- * `latest`/`*`/`file:`/`github:`/`workspace:`/`npm:` pin is left untouched and treated
- * as already-OK rather than clobbered to a version).
- */
-function looksLikeSemverRange(range: string): boolean {
-    return /^\s*[v^~>=<]*\s*\d+\.\d+/.test(range);
-}
-
-/** Reads the project and reports which parts of the typed-RPC wiring are present. */
-function gatherRpcFacts(root: string): RpcFacts {
-    const pkg = readJsonObject(path.join(root, 'package.json'));
-    const scripts = pkg ? stringRecord(pkg.scripts) : {};
-    const deps = {
-        ...(pkg ? stringRecord(pkg.dependencies) : {}),
-        ...(pkg ? stringRecord(pkg.devDependencies) : {}),
-    };
-    const tsconfig = readJsonObject(path.join(root, 'tsconfig.json'));
-    const gitignore = readFile(path.join(root, '.gitignore'));
-
-    // Either the combined `build` or `build:server` carrying --rpcModule counts (the fixer writes both).
-    const buildServerWired = [scripts['build:server'], scripts['build']].some(
-        (s) => typeof s === 'string' && s.includes('--rpcModule'),
-    );
-
-    let tsconfigWired = false;
-    if (tsconfig) {
-        // An absent `include` compiles all files, so `shared` is covered implicitly.
-        const include = tsconfig.include;
-        const hasShared = !Array.isArray(include) || include.includes('shared');
-        const paths = asRecord(asRecord(tsconfig.compilerOptions)?.paths);
-        tsconfigWired = hasShared && paths !== null && 'shared/*' in paths;
-    }
-
-    const gitignoreWired = gitignore !== null && RPC_GITIGNORE_RE.test(gitignore);
-    const range = deps.toilscript;
-    // A non-semver range (file:/github:/latest/*) can't be assessed; don't flag it.
-    const toilscriptOk =
-        range == null
-            ? false
-            : looksLikeSemverRange(range)
-              ? satisfiesMin(range, RPC_TOILSCRIPT_MIN)
-              : true;
-
-    return { buildServerWired, tsconfigWired, gitignoreWired, toilscriptOk };
-}
-
-/** The server `.ts` sources, read from the directories of the toilconfig entries (capped). */
-function serverSources(root: string, toilconfig: Record<string, unknown> | null): string[] {
-    const dirs = new Set<string>();
-    const entries = Array.isArray(toilconfig?.entries)
-        ? (toilconfig.entries as unknown[]).filter((e): e is string => typeof e === 'string')
-        : [];
-    for (const e of entries) dirs.add(path.dirname(path.resolve(root, e)));
-
-    const out: string[] = [];
-    const cap = 200;
-    const maxDepth = 16; // bounds the walk so a symlink cycle in a hostile project can't hang doctor
-    const visit = (current: string, depth: number): void => {
-        if (out.length >= cap || depth > maxDepth) return;
-        let listing: fs.Dirent[];
-        try {
-            listing = fs.readdirSync(current, { withFileTypes: true });
-        } catch {
-            return;
-        }
-        for (const entry of listing) {
-            if (out.length >= cap) break;
-            const full = path.join(current, entry.name);
-            // isDirectory() follows symlinks; the depth cap keeps a symlink cycle bounded.
-            if (entry.isDirectory()) {
-                if (entry.name !== 'node_modules') visit(full, depth + 1);
-            } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
-                const src = readFile(full);
-                if (src !== null) out.push(src);
-            }
-        }
-    };
-    for (const dir of dirs) visit(dir, 0);
-    return out;
-}
-
-/** Scans the server sources for `@rest` controllers and whether anything dispatches them. */
-function gatherRestFacts(root: string, toilconfig: Record<string, unknown> | null): RestFacts {
-    let hasControllers = false;
-    let dispatched = false;
-    for (const src of serverSources(root, toilconfig)) {
-        if (/@rest\b/.test(src)) hasControllers = true;
-        if (/\bRest\s*\.\s*dispatch\s*\(/.test(src) || /\bRestHandler\b/.test(src))
-            dispatched = true;
-        if (hasControllers && dispatched) break;
-    }
-    return { hasControllers, dispatched };
-}
-
-/** Whether `.env.secrets` assigns `key` a non-empty value (a bare `KEY=` counts as unset). */
-function secretDefined(root: string, key: string): boolean {
-    const raw = readFile(path.join(root, '.env.secrets'));
-    if (raw === null) return false;
-    return new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=\\s*\\S`, 'm').test(raw);
-}
-
-/**
- * Whether the server uses the auth primitive (so a missing session secret matters) and whether
- * `AUTH_SESSION_SECRET` is set locally. `getSecure` reads ONLY the `.env.secrets` bucket, so that
- * is the source we check; on a deploy target the secret lives on the dashboard instead.
- */
-function gatherAuthFacts(root: string, toilconfig: Record<string, unknown> | null): AuthFacts {
-    let usesAuth = false;
-    for (const src of serverSources(root, toilconfig)) {
-        if (/\bAuthService\b/.test(src) || /@user\b/.test(src) || /@auth\b/.test(src)) {
-            usesAuth = true;
-            break;
-        }
-    }
-    return { usesAuth, sessionSecretSet: secretDefined(root, 'AUTH_SESSION_SECRET') };
-}
-
-/** The toilscript language-service plugin id wired into a server tsconfig. */
-const TS_PLUGIN_NAME = 'toilscript/std/ts-plugin.cjs';
-
-/**
- * The server's tsconfig.json (the one beside a toilconfig entry, conventionally
- * `server/tsconfig.json`), or null if none exists. That is the project the editor uses for server
- * files, so it is where the toilscript LS plugin must live.
- */
-function serverTsconfigPath(root: string, toilconfig: Record<string, unknown> | null): string | null {
-    const dirs = new Set<string>();
-    const entries = Array.isArray(toilconfig?.entries)
-        ? (toilconfig.entries as unknown[]).filter((e): e is string => typeof e === 'string')
-        : [];
-    for (const e of entries) dirs.add(path.dirname(path.resolve(root, e)));
-    if (dirs.size === 0) dirs.add(path.join(root, 'server'));
-    for (const dir of dirs) {
-        const p = path.join(dir, 'tsconfig.json');
-        if (fs.existsSync(p)) return p;
-    }
-    return null;
-}
-
-/**
- * Whether a `migrations/` folder exists under any server dir (the dir of a toilconfig entry,
- * conventionally `server/`). ToilDB `@migrate` functions live in `*.migration.ts` files there, and
- * the build auto-discovers them; a missing folder is a warn, not a fail (older projects predate it).
- */
-function serverMigrationsExist(root: string, toilconfig: Record<string, unknown> | null): boolean {
-    const dirs = new Set<string>();
-    const entries = Array.isArray(toilconfig?.entries)
-        ? (toilconfig.entries as unknown[]).filter((e): e is string => typeof e === 'string')
-        : [];
-    for (const e of entries) dirs.add(path.dirname(path.resolve(root, e)));
-    if (dirs.size === 0) dirs.add(path.join(root, 'server'));
-    for (const dir of dirs) {
-        if (fs.existsSync(path.join(dir, 'migrations'))) return true;
-    }
-    return false;
-}
-
-/** Whether a parsed tsconfig's `compilerOptions.plugins` references the toilscript LS plugin. */
-function tsconfigHasToilPlugin(tsconfig: Record<string, unknown> | null): boolean {
-    const plugins = asRecord(tsconfig?.compilerOptions)?.plugins;
-    if (!Array.isArray(plugins)) return false;
-    return plugins.some((p) => {
-        const name = asRecord(p)?.name;
-        return typeof name === 'string' && name.includes('ts-plugin');
-    });
-}
-
-interface RpcFixResult {
-    /** Files written. */
-    readonly changed: string[];
-    /** Files that need a manual edit (e.g. tsconfig with comments). */
-    readonly skipped: string[];
-}
-
-/**
- * Applies the typed-RPC wiring in place: appends `--rpcModule` to the toilscript build scripts,
- * adds `shared` (+ the `shared/*` alias) to tsconfig, ignores the generated module, and lifts the
- * toilscript floor. Idempotent; only writes files it actually changes.
- */
-function applyRpcFix(root: string): RpcFixResult {
-    const changed: string[] = [];
-    const skipped: string[] = [];
-
-    const pkgPath = path.join(root, 'package.json');
-    const pkgRaw = readFile(pkgPath);
-    const pkg = pkgRaw !== null ? readJsonObject(pkgPath) : null;
-    if (pkg !== null) {
-        let touched = false;
-        const scripts = asRecord(pkg.scripts) ?? {};
-        for (const key of ['build', 'build:server']) {
-            const value = scripts[key];
-            if (
-                typeof value === 'string' &&
-                value.includes('toilscript') &&
-                !value.includes('--rpcModule')
-            ) {
-                scripts[key] = `${value} ${RPC_MODULE_FLAG}`;
-                pkg.scripts = scripts;
-                touched = true;
-            }
-        }
-        let toilscriptDeclared = false;
-        for (const field of ['devDependencies', 'dependencies']) {
-            const bag = asRecord(pkg[field]);
-            const current = bag?.toilscript;
-            if (bag && typeof current === 'string') {
-                toilscriptDeclared = true;
-                // Only lift a real semver range that floors below the minimum; leave file:/latest/* pins alone.
-                if (looksLikeSemverRange(current) && !satisfiesMin(current, RPC_TOILSCRIPT_MIN)) {
-                    bag.toilscript = `^${RPC_TOILSCRIPT_MIN}`;
-                    touched = true;
-                }
-            }
-        }
-        if (!toilscriptDeclared) {
-            // A server project needs toilscript; add it so the wiring actually resolves.
-            const dd = asRecord(pkg.devDependencies) ?? {};
-            dd.toilscript = `^${RPC_TOILSCRIPT_MIN}`;
-            pkg.devDependencies = dd;
-            touched = true;
-        }
-        if (touched) {
-            writeFile(pkgPath, JSON.stringify(pkg, null, 4) + '\n');
-            changed.push('package.json');
-        }
-    } else if (pkgRaw !== null) {
-        skipped.push('package.json (unparseable)');
-    }
-
-    const tsPath = path.join(root, 'tsconfig.json');
-    const tsRaw = readFile(tsPath);
-    const tsconfig = tsRaw !== null ? readJsonObject(tsPath) : null;
-    if (tsconfig !== null) {
-        let touched = false;
-        // Only touch `include` if it already exists; an absent `include` compiles all files,
-        // and synthesizing one would narrow what TypeScript sees.
-        if (Array.isArray(tsconfig.include)) {
-            const include = [...(tsconfig.include as unknown[])];
-            let changedInclude = false;
-            // `shared` (the @data/@remote RPC alias target) right after `client`.
-            if (!include.includes('shared')) {
-                const at = include.indexOf('client');
-                include.splice(at >= 0 ? at + 1 : include.length, 0, 'shared');
-                changedInclude = true;
-            }
-            // `emails` (the React email-template pipeline) + `toil.config.ts`, so the
-            // typescript-eslint project service / editor cover them — otherwise
-            // `emails/*.tsx` (and a typed `toil.config.ts`) raise "not found by the
-            // project service". Harmless when absent (a non-matching glob).
-            for (const entry of ['emails', 'toil.config.ts']) {
-                if (!include.includes(entry)) {
-                    include.push(entry);
-                    changedInclude = true;
-                }
-            }
-            if (changedInclude) {
-                tsconfig.include = include;
-                touched = true;
-            }
-        }
-        const co = asRecord(tsconfig.compilerOptions) ?? {};
-        const paths = asRecord(co.paths) ?? {};
-        if (!('shared/*' in paths)) {
-            paths['shared/*'] = ['./shared/*'];
-            co.paths = paths;
-            tsconfig.compilerOptions = co;
-            touched = true;
-        }
-        if (touched) {
-            writeFile(tsPath, JSON.stringify(tsconfig, null, 4) + '\n');
-            changed.push('tsconfig.json');
-        }
-    } else if (tsRaw !== null) {
-        skipped.push('tsconfig.json (JSON with comments, add "shared" + paths by hand)');
-    }
-
-    const giPath = path.join(root, '.gitignore');
-    const giRaw = readFile(giPath);
-    if (giRaw === null) {
-        writeFile(giPath, `${RPC_GITIGNORE_LINE}\n`);
-        changed.push('.gitignore');
-    } else if (!RPC_GITIGNORE_RE.test(giRaw)) {
-        const sep = giRaw.length === 0 || giRaw.endsWith('\n') ? '' : '\n';
-        writeFile(giPath, `${giRaw}${sep}${RPC_GITIGNORE_LINE}\n`);
-        changed.push('.gitignore');
-    }
-
-    // Migrate the editor-only server-globals d.ts to the current shapes (the
-    // exact content `toiljs build`/`dev` regenerate), in each server source dir.
-    // This is what fixes a stale, scaffolded `toil-server-env.d.ts` whose
-    // standalone class decls made a second, incompatible `Cookie`.
-    const serverToilconfig = readJsonObject(path.join(root, 'toilconfig.json'));
-    if (serverToilconfig !== null) {
-        const entries = Array.isArray(serverToilconfig.entries)
-            ? (serverToilconfig.entries as unknown[]).filter(
-                  (e): e is string => typeof e === 'string',
-              )
-            : [];
-        const dirs = new Set<string>();
-        for (const e of entries) dirs.add(path.dirname(path.resolve(root, e)));
-        if (dirs.size === 0) dirs.add(path.join(root, 'server'));
-        for (const dir of dirs) {
-            const envPath = path.join(dir, 'toil-server-env.d.ts');
-            if (readFile(envPath) !== TOIL_SERVER_ENV_DTS) {
-                try {
-                    fs.mkdirSync(dir, { recursive: true });
-                    writeFile(envPath, TOIL_SERVER_ENV_DTS);
-                    changed.push(path.relative(root, envPath));
-                } catch {
-                    // editor-only; ignore write failures
-                }
-            }
-        }
-    }
-
-    return { changed, skipped };
-}
-
-const PRETTIER_PLUGIN = 'toiljs/prettier-plugin';
-const PRETTIER_MENTION = /toiljs\/prettier(-plugin)?/;
-const PRETTIER_CONFIG_FILES = [
-    '.prettierrc',
-    '.prettierrc.json',
-    '.prettierrc.json5',
-    '.prettierrc.yaml',
-    '.prettierrc.yml',
-    '.prettierrc.js',
-    '.prettierrc.cjs',
-    '.prettierrc.mjs',
-    '.prettierrc.ts',
-    'prettier.config.js',
-    'prettier.config.cjs',
-    'prettier.config.mjs',
-    'prettier.config.ts',
-];
-
-/** Whether any prettier config (file or package.json field) pulls in the toilscript plugin. */
-function prettierPluginPresent(root: string, pkg: Record<string, unknown> | null): boolean {
-    if (pkg && pkg.prettier !== undefined && PRETTIER_MENTION.test(JSON.stringify(pkg.prettier))) {
-        return true;
-    }
-    for (const name of PRETTIER_CONFIG_FILES) {
-        const raw = readFile(path.join(root, name));
-        if (raw !== null && PRETTIER_MENTION.test(raw)) return true;
-    }
-    return false;
-}
-
-/**
- * Adds `toiljs/prettier-plugin` to the project's prettier config so prettier can format the
- * toilscript server. Handles the common cases (package.json `prettier`, a JSON `.prettierrc`,
- * or no config at all); warns for shapes it can't safely edit (a JS config, or a string preset).
- */
-function applyPrettierFix(root: string, pkg: Record<string, unknown> | null): RpcFixResult {
-    const changed: string[] = [];
-    const skipped: string[] = [];
-    if (prettierPluginPresent(root, pkg)) return { changed, skipped };
-
-    // package.json "prettier" object.
-    const pkgPath = path.join(root, 'package.json');
-    const pkgConfig = pkg ? asRecord(pkg.prettier) : null;
-    if (pkgConfig !== null) {
-        const full = readJsonObject(pkgPath);
-        const target = full ? asRecord(full.prettier) : null;
-        if (full && target) {
-            target.plugins = [
-                ...(Array.isArray(target.plugins) ? target.plugins : []),
-                PRETTIER_PLUGIN,
-            ];
-            writeFile(pkgPath, JSON.stringify(full, null, 4) + '\n');
-            changed.push('package.json');
-            return { changed, skipped };
-        }
-    }
-
-    // A JSON .prettierrc / .prettierrc.json object.
-    for (const name of ['.prettierrc', '.prettierrc.json']) {
-        const filePath = path.join(root, name);
-        const raw = readFile(filePath);
-        if (raw === null) continue;
-        const obj = readJsonObject(filePath);
-        if (obj === null) {
-            skipped.push(`${name} (add "${PRETTIER_PLUGIN}" to plugins by hand)`);
-            return { changed, skipped };
-        }
-        obj.plugins = [...(Array.isArray(obj.plugins) ? obj.plugins : []), PRETTIER_PLUGIN];
-        writeFile(filePath, JSON.stringify(obj, null, 4) + '\n');
-        changed.push(name);
-        return { changed, skipped };
-    }
-
-    // A JS/TS config we can't safely edit.
-    const jsConfig = PRETTIER_CONFIG_FILES.find((name) => readFile(path.join(root, name)) !== null);
-    if (jsConfig) {
-        skipped.push(`${jsConfig} (add "${PRETTIER_PLUGIN}" to its plugins by hand)`);
-        return { changed, skipped };
-    }
-
-    // No config at all: create one.
-    writeFile(
-        path.join(root, '.prettierrc.json'),
-        JSON.stringify({ plugins: [PRETTIER_PLUGIN] }, null, 4) + '\n',
-    );
-    changed.push('.prettierrc.json');
-    return { changed, skipped };
-}
-
-/**
- * Wires the editor side of the toilscript server: adds the LS plugin to the server tsconfig (so the
- * editor stops false-flagging `@database` static collections / `@data` members), and points VS Code
- * at the workspace TypeScript (so it actually loads that plugin). Idempotent; only writes real
- * changes, and skips (with a note) configs it can't safely edit (a tsconfig with comments).
- */
-function applyServerEditorFix(root: string, toilconfig: Record<string, unknown> | null): RpcFixResult {
-    const changed: string[] = [];
-    const skipped: string[] = [];
-
-    // 1. The LS plugin in the server tsconfig.
-    const tsPath = serverTsconfigPath(root, toilconfig);
-    if (tsPath === null) {
-        skipped.push('server/tsconfig.json (not found; add the toilscript ts-plugin by hand)');
-    } else {
-        const rel = path.relative(root, tsPath);
-        const raw = readFile(tsPath);
-        const parsed = raw !== null ? readJsonObject(tsPath) : null;
-        if (parsed === null) {
-            skipped.push(`${rel} (JSON with comments; add the "${TS_PLUGIN_NAME}" plugin by hand)`);
-        } else if (!tsconfigHasToilPlugin(parsed)) {
-            const co = asRecord(parsed.compilerOptions) ?? {};
-            const existingPlugins: unknown[] = Array.isArray(co.plugins)
-                ? (co.plugins as unknown[])
-                : [];
-            co.plugins = [...existingPlugins, { name: TS_PLUGIN_NAME }];
-            parsed.compilerOptions = co;
-            writeFile(tsPath, JSON.stringify(parsed, null, 4) + '\n');
-            changed.push(rel);
-        }
-    }
-
-    // 2. Make VS Code use the workspace TypeScript, so it loads the plugin above.
-    const vsPath = path.join(root, '.vscode', 'settings.json');
-    const vsRaw = readFile(vsPath);
-    const vs = vsRaw !== null ? readJsonObject(vsPath) : {};
-    if (vs === null) {
-        skipped.push('.vscode/settings.json (unparseable; set typescript.tsdk by hand)');
-    } else {
-        let touched = false;
-        if (vs['typescript.tsdk'] !== 'node_modules/typescript/lib') {
-            vs['typescript.tsdk'] = 'node_modules/typescript/lib';
-            touched = true;
-        }
-        if (vs['typescript.enablePromptUseWorkspaceTsdk'] !== true) {
-            vs['typescript.enablePromptUseWorkspaceTsdk'] = true;
-            touched = true;
-        }
-        if (touched) {
-            fs.mkdirSync(path.dirname(vsPath), { recursive: true });
-            writeFile(vsPath, JSON.stringify(vs, null, 4) + '\n');
-            changed.push('.vscode/settings.json');
-        }
-    }
-
-    return { changed, skipped };
-}
-
-/** Reads the framework's own package.json (engines + peerDependencies) for the requirements. */
-function frameworkMeta(): { node: string; peers: Record<string, string> } {
-    const pkgPath = path.resolve(
-        path.dirname(fileURLToPath(import.meta.url)),
-        '..',
-        '..',
-        'package.json',
-    );
-    const pkg = readJsonObject(pkgPath);
-    const engines = pkg ? stringRecord(pkg.engines) : {};
-    const peers = pkg ? stringRecord(pkg.peerDependencies) : {};
-    return { node: engines.node ?? '>=24.0.0', peers };
-}
-
-const LOCKFILES = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lockb'];
-
-/** Reads the app entry source (the file that mounts the app), or null if none is found. */
-function readEntry(clientAbsDir: string): string | null {
-    for (const name of ['toil.tsx', 'toil.jsx', 'main.tsx', 'main.jsx']) {
-        const source = readFile(path.join(clientAbsDir, name));
-        if (source !== null && /toiljs\/routes|\bmount\s*\(/.test(source)) return source;
-    }
-    return null;
-}
-
-/** Collects client `.tsx`/`.jsx` sources (capped) for the relative-asset scan. */
-function collectSources(root: string, dir: string, cap: number): SourceFile[] {
-    const out: SourceFile[] = [];
-    const visit = (current: string): void => {
-        if (out.length >= cap) return;
-        let entries: fs.Dirent[];
-        try {
-            entries = fs.readdirSync(current, { withFileTypes: true });
-        } catch {
-            return;
-        }
-        for (const entry of entries) {
-            if (out.length >= cap) break;
-            const full = path.join(current, entry.name);
-            if (entry.isDirectory()) {
-                if (entry.name !== 'node_modules') visit(full);
-            } else if (/\.(tsx|jsx)$/.test(entry.name)) {
-                const source = readFile(full);
-                if (source !== null) out.push({ path: path.relative(root, full), source });
-            }
-        }
-    };
-    visit(dir);
-    return out;
-}
-
-/** Picks a check glyph in the brand palette. */
-function glyph(status: CheckStatus): string {
-    if (status === 'pass') return success('✓');
-    if (status === 'warn') return warn('⚠');
-    return danger('✗');
-}
-
-function renderHuman(groups: readonly CheckGroup[]): void {
-    const summary = summarize(groups);
-    const out: string[] = [];
-    for (const group of groups) {
-        out.push('  ' + bold(group.title));
-        for (const check of group.checks) {
-            let line = `    ${glyph(check.status)} ${check.label}`;
-            if (check.detail) line += dim(`  ${check.detail}`);
-            out.push(line);
-            if (check.fix && check.status !== 'pass')
-                out.push('       ' + dim(`fix: ${check.fix}`));
-        }
-        out.push('');
-    }
-    const parts = [success(`${String(summary.pass)} passed`)];
-    if (summary.warn > 0) {
-        parts.push(warn(`${String(summary.warn)} warning${summary.warn === 1 ? '' : 's'}`));
-    }
-    if (summary.fail > 0) parts.push(danger(`${String(summary.fail)} failed`));
-    out.push('  ' + parts.join(dim(', ')));
-    out.push('');
-    process.stdout.write(out.join('\n') + '\n');
-}
-
-export async function runDoctor(opts: DoctorOptions): Promise<void> {
-    const root = path.resolve(opts.root ?? opts.cwd);
-    const meta = frameworkMeta();
-
-    const projectPkg = readJsonObject(path.join(root, 'package.json'));
-    const deps: Record<string, string> = {
-        ...(projectPkg ? stringRecord(projectPkg.dependencies) : {}),
-        ...(projectPkg ? stringRecord(projectPkg.devDependencies) : {}),
-    };
-
-    // Config (the only async fact). On failure, downstream paths fall back to conventional defaults.
-    let cfg: ResolvedToilConfig | null = null;
-    let configError: string | undefined;
-    try {
-        cfg = await loadConfig({ root });
-    } catch (err) {
-        configError = err instanceof Error ? err.message : String(err);
-    }
-
-    const clientAbsDir = cfg ? cfg.clientAbsDir : path.join(root, 'client');
-    const routesAbsDir = cfg ? cfg.routesAbsDir : path.join(clientAbsDir, 'routes');
-    const publicDir = cfg ? cfg.publicDir : path.join(clientAbsDir, 'public');
-
-    const entrySource = readEntry(clientAbsDir);
-    const indexHtml = readFile(path.join(publicDir, 'index.html'));
-    const routes = scanRoutes(routesAbsDir);
-    const mainPatterns = routes.filter((r) => r.slot === undefined).map((r) => r.pattern);
-    const assetIssues = findRelativeAssets(collectSources(root, clientAbsDir, 200));
-
-    // Styling facts from the entry's style imports.
-    let preprocessorImported: Preprocessor | null = null;
-    let tailwindImported = false;
-    if (entrySource) {
-        const styleImport = /import\s+['"]\.\/styles\/main\.([a-z]+)['"]/.exec(entrySource);
-        if (styleImport) preprocessorImported = preprocessorForExt(styleImport[1]);
-        tailwindImported = entrySource.includes(TAILWIND_ENTRY);
-    }
-    const ppPkg = preprocessorImported ? PREPROCESSOR_PKG[preprocessorImported] : null;
-    const preprocessorInstalled = ppPkg === null || ppPkg in deps;
-
-    // Server / WASM facts.
-    const toilconfig = readJsonObject(path.join(root, 'toilconfig.json'));
-    const serverPresent = toilconfig !== null;
-    let missingEntries: string[] = [];
-    let toilscriptInstalled = false;
-    let wasmExists = false;
-    if (toilconfig) {
-        const entries = Array.isArray(toilconfig.entries)
-            ? toilconfig.entries.filter((e): e is string => typeof e === 'string')
-            : [];
-        missingEntries = entries.filter((e) => !fs.existsSync(path.join(root, e)));
-        toilscriptInstalled = isPackageInstalled(root, 'toilscript');
-        const targets =
-            typeof toilconfig.targets === 'object' && toilconfig.targets !== null
-                ? (toilconfig.targets as Record<string, unknown>)
-                : {};
-        const outFiles: string[] = [];
-        for (const target of Object.values(targets)) {
-            if (typeof target === 'object' && target !== null) {
-                const outFile = (target as Record<string, unknown>).outFile;
-                if (typeof outFile === 'string') outFiles.push(outFile);
-            }
-        }
-        wasmExists = outFiles.some((f) => fs.existsSync(path.join(root, f)));
-        if (!wasmExists && outFiles.length === 0) {
-            try {
-                wasmExists = fs
-                    .readdirSync(path.join(root, 'build', 'server'))
-                    .some((f) => f.endsWith('.wasm'));
-            } catch {
-                wasmExists = false;
-            }
-        }
-    }
-
-    const peerName = (n: string): Check => checkPeer(n, deps[n] ?? null, meta.peers[n] ?? '*');
-    // typescript gets its own check: its peer range is the only one whose upper bound matters (7.x
-    // clears the `>=6.0.0` floor but ships no compiler API), and it is fixable in place.
-    const peerChecks = Object.keys(meta.peers)
-        .filter((n) => n !== 'typescript')
-        .map(peerName);
-    const typeScriptFix = opts.fix ? applyTypeScriptFix(root) : null;
-    // Re-read the declared range: `--fix` may have just rewritten it.
-    const declaredTypeScript = (() => {
-        const pkg = readJsonObject(path.join(root, 'package.json'));
-        if (pkg === null) return deps.typescript ?? null;
-        for (const field of ['devDependencies', 'dependencies'] as const) {
-            const range = asRecord(pkg[field])?.typescript;
-            if (typeof range === 'string') return range;
-        }
-        return null;
-    })();
-    const typeScriptCheck = checkTypeScript(
-        installedVersion(root, 'typescript'),
-        declaredTypeScript,
-    );
-
-    // Server tooling (RPC wiring + the prettier plugin + the editor LS plugin): optionally fix in
-    // place, then re-read.
-    const rpcFix = serverPresent && opts.fix ? applyRpcFix(root) : null;
-    const prettierFix = serverPresent && opts.fix ? applyPrettierFix(root, projectPkg) : null;
-    const editorFix = serverPresent && opts.fix ? applyServerEditorFix(root, toilconfig) : null;
-    const rpcFacts = gatherRpcFacts(root);
-    const restFacts = gatherRestFacts(root, toilconfig);
-    const authFacts = gatherAuthFacts(root, toilconfig);
-    const prettierPresent = prettierPluginPresent(
-        root,
-        readJsonObject(path.join(root, 'package.json')),
-    );
-    // Only assess the LS plugin when a server tsconfig exists and parses; an absent or
-    // commented one is left to the user rather than warned on.
-    const serverTsPath = serverPresent ? serverTsconfigPath(root, toilconfig) : null;
-    const serverTsParsed = serverTsPath ? readJsonObject(serverTsPath) : null;
-    const serverTsPluginPresent =
-        serverTsPath === null || serverTsParsed === null ? true : tsconfigHasToilPlugin(serverTsParsed);
-    // The typescript pin is fixable without a server; the rest only apply to one.
-    const applied = [typeScriptFix, rpcFix, prettierFix, editorFix].filter(
-        (fix): fix is RpcFixResult => fix !== null,
-    );
-    const serverFix =
-        applied.length > 0
-            ? {
-                  changed: applied.flatMap((fix) => fix.changed),
-                  skipped: applied.flatMap((fix) => fix.skipped),
-              }
-            : null;
-
-    const groups: CheckGroup[] = [
-        {
-            title: 'Environment',
-            checks: [
-                checkNode(process.versions.node, meta.node),
-                checkToiljsInstalled('toiljs' in deps ? version() : null),
-                ...peerChecks,
-                typeScriptCheck,
-                checkPackageManager(LOCKFILES.filter((f) => fs.existsSync(path.join(root, f)))),
-            ],
-        },
-        {
-            title: 'Project + routing',
-            checks: [
-                checkDir(
-                    'client-dir',
-                    'client/ directory',
-                    fs.existsSync(clientAbsDir),
-                    'Create a client/ directory for your app.',
-                ),
-                checkDir(
-                    'routes-dir',
-                    'routes/ directory',
-                    fs.existsSync(routesAbsDir),
-                    'Create client/routes/ and add an index.tsx.',
-                ),
-                checkRootElement(indexHtml),
-                checkMountSlots(entrySource),
-                checkRoutesPresent(routes.length),
-                checkDuplicatePatterns(mainPatterns),
-                checkRelativeAssets(assetIssues),
-                checkDevScripts(projectPkg ? stringRecord(projectPkg.scripts) : {}),
-            ],
-        },
-        {
-            title: 'Config + assets',
-            checks: [
-                checkConfigLoads(cfg !== null, configError),
-                checkBasePath(cfg ? cfg.base : '/'),
-                checkSeoUrl(cfg?.seo != null, cfg?.seo?.url != null),
-                checkStyling({
-                    preprocessorImported,
-                    preprocessorInstalled,
-                    tailwindImported,
-                    tailwindInstalled: detectTailwind(deps),
-                }),
-            ],
-        },
-        {
-            title: 'Server / WASM',
-            checks: serverPresent
-                ? [
-                      checkToilconfig(true),
-                      checkServerEntry(missingEntries),
-                      checkToilscriptInstalled(toilscriptInstalled),
-                      checkWasmBuilt(wasmExists),
-                      checkRpcWiring(rpcFacts),
-                      checkRestDispatch(restFacts),
-                      checkPrettierPlugin(prettierPresent),
-                      checkServerTsPlugin(serverTsPluginPresent),
-                      checkMigrationsDir(serverMigrationsExist(root, toilconfig)),
-                  ]
-                : [checkToilconfig(false)],
-        },
-    ];
-
-    // Security checks only apply to a server (no server, no sessions to forge).
-    if (serverPresent) {
-        groups.push({ title: 'Security', checks: [checkAuthSecrets(authFacts)] });
-    }
-
-    const summary = summarize(groups);
-    if (opts.json) {
-        process.stdout.write(JSON.stringify({ groups, summary, fixed: serverFix }, null, 2) + '\n');
-    } else {
-        process.stdout.write('\n' + accent('  Doctor') + dim(`  ${root}`) + '\n\n');
-        renderHuman(groups);
-        if (serverFix) renderFix(serverFix);
-    }
-    if (hasFailures(summary)) process.exitCode = 1;
-}
-
-/** Prints the result of `--fix`, and whether a reinstall is needed (a changed dependency range). */
-function renderFix(result: RpcFixResult): void {
-    const out: string[] = [];
-    if (result.changed.length > 0) {
-        out.push('  ' + success('fixed') + dim(`  ${result.changed.join(', ')}`));
-        if (result.changed.some((entry) => entry.startsWith('package.json'))) {
-            out.push('  ' + dim('run your installer (npm/pnpm/yarn) to apply the version changes.'));
-        }
-    } else {
-        out.push('  ' + dim('nothing to fix.'));
-    }
-    for (const item of result.skipped) out.push('  ' + warn('skipped') + dim(`  ${item}`));
-    process.stdout.write(out.join('\n') + '\n\n');
-}