toiljs 0.0.15 → 0.0.16

package/src/compiler/docs.ts

@@ -1,228 +1,228 @@
-/**
- * AI-assistant helper files. `toiljs create` writes a small pointer file for each tool at the
- * project root (committed, yours to edit); the real documentation lives under `.toil/docs/`,
- * regenerated on every `toiljs dev` / `toiljs build` so it stays in sync with the installed
- * toiljs version. The pointer files just tell the agent to read `.toil/docs/`.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-
-/** Shared body for the per-tool pointer files. */
-const POINTER_BODY = `# toiljs · AI assistant guide
-
-This is a **toiljs** project, a full-stack React framework (React + Vite client, file-based
-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/cli.md\`, toiljs CLI commands
-
-\`.toil/docs/\` is regenerated by toiljs; do not edit it by hand. This pointer file is yours to edit.
-`;
-
-/** A selectable AI coding-tool helper: its id, label, and the root pointer file(s) it scaffolds. */
-export interface AiHelper {
-    readonly id: string;
-    readonly label: string;
-    readonly files: Record<string, string>;
-}
-
-/**
- * Per-tool pointer files, individually selectable in `toiljs create`. Each tool reads its own
- * conventional file: Claude Code → CLAUDE.md, Codex / others → AGENTS.md, Cursor → .cursor/rules,
- * GitHub Copilot → .github/copilot-instructions.md. Written once by `create`; not regenerated.
- */
-export const AI_HELPERS: readonly AiHelper[] = [
-    { id: 'claude', label: 'Claude Code (CLAUDE.md)', files: { 'CLAUDE.md': POINTER_BODY } },
-    { id: 'codex', label: 'Codex / AGENTS.md', files: { 'AGENTS.md': POINTER_BODY } },
-    {
-        id: 'cursor',
-        label: 'Cursor (.cursor/rules)',
-        files: {
-            '.cursor/rules/toiljs.mdc': `---\ndescription: toiljs project conventions\nalwaysApply: true\n---\n\n${POINTER_BODY}`,
-        },
-    },
-    {
-        id: 'copilot',
-        label: 'GitHub Copilot (.github/copilot-instructions.md)',
-        files: { '.github/copilot-instructions.md': POINTER_BODY },
-    },
-];
-
-/** All AI helper ids (the default selection). */
-export const AI_HELPER_IDS: readonly string[] = AI_HELPERS.map((h) => h.id);
-
-/** Merges the pointer files for the given helper ids into one path → content map. */
-export function aiHelperFiles(ids: readonly string[]): Record<string, string> {
-    const out: Record<string, string> = {};
-    for (const helper of AI_HELPERS) {
-        if (ids.includes(helper.id)) Object.assign(out, helper.files);
-    }
-    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`.',
-        '- `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).',
-        '',
-        '## Key ideas',
-        '',
-        '- `Toil` is a native global (no import): `Toil.Link`, `Toil.useRouter`, `Toil.useLoaderData`,',
-        '  etc. The IO classes (`BinaryWriter`, `BinaryReader`, `FastMap`, `FastSet`) 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`, `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.',
-        '',
-        '## 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): `BinaryWriter`, `BinaryReader`, `FastMap`, `FastSet`',
-        '',
-        '## 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`.',
-        '',
-        'Note: the client↔server bridge (calling WASM exports from the client) is not wired yet.',
-    ]),
-    '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`).',
-        '- `toiljs build`, production build → `build/client` (chain `toilscript` for the server).',
-        '- `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`).',
-    ]),
-};
-
-/** 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');
-    fs.mkdirSync(dir, { recursive: true });
-    for (const [name, content] of Object.entries(TOIL_DOCS)) {
-        fs.writeFileSync(path.join(dir, name), content);
-    }
-}
+/**
+ * AI-assistant helper files. `toiljs create` writes a small pointer file for each tool at the
+ * project root (committed, yours to edit); the real documentation lives under `.toil/docs/`,
+ * regenerated on every `toiljs dev` / `toiljs build` so it stays in sync with the installed
+ * toiljs version. The pointer files just tell the agent to read `.toil/docs/`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Shared body for the per-tool pointer files. */
+const POINTER_BODY = `# toiljs · AI assistant guide
+
+This is a **toiljs** project, a full-stack React framework (React + Vite client, file-based
+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/cli.md\`, toiljs CLI commands
+
+\`.toil/docs/\` is regenerated by toiljs; do not edit it by hand. This pointer file is yours to edit.
+`;
+
+/** A selectable AI coding-tool helper: its id, label, and the root pointer file(s) it scaffolds. */
+export interface AiHelper {
+    readonly id: string;
+    readonly label: string;
+    readonly files: Record<string, string>;
+}
+
+/**
+ * Per-tool pointer files, individually selectable in `toiljs create`. Each tool reads its own
+ * conventional file: Claude Code → CLAUDE.md, Codex / others → AGENTS.md, Cursor → .cursor/rules,
+ * GitHub Copilot → .github/copilot-instructions.md. Written once by `create`; not regenerated.
+ */
+export const AI_HELPERS: readonly AiHelper[] = [
+    { id: 'claude', label: 'Claude Code (CLAUDE.md)', files: { 'CLAUDE.md': POINTER_BODY } },
+    { id: 'codex', label: 'Codex / AGENTS.md', files: { 'AGENTS.md': POINTER_BODY } },
+    {
+        id: 'cursor',
+        label: 'Cursor (.cursor/rules)',
+        files: {
+            '.cursor/rules/toiljs.mdc': `---\ndescription: toiljs project conventions\nalwaysApply: true\n---\n\n${POINTER_BODY}`,
+        },
+    },
+    {
+        id: 'copilot',
+        label: 'GitHub Copilot (.github/copilot-instructions.md)',
+        files: { '.github/copilot-instructions.md': POINTER_BODY },
+    },
+];
+
+/** All AI helper ids (the default selection). */
+export const AI_HELPER_IDS: readonly string[] = AI_HELPERS.map((h) => h.id);
+
+/** Merges the pointer files for the given helper ids into one path → content map. */
+export function aiHelperFiles(ids: readonly string[]): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const helper of AI_HELPERS) {
+        if (ids.includes(helper.id)) Object.assign(out, helper.files);
+    }
+    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`.',
+        '- `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).',
+        '',
+        '## Key ideas',
+        '',
+        '- `Toil` is a native global (no import): `Toil.Link`, `Toil.useRouter`, `Toil.useLoaderData`,',
+        '  etc. The IO classes (`BinaryWriter`, `BinaryReader`, `FastMap`, `FastSet`) 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`, `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.',
+        '',
+        '## 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): `BinaryWriter`, `BinaryReader`, `FastMap`, `FastSet`',
+        '',
+        '## 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`.',
+        '',
+        'Note: the client↔server bridge (calling WASM exports from the client) is not wired yet.',
+    ]),
+    '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`).',
+        '- `toiljs build`, production build → `build/client` (chain `toilscript` for the server).',
+        '- `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`).',
+    ]),
+};
+
+/** 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');
+    fs.mkdirSync(dir, { recursive: true });
+    for (const [name, content] of Object.entries(TOIL_DOCS)) {
+        fs.writeFileSync(path.join(dir, name), content);
+    }
+}