@webjsdev/mcp 0.1.10 → 0.1.12

package/resources/references/typescript.md

@@ -5,8 +5,8 @@
 - TypeScript at runtime with **no build step**: `.ts` / `.mts` is stripped in place, not compiled.
 - **Erasable syntax only** (`erasableSyntaxOnly: true`) and the exact list of banned constructs, with their allowed rewrites.
 - The **pluggable stripper** (Node 24+ built-in vs `amaro` on Bun) and how the browser gets stripped source.
-- **Full-stack type safety**: server-action types flow to the call site, `import type` crosses the `.server` boundary, plus the carrier rule.
-- **Typing pages, layouts, and route handlers** with `PageProps` / `LayoutProps` / `RouteHandlerContext` and the generated route union (`webjs types`).
+- **Full-stack type safety**: the rule (derive the type at every boundary, never `unknown` / `any`), server-action types flowing to the call site, and the `import type` carrier rule across the `.server` boundary.
+- **Typing pages, layouts, and route handlers** with `PageProps` / `LayoutProps` / `RouteHandlerContext` and the generated route union (`npx webjsdev types`).
 
 Read this when you are writing `.ts` in a WebJs app, hit a strip-time 500, or want typed params and hrefs. For action signatures and the serializer wire see `data-and-actions.md`. For typing reactive props see `components.md`.
 
@@ -77,6 +77,75 @@ Prefer explicit `.ts` extensions in imports. A `.js` specifier pointing at a `.t
 
 ## Full-stack type safety
 
+### The rule: derive the type, never `unknown` or `any`
+
+Every value crossing an app boundary in WebJs already has a type you can reach, so reach for it. Writing `unknown` or `any` at a boundary throws away the framework's central guarantee, and it does so silently: the app still runs, the checker just stops helping. Nothing catches this for you. Both are valid TypeScript, so `webjs check` will not flag them (it is a correctness tool, and this is a convention), and `tsc --noEmit` passes happily.
+
+`unknown` is the more dangerous of the two, because it reads as the safe choice. It is safe only in the sense that it forces a narrow at the read site. As a boundary type it is exactly as uninformative as `any`, and it pushes a cast into every consumer.
+
+The ladder, in the order to climb it:
+
+| Boundary | Write this | Not this |
+|---|---|---|
+| A database row | `export type Todo = typeof todos.$inferSelect` in `db/schema.server.ts` (`$inferInsert` for a write) | a hand-written interface that drifts from the schema |
+| That row inside a shipping component | `import type { Todo } from '#db/schema.server.ts'` | `any[]`, or re-declaring the shape by hand |
+| A server action's input | a named `interface CreatePostInput` | `input: unknown` / `input: any` |
+| A server action's result | `Promise<ActionResult<Post>>` | `Promise<any>` |
+| `export const validate` | `(input: unknown)`, narrowed in the body, returning `data` that `satisfies` the action's input type | `(input: any)`, which un-types the returned `data` too |
+| A page | `PageProps<'/blog/[slug]'>` | `{ params: Record<string, any> }` |
+| A layout | `LayoutProps` (whose `children` is a `TemplateResult`) | `{ children: unknown }` |
+| A route handler's 2nd argument | `RouteHandlerContext<'/api/users/[id]'>` | `{ params: any }` |
+| A client-router href | the generated `Route` union (`npx webjsdev types`; `npm run dev` also emits it) | a bare `string` |
+| A reactive property | `prop<Student>(Object)`, `prop<Tag[]>(Array)` | `prop(Object)` plus a cast at every read |
+| An optimistic temp row | the pending shape on the row type (`pending?: boolean`) | `as any` on the temp id |
+
+One flow, end to end, with no escape hatch anywhere in it:
+
+```ts
+// db/schema.server.ts
+export const posts = table('posts', { id: uuidPk(), title: text().notNull(), body: text().notNull() });
+export type Post = typeof posts.$inferSelect;      // derived, never hand-written
+
+// modules/posts/actions/create-post.server.ts
+'use server';
+import type { Post } from '#db/schema.server.ts';  // type-only: erased before the browser sees it
+export interface CreatePostInput { title: string; body: string }
+export const validate = (input: unknown) => { /* narrows, returns data satisfying CreatePostInput */ };
+export async function createPost(input: CreatePostInput): Promise<ActionResult<Post>> { /* ... */ }
+
+// modules/posts/components/new-post.ts
+import { createPost } from '#modules/posts/actions/create-post.server.ts';
+const r = await createPost({ title, body });
+if (r.success && r.data) r.data.title;             // Post.title: string, checked at the call site
+```
+
+The payoff is not stylistic. A typo in `r.data.titel`, a renamed column, a changed action signature, and a page reading `params.slugg` are all compile errors in that version and all silent runtime `undefined` in the `unknown` version.
+
+### Where `unknown` is still the right type
+
+There are two cases, and only the first is about narrowing.
+
+**Case one: a value that genuinely has no type yet, at the moment before it is narrowed.**
+
+```ts
+// app/api/webhook/route.ts
+export async function POST(req: Request) {
+  const body: unknown = await req.json();   // correct: nothing has vouched for this yet
+  const parsed = parseWebhook(body);        // narrowed on the very next line
+  return Response.json({ ok: parsed.kind });
+}
+```
+
+The test is what the next line does. Correct `unknown` here is narrowed immediately by a parse, a validator, or a type guard, and the narrowed type is what the rest of the function sees. Anything standing at that boundary qualifies: a `route.ts` handler's `await req.json()` (above), a `catch (e)` binding (already `unknown` under `strict`), an action's `export const validate`, and any validator function those delegate to. In a validator, returning `data` that `satisfies` the action's input type is what carries a real type into the action body. See `data-and-actions.md`.
+
+**Case two: a parameter of YOUR OWN helper that forwards its argument into an `html` template hole, which is NOT narrowed.** A hole renders a string, a number, a `TemplateResult`, an array of those, a directive result, or nothing, so a helper like `lede(content: unknown)` is correctly typed and `TemplateResult` alone would be too narrow. Narrow it only when the helper genuinely accepts one shape (`backLink(href: string, ...)`).
+
+This case is about a value YOU accept, never one the framework hands you. A layout's `children` also ends up in a hole, but the framework already types it (`LayoutProps.children` is a `TemplateResult`), so `{ children: unknown }` is a discarded type, not this carve-out.
+
+Everywhere else `unknown` is a missing type, not a safe one: surviving into a return type, a component prop, a layout's `children`, or an action signature is the shape to fix.
+
+`any` gets no carve-out at all in app code. It does not defer checking, it disables it, so a validator typed `(input: any)` un-types everything downstream of the call.
+
 ### Server actions type-check automatically
 
 Calling a server action from a client component resolves at type-check time to the action's real source file. The runtime stub swap is invisible to the checker, and the RPC serializer makes runtime match the types (`Date` stays `Date`, `Map` stays `Map`, `BigInt` stays `BigInt`; see `data-and-actions.md` for the full supported set).
@@ -128,18 +197,18 @@ With no route literal (or before you generate route types), `params` is `Record<
 
 Type page metadata with the exported `Metadata` type (and `MetadataContext` for the `generateMetadata` argument), the same ergonomics as Next.js's `import type { Metadata } from 'next'`.
 
-### The generated route union (`webjs types`)
+### The generated route union (`npx webjsdev types`)
 
-Run `webjs types` to write `.webjs/routes.d.ts`, an opt-in overlay augmenting `@webjsdev/core` with one key per route in `app/`. It narrows two things at tsserver time:
+Run `npx webjsdev types` to write `.webjs/routes.d.ts`, an opt-in overlay augmenting `@webjsdev/core` with one key per route in `app/`. It narrows two things at tsserver time:
 
 - The `Route` href type: `navigate('/blog/anything')` passes, `navigate('/nonexistent')` is an error. Until you generate the types, `Route` is `string` (unconstrained, non-breaking for JSDoc and un-generated apps).
 - Per-route `params`: `PageProps<'/blog/[slug]'>['params']` becomes `{ slug: string }`.
 
 ```sh
-webjs types     # writes .webjs/routes.d.ts (route count printed)
+npx webjsdev types     # writes .webjs/routes.d.ts (route count printed)
 ```
 
-`webjs dev` emits it at startup and re-emits after each route rebuild, so the editor always has fresh types. The file is gitignored (regenerated per machine, like Next's `.next/types`); the scaffold `tsconfig.json` already lists it in `include`. To opt in for an existing app, run `webjs types` once and add `.webjs/routes.d.ts` to `include`. This is webjs's no-build equivalent of Next 15's `typedRoutes`, achieved via interface declaration-merging rather than a bundler.
+`npm run dev` emits it at startup and re-emits after each route rebuild, so the editor always has fresh types. The file is gitignored (regenerated per machine, like Next's `.next/types`); the scaffold `tsconfig.json` already lists it in `include`. To opt in for an existing app, run `npx webjsdev types` once and add `.webjs/routes.d.ts` to `include`. This is the WebJs no-build equivalent of Next 15's `typedRoutes`, achieved via interface declaration-merging rather than a bundler.
 
 ### The `webjs` config block and auth user
 

package/resources/references/ui-kit.md

@@ -1,8 +1,13 @@
 # The `@webjsdev/ui` component kit
 
-Load this when the app has a `components.json` (it uses `@webjsdev/ui`, the
-shadcn-style kit for WebJs). The source is copied into your repo (`components/ui/`),
-so you own and edit it. Two tiers:
+Load this when the app uses `@webjsdev/ui` (a `components.json` is present), OR
+when you are about to add a UI primitive (button, card, input, badge) to a fresh
+app that has not initialised the kit yet: running `npx webjsdev ui init` then
+`npx webjsdev ui add <name>` is HOW the kit comes to exist, and it is the default for a
+repeated primitive over hand-writing one from scratch. `@webjsdev/ui` is the shadcn-style
+kit for WebJs. The source is copied into your repo (`components/ui/`), so you own
+and edit it exactly as freely as code you wrote yourself, and can add, remove,
+restructure, or theme it however your app needs. Two tiers:
 
 - **Tier 1, class helpers (23 components).** Pure functions returning Tailwind
   class strings (`buttonClass({ variant })`, `cardClass()`), composed with
@@ -27,25 +32,28 @@ paste-ready structure on demand:
   kit inventory (each component's tier, helper signatures, npm deps); pass
   `{ name: "accordion" }` for one component's helper signatures, the paste-ready
   structural example, the accessibility header, and deps.
-- **CLI**: `webjs ui list` (inventory), `webjs ui view <name>` (the projected
+- **CLI**: `npx webjsdev ui list` (inventory), `npx webjsdev ui view <name>` (the projected
   view plus the full source). Same data as the MCP tool (one shared projector).
 
 So the loop is: `add` the component, then query `ui <name>` (MCP) or
-`webjs ui view <name>` for the accessible structure, paste it, and fill it in.
+`npx webjsdev ui view <name>` for the accessible structure, paste it, and fill it in.
 
 ## Setup and resolution
 
-- `webjs ui init` writes `components.json`, `lib/utils.ts`, and the CSS design
+- `npx webjsdev ui init` writes `components.json`, `lib/utils/cn.ts`, and the CSS design
   tokens the helpers render against (`--background`, `--foreground`,
   `--destructive`, ...). It HARD-FAILS if the tokens cannot be written, so a
-  clean exit means the kit is styled. `add` self-heals the tokens if they go
+  clean exit means the kit is styled. Re-running it is safe on an existing
+  project: it keeps the aliases, stylesheet path, and base color already in
+  `components.json` and leaves an edited `cn.ts` / `dom.ts` alone, so it only
+  fills in what is missing (`--overwrite` resets them instead). `add` self-heals the tokens if they go
   missing.
 - Resolution is LOCAL-FIRST: `init` / `add` / `list` / `view` read the registry
   that ships inside the installed `@webjsdev/ui`, with no network. This pins you
-  to the installed version; run `webjs ui diff` to see where your local copies
+  to the installed version; run `npx webjsdev ui diff` to see where your local copies
   drift from the upstream (that command alone compares against the live registry).
 
-## Inventory (run `webjs ui list` or the MCP `ui` tool for the authoritative, current set)
+## Inventory (run `npx webjsdev ui list` or the MCP `ui` tool for the authoritative, current set)
 
 **Tier 1 (class helpers):** accordion, alert, aspect-ratio, avatar, badge,
 breadcrumb, button, card, checkbox, collapsible, input, kbd, label,
@@ -61,7 +69,7 @@ dropdown-menu, hover-card, sonner, tabs, tooltip, plus toggle and toggle-group
 - A helper is a function, so compose it: `class=${buttonClass({ variant: 'outline' })}`.
   The unquoted `${...}` is a normal `html` attribute hole.
 - Tier-1 helpers assume the design tokens exist; if a component paints unstyled,
-  the tokens are missing (re-run `webjs ui init` or let `add` self-heal them).
+  the tokens are missing (re-run `npx webjsdev ui init` or let `add` self-heal them).
 - Custom elements are display-only-safe at SSR and hydrate in the browser, the
   standard WebJs component model (`references/components.md`).
 

package/src/mcp.js

@@ -163,6 +163,12 @@ const TOOL_DEFS = [
       'List registered custom-element tags: tag name, defining file, and class name. Read-only.',
     inputSchema: APPDIR_SCHEMA,
   },
+  {
+    name: 'list_elision',
+    description:
+      'Report the display-only elision verdict: every component module with whether it is elided (the browser never downloads it) or shipped plus the evidence that produced the verdict, every page/layout route module as inert / import-only / shipped (with the first client-effecting blocker that pins it), and any ORPHAN component class, one that either has no registration call at all or registers a computed tag, which the scanner cannot see either way, so it always loses its elision verdict, its tag-to-module registry entry, and its preload hint (and never upgrades at all with no registration call, or when a computed-tag class has no importer that ships whole). Identical to `webjs elision --json`. Read-only.',
+    inputSchema: APPDIR_SCHEMA,
+  },
   {
     name: 'check',
     description:
@@ -298,7 +304,7 @@ export function extractActionConfig(src) {
  * JSON-serialisable projection of an existing server data function. All are
  * read-only.
  *
- * @param {{ buildRouteTable: Function, buildActionIndex: Function, hashFile: Function, scanComponents: Function, checkConventions: Function, projectCheck: Function, readFile: Function }} deps
+ * @param {{ buildRouteTable: Function, buildActionIndex: Function, hashFile: Function, scanComponents: Function, analyzeAppElision: Function, checkConventions: Function, projectCheck: Function, readFile: Function }} deps
  */
 export function makeToolRunners(deps) {
   const {
@@ -306,6 +312,7 @@ export function makeToolRunners(deps) {
     buildActionIndex,
     hashFile,
     scanComponents,
+    analyzeAppElision,
     checkConventions,
     projectCheck,
     readFile,
@@ -369,6 +376,15 @@ export function makeToolRunners(deps) {
         .sort((a, b) => a.tag.localeCompare(b.tag));
     },
 
+    async list_elision(appDir) {
+      // The whole report IS the contract: `analyzeAppElision` already returns
+      // an app-relative, sorted, JSON-serializable object, so unlike
+      // `list_routes` there is no projector leaf here and nothing to keep in
+      // sync. `webjs elision --json` prints this same object, and a drift test
+      // asserts the two are equal.
+      return analyzeAppElision(appDir);
+    },
+
     async check(appDir) {
       const violations = await checkConventions(appDir);
       return projectCheck(violations);
@@ -475,6 +491,7 @@ export async function runMcpServer(opts) {
       buildActionIndex: server.buildActionIndex,
       hashFile: server.hashFile,
       scanComponents: server.scanComponents,
+      analyzeAppElision: server.analyzeAppElision,
       checkConventions: check.checkConventions,
       projectCheck,
       readFile,