rcf-lite 0.0.1 → 0.7.1

package/src/cli/guidance.js

@@ -0,0 +1,206 @@
+// `rcf guidance [topic]` subcommand handler. Prints a guidance-pack
+// document from the INSTALLED package to stdout, so the method is
+// reachable from a consumer project on the CLI alone.
+//
+// Why this verb exists: the pack ships inside the package (package.json
+// `files` includes `guidance`), but it is never copied into a consumer
+// project. Guidance that pointed at a bare `guidance/<file>.md` path was
+// therefore only reachable by someone sitting in the rcf-build-lite repo.
+// MCP-wired harnesses reach the same content through `rcf://docs/<slug>`
+// resources and the `rcf_*` prompts; this is the CLI-only route to it.
+//
+// Topics come from guidance/manifest.json - the same map the MCP layer
+// reads - so there is one inventory and no duplication. Doc topics keep
+// their manifest slug; prompt topics are addressed by filename minus
+// extension (`build-cycle-playbook`, `elicitation-playbook`), which is
+// the same slug convention.
+//
+// No project root is required: this reads the package, not the tree.
+
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(here, '..', '..');
+const GUIDANCE_DIR = join(PACKAGE_ROOT, 'guidance');
+
+const OPTION_SPEC = {
+  list: { type: 'boolean' },
+  path: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf guidance [topic] [options]
+
+Print a guidance-pack document from the installed rcf-build-lite
+package to stdout. The pack ships with the package and is never copied
+into your project, so this verb is how a CLI-only agent reads the
+method. MCP-wired harnesses can use the rcf://docs/<slug> resources and
+the rcf_* prompts instead; the content is the same.
+
+Topics (run 'rcf guidance' with no arguments to list them):
+  overview                  What RCF is and the document hierarchy
+  document-model            Document kinds, fields and relationships
+  build-cycle               The 5-stage build cycle contract
+  harness-template          The agent-instructions fragment rcf init writes
+  build-cycle-playbook      Deep method: running the build cycle well
+  elicitation-playbook      Deep method: drawing a valid tree out of a
+                            conversation
+  persona-programme         Persona programme: the tail-interview template
+
+Platform-invariant printer (Track C+D):
+  rcf guidance invariants   Print the platform invariants block from the
+                            manifest (currently: never-skip-RCF).
+
+Options:
+  --list                    List the topics, one per line, and exit
+  --path                    Print the file's absolute path instead of
+                            its contents
+  --help                    Print this help
+
+Exit codes:
+  0  success
+  1  the pack could not be read from the installed package
+  2  usage error (unknown topic, too many arguments)
+`;
+
+/**
+ * Read the guidance manifest and flatten it into an ordered topic list.
+ * Docs keep their manifest slug; prompts are addressed by filename
+ * minus extension. Both resolve to a file inside guidance/.
+ *
+ * @param {string} [guidanceDir]
+ * @returns {Promise<Array<{ slug: string, file: string, title: string }>>}
+ */
+export async function listTopics(guidanceDir = GUIDANCE_DIR) {
+  const manifest = JSON.parse(await readFile(join(guidanceDir, 'manifest.json'), 'utf8'));
+  const topics = [];
+  for (const d of manifest.docs ?? []) {
+    topics.push({ slug: d.slug, file: d.file, title: d.title });
+  }
+  // Note: Track C+D §8's `rcf guidance invariants` is deliberately NOT
+  // registered as a listTopics entry. It is a virtual verb (no backing
+  // file; it formats the platformInvariants[] array from the manifest),
+  // handled by the `positionals[0] === 'invariants'` branch in main().
+  // Listing it here would break the byte-faithful topic-serving contract
+  // (topic → file bytes verbatim) that the pack-inventory tests lock.
+  for (const p of manifest.prompts ?? []) {
+    topics.push({
+      slug: p.file.replace(/\.md$/, ''),
+      file: p.file,
+      title: p.description ?? p.name,
+    });
+  }
+  return topics;
+}
+
+/**
+ * @param {string[]} argv - argv slice after `guidance`
+ * @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 guidanceDir = deps.guidanceDir ?? GUIDANCE_DIR;
+
+  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 guidance: expected at most one <topic>\n');
+    stderr.write(HELP);
+    return 2;
+  }
+
+  let topics;
+  try {
+    topics = await listTopics(guidanceDir);
+  } catch (err) {
+    stderr.write(`[error] io guidance pack not readable at ${guidanceDir} (${err.message})\n`);
+    return 1;
+  }
+
+  // No topic named: list what is available. Terse when --list, so the
+  // output pipes cleanly; annotated otherwise, so a human sees titles.
+  if (positionals.length === 0) {
+    if (flags.list) {
+      stdout.write(`${topics.map((t) => t.slug).join('\n')}\n`);
+      return 0;
+    }
+    const width = Math.max(...topics.map((t) => t.slug.length));
+    const lines = topics.map((t) => `  ${t.slug.padEnd(width)}  ${firstSentence(t.title)}`);
+    stdout.write(`Guidance topics (rcf guidance <topic> prints one):\n${lines.join('\n')}\n`);
+    return 0;
+  }
+
+  // Special virtual topic: `invariants` prints the platform-invariant
+  // list from the manifest, not a guidance file. `--path` on this topic
+  // resolves to the manifest itself.
+  if (positionals[0] === 'invariants') {
+    const manifestPath = join(guidanceDir, 'manifest.json');
+    if (flags.path) {
+      stdout.write(`${manifestPath}\n`);
+      return 0;
+    }
+    let invariants;
+    try {
+      const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+      invariants = Array.isArray(manifest?.platformInvariants) ? manifest.platformInvariants : [];
+    } catch (err) {
+      stderr.write(`[error] io guidance invariants: ${err.message}\n`);
+      return 1;
+    }
+    if (invariants.length === 0) {
+      stdout.write('no platform invariants declared in this build\n');
+      return 0;
+    }
+    const lines = [];
+    lines.push('# Platform invariants');
+    lines.push('');
+    for (const [i, inv] of invariants.entries()) {
+      lines.push(`## ${i + 1}. ${inv.title} (id: ${inv.id})`);
+      lines.push('');
+      lines.push(inv.text);
+      lines.push('');
+    }
+    stdout.write(lines.join('\n'));
+    return 0;
+  }
+
+  const topic = topics.find((t) => t.slug === positionals[0]);
+  if (!topic) {
+    stderr.write(`[error] usage guidance: no topic named '${positionals[0]}'. Known topics: ${topics.map((t) => t.slug).join(', ')}\n`);
+    return 2;
+  }
+  const filePath = join(guidanceDir, topic.file);
+  if (flags.path) {
+    stdout.write(`${filePath}\n`);
+    return 0;
+  }
+  let text;
+  try {
+    text = await readFile(filePath, 'utf8');
+  } catch (err) {
+    stderr.write(`[error] io guidance: ${topic.file} is mapped by the manifest but not readable (${err.message})\n`);
+    return 1;
+  }
+  stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+  return 0;
+}
+
+/** First sentence of a title/description, for the one-line topic list. */
+function firstSentence(text) {
+  const cut = String(text).split('. ')[0];
+  return cut.length > 88 ? `${cut.slice(0, 85)}...` : cut;
+}

package/src/cli/help.js

@@ -0,0 +1,156 @@
+// Top-level and per-subcommand help. British English, ASCII hyphens
+// only (Phase 4 §D17).
+//
+// Single-source rule: this module owns the TOP_LEVEL block and NOTHING
+// else. Every per-subcommand block is imported from the module that
+// implements the subcommand, so `rcf help <cmd>` and `rcf <cmd> --help`
+// are the same string by construction. Do not reintroduce a local copy
+// of a subcommand's help - `test/cli/help-parity.test.js` fails the
+// moment the two paths differ. (This file previously kept private
+// duplicates of nine blocks; every one of them had drifted stale, and
+// `rcf help create` was hiding the `cn` kind outright.)
+
+import { HELP as BUILD_HELP } from './build.js';
+import { HELP as COVERAGE_HELP } from './coverage.js';
+import { HELP as CREATE_HELP } from './create.js';
+import { HELP as DELETE_HELP } from './delete.js';
+import { HELP as DOCTOR_HELP } from './doctor.js';
+import { HELP as FINALISE_HELP } from './finalise.js';
+import { HELP as GUIDANCE_HELP } from './guidance.js';
+import { HELP as IMPACT_HELP } from './impact.js';
+import { HELP as INIT_HELP } from './init.js';
+import { HELP as LINK_HELP, UNLINK_HELP } from './link.js';
+import { HELP as MCP_HELP } from './mcp.js';
+import { HELP as PREFLIGHT_HELP } from './preflight.js';
+import { HELP as READ_HELP } from './read.js';
+import { HELP as REVIEW_HELP } from './review.js';
+import { HELP as FBS_HELP } from './fbs.js';
+import { HELP as TEST_SUITE_HELP } from './test-suite.js';
+import { HELP as TRACE_HELP } from './trace.js';
+import { HELP as UI_CLASSIFY_HELP } from './ui-classify.js';
+import { HELP as UI_BASELINE_HELP } from './ui-baseline.js';
+import { HELP as DESIGN_HELP } from './design.js';
+import { HELP as BROWSER_VERIFY_HELP } from './browser-verify.js';
+import { HELP as UPDATE_HELP } from './update.js';
+import { HELP as VALIDATE_HELP } from './validate.js';
+import { HELP as VIEW_HELP } from './view.js';
+// Track C+D (elicitation-and-playbook-hardening-0.7.0) verbs.
+import { HELP as REQ_CLASSIFY_HELP } from './req-classify.js';
+import { HELP as REQ_BASELINE_HELP } from './req-baseline.js';
+import { HELP as INTAKE_HELP } from './intake.js';
+// 0.7.1 packaging consolidation: `rcf verify <verb>` routes to the same
+// help block the transition-grace `rcf-verify` alias bin uses.
+import { TOP_LEVEL_HELP as VERIFY_HELP } from '../verify/cli/help.js';
+
+const TOP_LEVEL = `Usage: rcf <command> [options]
+
+Commands:
+  init                Scaffold a new RCF project
+  view                Render the tree as HTML (live server)
+  validate            Walk the tree and report schema and reference issues
+  create <kind>       Create a new document
+  read <id>           Print a document's body to stdout
+  update <id>         Patch fields on an existing document
+  delete <id>         Delete a document (refuses on dependents by default)
+  link <us-id>        Link a US to a TAC (appends to tacIds; idempotent)
+  unlink <us-id>      Unlink a US from a TAC
+  coverage            Structural coverage report (PRD -> REQ -> US -> AC -> TS -> TC)
+  trace <id>          Walk the graph forward / back / both from an id
+  impact <id>         Impact fan-out with per-node action label
+  build [fbs-id]      Assemble FBS spec bundles and drive the build queue
+  finalise <fbs-id>   Ship gate: verify the deployed app, then mark verified
+  doctor              Diagnose init-hygiene drift (0.6.0 spec); --fix repairs
+  guidance [topic]    Print a method document from the installed pack
+  mcp                 Serve the project over MCP (local stdio)
+  preflight           Elicit pre-flight service-attestation + design-shape record
+  fbs <fbs-id>        FBS-level verbs (depends-on)
+  test-suite <ts-id>  Test-suite verbs (provenance, approve)
+  review <fbs-id>     REVIEW-stage audit (test-theatre + mutation-sampling)
+  ui-classify <id>    Run the UI-bearing classifier on one FBS
+  ui-baseline <verb>  UI baseline: init | show | opt-out
+  design <fbs-id>     Design substage: dispatch worker or hand-author artefacts
+  browser-verify <id> Stage 5 browser-verification gate for a UI-bearing FBS
+  req-classify <id>   Rerun the REQ-shape classifier and write the block
+  req-baseline <verb> Baseline-AC sweep and opt-out ledger for classified REQs
+  intake              Variable-fidelity intake stage (classify supplied artefacts)
+  verify <verb>       Adversarial ship gate (run|report|provision|cleanup|mcp); the legacy rcf-verify bin is a transition alias
+  help [command]      Print help for a command
+
+Options:
+  --version           Print the package version and exit
+  --help              Print this help and exit
+
+Exit codes:
+  0  success
+  1  IO / unexpected runtime failure
+  2  usage error (bad flags, unknown id)
+  3  schema validation or broken references
+  4  refused (delete with dependents; other blocked mutations)
+
+Run 'rcf help <command>' for command-specific help.
+`;
+
+// Every value here is an import. See the single-source rule at the top
+// of this file before adding an entry.
+const HELP_MAP = {
+  init: INIT_HELP,
+  validate: VALIDATE_HELP,
+  create: CREATE_HELP,
+  read: READ_HELP,
+  update: UPDATE_HELP,
+  delete: DELETE_HELP,
+  link: LINK_HELP,
+  unlink: UNLINK_HELP,
+  coverage: COVERAGE_HELP,
+  trace: TRACE_HELP,
+  impact: IMPACT_HELP,
+  build: BUILD_HELP,
+  finalise: FINALISE_HELP,
+  doctor: DOCTOR_HELP,
+  guidance: GUIDANCE_HELP,
+  mcp: MCP_HELP,
+  view: VIEW_HELP,
+  preflight: PREFLIGHT_HELP,
+  review: REVIEW_HELP,
+  fbs: FBS_HELP,
+  'test-suite': TEST_SUITE_HELP,
+  'ui-classify': UI_CLASSIFY_HELP,
+  'ui-baseline': UI_BASELINE_HELP,
+  design: DESIGN_HELP,
+  'browser-verify': BROWSER_VERIFY_HELP,
+  // Track C+D (elicitation-and-playbook-hardening-0.7.0) verbs.
+  'req-classify': REQ_CLASSIFY_HELP,
+  'req-baseline': REQ_BASELINE_HELP,
+  intake: INTAKE_HELP,
+  // 0.7.1 packaging consolidation: verify subcommand tree.
+  verify: VERIFY_HELP,
+};
+
+/**
+ * `rcf help [command]` handler. Positional after `help` names the
+ * subcommand; absent → top-level help.
+ *
+ * @param {string[]} argv - argv slice after `help`
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  if (argv.length === 0) {
+    stdout.write(TOP_LEVEL);
+    return 0;
+  }
+  const cmd = argv[0];
+  const body = HELP_MAP[cmd];
+  if (!body) {
+    stderr.write(`[error] usage no help topic named '${cmd}'\n`);
+    stdout.write(TOP_LEVEL);
+    return 2;
+  }
+  stdout.write(body);
+  return 0;
+}
+
+export const TOP_LEVEL_HELP = TOP_LEVEL;
+export { HELP_MAP };

package/src/cli/impact.js

@@ -0,0 +1,119 @@
+// `rcf impact <id>` subcommand handler. Reports "if this id changes,
+// what should we re-verify / re-approve". Phase 5 §D7.
+//
+// Impact = trace-forward (down to test-leaves) + trace-back (up to
+// root PRD / TAD / BS) + a labelled `actionNeeded` column per node,
+// driven by static (kind, role) rules per D7.
+
+import { parseArgs } from 'node:util';
+
+import { formatErrors } from '#core/errors';
+import { walkTree } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+import {
+  computeImpact,
+  formatJson,
+  formatMermaid,
+  formatTable,
+  kindOf,
+} from '../query/index.js';
+
+const OPTION_SPEC = {
+  format: { type: 'string' },
+  help: { type: 'boolean' },
+  // Phase 10 (X2 CodeNode bridge): extend the forward fan-out into the code
+  // layer (AC -> implementing Code Nodes -> transitively dependent CNs).
+  'to-code': { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf impact <id> [options]
+
+Report the fan-out for 'if <id> changes'. Emits ancestors (up to the
+root PRD / TAD / BS) plus descendants (down to test-leaves) with a
+per-node action label:
+  re-run          test needs to be re-executed
+  re-verify       suite ownership; check whether the change invalidates
+  re-approve      the AC or PRD approval scope needs re-signing
+  review-scope    US / REQ scope needs re-checking
+  review-arch     TAD architectural context needs revisiting
+  review-plan     BS build queue may need re-ordering
+  re-execute      FBS delivery re-runs against updated AC
+  review-context  TAC / ADR referenced by an affected FBS
+  re-verify-code  code node reached from a spec change (--to-code)
+
+Options:
+  --format <format>         table (default) | json | mermaid
+  --to-code                 Extend the forward fan-out into Code Nodes
+  --help                    Print this help
+`;
+
+const VALID_FORMATS = new Set(['table', 'json', 'mermaid']);
+
+/**
+ * @param {string[]} argv - argv slice after `impact`
+ * @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; }
+
+  const format = flags.format ?? 'table';
+  if (!VALID_FORMATS.has(format)) {
+    stderr.write(`[error] usage impact: unknown --format ${format} (expected table | json | mermaid)\n`);
+    return 2;
+  }
+
+  if (positionals.length === 0) {
+    stderr.write('[error] usage impact: expected exactly one <id>\n');
+    stderr.write(HELP);
+    return 2;
+  }
+  if (positionals.length > 1) {
+    stderr.write('[error] usage impact: multiple positional ids are not supported\n');
+    return 2;
+  }
+  const id = positionals[0];
+  if (id.includes('*') || id.includes('?')) {
+    stderr.write('[error] usage impact: wildcard / glob positional not supported\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` to create and wire a project.\n');
+    return 2;
+  }
+  const { tree, errors } = await walkTree({ projectRoot });
+  if (errors.length > 0) {
+    stderr.write(`${formatErrors(errors, { verbose: false, strict: false })}\n`);
+    return 3;
+  }
+
+  if (!kindOf(tree, id)) {
+    stderr.write(`[error] usage impact: id ${id} not found\n`);
+    return 2;
+  }
+
+  const result = computeImpact(tree, { id, includeCode: Boolean(flags['to-code']) });
+
+  let output;
+  if (format === 'json') output = formatJson(result, 'impact');
+  else if (format === 'mermaid') output = formatMermaid(result, 'impact');
+  else output = formatTable(result, 'impact');
+  stdout.write(output);
+  return 0;
+}