@webjsdev/mcp 0.1.5 → 0.1.7

package/resources/agent-docs/types-and-mutations.md

@@ -0,0 +1,171 @@
+# Types and mutations: sharing server-derived shapes with the browser
+
+An interactive component that ships to the browser almost always needs the
+shape of the data it renders (`Todo`, `Post`, the `ActionResult<T>` envelope a
+mutation returns). Those shapes are DERIVED from server-only modules (the
+Drizzle schema, the action files), so the reflex is to import them straight from
+`db/schema.server.ts` or a `*.server.ts` action. That reflex pins a server
+module to a browser closure and breaks the build. This page codifies where the
+types live so a shipping component consumes them safely.
+
+The one rule. **A type crossing to the browser is a TYPE, never a runtime
+value.** Keep the shape in a browser-safe `modules/<feature>/types.ts` with no
+runtime import from a `.server.ts` file or from `db/`. A `import type { ... }`
+is erased by the TypeScript stripper before the module reaches the browser, so
+it is safe. A plain `import { ... }` (a value import) is NOT erased, so it pins
+the server module and trips the `no-server-import-in-browser-module` check.
+
+---
+
+## Why a value import breaks and a type import does not
+
+webjs strips TypeScript at runtime with no bundler. The stripper erases every
+`import type` and every type-only specifier, so those imports never exist in the
+served JavaScript. A value import survives stripping and becomes a real browser
+`import`. When the target is a `.server.ts` module, its browser stub throws at
+module load (invariant 1), and the `no-server-import-in-browser-module` check
+flags it statically for any module the framework determines actually ships.
+
+```ts
+// SAFE: type-only, erased before it reaches the browser.
+import type { Post } from '#db/schema.server.ts';
+
+// UNSAFE: a runtime value import of the server schema. Survives stripping,
+// pins db/schema.server.ts into the browser closure, throws at load.
+import { posts } from '#db/schema.server.ts';
+```
+
+The subtle trap is deriving a type from a value with a value import. `typeof
+posts.$inferSelect` needs the `posts` binding, and `import { posts }` is a value
+import even though you only use it at the type level. Write `import type` (rc.3
+schemas already `export type Post = typeof posts.$inferSelect`, so import the
+ready-made type), or hand-write the DTO in `types.ts`.
+
+---
+
+## The wrong chain: a types module re-exporting a runtime value
+
+The classic failure is a `types.ts` that looks type-only but carries a runtime
+re-export. A browser-shipped page or component imports it, and the whole server
+schema is dragged along.
+
+```ts
+// modules/posts/types.ts   WRONG
+// A star or value re-export carries the runtime `posts`, `users` table
+// bindings, not just their types.
+export * from '#db/schema.server.ts';           // re-exports VALUES
+export { posts } from '#db/schema.server.ts';    // re-exports a VALUE
+```
+
+```ts
+// components/post-card.ts   (an interactive component, ships to the browser)
+import type { Post } from '#modules/posts/types.ts';
+// Because types.ts value-re-exports the schema, the browser module graph now
+// reaches db/schema.server.ts. no-server-import-in-browser-module fails, and
+// at runtime the server stub throws the moment post-card.ts loads.
+```
+
+The check fires on the component (a shipping browser module), even though the
+mistake is in `types.ts`. The re-export made a server value reachable from a
+browser closure.
+
+---
+
+## The right chain: a browser-safe DTO in `types.ts`
+
+Define the wire shape as a plain interface (or a `type`) in `types.ts` with no
+runtime import. This is the DTO the query / action returns and the component
+consumes. It has zero server dependency, so it crosses the boundary freely.
+
+```ts
+// modules/posts/types.ts   RIGHT
+// A hand-written DTO. No import from db/ or any *.server.ts. Pure types.
+export type PostFormatted = {
+  id: number;
+  slug: string;
+  title: string;
+  body: string;
+  authorId: number;
+  authorName: string | null;
+  createdAt: string;   // serialized for the wire
+};
+
+export type CreatePostInput = { title: string; body: string };
+
+// The mutation envelope every action returns. Browser-safe, no server import.
+export type ActionResult<T> =
+  | { success: true; data?: T; redirect?: string }
+  | { success: false; error?: string; fieldErrors?: Record<string, string>;
+      values?: Record<string, string>; status?: number };
+```
+
+```ts
+// modules/posts/queries/list-posts.server.ts   (server: may touch db)
+import { db } from '#db/connection.server.ts';
+import type { PostFormatted } from '#modules/posts/types.ts';
+export async function listPosts(): Promise<PostFormatted[]> {
+  const rows = await db.query.posts.findMany({ orderBy: { createdAt: 'desc' } });
+  return rows.map(formatPost);   // maps the row to the DTO
+}
+```
+
+```ts
+// components/post-card.ts   (browser: consumes the DTO type only)
+import type { PostFormatted } from '#modules/posts/types.ts';
+```
+
+If you want the DTO to track the schema automatically rather than restating it,
+use a **type-only** derivation and keep it in `types.ts`.
+
+```ts
+// modules/posts/types.ts   RIGHT (type-only derivation, still erased)
+import type { Post } from '#db/schema.server.ts';   // type-only, erased
+export type PostFormatted = Omit<Post, 'createdAt'> & { createdAt: string };
+```
+
+Either form ships nothing server-side to the browser. The `import type` is the
+seam. A value import is the leak.
+
+---
+
+## Carrier choice: register an interactive component in `layout.ts`
+
+An interactive component reaches the browser because SOME module imports it and
+that module ships. A `page.ts` and a `layout.ts` never hydrate, but they DO load
+in the browser to register the components they import. When a page's ONLY reason
+to ship is registering a component, prefer registering that component in
+`app/layout.ts` (or a section layout), not `app/page.ts`.
+
+The reason is elision economics. A `page.ts` whose sole client job is
+registering a component is dropped by the framework, and the browser fetches the
+component leaf directly (the import-only page optimization). But when you have a
+component shared across a section (a header search box, a theme toggle, a cart
+button), the layout is the natural single carrier. Register it once there and
+every page under it gets the upgraded element with no per-page import.
+
+```ts
+// app/layout.ts   RIGHT: the section carrier registers shared interactive UI
+import '#components/theme-toggle.ts';   // registers <theme-toggle> for every page
+import '#components/ui/dialog.ts';      // registers the Tier-2 <ui-dialog> element
+
+export default function RootLayout({ children }) {
+  return html`... <theme-toggle></theme-toggle> ${children} ...`;
+}
+```
+
+```ts
+// app/page.ts   RIGHT: page stays a pure server function, no client import
+export default function Home() {
+  return html`<h1>Home</h1><theme-toggle></theme-toggle>`;   // tag already registered by the layout
+}
+```
+
+Register in `page.ts` only when the component is page-specific (used on that one
+route). A shared element registered per page duplicates the import intent across
+routes and muddies which module is the carrier. Keep pages pure server functions
+where you can, and let the nearest layout carry the shared interactive tags.
+
+Cross-references. The server-only boundary and the type-only-import exception
+are invariant 1 in the root `AGENTS.md`. The Drizzle query surface that produces
+these rows is in `agent-docs/orm.md`. The optimistic mutation flow that consumes
+`ActionResult<T>` on the client is in `agent-docs/advanced.md`.

package/src/mcp-source.js

@@ -48,15 +48,8 @@ const MAX_FILES = 4000;
  * reliable. The source dir is `src/`, or `lib/` for the cli. A package that is
  * not installed is skipped (not every app depends on every `@webjsdev/*`).
  *
- * Under Bun ZERO-INSTALL (no `node_modules`, #675) the packages live only in
- * Bun's global install cache (`<bunCacheDir>/@webjsdev/<pkg>@<version>@@@<n>/`,
- * which holds the full source). When the `node_modules` walk finds nothing and a
- * `bunCacheDir` + `readdir` are supplied, fall back to scanning that scope dir
- * for the package's versioned entry (highest version wins, best-effort), so the
- * tool works whether the package is installed OR resolved from the Bun cache.
- *
  * @param {string} cwd
- * @param {{ exists: (p: string) => boolean, readdir?: (d: string) => Array<{ name: string, isDir: boolean }>, bunCacheDir?: string | null }} fsDeps
+ * @param {{ exists: (p: string) => boolean }} fsDeps
  * @returns {Array<{ pkg: string, root: string, src: string }>}
  */
 export function resolveFrameworkRoots(cwd, fsDeps) {
@@ -76,8 +69,6 @@ export function resolveFrameworkRoots(cwd, fsDeps) {
       const cand = join(base, '@webjsdev', pkg);
       if (fsDeps.exists(join(cand, 'package.json'))) { root = cand; break; }
     }
-    // Zero-install fallback: no node_modules, so look in Bun's global cache.
-    if (!root) root = resolveFromBunCache(pkg, fsDeps);
     if (!root) continue;
     // Most packages keep source in `src/`; the cli keeps it in `lib/`. Use
     // whichever exists so every framework package's source is reachable.
@@ -91,69 +82,6 @@ export function resolveFrameworkRoots(cwd, fsDeps) {
   return out;
 }
 
-/**
- * Locate `@webjsdev/<pkg>` in Bun's global install cache (the zero-install
- * fallback). Bun caches a scoped package at `<bunCacheDir>/@webjsdev/<pkg>@<ver>@@@<n>/`
- * (the versioned dir holds the full source; a sibling unversioned `<pkg>/` dir is
- * metadata, skipped). Picks the highest cached version (semver-aware, so
- * `0.10.0` beats `0.9.0`), and returns its path only if it carries a
- * `package.json`. Returns '' when there is no cache dir, no `readdir`, or no
- * matching entry.
- *
- * @param {string} pkg
- * @param {{ exists: (p: string) => boolean, readdir?: (d: string) => Array<{ name: string, isDir: boolean }>, bunCacheDir?: string | null }} fsDeps
- * @returns {string}
- */
-function resolveFromBunCache(pkg, fsDeps) {
-  const { bunCacheDir, readdir, exists } = fsDeps;
-  if (!bunCacheDir || typeof readdir !== 'function') return '';
-  const scopeDir = join(bunCacheDir, '@webjsdev');
-  if (!exists(scopeDir)) return '';
-  let entries;
-  try { entries = readdir(scopeDir); } catch { return ''; }
-  const prefix = `${pkg}@`;
-  // A cache dir is `<pkg>@<version>@@@<n>`; extract <version> (between the name
-  // and the `@@@` cache-key suffix) and sort by it, highest first.
-  const versioned = entries
-    .filter((e) => e.isDir && e.name.startsWith(prefix) && e.name.includes('@@@'))
-    .map((e) => ({ name: e.name, version: e.name.slice(prefix.length).split('@@@')[0] }))
-    .sort((a, b) => compareVersions(b.version, a.version));
-  for (const { name } of versioned) {
-    const cand = join(scopeDir, name);
-    if (exists(join(cand, 'package.json'))) return cand;
-  }
-  return '';
-}
-
-/**
- * Compare two semver-ish version strings numerically (so `0.10.0` > `0.9.0`),
- * with a release ranking ABOVE its prerelease (`1.0.0` > `1.0.0-rc.1`). Compares
- * the release core (`major.minor.patch`) segment by segment numerically; on a
- * tie, a version WITHOUT a prerelease tag sorts higher, else the prerelease tags
- * compare lexically. The build suffix (`+...`) is ignored, per semver. Returns
- * negative / 0 / positive like a comparator.
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-function compareVersions(a, b) {
-  const parse = (v) => {
-    const [core, pre = ''] = v.split('+')[0].split('-');
-    return { nums: core.split('.').map(Number), pre };
-  };
-  const A = parse(a);
-  const B = parse(b);
-  for (let i = 0; i < Math.max(A.nums.length, B.nums.length); i++) {
-    const x = A.nums[i] || 0;
-    const y = B.nums[i] || 0;
-    if (x !== y) return x - y;
-  }
-  if (A.pre === B.pre) return 0;
-  if (!A.pre) return 1; // a release outranks any prerelease of the same core
-  if (!B.pre) return -1;
-  return A.pre < B.pre ? -1 : 1;
-}
-
 /**
  * Recursively list text-source files under `dir` (absolute paths), skipping
  * `node_modules` / `dist` and bounded by {@link MAX_FILES}.
@@ -225,6 +153,13 @@ export function listSources(deps, pkgFilter) {
 export async function grepSources(deps, query) {
   const q = String(query).toLowerCase();
   if (!q) return 'Provide a non-empty `query`.';
+  // No resolvable packages means NOTHING was searched. Returning "no matches"
+  // here would read as authoritative absence when the search never ran, which
+  // is the #837 dogfood failure: an odd/shimmed node_modules layout resolved
+  // zero roots, so a real symbol looked missing and the agent lost trust.
+  if (!deps.roots.length) {
+    return 'No @webjsdev/* source is resolvable here, so NOTHING was searched (run inside a webjs app or the monorepo). This is not the same as "not found".';
+  }
   /** @type {string[]} */
   const hits = [];
   let capped = false;
@@ -242,7 +177,10 @@ export async function grepSources(deps, query) {
       }
     }
   }
-  if (!hits.length) return `No matches for "${query}" in the @webjsdev/* source.`;
+  // Disclose the SEARCHED scope on a no-match, so "no matches" reads as a
+  // comprehensive-search result the agent can trust, not a silent gap (#837).
+  const searched = deps.roots.map((r) => r.pkg).join(', ');
+  if (!hits.length) return `No matches for "${query}" in the searched @webjsdev/* source (${searched}).`;
   if (capped) hits.push(`... (truncated at ${MAX_HITS} matches; narrow the query or read a file with \`path\`)`);
   return hits.join('\n');
 }

package/src/mcp.js

@@ -21,8 +21,7 @@
  */
 
 import { createInterface } from 'node:readline';
-import { relative, join } from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { relative } from 'node:path';
 
 import {
   resolveDocsLocation,
@@ -37,29 +36,6 @@ import { resolveFrameworkRoots, runSourceTool } from './mcp-source.js';
 
 const PROTOCOL_VERSION = '2024-11-05';
 
-/**
- * Best-effort path to Bun's global install cache, for the zero-install `source`
- * fallback (#687): under Bun zero-install an app has no `node_modules`, so
- * `@webjsdev/*` lives only in this cache. Prefers `bun pm cache` (authoritative),
- * then `$BUN_INSTALL/install/cache`, then `~/.bun/install/cache`. Returns null
- * when none exists (e.g. Bun is not installed), which leaves the tool on the
- * node_modules path with no behavior change.
- * @param {(p: string) => boolean} exists
- * @returns {string | null}
- */
-function resolveBunCacheDir(exists) {
-  try {
-    const out = spawnSync('bun', ['pm', 'cache'], { encoding: 'utf8' });
-    const dir = out && out.status === 0 && out.stdout ? out.stdout.trim() : '';
-    if (dir && exists(dir)) return dir;
-  } catch { /* bun not on PATH */ }
-  const candidates = [];
-  if (process.env.BUN_INSTALL) candidates.push(join(process.env.BUN_INSTALL, 'install', 'cache'));
-  if (process.env.HOME) candidates.push(join(process.env.HOME, '.bun', 'install', 'cache'));
-  for (const c of candidates) { if (exists(c)) return c; }
-  return null;
-}
-
 // Mirrors packages/server/src/action-config.js. A drift test in
 // packages/mcp/test/mcp.test.mjs asserts these stay in sync with the source.
 /** HTTP verbs an action may declare (mirrors RPC_VERBS in action-config.js). */
@@ -509,7 +485,7 @@ export async function runMcpServer(opts) {
     const { readdirSync, existsSync, realpathSync } = await import('node:fs');
     const readdir = (d) => readdirSync(d, { withFileTypes: true }).map((e) => ({ name: e.name, isDir: e.isDirectory() }));
     sourceDeps = {
-      roots: resolveFrameworkRoots(cwd, { exists: existsSync, readdir, bunCacheDir: resolveBunCacheDir(existsSync) }),
+      roots: resolveFrameworkRoots(cwd, { exists: existsSync }),
       readFile,
       readdir,
       realpath: realpathSync,