@webjsdev/mcp 0.1.17 → 0.1.19

package/resources/SKILL.md

@@ -1,286 +0,0 @@
----
-name: webjs
-description: Build and review WebJs applications. Use when working on WebJs app structure, pages, layouts, routes, server actions, components, signals, data and validation, auth, sessions, styling, the client router, streaming, or tests. WebJs is AI-first, web-components-first, and has no build step.
----
-
-# Build a WebJs App
-
-Use this skill for end-to-end WebJs app work. It helps you choose the right layer first, reach for the right export, and avoid the WebJs-specific mistakes that Next.js or Lit muscle memory causes. WebJs is its own framework: the component API matches Lit and the routing feels like Next, but the execution model is neither.
-
-## Full Documentation
-
-This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). To check ONE export's contract, run `npx webjs source <Export>` (for example `npx webjs source createAuth`, or `--pkg core` to narrow): it prints that export's signature and the doc comment above it from the installed package, so you read the declaration instead of the file. The MCP `source` tool does the same with `export`. Open the source file when the question is about behaviour the signature does not state. The complete hosted docs live at https://webjs.dev/docs.
-
-## What WebJs Is
-
-WebJs is an AI-first, web-components-first framework with **no build step**: source files are served as native ES modules, and TypeScript is stripped in place (Node 24+ or Bun). It runs SSR + progressive enhancement by default.
-
-**There is no server/client component split.** No RSC render tree, no Flight protocol, no `"use client"` boundary. Instead:
-
-- **Pages and layouts** (`app/**/page.ts`, `app/**/layout.ts`) run **only on the server** to produce HTML. They do NOT hydrate, so their own markup cannot be interactive (an `@click` in a page template is dropped at SSR). They still LOAD in the browser so imported components register.
-- **Components** (`WebComponent` custom elements) hydrate per element, islands-style. **All interactivity lives here**: `@event`, reactive property assignment, signal mutation.
-- **`*.server.ts`** is the one server boundary. With `'use server'` its exports are RPC-callable from the client (the import is rewritten to a stub); without it the file is a server-only utility whose browser import throws at load. This, not a component annotation, is how a dependency (the DB driver, secrets, `node:*`) is kept off the client.
-- **`route.ts`** is a server-only HTTP handler (named `GET`/`POST` exports), the one routing file that is NOT isomorphic.
-
-**Progressive enhancement is the default architecture.** With JS off, content reads, `<a>` navigates, and a `<form action=${importedAction}>` submits to its server action. JS is opt-in per interactive behaviour. Never write a first paint that depends on hydration.
-
-**Islands, and why their size is a decision.** A WebJs page is server-rendered HTML with small interactive components embedded in it, each hydrating on its own when the browser upgrades its tag. That is the islands model, and what makes it pay is that the sea is free: static markup a page renders costs the browser nothing, because a page never hydrates. So an island is not a unit of code organisation, it is a unit of shipped JavaScript, and it should wrap the interactive part and stop. Absorbing a page's static markup into a component to keep things tidy converts free HTML into shipped JavaScript, and it takes every display-only child down with it, because a component rendered by a component that ships can no longer be elided. Size the island to the behaviour, not to the section of the design it happens to sit in. `references/components.md` has the stopping rule and a worked before/after.
-
-## When To Use This Skill
-
-- New features or refactors touching pages, routes, actions, components, data, auth, sessions, styling, or tests
-- Reviewing WebJs code for correctness or framework usage
-- Answering "how should this be structured in WebJs?"
-- Finding the right export, reference doc, or default pattern for a task
-
-## Reach For The Right Primitive
-
-Scan this BEFORE deciding how to build something, while the shape of the code is still open. WebJs ships a primitive for most of the jobs below, and the mistake to guard against is rarely choosing badly between them. It is that the primitive never comes to mind at all, so the React-shaped version gets hand-rolled in its place. That version compiles, passes `webjs check`, and ships, so nothing catches it. The "reflex to resist" column is what the hand-rolled version usually looks like.
-
-Rows point rather than explain. The reference is the authority on the rule, and it is the durable half: the demo lives in the scaffold gallery, which an app deletes with `npm run gallery:clear` once it has outgrown it.
-
-| I need to... | Reach for | Reflex to resist | Reference | Demo |
-| --- | --- | --- | --- | --- |
-| add a URL, static or with a dynamic segment | a file at `app/<path>/page.ts`, `[id]` for a param | registering the route in a table or config | `references/routing-and-pages.md` | `app/features/routing` |
-| abandon a render because something is missing or not allowed | throw `notFound()` / `forbidden()` / `unauthorized()` | returning an error object and branching in the template | `references/routing-and-pages.md` | `app/features/boundaries` |
-| set a page's title, description, or social preview | `export const metadata` or `generateMetadata()` | writing `<head>` tags in the page | `references/routing-and-pages.md` | `app/features/metadata` |
-| make part of the page respond to a click or hold state | a `WebComponent` custom element | expecting the page's own markup to hydrate | `references/components.md` | `app/features/components` |
-| render a keyed list, or swap one node when state changes | `repeat()` / `watch()` from `/directives` | re-rendering the component or diffing by hand | `references/components.md` | `app/features/directives` |
-| get server data into a component's first paint | `async render()` awaiting an action | fetching in `connectedCallback`, which SSR never calls | `references/components.md` | `app/features/async-render` |
-| call server code from the browser | import the `'use server'` function and call it | hand-writing `fetch()` against an endpoint | `references/data-and-actions.md` | `app/features/server-actions` |
-| expose JSON to a caller outside the app | `route.ts` with named `GET` / `POST` exports | a server action, which is the in-app path | `references/routing-and-pages.md` | `app/features/route-handler` |
-| write data from a form, JS off included | `<form action=${importedAction}>` | an `@submit` handler calling `fetch()` | `references/data-and-actions.md` | `app/features/forms` |
-| make a mutation feel instant | `optimistic()` | a manual try-catch that restores a cached copy | `references/optimistic-ui.md` | `app/features/optimistic-ui` |
-| navigate without a full page reload | nothing, the router is already on | importing or configuring a router | `references/client-router-and-streaming.md` | `app/features/client-router` |
-| cross-fade a navigation instead of snapping | the `view-transition` meta, via page metadata | animating the swap yourself | `references/client-router-and-streaming.md` | `app/features/view-transitions` |
-| show tokens or progress as the server produces them | an action returning an async generator | polling, or a socket for a one-shot answer | `references/client-router-and-streaming.md` | `app/features/streaming` |
-| change ONE element after a write | `<webjs-stream>` | redrawing the whole list around it | `references/client-router-and-streaming.md` | `app/features/stream` |
-| paint the page before a slow region is ready | `<webjs-suspense>` with a fallback | blocking the whole page on the slow await | `references/client-router-and-streaming.md` | `app/features/suspense` |
-| refresh one region on its own, with no navigation | `<webjs-frame>` | a stateful component that fetches and re-renders | `references/client-router-and-streaming.md` | `app/features/frames` |
-| hold a live two-way connection | a `WS()` route export plus `connectWS()` | polling on an interval | `references/client-router-and-streaming.md` | `app/features/websockets` |
-| push one update to every client on a socket path | `broadcast()` | every client polling for changes | `references/client-router-and-streaming.md` | `app/features/broadcast` |
-| add login and a signed-in-only route | `createAuth` plus a redirect in the page | rolling password hashing and session cookies | `references/auth-and-sessions.md` | `app/features/auth` |
-| remember something per visitor across requests | `getSession()` on a signed cookie | a module-level map keyed by user | `references/auth-and-sessions.md` | `app/features/sessions` |
-| stop re-rendering a page identical for everyone | `export const revalidate` | caching by hand in a module variable | `references/built-ins.md` | `app/features/caching` |
-| read config or a secret at runtime | `process.env` server-side, `WEBJS_PUBLIC_` for the browser | importing a config module into a component | `references/built-ins.md` | `app/features/env` |
-| stop one caller hammering an endpoint | the `rateLimit()` middleware | counting requests inside the handler | `references/built-ins.md` | `app/features/rate-limit` |
-| accept an upload and serve it back | `FileStore` plus a streaming route | buffering the file in memory or writing to `public/` | `references/built-ins.md` | `app/features/file-storage` |
-| keep the app usable offline | the opt-in service worker | caching responses in `localStorage` | `references/service-worker.md` | `app/features/service-worker` |
-| see these composed in one real feature | the todo example app | stitching the single-feature demos together | `references/optimistic-ui.md` | `app/examples/todo` |
-
-## Load Only The References You Need
-
-The table above routes by the job; this one routes by the topic, for when you already know which surface you are working on. Classify the task first, then load the smallest useful reference set. Each reference starts with a "What This Covers" section; read that to confirm relevance before reading the rest. Loading more than two or three at once usually means the task is not narrowed yet.
-
-| Task involves...                                                            | Start with                                    |
-| --------------------------------------------------------------------------- | --------------------------------------------- |
-| Pages, layouts, dynamic routes, route handlers, metadata, redirects, 404s   | `references/routing-and-pages.md`             |
-| Writing components: what a component owns, reactive props, signals, lifecycle, light vs shadow DOM  | `references/components.md`                     |
-| Why a component's JS was or was not downloaded, `webjs elision`, `static interactive = true` | `references/components.md`                     |
-| Server actions, mutations, queries, validation, the `ActionResult` envelope | `references/data-and-actions.md`              |
-| Sessions, login flows, route protection, `forbidden()` / `unauthorized()`   | `references/auth-and-sessions.md`             |
-| Tailwind, light-DOM tag-prefix rule, tokens, fixed headers, no-reflow layout | `references/styling.md`                        |
-| Where a repeated markup helper lives (`utils/ui/` vs `lib/`), and fragment vs display-only component | `references/styling.md`                        |
-| Client router, prefetch, frames, view transitions, Suspense streaming        | `references/client-router-and-streaming.md`   |
-| Optimistic UI for a user-facing mutation                                     | `references/optimistic-ui.md`                 |
-| The `@webjsdev/ui` component kit (a `components.json` is present): class helpers, tokens, `add` / `view`, the MCP `ui` tool | `references/ui-kit.md`                         |
-| TypeScript at runtime, erasable syntax, full-stack types, the derive-the-type rule (never `unknown` / `any`) | `references/typescript.md`                     |
-| Unit, browser, e2e tests, the `handle()` harness, Bun parity                 | `references/testing.md`                        |
-| Auth, caching, env vars, rate limit, file storage, the `webjs` config block  | `references/built-ins.md`                      |
-| Node vs Bun, running the app, deploying, runtime-specific differences        | `references/runtime.md`                        |
-| Offline support, an asset cache, the opt-in service worker                   | `references/service-worker.md`                 |
-| Splitting a large file, or how big a module may be                            | `references/module-structure.md`              |
-| A pattern that feels like Next.js or Lit but might not transfer              | `references/muscle-memory-gotchas.md`         |
-
-Common bundles:
-
-- **Form or CRUD feature** then data-and-actions, routing-and-pages, testing; add auth if user-specific
-- **Interactive widget** then components, styling; add client-router-and-streaming only if it streams
-- **Protected area** then auth-and-sessions, routing-and-pages, testing
-- **Instant-feeling mutation** then data-and-actions, optimistic-ui
-
-## Default Workflow
-
-1. **Classify the change.** Route contract, data model, server mutation, auth, or only UI?
-2. **Start from the server.** Add the page/route and its server action or query before wiring interactive UI. A page render or a `<form>` POST should already return correct HTML before any component hydrates.
-3. **Put code in the narrowest owner.** Route-local first (`modules/<feature>/`), promote to `lib/` or `components/` only when reuse is real.
-4. **Keep server-only code behind `.server.ts`** (Core WebJs Rules 1 and 2).
-5. **Add interactivity per behaviour.** Reach for a component (and a signal or `@event`) only where the UI is genuinely interactive. A display-only component is elided from the browser. Then wrap the interactive part and STOP: the static markup around it stays in the page, where it costs nothing.
-6. **Validate input at the boundary.** Declare `export const validate` on an action; the RPC and `route()` boundaries run it.
-7. **Default mutations to optimistic UI** where the client can predict the result (`optimistic()` from `@webjsdev/core`).
-8. **Type every boundary from its source, never `unknown` or `any`.** The row type comes from the schema (`typeof todos.$inferSelect`), the action's input from a named `interface` and its result from `ActionResult<T>`, the routing files from `PageProps` / `LayoutProps` / `RouteHandlerContext`. `unknown` belongs on a payload nothing has vouched for yet that the next line narrows, and on a parameter of your own helper that forwards into an `html` template hole. Everywhere else, including a layout's `children`, it is a missing type. Carry a row type into a shipping component with `import type` (erased before the browser sees it). Nothing enforces this (both spellings are valid TypeScript, so `webjs check` and `tsc` pass either way), which is why it is written down. See `references/typescript.md`.
-9. **Test the narrowest meaningful layer**, and look at any UI change in a real browser (see Testing Defaults).
-
-## Project Layout
-
-```
-app/                  ROUTING ONLY (thin adapters importing from modules/)
-  layout.ts           root layout (the ONLY file that may write <html>/<head>/<body>)
-  page.ts             /
-  <segment>/page.ts   /<segment>
-  [param]/page.ts     dynamic route (params.param)
-  <path>/route.ts     HTTP handler at /<path>
-  error.ts loading.ts not-found.ts forbidden.ts unauthorized.ts   boundaries (nearest wins)
-middleware.ts         root middleware
-modules/<feature>/    actions/ (mutations, *.server.ts), queries/ (reads, *.server.ts),
-                      components/ (custom elements), types.ts,
-                      utils/ (pure; returns data, or an html fragment under utils/ui/)
-lib/                  lib/*.server.ts server-only infra, lib/utils/ browser-safe helpers,
-                      lib/utils/ui.ts app-wide html fragments (lib/ui/ once they grow)
-components/*.ts        shared presentational custom elements (one per file)
-db/*.server.ts        Drizzle: schema, connection
-public/*              static assets, served at /public/<name>
-```
-
-App-internal imports use the `#` root alias (`import { db } from '#db/connection.server.ts'`), Node's native `package.json` imports field, not deep `../../../` relatives. A same-directory import stays relative.
-
-## Core WebJs Rules (invariants)
-
-1. Server-only code lives in `.server.ts`, `route.ts`, or `middleware.ts`. Never in a page, layout, or component (it crashes the browser at module load).
-2. `'use server'` exports are `async` functions returning serializer-safe values, callable from browser code as RPC. Files without `'use server'` are server-only utilities: reach them only from `'use server'` actions, `route.ts`, or middleware. Never add `'use server'` to a file only other server code imports (the DB connection, the schema).
-3. Custom element tag names contain a hyphen. Pass the tag to `Class.register('tag-name')`.
-4. Event (`@`), property (`.`), and boolean (`?`) holes in `html` are UNQUOTED: `@click=${fn}`, never `@click="${fn}"`.
-5. Signals are the default state primitive. Import `signal` / `computed` from `@webjsdev/core`, read via `signal.get()` inside `render()`. The base-class factory `WebComponent({ ... })` is only for values riding an HTML attribute or arriving via SSR hydration.
-6. Page and layout default exports are functions returning a value; they never call `render()` themselves.
-7. Light-DOM components with custom CSS prefix every class selector with their tag name. Prefer Tailwind (unique by construction).
-8. Only the root layout may write `<!doctype>` / `<html>` / `<head>` / `<body>`.
-9. No backtick characters inside an `html\`...\`` body, even in comments (it closes the literal and 500s).
-10. TypeScript must be erasable (`erasableSyntaxOnly: true`): no `enum`, no value `namespace`, no constructor parameter properties, no legacy decorators.
-11. Reactive properties are declared ONLY through the base-class factory `extends WebComponent({ count: Number })`. Never a `static properties` block, never a class-field initializer (it clobbers the reactive accessor).
-12. A form that writes binds its action: `<form action=${importedAction}>`, or a per-button `<button formaction=${importedAction}>`. A bound submitter is SELF-SUFFICIENT (#1307): the renderer puts `formmethod="post"` and `formenctype` on the button itself, so it needs no bound form around it and works inside any form or none. Quoted bindings, non-submit controls, `<input type="submit">` (the identity needs its `value`, which is also its label, so use a `<button>`), submitter `name` / `value` / `form` / static `formaction` attributes (the identity IS the button's name/value pair, so both halves are spoken for), a `.prop` spelling of any of those, `action=${fn}` off a `<form>`, a bound form with `method="get"` (a GET sends no body for the action to read), a BOUND submitter's own non-post `formmethod` or unparseable `formenctype`, and a non-action function all throw. A PLAIN button's own `formmethod` / `formenctype` is a legal native override and is left alone. A page has no `action` export, so a bare `<form method="post">` is a 405.
-
-## Export Map
-
-Find the right export fast. Load the linked reference for full examples.
-
-### `@webjsdev/core` (browser + isomorphic)
-
-- `html` / `css` tagged templates. `WebComponent({ ... })` base-class factory; `prop(type?, opts?)` declares one reactive property. `Class.register('tag')` binds the tag.
-- `signal` / `computed` reactive state, `effect(fn)` client-only reaction (returns a disposer), `batch(fn)` coalesced writes; `render(v, el)` client render.
-- `notFound()` / `redirect(url[, status])` control-flow throws (page/layout/action only, NOT `route.ts`). `forbidden()` / `unauthorized()` render the nearest boundary.
-- `Suspense({fallback, children})` page-level streaming; `<webjs-suspense>` component-level streaming.
-- `optimistic()` optimistic UI; `navigate(url)` / `revalidate(url?)` client-router control; `connectWS` / `richFetch`.
-- `asset(path)` content-hashes a `public/` url so a deploy cannot serve stale bytes (`href=${asset('/public/app.css')}`), served `immutable` for a year. Page / layout / metadata route only, inside the render function. See `references/built-ins.md`.
-- Types: `Metadata`, `PageProps<R>`, `LayoutProps<R>`, `RouteHandlerContext<R>`, `WebjsConfig`.
-- `@webjsdev/core/server`: `renderToString` / `renderToStream` (Node side).
-- `@webjsdev/core/directives`: `repeat`, `unsafeHTML` (trusted only), `live`, `keyed`, `guard`, `cache`, `until`, `watch(signal)`, `ref` / `createRef`, `asyncAppend` / `asyncReplace`, `templateContent`. `Task` / `TaskStatus` live at `@webjsdev/core/task`, context (`createContext` / `ContextProvider` / `ContextConsumer`) at `/context`. See `references/components.md` for the directive table + Task + context.
-
-### `@webjsdev/server` (server side)
-
-- `createRequestHandler`, `cors()`, `route(action, opts?)` REST adapter, `sitemap()` / `sitemapIndex()`, `actionContext()`, `actionSignal()`, `requestId()`, `cache()` / `revalidateTag`.
-- Route-handler toolkit: `json(v)` rich responder, `readBody(req)`, `clientIp(req)`, no-arg `headers()` / `cookies()` / `cspNonce()` (client counterpart `richFetch` is in `@webjsdev/core`). See `references/routing-and-pages.md`.
-- Auth + sessions: `createAuth` (+ `Credentials` / `Google` / `GitHub`), `auth()` / `auth(req)`, `session()` + `cookieSession` / `storeSession`, `getSession(req)` (`.get` / `.set` / `.flash` / `.destroy`). File storage: `getFileStore` / `diskStore` / `signedUrl`. See `references/auth-and-sessions.md` + `references/built-ins.md`.
-- Data layer is Drizzle in `db/*.server.ts`. Auth, sessions, caching, rate limit, file storage are built in and pluggable (`references/built-ins.md`).
-
-### File conventions
-
-`page.ts` (server-only fn), `layout.ts` (embeds `children`), `route.ts` (HTTP handler), `middleware.ts`, `*.server.ts` (server boundary), `error.ts` / `loading.ts` / `not-found.ts` / `forbidden.ts` / `unauthorized.ts` (boundaries), metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `opengraph-image.ts`), and the static app-root icon files (`icon.svg`, `apple-icon.png`, `manifest.webmanifest`, `favicon.ico`), auto-linked into `<head>`. The scaffold's `app/icon.svg` is a placeholder: replace it with the app's own icon.
-
-## Canonical Patterns
-
-### A page
-
-```ts
-// app/about/page.ts
-import { html } from '@webjsdev/core';
-export default function About() {
-  return html`<h1>About</h1>`;
-}
-```
-
-### A dynamic route reading data through an action
-
-```ts
-// app/users/[id]/page.ts
-import { html } from '@webjsdev/core';
-import { getUser } from '#modules/users/queries/get-user.server.ts';
-export default async function User({ params }: { params: { id: string } }) {
-  const user = await getUser(params.id); // never import the DB directly into a page
-  return html`<h1>${user.name}</h1>`;
-}
-```
-
-### A server action
-
-```ts
-// modules/users/actions/update-profile.server.ts
-'use server';
-import { eq } from 'drizzle-orm';
-import { db } from '#db/connection.server.ts';
-import { users } from '#db/schema.server.ts';
-export async function updateProfile(input: { id: string; name: string }) {
-  const name = String(input?.name || '').trim();
-  if (!name) return { success: false, error: 'name required', status: 400 };
-  const [row] = await db.update(users).set({ name }).where(eq(users.id, input.id)).returning();
-  return { success: true, data: row };
-}
-```
-
-Call it from a component via a normal import (rewritten to a typed RPC stub). Never hand-write `fetch()`.
-
-### An interactive component
-
-```ts
-// components/counter.ts
-import { WebComponent, prop, html } from '@webjsdev/core';
-class Counter extends WebComponent({ count: prop(Number) }) {
-  constructor() { super(); this.count = 0; }
-  render() {
-    return html`<button @click=${() => this.count++}>${this.count}</button>`;
-  }
-}
-Counter.register('my-counter');
-```
-
-### The no-JS write path (a form-bound action)
-
-```ts
-// modules/contact/actions/send-message.server.ts
-'use server';
-export async function sendMessage(formData: FormData) {
-  const email = String(formData.get('email') || '');
-  if (!email) return { success: false, fieldErrors: { email: 'required' } };
-  return { success: true, redirect: '/thanks' };
-}
-
-// app/contact/page.ts
-import { sendMessage } from '#modules/contact/actions/send-message.server.ts';
-export default function Contact({ actionData }) {
-  return html`<form action=${sendMessage}><input name="email"></form>`;
-}
-```
-
-Binding the action is the whole wiring: the renderer omits `action` (so the form posts to the page's own url), supplies `method="post"` and an enctype, and emits a hidden `__webjs_action` identity field. A form-bound action always receives the `FormData`.
-
-Success is a 303 (PRG); failure re-renders the page at 422 with the result on `actionData`. With JS the client router applies the response in place. A submission that binds nothing is a 405, and the submission is Origin-verified like an RPC call.
-
-## Security And Session Defaults
-
-- Never ship demo secrets. Require session and provider secrets from the environment and fail fast if missing.
-- CSRF is an Origin / `Sec-Fetch-Site` check on both the action RPC and the form-submit path, not a token cookie. A safe GET action is CSRF-exempt. A `route.ts` REST endpoint is NOT covered: authenticate every mutating endpoint, validate, rate-limit.
-- Prod action errors are sanitized to a generic message plus a digest. Put a user-facing message on the `ActionResult` `{ success: false, error }` envelope, never on a raw throw.
-- Use `forbidden()` for an authenticated user lacking permission, `unauthorized()` for an unauthenticated request. Inside a `'use server'` RPC action, return an `ActionResult` for an auth failure instead of throwing.
-- For CORS use `cors()` from `@webjsdev/server`; `credentials: true` REQUIRES an explicit origin allowlist, never `'*'`.
-
-## Testing Defaults
-
-- `npm run ci` before every push: it runs the `webjs.ci` step list in `package.json` (correctness, project health, types, a dependency audit, then the server, browser, and e2e test layers) with a result line per step, and CI runs the same list, so a green local run predicts the pipeline. `npm run ci -- --only Tests` runs one layer while iterating. See `references/testing.md` and `references/built-ins.md`.
-- Prefer server/handler tests first: drive the app with `handle()` from `@webjsdev/server/testing` and assert on the `Response`.
-- Add a browser test (`npm run test:browser`) for anything touching hydration, the client router, slots, or custom-element upgrade. A unit test is necessary but NOT sufficient for a browser-facing change.
-- Render the app and LOOK for any UI change: `npm run check` and `npm run typecheck` pass even when a layout collapses. Static tools give no signal for a visual defect.
-- WebJs runs on Node 24+ AND Bun. Prove a runtime-sensitive change (serializer, listener, streams, `node:crypto`, the TS stripper) on both.
-
-## Common Mistakes To Avoid
-
-The invariants above are not repeated here; this list is the mistakes they do not already name.
-
-- Promoting a whole page section to a component so that one control inside it can be interactive. The island should wrap the control and the state it reads. An oversized island ships its own JS AND un-elides every display-only component inside it, so the cost is not linear in what you moved.
-- Writing `fetch()` to call your own server instead of importing the action.
-- Binding an action whose file declares `export const method = 'GET'`. Form-bound actions strictly require POST (default). Binding a GET action to a form is a 405 at runtime and a `webjs check` error (`form-action-not-a-get-action`).
-- Leaving read-only RPC server query actions as default `POST`. Always export `export const method = 'GET'` for RPC data queries so arguments ride URL params, ETags/304 caching work, and CSRF is safely bypassed.
-- Throwing `redirect()` / `notFound()` inside a `route.ts` handler (uncaught 500). Return a `Response` there.
-- A placeholder first paint that fetches in `connectedCallback`. SSR does not call `connectedCallback`; put first-paint data in the constructor (server-known inputs) or use `async render()`.
-- A browser global (`window`, `document`, `localStorage`) in the constructor or `render()`. It throws at SSR; do browser-only work in `connectedCallback`.
-- Interpolating into a component's `<style>` / `<script>` body. Use `static styles` or Tailwind.
-- Driving a component's markup from a delegated `document` listener in a page or layout, coupled by a class selector. The markup, the state, and the listener belong in one component.
-- Parking one component's UI state on `<body>` or `<html>`. The router's swap range never covers the document shell, so the flag outlives the markup it described. A document-wide SETTING such as the theme is the exception, and a transient effect such as a scroll lock is released in `disconnectedCallback`.

package/resources/corpus.json

@@ -1,6 +0,0 @@
-{
-  "package": "@webjsdev/mcp",
-  "version": "0.1.17",
-  "sha": "790ec039cd43b89c94ec9322a361d3c856641730",
-  "copiedAt": "2026-10-08T17:33:42.702Z"
-}

package/resources/references/auth-and-sessions.md

@@ -1,300 +0,0 @@
-# Auth and Sessions
-
-## What This Covers
-
-- Sessions: the `session()` middleware + storage factories (`cookieSession` / `storeSession`), the `getSession(req)` method API (`.get` / `.set` / `.flash` / `.destroy`), the `SESSION_SECRET` requirement
-- Authentication: `createAuth` (NextAuth-style), Credentials plus OAuth providers, `auth()` in a page or action, scrypt password hashing
-- Login and logout flows: mounting `handlers` at `app/api/auth/[...path]`, the no-JS credentials form (`/api/auth/signin/credentials` + `redirectTo` + `?error`), `signIn` / `signOut`
-- Protecting a route: a page-top `auth()` gate OR a per-segment `middleware.ts` calling `auth(req)`
-- `forbidden()` (403) vs `unauthorized()` (401) and their nearest-wins boundary files
-- Returning an `ActionResult` for an auth failure inside a `'use server'` action (do NOT throw there)
-- The Origin / `Sec-Fetch-Site` CSRF model (not a token cookie)
-- Requiring secrets from the environment and failing fast
-- `cors()` with an explicit allowlist when `credentials: true`
-
-Read this when a task touches login, logout, who-can-see-a-page, session
-state, or the CSRF / CORS posture of a mutation. Sibling refs:
-`data-and-actions.md` (the `ActionResult` envelope, validation, the RPC
-boundary), `routing-and-pages.md` (the `forbidden.ts` / `unauthorized.ts`
-boundary files and control-flow throws), `built-ins.md` (env vars, Redis
-scaling, the full caching surface).
-
-## Sessions
-
-Enable sessions with `session()` MIDDLEWARE, then read and write them with `getSession(req)` in any route or middleware the session wraps.
-
-```ts
-// middleware.ts: enable on all routes. Storage is pluggable.
-import { session, cookieSession, storeSession } from '@webjsdev/server';
-export default session({ secret: process.env.SESSION_SECRET, storage: cookieSession() });
-// cookieSession()  -> whole session in a signed cookie (stateless, the default)
-// storeSession()   -> session in the active store (memoryStore in dev, Redis in prod), id in the cookie
-```
-
-`getSession(req)` returns a small key/value `Session` with a METHOD API, not property assignment. Mutating it makes the middleware re-sign and set the cookie on the way out:
-
-```ts
-import { getSession } from '@webjsdev/server';
-export async function GET(req: Request) {
-  const s = getSession(req);
-  s.set('userId', user.id);            // write
-  const id = s.get('userId');          // read
-  s.flash('notice', 'Saved');          // one-read-only value (cleared after the next read)
-  s.destroy();                         // clear the whole session (logout)
-}
-```
-
-Cookie sessions (the default) are signed with no server state; store sessions keep only the id in the cookie and the data in the store. `cookieSession` / `storeSession` are aliases for `cookieSessionStorage` / `storeSessionStorage`. Both strategies require `SESSION_SECRET`, read from the environment (never a literal in source) so boot fails if it is missing.
-
-## Authentication (`createAuth`)
-
-Configure providers once in a `.server.ts` file. `createAuth` returns
-`auth` (read the session), `signIn` / `signOut` (the flows), and
-`handlers` (the OAuth redirect endpoints).
-
-```ts
-// modules/auth/auth.server.ts
-import { createAuth, Credentials, Google, GitHub } from '@webjsdev/server';
-import { db } from '#db/connection.server.ts';
-import { compare } from './password.server.ts';
-
-export const { auth, signIn, signOut, handlers } = createAuth({
-  providers: [
-    Credentials({
-      async authorize(credentials) {
-        const user = await db.query.users.findFirst({ where: { email: credentials.email } });
-        if (!user || !(await compare(credentials.password, user.passwordHash))) return null;
-        return { id: user.id, name: user.name, email: user.email, role: user.role };
-      },
-    }),
-    Google(),   // reads AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET
-    GitHub(),   // reads AUTH_GITHUB_ID, AUTH_GITHUB_SECRET
-  ],
-  secret: process.env.AUTH_SECRET,   // required, 32+ random chars, from the env
-  pages: { error: '/login' },        // a failed sign-in 302s here with ?error=<code>
-});
-```
-
-**Password hashing is the app's job** (WebJs ships no `verifyPassword`). Use `scrypt` from `node:crypto` (built into Node AND Bun, no dependency) in a server-only utility, and call it from `authorize`:
-
-```ts
-// modules/auth/password.server.ts (a server-only utility, never reaches the browser)
-import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto';
-import { promisify } from 'node:util';
-const scryptAsync = promisify(scrypt);
-export async function hash(pw: string) {
-  const salt = randomBytes(16).toString('hex');
-  return salt + ':' + ((await scryptAsync(pw, salt, 64)) as Buffer).toString('hex');
-}
-export async function compare(pw: string, stored: string) {
-  const [salt, key] = stored.split(':');
-  return timingSafeEqual((await scryptAsync(pw, salt, 64)) as Buffer, Buffer.from(key, 'hex'));
-}
-```
-
-**Mount `handlers` at an `app/api/auth/[...path]/route.ts` catch-all** (at the app root, NOT under a feature folder): `createAuth` hardcodes `/api/auth/signin/*` and `/api/auth/callback/*` for its form posts and OAuth callback URIs.
-
-```ts
-// app/api/auth/[...path]/route.ts
-import { handlers } from '#modules/auth/auth.server.ts';
-export const GET = handlers.GET;
-export const POST = handlers.POST;
-```
-
-**Cookie names.** `createAuth` sets `webjs.auth` (session) and, for OAuth, `webjs.auth.state` and `webjs.auth.redirect` in development. In production (`NODE_ENV=production`) each carries the `__Host-` prefix (`__Host-webjs.auth`, ...), which a browser stores only when `Secure`, `Path=/` and without `Domain`, so an app on a sibling subdomain cannot toss its own session cookie into yours. Production reads only the prefixed names; a test or tool that hand-sets the cookie in production must use the prefixed name.
-
-**The no-JS sign-in / sign-out flow is plain forms** (progressive-enhancement-safe). Sign in by POSTing to `/api/auth/signin/credentials` with a hidden `redirectTo`, and read `?error` (mapped from `pages.error`) for feedback; sign out by POSTing to `/api/auth/signout`:
-
-```html
-<form method="POST" action="/api/auth/signin/credentials">
-  <input type="hidden" name="redirectTo" value="/dashboard">
-  <input name="email" type="email" required><input name="password" type="password" required>
-  <button>Sign in</button>
-</form>
-<!-- log out -->
-<form method="POST" action="/api/auth/signout"><button>Log out</button></form>
-```
-
-**OAuth sign-in returns the user where they started, with the same one form.** POST to `/api/auth/signin/github` (or `google`) with a hidden `redirectTo`, or link to `GET /api/auth/signin/github?redirectTo=/dashboard/x`; `signIn('github', undefined, { redirectTo })` does the same from an action. The target rides through the provider round trip in a short-lived signed cookie and the callback lands on it, so no wrapper around the auth route is needed:
-
-```html
-<form method="POST" action="/api/auth/signin/github">
-  <input type="hidden" name="redirectTo" value="/dashboard/x">
-  <button>Sign in with GitHub</button>
-</form>
-```
-
-A `redirectTo` that arrives from a request (a form field or a query param, for OAuth or credentials) must be a same-origin local path: one leading `/`, not followed by `/` or `\`. An absolute URL, a protocol-relative `//host`, or a backslash variant is dropped (not repaired) and the sign-in lands on `/`, so the field is never an open redirect. A denied sign-in still goes to `pages.error`.
-
-For a programmatic sign-in (the auto-login-after-signup pattern), `signIn('credentials', creds, { redirectTo })` returns a `302` `Response` that a form-bound action can return directly (the framework honors a returned `Response` verbatim).
-
-**The header updates on its own after sign-in and sign-out.** A layout that reads `auth()` to render "Sign in" / "Sign out" is re-rendered after any mutating form submission the router handles (a form bound to a sign-in action, or a plain POST to `/api/auth/signin/credentials` / `/api/auth/signout`), and its markup is morphed in place, so there is nothing to refresh by hand (#1557). Only a sign-out done over RPC from a component (`await logout(); navigate('/')`) needs `await refreshPage('shell')` after it, since that navigation is a plain GET.
-
-Sessions are JWT by default (stateless, scales horizontally). OAuth
-providers handle the full redirect flow. Read the session anywhere on the
-server with `auth()`.
-
-```ts
-// in a page or action
-import { redirect } from '@webjsdev/core';
-const session = await auth();
-if (!session) throw redirect('/login');   // page-render gate: 302
-```
-
-`auth()` resolves `{ user }`, where `user` is `Record<string, unknown>` by
-default. To read custom fields (`session.user.id`, `session.user.role`)
-without a cast, type the session by augmenting the `AuthUser` interface
-(types-only, opt-in). See `typescript.md`.
-
-## Required secrets, fail fast
-
-| Variable | Effect |
-|---|---|
-| `AUTH_SECRET` | Required for auth JWT signing (32+ random chars) |
-| `AUTH_GOOGLE_ID` / `AUTH_GOOGLE_SECRET` | Google OAuth (optional) |
-| `AUTH_GITHUB_ID` / `AUTH_GITHUB_SECRET` | GitHub OAuth (optional) |
-| `SESSION_SECRET` | Cookie session signing |
-| `REDIS_URL` | When set, sessions and rate limit and cache use Redis |
-
-Never ship a demo secret or an in-source default. Read each secret from
-`process.env` and fail boot when a required one is absent (use the
-optional `env.ts` schema file to validate at boot and name every bad var).
-A guessable signing secret means forgeable sessions.
-
-## Protecting a route
-
-Gate at the top of the page or layout that owns the protected subtree.
-Because a page runs only on the server, the check happens before any HTML
-is produced, so a logged-out visitor never receives protected markup.
-
-```ts
-// app/dashboard/page.ts
-import { html, redirect } from '@webjsdev/core';
-import { auth } from '#modules/auth/auth.server.ts';
-
-export default async function Dashboard() {
-  const session = await auth();
-  if (!session) throw redirect('/login');   // not signed in
-  return html`<h1>Welcome, ${session.user.name}</h1>`;
-}
-```
-
-Reading the session through `auth()` also auto-excludes the page from the
-server HTML response cache, so a per-user page is never cached and served
-to another visitor (see `built-ins.md`).
-
-To gate a WHOLE subtree in one place, use a per-segment `middleware.ts` that reads `auth(req)` (the explicit-request form) and returns a `302` BEFORE the page renders. It runs for every request under its segment and needs only a cookie read (no DB query), so the gate is real the moment the app boots:
-
-```ts
-// app/dashboard/middleware.ts  (protects /dashboard/*)
-import { auth } from '#modules/auth/auth.server.ts';
-export default async function requireAuth(req: Request, next: () => Promise<Response>) {
-  const session = await auth(req);
-  if (!session?.user) return new Response(null, { status: 302, headers: { location: '/login' } });
-  return next();
-}
-```
-
-`auth(req)` takes the in-flight request explicitly (for a middleware / route); the ambient `auth()` (no argument) reads from context inside a page or action.
-
-## `forbidden()` (403) vs `unauthorized()` (401)
-
-Two control-flow throws from `@webjsdev/core`, mirroring the `notFound()`
-model. Both render the NEAREST matching boundary (innermost wins), else a
-default page.
-
-- `unauthorized()` for a request that is NOT authenticated (no valid
-  session). Renders the nearest `unauthorized.ts`. Use it when the fix is
-  "log in".
-- `forbidden()` for an authenticated user who LACKS permission for this
-  resource. Renders the nearest `forbidden.ts`. Use it when logging in as
-  a different account would not help.
-
-```ts
-// app/admin/page.ts
-import { html, forbidden, unauthorized } from '@webjsdev/core';
-import { auth } from '#modules/auth/auth.server.ts';
-
-export default async function Admin() {
-  const session = await auth();
-  if (!session) throw unauthorized();          // 401, renders unauthorized.ts
-  if (session.user.role !== 'admin') throw forbidden();  // 403, renders forbidden.ts
-  return html`<h1>Admin</h1>`;
-}
-```
-
-Both work from a page or layout render AND from a form-bound action (the no-JS
-write path). The boundary files (`app/forbidden.ts`, `app/unauthorized.ts`,
-or nested variants) live alongside the routes they cover and each
-default-export a function returning the boundary markup.
-
-`forbidden()` / `unauthorized()` are for a page / layout render or a page
-`action`. They are NOT for a `route.ts` handler (return a `Response` with
-the status there), and NOT for a `'use server'` RPC action (a raw throw
-becomes a generic 500). See the next section for the action case.
-
-## Auth failure inside a `'use server'` action: return, do not throw
-
-A `'use server'` RPC action must NOT throw `forbidden()` / `unauthorized()`
-/ `redirect()` for an auth failure. A raw throw there is sanitized to a
-generic 500 in production, so the caller loses the reason. Instead return
-an `ActionResult` failure envelope with a status the client can act on.
-
-```ts
-// modules/posts/actions/delete-post.server.ts
-'use server';
-import { eq } from 'drizzle-orm';
-import { auth } from '#modules/auth/auth.server.ts';
-import { db } from '#db/connection.server.ts';
-import { posts } from '#db/schema.server.ts';
-
-export async function deletePost(input: { id: string }) {
-  const session = await auth();
-  if (!session) return { success: false, error: 'Sign in to continue.', status: 401 };
-  const post = await db.query.posts.findFirst({ where: { id: input.id } });
-  if (post?.authorId !== session.user.id) {
-    return { success: false, error: 'Not your post.', status: 403 };
-  }
-  await db.delete(posts).where(eq(posts.id, input.id));
-  return { success: true };
-}
-```
-
-The user-facing message belongs on the envelope's `error` field, never on
-a raw throw (prod strips a thrown message to a digest). See
-`data-and-actions.md` for the full `ActionResult` shape.
-
-## CSRF: an Origin / `Sec-Fetch-Site` check, not a token cookie
-
-Action RPC CSRF protection is an Origin / `Sec-Fetch-Site` header check
-(the Remix 3 / Go 1.25 model), NOT a token cookie. A state-changing verb
-(POST / PUT / PATCH / DELETE) passes only when:
-
-- `Sec-Fetch-Site` is `same-origin` or `none`, OR
-- (older browsers with no `Sec-Fetch-Site`) the `Origin` host matches the
-  request host, OR
-- the source is listed in `webjs.allowedOrigins`.
-
-Otherwise the request is a 403. A safe GET action is CSRF-exempt. Because
-there is no CSRF token cookie and no `Set-Cookie` rides the SSR HTML, a
-page that opts into a public `Cache-Control` stays CDN-edge-cacheable.
-
-A `route.ts` REST endpoint is NOT covered. Authenticate every mutating
-endpoint yourself, run `export const validate`, log without secrets, and
-rate-limit.
-
-## CORS: explicit allowlist when `credentials: true`
-
-For cross-origin requests use `cors()` from `@webjsdev/server` as
-middleware. When `credentials: true` you MUST pass an explicit origin
-allowlist. Never `'*'` with credentials (that would expose an
-authenticated response to any origin).
-
-```ts
-// middleware.ts
-import { cors } from '@webjsdev/server';
-export default cors({
-  origin: ['https://app.example.com', 'https://admin.example.com'],
-  credentials: true,   // requires the explicit allowlist above
-});
-```