@webjsdev/mcp 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/mcp",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "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": {
@@ -13,6 +13,9 @@
     "./check-report": {
       "default": "./src/check-report.js"
     },
+    "./routes-report": {
+      "default": "./src/routes-report.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [

package/resources/AGENTS.md

@@ -462,9 +462,12 @@ webjs dev    [--port N] [--no-hot] # dev server with live reload (node --watch o
 webjs start  [--port N]            # prod server; source IS the runtime, plain HTTP/1.1 (reverse-proxy for TLS + HTTP/2). Runs webjs.start.before first (#550)
 webjs test   [--server] [--browser] [--watch]
 webjs check  [--rules] [--json]    # correctness validator (report-only, no autofix); --json for an agent loop
+webjs routes [--json] [--table] [--no-headers]   # print the route table (path / owner file / methods, #975). Default tree; --json is byte-identical to the MCP list_routes tool; --no-headers drops the --table header for piping
 webjs mcp                          # read-only MCP: routes, actions (RPC hashes), components, check
-webjs doctor                       # project-health checklist (incl. a framework-resolve check that warns when @webjsdev/core can't be resolved from the app dir, the fresh-worktree-without-node_modules trap #954; a page/layout elision advisory); non-zero exit on a hard fail
+webjs doctor [--json] [--strict]   # project-health checklist (incl. a framework-resolve check that warns when @webjsdev/core can't be resolved from the app dir, the fresh-worktree-without-node_modules trap #954; a page/layout elision advisory); non-zero exit on a hard fail. --json emits `{ results, summary }` (results is the DoctorResult[], each carrying a stable code); --strict also fails the exit on warnings (#975)
 webjs types                        # generate .webjs/routes.d.ts (typed Route union + per-route params, #258)
+webjs version                      # print the installed @webjsdev/cli version (also: webjs --version / -v, #975)
+webjs help   [command]             # full usage banner, or per-command usage + Options + Examples (e.g. webjs help routes, #975). Flag forms: webjs --help / -h (banner), webjs <command> --help / -h (that command). typecheck/db/ui --help forward to their wrapped tool; an unknown topic exits 1
 webjs typecheck [tsc args...]      # the project's own tsc --noEmit
 webjs create <name> [--template api|saas]
 webjs db <generate|migrate|push|studio|seed>   # wraps drizzle-kit (+ runs db/seed.server.ts)

package/src/mcp.js

@@ -33,6 +33,7 @@ import {
   getPrompt,
 } from './mcp-docs.js';
 import { resolveFrameworkRoots, runSourceTool } from './mcp-source.js';
+import { projectRoutes } from './routes-report.js';
 
 const PROTOCOL_VERSION = '2024-11-05';
 
@@ -274,22 +275,6 @@ export function extractActionConfig(src) {
   };
 }
 
-/**
- * The literal URL path for a page/api directory: `blog/[slug]` -> `/blog/[slug]`,
- * the root `.` -> `/`. Route groups `(group)` and `_private` segments drop, the
- * same normalization `buildRouteTable` uses for matching.
- *
- * @param {string} routeDir  POSIX-style, `.` for the app root.
- * @returns {string}
- */
-function routePathFromDir(routeDir) {
-  if (!routeDir || routeDir === '.') return '/';
-  const segs = routeDir
-    .split('/')
-    .filter((s) => !(s.startsWith('(') && s.endsWith(')')) && !s.startsWith('_'));
-  return segs.length ? '/' + segs.join('/') : '/';
-}
-
 /**
  * The tool runners. Each is async, takes `(appDir)`, and returns a plain
  * JSON-serialisable projection of an existing server data function. All are
@@ -311,34 +296,10 @@ export function makeToolRunners(deps) {
   return {
     async list_routes(appDir) {
       const table = await buildRouteTable(appDir);
-      const pages = await Promise.all(
-        table.pages.map(async (r) => {
-          /** @type {{ path: string, file: string, dynamic?: boolean, params?: string[] }} */
-          const out = {
-            path: routePathFromDir(r.routeDir),
-            file: relative(appDir, r.file),
-          };
-          if (r.paramNames && r.paramNames.length) {
-            out.dynamic = true;
-            out.params = r.paramNames;
-          }
-          return out;
-        }),
-      );
-      const apis = await Promise.all(
-        table.apis.map(async (r) => {
-          let methods = [];
-          try {
-            methods = extractRouteMethods(await readFile(r.file, 'utf8'));
-          } catch {}
-          return {
-            path: routePathFromDir(r.routeDir),
-            file: relative(appDir, r.file),
-            methods,
-          };
-        }),
-      );
-      return { pages, apis };
+      // The projection lives in `routes-report.js` so `list_routes` and the CLI
+      // `webjs routes --json` stay byte-identical (#975), the same split as
+      // `check-report.js` for the `check` tool.
+      return projectRoutes(table, { appDir, readFile, extractRouteMethods });
     },
 
     async list_actions(appDir) {

package/src/routes-report.js

@@ -0,0 +1,90 @@
+/**
+ * Shared JSON projector for the app route table (#975).
+ *
+ * `webjs routes --json` and the `webjs mcp` server's `list_routes` tool BOTH
+ * return the identical shape, so the projection lives here once (the same
+ * pattern as `check-report.js` for `check --json` / the MCP `check` tool). The
+ * input is the raw `RouteTable` from `buildRouteTable(appDir)` (the ONE route
+ * walker, reused, never re-implemented); the output is a stable, agent-friendly
+ * `{ pages, apis }` shape.
+ *
+ * This module is a LEAF: it imports only `node:path` and receives the two
+ * effectful dependencies it needs (`readFile` to read a `route.{js,ts}` file's
+ * source, `extractRouteMethods` to lexically pull its HTTP-verb exports) as
+ * injected arguments, the same dependency-injection style the MCP tool runners
+ * already use. That keeps it free of any `@webjsdev/mcp` main-entry import (so
+ * the CLI can pull just this projector without loading the MCP server) and free
+ * of a cycle with `mcp.js`.
+ *
+ * @module routes-report
+ */
+
+import { relative } from 'node:path';
+
+/**
+ * The literal URL path for a page/api directory: `blog/[slug]` -> `/blog/[slug]`,
+ * the root `.` -> `/`. Route groups `(group)` and `_private` segments drop, the
+ * same normalization `buildRouteTable` uses for matching.
+ *
+ * @param {string} routeDir  POSIX-style, `.` for the app root.
+ * @returns {string}
+ */
+export function routePathFromDir(routeDir) {
+  if (!routeDir || routeDir === '.') return '/';
+  const segs = routeDir
+    .split('/')
+    .filter((s) => !(s.startsWith('(') && s.endsWith(')')) && !s.startsWith('_'));
+  return segs.length ? '/' + segs.join('/') : '/';
+}
+
+/**
+ * @typedef {{ path: string, file: string, dynamic?: boolean, params?: string[] }} PageRouteReport
+ * @typedef {{ path: string, file: string, methods: string[] }} ApiRouteReport
+ * @typedef {{ pages: PageRouteReport[], apis: ApiRouteReport[] }} RoutesReport
+ */
+
+/**
+ * Project a `RouteTable` into the structured `{ pages, apis }` report shared by
+ * `webjs routes --json` and the MCP `list_routes` tool. Pure over its inputs
+ * (given the same table + deps it produces the same output); the only I/O is
+ * the injected `readFile` reading each `route.{js,ts}` source to extract its
+ * methods. A `route.{js,ts}` that cannot be read degrades to an empty method
+ * list rather than throwing, so one unreadable file never sinks the whole
+ * report.
+ *
+ * @param {{ pages: any[], apis: any[] }} table  the `buildRouteTable(appDir)` result
+ * @param {{
+ *   appDir: string,
+ *   readFile: (path: string, enc: string) => Promise<string>,
+ *   extractRouteMethods: (src: string) => string[],
+ * }} deps
+ * @returns {Promise<RoutesReport>}
+ */
+export async function projectRoutes(table, { appDir, readFile, extractRouteMethods }) {
+  const pages = table.pages.map((r) => {
+    /** @type {PageRouteReport} */
+    const out = {
+      path: routePathFromDir(r.routeDir),
+      file: relative(appDir, r.file),
+    };
+    if (r.paramNames && r.paramNames.length) {
+      out.dynamic = true;
+      out.params = r.paramNames;
+    }
+    return out;
+  });
+  const apis = await Promise.all(
+    table.apis.map(async (r) => {
+      let methods = [];
+      try {
+        methods = extractRouteMethods(await readFile(r.file, 'utf8'));
+      } catch {}
+      return {
+        path: routePathFromDir(r.routeDir),
+        file: relative(appDir, r.file),
+        methods,
+      };
+    }),
+  );
+  return { pages, apis };
+}