toiljs 0.0.15 → 0.0.19

package/src/compiler/index.ts

@@ -1,57 +1,66 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { build as viteBuild, createServer, type ViteDevServer } from 'vite';
-import { startBackend, type RunningBackend } from 'toiljs/backend';
-
-import { loadConfig } from './config.js';
-import { generate } from './generate.js';
-import { prerenderStaticParams } from './ssg.js';
-import { createViteConfig } from './vite.js';
-
-export interface ToilCommandOptions {
-    readonly root?: string;
-    readonly port?: number;
-}
-
-/** Starts the Vite dev server (HMR + transforms) for the client app. Returns the running server. */
-export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer> {
-    const cfg = await loadConfig(opts);
-    generate(cfg);
-    const server = await createServer(await createViteConfig(cfg));
-    await server.listen();
-    server.printUrls();
-    return server;
-}
-
-/** Produces an optimized production SPA bundle in the configured `outDir`. */
-export async function build(opts: ToilCommandOptions = {}): Promise<void> {
-    const cfg = await loadConfig(opts);
-    generate(cfg);
-    await viteBuild(await createViteConfig(cfg));
-    // SSG: bake per-URL HTML + sitemap for dynamic routes that opt in via `generateStaticParams`.
-    await prerenderStaticParams(cfg);
-}
-
-/**
- * Self-hosts the built client over the high-performance hyper-express backend (uWebSockets.js),
- * serving the configured `outDir` with an SPA fallback plus a WebSocket channel. Requires a prior
- * `build`. Returns the running backend.
- */
-export async function start(opts: ToilCommandOptions = {}): Promise<RunningBackend> {
-    const cfg = await loadConfig(opts);
-    const outDir = path.resolve(cfg.root, cfg.outDir);
-    if (!fs.existsSync(path.join(outDir, 'index.html'))) {
-        throw new Error(`No build found in ${outDir}. Run \`toiljs build\` first.`);
-    }
-    return startBackend({ root: outDir, port: cfg.port });
-}
-
-export { defineConfig, loadConfig } from './config.js';
-export { scanRoutes } from './routes.js';
-export type { ScannedRoute } from './routes.js';
-export { TOIL_ENV_DTS } from './generate.js';
-export { AI_HELPERS, AI_HELPER_IDS, aiHelperFiles, TOIL_DOCS } from './docs.js';
-export type { AiHelper } from './docs.js';
-export type { ToilConfig, ResolvedToilConfig } from './config.js';
-export type { RunningBackend, BackendOptions } from 'toiljs/backend';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { build as viteBuild, createServer, type ViteDevServer } from 'vite';
+import { startBackend, type RunningBackend } from 'toiljs/backend';
+
+import { loadConfig } from './config.js';
+import { generate } from './generate.js';
+import { prerenderStaticParams } from './ssg.js';
+import { createViteConfig } from './vite.js';
+
+export interface ToilCommandOptions {
+    readonly root?: string;
+    readonly port?: number;
+    /** Bind host for `start`. Defaults to loopback (`127.0.0.1`); pass `0.0.0.0` to expose. */
+    readonly host?: string;
+}
+
+/** Starts the Vite dev server (HMR + transforms) for the client app. Returns the running server. */
+export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer> {
+    const cfg = await loadConfig(opts);
+    generate(cfg);
+    const server = await createServer(await createViteConfig(cfg));
+    await server.listen();
+    server.printUrls();
+    return server;
+}
+
+/** Produces an optimized production SPA bundle in the configured `outDir`. */
+export async function build(opts: ToilCommandOptions = {}): Promise<void> {
+    const cfg = await loadConfig(opts);
+    generate(cfg);
+    await viteBuild(await createViteConfig(cfg));
+    // SSG: bake per-URL HTML + sitemap for dynamic routes that opt in via `generateStaticParams`.
+    await prerenderStaticParams(cfg);
+}
+
+/**
+ * Self-hosts the built client over the high-performance hyper-express backend (uWebSockets.js),
+ * serving the configured `outDir` with an SPA fallback plus a WebSocket channel. Requires a prior
+ * `build`. Returns the running backend.
+ */
+export async function start(opts: ToilCommandOptions = {}): Promise<RunningBackend> {
+    const cfg = await loadConfig(opts);
+    const outDir = path.resolve(cfg.root, cfg.outDir);
+    if (!fs.existsSync(path.join(outDir, 'index.html'))) {
+        throw new Error(`No build found in ${outDir}. Run \`toiljs build\` first.`);
+    }
+    return startBackend({ root: outDir, port: cfg.port, host: opts.host });
+}
+
+export { defineConfig, loadConfig, AiProvider } from './config.js';
+export { scanRoutes } from './routes.js';
+export type { ScannedRoute } from './routes.js';
+export { TOIL_ENV_DTS } from './generate.js';
+export { AI_HELPERS, AI_HELPER_IDS, aiHelperFiles, TOIL_DOCS } from './docs.js';
+export type { AiHelper } from './docs.js';
+export type {
+    ToilConfig,
+    ResolvedToilConfig,
+    ClientConfig,
+    ServerConfig,
+    DevtoolsConfig,
+    DevtoolsAiConfig,
+} from './config.js';
+export type { RunningBackend, BackendOptions } from 'toiljs/backend';

package/src/compiler/pages.ts

@@ -1,70 +1,70 @@
-import { createRequire } from 'node:module';
-import path from 'node:path';
-
-import type * as TS from 'typescript';
-
-import { extractStaticExports } from './prerender.js';
-import type { ScannedRoute } from './routes.js';
-
-type Ts = typeof TS;
-
-/**
- * A page in the build-time search index: its URL pattern, whether it's dynamic, and the
- * statically-extracted `metadata` literal (the searchable subset; dynamic `generateMetadata` and
- * computed values can't be known at build, so they're absent). Serialized into the generated
- * `routes` module and registered client-side for {@link searchPages}.
- */
-export interface PageIndexEntry {
-    readonly path: string;
-    readonly dynamic: boolean;
-    readonly metadata: Record<string, unknown>;
-}
-
-/**
- * Loads the project's TypeScript synchronously (so {@link buildPageIndex} can run inside the sync
- * `generate()`), or `null` if it isn't installed, in which case pages are indexed by path only.
- */
-function loadTypeScriptSync(root: string): Ts | null {
-    try {
-        const require = createRequire(path.join(root, 'package.json'));
-        const mod = require('typescript') as { default?: Ts } & Ts;
-        return mod.default ?? mod;
-    } catch {
-        return null;
-    }
-}
-
-/** True when a route pattern has dynamic (`:param` / `*catch-all`) segments. */
-function isDynamic(pattern: string): boolean {
-    return /[:*]/.test(pattern);
-}
-
-/**
- * Builds the searchable page index from the scanned routes: every main-tree page (slots and
- * intercepting routes are excluded, they don't own a distinct URL) paired with its statically
- * extracted `metadata`. A route may also `export const searchHints` (a static `title`/`description`/
- * `keywords` object) to feed the index even when its real metadata is dynamic (`generateMetadata`);
- * hints are merged over the static `metadata`, winning ties. Reads each route file once.
- */
-export function buildPageIndex(root: string, routes: readonly ScannedRoute[]): PageIndexEntry[] {
-    const ts = loadTypeScriptSync(root);
-    const seen = new Set<string>();
-    const pages: PageIndexEntry[] = [];
-    for (const route of routes) {
-        if (route.slot !== undefined || route.intercept) continue;
-        if (seen.has(route.pattern)) continue;
-        seen.add(route.pattern);
-        const exports = ts ? extractStaticExports(ts, route.file, ['metadata', 'searchHints']) : {};
-        const metadata = { ...exports.metadata, ...exports.searchHints };
-        pages.push({ path: route.pattern, dynamic: isDynamic(route.pattern), metadata });
-    }
-    // Stable order (by path) so the generated module is deterministic across runs.
-    pages.sort((a, b) => a.path.localeCompare(b.path));
-    return pages;
-}
-
-/** Serializes the page index to the `export const pages` literal embedded in the routes module. */
-export function pagesModuleSource(pages: readonly PageIndexEntry[]): string {
-    const body = pages.map((p) => `  ${JSON.stringify(p)},`).join('\n');
-    return `export const pages: PageMeta[] = [\n${body}\n];\n`;
-}
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import type * as TS from 'typescript';
+
+import { extractStaticExports } from './prerender.js';
+import type { ScannedRoute } from './routes.js';
+
+type Ts = typeof TS;
+
+/**
+ * A page in the build-time search index: its URL pattern, whether it's dynamic, and the
+ * statically-extracted `metadata` literal (the searchable subset; dynamic `generateMetadata` and
+ * computed values can't be known at build, so they're absent). Serialized into the generated
+ * `routes` module and registered client-side for {@link searchPages}.
+ */
+export interface PageIndexEntry {
+    readonly path: string;
+    readonly dynamic: boolean;
+    readonly metadata: Record<string, unknown>;
+}
+
+/**
+ * Loads the project's TypeScript synchronously (so {@link buildPageIndex} can run inside the sync
+ * `generate()`), or `null` if it isn't installed, in which case pages are indexed by path only.
+ */
+function loadTypeScriptSync(root: string): Ts | null {
+    try {
+        const require = createRequire(path.join(root, 'package.json'));
+        const mod = require('typescript') as { default?: Ts } & Ts;
+        return mod.default ?? mod;
+    } catch {
+        return null;
+    }
+}
+
+/** True when a route pattern has dynamic (`:param` / `*catch-all`) segments. */
+function isDynamic(pattern: string): boolean {
+    return /[:*]/.test(pattern);
+}
+
+/**
+ * Builds the searchable page index from the scanned routes: every main-tree page (slots and
+ * intercepting routes are excluded, they don't own a distinct URL) paired with its statically
+ * extracted `metadata`. A route may also `export const searchHints` (a static `title`/`description`/
+ * `keywords` object) to feed the index even when its real metadata is dynamic (`generateMetadata`);
+ * hints are merged over the static `metadata`, winning ties. Reads each route file once.
+ */
+export function buildPageIndex(root: string, routes: readonly ScannedRoute[]): PageIndexEntry[] {
+    const ts = loadTypeScriptSync(root);
+    const seen = new Set<string>();
+    const pages: PageIndexEntry[] = [];
+    for (const route of routes) {
+        if (route.slot !== undefined || route.intercept) continue;
+        if (seen.has(route.pattern)) continue;
+        seen.add(route.pattern);
+        const exports = ts ? extractStaticExports(ts, route.file, ['metadata', 'searchHints']) : {};
+        const metadata = { ...exports.metadata, ...exports.searchHints };
+        pages.push({ path: route.pattern, dynamic: isDynamic(route.pattern), metadata });
+    }
+    // Stable order (by path) so the generated module is deterministic across runs.
+    pages.sort((a, b) => a.path.localeCompare(b.path));
+    return pages;
+}
+
+/** Serializes the page index to the `export const pages` literal embedded in the routes module. */
+export function pagesModuleSource(pages: readonly PageIndexEntry[]): string {
+    const body = pages.map((p) => `  ${JSON.stringify(p)},`).join('\n');
+    return `export const pages: PageMeta[] = [\n${body}\n];\n`;
+}

package/src/compiler/plugin.ts

@@ -1,7 +1,152 @@
-import { type Plugin } from 'vite';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { type IncomingMessage } from 'node:http';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-import { type ResolvedToilConfig } from './config.js';
+import { type Plugin, version as viteVersion } from 'vite';
+
+import { AiProvider, type DevtoolsAiConfig, type ResolvedToilConfig } from './config.js';
 import { generate } from './generate.js';
+import { scanRoutes } from './routes.js';
+
+/** Calls the configured AI provider (server-side, so the key never reaches the browser). */
+async function aiComplete(ai: DevtoolsAiConfig, prompt: string): Promise<string> {
+    const key = ai.apiKeyEnv ? process.env[ai.apiKeyEnv] : undefined;
+    if (ai.endpoint) {
+        const r = await fetch(ai.endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ prompt }),
+        });
+        const j = (await r.json()) as { text?: string };
+        return j.text ?? '';
+    }
+    if (ai.provider === AiProvider.OpenAI) {
+        if (!key) throw new Error(`missing API key (set env ${ai.apiKeyEnv ?? 'OPENAI_API_KEY'})`);
+        const r = await fetch('https://api.openai.com/v1/chat/completions', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+            body: JSON.stringify({
+                model: ai.model ?? 'gpt-4o',
+                messages: [{ role: 'user', content: prompt }],
+            }),
+        });
+        const j = (await r.json()) as { choices?: { message?: { content?: string } }[] };
+        return j.choices?.[0]?.message?.content ?? '';
+    }
+    // default: anthropic
+    if (!key) throw new Error(`missing API key (set env ${ai.apiKeyEnv ?? 'ANTHROPIC_API_KEY'})`);
+    const r = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            'x-api-key': key,
+            'anthropic-version': '2023-06-01',
+        },
+        body: JSON.stringify({
+            model: ai.model ?? 'claude-sonnet-4-6',
+            max_tokens: 1024,
+            messages: [{ role: 'user', content: prompt }],
+        }),
+    });
+    const j = (await r.json()) as { content?: { text?: string }[] };
+    return (j.content ?? []).map((c) => c.text ?? '').join('');
+}
+
+/** Reads a package's version resolved from `<fromDir>`, or 'unknown'. */
+function depVersion(fromDir: string, name: string): string {
+    try {
+        const pkgPath = createRequire(path.join(fromDir, 'package.json')).resolve(`${name}/package.json`);
+        const raw = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version?: string };
+        return raw.version ?? 'unknown';
+    } catch {
+        return 'unknown';
+    }
+}
+
+/** toiljs's own version (package.json two levels up from build/compiler). */
+function frameworkVersion(): string {
+    try {
+        const p = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+        const raw = JSON.parse(fs.readFileSync(p, 'utf8')) as { version?: string };
+        return raw.version ?? '0.0.0';
+    } catch {
+        return '0.0.0';
+    }
+}
+
+/** Build/config snapshot served to the dev toolbar at `/__toil/devinfo`. */
+function devInfo(cfg: ResolvedToilConfig, port: number): Record<string, unknown> {
+    const routes: Record<string, string> = {};
+    for (const r of scanRoutes(cfg.routesAbsDir)) {
+        if (r.slot === undefined && !r.intercept) routes[r.pattern] = r.file;
+    }
+    return {
+        toiljs: frameworkVersion(),
+        // vite is a dependency of the framework, not the app, so resolving it from the app root
+        // fails; read the running vite's own exported version instead.
+        vite: viteVersion,
+        react: depVersion(cfg.root, 'react'),
+        port,
+        enabled: cfg.devtools,
+        flags: {
+            images: cfg.images,
+            fonts: cfg.fonts,
+            viewTransitions: cfg.viewTransitions,
+            transitions: cfg.transitions,
+            seo: cfg.seo != null,
+        },
+        routes,
+        ai: cfg.devtoolsAi !== null,
+    };
+}
+
+/**
+ * Resolves a request's `file` param to an absolute path that is genuinely inside the project root,
+ * or null. Guards against `..` traversal, sibling-prefix escapes (`<root>-evil/secret` passes a bare
+ * `startsWith(root)`), and symlinks inside the project that point outside it (realpath re-check).
+ */
+function safeProjectPath(cfg: ResolvedToilConfig, file: string | null): string | null {
+    if (!file) return null;
+    const root = cfg.root;
+    const inside = (p: string): boolean => p === root || p.startsWith(root + path.sep);
+    const abs = path.resolve(file);
+    if (!inside(abs) || !fs.existsSync(abs)) return null;
+    try {
+        const real = fs.realpathSync(abs);
+        return inside(real) ? real : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * True for requests that must NOT reach the dev endpoints (they open files, read source, and spend
+ * AI credits). Uses an allowlist on the browser-set `Sec-Fetch-Site`: only `same-origin` (the
+ * toolbar), `none` (user-initiated, e.g. the address bar), or an absent header (non-browser tooling
+ * like curl) are allowed. Everything else, `cross-site`, `same-site`, or any unexpected value, is
+ * rejected. This blocks CSRF (a malicious site's fetch/img) without breaking local dev tooling.
+ */
+function isCrossSiteRequest(headers: IncomingMessage['headers']): boolean {
+    const site = headers['sec-fetch-site'];
+    return site !== undefined && site !== 'same-origin' && site !== 'none';
+}
+
+/** Opens `file` in the user's editor (best-effort): `$EDITOR file`, else `code -g file`. */
+function openInEditor(file: string): void {
+    try {
+        const editor = process.env.EDITOR ?? process.env.VISUAL;
+        const child = editor
+            ? spawn(editor, [file], { stdio: 'ignore', detached: true })
+            : spawn('code', ['-g', file], { stdio: 'ignore', detached: true });
+        child.on('error', () => undefined);
+        child.unref();
+    } catch {
+        /* ignore */
+    }
+}
 
 /**
  * Vite plugin that keeps the generated route table in sync during dev: when a route file is
@@ -35,6 +180,117 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
             return null;
         },
         configureServer(server) {
+            // Dev toolbar endpoints (dev only). `/__toil/devinfo` -> build/config snapshot;
+            // `/__toil/open?file=` -> open the file in the editor.
+            server.middlewares.use('/__toil/devinfo', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                const port = server.config.server.port ?? cfg.port;
+                res.setHeader('content-type', 'application/json');
+                res.end(JSON.stringify(devInfo(cfg, port)));
+            });
+            // `/__toil/ai` -> server-side AI proxy. The key is read from the env here and never
+            // reaches the browser; 404 when AI isn't configured (the toolbar then only hands off).
+            server.middlewares.use('/__toil/ai', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                if (req.method !== 'POST') {
+                    res.statusCode = 405;
+                    res.end();
+                    return;
+                }
+                const ai = cfg.devtoolsAi;
+                if (!ai) {
+                    res.statusCode = 404;
+                    res.end();
+                    return;
+                }
+                let body = '';
+                let aborted = false;
+                req.on('data', (chunk) => {
+                    if (aborted) return;
+                    body += String(chunk);
+                    if (body.length > 100_000) {
+                        // Cap the request body so a runaway/malicious POST can't grow it unbounded.
+                        aborted = true;
+                        res.statusCode = 413;
+                        res.end();
+                        req.destroy();
+                    }
+                });
+                req.on('end', () => {
+                    if (aborted) return;
+                    void (async () => {
+                        try {
+                            const parsed = JSON.parse(body || '{}') as { prompt?: string };
+                            // Cap the prompt actually forwarded upstream (independent of the raw-body cap).
+                            const prompt =
+                                typeof parsed.prompt === 'string' ? parsed.prompt.slice(0, 16000) : '';
+                            const text = await aiComplete(ai, prompt);
+                            res.setHeader('content-type', 'application/json');
+                            res.end(JSON.stringify({ text }));
+                        } catch (e) {
+                            // Log the detail to the dev's terminal; return a generic message to the
+                            // client so upstream/provider error text is never reflected over HTTP.
+                            process.stderr.write(
+                                `toil: /__toil/ai failed: ${e instanceof Error ? e.message : String(e)}\n`,
+                            );
+                            res.statusCode = 500;
+                            res.setHeader('content-type', 'application/json');
+                            res.end(JSON.stringify({ error: 'AI request failed (see dev server logs).' }));
+                        }
+                    })();
+                });
+            });
+            server.middlewares.use('/__toil/open', (req, res) => {
+                try {
+                    if (isCrossSiteRequest(req.headers)) {
+                        res.statusCode = 403;
+                        res.end();
+                        return;
+                    }
+                    const url = new URL(req.url ?? '', 'http://localhost');
+                    const abs = safeProjectPath(cfg, url.searchParams.get('file'));
+                    if (abs) openInEditor(abs);
+                    res.statusCode = 204;
+                    res.end();
+                } catch {
+                    res.statusCode = 400;
+                    res.end();
+                }
+            });
+            // `/__toil/source?file=` -> the file's text, so the AI tab can include the page's code in
+            // its prompt. Same root-confinement (`safeProjectPath`) as `/__toil/open`; capped so a
+            // stray huge file can't bloat the response.
+            server.middlewares.use('/__toil/source', (req, res) => {
+                try {
+                    if (isCrossSiteRequest(req.headers)) {
+                        res.statusCode = 403;
+                        res.end();
+                        return;
+                    }
+                    const url = new URL(req.url ?? '', 'http://localhost');
+                    const abs = safeProjectPath(cfg, url.searchParams.get('file'));
+                    if (!abs) {
+                        res.statusCode = 404;
+                        res.end();
+                        return;
+                    }
+                    const text = fs.readFileSync(abs, 'utf8').slice(0, 20000);
+                    res.setHeader('content-type', 'text/plain; charset=utf-8');
+                    res.end(text);
+                } catch {
+                    res.statusCode = 400;
+                    res.end();
+                }
+            });
+
             // Trailing slash so a sibling like `routes-extra/` doesn't match the `routes/` prefix.
             const routesPrefix = cfg.routesAbsDir.replace(/\\/g, '/').replace(/\/?$/, '/');
             const onChange = (file: string): void => {