toiljs 0.0.113 → 0.0.115

package/src/cli/create.ts

@@ -38,7 +38,7 @@ import { run } from './proc.js';
 import { accent, dim, version } from './ui.js';
 import { isPackageManager, isValidName, resolveProjectDir } from './validate.js';
 
-export type Template = 'app' | 'minimal';
+export type Template = 'app' | 'minimal' | 'agent';
 
 /**
  * The `server/migrations/` README, scaffolded by `create` and ensured by `doctor`/`update`. ToilDB
@@ -157,6 +157,7 @@ function scaffold(
         private: true,
         type: 'module',
         scripts: {
+            start: 'toiljs start',
             dev: 'toiljs dev',
             build: 'toiljs build',
             'build:server': 'toiljs build --server',
@@ -297,11 +298,16 @@ function scaffold(
         'server/migrations/README.md': MIGRATIONS_README,
     };
 
-    // The `app` template's client UI + server are copied from examples/basic at runtime; `minimal`
-    // ships an inline client + a minimal working server here.
+    // The `app` template's client UI + server are copied from examples/basic at runtime; the
+    // `minimal` and `agent` templates ship an inline client + working server here. `agent` adds
+    // one correctly-structured @rest endpoint (a @data model + controller) and a home page that
+    // calls it, the smallest complete client-to-backend loop for an agent to build on.
     if (template === 'minimal') {
         Object.assign(files, minimalClient(name, features));
         Object.assign(files, minimalServer());
+    } else if (template === 'agent') {
+        Object.assign(files, agentClient(name, features));
+        Object.assign(files, agentServer());
     }
 
     // Selected AI-assistant pointer files at the root (committed). The real docs are always seeded
@@ -362,6 +368,22 @@ declare namespace AuthService { const SESSION_COOKIE: string; const USER_COOKIE:
 interface __ToilAuthUser {}
 `;
 
+/** The `server/README.md` shipped by the inline templates: the folder-conventions map. */
+const SERVER_README =
+    '# server/\n\n' +
+    'Your ToilScript backend, compiled to a single WebAssembly module. One folder per concern:\n\n' +
+    '| Folder | What lives here |\n' +
+    '| --- | --- |\n' +
+    '| `main.ts` | The entry point: wires the handler and imports the surface modules. |\n' +
+    '| `core/` | The request handler and shared app logic (state, helpers). |\n' +
+    '| `models/` | `@data` classes, the typed wire model shared by HTTP and RPC. One type per file. |\n' +
+    '| `migrations/` | ToilDB schema migrations: a `<Type>.migration.ts` per evolving `@data` value type, holding the old shapes + the `@migrate` transform. |\n' +
+    '| `routes/` | `@rest` controllers (HTTP). One controller per file, named after its class. |\n' +
+    '| `services/` | `@service` classes and free `@remote` functions (typed RPC). |\n' +
+    '| `scheduled/` | Reserved for scheduled tasks (not shipped yet). |\n\n' +
+    'New decorated files are picked up automatically by `toiljs build`/`dev`; also add an import\n' +
+    'in `main.ts` so a direct `toilscript` run builds the same server.\n';
+
 /**
  * A minimal but working server for the `minimal` template (the `app` template copies
  * examples/basic/server). Same folder conventions as the full starter, just fewer files:
@@ -405,25 +427,86 @@ function minimalServer(): Record<string, string> {
             'export function abort(message: string, fileName: string, line: u32, column: u32): void {\n' +
             '    revertOnError(message, fileName, line, column);\n' +
             '}\n',
-        'server/README.md':
-            '# server/\n\n' +
-            'Your ToilScript backend, compiled to a single WebAssembly module. One folder per concern:\n\n' +
-            '| Folder | What lives here |\n' +
-            '| --- | --- |\n' +
-            '| `main.ts` | The entry point: wires the handler and imports the surface modules. |\n' +
-            '| `core/` | The request handler and shared app logic (state, helpers). |\n' +
-            '| `models/` | `@data` classes, the typed wire model shared by HTTP and RPC. One type per file. |\n' +
-            '| `migrations/` | ToilDB schema migrations: a `<Type>.migration.ts` per evolving `@data` value type, holding the old shapes + the `@migrate` transform. |\n' +
-            '| `routes/` | `@rest` controllers (HTTP). One controller per file, named after its class. |\n' +
-            '| `services/` | `@service` classes and free `@remote` functions (typed RPC). |\n' +
-            '| `scheduled/` | Reserved for scheduled tasks (not shipped yet). |\n\n' +
-            'New decorated files are picked up automatically by `toiljs build`/`dev`; also add an import\n' +
-            'in `main.ts` so a direct `toilscript` run builds the same server.\n',
+        'server/README.md': SERVER_README,
     };
 }
 
-/** The inline client UI for the `minimal` template (the `app` template copies examples/basic/client). */
-function minimalClient(name: string, features: StyleFeatures): Record<string, string> {
+/**
+ * A working server for the `agent` template: one correctly-structured `@rest` endpoint. A `@data`
+ * model under models/, a controller under routes/, an AppHandler that tries the REST controllers
+ * via `Rest.dispatch` (then yields to the client), and main.ts importing the route. The server
+ * build turns this into the typed `Server.REST.greeting.hello()` fetch the home page calls.
+ */
+function agentServer(): Record<string, string> {
+    return {
+        'server/toil-server-env.d.ts': TOIL_SERVER_ENV_DTS,
+        'server/models/Greeting.ts':
+            '/** The response body for `GET /greeting`. `@data` classes cross the wire as JSON and\n' +
+            ' *  land on the client as this exact typed class. One `@data` type per file. */\n' +
+            '@data\n' +
+            'export class Greeting {\n' +
+            "    message: string = '';\n" +
+            '}\n',
+        'server/routes/Greet.ts':
+            "import { Greeting } from '../models/Greeting';\n\n" +
+            '/**\n' +
+            ' * The greeting endpoint, mounted at `/greeting`. `@rest` / `@get` are ambient compiler\n' +
+            ' * decorators (no import). On the client this is one typed fetch:\n' +
+            ' *   await Server.REST.greeting.hello()\n' +
+            ' */\n' +
+            "@rest('greeting')\n" +
+            'class Greet {\n' +
+            '    /** `GET /greeting` - returns a `Greeting`, serialized to JSON for the client. */\n' +
+            "    @get('/')\n" +
+            '    public hello(): Greeting {\n' +
+            '        const g = new Greeting();\n' +
+            "        g.message = 'Hello from the toiljs backend';\n" +
+            '        return g;\n' +
+            '    }\n' +
+            '}\n',
+        'server/core/AppHandler.ts':
+            "import { Request, Response, Rest, ToilHandler } from 'toiljs/server/runtime';\n\n" +
+            '/**\n' +
+            ' * Every request enters here. The `@rest` controllers under routes/ are tried first via\n' +
+            ' * `Rest.dispatch`; anything they do not claim yields to the client (page routes, assets).\n' +
+            ' */\n' +
+            'export class AppHandler extends ToilHandler {\n' +
+            '    public handle(req: Request): Response {\n' +
+            '        // Rest.dispatch returns the first matching route\'s Response, or null when nothing\n' +
+            '        // matched. REST composes; it never takes over handle().\n' +
+            '        const hit = Rest.dispatch(req);\n' +
+            '        if (hit != null) {\n' +
+            '            return hit;\n' +
+            '        }\n' +
+            '        // Nothing matched: yield to the client. Under `toiljs dev` this falls through to\n' +
+            '        // Vite so the app renders at /.\n' +
+            '        return Response.unhandled();\n' +
+            '    }\n' +
+            '}\n',
+        'server/main.ts':
+            "import { Server } from 'toiljs/server/runtime';\n" +
+            "import { revertOnError } from 'toiljs/server/runtime/abort/abort';\n\n" +
+            "import { AppHandler } from './core/AppHandler';\n\n" +
+            '// Surface modules: import every @rest route (and @service/@remote RPC) here so a direct\n' +
+            '// `toilscript` run builds the same server `toiljs build` does.\n' +
+            "import './routes/Greet';\n\n" +
+            '// Wire your handler here.\n' +
+            'Server.handler = () => new AppHandler();\n\n' +
+            '// Required: re-export the WASM entry points and the abort hook.\n' +
+            "export * from 'toiljs/server/runtime/exports';\n" +
+            'export function abort(message: string, fileName: string, line: u32, column: u32): void {\n' +
+            '    revertOnError(message, fileName, line, column);\n' +
+            '}\n',
+        'server/README.md': SERVER_README,
+    };
+}
+
+/**
+ * The shared client shell for the inline templates (`minimal`, `agent`): the public assets,
+ * `toil.tsx` mount, global stylesheet, and the (optional) Tailwind entry. Each template layers
+ * its own `layout.tsx` + `routes/` on top; the `app` template copies examples/basic/client instead.
+ */
+function clientShell(name: string, features: StyleFeatures): Record<string, string> {
     const files: Record<string, string> = {
         'client/public/index.html':
             '<!doctype html>\n<html lang="en">\n  <head>\n' +
@@ -471,7 +554,17 @@ function minimalClient(name: string, features: StyleFeatures): Record<string, st
             'Toil.mount(routes, layout, notFound, globalError, slots);\n',
         [`client/${styleEntry(features.preprocessor)}`]: DEFAULT_STYLE_CONTENT,
         'client/components/.gitkeep': '# Place shared React components here.\n',
-        'client/layout.tsx': `import { type ReactNode } from 'react';
+    };
+    if (features.tailwind) files[`client/${TAILWIND_ENTRY}`] = TAILWIND_CSS;
+    return files;
+}
+
+/** The root `layout.tsx`: the app frame + a nav bar of `Toil.Link`s (one per `nav` entry). */
+function layoutTsx(name: string, nav: readonly { href: string; label: string }[]): string {
+    const links = nav
+        .map((l) => `                    <Toil.Link href="${l.href}">${l.label}</Toil.Link>`)
+        .join('\n');
+    return `import { type ReactNode } from 'react';
 
 export default function Layout({ children }: { children?: ReactNode }) {
     return (
@@ -487,14 +580,21 @@ export default function Layout({ children }: { children?: ReactNode }) {
                 }}>
                 <strong style={{ color: '#2563FF', fontSize: '1.1rem' }}>${path.basename(name)}</strong>
                 <nav style={{ display: 'flex', gap: '1rem' }}>
-                    <Toil.Link href="/">home</Toil.Link>
+${links}
                 </nav>
             </header>
             {children}
         </div>
     );
 }
-`,
+`;
+}
+
+/** The inline client UI for the `minimal` template (the `app` template copies examples/basic/client). */
+function minimalClient(name: string, features: StyleFeatures): Record<string, string> {
+    return {
+        ...clientShell(name, features),
+        'client/layout.tsx': layoutTsx(name, [{ href: '/', label: 'home' }]),
         'client/routes/index.tsx':
             'export default function Home() {\n' +
             '    return (\n        <main>\n' +
@@ -502,8 +602,49 @@ export default function Layout({ children }: { children?: ReactNode }) {
             '            <p>File-based routing, bundled by Vite, zero config.</p>\n' +
             '        </main>\n    );\n}\n',
     };
-    if (features.tailwind) files[`client/${TAILWIND_ENTRY}`] = TAILWIND_CSS;
-    return files;
+}
+
+/**
+ * The inline client UI for the `agent` template: two file-routed pages (basic routing) and a home
+ * page that calls the backend's one @rest endpoint through the generated, typed `Server.REST`
+ * fetch client. `Server` and `parseError` are client globals (no import), like `Toil`.
+ */
+function agentClient(name: string, features: StyleFeatures): Record<string, string> {
+    return {
+        ...clientShell(name, features),
+        'client/layout.tsx': layoutTsx(name, [
+            { href: '/', label: 'home' },
+            { href: '/about', label: 'about' },
+        ]),
+        'client/routes/index.tsx':
+            "import { useEffect, useState } from 'react';\n\n" +
+            '// The home page calls the backend. `Server.REST.greeting.hello()` is a real, typed\n' +
+            '// fetch generated from the @rest controller in server/routes/Greet.ts (see the\n' +
+            '// gitignored shared/server.ts, emitted by the server build). It needs the server running.\n' +
+            'export default function Home() {\n' +
+            "    const [message, setMessage] = useState('loading…');\n\n" +
+            '    useEffect(() => {\n' +
+            '        Server.REST.greeting\n' +
+            '            .hello()\n' +
+            '            .then((g) => setMessage(g.message))\n' +
+            '            .catch((err) => setMessage(parseError(err)));\n' +
+            '    }, []);\n\n' +
+            '    return (\n        <main>\n' +
+            '            <h1>Welcome to toiljs</h1>\n' +
+            '            <p>File-based routing on the client, a ToilScript backend behind one typed fetch.</p>\n' +
+            '            <p>\n' +
+            '                <code>GET /greeting</code> says: <strong>{message}</strong>\n' +
+            '            </p>\n' +
+            '        </main>\n    );\n}\n',
+        'client/routes/about.tsx':
+            'export default function About() {\n' +
+            '    return (\n        <main>\n' +
+            '            <h1>About</h1>\n' +
+            '            <p>\n' +
+            '                A second page, routed by its file name. Add more under <code>client/routes/</code>.\n' +
+            '            </p>\n' +
+            '        </main>\n    );\n}\n',
+    };
 }
 
 /**
@@ -624,6 +765,11 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
                 hint: 'the full ToilJS starter, landing page, layout, styles, demo routes',
             },
             { value: 'minimal', label: 'Minimal', hint: 'just a layout and a home route' },
+            {
+                value: 'agent',
+                label: 'Agent',
+                hint: 'minimal, plus one @rest endpoint the home page calls, a base to build on',
+            },
         ];
         const choice = await select({
             message: 'Which template?',
@@ -631,7 +777,7 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
             initialValue: 'app',
         });
         bail(choice);
-        template = choice === 'minimal' ? 'minimal' : 'app';
+        template = choice === 'minimal' || choice === 'agent' ? choice : 'app';
     }
 
     let preprocessor: Preprocessor = opts.preprocessor ?? 'css';

package/src/cli/diagnostics.ts

@@ -83,6 +83,80 @@ export function checkPeer(name: string, installed: string | null, range: string)
     };
 }
 
+/** The TypeScript range toiljs supports, and the range `doctor --fix` pins an unsupported one to. */
+export const TYPESCRIPT_SUPPORTED = '>=6.0.0 <7.0.0';
+export const TYPESCRIPT_FIX_RANGE = '^6.0.3';
+
+/** First TypeScript major that dropped the JavaScript compiler API (the native port). */
+const TYPESCRIPT_NATIVE_MAJOR = 7;
+
+/**
+ * The major a dependency range floats to: the first number in the range, once the comparators are
+ * stripped (`^7.0.2` -> 7, `>=6.0.0 <7.0.0` -> 6). Returns null for a range that names no version
+ * (`*`, `latest`), which is treated as "unpinned" rather than "unsupported".
+ */
+export function rangeMajor(range: string): number | null {
+    const m = /(\d+)/.exec(range.replace(/^[\s^~>=<v]*/, ''));
+    return m ? Number(m[1]) : null;
+}
+
+/**
+ * TypeScript 7 is the native (Go) port: it publishes `tsc` but no longer exports the JavaScript
+ * compiler API, whose main entry is now just `{ version, versionMajorMinor }`. toiljs reads each
+ * route's static `metadata` through that API to bake SEO tags into the built HTML, and the eslint
+ * and typedoc presets load it too. So a TS 7 install does not fail loudly, it silently stops baking
+ * metadata (and hard-crashes typescript-eslint), which is worth a `fail` rather than a warning.
+ *
+ * `installed` is the version resolved from node_modules (authoritative, it is what actually runs);
+ * `declared` is the project's package.json range, which is flagged when it *admits* 7 even if the
+ * currently-installed copy is older, since the next install would break.
+ */
+export function checkTypeScript(installed: string | null, declared: string | null): Check {
+    const id = 'peer:typescript';
+    const label = 'typescript';
+    const unsupported = (version: string, detail: string): Check => ({
+        id,
+        label,
+        status: 'fail',
+        detail,
+        fix:
+            `TypeScript ${version} removed the JavaScript compiler API (it moved to ` +
+            `'typescript/unstable/*'), which toiljs's route-metadata extractor, the eslint preset, ` +
+            `and typedoc all load. Pin typescript to "${TYPESCRIPT_FIX_RANGE}" and reinstall ` +
+            `(\`toiljs doctor --fix\` does this).`,
+    });
+
+    if (installed === null) {
+        return {
+            id,
+            label,
+            status: 'fail',
+            detail: `not installed (requires ${TYPESCRIPT_SUPPORTED})`,
+            fix: `Install typescript@"${TYPESCRIPT_FIX_RANGE}".`,
+        };
+    }
+
+    const installedMajor = rangeMajor(installed);
+    if (installedMajor !== null && installedMajor >= TYPESCRIPT_NATIVE_MAJOR) {
+        return unsupported(String(installedMajor), `${installed} installed, unsupported`);
+    }
+
+    // Installed copy is fine, but the declared range would pull an unsupported major next install.
+    const declaredMajor = declared === null ? null : rangeMajor(declared);
+    if (declaredMajor !== null && declaredMajor >= TYPESCRIPT_NATIVE_MAJOR) {
+        return unsupported(String(declaredMajor), `package.json declares ${declared ?? ''}`);
+    }
+
+    const ok = satisfiesMin(installed, TYPESCRIPT_SUPPORTED);
+    return {
+        id,
+        label,
+        status: ok ? 'pass' : 'warn',
+        detail: `${installed} (requires ${TYPESCRIPT_SUPPORTED})`,
+        fix: ok ? undefined : `Update typescript to ${TYPESCRIPT_SUPPORTED}.`,
+    };
+}
+
 export function checkPackageManager(lockfiles: readonly string[]): Check {
     if (lockfiles.length === 0) {
         return {

package/src/cli/doctor.ts

@@ -46,15 +46,18 @@ import {
     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,
@@ -70,7 +73,7 @@ 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). */
+    /** Auto-fix what can be fixed in place (the typed-RPC wiring, and an unsupported typescript). */
     readonly fix?: boolean;
 }
 
@@ -129,6 +132,72 @@ function isPackageInstalled(root: string, name: string): boolean {
     }
 }
 
+/**
+ * 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)
@@ -764,7 +833,26 @@ 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);
+    // 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.
@@ -784,19 +872,15 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
     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 =
-        rpcFix || prettierFix || editorFix
+        applied.length > 0
             ? {
-                  changed: [
-                      ...(rpcFix?.changed ?? []),
-                      ...(prettierFix?.changed ?? []),
-                      ...(editorFix?.changed ?? []),
-                  ],
-                  skipped: [
-                      ...(rpcFix?.skipped ?? []),
-                      ...(prettierFix?.skipped ?? []),
-                      ...(editorFix?.skipped ?? []),
-                  ],
+                  changed: applied.flatMap((fix) => fix.changed),
+                  skipped: applied.flatMap((fix) => fix.skipped),
               }
             : null;
 
@@ -807,6 +891,7 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
                 checkNode(process.versions.node, meta.node),
                 checkToiljsInstalled('toiljs' in deps ? version() : null),
                 ...peerChecks,
+                typeScriptCheck,
                 checkPackageManager(LOCKFILES.filter((f) => fs.existsSync(path.join(root, f)))),
             ],
         },
@@ -876,28 +961,21 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
     } 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 (serverFix) renderFix(serverFix);
     }
     if (hasFailures(summary)) process.exitCode = 1;
 }
 
-/** Prints the result of `--fix`, and whether a reinstall is needed (toilscript bump). */
-function renderRpcFix(result: RpcFixResult): void {
+/** 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 server 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.'),
-            );
+        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('server wiring already in place, nothing to fix.'));
+        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');

package/src/cli/features.ts

@@ -36,13 +36,17 @@ export const PREPROCESSOR_PKG: Record<Preprocessor, string | null> = {
 /** Tailwind v4 packages. The framework auto-wires the Vite plugin when `@tailwindcss/vite` resolves. */
 export const TAILWIND_PKGS: readonly string[] = ['tailwindcss', '@tailwindcss/vite'];
 
-/** Pinned versions for every package these features may install. */
+/**
+ * Pinned versions for every package these features may install. `@tailwindcss/vite` must be
+ * `>= 4.3.0`: earlier 4.x releases cap their `vite` peer at `^7`, so they ERESOLVE against the
+ * Vite 8 toiljs ships (the "Tailwind broken on install" error). Keep both Tailwind pins in lockstep.
+ */
 export const PKG_VERSION: Record<string, string> = {
     sass: '^1.83.0',
     less: '^4.2.1',
     stylus: '^0.64.0',
-    tailwindcss: '^4.0.0',
-    '@tailwindcss/vite': '^4.0.0',
+    tailwindcss: '^4.3.0',
+    '@tailwindcss/vite': '^4.3.0',
 };
 
 /** Dedicated Tailwind entry (kept `.css` so no preprocessor touches its `@import`). */

package/src/cli/index.ts

@@ -74,7 +74,7 @@ function parseArgs(argv: string[]): Flags {
             case '--template':
             case '-t': {
                 const t = argv[++i];
-                if (t === 'app' || t === 'minimal') flags.template = t;
+                if (t === 'app' || t === 'minimal' || t === 'agent') flags.template = t;
                 break;
             }
             case '--pm':
@@ -160,7 +160,7 @@ function printHelp(): void {
             cmd('--port <n>', 'dev/start: listen port (or PORT env / client.port; default 3000)'),
             cmd('--host <h>', 'dev/start: bind host, e.g. 0.0.0.0 (or HOST env / client.host; default 127.0.0.1)'),
             cmd('--threads <n>', 'start: production HTTP worker count'),
-            cmd('-t, --template', 'create: app | minimal'),
+            cmd('-t, --template', 'create: app | minimal | agent'),
             cmd('--style <name>', 'create/configure: css | sass | less | stylus'),
             cmd('--tailwind', 'create/configure: enable Tailwind (--no-tailwind to remove)'),
             cmd('--no-ai', 'create: skip AI assistant files (CLAUDE.md, etc.)'),

package/src/cli/update.ts

@@ -11,7 +11,7 @@ import { cancel, intro, isCancel, multiselect, note, outro, spinner } from '@cla
 
 import { MIGRATIONS_README } from './create.js';
 import { capture, run } from './proc.js';
-import { buildRows, type Bump, parseNcuJson, type UpdateRow } from './updates.js';
+import { buildRows, type Bump, parseNcuJson, type UpdateRow, withheldUpgrades } from './updates.js';
 import { accent, danger, dim, success, warn } from './ui.js';
 
 export interface UpdateOptions {
@@ -109,6 +109,20 @@ function rowLine(row: UpdateRow): string {
     return `${row.name}  ${dim(row.from)} ${dim('->')} ${bumpColor(row.bump, row.to)}`;
 }
 
+/** Tells the user which upgrades were held back, and why they are not simply missing. */
+function noteWithheld(names: readonly string[]): void {
+    note(
+        names.map((n) => `${dim('-')} ${n}`).join('\n') +
+            '\n\n' +
+            dim(
+                'Held back: this major is not supported by toiljs yet. TypeScript 7 is the native\n' +
+                    'port and ships no JavaScript compiler API, so route metadata would stop being\n' +
+                    'baked into the built HTML and typescript-eslint would not load.',
+            ),
+        warn('Not upgraded'),
+    );
+}
+
 const TARGETS = new Set(['latest', 'minor', 'patch', 'newest', 'greatest']);
 
 export async function runUpdate(opts: UpdateOptions): Promise<void> {
@@ -152,13 +166,21 @@ export async function runUpdate(opts: UpdateOptions): Promise<void> {
         process.exitCode = 1;
         return;
     }
-    const rows = buildRows(parseNcuJson(res.stdout), currentDeps);
+    // Hold back upgrades into a major toiljs cannot run on (typescript 7), so neither the picker nor
+    // a `-y` run can install one. `--reject` keeps ncu from applying them during `-u` below.
+    const upgraded = parseNcuJson(res.stdout);
+    const withheld = withheldUpgrades(upgraded);
+    for (const name of withheld) delete upgraded[name];
+
+    const rows = buildRows(upgraded, currentDeps);
     if (rows.length === 0) {
         s.stop('Everything is up to date');
+        if (withheld.length > 0) noteWithheld(withheld);
         outro(success('Nothing to update.'));
         return;
     }
     s.stop(`${String(rows.length)} update${rows.length === 1 ? '' : 's'} available`);
+    if (withheld.length > 0) noteWithheld(withheld);
 
     const counts = { major: 0, minor: 0, patch: 0, other: 0 };
     for (const r of rows) counts[r.bump]++;
@@ -195,7 +217,12 @@ export async function runUpdate(opts: UpdateOptions): Promise<void> {
 
     s.start('Updating package.json');
     const applyAll = selected.length === rows.length;
-    await run('npx', ncuArgs(applyAll ? ['-u'] : ['-u', '--filter', selected.join(' ')]), root);
+    const reject = withheld.length > 0 ? ['--reject', withheld.join(' ')] : [];
+    await run(
+        'npx',
+        ncuArgs(applyAll ? ['-u', ...reject] : ['-u', '--filter', selected.join(' '), ...reject]),
+        root,
+    );
     s.stop('package.json updated');
 
     // Run the install with VISIBLE output (so a failure is diagnosable — npm