@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/mcp/spec.ts

@@ -0,0 +1,86 @@
+// The `flawless-react mcp` subcommand's grammar and help, in one importless
+// module — the same reason `skills/spec.ts` and `docLine.ts` exist.
+//
+// main() dispatches on it, and `--check` has to parse the `flawless-react mcp`
+// lines in the README, the skills and the website, or a renamed subcommand
+// survives in documentation. Without this file that line would fall through to
+// parseArgs, read `mcp` as an entry glob, and PASS FOR THE WRONG REASON — the
+// failure mode skills/spec.ts exists to prevent. And `--help`/`--check` must
+// answer without importing core.ts and the TypeScript compiler behind it
+// (FR-031), so the server's own module cannot be the source of its help text.
+//
+// The tool names below are prose here, not a second registry: tests/mcp.test.ts
+// asserts this text and ALL_TOOLS name the same set, so the drift is a red test
+// rather than a stale help screen.
+
+export const MCP_SUBCOMMAND = "mcp";
+
+/** True when argv is an MCP-server invocation rather than a generation run. */
+export function isMcpArgv(argv: readonly string[]): boolean {
+  return argv[0] === MCP_SUBCOMMAND;
+}
+
+export interface McpCommand {
+  /** "serve" speaks the protocol on stdio; "help" prints the help and exits. */
+  verb: "serve" | "help";
+}
+
+/**
+ * Parse the arguments AFTER the `mcp` word (main() strips the subcommand).
+ *
+ * It takes no options, and says so rather than ignoring them: a host config
+ * carrying a typo'd flag would otherwise start a server that quietly did not
+ * honour it. The transport is fixed — stdio, one JSON-RPC 2.0 message per line —
+ * because it is the only one an MCP host configures without a plugin.
+ */
+export function parseMcpCommand(argv: readonly string[]): McpCommand {
+  const first = argv[0];
+  if (first === undefined) return { verb: "serve" };
+  if (first === "help" || first === "-h" || first === "--help") return { verb: "help" };
+  throw new Error(
+    `'mcp' takes no arguments — it serves JSON-RPC 2.0 on stdin/stdout. Got '${first}'. ` +
+      `Run 'flawless-react mcp --help' for the host configuration.`,
+  );
+}
+
+const USAGE = `flawless-react mcp — Model Context Protocol server over stdio
+
+  Speaks JSON-RPC 2.0, one message per line, on stdin and stdout. There is no
+  menu and no prompt: stdin belongs to the protocol, and anything a run prints
+  is captured per call so it can never mix with a frame.
+
+  Configure it in an MCP host (OpenCode, Claude Code, Codex, Cursor, ...):
+
+    { "mcpServers": { "flawless-react": { "command": "flawless-react", "args": ["mcp"] } } }
+
+  tools/list returns eight tools:
+
+    flawless_run             generate or refresh a suite (every CLI option), returning
+                             the --ci JSON blob and the child's exit code
+    flawless_skills          the embedded agent skills: status, or install
+    flawless_tasks           the task registry — ids, what each does, which run under --expo
+    flawless_reference       flag inventory, task ids, skill names, version
+    flawless_analyse         a component's analysed facts — props, hooks, state, guards,
+                             unresolved types — writing nothing
+    flawless_findings        the static perf and correctness rules over a file or glob,
+                             as file:line findings, writing nothing
+    flawless_project_status  Next.js / Expo detection plus what suite already exists
+    flawless_check_docs      parse documented flawless-react invocations, the way this
+                             repo's own docs lint does
+
+  Two planes, and the difference shows up in what a call costs. The run plane
+  spawns a flawless-react CHILD per call: the CLI's real exit codes, a killable
+  process group, per-call cwd and env, nothing kept between calls. The read plane
+  runs in this process, opens no other tool, spawns nothing and writes no files.
+
+  A nonzero exit is ALWAYS an isError result carrying the child's own output, and
+  every cap is announced. This tool does not report a false pass, over MCP included.
+
+Options:
+  -h, --help   Show this help instead of serving.
+`;
+
+/** The `mcp --help` text. */
+export function renderMcpHelp(): string {
+  return USAGE;
+}

package/src/mcp/support.ts

@@ -0,0 +1,268 @@
+// Shared plumbing for the MCP tool surface: result shapes, argument accessors
+// that fail loudly, and output caps that are always ANNOUNCED.
+//
+// Why the readers reject instead of coercing: an agent that typos `run_tests` as
+// `runTests` would otherwise get a run that silently skipped the suites and
+// reported it green — the exact false pass this repo scores itself on removing.
+// Same reasoning as parseArgs' `unknown flag` branch: an option that did nothing
+// is worse than a refusal, because the caller keeps believing it took effect.
+//
+// Why the caps announce themselves: a silent cut turns "the last 256KB of a 4MB
+// run log" into "the whole run log", and the reader has no way to tell.
+
+import path from "node:path";
+import type { JsonObject, JsonValue } from "./protocol.ts";
+
+export interface ToolContent {
+  type: "text";
+  text: string;
+}
+
+export interface ToolResult {
+  content: ToolContent[];
+  isError?: boolean;
+}
+
+export interface ToolDef {
+  name: string;
+  description: string;
+  inputSchema: JsonObject;
+  run(args: JsonObject): Promise<ToolResult>;
+}
+
+/** Argument misuse and honest failures. The server turns these into an `isError`
+ *  tool result (MCP's contract for "the tool ran and said no"); protocol-layer
+ *  misuse (unknown tool, malformed params) stays a JSON-RPC error, per spec. */
+export class ToolError extends Error {}
+
+export function ok(text: string): ToolResult {
+  return { content: [{ type: "text", text }] };
+}
+
+export function fail(text: string): ToolResult {
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+/** A structured answer. Tool content is a text channel, so the JSON IS the
+ *  payload — every read-plane tool returns it this way rather than inventing a
+ *  prose shape the caller would have to regex. */
+export function okJson(value: JsonValue): ToolResult {
+  return ok(JSON.stringify(value, null, 2));
+}
+
+/** Per-stream cap on captured child output. Tail-kept, because the tail of a run
+ *  is where the failure is, and the marker states the total. */
+export const OUTPUT_CAP = 256 * 1024;
+
+export function capText(s: string, cap = OUTPUT_CAP): { text: string; truncated: boolean } {
+  if (s.length <= cap) return { text: s, truncated: false };
+  return {
+    text:
+      `… flawless-mcp: output truncated, showing last ${cap} of ${s.length} chars …\n` +
+      s.slice(-cap),
+    truncated: true,
+  };
+}
+
+/**
+ * How many entry files a read-plane tool analyses in one call, and its ceiling.
+ *
+ * A glob over a whole app is hundreds of files and each one is a TypeScript
+ * parse, so an unbounded read tool is a request that cannot be answered. The
+ * default is a generous sample; hitting the cap is REPORTED (`entries_skipped`)
+ * rather than quietly narrowed — "findings for 50 components" must never read as
+ * "this app has 50 components".
+ */
+export const DEFAULT_MAX_ENTRIES = 50;
+export const MAX_ENTRIES_LIMIT = 500;
+
+// ------------------------------------------------------------ arg reading ----
+
+function bad(name: string, want: string, got: unknown): never {
+  const shown = typeof got === "string" ? JSON.stringify(got) : String(got);
+  throw new ToolError(`invalid argument "${name}": expected ${want}, got ${shown}`);
+}
+
+/** Required string, non-empty after trimming. */
+export function reqStr(args: JsonObject, name: string): string {
+  const v = args[name];
+  if (typeof v !== "string" || !v.trim()) bad(name, "non-empty string", v);
+  return v as string;
+}
+
+export function optStr(args: JsonObject, name: string): string | undefined {
+  const v = args[name];
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "string" || !v.trim()) bad(name, "non-empty string", v);
+  return v as string;
+}
+
+export function optInt(
+  args: JsonObject,
+  name: string,
+  min: number,
+  max: number,
+): number | undefined {
+  const v = args[name];
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "number" || !Number.isInteger(v) || v < min || v > max) {
+    bad(name, `integer ${min}..${max}`, v);
+  }
+  return v as number;
+}
+
+export function optBool(args: JsonObject, name: string): boolean | undefined {
+  const v = args[name];
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "boolean") bad(name, "boolean", v);
+  return v as boolean;
+}
+
+/** One value from a closed set. The rejection lists the choices, because a
+ *  caller that has never seen the schema is exactly the one that needs them. */
+export function optEnum<X extends string>(
+  args: JsonObject,
+  name: string,
+  choices: readonly X[],
+): X | undefined {
+  const v = args[name];
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "string" || !choices.includes(v as X)) {
+    bad(name, `one of: ${choices.join(", ")}`, v);
+  }
+  return v as X;
+}
+
+export function reqEnum<X extends string>(
+  args: JsonObject,
+  name: string,
+  choices: readonly X[],
+): X {
+  const v = optEnum(args, name, choices);
+  if (v === undefined) throw new ToolError(`missing required argument "${name}"`);
+  return v;
+}
+
+/** A string array whose members must all belong to a closed set (task ids,
+ *  severities). Members are checked one by one so the rejection names the bad
+ *  one instead of the whole array. */
+export function optEnumArray<X extends string>(
+  args: JsonObject,
+  name: string,
+  choices: readonly X[],
+): X[] | undefined {
+  const v = args[name];
+  if (v === undefined || v === null) return undefined;
+  if (!Array.isArray(v)) bad(name, `array of: ${choices.join(", ")}`, v);
+  return (v as unknown[]).map((item) => {
+    if (typeof item !== "string" || !choices.includes(item as X)) {
+      throw new ToolError(
+        `invalid "${name}" member: expected one of ${choices.join(", ")}, got ${JSON.stringify(item)}`,
+      );
+    }
+    return item as X;
+  });
+}
+
+export function optStrArray(args: JsonObject, name: string): string[] | undefined {
+  const v = args[name];
+  if (v === undefined || v === null) return undefined;
+  if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) bad(name, "array of strings", v);
+  return v as string[];
+}
+
+/** Flat string map (env vars). Rejects non-string values loudly: stringifying
+ *  `{…}` into "[object Object]" would poison a run whose failure the caller
+ *  then cannot explain. */
+export function optStrMap(args: JsonObject, name: string): Record<string, string> | undefined {
+  const v = args[name];
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "object" || Array.isArray(v)) bad(name, "object of string values", v);
+  const out: Record<string, string> = {};
+  for (const [k, item] of Object.entries(v as JsonObject)) {
+    if (typeof item !== "string") {
+      throw new ToolError(`invalid "${name}.${k}": expected string, got ${String(item)}`);
+    }
+    out[k] = item;
+  }
+  return out;
+}
+
+/**
+ * A JSON object, returned as JSON text — used once, for `flawless_reference`,
+ * where the point is that the caller parses it.
+ *
+ * Kept out of the flags mapping on purpose: the value the CLI receives for
+ * `--props` is JSON text, and re-serialising a parsed copy would put a second,
+ * drift-prone copy of that contract between the agent and parsePropsJson.
+ */
+export function optJsonText(args: JsonObject, name: string): string | undefined {
+  const v = args[name];
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "object") bad(name, "JSON object", v);
+  return JSON.stringify(v);
+}
+
+/**
+ * String OR true — the shape `nextjs`/`expo` take, mirroring the flags' own
+ * optional value (`--nextjs` alone means the current directory, `--nextjs <p>`
+ * names a root). A bare `true` is accepted so a caller that read the schema as
+ * "boolean" is not refused for expressing the same intent.
+ */
+export function optStrOrTrue(args: JsonObject, name: string): string | true | undefined {
+  const v = args[name];
+  if (v === undefined || v === null) return undefined;
+  if (v === true) return true;
+  if (typeof v !== "string" || !v.trim()) bad(name, "path string or true", v);
+  return v as string;
+}
+
+/**
+ * Unknown keys are rejected, not ignored, and required keys are checked first.
+ *
+ * The schema already says `additionalProperties: false`, but a host is free to
+ * send what it likes, and a server that quietly drops `{"run_test": true}` has
+ * just reported a green suite for a run that never executed one.
+ */
+export function requireKeys(
+  args: JsonObject,
+  allowed: readonly string[],
+  required: readonly string[] = [],
+): void {
+  for (const name of required) {
+    if (args[name] === undefined || args[name] === null) {
+      throw new ToolError(`missing required argument "${name}"`);
+    }
+  }
+  for (const key of Object.keys(args)) {
+    if (!allowed.includes(key)) {
+      throw new ToolError(`unknown argument "${key}" — allowed: ${allowed.join(", ")}`);
+    }
+  }
+}
+
+// ------------------------------------------------------------- path roots ----
+
+/**
+ * The project directory a call operates on, absolute.
+ *
+ * Every path argument is resolved against this instead of the server changing
+ * its own working directory: one agent driving two repositories must be able to
+ * point calls at different roots without the second call silently reading the
+ * first one's files.
+ */
+export function rootArg(args: JsonObject): string {
+  return path.resolve(optStr(args, "root") ?? ".");
+}
+
+/** Resolve a caller-supplied path against the call's root. */
+export function resolveIn(root: string, p: string): string {
+  return path.isAbsolute(p) ? path.normalize(p) : path.resolve(root, p);
+}
+
+/** A path made relative to the call's root, so output is stable across machines
+ *  and the caller is not asked to read absolute filesystem noise. */
+export function relativeTo(root: string, p: string): string {
+  const rel = path.relative(root, p);
+  return rel && !rel.startsWith("..") ? rel : p;
+}

package/src/mcp/tools.ts

@@ -0,0 +1,75 @@
+// The tool registry: one list, ordered the way `tools/list` should present it.
+//
+// Why the composition lives here and not in server.ts: the tool set is a claim
+// about the product (docs/mcp.md and the README both name these eight), and
+// tests/mcp.test.ts asserts that claim against THIS array. A registry the server
+// assembled inline would be reachable only by speaking JSON-RPC at a live child,
+// which is a heavier way to learn a name drifted than importing a constant.
+//
+// Order is the documentation order — the two tools that change something first,
+// then the reference trio, then the three that read a project — so a host that
+// lists tools in arrival order shows the same story the docs tell.
+
+import { ANALYSIS_TOOLS } from "./analysisTools.ts";
+import { INFO_TOOLS } from "./infoTools.ts";
+import type { JsonObject, JsonValue } from "./protocol.ts";
+import { RUN_TOOLS } from "./runTools.ts";
+import { type ToolDef, ToolError, type ToolResult } from "./support.ts";
+
+export const ALL_TOOLS: ToolDef[] = [...RUN_TOOLS, ...INFO_TOOLS, ...ANALYSIS_TOOLS];
+
+/** The `tools/list` result body, in the shape MCP prescribes. */
+export function toolsList(): JsonValue {
+  return {
+    tools: ALL_TOOLS.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+    })),
+  };
+}
+
+export function toolByName(name: string): ToolDef | undefined {
+  return ALL_TOOLS.find((t) => t.name === name);
+}
+
+/**
+ * Run one tool after checking its arguments against the schema it publishes.
+ *
+ * The check belongs HERE, on the one path every call takes, and not inside each
+ * tool: a schema is the contract a host codes against, so a key the schema does
+ * not name must not be silently dropped on the floor. `{"run_test": true}` typoed
+ * into `flawless_run` would otherwise return an exit 0 for a run that never
+ * executed a suite — a false pass reached through the protocol. Checking centrally
+ * is also what lets a tool that genuinely takes no arguments (`flawless_tasks`,
+ * `flawless_reference`) stay a one-line `run()` and still refuse junk.
+ *
+ * Keys, presence and shape only. Value semantics — a task id that exists, a heap
+ * mode in the closed set, an integer inside its range — stay with the argument
+ * readers in support.ts, whose rejections name the allowed set; duplicating that
+ * here would put a second, drift-prone copy of each contract in the way.
+ */
+export async function invokeTool(tool: ToolDef, args: JsonObject): Promise<ToolResult> {
+  const props = tool.inputSchema.properties;
+  const allowed =
+    props !== undefined && typeof props === "object" && props !== null
+      ? Object.keys(props as JsonObject)
+      : [];
+  const strict = tool.inputSchema.additionalProperties === false;
+  const required = Array.isArray(tool.inputSchema.required) ? tool.inputSchema.required : [];
+
+  for (const name of required) {
+    if (typeof name !== "string") continue;
+    if (args[name] === undefined || args[name] === null) {
+      throw new ToolError(`missing required argument "${name}"`);
+    }
+  }
+  for (const key of Object.keys(args)) {
+    if (strict && !allowed.includes(key)) {
+      throw new ToolError(
+        `unknown argument "${key}" for ${tool.name} — allowed: ${allowed.length ? allowed.join(", ") : "none"}`,
+      );
+    }
+  }
+  return tool.run(args);
+}

package/src/nextjs/apiRoutes.ts

@@ -0,0 +1,116 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import type { NextjsApiRoute, NextjsRouter } from "../types.ts";
+
+const HTTP_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]);
+
+export async function walkApiRoutes(
+  router: NextjsRouter,
+  routerRoot: string,
+): Promise<NextjsApiRoute[]> {
+  if (router === "app") return walkAppRouterApi(path.join(routerRoot, "api"));
+  return walkPagesRouterApi(path.join(routerRoot, "api"));
+}
+
+async function walkAppRouterApi(apiDir: string): Promise<NextjsApiRoute[]> {
+  if (!existsSync(apiDir)) return [];
+  const out: NextjsApiRoute[] = [];
+  const glob = new Bun.Glob("**/route.{ts,tsx,js,jsx,mjs}");
+  for await (const rel of glob.scan({ cwd: apiDir })) {
+    const abs = path.join(apiDir, rel);
+    const segments = path
+      .dirname(rel)
+      .split(path.sep)
+      .filter((s) => s !== ".");
+    // Route groups map to an empty segment — drop them or the path grows a `//`.
+    const urlPath = `/api/${segments.map(appRouterSegment).filter(Boolean).join("/")}`;
+    const methods = extractAppRouterMethods(abs);
+    if (methods.length === 0) continue;
+    out.push({
+      path: stripTrailingSlash(urlPath),
+      methods,
+      file: abs,
+    });
+  }
+  return out;
+}
+
+async function walkPagesRouterApi(apiDir: string): Promise<NextjsApiRoute[]> {
+  if (!existsSync(apiDir)) return [];
+  const out: NextjsApiRoute[] = [];
+  const glob = new Bun.Glob("**/*.{ts,tsx,js,jsx,mjs}");
+  for await (const rel of glob.scan({ cwd: apiDir })) {
+    const abs = path.join(apiDir, rel);
+    const noExt = rel.replace(/\.(ts|tsx|js|jsx|mjs)$/, "");
+    let segments = noExt.split(path.sep);
+    if (segments[segments.length - 1] === "index") segments = segments.slice(0, -1);
+    const urlPath = `/api/${segments.map(pagesRouterSegment).filter(Boolean).join("/")}`;
+    out.push({
+      path: stripTrailingSlash(urlPath),
+      methods: ["GET", "POST", "PUT", "DELETE", "PATCH"],
+      file: abs,
+    });
+  }
+  return out;
+}
+
+function appRouterSegment(seg: string): string {
+  // [id] -> {id}, [...slug] -> {slug} (catch-all collapses to one path-param in swagger).
+  if (seg.startsWith("[[...") && seg.endsWith("]]")) {
+    return `{${seg.slice(5, -2)}}`;
+  }
+  if (seg.startsWith("[...") && seg.endsWith("]")) {
+    return `{${seg.slice(4, -1)}}`;
+  }
+  if (seg.startsWith("[") && seg.endsWith("]")) {
+    return `{${seg.slice(1, -1)}}`;
+  }
+  // Route groups (parenthesised) don't appear in the URL.
+  if (seg.startsWith("(") && seg.endsWith(")")) return "";
+  return seg;
+}
+
+function pagesRouterSegment(seg: string): string {
+  return appRouterSegment(seg);
+}
+
+function stripTrailingSlash(p: string): string {
+  return p.length > 1 && p.endsWith("/") ? p.slice(0, -1) : p;
+}
+
+function extractAppRouterMethods(file: string): string[] {
+  let source = "";
+  try {
+    const fs = require("node:fs") as typeof import("node:fs");
+    source = fs.readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const found = new Set<string>();
+  const visit = (node: ts.Node): void => {
+    // export const GET = ...
+    if (ts.isVariableStatement(node) && hasExportModifier(node)) {
+      for (const d of node.declarationList.declarations) {
+        if (ts.isIdentifier(d.name) && HTTP_METHODS.has(d.name.text)) {
+          found.add(d.name.text);
+        }
+      }
+    }
+    // export function GET() { ... }
+    if (ts.isFunctionDeclaration(node) && hasExportModifier(node) && node.name) {
+      if (HTTP_METHODS.has(node.name.text)) found.add(node.name.text);
+    }
+    // export async function GET() { ... }
+    // (same node shape; handled above)
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return [...found].sort();
+}
+
+function hasExportModifier(node: ts.HasModifiers): boolean {
+  const mods = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+  return Boolean(mods?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword));
+}