rcf-lite 0.0.1 → 0.7.1

package/src/cli/mcp.js

@@ -0,0 +1,160 @@
+// `rcf mcp` subcommand handler (Phase 7 §D1 / §D13). Resolves the
+// project root ONCE at startup, wires process stdin / stdout / stderr
+// into the MCP server core, and serves until stdin EOF or a signal.
+//
+// Stream discipline (D2): stdout carries MCP messages and NOTHING
+// else. All logging goes to stderr; default stderr output is one
+// startup line plus unexpected-failure blocks, with per-request lines
+// behind --verbose. No root found: one stderr line and exit 2 BEFORE
+// any stdout traffic - a misconfigured client sees a dead subprocess
+// and a clear stderr message.
+
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+import { findProjectRoot } from '../view/index.js';
+import { createMcpServer, serveStreams } from '#core/mcp-shell';
+import { createToolRegistry } from '../mcp/tools.js';
+import { createResourceRegistry } from '../mcp/resources.js';
+import { createPromptRegistry } from '../mcp/prompts.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const OPTION_SPEC = {
+  'project-root': { type: 'string' },
+  verbose: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf mcp [options]
+
+Serve the project over the Model Context Protocol (local stdio). An
+MCP-capable agent harness launches 'rcf mcp' as a subprocess in a
+project directory; stdout carries protocol messages only, logging
+goes to stderr.
+
+Serves eleven tools (rcf_validate, rcf_coverage, rcf_trace,
+rcf_impact, rcf_read, rcf_create, rcf_update, rcf_delete, rcf_link,
+rcf_unlink, rcf_build), resources (rcf://tree, rcf://doc/<id>,
+rcf://docs/<slug>) and the agent-guidance prompts.
+
+The project root is resolved once at startup and fixed for the
+process lifetime; multi-project harnesses run multiple server
+entries. The server exits when the client closes stdin.
+
+Options:
+  --project-root <path>     Resolve the project root from <path>
+                            instead of the working directory
+  --verbose                 Per-request logging on stderr
+  --help                    Print this help
+`;
+
+const INSTRUCTIONS = 'Filesystem-backed RCF (Requirements Confidence Framework) project. '
+  + 'Start with rcf_validate to check tree health, and the rcf://tree resource to orient. '
+  + 'Coverage is structural, not semantic: rcf_coverage reports whether chains reach test '
+  + 'cases, not whether acceptance criteria adequately capture intent. Write tools edit '
+  + 'the git-tracked rcf/ tree directly.';
+
+/**
+ * @param {string[]} argv - argv slice after `mcp`
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const stdin = deps.stdin ?? process.stdin;
+  const cwd = deps.cwd ?? process.cwd();
+  const onSignal = deps.onSignal ?? ((sig, fn) => process.on(sig, fn));
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+  if (parsed.positionals.length > 0) {
+    stderr.write('[error] usage mcp: takes no positional arguments\n');
+    stderr.write(HELP);
+    return 2;
+  }
+
+  // D13: resolve the root once, before any protocol traffic.
+  const start = flags['project-root'] ? resolvePath(cwd, flags['project-root']) : cwd;
+  const projectRoot = await findProjectRoot(start);
+  if (!projectRoot) {
+    // B3 (E2E matrix 2026-07-06-003): an MCP client surfaces this failure
+    // as "zero tools" with no visible error, so the stderr line must tell
+    // the operator exactly what to do next. Theme 1 funnel: incomplete
+    // setup always routes to `npx rcf init` + a session restart.
+    stderr.write(`[error] usage no project root found (no rcf/manifest.json in ${start} or any ancestor). `
+      + 'The MCP server needs an existing rcf/ tree - run `npx rcf init` in the project first '
+      + '(it wires the tree, .mcp.json and the agent instructions), then restart your agent '
+      + 'session; or pass --project-root <path>. See docs/install.md, section 7.\n');
+    return 2;
+  }
+
+  const verbose = Boolean(flags.verbose);
+  const log = {
+    info: verbose ? (line) => stderr.write(`[rcf mcp] ${line}\n`) : () => {},
+    error: (line) => stderr.write(`${line}\n`),
+  };
+
+  const tools = createToolRegistry({ projectRoot, log });
+  const resources = createResourceRegistry({ projectRoot });
+  const prompts = createPromptRegistry();
+
+  const server = createMcpServer({
+    serverInfo: { name: 'rcf-build-lite', version: await readPackageVersion() },
+    instructions: INSTRUCTIONS,
+    capabilities: { tools: {}, resources: {}, prompts: {} },
+    handlers: {
+      'tools/list': async () => ({ tools: tools.definitions }),
+      'tools/call': async (params) => {
+        log.info(`tools/call ${params.name}`);
+        return await tools.call(params.name, params.arguments);
+      },
+      'resources/list': async () => await resources.list(),
+      'resources/read': async (params) => {
+        log.info(`resources/read ${params.uri}`);
+        return await resources.read(params.uri);
+      },
+      'prompts/list': async () => await prompts.list(),
+      'prompts/get': async (params) => {
+        log.info(`prompts/get ${params?.name}`);
+        return await prompts.get(params);
+      },
+    },
+    log,
+  });
+
+  stderr.write(`rcf mcp: serving ${projectRoot}\n`);
+
+  const { done, stop } = serveStreams(server, { input: stdin, output: stdout, log });
+
+  // D18: SIGINT / SIGTERM exit cleanly - nothing to drain, no ports,
+  // no watchers. EOF on stdin is the spec's termination path.
+  onSignal('SIGINT', () => { log.info('received SIGINT, shutting down'); stop(); });
+  onSignal('SIGTERM', () => { log.info('received SIGTERM, shutting down'); stop(); });
+
+  return await done;
+}
+
+async function readPackageVersion() {
+  try {
+    const pkgPath = resolvePath(here, '..', '..', 'package.json');
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+    return pkg.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}

package/src/cli/preflight.js

@@ -0,0 +1,220 @@
+// `rcf preflight` subcommand handler
+// (verification-integrity-cluster-spec §4, ADDENDUM §A).
+//
+// Runs the pre-flight config elicitation session and writes a
+// `preFlightConfig` record onto the manifest. Interactive mode by
+// default when stdin + stdout are TTYs; non-interactive mode reads a
+// pre-filled JSON file (--input) for CI / automation. The session
+// composes:
+//   - one per-service ruling per candidate the scanner surfaced (§4.5),
+//     plus operator additions;
+//   - one design-shape answer per applicable REQ + catalogue question
+//     (ADDENDUM §A.1);
+//   - one baselineAcOptOuts entry per design-shape answer that triggers
+//     an opt-out (ADDENDUM §A.2).
+//
+// Credentials never enter the chain: the session records only env-var
+// NAMES + presence booleans, via the gitignored
+// `.rcf/preflight-secrets.local.json` side-file whose gitignore path
+// rides the 0.6.0 aggregator seam (§4.6).
+
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import process from 'node:process';
+
+import { walkTree } from '#core/store';
+import { writeUnexpectedFailure, rcfError } from '#core/errors';
+
+import { findProjectRoot } from '../view/index.js';
+import {
+  composeDesignShapeOptOuts,
+  composePreflightRecord,
+  normaliseNonInteractiveInput,
+  runInteractiveSession,
+  scanForServiceCandidates,
+  writePreflightRecord,
+} from '../preflight/index.js';
+
+const OPTION_SPEC = {
+  prd: { type: 'string' },
+  'from-tad': { type: 'string' },
+  input: { type: 'string' },
+  'non-interactive': { type: 'boolean' },
+  'dry-run': { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  json: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf preflight [options]
+
+Elicit the pre-flight configuration record: for every third-party
+service the PRD or TAD names, force one of the five attestation modes,
+and record the operator's ruling on the manifest. Also poses any
+applicable design-shape questions (v1 catalogue: auth.htmlLoginPage).
+
+Interactive by default when running on a TTY. Non-interactive mode
+reads a JSON file matching the session-summary shape.
+
+Options:
+  --prd <prd-id>            PRD to scan (default: the project's PRD)
+  --from-tad <tad-id>       Also scan this TAD (default: the project's TAD)
+  --input <path>            Non-interactive: read pre-filled session
+  --non-interactive         Force non-interactive mode (default when
+                            not on a TTY or when piped)
+  --dry-run                 Print the composed record; do not write
+  --json                    Emit the composed record as JSON to stdout
+  --quiet                   Suppress non-error stdout
+  --help                    Print this help
+
+Credentials NEVER enter the chain. The session prompts for env var
+NAMES only; values are read from the shell at test / finalise time.
+The name-metadata is written to .rcf/preflight-secrets.local.json,
+which is gitignored via the managed block written by rcf init.
+
+Exit codes:
+  0  success
+  1  IO / unexpected runtime failure
+  2  usage error (bad flags, unresolvable PRD id)
+  3  schema validation on the composed record
+  4  operator cancelled the session at the confirm step
+`;
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const stdin = deps.stdin ?? process.stdin;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) { stdout.write(HELP); return 0; }
+  if (parsed.positionals.length > 0) {
+    stderr.write('[error] usage preflight: no positional arguments (use --prd / --from-tad)\n');
+    return 2;
+  }
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` first.\n');
+    return 2;
+  }
+
+  const walkResult = await walkTree({ projectRoot });
+  if (walkResult.errors.length > 0) {
+    stderr.write(`[warn] tree has ${walkResult.errors.length} pre-existing issue(s); proceeding — run 'rcf validate' for details\n`);
+  }
+  const { tree } = walkResult;
+
+  const prdId = flags.prd ?? tree.prd?.prdId;
+  if (!prdId) {
+    stderr.write('[error] usage preflight: no --prd given and no PRD found on the tree\n');
+    return 2;
+  }
+  const tadId = flags['from-tad'] ?? tree.tad?.tadId ?? null;
+
+  const scan = scanForServiceCandidates({ tree, prdId, tadId });
+  if (scan.skippedDocIds.length > 0) {
+    stderr.write(`[warn] preflight: skipped ids not found on the tree: ${scan.skippedDocIds.join(', ')}\n`);
+  }
+
+  const isTty = Boolean(stdout.isTTY && stdin.isTTY);
+  const forceNonInteractive = Boolean(flags['non-interactive']) || Boolean(flags.input);
+  const interactive = !forceNonInteractive && isTty;
+
+  let sessionResult;
+  try {
+    if (interactive) {
+      const rl = createInterface({ input: stdin, output: stdout });
+      const prompt = (q) => rl.question(q);
+      const write = (line) => stdout.write(`${line}\n`);
+      try {
+        sessionResult = await runInteractiveSession({
+          projectRoot,
+          scan,
+          reqsForDesignShapes: tree.requirements ?? [],
+          prompt,
+          write,
+          env: deps.env ?? process.env,
+        });
+      } finally {
+        rl.close();
+      }
+    } else if (flags.input) {
+      const raw = await readFile(flags.input, 'utf8');
+      const parsedInput = JSON.parse(raw);
+      sessionResult = normaliseNonInteractiveInput(parsedInput);
+    } else {
+      stderr.write('[error] usage preflight: not on a TTY and no --input file given\n');
+      return 2;
+    }
+  } catch (err) {
+    if (err.message === 'preflight: session cancelled by operator') {
+      stderr.write('[error] preflight: session cancelled; no record written.\n');
+      return 4;
+    }
+    writeUnexpectedFailure(
+      rcfError({ kind: 'ioFailure', message: `preflight: ${err.message}`, stack: err.stack }),
+      stderr,
+    );
+    return 1;
+  }
+
+  const now = deps.now ? new Date(deps.now()) : new Date();
+  const record = composePreflightRecord({
+    manifest: tree.manifest,
+    prdId,
+    services: sessionResult.services,
+    designShapeAnswers: sessionResult.designShapeAnswers,
+    now,
+  });
+  const optOuts = composeDesignShapeOptOuts({
+    manifest: tree.manifest,
+    preflightRecord: record,
+    designShapeAnswers: sessionResult.designShapeAnswers,
+    now,
+  });
+
+  if (flags['dry-run']) {
+    if (flags.json) stdout.write(`${JSON.stringify({ record, optOuts }, null, 2)}\n`);
+    if (!flags.quiet) {
+      stdout.write(`[dry-run] preflight would write record ${record.id} (${record.servicesInScope.length} services, ${record.designShapeAnswers?.length ?? 0} design-shape answers, ${optOuts.length} opt-outs)\n`);
+    }
+    return 0;
+  }
+
+  const writeResult = await writePreflightRecord({
+    projectRoot, tree, record, optOuts, options: {},
+  });
+  if (writeResult && 'kind' in writeResult && 'message' in writeResult) {
+    if (writeResult.kind === 'ioFailure') { writeUnexpectedFailure(writeResult, stderr); return 1; }
+    stderr.write(`[error] ${writeResult.kind} ${writeResult.message}\n`);
+    if (writeResult.kind === 'usage') return 2;
+    if (writeResult.kind === 'validation' || writeResult.kind === 'brokenReference') return 3;
+    return 1;
+  }
+
+  if (flags.json) stdout.write(`${JSON.stringify({ record, optOuts }, null, 2)}\n`);
+  if (!flags.quiet) {
+    stdout.write(`preflight: wrote ${record.id} to rcf/manifest.json (${record.servicesInScope.length} services, ${record.designShapeAnswers?.length ?? 0} design-shape answers)`);
+    if (optOuts.length > 0) stdout.write(` and ${optOuts.length} baseline opt-out(s)`);
+    stdout.write('.\n');
+    if (writeResult.skippedUiBaseline && (record.designShapeAnswers ?? []).length > 0) {
+      stdout.write('  Note: uiBaseline defaults writes are fenced pending Track B (UI design gate). The opt-out ledger carries the linkedPreFlightConfigRef for Track B to consume when it lands.\n');
+    }
+  }
+  return 0;
+}

package/src/cli/read.js

@@ -0,0 +1,162 @@
+// `rcf read <id>` subcommand handler. Prints the document body (or a
+// dot-path field). Inline AC / TC ids resolve to the addressed inline
+// entry inside the parent US / TS body. Phase 4 §D7.
+
+import { parseArgs } from 'node:util';
+
+import { walkTree } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+
+const OPTION_SPEC = {
+  field: { type: 'string' },
+  raw: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf read <id> [options]
+
+Prints the document body to stdout and a schema-validity report to
+stderr: a valid document is reported as valid; an invalid-but-present
+document is still returned, together with its validation errors, so the
+caller sees both the content and the problem. The exit code stays 0
+either way - read is a retrieval verb, not a gate (that is rcf validate).
+
+Options:
+  --field <dotPath>         Print only the addressed field
+  --raw                     Emit unformatted (single-line) JSON
+  --help                    Print this help
+`;
+
+/**
+ * @param {string[]} argv - argv slice after `read`
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  const positionals = parsed.positionals;
+  if (flags.help) { stdout.write(HELP); return 0; }
+  if (positionals.length !== 1) {
+    stderr.write('[error] usage read: expected exactly one <id>\n');
+    stderr.write(HELP);
+    return 2;
+  }
+  const id = positionals[0];
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    return 2;
+  }
+  const { tree, errors } = await walkTree({ projectRoot });
+  const target = resolveTarget(tree, id);
+  if (!target) {
+    stderr.write(`[error] usage read: id ${id} not found\n`);
+    return 2;
+  }
+  let value = target.doc;
+  if (flags.field) {
+    value = extractField(target.doc, flags.field);
+    if (value === undefined) {
+      stderr.write(`[error] usage read: field ${flags.field} not present on ${id}\n`);
+      return 2;
+    }
+  }
+  const out = flags.raw ? JSON.stringify(value) : JSON.stringify(value, null, 2);
+  stdout.write(`${out}\n`);
+  // Validity report (AC-301-1 / AC-301-3): the body went to stdout; the
+  // schema verdict goes to stderr so piped output stays pure JSON. An
+  // invalid-but-present document is returned WITH its validation errors -
+  // content and problem together. Read never gates on validity (exit 0);
+  // rcf validate is the gate.
+  if (target.invalid) {
+    stderr.write(`[warn] read: ${target.containerId} fails schema validation; body returned together with the errors:\n`);
+    const validationErrors = (errors ?? []).filter(
+      (e) => e.kind === 'validation' && e.documentId === target.containerId,
+    );
+    for (const e of validationErrors) {
+      stderr.write(`[warn] validation ${target.containerId}: ${e.message}\n`);
+    }
+  } else {
+    stderr.write(`[ok] read: ${id} is valid against its schema\n`);
+  }
+  return 0;
+}
+
+/**
+ * Resolve a target id against the tree. Supports:
+ *   - root docs (PRD, TAD, BS, MANIFEST)
+ *   - child docs (REQ, US, TAC, ADR, FBS, TS)
+ *   - inline AC (`AC-XXX-N`) -> returns the AC entry from parent US
+ *   - inline TC (`TC-XXX-slug`) -> returns the TC entry from parent TS
+ */
+function resolveTarget(tree, id) {
+  if (id === 'MANIFEST' && tree.manifest) {
+    return { doc: tree.manifest, containerId: 'MANIFEST', invalid: false };
+  }
+  const doc = tree.byId.get(id);
+  if (doc) return { doc, containerId: id, invalid: false };
+  // B5: schema-invalid docs stay addressable (tree.invalidDocs) - read
+  // returns the body together with the validation errors (AC-301-3).
+  const invalidEntry = tree.invalidDocs?.get(id);
+  if (invalidEntry) return { doc: invalidEntry.doc, containerId: id, invalid: true };
+  if (/^AC-\d+(-\d+)?$/.test(id)) {
+    const parentId = tree.parentByChild.get(id);
+    if (!parentId) return null;
+    const us = tree.byId.get(parentId);
+    if (!us) return null;
+    const entry = (us.acceptanceCriteria ?? []).find((ac) => ac.id === id);
+    return entry ? { doc: entry, containerId: parentId, invalid: false } : null;
+  }
+  if (/^TC-\d{3}-[a-z0-9-]+$/.test(id)) {
+    const parentId = tree.parentByChild.get(id);
+    if (!parentId) return null;
+    const ts = tree.byId.get(parentId);
+    if (!ts) return null;
+    const entry = (ts.testCases ?? []).find((tc) => tc.id === id);
+    return entry ? { doc: entry, containerId: parentId, invalid: false } : null;
+  }
+  return null;
+}
+
+function extractField(root, path) {
+  const parts = parseDotPath(path);
+  if (!parts) return undefined;
+  let cur = root;
+  for (const seg of parts) {
+    if (cur === undefined || cur === null) return undefined;
+    if (seg.kind === 'index') {
+      if (!Array.isArray(cur)) return undefined;
+      cur = cur[seg.value];
+    } else {
+      cur = cur[seg.value];
+    }
+  }
+  return cur;
+}
+
+function parseDotPath(path) {
+  if (typeof path !== 'string' || path.length === 0) return null;
+  const parts = [];
+  for (const seg of path.split('.')) {
+    const m = /^([^\[\]]+)((?:\[\d+\])*)$/.exec(seg);
+    if (!m) return null;
+    parts.push({ kind: 'prop', value: m[1] });
+    if (m[2]) {
+      const indices = m[2].match(/\d+/g) ?? [];
+      for (const n of indices) parts.push({ kind: 'index', value: Number(n) });
+    }
+  }
+  return parts;
+}