@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/mcp/infoTools.ts

@@ -0,0 +1,135 @@
+// The read plane's reference tools: what the CLI can do, as data, computed from
+// the same tables the CLI renders its help from.
+//
+// These exist because an agent's alternative is guessing a flag name from a
+// conversation and finding out from an exit 2. Each one reads a table that
+// already exists — cliFlags.ts's inventory, the task registry, the embedded skill
+// names — so there is no second copy here to drift, which is the defect this
+// repo's own docs lint was written to catch. All three open no project, spawn
+// nothing, and write nothing.
+
+import { checkLines } from "../cli.ts";
+import { FLAGS, type FlagDoc, MAINTENANCE_FLAGS } from "../cliFlags.ts";
+import { EXPO_IMPLEMENTED } from "../expo/refusal.ts";
+import { SKILL_NAMES } from "../skills/spec.ts";
+import { ALL_TASK_IDS, TASKS } from "../tasks/index.ts";
+import { VERSION } from "../version.ts";
+import type { JsonObject, JsonValue } from "./protocol.ts";
+import { okJson, reqStr, requireKeys, type ToolDef } from "./support.ts";
+
+// ------------------------------------------------------------ flawless_tasks ----
+
+const flawlessTasks: ToolDef = {
+  name: "flawless_tasks",
+  description:
+    "The task registry: every id `tasks` accepts, what it emits, and whether it runs under Expo " +
+    "mode or refuses by design (perf-harness is measured-and-declined there — a browser host " +
+    "cannot mount a route screen). Read-only, no project needed. Consult this before choosing " +
+    "tasks rather than guessing an id: an unknown one is a usage error, exit 2.",
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  async run() {
+    return okJson({
+      task_ids: [...ALL_TASK_IDS],
+      tasks: TASKS.map((t) => ({
+        id: t.id,
+        label: t.label,
+        description: t.description,
+        needs_tree: t.needsTree,
+        runs_under_expo: EXPO_IMPLEMENTED.includes(t.id),
+      })),
+      expo_note:
+        "A task that is not marked runs_under_expo refuses under --expo with its reason rather " +
+        "than emitting DOM artefacts for a React Native project.",
+    });
+  },
+};
+
+// -------------------------------------------------------- flawless_reference ----
+
+/** FlagDoc → JSON. `summary` is a string OR continuation lines in the table, and
+ *  a caller should not have to handle both, so it is always an array here. */
+function flagJson(flags: readonly FlagDoc[]) {
+  return flags.map((f) => ({
+    name: f.name,
+    ...(f.alias ? { alias: f.alias } : {}),
+    ...(f.value ? { value: f.value } : {}),
+    summary: Array.isArray(f.summary) ? f.summary : [f.summary],
+  }));
+}
+
+const flawlessReference: ToolDef = {
+  name: "flawless_reference",
+  description:
+    "The CLI as data: every flag with its value form and summary, the maintenance flags " +
+    "(--help, --version, --flags, --check), the task ids, the embedded skill names and the " +
+    "version. Rendered from the same inventory --help and --flags print, so it cannot disagree " +
+    "with the binary. Read-only, no project needed. Use it to build an invocation instead of " +
+    "recalling flag names — the closed sets (--roots, --heaps) are where guessed arguments fail.",
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  async run() {
+    return okJson({
+      version: VERSION,
+      usage:
+        "flawless-react [entry] [flags] | flawless-react skills <list|install> | flawless-react mcp",
+      flags: flagJson(FLAGS),
+      maintenance_flags: flagJson(MAINTENANCE_FLAGS),
+      task_ids: [...ALL_TASK_IDS],
+      skill_names: [...SKILL_NAMES],
+      exits: {
+        "0": "success",
+        "1": "a task failed, or a suite failed under run_tests",
+        "2": "usage error — bad flag, unknown task id, unresolvable props",
+      },
+      ci_contract:
+        "With --ci the run is non-interactive and stdout is exactly one JSON document: " +
+        "{exitCode, outDir, results, keptScripts, testRun?, errors?}. A usage error exits 2 with " +
+        "its reason on stderr and no JSON.",
+    });
+  },
+};
+
+// ------------------------------------------------------- flawless_check_docs ----
+
+const CHECK_DOCS_ARGS = ["text"] as const;
+
+const flawlessCheckDocs: ToolDef = {
+  name: "flawless_check_docs",
+  description:
+    "Parse documented flawless-react invocations without running them — the same checker this " +
+    "repo's docs lint runs against README, the skills and the website. Give it prose or fenced " +
+    "shell blocks: every line that invokes flawless-react is parsed for unknown flags, unknown " +
+    "task ids and closed-set values, and lines that invoke something else are counted as skipped " +
+    "rather than passed. Returns {checked, skipped, problems}. Read-only. A corpus with " +
+    "checked=0 checked nothing — that is a gap in the extractor, not a pass.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      text: {
+        type: "string",
+        description:
+          "Documentation text. Shell-runner prefixes, env assignments, quotes and trailing # comments are stripped.",
+      },
+    },
+    required: ["text"],
+    additionalProperties: false,
+  },
+  async run(args) {
+    requireKeys(args, CHECK_DOCS_ARGS, ["text"]);
+    const report = checkLines(reqStr(args, "text"));
+    const out: JsonObject = {
+      checked: report.checked,
+      skipped: report.skipped,
+      problems: report.problems.map((p): JsonValue => ({ line: p.line, problem: p.problem })),
+    };
+    if (report.checked === 0) {
+      out.note = "nothing was checked: no line in the text invoked flawless-react";
+    }
+    // An example that does not parse is a broken documented command, and the
+    // caller needs that to be a failure, not a field they might forget to read.
+    return report.problems.length === 0
+      ? okJson(out)
+      : { content: [{ type: "text", text: JSON.stringify(out, null, 2) }], isError: true };
+  },
+};
+
+export const INFO_TOOLS: ToolDef[] = [flawlessTasks, flawlessReference, flawlessCheckDocs];

package/src/mcp/protocol.ts

@@ -0,0 +1,130 @@
+// JSON-RPC 2.0 message layer for the MCP stdio transport.
+//
+// The wire contract (MCP stdio): one JSON message per line, `\n` delimited, no
+// embedded newlines inside a message. This is the whole protocol surface
+// flawless-react needs — hand-rolled because the shipped artifact is a compiled
+// Bun binary whose bundle stays dependency-free, so the official SDK is not an
+// option inside it (the same rule that keeps src/ free of imports in
+// cliFlags.ts and docLine.ts).
+//
+// Honest framing: a line that is not valid JSON gets a -32700 response with
+// id:null, exactly as JSON-RPC prescribes, and the connection keeps serving.
+// Dropping it silently would let a partially-written message vanish without the
+// client ever learning its call was never parsed — the false pass, in the one
+// place where a pass is a frame the host is about to trust.
+
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+export type JsonObject = { [k: string]: JsonValue };
+
+export interface RpcRequest {
+  jsonrpc: "2.0";
+  id: number | string;
+  method: string;
+  params?: JsonObject;
+}
+
+export interface RpcNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: JsonObject;
+}
+
+/** parseLine's discriminated result: a frame is EITHER a parsed message OR the
+ *  -32700/-32600 response the server owes the client — never a bag of optional
+ *  fields the dispatcher has to guess through. */
+export type ParsedLine =
+  | { kind: "request"; request: RpcRequest }
+  | { kind: "notification"; notification: RpcNotification }
+  | { kind: "invalid"; response: RpcResponse };
+
+export interface RpcError {
+  code: number;
+  message: string;
+  data?: JsonValue;
+}
+
+export interface RpcResponse {
+  jsonrpc: "2.0";
+  id: number | string | null;
+  result?: JsonValue;
+  error?: RpcError;
+}
+
+// The standard JSON-RPC codes MCP hosts expect, plus the one MCP reserves for
+// "the server understood and refuses" (used here for the not-initialized guard).
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+export const SERVER_NOT_INITIALIZED = -32002;
+
+export function isRequest(v: unknown): v is RpcRequest {
+  const o = v as Partial<RpcRequest> | null;
+  return (
+    typeof v === "object" &&
+    o !== null &&
+    o.jsonrpc === "2.0" &&
+    typeof o.method === "string" &&
+    (typeof o.id === "number" || typeof o.id === "string")
+  );
+}
+
+export function isNotification(v: unknown): v is RpcNotification {
+  const o = v as (Partial<RpcNotification> & { id?: unknown }) | null;
+  return (
+    typeof v === "object" &&
+    o !== null &&
+    o.jsonrpc === "2.0" &&
+    typeof o.method === "string" &&
+    o.id === undefined
+  );
+}
+
+export function reply(id: number | string | null, result: JsonValue): RpcResponse {
+  return { jsonrpc: "2.0", id, result };
+}
+
+export function fail(id: number | string | null, error: RpcError): RpcResponse {
+  return { jsonrpc: "2.0", id, error };
+}
+
+/**
+ * Parse one framed line into a discriminated result.
+ *
+ * A frame that is not valid JSON, or JSON without a string method, gets the
+ * prescribed error response (id:null) rather than silent loss: the client must
+ * learn its call was never understood.
+ */
+export function parseLine(line: string): ParsedLine {
+  let value: unknown;
+  try {
+    value = JSON.parse(line);
+  } catch {
+    return {
+      kind: "invalid",
+      response: fail(null, { code: PARSE_ERROR, message: "parse error: line is not valid JSON" }),
+    };
+  }
+  if (isRequest(value)) return { kind: "request", request: value };
+  if (isNotification(value)) return { kind: "notification", notification: value };
+  return {
+    kind: "invalid",
+    response: fail(null, {
+      code: INVALID_REQUEST,
+      message: "expected a JSON-RPC 2.0 request or notification with a string method",
+    }),
+  };
+}
+
+export function serialize(message: RpcResponse): string {
+  // JSON.stringify NEVER emits a raw newline, so one message is always one line
+  // — the only framing rule this transport has.
+  return `${JSON.stringify(message)}\n`;
+}
+
+// Reserved for genuine dispatch bugs; every handler path currently in server.ts
+// has a defined answer, so nothing reaches it yet. Kept exported-and-void rather
+// than deleted: the next method added needs the code, and a handler that has no
+// answer owes -32603, not a thrown stack.
+void INTERNAL_ERROR;

package/src/mcp/run.ts

@@ -0,0 +1,269 @@
+// The run plane of the MCP surface: every tool that GENERATES, INSTALLS or runs
+// suites spawns a flawless-react CHILD process per call.
+//
+// Why a child is structural, not cosmetic: core.ts's test runner spawns the
+// generated Playwright/Vitest suites with `stdout: "inherit"` unless the run is
+// quiet, and the scaffold narrates progress to stdout. In-process execution
+// would write raw bytes into the protocol's stdout and corrupt JSON-RPC — the
+// one failure an MCP server cannot survive, because the host reads the stream
+// for framing. The child boundary also buys the three things a long generation
+// job actually needs: the CLI's real exit-code contract (0/1/2, including the
+// `exitCode` inside the --ci blob), a killable process group for a suite that
+// hangs, and per-call cwd/env with nothing kept between calls.
+//
+// Honest-failure contract (the repo's first design rule, ported to MCP): a
+// nonzero child exit or a killed timeout is an isError result carrying the
+// child's own output — never a success that measured nothing. Output caps are
+// always announced, never silent.
+
+import path from "node:path";
+import type { JsonObject, JsonValue } from "./protocol.ts";
+import { capText, fail, ok, optInt, optStr, optStrMap, type ToolResult } from "./support.ts";
+
+/** Interpreter names. When `process.execPath` is one of these, the CLI was
+ *  started as `bun <script>`, and re-invoking means naming the script again. */
+const RUNTIMES = new Set(["bun", "bunx", "node", "nodejs", "deno"]);
+
+/**
+ * How to re-invoke THIS flawless-react from inside itself.
+ *
+ * Measured on Bun 1.4 for all three shipped shapes (a probe, not an assumption —
+ * the compiled binary reports argv differently and a wrong guess here means every
+ * run tool spawns the wrong thing):
+ *
+ *   `bun src/cli.ts mcp`        execPath=<bun>  argv[1]=<abs>/src/cli.ts
+ *   `bin/flawless-react mcp`    execPath=<bun>  argv[1]=<abs>/bin/flawless-react
+ *                               (the npm shim is extensionless, so an extension
+ *                               test on argv[1] — the obvious heuristic — picks
+ *                               the WRONG branch here)
+ *   compiled binary             execPath=<the binary>  argv[0]="bun"
+ *                               argv[1]=Bun.main="/$bunfs/root/flawless-react"
+ *
+ * So: the virtual-fs path proves we are the binary itself; otherwise a runtime
+ * execPath proves we must re-name the script.
+ */
+export function flawlessSpawnArgv(): string[] {
+  const script = process.argv[1] ?? "";
+  if (script.startsWith("/$bunfs/")) return [process.execPath];
+  if (RUNTIMES.has(path.basename(process.execPath))) {
+    if (!script) {
+      throw new Error(
+        "flawless-mcp: cannot re-invoke flawless-react — no script path in argv[1] and " +
+          `execPath is the runtime (${process.execPath}). Start the server as a compiled ` +
+          "binary or as `bun src/cli.ts mcp`.",
+      );
+    }
+    return [process.execPath, script];
+  }
+  return [process.execPath];
+}
+
+export interface ChildRun {
+  code: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+/** Generation over a whole app's glob is analysis + file writing; with
+ *  `run_tests` it is Playwright and Vitest on top. Ten minutes is the default
+ *  because that is what a component-level run costs, and the timeout is a
+ *  watchdog with a named deadline, not a budget the tool silently enforces. */
+export const DEFAULT_TIMEOUT_MS = 600_000;
+export const TIMEOUT_MIN = 1_000;
+export const TIMEOUT_MAX = 4 * 3_600_000;
+
+export interface ChildOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  timeoutMs?: number;
+}
+
+/**
+ * Children this process spawned and has not reaped.
+ *
+ * The registry exists for one moment: the host closes stdin or sends SIGTERM
+ * while a generation is mid-flight. Without it the child — and under `--run-tests`
+ * its dev server and browsers — outlives the server that started it, holding
+ * ports in a project whose agent has already gone.
+ */
+const LIVE = new Set<ReturnType<typeof Bun.spawn>>();
+
+/**
+ * Set once the server has begun teardown.
+ *
+ * It closes the one race the registry would otherwise leave: a call already
+ * dequeued when stdin closed spawns its child a moment AFTER the kill pass, and
+ * that child — a generation, or under `--run-tests` a dev server and browsers —
+ * would then be orphaned with nobody left to reap it. After teardown, registering
+ * is killing.
+ */
+let TEARDOWN = false;
+
+/** Kills performed because the server is going away — not watchdog timeouts, which
+ *  are the caller's own deadline, not teardown. The stderr note quotes this. */
+let KILLED_TOTAL = 0;
+
+function killGroup(proc: ReturnType<typeof Bun.spawn>): void {
+  try {
+    process.kill(-proc.pid, "SIGKILL");
+  } catch {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // Already dead. The registry entry is dropped either way.
+    }
+  }
+}
+
+/** Register a live child, or kill it on arrival if teardown already happened. */
+function track(proc: ReturnType<typeof Bun.spawn>): void {
+  LIVE.add(proc);
+  if (TEARDOWN) {
+    KILLED_TOTAL++;
+    killGroup(proc);
+  }
+}
+
+/** SIGKILL every live child's process group. Sticky: children spawned afterwards
+ *  are killed as they appear, so a call that was dequeued after teardown started
+ *  cannot orphan its child. */
+export function killLiveChildren(): void {
+  TEARDOWN = true;
+  KILLED_TOTAL += LIVE.size;
+  for (const proc of LIVE) killGroup(proc);
+  LIVE.clear();
+}
+
+/** How many children teardown has killed, late kills included. */
+export function killedChildCount(): number {
+  return KILLED_TOTAL;
+}
+
+/**
+ * Run `flawless-react <args…>` to completion, or kill its whole process group at
+ * the deadline.
+ *
+ * Children are spawned detached so the kill reaches the grandchildren — a suite
+ * under `--run-tests` is a dev server plus browsers plus workers, and killing
+ * only the CLI would orphan exactly the processes that hold ports.
+ */
+export async function runFlawlessChild(args: string[], opts: ChildOptions = {}): Promise<ChildRun> {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let proc: ReturnType<typeof Bun.spawn>;
+  try {
+    proc = Bun.spawn([...flawlessSpawnArgv(), ...args], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      detached: true,
+      ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+      ...(opts.env !== undefined ? { env: { ...process.env, ...opts.env } } : {}),
+    });
+  } catch (err) {
+    // A bad cwd is Bun.spawn throwing ENOENT before anything ran. Name the
+    // argument at fault rather than the syscall.
+    const message = (err as Error).message;
+    if (opts.cwd !== undefined && message.includes(opts.cwd)) {
+      throw new Error(`invalid "cwd": ${message}`);
+    }
+    throw err;
+  }
+  track(proc);
+  let timedOut = false;
+  const killer = setTimeout(() => {
+    timedOut = true;
+    killGroup(proc);
+  }, timeoutMs);
+  // No race needed: the watchdog KILLS the child, so `proc.exited` is the one
+  // promise that always lands — with or without the deadline.
+  const readOut = new Response(proc.stdout as ReadableStream).text();
+  const readErr = new Response(proc.stderr as ReadableStream).text();
+  await proc.exited;
+  LIVE.delete(proc);
+  clearTimeout(killer);
+  const stdout = await readOut;
+  const stderr = await readErr;
+  return { code: timedOut ? -1 : (proc.exitCode ?? -1), stdout, stderr, timedOut };
+}
+
+/** A stream, capped and labelled; empty streams say so rather than vanishing. */
+function stream(label: string, text: string): string | null {
+  const capped = capText(text);
+  const body = capped.text.replace(/\n+$/, "");
+  if (!body.trim()) return null;
+  return `--- ${label}${capped.truncated ? " (truncated, see marker)" : ""} ---\n${body}`;
+}
+
+/** Nonzero exit and timeouts are isError; the child's verdict is the verdict. */
+export function renderRun(run: ChildRun, timeoutMs: number): ToolResult {
+  const parts = [
+    run.timedOut
+      ? `timed out after ${timeoutMs}ms — process group killed (exit reported as -1)`
+      : `exit ${run.code}`,
+  ];
+  const out = stream("stdout", run.stdout);
+  const err = stream("stderr", run.stderr);
+  if (out) parts.push(out);
+  if (err) parts.push(err);
+  if (!out && !err) parts.push("(no output)");
+  return run.timedOut || run.code !== 0 ? fail(parts.join("\n")) : ok(parts.join("\n"));
+}
+
+/**
+ * A `--ci` child run rendered as a tool result: the JSON blob parsed and
+ * re-emitted (the caller gets structure, not a string it has to un-nest from a
+ * text field), with the child's stderr diagnostics kept beside it.
+ *
+ * The parse is allowed to fail, and says so when it does: `--ci`'s contract is
+ * that a successful run prints exactly one JSON document, but a usage error
+ * exits 2 with its reason on stderr and nothing on stdout, and reporting THAT as
+ * "no JSON" would bury the actual message. So an unparseable stdout falls back
+ * to the raw streams rather than to a guess.
+ */
+export function renderCiRun(run: ChildRun, timeoutMs: number): ToolResult {
+  const head = run.timedOut
+    ? `timed out after ${timeoutMs}ms — process group killed (exit reported as -1)`
+    : `exit ${run.code}`;
+  const blob = parseCiBlob(run.stdout);
+  const parts = [head];
+  if (blob !== null) {
+    parts.push(`--- result (--ci --json) ---\n${JSON.stringify(blob, null, 2)}`);
+  } else {
+    const out = stream("stdout (not a JSON blob)", run.stdout);
+    if (out) parts.push(out);
+  }
+  const err = stream("stderr", run.stderr);
+  if (err) parts.push(err);
+  if (blob === null && !err) parts.push("(no output)");
+  return run.timedOut || run.code !== 0 ? fail(parts.join("\n")) : ok(parts.join("\n"));
+}
+
+/** The blob, or null when stdout is not one. Trailing text after the document is
+ *  a contract break, so it is reported as unparseable rather than ignored. */
+function parseCiBlob(stdout: string): JsonValue | null {
+  const trimmed = stdout.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed) as JsonValue;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Per-call cwd/env/watchdog, read through the same validating accessors every
+ * other argument uses — a timeout of `"60000"` (a string, from a host that
+ * stringifies) is rejected by name rather than silently dropped, leaving the
+ * caller with a run that had no watchdog at all.
+ */
+export function callOpts(args: JsonObject): ChildOptions {
+  const timeoutMs = optInt(args, "timeout_ms", TIMEOUT_MIN, TIMEOUT_MAX);
+  const cwd = optStr(args, "cwd");
+  const env = optStrMap(args, "env");
+  return {
+    ...(cwd !== undefined ? { cwd } : {}),
+    ...(env !== undefined ? { env } : {}),
+    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+  };
+}