@webjsdev/mcp 0.1.5 → 0.1.6

package/README.md

@@ -34,9 +34,7 @@ subcommand) delegates to this same server, so both routes run identical code.
   MCP `resources` (the `agent-docs/*` corpus + `AGENTS.md` as `webjs-docs://*`),
   and `prompts` (the recipes as guided workflows).
 - **`source` tool**: reads the framework's own no-build source from
-  `node_modules/@webjsdev/*/src` (read-only, traversal-guarded). Under Bun
-  zero-install (no `node_modules`) it falls back to Bun's global cache, where the
-  packages live, so it works without an install.
+  `node_modules/@webjsdev/*/src` (read-only, traversal-guarded).
 
 The docs corpus is bundled into the package at `prepack`, so `npx @webjsdev/mcp`
 is self-contained; in the monorepo it falls back to the live repo-root docs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/mcp",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "description": "The webjs Model Context Protocol server: live app introspection (routes / actions / components / check) plus the framework knowledge layer (docs, recipes, source) for AI coding agents",
   "bin": {

package/resources/AGENTS.md

@@ -15,7 +15,7 @@ reference there.
 | `agent-docs/styling.md` | Tailwind helpers + vanilla-CSS opt-out conventions |
 | `agent-docs/built-ins.md` | Auth, sessions, env vars, caching (cache(), HTTP cache, asset-hash, conditional GET), rate-limit, broadcast, file storage |
 | `agent-docs/configuration.md` | The `package.json` `"webjs"` block (security headers, CSP, redirects, trailing-slash, basePath, client-router opt-out, ingress caps, dev/start task orchestration) + observability |
-| `agent-docs/runtime.md` | Node vs Bun (commands, the zero-install Bun bootstrap, the listener/stripper/SQLite/WebSocket differences) + the future-Deno seam |
+| `agent-docs/runtime.md` | Node vs Bun (commands, install, the listener/stripper/SQLite/WebSocket differences) + the future-Deno seam |
 | `agent-docs/advanced.md` | Suspense streaming, performance, bundling, client router (prefetch, frames, view transitions, stream actions), WebSockets |
 | `agent-docs/typescript.md` | TS at runtime + full-stack type safety |
 | `agent-docs/service-worker.md` | The opt-in progressive-enhancement service worker (`public/sw.js`) |
@@ -90,7 +90,7 @@ See `agent-docs/framework-dev.md` for monorepo commands, workspace layout, per-f
 
 An **AI-first, web-components-first** framework inspired by NextJs, Lit, and Rails. The component runtime API matches lit (reactive properties, the lit lifecycle hooks, ReactiveControllers, the `lit-html` directive set, `html` / `css` templates) so lit training data transfers directly, but webjs ships its own no-build implementation under `packages/core/src/`. Reactive properties are the one deliberate divergence (invariant 10): instead of lit's `@property()` decorator or a `static properties` block, webjs declares them through the declare-free base-class factory `extends WebComponent({ count: Number })`.
 
-- **No build step.** Source files are served as native ES modules. JSDoc `.js` is default; `.ts` / `.mts` is stripped through a pluggable stripper (#508): Node 24+'s built-in `module.stripTypeScriptTypes`, or `amaro` on Bun (byte-identical, position-preserving) (invariant 10 + `agent-docs/typescript.md`). **Runs on Node 24+ or Bun** (run a Bun app with `bun --bun run dev` / `start`); the early `assertNodeVersion()` preflight enforces the Node floor and admits Bun. On Bun, `startServer` selects a native `Bun.serve` listener shell instead of the node:http one (skipping the compat bridge for ~1.9x more req/s on the listening path, at near-complete feature parity, the one node-only gap being 103 Early Hints since `Bun.serve` has no informational-response API), via a runtime-neutral seam that also sets up future `Deno.serve` / embedded adapters. Edge runtimes (no filesystem) are a separate, later target. See `agent-docs/runtime.md` for the Node vs Bun command + difference reference (and the zero-install Bun bootstrap).
+- **No build step.** Source files are served as native ES modules. JSDoc `.js` is default; `.ts` / `.mts` is stripped through a pluggable stripper (#508): Node 24+'s built-in `module.stripTypeScriptTypes`, or `amaro` on Bun (byte-identical, position-preserving) (invariant 10 + `agent-docs/typescript.md`). **Runs on Node 24+ or Bun** (run a Bun app with `bun --bun run dev` / `start`); the early `assertNodeVersion()` preflight enforces the Node floor and admits Bun. On Bun, `startServer` selects a native `Bun.serve` listener shell instead of the node:http one (skipping the compat bridge for ~1.9x more req/s on the listening path, at near-complete feature parity, the one node-only gap being 103 Early Hints since `Bun.serve` has no informational-response API), via a runtime-neutral seam that also sets up future `Deno.serve` / embedded adapters. Edge runtimes (no filesystem) are a separate, later target. See `agent-docs/runtime.md` for the Node vs Bun command + difference reference.
 - **SSR + CSR by default.** Pages are server-rendered HTML; components render light DOM by default, shadow DOM opt-in via `static shadow = true` with DSD SSR.
 - **Progressive enhancement is the default architecture.** Pages and components are SSR'd; with JS off, content reads, `<a>` navigates, `<form>` server actions submit, display-only elements render. JS is opt-in *per interactive behaviour* (`@click`, a reactive property assignment, a signal mutation). Never write a first paint that depends on hydration; never use `fetch` + JS where a `<form>` + server action would do.
 - **Display-only components are elided from the browser.** A component with no interactivity signal renders identical HTML with or without its JS, so the framework strips its import (and any vendor reachable only through it, importmap entry included) from the served source. Automatic, conservative, verified differentially. Disable with `"webjs": { "elide": false }` or `WEBJS_ELIDE=0`. See `agent-docs/components.md`.
@@ -357,7 +357,7 @@ The advanced client-router surface is in `agent-docs/advanced.md`: **link prefet
 
 ## Scaffolding
 
-Three scaffolds exist (do not invent template names): `webjs create <name>` (full-stack: layout, page, components, modules, Drizzle+SQLite), `webjs create <name> --template api` (backend-only routes + modules + Drizzle, no SSR), `webjs create <name> --template saas` (auth + login/signup + protected dashboard + User model). The `--db sqlite|postgres` flag (default sqlite) picks the dialect; the schema/queries/actions are identical across dialects (see #563). The `--runtime node|bun` flag (default node, #541) is ORTHOGONAL to the template and re-flavors any of the three for Bun (the dev/start/db scripts run through a generated `webjs-bun.mjs` bootstrap under `bun --bun`, so the SERVER runs on Bun AND Bun auto-install resolves deps on demand at the package.json/`bun.lock` versions (an `onLoad` specifier rewrite pins them so zero-install fetches the declared version, not latest, #685), so a Bun app serves with NO `bun install`, install optional for editor types / offline, #675; `bun.lock`, a pure `oven/bun:1` Dockerfile (#595; safe since cli@0.10.20's npx-free `webjs db migrate` (#570) needs no Node in the image) + bun-install CI, bun-command agent docs; the test/check/typecheck tooling stays plain `webjs` on Node and still expects an install); `bun create webjs <name>` auto-detects it. Pick from the request: default for any product with UI (todo, blog, dashboard, marketplace, social, e-commerce), `api` for an HTTP/JSON API with no UI, `saas` for accounts/login/signup; default to full-stack when ambiguous.
+Three scaffolds exist (do not invent template names): `webjs create <name>` (full-stack: layout, page, components, modules, Drizzle+SQLite), `webjs create <name> --template api` (backend-only routes + modules + Drizzle, no SSR), `webjs create <name> --template saas` (auth + login/signup + protected dashboard + User model). The `--db sqlite|postgres` flag (default sqlite) picks the dialect; the schema/queries/actions are identical across dialects (see #563). The `--runtime node|bun` flag (default node, #541) is ORTHOGONAL to the template and re-flavors any of the three for Bun (`bun --bun` dev/start scripts so the SERVER runs on Bun, `bun.lock`, a pure `oven/bun:1` Dockerfile (#595; safe since cli@0.10.20's npx-free `webjs db migrate` (#570) needs no Node in the image) + bun-install CI, bun-command agent docs; the test/db/check tooling stays on Node); `bun create webjs <name>` auto-detects it. Pick from the request: default for any product with UI (todo, blog, dashboard, marketplace, social, e-commerce), `api` for an HTTP/JSON API with no UI, `saas` for accounts/login/signup; default to full-stack when ambiguous.
 
 Rules: **always scaffold via `webjs create`** (never hand-roll). **Default to a real database (Drizzle + SQLite); NEVER use JSON files, in-memory arrays, or localStorage for persistence.** Update `db/schema.server.ts` to real models FIRST, then `webjs db generate` + `webjs db migrate`, then build pages/actions/queries. **Treat the scaffold as REFERENCE, not the final product:** replace the example page / `User` model / components and adapt `app/layout.ts` (brand, nav, content width; the default `<main class="max-w-[760px]">` reading column needs widening for a full-bleed app). ENFORCED: examples carry a `webjs-scaffold-placeholder` comment and `no-scaffold-placeholder` fails until the content is replaced and the marker deleted. Docs at https://docs.webjs.com.
 

package/resources/agent-docs/runtime.md

@@ -11,7 +11,7 @@ user-facing reference is the docs-site page `/docs/runtime`; keep the two in syn
 
 | Area | Node 24+ | Bun |
 |---|---|---|
-| Install | `npm install` (required) | optional (zero-install via Bun auto-install) |
+| Install | `npm install` (required) | `bun install` (required, like Node) |
 | Run | `npm run dev` / `npm run start` | `bun run dev` / `bun run start` |
 | Listener | `node:http` shell | native `Bun.serve` (about 1.9x req/s on the listening path) |
 | TS strip | built-in `module.stripTypeScriptTypes` | `amaro` (byte-identical, position-preserving) |
@@ -29,52 +29,26 @@ correctness (the modulepreload hints still ship in the document head).
 `webjs create <name>` defaults to Node. `webjs create <name> --runtime bun` (or
 `bun create webjs <name>`, auto-detected from the invoking package manager,
 #541) emits a Bun-flavored app: `bun.lock`, a pure `oven/bun:1` Dockerfile +
-bun-install CI, bun-command agent docs, and the zero-install bootstrap below.
-`--runtime` is orthogonal to `--template`.
+bun-install CI, and bun-command agent docs. `--runtime` is orthogonal to
+`--template`.
 
-## Bun zero-install (#675)
+## Bun
 
-A Bun app's `dev` / `start` / `db` scripts run through a generated app-local
-`webjs-bun.mjs` bootstrap under `bun --bun`:
+A Bun app installs with `bun install` (like Node), then its `dev` / `start` /
+`db` scripts force `bun --bun` so the server runs on Bun:
 
-```js
-// webjs-bun.mjs
-await import('@webjsdev/cli/bin/webjs.js');
+```sh
+bun install
+bun run dev      # or: bun run start
 ```
 
-`bun --bun` overrides the `webjs` bin's Node shebang so the server runs on Bun;
-importing the CLI by bare specifier lets Bun auto-install resolve `@webjsdev/*`
-and the app's deps on demand, so a fresh app serves with **no `bun install`**.
-The CLI's `start` is in-process and `dev` re-execs via `process.execPath` (which
-is `bun` here), so the server stays on Bun once the CLI does. `bunx
-@webjsdev/cli` is deliberately NOT used (it runs on Node via the shebang AND
-eager-installs the whole tree). The `start.before` migrate also routes through
-the bootstrap, so the boot-time `webjs db migrate` needs no `webjs` bin in
-`node_modules`. `bun install` stays optional: run it for editor type
-intelligence (no `node_modules` means no local type files) or a pinned offline
-install. The Node-targeted tooling scripts (`test` / `check` / `typecheck`)
-stay plain `webjs` on Node and still expect an install.
-
-**Version pinning (#685).** Bun's auto-install fetches `latest` for a bare
-`import 'zod'`, ignoring package.json and `bun.lock` (it consults neither the
-manifest, the lockfile, nor an `onResolve` plugin, verified in #684). webjs
-closes that gap with an `onLoad` transform: it rewrites a declared dep's bare
-specifier to an inline-versioned one (`zod` to `zod@3.22.4`), which Bun's
-auto-install DOES honor. The version is the EXACT one from `bun.lock` when
-present, else an exact `package.json` pin. Bun resolves an exact inline version
-but ENOENTs on a range or dist-tag (`zod@^3`, `zod@latest`), so a dep declared
-as a RANGE without a `bun.lock` is left bare and resolves to latest as before:
-commit a `bun.lock` (or pin exact versions) to get pinned zero-install. The
-rewrite is server-runtime only (it shapes what Bun fetches for SSR and server
-actions). The browser is still served bare specifiers resolved via the importmap
-/ jspm, unchanged. Only declared deps are rewritten (a transitive dep follows
-from its pinned parent's manifest), and it is a no-op when `node_modules` exists
-(Bun uses the installed copy). Default on. Opt out with `WEBJS_PIN=0` or
-`{ "webjs": { "pin": false } }`.
-
-**Reproducibility:** dev resolves on demand (now at the pinned versions), and the
-scaffold's Bun Dockerfile still keeps an explicit `bun install` so a prod image
-is immutable and self-contained with no registry fetch at boot.
+`bun --bun` overrides the `webjs` bin's Node shebang so the server runs on Bun
+(selecting the native `Bun.serve` listener and `amaro` type stripping); the app's
+deps resolve from `node_modules`, the same as Node. The `start.before` migrate
+(`webjs db migrate`) runs under Bun too. Commit a `bun.lock` (the Bun analog of
+`package-lock.json`) for reproducible, offline installs; the scaffold's Bun
+Dockerfile runs `bun install` and serves via `CMD ["bun", "--bun", "run",
+"start"]`.
 
 ## SQLite busy_timeout (#674)
 

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}.

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,