rcf-lite 0.0.1 → 0.7.1

package/src/cli/init.js

@@ -0,0 +1,282 @@
+// `rcf init` subcommand handler. Interactive by default when stdin +
+// stdout are TTYs and --non-interactive is not set. Init is a bootstrap,
+// not an elicitation session: it asks only for the project name and
+// seeds a fully placeholder document tree - the same tree the
+// non-interactive path produces - which the agent fills in during
+// elicitation. It deliberately does NOT ask the user to name a first
+// requirement / user story / problem statement up front (operator review
+// 2026-07-16, comment 2: a product owner does not know those yet, and
+// asking makes them freeze or type junk). Zero deps; prompt via
+// node:readline/promises.
+//
+// Theme 1 (E2E matrix 2026-07-06-003): init is the full pre-session
+// bootstrap. After scaffolding the tree it also (1) writes/merges the
+// project-root .mcp.json rcf server entry and (2) writes the guidance
+// fragment into CLAUDE.md / AGENTS.md inside rcf marker comments -
+// the project is wired BEFORE the agent session starts. Re-running
+// init on an existing tree leaves the tree alone and refreshes the
+// wiring (idempotent). --no-agent-setup skips the wiring and prints
+// the manual instructions instead.
+
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { initProject } from '#core/store/init.js';
+import {
+  loadManagedBlock,
+  manualSetupInstructions,
+  writeAgentInstructions,
+  writeMcpConfig,
+} from '../setup/agent-setup.js';
+import { writeKnowledgeSeed } from '../setup/knowledge-seed.js';
+import { writeIdentityTemplate } from '../setup/identity-seed.js';
+import {
+  composeGitignoreBlock,
+  computeGitignoreBlockHash,
+  extractGitignoreBlock,
+  GITIGNORE_MARKER_BEGIN,
+  GITIGNORE_MARKER_END,
+} from '../setup/managed-gitignore.js';
+import { hashInnerContent } from '../setup/managed-block.js';
+
+const OPTION_SPEC = {
+  'project-name': { type: 'string' },
+  'non-interactive': { type: 'boolean' },
+  'no-agent-setup': { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf init [options]
+
+Scaffolds the rcf/ tree, registers the MCP server in the project-root
+.mcp.json and writes the agent-instructions fragment into both CLAUDE.md
+and AGENTS.md (an existing instructions file is refreshed in place) -
+the full pre-session bootstrap. Interactive runs prompt only for the
+project name; everything else is seeded as placeholders for the agent
+to elicit. Re-running on an existing project leaves the tree alone and
+refreshes the wiring.
+
+Options:
+  --project-name <name>     Project name (required for --non-interactive)
+  --non-interactive         Skip prompts; use seed values (default when
+                            not on a TTY or when piped)
+  --no-agent-setup          Scaffold the tree only; print the manual
+                            harness-wiring instructions instead
+  --quiet                   Suppress non-error stdout
+  --help                    Print this help
+`;
+
+/**
+ * @param {string[]} argv - argv slice after `init`
+ * @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;
+
+  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;
+  }
+  const cwd = deps.cwd ?? process.cwd();
+  const agentSetup = !flags['no-agent-setup'];
+  const forceNonInteractive = Boolean(flags['non-interactive']);
+  const isTty = Boolean(stdout.isTTY && stdin.isTTY);
+  const interactive = !forceNonInteractive && isTty;
+
+  let projectName = flags['project-name'];
+  let seed = null;
+
+  if (interactive) {
+    // Init asks only for the project name. Everything else in the tree
+    // is seeded as a placeholder for the agent to elicit - see the file
+    // header. `seed` stays null so interactive and non-interactive
+    // produce the identical placeholder tree.
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+      projectName = projectName ?? (await rl.question('Project name: ')).trim();
+      if (!projectName) projectName = 'New RCF Project';
+    } finally {
+      rl.close();
+    }
+  } else {
+    if (!projectName) {
+      stderr.write('[error] usage --project-name is required in non-interactive mode\n');
+      stderr.write(HELP);
+      return 2;
+    }
+  }
+
+  const result = await initProject({ projectRoot: cwd, projectName, seed });
+  const treeExists = Boolean(result && 'kind' in result && result.kind === 'usage'
+    && /already exists/.test(result.message));
+  if (result && 'kind' in result && result.kind === 'usage' && !treeExists) {
+    stderr.write(`[error] usage ${result.message}\n`);
+    return 2;
+  }
+  if (result && 'kind' in result && !treeExists) {
+    stderr.write(`[error] ${result.kind} ${result.message}\n`);
+    return 1;
+  }
+  if (treeExists && !agentSetup) {
+    // Nothing to do at all: tree present, wiring explicitly skipped.
+    stderr.write(`[error] usage ${result.message}\n`);
+    return 2;
+  }
+
+  // --no-agent-setup: scaffold the tree only, print the manual wiring
+  // steps. (A tree-already-present + opt-out combination has already
+  // been refused above, so this branch is always a fresh scaffold.)
+  if (!agentSetup) {
+    if (!flags.quiet) {
+      stdout.write('Set up the RCF document chain under rcf/.\n');
+      stdout.write(`${manualSetupInstructions()}\n`);
+    }
+    return 0;
+  }
+
+  // Step 1: .mcp.json (merge; never clobber other servers / unknown keys).
+  const mcpResult = await writeMcpConfig({ projectRoot: cwd });
+  if (mcpResult && 'kind' in mcpResult && 'message' in mcpResult) {
+    stderr.write(`[error] ${mcpResult.kind} ${mcpResult.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
+  // package build time via scripts/gen-managed-artefacts.mjs).
+  const fragment = await loadManagedBlock();
+  if (typeof fragment !== 'string') {
+    stderr.write(`[error] ${fragment.kind} ${fragment.message}\n`);
+    return 1;
+  }
+  const instrResult = await writeAgentInstructions({ projectRoot: cwd, fragment });
+
+  // Step 3: knowledge space (§3, AC-2.1..AC-2.3). Idempotent per file.
+  const knowledgeResult = await writeKnowledgeSeed({ projectRoot: cwd });
+  // Step 4: identity template (§5, AC-4.1..AC-4.2). Idempotent.
+  const identityResult = await writeIdentityTemplate({ projectRoot: cwd });
+  // Step 5: managed .gitignore block (§4, AC-3.1..AC-3.2). Written or
+  // refreshed in place; operator content outside preserved byte-for-byte.
+  const gitignoreResult = await ensureManagedGitignore({ projectRoot: cwd });
+
+  // High-level completion summary: what was set up and what to do next -
+  // not a developer file list (operator review 2026-07-16, comment 3a).
+  if (!flags.quiet) {
+    let mcpDesc;
+    if (mcpResult.action === 'kept') mcpDesc = 'already registered in .mcp.json (kept)';
+    else if (mcpResult.action === 'merged') mcpDesc = 'registered in .mcp.json (merged with your existing servers)';
+    else mcpDesc = 'registered in .mcp.json';
+
+    const instrFiles = instrResult.writes.map((w) => w.file).join(' and ');
+    const actions = new Set(instrResult.writes.map((w) => w.action));
+    let instrVerb;
+    if (actions.size === 1 && actions.has('created')) instrVerb = 'written to';
+    else if (actions.has('replaced')) instrVerb = 'refreshed in';
+    else instrVerb = 'updated in';
+
+    if (treeExists) {
+      stdout.write('RCF project already set up here - document chain left untouched, agent wiring refreshed.\n');
+    } else {
+      stdout.write('RCF project created.\n');
+      stdout.write('  Document chain     scaffolded under rcf/ - PRD, requirement, story, acceptance criterion, architecture and build-sequence placeholders for your agent to fill in.\n');
+    }
+    stdout.write(`  MCP server         ${mcpDesc}.\n`);
+    stdout.write(`  Agent instructions ${instrVerb} ${instrFiles}.\n`);
+    stdout.write(`  Knowledge space    ${knowledgeVerbAndTarget(knowledgeResult)}.\n`);
+    stdout.write(`  Operator profile   ${identityVerbAndTarget(identityResult)}.\n`);
+    stdout.write(`  Gitignore          ${gitignoreVerbAndTarget(gitignoreResult)}.\n`);
+    stdout.write('\nNext: start your agent session in this directory and tell it what you want to build. '
+      + 'It elicits the requirements and drives the build from there - you do not fill in the document chain by hand.\n');
+  }
+  return 0;
+}
+
+function knowledgeVerbAndTarget(result) {
+  const created = result.writes.filter((w) => w.action === 'created').length;
+  if (created === 0) return 'left as-is at rcf/knowledge/ (all managed files already present)';
+  if (created === result.writes.length) return 'seeded at rcf/knowledge/ (write what you learn; grep before asking)';
+  return `refreshed at rcf/knowledge/ (${created} new managed files)`;
+}
+
+function identityVerbAndTarget(result) {
+  if (result.action === 'kept') return 'left as-is at rcf/.identity/profile.md (already present)';
+  return 'template at rcf/.identity/profile.md (gitignored by default; fill in what is useful)';
+}
+
+function gitignoreVerbAndTarget(result) {
+  if (result.action === 'noop') return 'managed block already up to date in .gitignore';
+  if (result.action === 'created') return 'managed block written to .gitignore (rcf/.identity/ ignored)';
+  if (result.action === 'appended') return 'managed block appended to existing .gitignore (rcf/.identity/ ignored)';
+  return 'managed block refreshed in .gitignore (rcf/.identity/ ignored)';
+}
+
+/**
+ * Ensure the project-root `.gitignore` carries the current managed
+ * block. Writes/refreshes in place; operator entries outside markers
+ * preserved byte-for-byte. Idempotent when block is already current.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @returns {Promise<{ action: 'created' | 'appended' | 'replaced' | 'noop' }>}
+ */
+async function ensureManagedGitignore({ projectRoot }) {
+  const path = join(projectRoot, '.gitignore');
+  let existing;
+  try {
+    existing = await readFile(path, 'utf8');
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code !== 'ENOENT') throw err;
+    await writeFile(path, composeGitignoreBlock(), 'utf8');
+    return { action: 'created' };
+  }
+  const located = extractGitignoreBlock(existing);
+  const composed = composeGitignoreBlock();
+  if (!located) {
+    // No managed block yet - append with a blank-line separator.
+    const beginCount = countLocal(existing, GITIGNORE_MARKER_BEGIN);
+    const endCount = countLocal(existing, GITIGNORE_MARKER_END);
+    if (beginCount !== 0 || endCount !== 0) {
+      // Structurally malformed - leave alone; doctor will surface the
+      // drift and the operator repairs by hand.
+      return { action: 'noop' };
+    }
+    const sep = existing.length === 0 ? '' : (existing.endsWith('\n') ? '\n' : '\n\n');
+    await writeFile(path, `${existing}${sep}${composed}`, 'utf8');
+    return { action: 'appended' };
+  }
+  const innerHash = hashInnerContent(located.innerText);
+  const expected = computeGitignoreBlockHash();
+  if (innerHash === expected) return { action: 'noop' };
+  const next = existing.slice(0, located.beginIndex) + composed + existing.slice(located.endIndex);
+  await writeFile(path, next, 'utf8');
+  return { action: 'replaced' };
+}
+
+function countLocal(haystack, needle) {
+  if (!needle) return 0;
+  let n = 0;
+  let i = 0;
+  while (true) {
+    const at = haystack.indexOf(needle, i);
+    if (at < 0) return n;
+    n += 1;
+    i = at + needle.length;
+  }
+}

package/src/cli/intake.js

@@ -0,0 +1,153 @@
+// `rcf intake` subcommand handler
+// (elicitation-and-playbook-hardening-0.7.0-spec §6).
+//
+// Variable-fidelity intake stage. Classifies the supplied artefacts by
+// fidelity (none | napkin | briefLight | briefStrong | prd | prdPlusTad
+// per spec §3.7), applies elicitation-integrity discipline (§6.4 phase 2
+// scans: impliedButNotStated, contradiction, missingLoadBearingConstraint),
+// records validation findings, and writes an intakeClassification record
+// to the manifest. Elicitation of gaps handed off to the standard
+// playbook §3-§7 (this verb closes at phase 2).
+
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+
+import { walkTree } from '#core/store';
+
+import { findProjectRoot } from '../view/index.js';
+import {
+  runIntakePhases,
+  writeIntakeRecord,
+} from '../intake/index.js';
+
+const OPTION_SPEC = {
+  artefact: { type: 'string', multiple: true },
+  kind: { type: 'string' },
+  input: { type: 'string' },
+  'dry-run': { type: 'boolean' },
+  json: { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf intake [--artefact <path>[,path]] [--kind <kind>] [--dry-run]
+       rcf intake --input <config.json> [--dry-run]
+
+Variable-fidelity intake: read what the operator supplied, classify its
+fidelity, validate it against elicitation integrity, and record an
+intakeClassification block on the manifest. Runs BEFORE the standard
+elicitation playbook when the operator has any starting material.
+
+Options:
+  --artefact <path>[,path]   One or more artefact file paths (repeatable
+                             or comma-separated)
+  --kind <kind>              Hint the artefact kind: napkin |
+                             productBrief | prd | prdPlusTad | other
+  --input <config.json>      Non-interactive mode: pre-filled artefacts
+                             + findings + acknowledgements
+  --dry-run                  Print the plan without writing the record
+  --json                     Emit the intakeClassification block as JSON
+  --quiet                    Suppress non-error confirmations
+  --help                     Print this help
+
+Exit codes:
+  0  success
+  2  usage error (missing --artefact/--input, unreadable file)
+  3  validation failure on the written manifest
+`;
+
+/**
+ * @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 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; }
+
+  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;
+  }
+
+  let input = null;
+  if (flags.input) {
+    try {
+      input = JSON.parse(await readFile(flags.input, 'utf8'));
+    } catch (err) {
+      stderr.write(`[error] usage intake: cannot read --input file: ${err.message}\n`);
+      return 2;
+    }
+  }
+
+  const artefactPaths = [];
+  if (input?.artefacts) {
+    for (const a of input.artefacts) {
+      if (typeof a?.path === 'string' && a.path.length > 0) artefactPaths.push(a.path);
+    }
+  }
+  for (const raw of flags.artefact ?? []) {
+    for (const p of raw.split(',').map((s) => s.trim()).filter(Boolean)) artefactPaths.push(p);
+  }
+  if (artefactPaths.length === 0 && !input?.fidelity) {
+    stderr.write('[error] usage intake: at least one --artefact <path> is required (or an --input config with artefacts or a bare fidelity)\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 - writes are validated against the post-write state (run 'rcf validate' for details)\n`);
+  }
+
+  const outcome = await runIntakePhases({
+    projectRoot,
+    artefactPaths,
+    kindHint: flags.kind ?? null,
+    input,
+  });
+  if (outcome && outcome.kind && typeof outcome.message === 'string') {
+    stderr.write(`[error] ${outcome.kind} ${outcome.message}\n`);
+    return outcome.kind === 'usage' ? 2 : 3;
+  }
+
+  if (flags['dry-run']) {
+    if (flags.json) {
+      stdout.write(`${JSON.stringify(outcome.record, null, 2)}\n`);
+    } else {
+      stdout.write(`[dry-run] would write intakeClassification ${outcome.record.id} (fidelity=${outcome.record.fidelity}, findings=${outcome.record.validationFindings.length})\n`);
+    }
+    return 0;
+  }
+
+  const result = await writeIntakeRecord({
+    projectRoot,
+    tree: walkResult.tree,
+    record: outcome.record,
+  });
+  if (result && result.kind && typeof result.message === 'string') {
+    stderr.write(`[error] ${result.kind} ${result.message}\n`);
+    return 3;
+  }
+
+  if (flags.json) {
+    stdout.write(`${JSON.stringify(outcome.record, null, 2)}\n`);
+    return 0;
+  }
+  if (!flags.quiet) {
+    stdout.write(`intake: ${outcome.record.id} fidelity=${outcome.record.fidelity} findings=${outcome.record.validationFindings.length}\n`);
+  }
+  return 0;
+}

package/src/cli/link.js

@@ -0,0 +1,128 @@
+// `rcf link` / `rcf unlink` verb (Phase 4 §D19). Idempotent append/remove
+// of TAC ids on a US's `tacIds[]`. Depends on `@stravica-ai/rcf-schemas`
+// having `US.tacIds[]` defined (0.2.1+).
+
+import { parseArgs } from 'node:util';
+
+import { isRcfError } from '#core/errors';
+import { updateDocument, walkTree } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+
+const OPTION_SPEC = {
+  tac: { type: 'string', multiple: true },
+  'dry-run': { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf link <us-id> --tac <tac-id> [options]
+
+Options:
+  --tac <tac-id>            TAC id to link (repeatable to link multiple
+                            TACs in one invocation)
+  --dry-run                 Print the intended write without executing
+  --quiet                   Suppress non-error stdout
+  --help                    Print this help
+`;
+
+export const UNLINK_HELP = `Usage: rcf unlink <us-id> --tac <tac-id> [options]
+
+Options:
+  --tac <tac-id>            TAC id to unlink (repeatable)
+  --dry-run                 Print the intended write without executing
+  --quiet                   Suppress non-error stdout
+  --help                    Print this help
+`;
+
+/**
+ * @param {string[]} argv - argv slice after `link`
+ * @param {object} deps
+ * @param {boolean} deps.remove - false for link, true for unlink
+ * @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();
+  const removing = Boolean(deps.remove);
+
+  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(removing));
+    return 2;
+  }
+  const flags = parsed.values;
+  const positionals = parsed.positionals;
+  if (flags.help) { stdout.write(help(removing)); return 0; }
+  if (positionals.length !== 1) {
+    stderr.write(`[error] usage ${removing ? 'unlink' : 'link'}: expected exactly one <us-id>\n`);
+    return 2;
+  }
+  const usId = positionals[0];
+  const tacIds = flags.tac ?? [];
+  if (tacIds.length === 0) {
+    stderr.write(`[error] usage ${removing ? 'unlink' : 'link'}: at least one --tac is required\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 walkResult = await walkTree({ projectRoot });
+  // B5: pre-existing tree breakage no longer blocks write verbs - the
+  // write is gated on the POST-write tree state inside the writer.
+  if (walkResult.errors.length > 0) {
+    stderr.write(`[warn] tree has ${walkResult.errors.length} pre-existing issue(s); proceeding - writes are validated against the post-write state (run 'rcf validate' for details)\n`);
+  }
+  const us = walkResult.tree.byId.get(usId);
+  if (!us || walkResult.tree.kindById.get(usId) !== 'userStory') {
+    stderr.write(`[error] usage ${removing ? 'unlink' : 'link'}: ${usId} is not an existing US\n`);
+    return 2;
+  }
+  for (const tacId of tacIds) {
+    if (walkResult.tree.kindById.get(tacId) !== 'tac') {
+      stderr.write(`[error] brokenReference ${removing ? 'unlink' : 'link'}: ${tacId} is not an existing TAC\n`);
+      return 3;
+    }
+  }
+  const current = new Set(us.tacIds ?? []);
+  const target = new Set(current);
+  for (const tacId of tacIds) {
+    if (removing) target.delete(tacId); else target.add(tacId);
+  }
+  const next = [...target].sort();
+  const changed = next.length !== current.size || next.some((id, i) => id !== [...current].sort()[i]);
+  if (!changed) {
+    if (!flags.quiet) stdout.write(`${usId} tacIds already at target state (idempotent no-op).\n`);
+    return 0;
+  }
+  const result = await updateDocument({
+    projectRoot,
+    tree: walkResult.tree,
+    id: usId,
+    patch: next.length === 0 ? { tacIds: [] } : { tacIds: next },
+    sets: [],
+    options: { dryRun: Boolean(flags['dry-run']) },
+    walkErrors: walkResult.errors,
+  });
+  if (isRcfError(result)) {
+    stderr.write(`[error] ${result.kind} ${result.message}\n`);
+    if (result.kind === 'validation' || result.kind === 'brokenReference') return 3;
+    return 2;
+  }
+  if (flags['dry-run']) {
+    if (!flags.quiet) stdout.write(`[dry-run] would ${removing ? 'unlink' : 'link'} ${usId} tacIds=${JSON.stringify(next)}\n`);
+    return 0;
+  }
+  if (!flags.quiet) stdout.write(`${usId} tacIds updated (${next.length} entries).\n`);
+  return 0;
+}
+
+function help(removing) {
+  return removing ? UNLINK_HELP : HELP;
+}