@webjsdev/cli 0.10.11 → 0.10.12

package/lib/mcp-docs.js

@@ -0,0 +1,400 @@
+/**
+ * The knowledge + authoring layer for `webjs mcp` (#376).
+ *
+ * `webjs mcp` (lib/mcp.js) started as four READ-ONLY introspection tools. This
+ * module adds the second layer the Next.js MCP (`next-devtools-mcp`) showed is
+ * the high-leverage one: the framework knowledge an agent needs to author
+ * idiomatic webjs code, surfaced as MCP RESOURCES (the `agent-docs/*.md` corpus
+ * plus the `AGENTS.md` contract), an `init` "read first" primer that fights the
+ * React/RSC mental model, a `docs` retrieval tool, and guided-workflow PROMPTS
+ * built from the recipes.
+ *
+ * It stays hand-rolled and ZERO-dependency (no `@modelcontextprotocol/sdk`),
+ * consistent with webjs being buildless + minimal-deps. Everything here is PURE
+ * given its injected `{ docsDir, agentsPath, readFile }` deps, so it is testable
+ * in-process without booting a server or touching the real filesystem.
+ *
+ * Docs resolution (so `npx @webjsdev/cli mcp` is self-contained): a published
+ * install reads the corpus bundled under `<cli>/resources/agent-docs` (copied
+ * at `prepack`, see `scripts/copy-mcp-resources.js`); a monorepo dev run falls
+ * back to the repo-root `agent-docs/`. {@link resolveDocsLocation} encodes that
+ * two-path lookup so source stays single (no committed duplicate docs).
+ *
+ * @module mcp-docs
+ */
+
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** The URI scheme for a framework-docs resource: `webjs-docs://<name>`. */
+const DOCS_SCHEME = 'webjs-docs://';
+
+/**
+ * Resolve where the framework-docs corpus lives, plus the `AGENTS.md` contract
+ * path. Tries the BUNDLED location first (a published `@webjsdev/cli` ships
+ * `resources/agent-docs/` + `resources/AGENTS.md` via `prepack`), then falls
+ * back to the monorepo-root layout (`agent-docs/` + `AGENTS.md`) used in dev and
+ * tests. Returns `{ docsDir, agentsPath }`; either path may not exist, callers
+ * fail soft (an empty corpus is valid, never a crash).
+ *
+ * @param {string} [moduleUrl]  `import.meta.url` of the caller (defaults to this module)
+ * @returns {{ docsDir: string, agentsPath: string }}
+ */
+export function resolveDocsLocation(moduleUrl) {
+  const here = dirname(fileURLToPath(moduleUrl || import.meta.url));
+  const cliRoot = resolve(here, '..'); // packages/cli/lib -> packages/cli
+  const repoRoot = resolve(here, '..', '..', '..'); // -> monorepo root
+
+  const bundledDocs = join(cliRoot, 'resources', 'agent-docs');
+  if (existsSync(bundledDocs)) {
+    return { docsDir: bundledDocs, agentsPath: join(cliRoot, 'resources', 'AGENTS.md') };
+  }
+  return { docsDir: join(repoRoot, 'agent-docs'), agentsPath: join(repoRoot, 'AGENTS.md') };
+}
+
+/**
+ * A doc's logical name from its filename: `lit-muscle-memory-gotchas.md` ->
+ * `lit-muscle-memory-gotchas`. The `AGENTS.md` contract keeps its own name.
+ *
+ * @param {string} file
+ * @returns {string}
+ */
+function docName(file) {
+  return file.replace(/\.md$/i, '');
+}
+
+/**
+ * A human title for a doc name: `lit-muscle-memory-gotchas` ->
+ * `Lit Muscle Memory Gotchas`. Used in the resource listing so a model picks
+ * the right doc without reading it.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+function titleFor(name) {
+  if (name === 'AGENTS') return 'AGENTS.md (the framework contract + invariants)';
+  return name
+    .split('-')
+    .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(' ');
+}
+
+/**
+ * The corpus catalogue: every servable doc as `{ name, file, uri, title }`.
+ * Reads the docs dir listing (so it tracks the shipped set) plus the `AGENTS.md`
+ * contract. PURE given `deps`.
+ *
+ * @param {{ docsDir: string, agentsPath: string, listDir: (d: string) => string[], exists: (p: string) => boolean }} deps
+ * @returns {Array<{ name: string, file: string, uri: string, title: string }>}
+ */
+export function catalogue(deps) {
+  const { docsDir, agentsPath, listDir, exists } = deps;
+  /** @type {Array<{ name: string, file: string, uri: string, title: string }>} */
+  const out = [];
+  if (exists(agentsPath)) {
+    out.push({ name: 'AGENTS', file: agentsPath, uri: `${DOCS_SCHEME}AGENTS`, title: titleFor('AGENTS') });
+  }
+  let files = [];
+  try { files = listDir(docsDir).filter((f) => /\.md$/i.test(f)).sort(); } catch { files = []; }
+  for (const f of files) {
+    const name = docName(f);
+    out.push({ name, file: join(docsDir, f), uri: `${DOCS_SCHEME}${name}`, title: titleFor(name) });
+  }
+  return out;
+}
+
+/**
+ * MCP `resources/list`: the corpus as resource descriptors.
+ *
+ * @param {object} deps
+ * @returns {Array<{ uri: string, name: string, title: string, mimeType: string }>}
+ */
+export function listResources(deps) {
+  return catalogue(deps).map((d) => ({
+    uri: d.uri,
+    name: d.name,
+    title: d.title,
+    mimeType: 'text/markdown',
+  }));
+}
+
+/**
+ * MCP `resources/read`: the markdown text for a `webjs-docs://<name>` URI.
+ * Throws a clear Error for an unknown URI (the dispatcher maps it to a JSON-RPC
+ * error, never a crash).
+ *
+ * @param {object} deps
+ * @param {string} uri
+ * @returns {Promise<{ uri: string, mimeType: string, text: string }>}
+ */
+export async function readResource(deps, uri) {
+  const entry = catalogue(deps).find((d) => d.uri === uri);
+  if (!entry) throw new Error(`Unknown resource: ${uri}`);
+  const text = await deps.readFile(entry.file, 'utf8');
+  return { uri, mimeType: 'text/markdown', text };
+}
+
+/**
+ * Extract a `## <heading>` section (heading line through the line before the
+ * next same-or-higher-level heading) from a markdown doc. Used to source the
+ * `init` primer from `AGENTS.md` rather than hand-duplicating it (so it cannot
+ * drift). Returns '' when the heading is absent.
+ *
+ * @param {string} md
+ * @param {RegExp} headingRe  matches the section's heading LINE (e.g. /^##\s+Execution model/m)
+ * @returns {string}
+ */
+export function sectionByHeading(md, headingRe) {
+  const lines = md.split('\n');
+  let start = -1;
+  let level = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (headingRe.test(lines[i])) {
+      start = i;
+      level = (lines[i].match(/^#+/) || ['##'])[0].length;
+      break;
+    }
+  }
+  if (start === -1) return '';
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    const m = lines[i].match(/^(#+)\s/);
+    if (m && m[1].length <= level) { end = i; break; }
+  }
+  return lines.slice(start, end).join('\n').trim();
+}
+
+/**
+ * The `init` tool output: the "read first" orientation that fights the
+ * React/RSC mental model. Sources the EXECUTION MODEL + INVARIANTS sections
+ * from the shipped `AGENTS.md` (no hand-duplication), prepends a short router
+ * to the highest-value resources, and lists the corpus so the agent knows what
+ * else it can pull. PURE given `deps`.
+ *
+ * @param {object} deps
+ * @returns {Promise<string>}
+ */
+export async function initText(deps) {
+  let agents = '';
+  try { agents = await deps.readFile(deps.agentsPath, 'utf8'); } catch { agents = ''; }
+  const execModel = sectionByHeading(agents, /^##\s+Execution model/im);
+  const invariants = sectionByHeading(agents, /^##\s+Invariants/im);
+
+  const cat = catalogue(deps);
+  const resourceList = cat.map((d) => `- \`${d.uri}\` (${d.title})`).join('\n');
+
+  const router = [
+    'You are about to write or edit a webjs app. Read this orientation FIRST, then',
+    'pull the specific docs you need via the `docs` tool or the `webjs-docs://*`',
+    'resources. webjs is web-components-first and looks like Lit + Rails, NOT React/Next:',
+    'there is NO RSC, no server/client component split, no `use client`. Components',
+    'hydrate (islands); pages and layouts do NOT hydrate. Signals are the default',
+    'state primitive. Server-only code lives behind the `.server.{js,ts}` boundary.',
+    'When writing a component, read `webjs-docs://lit-muscle-memory-gotchas` first:',
+    'the Lit habits that break webjs SSR/reactivity each have a webjs-shaped fix there.',
+    '',
+    'webjs is buildless: the authored framework source is readable JSDoc in',
+    '`node_modules/@webjsdev/<pkg>/src`, and server-side that source runs directly.',
+    '(The one built artifact is the `@webjsdev/core` BROWSER bundle in `dist/`;',
+    'its authored source is still in `src/`.) When the docs do not answer something,',
+    'use the `source` tool to grep or read that real `src/` source (it skips `dist/`).',
+  ].join('\n');
+
+  const parts = [
+    '# webjs: read first',
+    '',
+    router,
+    '',
+    execModel || '(execution-model section unavailable)',
+    '',
+    invariants || '(invariants section unavailable)',
+    '',
+    '## Available docs (read via the `docs` tool or these resources)',
+    '',
+    resourceList || '(no docs bundled)',
+  ];
+  return parts.join('\n');
+}
+
+/**
+ * The `docs` tool. With `topic` matching a corpus name, returns that doc's full
+ * text. With `query`, keyword-searches every doc and returns the matching lines
+ * (each tagged with its source URI and nearest heading). With neither, returns
+ * the topic index (the catalogue). PURE given `deps`.
+ *
+ * @param {object} deps
+ * @param {{ topic?: string, query?: string }} [args]
+ * @returns {Promise<string>}
+ */
+export async function searchDocs(deps, args) {
+  const { topic, query } = args || {};
+  const cat = catalogue(deps);
+
+  if (topic) {
+    const entry = cat.find((d) => d.name.toLowerCase() === String(topic).toLowerCase());
+    if (!entry) {
+      const names = cat.map((d) => d.name).join(', ');
+      return `Unknown topic "${topic}". Available topics: ${names}`;
+    }
+    return await deps.readFile(entry.file, 'utf8');
+  }
+
+  if (query) {
+    const q = String(query).toLowerCase();
+    const MAX_HITS = 40;
+    /** @type {string[]} */
+    const hits = [];
+    let capped = false;
+    outer: for (const entry of cat) {
+      let text = '';
+      try { text = await deps.readFile(entry.file, 'utf8'); } catch { continue; }
+      const lines = text.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        if (!lines[i].toLowerCase().includes(q)) continue;
+        // Check the cap BEFORE pushing, so `capped` means a match BEYOND the cap
+        // exists (exactly MAX_HITS matches is NOT a truncation, nothing dropped).
+        if (hits.length >= MAX_HITS) { capped = true; break outer; }
+        // Nearest preceding heading for context.
+        let heading = '';
+        for (let j = i; j >= 0; j--) {
+          if (/^#+\s/.test(lines[j])) { heading = lines[j].replace(/^#+\s/, ''); break; }
+        }
+        hits.push(`[${entry.uri}] ${heading ? heading + ': ' : ''}${lines[i].trim()}`);
+      }
+    }
+    if (!hits.length) return `No matches for "${query}" in the webjs docs. Topics: ${cat.map((d) => d.name).join(', ')}`;
+    // Disclose truncation rather than silently capping (no silent caps).
+    if (capped) hits.push(`... (truncated at ${MAX_HITS} matches; refine the query or open a doc with \`topic\`)`);
+    return hits.join('\n');
+  }
+
+  // No args: the topic index.
+  return ['webjs docs topics (pass one as `topic`, or `query` to search):', '', ...cat.map((d) => `- ${d.name}: ${d.title}`)].join('\n');
+}
+
+/**
+ * The guided-workflow PROMPTS, built from the recipes. Each is a single-message
+ * prompt that hands the agent the canonical webjs recipe plus the invariants it
+ * must not break, then tells it to pull `webjs-docs://recipes` for the full set.
+ * Static metadata; {@link getPrompt} fills the message text.
+ */
+export const PROMPTS = [
+  { name: 'add_page', description: 'Scaffold a webjs page (app/<segment>/page.ts), the idiomatic way.', arguments: [{ name: 'route', description: 'URL path, e.g. /about', required: false }] },
+  { name: 'add_dynamic_route', description: 'Scaffold a dynamic page reading params, e.g. app/users/[id]/page.ts.', arguments: [{ name: 'route', description: 'URL path with a [param], e.g. /users/[id]', required: false }] },
+  { name: 'add_server_action', description: 'Scaffold a server action (.server.ts + use server) called from a component.', arguments: [{ name: 'feature', description: 'Feature/module name', required: false }] },
+  { name: 'add_component', description: 'Scaffold an interactive WebComponent (signals, light DOM, register).', arguments: [{ name: 'tag', description: 'Custom-element tag, e.g. my-thing', required: false }] },
+  { name: 'add_module', description: 'Scaffold a modules/<feature>/ slice (actions/queries/components/utils).', arguments: [{ name: 'feature', description: 'Feature name', required: false }] },
+];
+
+/**
+ * The canonical recipe snippet + invariant reminders for each prompt. Kept
+ * compact on purpose: the prompt orients + shows the shape, then points at the
+ * full `webjs-docs://recipes` resource. The shapes mirror `agent-docs/recipes.md`.
+ *
+ * @type {Record<string, string>}
+ */
+const PROMPT_BODIES = {
+  add_page: [
+    'Add a webjs page. A page is `app/<segment>/page.ts` whose DEFAULT export is a',
+    '(possibly async) function returning a `TemplateResult`; it runs ONLY on the server.',
+    '',
+    '```ts',
+    "import { html } from '@webjsdev/core';",
+    'export default function About() {',
+    '  return html`<h1>About</h1>`;',
+    '}',
+    '```',
+    '',
+    'Rules: the default export is a FUNCTION (invariant 6), it does NOT call render().',
+    'For interactivity, render a component tag inside it (pages do not hydrate).',
+    'Name metadata via a `metadata` / `generateMetadata` named export.',
+  ].join('\n'),
+  add_dynamic_route: [
+    'Add a dynamic page. `app/users/[id]/page.ts` receives `{ params }`; fetch data',
+    'through a server action or query, never by importing the DB directly.',
+    '',
+    '```ts',
+    'export default async function User({ params }: { params: { id: string } }) {',
+    '  const user = await getUser(params.id); // a `use server` action / query',
+    '  return html`<h1>${user.name}</h1>`;',
+    '}',
+    '```',
+    '',
+    'Catch-all is `[...rest]`, optional catch-all `[[...rest]]`. Server-only data',
+    'access goes through `.server.{js,ts}`, never a direct import into the page.',
+  ].join('\n'),
+  add_server_action: [
+    "Add a server action. A `*.server.ts` file with `'use server'` exports async",
+    'functions that round-trip serializer-safe values; a client import is rewritten',
+    'to a typed RPC stub (never hand-write fetch).',
+    '',
+    '```ts',
+    '// modules/<feature>/actions/<name>.server.ts',
+    "'use server';",
+    "import { prisma } from '../../../lib/prisma.server.ts';",
+    'export async function doThing(input: { name: string }) {',
+    "  const name = String(input?.name || '').trim();",
+    "  if (!name) return { success: false, error: 'name required', status: 400 };",
+    '  return { success: true, data: await prisma.thing.create({ data: { name } }) };',
+    '}',
+    '```',
+    '',
+    'Return the `ActionResult<T>` envelope. Server-only code MUST stay in `.server.*`',
+    '(invariant 1). Call it from a component via a normal import.',
+  ].join('\n'),
+  add_component: [
+    'Add an interactive WebComponent. One custom element per file; register at module',
+    'top level. Signals are the default state; read with `.get()` inside render().',
+    '',
+    '```ts',
+    "import { WebComponent, html, signal } from '@webjsdev/core';",
+    'export class MyThing extends WebComponent {',
+    '  count = signal(0);',
+    '  render() {',
+    '    return html`<button @click=${() => this.count.set(this.count.get() + 1)}>',
+    '      ${this.count.get()}</button>`;',
+    '  }',
+    '}',
+    "MyThing.register('my-thing');",
+    '```',
+    '',
+    'Tag MUST contain a hyphen (invariant 3). Event/property/boolean holes are',
+    'unquoted (invariant 4). Read `webjs-docs://lit-muscle-memory-gotchas` first:',
+    'a class-field initializer that overwrites a reactive accessor breaks reactivity',
+    '(use `declare` + `static properties`).',
+  ].join('\n'),
+  add_module: [
+    'Add a feature module. `modules/<feature>/` holds `actions/*.server.ts` (mutations),',
+    '`queries/*.server.ts` (reads), `components/*.ts` (feature UI), `utils/*.ts` (pure),',
+    '`types.ts`. One function per action/query file. Routes stay thin: extract anything',
+    'over ~20 lines into a module action. Shared presentational primitives go in the',
+    'top-level `components/`, cross-cutting infra in `lib/*.server.ts`.',
+  ].join('\n'),
+};
+
+/**
+ * MCP `prompts/get`: the messages for a guided-workflow prompt. Throws for an
+ * unknown name (mapped to a JSON-RPC error).
+ *
+ * @param {string} name
+ * @param {Record<string, string>} [args]
+ * @returns {{ description: string, messages: Array<{ role: string, content: { type: string, text: string } }> }}
+ */
+export function getPrompt(name, args) {
+  const meta = PROMPTS.find((p) => p.name === name);
+  const body = PROMPT_BODIES[name];
+  if (!meta || !body) throw new Error(`Unknown prompt: ${name}`);
+
+  // Fold any provided argument values in as a one-line hint at the top.
+  const provided = Object.entries(args || {}).filter(([, v]) => v != null && v !== '');
+  const argLine = provided.length
+    ? `Context: ${provided.map(([k, v]) => `${k}=${v}`).join(', ')}.\n\n`
+    : '';
+
+  const text = `${argLine}${body}\n\nSee \`webjs-docs://recipes\` for the full recipe set and \`webjs-docs://AGENTS\` for the invariants.`;
+  return {
+    description: meta.description,
+    messages: [{ role: 'user', content: { type: 'text', text } }],
+  };
+}

package/lib/mcp-source.js

@@ -0,0 +1,244 @@
+/**
+ * The `source` tool for `webjs mcp` (#378): read-only access to the FRAMEWORK
+ * source itself.
+ *
+ * webjs is buildless, so every app's `node_modules/@webjsdev/<pkg>/src` holds the
+ * authored JSDoc `.js`, and server-side that source runs directly. (The one built
+ * artifact is the `@webjsdev/core` browser bundle in `dist/`, which this tool
+ * deliberately skips: it surfaces only the authored `src/`.) That is a real
+ * advantage: when the docs do not answer a question, an agent can read the real
+ * authored source. This tool makes that first-class and
+ * discoverable (and reachable for an MCP-only client with no filesystem tools):
+ *   - no args (or `package`): list the resolved `@webjsdev/*` packages + their
+ *     `src/` entry-point files.
+ *   - `query`: grep the framework `src/` trees, returning bounded `file:line`
+ *     hits (with a disclosed cap, no silent truncation).
+ *   - `path`: read one source file (e.g. `server/src/ssr.js`), traversal-guarded
+ *     to stay inside a resolved framework package root.
+ *
+ * READ-ONLY and side-effect-free: it only reads files, loads no module, and
+ * cannot read outside the resolved `@webjsdev/*` package roots. Zero-dependency,
+ * consistent with the rest of the server. PURE given injected `deps`
+ * (`{ roots, readFile, readdir }`), so it is testable against a fake tree.
+ *
+ * @module mcp-source
+ */
+
+import { createRequire } from 'node:module';
+import { join, resolve, sep, relative } from 'node:path';
+
+/** The published framework packages whose source an agent may want to read. */
+export const FRAMEWORK_PACKAGES = ['core', 'server', 'cli', 'ts-plugin', 'ui'];
+
+/** Source file extensions worth grepping / reading (text, not assets). */
+const TEXT_EXT = /\.(?:js|ts|mjs|mts|cjs|cts|json|md)$/i;
+
+/** Bound the grep output (disclosed when hit) and the walk (defensive). */
+const MAX_HITS = 60;
+const MAX_FILES = 4000;
+
+/**
+ * Resolve each `@webjsdev/*` package's root + source dir from `cwd`. Locates the
+ * root by checking each `require.resolve.paths` node_modules dir on disk for
+ * `@webjsdev/<pkg>/package.json`, so it works for a real `node_modules` install
+ * AND the monorepo workspace (where the dir is a symlink to `packages/<pkg>`),
+ * and honours hoisting. This fs check is deliberate: `<pkg>/package.json` is
+ * blocked by `exports` for server/cli/ui, and the bin-only cli has no main
+ * entry, so neither `resolve('<pkg>/package.json')` nor `resolve('<pkg>')` is
+ * 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/*`).
+ *
+ * @param {string} cwd
+ * @param {{ exists: (p: string) => boolean }} fsDeps
+ * @returns {Array<{ pkg: string, root: string, src: string }>}
+ */
+export function resolveFrameworkRoots(cwd, fsDeps) {
+  const req = createRequire(join(cwd, '__webjs_mcp_source__.js'));
+  /** @type {Array<{ pkg: string, root: string, src: string }>} */
+  const out = [];
+  for (const pkg of FRAMEWORK_PACKAGES) {
+    // Find the package ROOT by checking each node_modules search path on disk,
+    // NOT via `require.resolve('<pkg>')` or `<pkg>/package.json`: a package whose
+    // `exports` omits `./package.json` (server/cli/ui) or that has no main entry
+    // (cli is a bin-only package) would otherwise be unreachable. The fs check
+    // bypasses both and still honours hoisting (the search paths include every
+    // parent `node_modules`).
+    const bases = req.resolve.paths(`@webjsdev/${pkg}`) || [];
+    let root = '';
+    for (const base of bases) {
+      const cand = join(base, '@webjsdev', pkg);
+      if (fsDeps.exists(join(cand, 'package.json'))) { root = cand; break; }
+    }
+    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.
+    const src = fsDeps.exists(join(root, 'src'))
+      ? join(root, 'src')
+      : fsDeps.exists(join(root, 'lib'))
+        ? join(root, 'lib')
+        : '';
+    if (src) out.push({ pkg, root, src });
+  }
+  return out;
+}
+
+/**
+ * Recursively list text-source files under `dir` (absolute paths), skipping
+ * `node_modules` / `dist` and bounded by {@link MAX_FILES}.
+ *
+ * @param {string} dir
+ * @param {{ readdir: (d: string) => Array<{ name: string, isDir: boolean }> }} deps
+ * @returns {string[]}
+ */
+export function walkSource(dir, deps) {
+  /** @type {string[]} */
+  const files = [];
+  /** @type {string[]} */
+  const stack = [dir];
+  while (stack.length && files.length < MAX_FILES) {
+    const d = stack.pop();
+    let entries = [];
+    try { entries = deps.readdir(d); } catch { continue; }
+    for (const e of entries) {
+      if (e.isDir) {
+        if (e.name === 'node_modules' || e.name === 'dist' || e.name === '.git') continue;
+        stack.push(join(d, e.name));
+      } else if (TEXT_EXT.test(e.name)) {
+        files.push(join(d, e.name));
+        if (files.length >= MAX_FILES) break;
+      }
+    }
+  }
+  return files.sort();
+}
+
+/**
+ * No-args / `package` mode: list the resolved packages and their `src/`
+ * top-level files (the entry points), so the agent has a map to grep or read.
+ *
+ * @param {{ roots: Array<{ pkg: string, root: string, src: string }>, readdir: Function }} deps
+ * @param {string} [pkgFilter]
+ * @returns {string}
+ */
+export function listSources(deps, pkgFilter) {
+  const roots = pkgFilter ? deps.roots.filter((r) => r.pkg === pkgFilter) : deps.roots;
+  if (!roots.length) {
+    return pkgFilter
+      ? `@webjsdev/${pkgFilter} is not installed/resolvable here. Resolvable: ${deps.roots.map((r) => r.pkg).join(', ') || '(none)'}`
+      : 'No @webjsdev/* packages resolvable from here (run inside a webjs app or the monorepo).';
+  }
+  const lines = ['webjs framework authored source (buildless; server-side this runs directly, and core ships a built browser dist/ that is excluded here). Read with `source({ path })` or search with `source({ query })`.', ''];
+  for (const r of roots) {
+    const dirName = r.src.split(sep).pop(); // 'src' for most, 'lib' for cli
+    let entries = [];
+    try { entries = deps.readdir(r.src); } catch { entries = []; }
+    const top = entries.filter((e) => !e.isDir && TEXT_EXT.test(e.name)).map((e) => e.name).sort();
+    const dirs = entries.filter((e) => e.isDir).map((e) => e.name).sort();
+    lines.push(`@webjsdev/${r.pkg}/${dirName}:`);
+    if (top.length) lines.push(`  files: ${top.map((f) => `${r.pkg}/${dirName}/${f}`).join(', ')}`);
+    if (dirs.length) lines.push(`  subdirs: ${dirs.join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * `query` mode: grep every resolved `src/` tree for the (case-insensitive)
+ * substring, returning bounded `[<pkg>/src/<rel>:<line>] <text>` hits. Discloses
+ * truncation rather than silently capping.
+ *
+ * @param {{ roots: Array<{ pkg: string, root: string, src: string }>, readFile: Function, readdir: Function }} deps
+ * @param {string} query
+ * @returns {Promise<string>}
+ */
+export async function grepSources(deps, query) {
+  const q = String(query).toLowerCase();
+  if (!q) return 'Provide a non-empty `query`.';
+  /** @type {string[]} */
+  const hits = [];
+  let capped = false;
+  outer: for (const r of deps.roots) {
+    for (const file of walkSource(r.src, deps)) {
+      let text = '';
+      try { text = await deps.readFile(file, 'utf8'); } catch { continue; }
+      if (!text.toLowerCase().includes(q)) continue; // fast skip whole file
+      const lines = text.split('\n');
+      const rel = relative(r.root, file).split(sep).join('/');
+      for (let i = 0; i < lines.length; i++) {
+        if (!lines[i].toLowerCase().includes(q)) continue;
+        if (hits.length >= MAX_HITS) { capped = true; break outer; }
+        hits.push(`[@webjsdev/${r.pkg}/${rel}:${i + 1}] ${lines[i].trim()}`);
+      }
+    }
+  }
+  if (!hits.length) return `No matches for "${query}" in the @webjsdev/* source.`;
+  if (capped) hits.push(`... (truncated at ${MAX_HITS} matches; narrow the query or read a file with \`path\`)`);
+  return hits.join('\n');
+}
+
+/** True when `p` is `base` itself or a descendant of it. */
+function within(base, p) {
+  return p === base || p.startsWith(base + sep);
+}
+
+/**
+ * `path` mode: read one AUTHORED-source file. Accepts `<pkg>/...` or
+ * `@webjsdev/<pkg>/...`. Scoped to the package's SOURCE dir (`src/`, or `lib/`
+ * for cli), so it serves only the authored source and NOT the built `dist/`
+ * browser bundle, `node_modules`, etc. Refuses any path that escapes the source
+ * dir lexically (`..`/absolute), and (when `deps.realpath` is provided)
+ * re-checks the symlink-resolved path so a symlink inside `src/` cannot reach
+ * outside. Read-only.
+ *
+ * @param {{ roots: Array<{ pkg: string, root: string, src: string }>, readFile: Function, realpath?: Function }} deps
+ * @param {string} path
+ * @returns {Promise<string>}
+ */
+export async function readSource(deps, path) {
+  const cleaned = String(path).replace(/^@webjsdev\//, '');
+  const segs = cleaned.split('/').filter(Boolean);
+  const pkg = segs[0];
+  const entry = deps.roots.find((r) => r.pkg === pkg);
+  if (!entry) {
+    return `Unknown or unresolvable package "${pkg || path}". Resolvable: ${deps.roots.map((r) => r.pkg).join(', ') || '(none)'}. Pass a path like server/src/ssr.js.`;
+  }
+  const abs = resolve(entry.root, segs.slice(1).join('/'));
+  const srcLabel = entry.src.split(sep).pop();
+  // Scope to the authored source dir, so dist/ (the built core browser bundle),
+  // package.json, node_modules, etc. are not readable; only `src/` (or cli `lib/`).
+  if (!within(entry.src, abs)) {
+    return `Refusing to read outside the @webjsdev/${pkg} authored source (only ${srcLabel}/ is exposed; the built dist/ is not).`;
+  }
+  // Defense in depth: a symlink inside the source dir must not resolve outside it.
+  if (deps.realpath) {
+    try {
+      if (!within(deps.realpath(entry.src), deps.realpath(abs))) {
+        return `Refusing to read outside the @webjsdev/${pkg} authored source (a symlink escapes ${srcLabel}/).`;
+      }
+    } catch { /* abs does not exist; the readFile below returns the not-a-file message */ }
+  }
+  // Legacy guard kept as a belt-and-suspenders against a root escape too.
+  if (abs !== entry.root && !abs.startsWith(entry.root + sep)) {
+    return `Refusing to read outside @webjsdev/${pkg} (path escapes the package root).`;
+  }
+  try {
+    return await deps.readFile(abs, 'utf8');
+  } catch {
+    return `Could not read ${path} (not a file under @webjsdev/${pkg}).`;
+  }
+}
+
+/**
+ * The `source` tool entry point. Dispatches on the args: `path` reads a file,
+ * `query` greps, otherwise (or with `package`) lists the packages. PURE given
+ * `deps` (`{ roots, readFile, readdir }`).
+ *
+ * @param {object} deps
+ * @param {{ query?: string, path?: string, package?: string }} [args]
+ * @returns {Promise<string>}
+ */
+export async function runSourceTool(deps, args) {
+  const a = args || {};
+  if (a.path) return readSource(deps, a.path);
+  if (a.query) return grepSources(deps, a.query);
+  return listSources(deps, a.package);
+}