toiljs 0.0.59 → 0.0.61

package/src/compiler/docs.ts

@@ -6,6 +6,52 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { TOIL_DOCS } from './toil-docs.generated.js';
+
+export { TOIL_DOCS };
+
+/**
+ * One-line summaries for the pointer files' bullet list, keyed by `.toil/docs/` filename.
+ * A doc with no entry here still appears in the list (using its `# ` heading as the label),
+ * so adding a `docs/*.md` is picked up automatically without re-listing it by hand.
+ */
+const DOC_SUMMARIES: Record<string, string> = {
+    'index.md': 'overview and project layout',
+    'getting-started.md': 'the two halves, build/dev, and the request lifecycle',
+    'routing.md': 'file-based routing, nested layouts, loading / error files',
+    'client.md': 'the `Toil` global, Link / NavLink, router hooks',
+    'styling.md': 'CSS / Sass / Less / Stylus / Tailwind (via `toiljs configure`)',
+    'server.md': 'the toilscript server target, `@data` / `@remote` / `@rest`',
+    'ssr.md': 'server-side rendering (`ssr = true`, hole markers, the server `render`)',
+    'rpc.md': '`@service` / `@remote` and the generated typed client',
+    'data.md': 'the `@data` decorator and the binary codec',
+    'caching.md': 'the `@cache` decorator and `Response.cache(...)`',
+    'ratelimit.md': 'the `@ratelimit` decorator',
+    'auth.md': '`@auth` guards, `@user`, sessions, the client half',
+    'environment.md': '`Environment.get` / `getSecure` config + secrets',
+    'email.md': '`EmailService`, templates, provider config',
+    'cookies.md': 'the `Cookie` builder, `SecureCookies`, signing / encryption',
+    'crypto.md': 'the synchronous `crypto` global and `crypto.subtle`',
+    'time.md': '`Time.nowMillis()` / `Time.nowSeconds()`',
+    'cli.md': 'toiljs CLI commands',
+};
+
+/** First-level `# ` heading of a Markdown doc, used as a fallback bullet label. */
+function docTitle(content: string): string {
+    const m = content.match(/^#\s+(.+)$/m);
+    return m ? m[1].trim() : '';
+}
+
+/**
+ * The pointer files' bullet list, derived from the generated `TOIL_DOCS` map so it never
+ * drifts from the docs actually written into `.toil/docs/` (no second hand-kept list).
+ */
+const DOC_POINTERS = Object.keys(TOIL_DOCS)
+    .map((name) => {
+        const summary = DOC_SUMMARIES[name] ?? docTitle(TOIL_DOCS[name]);
+        return `- \`.toil/docs/${name}\`${summary ? `, ${summary}` : ''}`;
+    })
+    .join('\n');
 
 /** Shared body for the per-tool pointer files. */
 const POINTER_BODY = `# toiljs, AI assistant guide
@@ -16,13 +62,7 @@ routing, and a toilscript→WebAssembly server).
 **Before editing this project, read the generated documentation in \`.toil/docs/\`.** It describes
 the conventions you must follow:
 
-- \`.toil/docs/index.md\`, overview and project layout
-- \`.toil/docs/routing.md\`, file-based routing, nested layouts, loading / error files
-- \`.toil/docs/client.md\`, the \`Toil\` global, Link / NavLink, router hooks
-- \`.toil/docs/styling.md\`, CSS / Sass / Less / Stylus / Tailwind (via \`toiljs configure\`)
-- \`.toil/docs/server.md\`, the toilscript server target
-- \`.toil/docs/ssr.md\`, server-side rendering (\`ssr = true\`, hole markers, the server \`render\`)
-- \`.toil/docs/cli.md\`, toiljs CLI commands
+${DOC_POINTERS}
 
 \`.toil/docs/\` is regenerated by toiljs; do not edit it by hand. This pointer file is yours to edit.
 `;
@@ -68,307 +108,6 @@ export function aiHelperFiles(ids: readonly string[]): Record<string, string> {
     return out;
 }
 
-/** The framework docs written into `.toil/docs/` (placeholders for now), keyed by filename. */
-/** A doc file's contents from an array of lines (single-quoted, so backticks/`${}` stay literal). */
-function doc(lines: string[]): string {
-    return lines.join('\n') + '\n';
-}
-
-export const TOIL_DOCS: Record<string, string> = {
-    'index.md': doc([
-        '# toiljs',
-        '',
-        'A full-stack React framework: a Vite-bundled client SPA with file-based routing, plus a',
-        'toilscript-to-WebAssembly server target.',
-        '',
-        '## Project layout',
-        '',
-        '- `client/`, the app: `routes/` (file-based), `layout.tsx`, `components/`, `styles/`,',
-        '  `public/`, and `toil.tsx` (the entry that calls `Toil.mount`).',
-        '- `server/`, the toilscript → WASM target (`@main` entry), compiled by `toilscript`.',
-        '  `@data`/`@remote`/`@service` here generate the typed client `Server` API (see `server.md`).',
-        '- `toil.config.ts`, configuration via `defineConfig` (`toiljs.config.ts` also works).',
-        '- Generated, gitignored, do not edit: `.toil/` (working dir), `toil-env.d.ts` (ambient',
-        '  globals), `toil-routes.d.ts` (typed routes), `shared/server.ts` (the typed RPC module,',
-        '  emitted by the server build; import `@data` classes from `shared/server`).',
-        '',
-        '## Key ideas',
-        '',
-        '- `Toil` is a native global (no import): `Toil.Link`, `Toil.useRouter`, `Toil.useLoaderData`,',
-        '  etc. The IO classes (`FastMap`, `FastSet`, `DataWriter`, `DataReader`), `parseError`, and the',
-        '  generated `Server` RPC surface are globals too.',
-        '- Scripts: `npm run dev` (HMR), `npm run build` (→ `build/client` + `build/server`),',
-        '  `npm start` (self-host the build).',
-        '',
-        'See `routing.md`, `client.md`, `styling.md`, `server.md`, `ssr.md`, `cli.md`.',
-    ]),
-    'routing.md': doc([
-        '# Routing',
-        '',
-        'File-based, under `client/routes/`. A file path maps to a URL.',
-        '',
-        '## Route files',
-        '',
-        '- `index.tsx` → `/`, `about.tsx` → `/about`, `blog/index.tsx` → `/blog`',
-        '- `[id].tsx` → dynamic `/:id`, read with `Toil.useParams<{ id: string }>()`',
-        '- `[...slug].tsx` → catch-all (1+ segments); `[[...slug]].tsx` → optional catch-all (0+)',
-        '- `(group)/` → route group: groups files / scopes a layout, adds no URL segment',
-        '',
-        '## Special files',
-        '',
-        '- `layout.tsx`, wraps the routes beneath it. Root `client/layout.tsx` wraps everything;',
-        '  nested `routes/**/layout.tsx` compose inside it.',
-        '- `loading.tsx`, Suspense fallback shown while a route (chunk + loader) loads',
-        '- `error.tsx`, error boundary; receives `{ error, reset }` (`Toil.RouteErrorProps`)',
-        '- `client/404.tsx`, shown when no route matches',
-        '',
-        '## Data loaders',
-        '',
-        'Export `loader` from a route; it runs on navigation, in parallel with the chunk, and the',
-        'page suspends until it resolves (so `loading.tsx` shows). Read it with `useLoaderData`:',
-        '',
-        '    export const loader = async ({ params, searchParams }: Toil.LoaderArgs) => {',
-        '        return fetch(`/api/post/${params.id}`).then((r) => r.json());',
-        '    };',
-        '    export default function Post() {',
-        '        const post = Toil.useLoaderData<{ title: string }>();',
-        '        return <h1>{post.title}</h1>;',
-        '    }',
-        '',
-        '`Toil.useRouter().refresh()` re-runs loaders.',
-        '',
-        '## Server rendering',
-        '',
-        'Add `export const ssr = true` to render a route on the server (real first-paint HTML + SEO,',
-        'then hydration) with near-static speed. See `ssr.md`.',
-        '',
-        '## Navigation',
-        '',
-        '- `Toil.Link` / `Toil.NavLink` (adds an active class) / `Toil.useRouter()`',
-        '  (push / replace / back / forward / refresh / prefetch)',
-        '- `Toil.useParams`, `usePathname`, `useSearchParams`, `useNavigationPending`',
-        '- Hrefs are type-checked against your routes, a typo is a compile error.',
-    ]),
-    'client.md': doc([
-        '# Client runtime',
-        '',
-        'Everything is on the `Toil` global, no imports needed in route files.',
-        '',
-        '## Entry',
-        '',
-        '`client/toil.tsx` imports the route table + global styles and mounts the app:',
-        '',
-        '    import { routes, layout, notFound } from "toiljs/routes";',
-        '    import "./styles/main.css";',
-        '    Toil.mount(routes, layout, notFound);',
-        '',
-        '## API (on `Toil`)',
-        '',
-        '- Components: `Link`, `NavLink`, `Head`',
-        '- Navigation: `navigate`, `useRouter`, `useNavigate`',
-        '- Location: `usePathname`, `useSearchParams`, `useParams`, `useNavigationPending`',
-        '- Data: `useLoaderData` (see `routing.md`)',
-        '- Head: `useHead`, `useTitle`, `<Head>`, set the `<title>` / meta per route',
-        '- Realtime: `useChannel`, `connectChannel` (WebSocket to the backend at `/_toil`)',
-        '- IO globals (no `Toil.` prefix): `FastMap`, `FastSet`, `DataWriter`, `DataReader`',
-        '- `parseError(err)` global: message from an unknown caught value (handy in `catch`)',
-        '- `Server` global: the typed RPC surface generated from the server (see `server.md`)',
-        '- `Server.REST.<controller>.<route>(args)`: a working, typed `fetch` client for your',
-        '  `@rest` controllers, e.g. `await Server.REST.todos.getTodo({ params: { id } })` or',
-        '  `await Server.REST.todos.add({ body: new AddTodo("milk") })`. `args` is',
-        '  `{ params?, body?, query?, headers? }`; returns are typed (`@data` classes are parsed for',
-        '  you). The REST client attaches when you import from `shared/server`.',
-        '',
-        '## Head example',
-        '',
-        '    Toil.useHead({',
-        '        title: "Blog",',
-        '        titleTemplate: "%s, MyApp",',
-        '        meta: [{ name: "description", content: "..." }],',
-        '    });',
-    ]),
-    'styling.md': doc([
-        '# Styling',
-        '',
-        'The app imports one stylesheet from `client/toil.tsx` (e.g. `./styles/main.css`).',
-        '',
-        '## Preprocessors & Tailwind',
-        '',
-        'Pick a CSS preprocessor (none / Sass / Less / Stylus) and optionally Tailwind at',
-        '`toiljs create`, or change it later on an existing project:',
-        '',
-        '    toiljs configure                 # interactive',
-        '    toiljs configure --tailwind      # add Tailwind',
-        '    toiljs configure --style sass    # switch preprocessor',
-        '',
-        '`configure` installs/removes the right packages and rewrites the imports. Tailwind lives',
-        'in its own `styles/tailwind.css` (`@import "tailwindcss";`).',
-        '',
-        '## Imports',
-        '',
-        '`.css` / `.scss` / `.sass` / `.less` / `.styl` and image imports (`.svg`, `.png`, …) are',
-        'typed via `toil-env.d.ts`.',
-    ]),
-    'server.md': doc([
-        '# Server (toilscript → WebAssembly)',
-        '',
-        '`server/` is the toilscript source, compiled to WebAssembly by `toilscript`.',
-        '',
-        '- `server/main.ts`, the `@main` entry, exported as the WASM `main`.',
-        '- `server/index.ts`, your functions.',
-        '- `server/tsconfig.json`, extends `toilscript/std/assembly.json` (AssemblyScript/toilscript',
-        '  globals like `i32`, not the DOM), so editors resolve server types correctly.',
-        '- `npm run build:server` (or `npm run build`) emits `build/server/release.wasm` and',
-        '  regenerates `shared/server.ts` (the typed client RPC module).',
-        '',
-        '## Typed RPC (`@data` / `@remote` / `@service`)',
-        '',
-        'Tag server code and the build generates a typed client `Server` surface:',
-        '',
-        '- `@data class X {}`, a serializable struct. Generates a client class with the same fields',
-        '  plus `encode`/`decode`; construct it on the client: `import { X } from "shared/server"`.',
-        '- `@remote function f(a: T): R`, a client-callable endpoint, becomes `Server.f(a)`.',
-        '- `@service class S { @remote m(...) {} }`, namespaces methods: `Server.s.m(...)`.',
-        '',
-        'On the client, `Server` is a global (no import) and fully typed; every call is async',
-        '(`Promise<R>`). Inputs/outputs are scalars, arrays, or `@data` classes, both directions.',
-        '',
-        'Note: the client↔server transport is not wired yet, so calling a `Server` method throws',
-        'until it lands; the typed surface + codec are generated and ready.',
-        '',
-        '## HTTP REST (`@rest` / `@route`)',
-        '',
-        'Tag a class `@rest` and its methods with a verb to expose a real HTTP API. Unlike RPC,',
-        'the generated client is working `fetch` code (it is just HTTP).',
-        '',
-        '- `@rest("api") class Todos {}`, mounts the controller at `/api` (bare `@rest` → `/`).',
-        '- `@get("/todos/:id")` / `@post` / `@put` / `@del` / `@patch` / `@head` / `@options`, verb',
-        '  shortcuts; or `@route({ method: Methods.GET, path: "/todos", stream: DataStream.JSON })`.',
-        '- A method takes an optional `@data` body + an optional `ctx: RouteContext` (path params via',
-        '  `ctx.param("id")`, `ctx.query(...)`, `ctx.header(...)`). It returns either a `@data` type,',
-        '  which the compiler encodes per `stream` (`DataStream.JSON` default, or `DataStream.Binary`,',
-        '  lossless for large `u64`/bignum), or a `Response` for full control - custom status and',
-        '  headers, e.g. `Response.json(value.toJSON().toString()).setHeader("cache-control", "no-store")`',
-        '  or `Response.notFound()`. (The editor sees the compiler-injected `@data` `toJSON`/`encode`',
-        '  members via the toilscript plugin, so serializing into a `Response` is editor-clean.)',
-        '',
-        'Each `@rest` class self-registers; dispatch them from your handler - it composes, it never',
-        'takes over `handle()`:',
-        '',
-        '```ts',
-        'import { ToilHandler, Request, Response, Rest } from "toiljs/server/runtime";',
-        'export class App extends ToilHandler {',
-        '    public handle(req: Request): Response {',
-        '        const hit = Rest.dispatch(req); // try every @rest controller',
-        '        if (hit != null) return hit;',
-        '        return Response.notFound();     // your own logic / static fallback',
-        '    }',
-        '}',
-        '```',
-        '',
-        'For a REST-only project, `Server.handler = () => new RestHandler()` does the same with no',
-        'boilerplate. On the client: `Server.REST.todos.getTodo({ params: { id } })` (see client.md).',
-    ]),
-    'ssr.md': doc([
-        '# Server-side rendering (SSR)',
-        '',
-        'Opt a route into SSR with `export const ssr = true`. toiljs renders the page ONCE at build',
-        'time into a template with holes; at request time the server fills only the dynamic holes and',
-        'serves the page, then the browser hydrates it in place. The page is never re-rendered per',
-        'request, so an SSR route is served about as fast as a static file while still delivering real',
-        'first-paint HTML and SEO.',
-        '',
-        '## Marking the holes',
-        '',
-        'Wrap the dynamic bits of the page in hole markers from `toiljs/client`. They are transparent',
-        'in the browser (they just render their children); only the build and the server treat them',
-        'specially, so the same component is your normal client UI.',
-        '',
-        '- `<Hole id="name">{value}</Hole>`, a text hole (the value is HTML-escaped for you).',
-        '- `<RawHtml id="bio" html={s} />`, a raw-HTML block (you own sanitisation, like',
-        '  `dangerouslySetInnerHTML`).',
-        '- `<Repeat id="rows" each={items}>{(item) => <li>...</li>}</Repeat>`, a repeated region (a',
-        '  list); the row markup is captured once and stamped per item.',
-        '- `<Island>{...}</Island>`, a client-only escape hatch: empty in the server HTML, rendered',
-        '  after hydration (so it gets no first paint or SEO). Put router-hook-driven or otherwise',
-        '  non-server-safe bits here.',
-        '',
-        '    import { Hole, Repeat, RawHtml, useLoaderData } from "toiljs/client";',
-        '    export const ssr = true;',
-        '    export const loader = ({ params }: Toil.LoaderArgs) => loadProfile(params.name);',
-        '    export default function Profile() {',
-        '        const d = useLoaderData<typeof loader>();',
-        '        return (',
-        '            <main>',
-        '                <h1>@<Hole id="username">{d.username}</Hole></h1>',
-        '                <RawHtml id="bio" html={d.bioHtml} />',
-        '                <ul>',
-        '                    <Repeat id="posts" each={d.posts}>',
-        '                        {(p) => <li><Hole id="title">{p.title}</Hole></li>}',
-        '                    </Repeat>',
-        '                </ul>',
-        '            </main>',
-        '        );',
-        '    }',
-        '',
-        '## The server render',
-        '',
-        'For each SSR route the build emits a typed `Slot` enum and a coherence hash (a',
-        '`<route>.slots.ts` module). In the server you write a `render(req)` that fills each slot from',
-        'the request and data, using the `SlotValues` API, and register it with `Ssr`:',
-        '',
-        '```ts',
-        'import { Request, SlotValues, HtmlBuilder, Ssr } from "toiljs/server/runtime";',
-        'import { Slot, HASH } from "./profile.slots";',
-        '',
-        'function renderProfile(req: Request): SlotValues | null {',
-        '    if (!req.path.startsWith("/u/")) return null; // not this route',
-        '    const v = new SlotValues(HASH);',
-        '    v.setText(Slot.username, usernameFor(req));   // escaped',
-        '    v.setRaw(Slot.bio, bioHtml);                  // verbatim',
-        '    const rows = new HtmlBuilder();',
-        '    for (let i = 0; i < posts.length; i++) rows.raw("<li>").text(posts[i]).raw("</li>");',
-        '    v.setRepeat(Slot.posts, rows);                // stamped rows',
-        '    return v;',
-        '}',
-        'Ssr.register(renderProfile);',
-        '```',
-        '',
-        '`SlotValues`: `setText` (escaped), `setRaw` (verbatim), `setAttr` (attribute value),',
-        '`setRepeat` (a stamped `HtmlBuilder`), plus `setHeader` and `setStatus`. The hole values you',
-        'return are filled into the template and the page is served; the browser then hydrates against',
-        'the same data, so the markup matches with no client re-render.',
-        '',
-        '## Rules of thumb',
-        '',
-        '- An SSR route (and the layouts above it) must render under static markup. Use the hole',
-        '  markers and `useLoaderData`; move anything that needs router hooks or browser-only APIs into',
-        '  an `<Island>`. A route that cannot render this way is skipped at build (with a warning) and',
-        '  simply falls back to normal client rendering.',
-        '- Hole values are HTML-escaped exactly as React escapes them, so hydration is byte-for-byte',
-        "  clean. Keep a repeat row's structure the same across items (only the leaf hole values vary).",
-        '- Build output for an SSR route lands in `build/client/_ssr/` (the template + its manifest)',
-        '  alongside the generated `Slot` module; routes without `ssr = true` are unaffected.',
-    ]),
-    'cli.md': doc([
-        '# CLI',
-        '',
-        '- `toiljs create [name]`, scaffold a project. Flags: `--template app|minimal`,',
-        '  `--style css|sass|less|stylus`, `--tailwind`, `--no-ai`, `-y`/`--yes`.',
-        '- `toiljs dev`, dev server with HMR (`--port`, `--root`). With a `toilconfig.json` it builds',
-        '  the server first, then rebuilds it whenever a `server/` file changes (regenerating',
-        '  `shared/server.ts`, which Vite HMRs into the client); client-only edits just HMR the client.',
-        '- `toiljs build`, production build. With a `toilconfig.json` it builds the server (toilscript,',
-        '  regenerating `shared/server.ts`) first, then the client → `build/client`. `--server` builds',
-        '  only the server. Every `server/` file declaring a surface (`@data`/`@rest`/...) is compiled.',
-        '- `toiljs start`, self-host the built app (hyper-express) with a `/_toil` WebSocket channel.',
-        '- `toiljs configure`, toggle styling features on an existing project (see `styling.md`).',
-        '- `toiljs doctor`, diagnose project setup (`--json` for CI). `--fix` auto-wires the typed-RPC',
-        '  setup (build scripts, tsconfig `shared` + alias, `.gitignore`, toilscript version, and the',
-        '  toilscript prettier plugin) so an existing project upgrades in one command.',
-    ]),
-};
-
 /** Writes the framework docs into `<toilDir>/docs/`. Called by `generate` each dev/build. */
 export function writeDocs(toilDir: string): void {
     const dir = path.join(toilDir, 'docs');