@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/mcp/runTools.ts

@@ -0,0 +1,362 @@
+// The RUN plane of the MCP surface: the tools that change a project, and so run
+// as a flawless-react child process (see run.ts for why that boundary exists).
+//
+// Both tools here map argument → argv rather than reaching into core.ts, and
+// that is deliberate: the CLI is the contract agents are told about, the exit
+// codes and the `--ci` blob are already its documented shape, and a second
+// in-process path would be a second implementation to keep in agreement — the
+// defect class this repo keeps finding in its own docs.
+
+import { parseSkillsCommand } from "../skills/spec.ts";
+import { ALL_TASK_IDS } from "../tasks/index.ts";
+import type { HeapMode, RootMode } from "../types.ts";
+import type { JsonObject } from "./protocol.ts";
+import { callOpts, DEFAULT_TIMEOUT_MS, renderCiRun, renderRun, runFlawlessChild } from "./run.ts";
+import {
+  optBool,
+  optEnum,
+  optEnumArray,
+  optJsonText,
+  optStr,
+  optStrArray,
+  optStrOrTrue,
+  requireKeys,
+  type ToolDef,
+  ToolError,
+} from "./support.ts";
+
+/** `--heaps` closed set, from HeapMode — the flag's own doc line is stale about
+ *  this and parseArgs is the authority. */
+const HEAP_MODES: readonly HeapMode[] = ["off", "stress", "all"];
+const ROOT_MODES: readonly RootMode[] = ["primary", "exported"];
+
+// ------------------------------------------------------------ flawless_run ----
+
+const RUN_ARGS = [
+  "entry",
+  "tasks",
+  "nextjs",
+  "expo",
+  "out",
+  "colocate",
+  "force",
+  "report",
+  "run_tests",
+  "changed",
+  "roots",
+  "exclude",
+  "no_default_excludes",
+  "depth",
+  "variants",
+  "include_children",
+  "heaps",
+  "props",
+  "provider",
+  "app_resolver",
+  "api",
+  "swagger_url",
+  "inline_summary",
+  "cwd",
+  "env",
+  "timeout_ms",
+] as const;
+
+/**
+ * Tool arguments → CLI argv, in the order the CLI reads them.
+ *
+ * `--ci` is always first: it is the non-interactive contract (no prompts, JSON on
+ * stdout) and without it a run would wait forever on a stdin the protocol owns.
+ * Boolean options are only emitted when they change the default, so the argv a
+ * user reproduces by hand matches what the tool ran.
+ */
+function runArgv(a: JsonObject): string[] {
+  const entry = optStr(a, "entry");
+  const tasks = optEnumArray(a, "tasks", ALL_TASK_IDS);
+  const nextjs = optStrOrTrue(a, "nextjs");
+  const expo = optStrOrTrue(a, "expo");
+  if (nextjs !== undefined && expo !== undefined) {
+    // The CLI refuses this too; refusing here gives the agent the explanation
+    // before a child pays for the module graph to say it.
+    throw new ToolError(
+      "nextjs and expo are mutually exclusive — one project, one framework mode per run",
+    );
+  }
+  const argv = ["--ci"];
+  if (entry) argv.push(entry);
+  if (tasks?.length) argv.push("--tasks", tasks.join(","));
+  if (nextjs === true) argv.push("--nextjs");
+  else if (typeof nextjs === "string") argv.push("--nextjs", nextjs);
+  if (expo === true) argv.push("--expo");
+  else if (typeof expo === "string") argv.push("--expo", expo);
+  const out = optStr(a, "out");
+  if (out) argv.push("--out", out);
+  if (optBool(a, "colocate")) argv.push("--colocate");
+  if (optBool(a, "force")) argv.push("--force");
+  if (optBool(a, "report")) argv.push("--report");
+  if (optBool(a, "run_tests")) argv.push("--run-tests");
+  const changed = optStrOrTrue(a, "changed");
+  if (changed === true) argv.push("--changed");
+  else if (typeof changed === "string") argv.push("--changed", changed);
+  const roots = optEnum(a, "roots", ROOT_MODES);
+  if (roots) argv.push("--roots", roots);
+  for (const g of optStrArray(a, "exclude") ?? []) argv.push("--exclude", g);
+  if (optBool(a, "no_default_excludes")) argv.push("--no-default-excludes");
+  const depth = a.depth;
+  if (typeof depth === "number") argv.push("--depth", String(depth));
+  const variants = a.variants;
+  if (typeof variants === "number") argv.push("--variants", String(variants));
+  const includeChildren = optBool(a, "include_children");
+  if (includeChildren === false) argv.push("--include-children=false");
+  const heaps = optEnum(a, "heaps", HEAP_MODES);
+  if (heaps) argv.push("--heaps", heaps);
+  const props = optJsonText(a, "props");
+  if (props) argv.push("--props", props);
+  const provider = optStr(a, "provider");
+  if (provider) argv.push("--provider", provider);
+  const appResolver = optStr(a, "app_resolver");
+  if (appResolver) argv.push("--app-resolver", appResolver);
+  const api = optStr(a, "api");
+  if (api) argv.push("--api", api);
+  const swaggerUrl = optStr(a, "swagger_url");
+  if (swaggerUrl) argv.push("--swagger-url", swaggerUrl);
+  if (optBool(a, "inline_summary") === false) argv.push("--no-inline-summary");
+  return argv;
+}
+
+const flawlessRun: ToolDef = {
+  name: "flawless_run",
+  description:
+    "Generate or refresh a flawless-react suite. THIS WRITES FILES: the suite directory " +
+    "(.flawless, or flawless/ in framework mode), regenerated specs and harness, REPORT.md, and " +
+    "in Next.js/Expo mode the target project's package.json scripts and its config files. Every " +
+    "CLI option is available; omit `tasks` to run perf-harness alone, the documented " +
+    "non-interactive default. Runs a flawless-react child with --ci and returns its JSON blob " +
+    "(exitCode, outDir, results, keptScripts, testRun, errors) plus stderr diagnostics — a " +
+    "nonzero exit is an error result, never a green run. `run_tests` executes the generated " +
+    "suites, which is minutes and needs their prerequisites: a dev server for e2e " +
+    "(FLAWLESS_E2E_BASEURL, FLAWLESS_E2E_ID) and a seeded database for load pipes (LOAD_BASE, " +
+    "LOAD_AUTH). Call flawless_project_status first: an existing suite is regenerated wholesale, " +
+    "and hand-written assertions in it are lost unless they live in generated files.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      entry: {
+        type: "string",
+        description:
+          "Component file or glob. Omit in Next.js/Expo mode to sweep what the framework detection " +
+          "finds. Relative paths resolve against `cwd`.",
+      },
+      tasks: {
+        type: "array",
+        items: { type: "string", enum: [...ALL_TASK_IDS] },
+        description: "Which tasks to run. Default: perf-harness only.",
+      },
+      nextjs: {
+        type: ["string", "boolean"],
+        description: "Next.js mode: project root, or true for the current directory.",
+      },
+      expo: {
+        type: ["string", "boolean"],
+        description:
+          "Expo / React Native mode: project root, or true for the current directory. Mutually " +
+          "exclusive with nextjs.",
+      },
+      out: {
+        type: "string",
+        description:
+          "Suite output directory, relative to cwd. Default .flawless, flawless/ in framework mode.",
+      },
+      colocate: {
+        type: "boolean",
+        description: "Write unit specs beside each source file instead of into the suite.",
+      },
+      force: {
+        type: "boolean",
+        description:
+          "Overwrite a suite that exists. Without it an existing suite is left as-is (status kept).",
+      },
+      report: { type: "boolean", description: "Write REPORT.md." },
+      run_tests: {
+        type: "boolean",
+        description:
+          "Actually execute the generated suites and fold their exit code into the result. Slow, and " +
+          "each suite fails with its own named prerequisite when its environment is missing.",
+      },
+      changed: {
+        type: ["string", "boolean"],
+        description:
+          "Scoped mode: only components affected since a git ref (true = HEAD). A repo with no commits " +
+          "refuses rather than treating everything as deleted.",
+      },
+      roots: {
+        type: "string",
+        enum: [...ROOT_MODES],
+        description: "exported emits a tree per exported component — what a whole-app sweep needs.",
+      },
+      exclude: {
+        type: "array",
+        items: { type: "string" },
+        description: "Extra glob patterns to skip, added to the defaults.",
+      },
+      no_default_excludes: {
+        type: "boolean",
+        description: "Drop the built-in excludes (fixtures, shadcn/ui kit, copy, stories).",
+      },
+      depth: {
+        type: "integer",
+        minimum: 1,
+        maximum: 20,
+        description: "Component-tree depth to follow.",
+      },
+      variants: {
+        type: "integer",
+        minimum: 1,
+        maximum: 20,
+        description: "Prop variants per component.",
+      },
+      include_children: {
+        type: "boolean",
+        description:
+          "Follow JSX children through to leaf content. Default true; false is a speed control.",
+      },
+      heaps: {
+        type: "string",
+        enum: [...HEAP_MODES],
+        description: "How much of the V8 heap the profiling suite keeps. Default stress.",
+      },
+      props: {
+        type: "object",
+        description:
+          'Props override when the analyser cannot resolve a type, e.g. {"data": [{"id": "1"}]}.',
+      },
+      provider: {
+        type: "string",
+        description: "Provider wrapper file evaluated by the browser host.",
+      },
+      app_resolver: {
+        type: "string",
+        description: "Module resolver for the real-app browser host.",
+      },
+      api: {
+        type: "string",
+        description: "OpenAPI spec for the MSW layer, or off to disable route discovery.",
+      },
+      swagger_url: {
+        type: "string",
+        description: "Fetch the API spec from a URL, or off to disable it.",
+      },
+      inline_summary: {
+        type: "boolean",
+        description:
+          "Drop <Component>.flawless.json beside each source file. Default true, so false to opt out.",
+      },
+      cwd: { type: "string", description: "Working directory for the run. Default: the server's." },
+      env: {
+        type: "object",
+        additionalProperties: { type: "string" },
+        description:
+          "Extra environment variables, e.g. FLAWLESS_E2E_BASEURL for a run with run_tests.",
+      },
+      timeout_ms: {
+        type: "integer",
+        minimum: 1000,
+        maximum: 14400000,
+        description: `Watchdog; the process group is killed at the deadline. Default ${DEFAULT_TIMEOUT_MS}.`,
+      },
+    },
+    required: [],
+    additionalProperties: false,
+  },
+  async run(args) {
+    requireKeys(args, RUN_ARGS);
+    const opts = callOpts(args);
+    const run = await runFlawlessChild(runArgv(args), opts);
+    return renderCiRun(run, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  },
+};
+
+// ---------------------------------------------------------- flawless_skills ----
+
+const SKILLS_ARGS = [
+  "action",
+  "all",
+  "select",
+  "global",
+  "force",
+  "copy",
+  "cwd",
+  "timeout_ms",
+] as const;
+
+const flawlessSkills: ToolDef = {
+  name: "flawless_skills",
+  description:
+    "The fourteen agent skills flawless-react embeds, in the .agents/skills and .claude/skills " +
+    "layout Codex, Cursor, OpenCode and Claude Code read. action=status reads both scopes and " +
+    "writes nothing; action=install runs the CLI's install and WRITES those files (links by " +
+    "default, copies with `copy` for Claude Code). Without `all` or `select`, install installs " +
+    "every skill — the piped/CI behaviour, since this call has no terminal to answer a menu. " +
+    "A skill whose file a user edited is reported as edited and is only overwritten with `force`.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["status", "install"],
+        description: "status reads; install writes.",
+      },
+      all: { type: "boolean", description: "install: every skill, no menu." },
+      select: {
+        type: "array",
+        items: { type: "string" },
+        description: "install: only these skill names.",
+      },
+      global: {
+        type: "boolean",
+        description: "install: target ~/.agents/skills instead of ./.agents/skills.",
+      },
+      force: {
+        type: "boolean",
+        description: "install: overwrite a SKILL.md the user edited locally.",
+      },
+      copy: {
+        type: "boolean",
+        description: "install: copy into .claude/skills instead of linking it.",
+      },
+      cwd: { type: "string", description: "Project directory for a project-scoped install." },
+      timeout_ms: { type: "integer", minimum: 1000, maximum: 300000 },
+    },
+    required: ["action"],
+    additionalProperties: false,
+  },
+  async run(args) {
+    requireKeys(args, SKILLS_ARGS, ["action"]);
+    const action = args.action;
+    if (action !== "status" && action !== "install") {
+      throw new ToolError('invalid argument "action": expected status or install');
+    }
+    const opts = callOpts(args);
+    const argv = ["skills", action === "install" ? "install" : "list"];
+    // Validated through the CLI's own parser, so an argument the verb does not
+    // take is refused with the CLI's message instead of being silently dropped.
+    parseSkillsCommand(argv.slice(1).concat(buildSkillFlags(args)));
+    argv.push(...buildSkillFlags(args));
+    const run = await runFlawlessChild(argv, opts);
+    return renderRun(run, opts.timeoutMs ?? 30_000);
+  },
+};
+
+/** install-only switches, in CLI spelling. `status` ignores them, and the parser
+ *  above is what refuses them on a status call. */
+function buildSkillFlags(a: JsonObject): string[] {
+  const out: string[] = [];
+  const select = optStrArray(a, "select");
+  if (optBool(a, "all")) out.push("--all");
+  if (select?.length) out.push("--select", select.join(","));
+  if (optBool(a, "global")) out.push("--global");
+  if (optBool(a, "force")) out.push("--force");
+  if (optBool(a, "copy")) out.push("--copy");
+  return out;
+}
+
+export const RUN_TOOLS: ToolDef[] = [flawlessRun, flawlessSkills];

package/src/mcp/server.ts

@@ -0,0 +1,279 @@
+// `flawless-react mcp` — the Model Context Protocol server over stdio.
+//
+// Transport contract: one JSON-RPC 2.0 message per line on stdin and stdout.
+// stdout belongs to the protocol EXCLUSIVELY, so before anything is served
+// process.stdout.write is redirected to stderr and protocol frames go out on the
+// saved real writer with drain backpressure. Two things make that more than
+// hygiene here: the analyser and the scaffolder are libraries that narrate to
+// stdout, and the read plane runs IN this process — without the redirect a single
+// progress line would corrupt the frame the host is framing its own reads on.
+// (Generation is different: it runs in a child, see run.ts, because the suites it
+// executes inherit stdout.)
+//
+// Lifetime contract: the host owns the lifecycle. A signal (SIGINT, SIGTERM) kills
+// any live child's process group and then drains the in-flight call, so a server
+// that is taken down never leaves a generation — or under `--run-tests` a dev
+// server and a browser — holding ports in someone's project. stdin EOF drains
+// instead: `printf … | flawless-react mcp` closes the pipe as it writes the batch,
+// and the work that batch asked for still finishes (its watchdog still bounds it).
+// Closing the pipe is not a cancel.
+//
+// Calls are SERIALIZED, one in flight, and this is load-bearing rather than
+// polite: the read plane runs with the process working directory set to the
+// call's `root` (so globs, default excludes and tsconfig resolution behave exactly
+// as they do when the same command is typed in that project). Two concurrent
+// reads would each chdir out from under the other's glob and return findings for
+// the wrong tree. One at a time makes that impossible by construction.
+
+import { VERSION } from "../version.ts";
+import {
+  INVALID_PARAMS,
+  type JsonObject,
+  type JsonValue,
+  METHOD_NOT_FOUND,
+  parseLine,
+  type RpcRequest,
+  type RpcResponse,
+  fail as rpcFail,
+  reply as rpcReply,
+  SERVER_NOT_INITIALIZED,
+  serialize,
+} from "./protocol.ts";
+import { killedChildCount, killLiveChildren } from "./run.ts";
+import { parseMcpCommand, renderMcpHelp } from "./spec.ts";
+import { ToolError } from "./support.ts";
+import { ALL_TOOLS, invokeTool, toolByName, toolsList } from "./tools.ts";
+
+/**
+ * Protocol versions this server answers, newest first.
+ *
+ * A client asking for one not listed here gets the newest version this dispatch
+ * actually implements rather than an echo of what it asked for: agreeing to a
+ * revision whose behaviour this file does not implement would be a promise
+ * flawless-react cannot keep.
+ */
+const SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+
+/**
+ * The `flawless-react mcp` entry point. `argv` is everything AFTER the
+ * subcommand word (cli.ts strips it, the same way it does for `skills`).
+ *
+ * Help is answered here, on a real stdout, before the redirect below — after the
+ * redirect `--help` would print itself onto stderr and the host would see an empty
+ * protocol stream.
+ */
+export async function runMcpCli(argv: readonly string[]): Promise<number> {
+  let help = false;
+  try {
+    help = parseMcpCommand(argv).verb === "help";
+  } catch (err) {
+    process.stderr.write(`${(err as Error).message}\n`);
+    return 2;
+  }
+  if (help) {
+    process.stdout.write(renderMcpHelp());
+    return 0;
+  }
+  return runMcp();
+}
+
+async function runMcp(): Promise<number> {
+  const realStdout = process.stdout.write.bind(process.stdout);
+  process.stdout.write = ((chunk: unknown): boolean => {
+    const text =
+      typeof chunk === "string"
+        ? chunk
+        : chunk instanceof Uint8Array
+          ? Buffer.from(chunk).toString("utf8")
+          : String(chunk);
+    return process.stderr.write(text);
+  }) as typeof process.stdout.write;
+
+  let initialized = false;
+  let exiting = false;
+
+  // One frame out, backpressure honoured: a frame the OS buffer cannot take yet
+  // is waited for, not dropped. Exiting on a non-empty write queue truncates the
+  // stream, and a truncated frame is a host that hangs waiting for its answer.
+  const writeLine = async (message: RpcResponse): Promise<void> => {
+    if (realStdout(serialize(message))) return;
+    await new Promise<void>((res) => process.stdout.once("drain", () => res()));
+  };
+
+  let chain: Promise<void> = Promise.resolve();
+  const enqueue = (task: () => Promise<void>): void => {
+    chain = chain.then(task, task);
+  };
+
+  const handleRequest = async (req: RpcRequest): Promise<RpcResponse | null> => {
+    switch (req.method) {
+      case "initialize": {
+        const requested =
+          typeof req.params?.protocolVersion === "string" ? req.params.protocolVersion : "";
+        const version = SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+          ? requested
+          : (SUPPORTED_PROTOCOL_VERSIONS[0] as string);
+        initialized = true;
+        return rpcReply(req.id, {
+          protocolVersion: version,
+          capabilities: { tools: {} },
+          serverInfo: { name: "flawless-react", title: "flawless-react", version: VERSION },
+          instructions:
+            "flawless-react suite generation over MCP, in two planes. Run-plane tools " +
+            "(flawless_run, flawless_skills) change a project and execute a flawless-react " +
+            "child with --ci, so their exit codes and output are the CLI's own; read-plane " +
+            "tools open files and write nothing. Per-call cwd/env never persist — pass them " +
+            "on every call. A nonzero exit, a killed timeout and an unparseable example are " +
+            "isError results carrying the verbatim output, and every output cap announces " +
+            "itself: this server does not report a false pass.",
+        });
+      }
+      case "ping":
+        return rpcReply(req.id, {});
+      case "tools/list":
+        if (!initialized) {
+          return rpcFail(req.id, {
+            code: SERVER_NOT_INITIALIZED,
+            message: `flawless-react mcp: send initialize before ${req.method}`,
+          });
+        }
+        return rpcReply(req.id, toolsList());
+      case "tools/call": {
+        if (!initialized) {
+          return rpcFail(req.id, {
+            code: SERVER_NOT_INITIALIZED,
+            message: "flawless-react mcp: send initialize before tools/call",
+          });
+        }
+        const name = req.params?.name;
+        if (typeof name !== "string") {
+          return rpcFail(req.id, { code: INVALID_PARAMS, message: 'tools/call: "name" required' });
+        }
+        const tool = toolByName(name);
+        if (!tool) {
+          // Unknown tool is a protocol-level error, per the spec: the tool never
+          // existed, so it cannot be the one answering. The list rides along — a
+          // host that guessed a name is exactly the caller that needs the eight.
+          return rpcFail(req.id, {
+            code: INVALID_PARAMS,
+            message: `unknown tool "${name}" — one of: ${ALL_TOOLS.map((t) => t.name).join(", ")}`,
+          });
+        }
+        const rawArgs = req.params?.arguments;
+        if (rawArgs !== undefined && (typeof rawArgs !== "object" || rawArgs === null)) {
+          return rpcFail(req.id, {
+            code: INVALID_PARAMS,
+            message: "tools/call: arguments must be an object",
+          });
+        }
+        try {
+          const result = await invokeTool(tool, (rawArgs ?? {}) as JsonObject);
+          // ToolResult is plain data ({content, isError}); the cast is the
+          // JsonValue boundary, not a hole — it carries no methods.
+          return rpcReply(req.id, result as unknown as JsonValue);
+        } catch (err) {
+          // Argument misuse and tool failure are a RESULT, not a transport error:
+          // the call was understood, and the answer is "no, with the reason".
+          // This is the repo's never-a-false-pass rule read at the protocol layer —
+          // burying the reason in an error frame the host may only log is how a
+          // failed generation starts reading as an inconclusive one.
+          const kind = err instanceof ToolError ? "invalid arguments" : "error";
+          return rpcReply(req.id, {
+            content: [{ type: "text", text: `flawless-react ${kind}: ${(err as Error).message}` }],
+            isError: true,
+          });
+        }
+      }
+      default:
+        return rpcFail(req.id, {
+          code: METHOD_NOT_FOUND,
+          message: `flawless-react mcp does not implement "${req.method}"`,
+        });
+    }
+  };
+
+  // `kill` splits the two ways a server stops:
+  //
+  // - A SIGNAL means nobody is left to read and the process is being taken down by
+  //   force. Kill FIRST, then drain: the other order spends minutes serving a host
+  //   that is already gone, and the child spending them is the one still writing
+  //   into the project. The kill makes the drain a formality — the call's own
+  //   `proc.exited` is the promise that lands next.
+  // - EOF is different, because `printf … | flawless-react mcp` closes stdin the
+  //   instant the batch is written. Those in-flight calls ARE the requests that
+  //   were made; draining them lets a piped batch finish (a generation killed
+  //   halfway would leave half-written specs in the project for no one's
+  //   convenience). Closing the pipe is not a cancel — SIGTERM is.
+  const shutdown = async (reason: string, opts: { kill: boolean }): Promise<void> => {
+    if (exiting) return;
+    exiting = true;
+    if (opts.kill) killLiveChildren();
+    await chain.catch(() => {});
+    const killed = killedChildCount();
+    process.stderr.write(
+      `flawless-react mcp: ${reason}, shutting down${killed ? ` (${killed} child killed)` : ""}\n`,
+    );
+  };
+  // The signal name is passed as the reason rather than taken from the handler
+  // argument: this repo's `process.on` overloads resolve to a signal union that
+  // a `NodeJS.Signals`-typed parameter does not satisfy. Exiting here, after the
+  // drain, is what keeps a killed server from truncating a frame mid-write.
+  const onSignal = (signal: string): void => {
+    void shutdown(signal, { kill: true }).then(() => process.exit(0));
+  };
+  process.on("SIGTERM", () => onSignal("SIGTERM"));
+  process.on("SIGINT", () => onSignal("SIGINT"));
+
+  const reader = Bun.stdin.stream().getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  try {
+    while (!exiting) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let nl = buf.indexOf("\n");
+      while (nl !== -1) {
+        const line = buf.slice(0, nl).replace(/\r$/, "");
+        buf = buf.slice(nl + 1);
+        nl = buf.indexOf("\n");
+        if (!line.trim()) continue;
+        const parsed = parseLine(line);
+        if (parsed.kind === "invalid") {
+          const response = parsed.response;
+          enqueue(async () => void (await writeLine(response)));
+        } else if (parsed.kind === "request") {
+          const req = parsed.request;
+          enqueue(async () => {
+            const response = await handleRequest(req);
+            if (response) await writeLine(response);
+          });
+        } else {
+          const note = parsed.notification;
+          // The handshake's second half and the cancel notice: no frame back.
+          // Anything else is SAID to, on stderr, never swallowed silently — a
+          // host sending a method this server does not handle should know.
+          if (
+            note.method !== "notifications/initialized" &&
+            note.method !== "notifications/cancelled"
+          ) {
+            process.stderr.write(`flawless-react mcp: ignoring notification "${note.method}"\n`);
+          }
+        }
+      }
+    }
+  } catch (err) {
+    process.stderr.write(`flawless-react mcp: stdin error: ${(err as Error).message}\n`);
+    // A broken transport is not a closed one: nothing more can be read or answered,
+    // so an in-flight child is killed rather than left working for a server that
+    // cannot report on it.
+    await shutdown("stdin error", { kill: true });
+    return 1;
+  }
+  // stdin closed cleanly. Drain rather than kill: a piped batch closes the moment
+  // it is written, and the work it asked for is not less real for the pipe being
+  // gone. The drain is bounded by each call's own watchdog, so this is not
+  // unbounded — and no child outlives it.
+  await shutdown("stdin closed", { kill: false });
+  return 0;
+}