toiljs 0.0.16 → 0.0.20

package/src/cli/diagnostics.ts

@@ -400,6 +400,87 @@ export function checkWasmBuilt(exists: boolean): Check {
           };
 }
 
+// --- Typed RPC (@data / @remote / @service) -------------------------------------------------------
+
+/** Minimum toilscript: @rest/@route HTTP layer + RPC codegen + hardened decoders + @data editor decls. */
+export const RPC_TOILSCRIPT_MIN = '0.1.13';
+
+/** Whether each piece of the typed-RPC wiring is in place (computed in `doctor.ts`). */
+export interface RpcFacts {
+    /** `build:server` runs toilscript with `--rpcModule`. */
+    readonly buildServerWired: boolean;
+    /** tsconfig includes `shared` and has the `shared/*` path alias. */
+    readonly tsconfigWired: boolean;
+    /** `.gitignore` ignores the generated `shared/server.ts`. */
+    readonly gitignoreWired: boolean;
+    /** The declared toilscript range is at least {@link RPC_TOILSCRIPT_MIN}. */
+    readonly toilscriptOk: boolean;
+}
+
+/**
+ * One check for the typed-RPC setup (`@data`/`@remote` -> generated `Server`). Warns (does not fail)
+ * when an existing project predates the feature, and points at the one-command upgrade.
+ */
+export function checkRpcWiring(f: RpcFacts): Check {
+    const missing: string[] = [];
+    if (!f.toilscriptOk) missing.push(`toilscript >=${RPC_TOILSCRIPT_MIN}`);
+    if (!f.buildServerWired) missing.push('build:server --rpcModule');
+    if (!f.tsconfigWired) missing.push('tsconfig shared/ + alias');
+    if (!f.gitignoreWired) missing.push('.gitignore shared/server.ts');
+    if (missing.length === 0) {
+        return { id: 'rpc-wiring', label: 'typed RPC wiring', status: 'pass' };
+    }
+    return {
+        id: 'rpc-wiring',
+        label: 'typed RPC wiring',
+        status: 'warn',
+        detail: `missing: ${missing.join(', ')}`,
+        fix: 'Run `toiljs doctor --fix` to wire @data/@remote RPC (build:server, tsconfig, .gitignore, toilscript).',
+    };
+}
+
+/**
+ * Whether the project's prettier setup pulls in the toilscript plugin (`toiljs/prettier-plugin`,
+ * or the `toiljs/prettier` shareable that bundles it). Without it, prettier throws on the server's
+ * native function decorators (`@main`, `@remote function ...`).
+ */
+export function checkPrettierPlugin(present: boolean): Check {
+    return present
+        ? { id: 'prettier-plugin', label: 'prettier toilscript plugin', status: 'pass' }
+        : {
+              id: 'prettier-plugin',
+              label: 'prettier toilscript plugin',
+              status: 'warn',
+              detail: 'prettier will fail on @main / @remote-on-function in server code',
+              fix: 'Run `toiljs doctor --fix` to add toiljs/prettier-plugin to your prettier config.',
+          };
+}
+
+export interface RestFacts {
+    /** The server declares at least one `@rest` controller. */
+    readonly hasControllers: boolean;
+    /** Some server file dispatches them: a `Rest.dispatch(` call, or a `RestHandler`. */
+    readonly dispatched: boolean;
+}
+
+/**
+ * Guards the easy-to-miss wiring step for the HTTP layer: a `@rest` controller self-registers,
+ * but its routes are only served if a handler calls `Rest.dispatch(req)` (or the project uses
+ * `RestHandler`). Without that, the routes silently 404 - a confusing footgun, so we warn.
+ */
+export function checkRestDispatch(f: RestFacts): Check {
+    if (!f.hasControllers || f.dispatched) {
+        return { id: 'rest-dispatch', label: 'REST dispatch wiring', status: 'pass' };
+    }
+    return {
+        id: 'rest-dispatch',
+        label: 'REST dispatch wiring',
+        status: 'warn',
+        detail: '@rest controllers found, but nothing calls Rest.dispatch(req) - their routes will not be served',
+        fix: 'In your handler add `const hit = Rest.dispatch(req); if (hit != null) return hit;`, or set `Server.handler = () => new RestHandler()`.',
+    };
+}
+
 // --- Summary --------------------------------------------------------------------------------------
 
 export function summarize(groups: readonly CheckGroup[]): DoctorSummary {

package/src/cli/doctor.ts

@@ -23,9 +23,12 @@ import {
     checkNode,
     checkPackageManager,
     checkPeer,
+    checkPrettierPlugin,
     checkRelativeAssets,
+    checkRestDispatch,
     checkRootElement,
     checkRoutesPresent,
+    checkRpcWiring,
     checkSeoUrl,
     checkServerEntry,
     type CheckStatus,
@@ -36,6 +39,10 @@ import {
     checkWasmBuilt,
     findRelativeAssets,
     hasFailures,
+    type RestFacts,
+    type RpcFacts,
+    RPC_TOILSCRIPT_MIN,
+    satisfiesMin,
     type SourceFile,
     summarize,
 } from './diagnostics.js';
@@ -53,6 +60,8 @@ export interface DoctorOptions {
     readonly cwd: string;
     /** Emit machine-readable JSON instead of the human report. */
     readonly json?: boolean;
+    /** Auto-fix what can be fixed in place (currently the typed-RPC wiring). */
+    readonly fix?: boolean;
 }
 
 /** Parses a JSON file into a plain object, or null on any error / non-object. */
@@ -83,6 +92,336 @@ function readFile(file: string): string | 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;
+    }
+}
+
+/** 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 };
+}
+
+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[])];
+            if (!include.includes('shared')) {
+                const at = include.indexOf('client');
+                include.splice(at >= 0 ? at + 1 : include.length, 0, 'shared');
+                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');
+    }
+
+    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 };
+}
+
 /** Reads the framework's own package.json (engines + peerDependencies) for the requirements. */
 function frameworkMeta(): { node: string; peers: Record<string, string> } {
     const pkgPath = path.resolve(
@@ -216,12 +555,7 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
             ? toilconfig.entries.filter((e): e is string => typeof e === 'string')
             : [];
         missingEntries = entries.filter((e) => !fs.existsSync(path.join(root, e)));
-        try {
-            createRequire(path.join(root, 'package.json')).resolve('toilscript');
-            toilscriptInstalled = true;
-        } catch {
-            toilscriptInstalled = false;
-        }
+        toilscriptInstalled = isPackageInstalled(root, 'toilscript');
         const targets =
             typeof toilconfig.targets === 'object' && toilconfig.targets !== null
                 ? (toilconfig.targets as Record<string, unknown>)
@@ -248,6 +582,23 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
     const peerName = (n: string): Check => checkPeer(n, deps[n] ?? null, meta.peers[n] ?? '*');
     const peerChecks = Object.keys(meta.peers).map(peerName);
 
+    // Server tooling (RPC wiring + the prettier 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 rpcFacts = gatherRpcFacts(root);
+    const restFacts = gatherRestFacts(root, toilconfig);
+    const prettierPresent = prettierPluginPresent(
+        root,
+        readJsonObject(path.join(root, 'package.json')),
+    );
+    const serverFix =
+        rpcFix || prettierFix
+            ? {
+                  changed: [...(rpcFix?.changed ?? []), ...(prettierFix?.changed ?? [])],
+                  skipped: [...(rpcFix?.skipped ?? []), ...(prettierFix?.skipped ?? [])],
+              }
+            : null;
+
     const groups: CheckGroup[] = [
         {
             title: 'Environment',
@@ -302,6 +653,9 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
                       checkServerEntry(missingEntries),
                       checkToilscriptInstalled(toilscriptInstalled),
                       checkWasmBuilt(wasmExists),
+                      checkRpcWiring(rpcFacts),
+                      checkRestDispatch(restFacts),
+                      checkPrettierPlugin(prettierPresent),
                   ]
                 : [checkToilconfig(false)],
         },
@@ -309,10 +663,33 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
 
     const summary = summarize(groups);
     if (opts.json) {
-        process.stdout.write(JSON.stringify({ groups, summary }, null, 2) + '\n');
+        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) renderRpcFix(serverFix);
+        else if (opts.fix && !serverPresent) {
+            process.stdout.write(
+                '  ' + dim('--fix: no server (toilconfig.json) found, nothing to wire.') + '\n\n',
+            );
+        }
     }
     if (hasFailures(summary)) process.exitCode = 1;
 }
+
+/** Prints the result of `--fix`, and whether a reinstall is needed (toilscript bump). */
+function renderRpcFix(result: RpcFixResult): void {
+    const out: string[] = [];
+    if (result.changed.length > 0) {
+        out.push('  ' + success('fixed RPC wiring') + dim(`  ${result.changed.join(', ')}`));
+        if (result.changed.includes('package.json')) {
+            out.push(
+                '  ' + dim('run your installer (npm/pnpm/yarn) if the toilscript version changed.'),
+            );
+        }
+    } else {
+        out.push('  ' + dim('RPC wiring already in place, nothing to fix.'));
+    }
+    for (const item of result.skipped) out.push('  ' + warn('skipped') + dim(`  ${item}`));
+    process.stdout.write(out.join('\n') + '\n\n');
+}

package/src/cli/index.ts

@@ -16,6 +16,7 @@ import { accent, banner, bold, danger, dim, success, version } from './ui.js';
 interface Flags {
     root?: string;
     port?: number;
+    host?: string;
     name?: string;
     template?: Template;
     preprocessor?: Preprocessor;
@@ -27,6 +28,7 @@ interface Flags {
     pm?: string;
     yes?: boolean;
     json?: boolean;
+    fix?: boolean;
     target?: string;
 }
 
@@ -43,6 +45,9 @@ function parseArgs(argv: string[]): Flags {
                 if (!Number.isNaN(port)) flags.port = port;
                 break;
             }
+            case '--host':
+                flags.host = argv[++i];
+                break;
             case '--template':
             case '-t': {
                 const t = argv[++i];
@@ -95,6 +100,9 @@ function parseArgs(argv: string[]): Flags {
             case '--json':
                 flags.json = true;
                 break;
+            case '--fix':
+                flags.fix = true;
+                break;
             case '--target':
                 flags.target = argv[++i];
                 break;
@@ -130,6 +138,7 @@ function printHelp(): void {
             cmd('-y, --yes', 'create: accept defaults (non-interactive)'),
             cmd('--no-install', "create: don't install dependencies"),
             cmd('--json', 'doctor: machine-readable output'),
+            cmd('--fix', 'doctor: auto-fix what it can (typed-RPC wiring)'),
             cmd('--target <t>', 'update: latest | minor | patch | newest | greatest'),
             cmd('-v, --version', 'print the toiljs version'),
             '',
@@ -193,7 +202,7 @@ async function main(): Promise<void> {
         case 'start': {
             banner();
             process.stdout.write(dim('  self-hosting the built app…') + '\n\n');
-            const server = await start({ root: flags.root, port: flags.port });
+            const server = await start({ root: flags.root, port: flags.port, host: flags.host });
             process.stdout.write(
                 accent('  ➜ ') +
                     bold(`http://localhost:${String(server.port)}`) +
@@ -206,7 +215,7 @@ async function main(): Promise<void> {
         case 'doctor':
             // Skip the banner for --json so stdout stays valid JSON.
             if (!flags.json) banner();
-            await runDoctor({ root: flags.root, cwd: process.cwd(), json: flags.json });
+            await runDoctor({ root: flags.root, cwd: process.cwd(), json: flags.json, fix: flags.fix });
             break;
 
         case 'update':

package/src/client/dev/devtools.tsx

@@ -587,16 +587,56 @@ const DOC_LINKS: { label: string; slug: string }[] = [
     { label: 'Parallel routes and slots', slug: 'slots' },
 ];
 
-function AiTab({ info }: { info: DevInfo | null }): ReactNode {
-    useCurrentUrl(); // rebuild page context on navigation
+/** Max chars of route source to inline into the prompt (keeps the hand-off URL usable). */
+const AI_CODE_MAX = 8000;
+
+function AiTab({ info, routes }: { info: DevInfo | null; routes: RouteDef[] }): ReactNode {
+    const url = useCurrentUrl(); // rebuild page context + refetch source on navigation
     const [question, setQuestion] = useState('');
     const [answer, setAnswer] = useState<string | null>(null);
     const [busy, setBusy] = useState(false);
+    const [source, setSource] = useState<{ file: string; code: string } | null>(null);
     const configured = info?.ai === true;
 
+    // Resolve the current route's source file (pattern -> absolute path from the dev server).
+    const pathname = url.split('?')[0];
+    let file: string | undefined;
+    for (const r of routes) {
+        if (matchRoute(r.pattern, pathname)) {
+            file = info?.routes[r.pattern];
+            break;
+        }
+    }
+
+    useEffect(() => {
+        if (!file) {
+            setSource(null);
+            return;
+        }
+        let cancelled = false;
+        void fetch(`/__toil/source?file=${encodeURIComponent(file)}`)
+            .then((r) => (r.ok ? r.text() : null))
+            .then((code) => {
+                if (!cancelled) setSource(code !== null ? { file, code } : null);
+            })
+            .catch(() => {
+                if (!cancelled) setSource(null);
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, [file]);
+
     const prompt = (): string => {
         const q = question.trim() || 'Explain this page and suggest improvements.';
-        return `${buildAiContext()}\n\nQuestion: ${q}`;
+        const parts = [buildAiContext()];
+        if (source) {
+            const code = source.code.slice(0, AI_CODE_MAX);
+            const cut = source.code.length > AI_CODE_MAX ? '\n... (truncated)' : '';
+            parts.push(`\nPage source (${source.file}):\n\`\`\`tsx\n${code}${cut}\n\`\`\``);
+        }
+        parts.push(`\nQuestion: ${q}`);
+        return parts.join('\n');
     };
     const handOff = (base: string): void => {
         window.open(`${base}${encodeURIComponent(prompt())}`, '_blank', 'noopener');
@@ -668,6 +708,11 @@ function AiTab({ info }: { info: DevInfo | null }): ReactNode {
                     </button>
                 )}
             </div>
+            {source && (
+                <p className="toil-dt-k">
+                    Prompt includes this route&apos;s source ({source.file.split('/').pop()}).
+                </p>
+            )}
             {!configured && (
                 <p className="toil-dt-k">
                     Inline answers are off. Set <span className="toil-dt-tag">devtools.ai</span> in
@@ -963,7 +1008,7 @@ export function DevToolbar({
                 {p.tab === 'head' && <HeadTab />}
                 {p.tab === 'build' && <BuildTab info={info} />}
                 {p.tab === 'errors' && <ErrorsTab />}
-                {p.tab === 'ai' && <AiTab info={info} />}
+                {p.tab === 'ai' && <AiTab info={info} routes={routes} />}
                 {p.tab === 'prefs' && <PrefsTab />}
             </div>
         </div>