rcf-lite 0.0.1 → 0.7.1

package/src/view-supervisor/index.js

@@ -0,0 +1,26 @@
+// Public surface for the view-supervisor module (spec §9).
+
+export {
+  startDetached,
+  stopDetached,
+  statusOfDetached,
+  runDetachedChild,
+} from './supervisor.js';
+
+export {
+  readViewServerRecord,
+  writeViewServerRecord,
+  clearViewServerRecord,
+  writePidFile,
+  readPidFile,
+  removePidFile,
+  DEFAULT_PID_PATH,
+  isPidAlive,
+} from './manifest-writer.js';
+
+export {
+  supervisorLogPath,
+  ensureLogDir,
+  writeLogLine,
+  readLogTail,
+} from './logs.js';

package/src/view-supervisor/logs.js

@@ -0,0 +1,32 @@
+// Supervisor log helpers (spec §9.2 `rcf view logs`).
+
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+/**
+ * @param {string} projectRoot
+ */
+export function supervisorLogPath(projectRoot) {
+  return join(projectRoot, '.rcf', 'view-server.log');
+}
+
+export async function ensureLogDir(projectRoot) {
+  const dir = dirname(supervisorLogPath(projectRoot));
+  await mkdir(dir, { recursive: true });
+}
+
+export async function writeLogLine(projectRoot, line) {
+  await ensureLogDir(projectRoot);
+  await appendFile(supervisorLogPath(projectRoot), `${new Date().toISOString()} ${line}\n`, 'utf8');
+}
+
+export async function readLogTail(projectRoot, tail = 200) {
+  try {
+    const raw = await readFile(supervisorLogPath(projectRoot), 'utf8');
+    const lines = raw.split('\n').filter(Boolean);
+    return lines.slice(-tail);
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+}

package/src/view-supervisor/manifest-writer.js

@@ -0,0 +1,178 @@
+// reviewSurface.viewServer manifest reader/writer (spec §3.6).
+//
+// Writes are atomic (.tmp → rename) and schema-validated before persist,
+// mirroring the preflight and intake writers.
+
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+import { rcfError } from '#core/errors';
+import { validateDocument } from '#core/store';
+
+export const DEFAULT_PID_PATH = '.rcf/view-server.pid';
+
+/**
+ * The managed-gitignore entry the aggregator consumes (spec §9.3). The
+ * pid file and the supervisor log are host-local runtime artefacts; the
+ * chain never carries them.
+ */
+export const viewServerGitignoreEntry = Object.freeze({
+  path: '.rcf/view-server.pid',
+  owner: 'rcf view --detach (view-server pid file)',
+  since: '0.7.0',
+});
+
+export const viewServerLogGitignoreEntry = Object.freeze({
+  path: '.rcf/view-server.log',
+  owner: 'rcf view --detach (supervisor log)',
+  since: '0.7.0',
+});
+
+/**
+ * Read the reviewSurface.viewServer record from the manifest, if any.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<object|null>}
+ */
+export async function readViewServerRecord(projectRoot) {
+  const abs = join(projectRoot, 'rcf', 'manifest.json');
+  try {
+    const raw = await readFile(abs, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed?.reviewSurface?.viewServer ?? null;
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Persist a reviewSurface.viewServer block onto the manifest.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {object} args.record
+ * @returns {Promise<{ record: object } | import('#core/errors').RcfError>}
+ */
+export async function writeViewServerRecord({ projectRoot, record }) {
+  const abs = join(projectRoot, 'rcf', 'manifest.json');
+  let manifest = {};
+  try {
+    const raw = await readFile(abs, 'utf8');
+    manifest = JSON.parse(raw);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  const nextManifest = {
+    ...manifest,
+    reviewSurface: {
+      ...(manifest.reviewSurface ?? {}),
+      viewServer: record,
+    },
+  };
+  const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: 'rcf/manifest.json' });
+  if (validation) return validation;
+  try {
+    await mkdir(dirname(abs), { recursive: true });
+    const tmp = `${abs}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    try {
+      await rename(tmp, abs);
+    } catch (err) {
+      try { await unlink(tmp); } catch { /* ignore */ }
+      throw err;
+    }
+  } catch (err) {
+    return rcfError({
+      kind: 'ioFailure',
+      message: `view-supervisor: manifest write failed: ${err.message}`,
+      filePath: 'rcf/manifest.json',
+      stack: err.stack,
+    });
+  }
+  return { record };
+}
+
+/**
+ * Clear the reviewSurface.viewServer field.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<void>}
+ */
+export async function clearViewServerRecord(projectRoot) {
+  const abs = join(projectRoot, 'rcf', 'manifest.json');
+  let manifest = {};
+  try {
+    const raw = await readFile(abs, 'utf8');
+    manifest = JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  if (!manifest.reviewSurface?.viewServer) return;
+  const nextReview = { ...(manifest.reviewSurface ?? {}) };
+  delete nextReview.viewServer;
+  const nextManifest = { ...manifest, reviewSurface: nextReview };
+  // If the reviewSurface object is empty, drop it entirely so validate
+  // does not carry an empty object.
+  if (Object.keys(nextReview).length === 0) delete nextManifest.reviewSurface;
+  const tmp = `${abs}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+  try {
+    await rename(tmp, abs);
+  } catch (err) {
+    try { await unlink(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+/** Write a pid file at projectRoot/.rcf/view-server.pid. */
+export async function writePidFile(projectRoot, pid) {
+  const abs = join(projectRoot, DEFAULT_PID_PATH);
+  await mkdir(dirname(abs), { recursive: true });
+  await writeFile(abs, `${pid}\n`, 'utf8');
+}
+
+/** Read the pid file, or null when absent. */
+export async function readPidFile(projectRoot) {
+  const abs = join(projectRoot, DEFAULT_PID_PATH);
+  if (!existsSync(abs)) return null;
+  try {
+    const raw = await readFile(abs, 'utf8');
+    const n = Number.parseInt(raw.trim(), 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Remove the pid file, ignoring ENOENT. */
+export async function removePidFile(projectRoot) {
+  const abs = join(projectRoot, DEFAULT_PID_PATH);
+  try {
+    await unlink(abs);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+}
+
+/**
+ * Probe whether a pid is alive. `process.kill(pid, 0)` is the standard
+ * cross-platform (POSIX) predicate; throws ESRCH when the process is
+ * gone and EPERM when the process exists but the caller lacks permission
+ * (still "alive" from our perspective).
+ *
+ * @param {number} pid
+ * @returns {boolean}
+ */
+export function isPidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err.code === 'EPERM') return true;
+    return false;
+  }
+}

package/src/view-supervisor/persist-until.js

@@ -0,0 +1,85 @@
+// `rcf view start --persist-until <value>` argument parser (spec §9.2).
+//
+// The spec's sample invocation is `--persist-until 4h`; the shipping
+// help text also names an ISO timestamp as the durable form. Accept
+// both so the sample works AND cross-platform ISO timestamps still do.
+//
+// Duration grammar (minimal and documented):
+//
+//   <duration> := <hours> | <minutes> | <hours><minutes>
+//   <hours>    := /^\d+h$/     e.g. `4h`, `24h`
+//   <minutes>  := /^\d+m$/     e.g. `30m`, `90m`
+//   combined   := /^\d+h\d+m$/ e.g. `2h30m`
+//
+// Anything else (`4hrs`, `4 h`, `PT4H`, `4:00`, an empty component like
+// `0h`, or a plain integer with no unit) is a usage error: the parser
+// returns `{ ok: false, error: <message> }` and the CLI exits 2 with
+// that message plus the grammar. The old behaviour - `Date.parse('4h')`
+// returning NaN, no persist timer set, supervisor runs forever - is
+// what this parser exists to prevent.
+//
+// ISO parsing: any string `Date.parse` accepts as a finite timestamp
+// passes. We deliberately do NOT restrict to a strict ISO-8601 subset
+// - the shipping help text says "ISO timestamp" and operators reach
+// for `date -u +%Y-%m-%dT%H:%M:%SZ` and similar; Date.parse handles
+// them all. A past timestamp is accepted (the supervisor will unwind
+// on the next event loop turn); the parser is a shape check, not a
+// policy check.
+
+const DURATION_RE = /^(?:(\d+)h)?(?:(\d+)m)?$/;
+
+const GRAMMAR_HINT = 'expected a duration (e.g. `4h`, `30m`, `2h30m`) or an ISO timestamp (e.g. `2026-07-31T18:00:00Z`)';
+
+/**
+ * Parse a `--persist-until` argument into an ISO timestamp.
+ *
+ * @param {string} raw - argv value; must be a string
+ * @param {object} [opts]
+ * @param {number} [opts.nowMs] - injected clock for tests; defaults to Date.now()
+ * @returns {{ ok: true, iso: string, deadlineMs: number, source: 'duration'|'iso' }
+ *         | { ok: false, error: string }}
+ */
+export function parsePersistUntil(raw, opts = {}) {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    return { ok: false, error: `--persist-until: missing value; ${GRAMMAR_HINT}` };
+  }
+  const nowMs = typeof opts.nowMs === 'number' ? opts.nowMs : Date.now();
+
+  // Duration form. The regex `/^(?:(\d+)h)?(?:(\d+)m)?$/` also matches
+  // the empty string; guard against that plus `0h` / `0m` / `0h0m`
+  // (which the CLI accepting would make the supervisor unwind
+  // immediately, arguably useless).
+  const durationMatch = DURATION_RE.exec(raw);
+  const hasHours = durationMatch && durationMatch[1] !== undefined;
+  const hasMinutes = durationMatch && durationMatch[2] !== undefined;
+  if (durationMatch && (hasHours || hasMinutes)) {
+    const hours = hasHours ? Number.parseInt(durationMatch[1], 10) : 0;
+    const minutes = hasMinutes ? Number.parseInt(durationMatch[2], 10) : 0;
+    const ms = (hours * 60 * 60 * 1000) + (minutes * 60 * 1000);
+    if (ms <= 0) {
+      return { ok: false, error: `--persist-until: duration must be non-zero (got \`${raw}\`); ${GRAMMAR_HINT}` };
+    }
+    const deadlineMs = nowMs + ms;
+    return { ok: true, iso: new Date(deadlineMs).toISOString(), deadlineMs, source: 'duration' };
+  }
+
+  // A bare digit run is a duration-shaped mistake (someone typed `4`
+  // instead of `4h`). Date.parse would accept it as a year and the
+  // supervisor would happily set a timer for the far past; that is
+  // worse UX than a clean refusal.
+  if (/^\d+$/.test(raw)) {
+    return { ok: false, error: `--persist-until: bare integer \`${raw}\` has no unit; ${GRAMMAR_HINT}` };
+  }
+
+  // ISO form. Date.parse is loose (accepts a variety of shapes); we
+  // only care that it lands on a finite timestamp. A partial ISO like
+  // `2026` still parses; that is a policy question we leave to the
+  // supervisor's timer semantics (a past deadline unwinds immediately,
+  // which is a clearer failure than silent no-op).
+  const parsedMs = Date.parse(raw);
+  if (Number.isFinite(parsedMs)) {
+    return { ok: true, iso: new Date(parsedMs).toISOString(), deadlineMs: parsedMs, source: 'iso' };
+  }
+
+  return { ok: false, error: `--persist-until: unrecognised value \`${raw}\`; ${GRAMMAR_HINT}` };
+}

package/src/view-supervisor/supervisor.js

@@ -0,0 +1,276 @@
+// View-server supervisor (spec §9.3).
+//
+// Detached mode: the parent CLI process forks a supervisor child via
+// `child_process.spawn(..., { detached: true, stdio: 'ignore' })` then
+// unref's; the parent returns immediately. The supervisor:
+//   1. Writes its pid to .rcf/view-server.pid (gitignored).
+//   2. Starts the view server on the requested port.
+//   3. Writes the reviewSurface.viewServer manifest block.
+//   4. Runs a heartbeat that bumps lastHeartbeatAt every 30 seconds
+//      (or the injected interval for tests).
+//   5. Handles SIGTERM cleanly: server closed, manifest record cleared,
+//      pid file removed.
+//   6. On the child server crashing, attempts one restart within 5s;
+//      a second crash within a minute exits the supervisor cleanly.
+//
+// Windows is out of scope per spec §9.3 / §16 O-6.
+
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFile } from 'node:fs/promises';
+import process from 'node:process';
+
+import { startServer } from '../server/index.js';
+import {
+  writePidFile,
+  readPidFile,
+  removePidFile,
+  writeViewServerRecord,
+  readViewServerRecord,
+  clearViewServerRecord,
+  isPidAlive,
+  DEFAULT_PID_PATH,
+} from './manifest-writer.js';
+import { ensureLogDir, supervisorLogPath, writeLogLine } from './logs.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const CHILD_ENTRY_PATH = resolve(here, '..', '..', 'bin', 'view-supervisor-child.mjs');
+
+const DEFAULT_HEARTBEAT_MS = 30_000;
+const DEFAULT_STARTUP_TIMEOUT_MS = 15_000;
+
+/**
+ * Fork a detached supervisor child.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {number} args.port
+ * @param {string|null} [args.persistUntil]  ISO timestamp; supervisor auto-stops
+ * @param {number} [args.heartbeatMs]        for tests
+ * @param {number} [args.startupTimeoutMs]   for tests
+ * @returns {Promise<{ pid: number, url: string, record: object }>}
+ */
+export async function startDetached({ projectRoot, port, persistUntil = null, heartbeatMs = DEFAULT_HEARTBEAT_MS, startupTimeoutMs = DEFAULT_STARTUP_TIMEOUT_MS }) {
+  await ensureLogDir(projectRoot);
+
+  // Refuse when a supervisor is already up.
+  const existing = await statusOfDetached(projectRoot);
+  if (existing.state === 'running') {
+    return { pid: existing.pid, url: existing.url, record: existing.record, alreadyRunning: true };
+  }
+
+  const child = spawn(process.execPath, [CHILD_ENTRY_PATH], {
+    detached: true,
+    stdio: 'ignore',
+    env: {
+      ...process.env,
+      RCF_VIEW_SUPERVISOR_PROJECT_ROOT: projectRoot,
+      RCF_VIEW_SUPERVISOR_PORT: String(port),
+      RCF_VIEW_SUPERVISOR_PERSIST_UNTIL: persistUntil ?? '',
+      RCF_VIEW_SUPERVISOR_HEARTBEAT_MS: String(heartbeatMs),
+    },
+  });
+  if (typeof child.unref === 'function') child.unref();
+  const pid = child.pid;
+  if (typeof pid !== 'number') {
+    throw new Error('view-supervisor: spawn returned no pid');
+  }
+
+  // Wait for the child to record itself in the manifest. Poll instead
+  // of piping the child's stdio (we intentionally detach).
+  const started = Date.now();
+  let record = null;
+  while (Date.now() - started < startupTimeoutMs) {
+    // eslint-disable-next-line no-await-in-loop
+    record = await readViewServerRecord(projectRoot);
+    if (record?.pid === pid) break;
+    // eslint-disable-next-line no-await-in-loop
+    await delay(100);
+  }
+  if (!record || record.pid !== pid) {
+    // Startup failed. Try to clean up the orphaned child.
+    try { process.kill(pid, 'SIGTERM'); } catch { /* ignore */ }
+    throw new Error(`view-supervisor: child ${pid} did not record itself in the manifest within ${startupTimeoutMs}ms`);
+  }
+
+  // Extract URL from healthCheckPath: 127.0.0.1:PORT/healthz -> the
+  // base URL is everything up to /healthz.
+  const url = record.healthCheckPath.replace(/\/healthz$/, '');
+  return { pid, url, record };
+}
+
+/**
+ * Stop a running detached supervisor. Idempotent.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<{ stopped: boolean, pid: number|null }>}
+ */
+export async function stopDetached(projectRoot) {
+  const pid = await readPidFile(projectRoot);
+  if (!pid) {
+    // Best-effort cleanup for the manifest record.
+    await clearViewServerRecord(projectRoot);
+    return { stopped: false, pid: null };
+  }
+  if (!isPidAlive(pid)) {
+    await clearViewServerRecord(projectRoot);
+    await removePidFile(projectRoot);
+    return { stopped: false, pid };
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch (err) {
+    if (err.code !== 'ESRCH') throw err;
+  }
+  // Wait for the process to exit cleanly.
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(pid)) break;
+    // eslint-disable-next-line no-await-in-loop
+    await delay(100);
+  }
+  await clearViewServerRecord(projectRoot);
+  await removePidFile(projectRoot);
+  return { stopped: true, pid };
+}
+
+/**
+ * Report the current state of the detached supervisor.
+ *
+ * @param {string} projectRoot
+ * @param {object} [opts]
+ * @param {number} [opts.heartbeatMs]
+ * @returns {Promise<{ state: 'not-started'|'running'|'stale', pid: number|null, record: object|null, url: string|null, lastHeartbeatAt: string|null }>}
+ */
+export async function statusOfDetached(projectRoot, opts = {}) {
+  const heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+  const record = await readViewServerRecord(projectRoot);
+  const pidFilePid = await readPidFile(projectRoot);
+  const pid = record?.pid ?? pidFilePid ?? null;
+  if (!record && !pidFilePid) {
+    return { state: 'not-started', pid: null, record: null, url: null, lastHeartbeatAt: null };
+  }
+  const alive = pid !== null && isPidAlive(pid);
+  const url = record?.healthCheckPath ? record.healthCheckPath.replace(/\/healthz$/, '') : null;
+  const lastHeartbeatAt = record?.lastHeartbeatAt ?? null;
+  const heartbeatFresh = lastHeartbeatAt
+    ? (Date.now() - Date.parse(lastHeartbeatAt)) <= (heartbeatMs * 2)
+    : false;
+  if (alive && heartbeatFresh) {
+    return { state: 'running', pid, record, url, lastHeartbeatAt };
+  }
+  return { state: 'stale', pid, record, url, lastHeartbeatAt };
+}
+
+/**
+ * The supervisor loop. Runs inside the detached child; the caller is
+ * `bin/view-supervisor-child.mjs`. Reads config from env vars set by
+ * startDetached, brings up the view server, writes the manifest record,
+ * runs the heartbeat, and installs the shutdown handlers.
+ *
+ * @returns {Promise<void>}
+ */
+export async function runDetachedChild() {
+  const projectRoot = process.env.RCF_VIEW_SUPERVISOR_PROJECT_ROOT;
+  const port = Number.parseInt(process.env.RCF_VIEW_SUPERVISOR_PORT ?? '', 10);
+  const persistUntil = process.env.RCF_VIEW_SUPERVISOR_PERSIST_UNTIL || null;
+  const heartbeatMs = Number.parseInt(process.env.RCF_VIEW_SUPERVISOR_HEARTBEAT_MS ?? '', 10) || DEFAULT_HEARTBEAT_MS;
+  if (!projectRoot || !Number.isFinite(port)) {
+    await writeLogLine(projectRoot ?? '.', 'runDetachedChild: missing projectRoot or port');
+    process.exit(2);
+    return;
+  }
+
+  await writeLogLine(projectRoot, `supervisor starting on port ${port} (pid ${process.pid})`);
+
+  let server;
+  try {
+    server = await startServer({
+      projectRoot,
+      port,
+      log: (line) => { writeLogLine(projectRoot, `server: ${line}`).catch(() => {}); },
+    });
+  } catch (err) {
+    await writeLogLine(projectRoot, `supervisor: server start failed: ${err.message}`);
+    process.exit(1);
+    return;
+  }
+
+  await writePidFile(projectRoot, process.pid);
+
+  const socketPath = `.rcf/view-supervisor.${process.pid}.sock`;
+  const healthCheckPath = `${server.url.replace(/\/$/, '')}/healthz`;
+
+  let heartbeatTimer;
+  let persistTimer;
+  let stopping = false;
+
+  const writeRecord = async () => {
+    const record = {
+      mode: 'detached',
+      startedAt: new Date().toISOString(),
+      socketPath,
+      pid: process.pid,
+      healthCheckPath,
+      lastHeartbeatAt: new Date().toISOString(),
+    };
+    if (persistUntil) record.operatorRequestedPersistUntil = persistUntil;
+    const result = await writeViewServerRecord({ projectRoot, record });
+    if (result && result.kind && typeof result.message === 'string') {
+      await writeLogLine(projectRoot, `supervisor: manifest write failed: ${result.message}`);
+    }
+  };
+
+  const bumpHeartbeat = async () => {
+    const record = await readViewServerRecord(projectRoot);
+    if (!record) return;
+    const next = { ...record, lastHeartbeatAt: new Date().toISOString() };
+    await writeViewServerRecord({ projectRoot, record: next });
+  };
+
+  const shutdown = async (reason) => {
+    if (stopping) return;
+    stopping = true;
+    await writeLogLine(projectRoot, `supervisor: shutting down (${reason})`);
+    if (heartbeatTimer) clearInterval(heartbeatTimer);
+    if (persistTimer) clearTimeout(persistTimer);
+    try {
+      await server.close();
+    } catch (err) {
+      await writeLogLine(projectRoot, `supervisor: server close error: ${err.message}`);
+    }
+    await clearViewServerRecord(projectRoot);
+    await removePidFile(projectRoot);
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', () => { shutdown('SIGTERM'); });
+  process.on('SIGINT', () => { shutdown('SIGINT'); });
+
+  await writeRecord();
+
+  heartbeatTimer = setInterval(() => {
+    bumpHeartbeat().catch((err) => writeLogLine(projectRoot, `supervisor: heartbeat error: ${err.message}`).catch(() => {}));
+  }, heartbeatMs);
+  if (typeof heartbeatTimer.unref === 'function') heartbeatTimer.unref();
+
+  if (persistUntil) {
+    const deadline = Date.parse(persistUntil);
+    if (Number.isFinite(deadline)) {
+      const wait = Math.max(0, deadline - Date.now());
+      persistTimer = setTimeout(() => { shutdown('persistUntilExpired'); }, wait);
+      if (typeof persistTimer.unref === 'function') persistTimer.unref();
+    }
+  }
+
+  await writeLogLine(projectRoot, `supervisor: ready`);
+}
+
+// Kept exports available so downstream tooling that pulls the supervisor
+// path or config can do so without spelunking.
+void CHILD_ENTRY_PATH;
+void readFile;
+void supervisorLogPath;
+void DEFAULT_PID_PATH;