rcf-lite 0.16.0 → 0.17.0

package/src/cli/doctor.js

@@ -47,6 +47,16 @@ import {
 } from '../setup/managed-gitignore.js';
 import { identityProfilePath } from '../setup/identity-seed.js';
 import { knowledgePaths } from '../setup/knowledge-seed.js';
+import {
+  checkBrowserPresent,
+  checkPlaywrightMcpReachable,
+  checkPlaywrightPresent,
+  findProjectPlaywrightKey,
+  FIX_LINES,
+  loadBrowserFacingSources,
+  probeClaudeCodeMcp,
+  SKIP_LINE_NON_BROWSER_FACING,
+} from '../setup/playwright-checks.js';
 
 const OPTION_SPEC = {
   fix: { type: 'boolean' },
@@ -57,7 +67,24 @@ const OPTION_SPEC = {
   help: { type: 'boolean' },
 };
 
-const KNOWN_CHECKS = /** @type {const} */ (['agent-instructions', 'gitignore', 'knowledge', 'identity']);
+const KNOWN_CHECKS = /** @type {const} */ ([
+  'agent-instructions',
+  'gitignore',
+  'knowledge',
+  'identity',
+  'playwright-present',
+  'browser-present',
+  'playwright-mcp-reachable',
+  'playwright-mcp-redundant',
+]);
+
+/** The four Playwright-related checks doctor runs conditionally for
+ * browser-facing projects (spec 2026-09-03, section 3). */
+const PLAYWRIGHT_CHECKS = /** @type {const} */ ([
+  'playwright-present',
+  'browser-present',
+  'playwright-mcp-reachable',
+]);
 
 export const HELP = `Usage: rcf doctor [--fix] [--check <check>[,check]] [--json] [--quiet] [--help]
 
@@ -73,8 +100,10 @@ Options:
                             removing the corrupted region.
   --check <check>[,check]   Run only the named checks. Default: all.
                             Values: agent-instructions, gitignore,
-                                    knowledge, identity.
-  --json                    Emit machine-readable envelope: { ok, drift[] }.
+                                    knowledge, identity, playwright-present,
+                                    browser-present, playwright-mcp-reachable,
+                                    playwright-mcp-redundant.
+  --json                    Emit machine-readable envelope: { ok, drift, writes, notices }.
   --quiet                   Only summary line + first 3 drift items.
   --force                   Accept a legacy-markers --fix on hand-edited
                             content that a non-interactive run would
@@ -155,12 +184,48 @@ export async function main(argv, deps = {}) {
     force: Boolean(flags.force),
     // isTty is deps-injectable for tests; falls back to real stdout.
     isTty: deps.isTty ?? Boolean(stdout.isTTY),
+    // Doctor's Playwright-check seams (spec 2026-09-03, section 3). Every
+    // probe is injectable so the unit suite runs with none of these tools
+    // installed on the runner.
+    checkPlaywrightPresentImpl: deps.checkPlaywrightPresent ?? checkPlaywrightPresent,
+    checkBrowserPresentImpl: deps.checkBrowserPresent ?? checkBrowserPresent,
+    checkPlaywrightMcpReachableImpl:
+      deps.checkPlaywrightMcpReachable ?? checkPlaywrightMcpReachable,
+    probeClaudeCodeMcpImpl: deps.probeClaudeCodeMcp ?? probeClaudeCodeMcp,
+    loadBrowserFacingSourcesImpl:
+      deps.loadBrowserFacingSources ?? loadBrowserFacingSources,
+    readMcpJsonImpl: deps.readMcpJson ?? defaultReadMcpJson,
   };
 
+  // Section 3.1: browser-facing projection. Computed once; every Playwright
+  // check reads the result from ctx rather than re-walking the manifest.
+  const browserFacingResult = await ctx.loadBrowserFacingSourcesImpl(cwd);
+  ctx.browserFacing = Boolean(browserFacingResult.browserFacing);
+  ctx.browserFacingSources = browserFacingResult.sources ?? [];
+
   /** @type {Array<{check: string, item: string, file: string, message: string, refusedByFix: boolean}>} */
   const drift = [];
   /** @type {Array<{file: string, action: string}>} */
   const writes = [];
+  /** @type {string[]} */
+  const notices = [];
+
+  // Section 3.4: skip line for the three Playwright checks on non-browser-
+  // facing projects. Emitted when at least one of the three is enabled but
+  // the project is not browser-facing AND the operator did not explicitly ask
+  // for that check by name (spec 3.5). We honour the --check filter by
+  // detecting whether the operator explicitly named any playwright check.
+  const explicitlyPickedPlaywrightChecks = new Set(
+    enabled.filter((c) => PLAYWRIGHT_CHECKS.includes(c)),
+  );
+  const anyPlaywrightCheckEnabled = explicitlyPickedPlaywrightChecks.size > 0;
+  const operatorAskedByName =
+    typeof flags.check === 'string'
+    && flags.check.length > 0
+    && explicitlyPickedPlaywrightChecks.size > 0;
+  if (anyPlaywrightCheckEnabled && !ctx.browserFacing && !operatorAskedByName) {
+    notices.push(SKIP_LINE_NON_BROWSER_FACING);
+  }
 
   for (const check of enabled) {
     let result;
@@ -168,7 +233,21 @@ export async function main(argv, deps = {}) {
     else if (check === 'gitignore') result = await runGitignoreCheck(ctx);
     else if (check === 'knowledge') result = await runKnowledgeCheck(ctx);
     else if (check === 'identity') result = await runIdentityCheck(ctx);
-    else continue;
+    else if (PLAYWRIGHT_CHECKS.includes(check)) {
+      // Skip the check on non-browser-facing projects unless the operator
+      // explicitly asked for this check by name (--check filter): the skip
+      // line above is the ground-truth diagnostic in that case (spec 3.4/3.5).
+      if (!ctx.browserFacing && !operatorAskedByName) continue;
+      if (check === 'playwright-present') result = await runPlaywrightPresentCheck(ctx);
+      else if (check === 'browser-present') result = await runBrowserPresentCheck(ctx);
+      else if (check === 'playwright-mcp-reachable') result = await runPlaywrightMcpReachableCheck(ctx);
+      else continue;
+    } else if (check === 'playwright-mcp-redundant') {
+      // Fires only on browser-facing projects (spec 4.5). Never runs on an
+      // API-only project even under an explicit --check ask.
+      if (!ctx.browserFacing) continue;
+      result = await runPlaywrightMcpRedundantCheck(ctx);
+    } else continue;
     for (const d of result.drift) drift.push({ check, ...d });
     for (const w of result.writes) writes.push(w);
   }
@@ -183,10 +262,15 @@ export async function main(argv, deps = {}) {
   const exitCode = ok ? 0 : 3;
 
   if (flags.json) {
-    stdout.write(`${JSON.stringify({ ok, drift, writes }, null, 2)}\n`);
+    stdout.write(`${JSON.stringify({ ok, drift, writes, notices }, null, 2)}\n`);
     return exitCode;
   }
 
+  // Notices (spec 3.4 skip line) are diagnostic ground truth. Emitted BEFORE
+  // the summary so an operator scanning the top of the output sees why the
+  // three checks did not fire on a non-browser-facing project. Not
+  // suppressed by --quiet.
+  for (const notice of notices) stdout.write(`${notice}\n`);
   writeHumanSummary({ stdout, ok, drift, writes, fixed: ctx.fix, quiet: Boolean(flags.quiet) });
   return exitCode;
 }
@@ -546,3 +630,96 @@ async function isPathIgnored(projectRoot) {
 
 // Silence unused-import warnings for values consumed only via names.
 void composeGitignoreInner;
+
+/* ------------------------------------------------------------------ */
+/* Check: playwright-present (spec 3.3)                               */
+/* ------------------------------------------------------------------ */
+
+async function runPlaywrightPresentCheck(ctx) {
+  const drift = [];
+  const result = ctx.checkPlaywrightPresentImpl(ctx.projectRoot);
+  if (!result.ok) {
+    drift.push({
+      item: 'missing-peer',
+      file: 'package.json',
+      message: FIX_LINES['playwright-present'],
+      refusedByFix: true,
+    });
+  }
+  return { drift, writes: [] };
+}
+
+/* ------------------------------------------------------------------ */
+/* Check: browser-present (spec 3.3)                                  */
+/* ------------------------------------------------------------------ */
+
+async function runBrowserPresentCheck(ctx) {
+  const drift = [];
+  const result = await ctx.checkBrowserPresentImpl();
+  if (!result.ok) {
+    drift.push({
+      item: 'no-browser',
+      file: '(system)',
+      message: FIX_LINES['browser-present'],
+      refusedByFix: true,
+    });
+  }
+  return { drift, writes: [] };
+}
+
+/* ------------------------------------------------------------------ */
+/* Check: playwright-mcp-reachable (spec 3.3)                         */
+/* ------------------------------------------------------------------ */
+
+async function runPlaywrightMcpReachableCheck(ctx) {
+  const drift = [];
+  const result = await ctx.checkPlaywrightMcpReachableImpl();
+  if (!result.ok) {
+    drift.push({
+      item: result.timedOut ? 'unreachable-timeout' : 'unreachable',
+      file: '(npx @playwright/mcp)',
+      message: FIX_LINES['playwright-mcp-reachable'],
+      refusedByFix: true,
+    });
+  }
+  return { drift, writes: [] };
+}
+
+/* ------------------------------------------------------------------ */
+/* Check: playwright-mcp-redundant (spec 4.5)                         */
+/* ------------------------------------------------------------------ */
+
+async function runPlaywrightMcpRedundantCheck(ctx) {
+  const drift = [];
+  const mcpJson = await ctx.readMcpJsonImpl(ctx.projectRoot);
+  const projectKey = mcpJson ? findProjectPlaywrightKey(mcpJson) : null;
+  if (!projectKey) return { drift, writes: [] };
+  const probeResult = await ctx.probeClaudeCodeMcpImpl();
+  if (probeResult.kind !== 'found') return { drift, writes: [] };
+  drift.push({
+    item: 'redundant-entry',
+    file: '.mcp.json',
+    message: `project-scope .mcp.json carries a Playwright MCP entry ('${projectKey}') that is also declared at ${probeResult.scope} scope. The project entry shadows the user entry. Remove the project entry with \`rcf init --no-playwright-mcp\` (which re-runs init without writing it), or delete the '${projectKey}' entry from .mcp.json by hand.`,
+    refusedByFix: true,
+  });
+  return { drift, writes: [] };
+}
+
+/**
+ * Default reader for the project-root .mcp.json body. Returns the parsed
+ * object, or null on missing / unparseable (doctor treats an unparseable
+ * .mcp.json as "no signature findable" rather than a hard refusal here; the
+ * merge path in agent-setup already refuses unparseable with exit 2 on write).
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<object|null>}
+ */
+async function defaultReadMcpJson(projectRoot) {
+  const file = join(projectRoot, '.mcp.json');
+  try {
+    const raw = await readFile(file, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}

package/src/cli/init.js

@@ -31,6 +31,11 @@ import {
   writeAgentInstructions,
   writeMcpConfig,
 } from '../setup/agent-setup.js';
+import {
+  findProjectPlaywrightKey,
+  probeClaudeCodeMcp,
+} from '../setup/playwright-checks.js';
+import { PLAYWRIGHT_MCP_VERSION } from '../verify/engine/launcher.js';
 import { writeKnowledgeSeed } from '../setup/knowledge-seed.js';
 import { writeIdentityTemplate } from '../setup/identity-seed.js';
 import {
@@ -46,6 +51,7 @@ const OPTION_SPEC = {
   'project-name': { type: 'string' },
   'non-interactive': { type: 'boolean' },
   'no-agent-setup': { type: 'boolean' },
+  'no-playwright-mcp': { type: 'boolean' },
   quiet: { type: 'boolean' },
   help: { type: 'boolean' },
 };
@@ -70,6 +76,11 @@ Options:
                             not on a TTY or when piped)
   --no-agent-setup          Scaffold the tree only; print the manual
                             harness-wiring instructions instead
+  --no-playwright-mcp       Skip the Playwright MCP entry step. The probe
+                            still runs so the print-out remains honest, but
+                            init writes no Playwright entry and touches no
+                            existing one. Use when a user-scope Playwright
+                            entry is declared in a harness init cannot probe.
   --quiet                   Suppress non-error stdout
   --help                    Print this help
 `;
@@ -172,6 +183,26 @@ export async function main(argv, deps = {}) {
     return 2;
   }
 
+  // Step 1a: Playwright MCP entry (spec 2026-09-03, section 4). Writes a
+  // distinctly named 'playwright-rcf' entry ONLY when init can prove no
+  // Playwright entry exists at any scope the harness can report. Detection
+  // is by command tail (spec 4.1). Cross-scope probe of the Claude Code
+  // harness via `claude mcp list` (spec 4.2). Where the harness cannot be
+  // probed non-interactively, init falls back to the distinctly-named entry
+  // with a notice (spec 4.3). --no-playwright-mcp suppresses the write
+  // entirely; the probe still runs so the print-out remains honest.
+  const playwrightPass = await runPlaywrightMcpPass({
+    projectRoot: cwd,
+    stdout,
+    quiet: Boolean(flags.quiet),
+    optOut: Boolean(flags['no-playwright-mcp']),
+    probeClaudeCodeMcp: deps.probeClaudeCodeMcp ?? probeClaudeCodeMcp,
+  });
+  if (playwrightPass && 'kind' in playwrightPass && 'message' in playwrightPass) {
+    stderr.write(`[error] ${playwrightPass.kind} ${playwrightPass.message}\n`);
+    return 2;
+  }
+
   // Step 2: agent-instructions managed block inside rcf markers (idempotent).
   // Source is the 0.6.0 canonical asset, not the harness-template fenced
   // fragment (which is now regenerated from the same canonical text at
@@ -297,3 +328,138 @@ function countLocal(haystack, needle) {
     i = at + needle.length;
   }
 }
+
+/**
+ * Init's Playwright MCP pass (spec 2026-09-03, section 4). Decision tree:
+ *
+ *   1. If --no-playwright-mcp: probe still runs so the print-out is honest,
+ *      but no .mcp.json entry is written or touched.
+ *   2. If the project-scope .mcp.json carries a Playwright signature under
+ *      any key (spec 4.1): print the 'left alone' line and return.
+ *   3. Probe the Claude Code harness (spec 4.2):
+ *      - 'found': print the 'already registered at <scope> scope' line and
+ *        return (no shadowing).
+ *      - 'none': write the distinctly-named 'playwright-rcf' entry.
+ *      - 'inconclusive' (claude absent, non-zero, or unparseable): write the
+ *        distinctly-named 'playwright-rcf' entry with the 'could not probe'
+ *        notice.
+ *
+ * A distinct project-scope entry keeps init's "never write outside the
+ * project root" discipline; a coexisting user-scope entry the operator has
+ * that init could not see is not shadowed by naming convention.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {NodeJS.WritableStream} args.stdout
+ * @param {boolean} args.quiet
+ * @param {boolean} args.optOut
+ * @param {import('../setup/playwright-checks.js').probeClaudeCodeMcp} args.probeClaudeCodeMcp
+ * @returns {Promise<{ action: 'left-alone-project'|'left-alone-harness'|'written'|'skipped-opt-out', name?: string, scope?: string } | import('../core/errors/index.js').RcfError>}
+ */
+async function runPlaywrightMcpPass({ projectRoot, stdout, quiet, optOut, probeClaudeCodeMcp: probeImpl }) {
+  const mcpPath = join(projectRoot, '.mcp.json');
+  let mcpJson = null;
+  try {
+    const raw = await readFile(mcpPath, 'utf8');
+    try {
+      mcpJson = JSON.parse(raw);
+    } catch {
+      // writeMcpConfig already refused unparseable with a distinct error and
+      // returned before us; if we somehow reach here with a corrupt file,
+      // stay out and let doctor surface it. Return silently.
+      return { action: 'skipped-opt-out' };
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    // .mcp.json does not exist yet (rcf mcp write above would have created
+    // it; if that step ran we should not hit ENOENT). Treat as no project
+    // entry and continue to the probe.
+  }
+
+  const projectKey = mcpJson ? findProjectPlaywrightKey(mcpJson) : null;
+  // Gate finding 8 (2026-09-03): when --no-playwright-mcp is set, print the
+  // opt-out notice on EVERY terminal branch of this pass, in addition to the
+  // honest probe line. The probe still runs (spec 4.4) so the print-out is
+  // always honest about what init could see; the notice makes the reason a
+  // write did not happen unambiguous on the branches that would otherwise
+  // have written.
+  const optOutLine = 'Playwright MCP: --no-playwright-mcp set; nothing written.\n';
+
+  if (projectKey) {
+    if (!quiet) {
+      stdout.write(
+        `Playwright MCP: already registered in .mcp.json under key '${projectKey}' at project scope, left alone.\n`,
+      );
+      if (optOut) stdout.write(optOutLine);
+    }
+    return { action: 'left-alone-project', name: projectKey };
+  }
+
+  // Probe the harness even when --no-playwright-mcp so the print-out remains
+  // honest about what init can see.
+  const probeResult = await probeImpl();
+  if (probeResult.kind === 'found') {
+    if (!quiet) {
+      stdout.write(
+        `Playwright MCP: already registered under key '${probeResult.name}' at ${probeResult.scope} scope in Claude Code, left alone.\n`,
+      );
+      if (optOut) stdout.write(optOutLine);
+    }
+    return { action: 'left-alone-harness', name: probeResult.name, scope: probeResult.scope };
+  }
+
+  if (optOut) {
+    if (!quiet) {
+      // The honest probe line first, then the opt-out notice.
+      if (probeResult.kind === 'inconclusive') {
+        stdout.write(
+          `Playwright MCP: could not probe user-scope entries (${probeResult.reason}).\n`,
+        );
+      } else {
+        stdout.write(
+          'Playwright MCP: no ambient Playwright entry found at any scope this init could probe.\n',
+        );
+      }
+      stdout.write(optOutLine);
+    }
+    return { action: 'skipped-opt-out' };
+  }
+
+  // Compose the distinctly-named entry. Distinct from 'playwright' (the
+  // common name a user-scope entry uses) and from any name Claude Code
+  // writes by default. If init could not see a user-scope entry that
+  // actually exists, both coexist and no shadowing has occurred; verify
+  // provisions its OWN MCP config anyway.
+  const distinctEntry = {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', `@playwright/mcp@${PLAYWRIGHT_MCP_VERSION}`],
+    env: {},
+  };
+  const nextBody = mcpJson ?? {};
+  const servers = (nextBody.mcpServers && typeof nextBody.mcpServers === 'object' && !Array.isArray(nextBody.mcpServers))
+    ? nextBody.mcpServers
+    : {};
+  const nextConfig = {
+    ...nextBody,
+    mcpServers: {
+      ...servers,
+      'playwright-rcf': distinctEntry,
+    },
+  };
+  await writeFile(mcpPath, `${JSON.stringify(nextConfig, null, 2)}\n`, 'utf8');
+
+  if (!quiet) {
+    if (probeResult.kind === 'inconclusive') {
+      stdout.write(
+        `Playwright MCP: could not probe user-scope entries (${probeResult.reason}). Wrote 'playwright-rcf' at project scope; remove with \`rcf init --no-playwright-mcp\` or delete the entry by hand.\n`,
+      );
+    } else {
+      stdout.write(
+        "Playwright MCP: wrote 'playwright-rcf' at project scope (no ambient Playwright entry found at any scope this init could probe). Remove with `rcf init --no-playwright-mcp` or delete the entry by hand.\n",
+      );
+    }
+  }
+  return { action: 'written' };
+}
+