dev-harness-cli 1.0.0

package/cli/lib/contract.mjs

@@ -0,0 +1,306 @@
+/**
+ * contract — Sprint Contract management.
+ *
+ * Manages the generator-evaluator negotiation loop for pre-build agreement.
+ * The contract is stored in sprint-contract.md in the project root.
+ *
+ * Status flow:
+ *   pending → in-negotiation → agreed (or needs-revision → back to in-negotiation)
+ *
+ * Usage:
+ *   import { proposeContract, reviewContract, getContractStatus, validateContract } from './contract.mjs';
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { CONTRACT_PATH } from './paths.mjs';
+import { MAX_NEGOTIATION_ROUNDS } from './constants.mjs';
+
+// ── Status detection ─────────────────────────────────────────────────────────
+
+/**
+ * Read the agreement status from a sprint-contract.md file.
+ * Returns the current status, or null if file doesn't exist.
+ * @param {string} targetDir
+ * @returns {{ status: string|null, rounds: number, path: string }}
+ */
+export function getContractStatus(targetDir) {
+  const path = CONTRACT_PATH(targetDir);
+  if (!existsSync(path)) {
+    return { status: null, rounds: 0, path };
+  }
+
+  try {
+    const content = readFileSync(path, 'utf-8');
+    const lines = content.split('\n');
+
+    let status = null;
+    let rounds = 0;
+
+    for (const line of lines) {
+      const statusMatch = line.match(/\*\*Status:\*\*\s*(.+)/);
+      if (statusMatch) {
+        const raw = statusMatch[1].trim();
+        // Strip HTML comments from status value
+        const cleanRaw = raw.replace(/<!--.*?-->/g, '').trim();
+        // Map to canonical values
+        if (cleanRaw.toLowerCase().includes('agreed')) {status = 'agreed';}
+        else if (cleanRaw.toLowerCase().includes('needs revision')) {status = 'needs-revision';}
+        else if (cleanRaw.toLowerCase().includes('revision')) {status = 'needs-revision';}
+        else if (cleanRaw.toLowerCase().includes('escalated')) {status = 'escalated';}
+        else if (cleanRaw.length > 0) {status = 'pending';}
+      }
+
+      // Handle both `rounds: 0/5` and `rounds:** 0/5` (bold formatting)
+      const roundsMatch = line.match(/rounds?:\s*\*{0,2}\s*(\d+)\/(\d+)/);
+      if (roundsMatch) {
+        rounds = parseInt(roundsMatch[1], 10);
+      }
+    }
+
+    // If file was parsed but no status set, default to pending
+    if (status === null) {status = 'pending';}
+
+    return { status, rounds, path };
+  } catch {
+    return { status: 'error', rounds: 0, path };
+  }
+}
+
+/**
+ * Check if the contract is agreed (status === 'agreed').
+ * @param {string} targetDir
+ * @returns {boolean}
+ */
+export function isContractAgreed(targetDir) {
+  const { status } = getContractStatus(targetDir);
+  return status === 'agreed';
+}
+
+// ── Propose ──────────────────────────────────────────────────────────────────
+
+/**
+ * Propose or update a sprint contract.
+ *
+ * Writes sprint-contract.md with the Generator's proposed scope and criteria.
+ * If the file already exists, preserves the Evaluator Review section
+ * and only overwrites the Scope + Verification Criteria sections.
+ *
+ * @param {string} targetDir
+ * @param {object} proposal
+ * @param {string} proposal.scope — what will be built
+ * @param {string} [proposal.exclusions] — what will NOT be built
+ * @param {string[]} [proposal.criteria] — verification criteria
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function proposeContract(targetDir, proposal) {
+  const path = CONTRACT_PATH(targetDir);
+
+  let existingReview = '';
+  let existingStatus = '';
+
+  // Preserve evaluator review and status from existing contract
+  if (existsSync(path)) {
+    try {
+      const existing = readFileSync(path, 'utf-8');
+      const reviewMatch = existing.match(/## Evaluator Review[\s\S]*?(?=## Agreement|$)/);
+      if (reviewMatch) {existingReview = reviewMatch[0];}
+
+      const statusMatch = existing.match(/## Agreement Status[\s\S]*?(?=#|$)/);
+      if (statusMatch) {existingStatus = statusMatch[0];}
+    } catch {
+      // Ignore read errors
+    }
+  }
+
+  const criteriaList = (proposal.criteria || ['']).map(c => `${c}`).join('\n');
+
+  const content = `# Sprint Contract
+
+## Scope (Generator proposes)
+
+**I will build:**
+${proposal.scope || '<!-- Describe what will be built -->'}
+
+**I will NOT build:**
+${proposal.exclusions || '<!-- Explicit exclusions -->'}
+
+## Verification Criteria (Generator proposes)
+
+${criteriaList || '1. ...'}
+
+${existingReview || `## Evaluator Review (Evaluator fills in)
+
+- [ ] Scope is clear and bounded: <!-- yes/no — if no, explain -->
+- [ ] Verification criteria are sufficient: <!-- yes/no — if no, explain -->
+- [ ] Exclusions are reasonable: <!-- yes/no — if no, explain -->
+
+**Review notes:**
+<!-- Evaluator's feedback to Generator if revision is needed -->`}
+
+${existingStatus || `## Agreement Status
+
+**Status:** <!-- Agreed / Needs Revision -->
+**Negotiation rounds:** 0/${MAX_NEGOTIATION_ROUNDS}`}
+`;
+
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content, 'utf-8');
+    return { ok: true, error: null };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+// ── Review ───────────────────────────────────────────────────────────────────
+
+/**
+ * Review the current contract and update its status.
+ *
+ * Increments negotiation rounds and sets status to 'agreed' or 'needs-revision'.
+ * If rounds >= 5 and still not agreed, automatically escalates.
+ *
+ * @param {string} targetDir
+ * @param {'agreed'|'needs-revision'} decision
+ * @param {string} [notes] — evaluator's feedback
+ * @returns {{ ok: boolean, error: string|null, escalated: boolean }}
+ */
+export function reviewContract(targetDir, decision, notes) {
+  const path = CONTRACT_PATH(targetDir);
+  if (!existsSync(path)) {
+    return { ok: false, error: 'No sprint-contract.md found. Run: harness-dev contract propose first', escalated: false };
+  }
+
+  try {
+    let content = readFileSync(path, 'utf-8');
+    const { rounds } = getContractStatus(targetDir);
+    // Agreement is not a negotiation round — only increment on revision.
+    const newRounds = (decision === 'agreed') ? rounds : rounds + 1;
+    const escalated = newRounds >= MAX_NEGOTIATION_ROUNDS && decision !== 'agreed';
+
+    // Update agreement status
+    const displayStatus = escalated
+      ? 'Escalated — awaiting human adjudication'
+      : (decision === 'agreed' ? 'Agreed' : 'Needs Revision');
+    const escapedDecision = displayStatus;
+
+    content = content.replace(
+      /\*\*Status:\*\*.*/,
+      `**Status:** ${escapedDecision}`,
+    );
+    content = content.replace(
+      /(rounds?:\s*\*{0,2}\s*)\d+\/\d+/,
+      `$1${newRounds}/${MAX_NEGOTIATION_ROUNDS}`,
+    );
+
+    // Update review notes if provided
+    if (notes) {
+      const notesSection = `**Review notes:**\n${notes}\n`;
+      content = content.replace(
+        /\*\*Review notes:\*\*[\s\S]*?(?=\n##|$)/,
+        notesSection,
+      );
+    }
+
+    // Auto-escalation: append escalation section to file
+    if (escalated) {
+      // Remove old escalation section if present
+      if (content.includes('## Escalation')) {
+        content = content.replace(/\n## Escalation[\s\S]*$/, '');
+      }
+      content += `\n\n## Escalation\n\n**Reason:** Agents could not reach agreement after ${newRounds} rounds\n\n**Escalated at:** ${new Date().toISOString()}`;
+    }
+
+    writeFileSync(path, content, 'utf-8');
+
+    return { ok: true, error: null, escalated };
+  } catch (err) {
+    return { ok: false, error: err.message, escalated: false };
+  }
+}
+
+// ── Escalate ─────────────────────────────────────────────────────────────────
+
+/**
+ * Escalate a stalled contract negotiation to human.
+ * Sets status to 'escalated' and records the escalation reason.
+ * @param {string} targetDir
+ * @param {string} reason
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function escalateContract(targetDir, reason) {
+  const path = CONTRACT_PATH(targetDir);
+  if (!existsSync(path)) {
+    return { ok: false, error: 'No sprint-contract.md found. Nothing to escalate.' };
+  }
+
+  try {
+    let content = readFileSync(path, 'utf-8');
+
+    content = content.replace(
+      /\*\*Status:\*\*.*/,
+      `**Status:** Escalated — awaiting human adjudication`,
+    );
+
+    const escalationNote = `\n\n## Escalation\n\n**Reason:** ${reason || `Agents could not reach agreement after ${MAX_NEGOTIATION_ROUNDS} rounds`}\n\n**Escalated at:** ${new Date().toISOString()}`;
+
+    // Append escalation section before the end
+    if (content.includes('## Escalation')) {
+      content = content.replace(
+        /## Escalation[\s\S]*$/,
+        escalationNote.trim(),
+      );
+    } else {
+      content += escalationNote;
+    }
+
+    writeFileSync(path, content, 'utf-8');
+    return { ok: true, error: null };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+// ── Validation (for gates) ───────────────────────────────────────────────────
+
+/**
+ * Validate contract for gate checking.
+ * Returns pass/fail with detail message.
+ * @param {string} targetDir
+ * @returns {{ name: string, pass: boolean, detail: string }}
+ */
+export function validateContract(targetDir) {
+  const { status, rounds } = getContractStatus(targetDir);
+
+  if (status === null) {
+    return {
+      name: 'contract-agreed',
+      pass: false,
+      detail: 'Sprint contract not yet proposed. Run: harness-dev contract propose',
+    };
+  }
+
+  if (status === 'agreed') {
+    return {
+      name: 'contract-agreed',
+      pass: true,
+      detail: `Sprint contract agreed after ${rounds} round(s)`,
+    };
+  }
+
+  if (status === 'escalated') {
+    return {
+      name: 'contract-agreed',
+      pass: false,
+      detail: 'Sprint contract escalated to human. Awaiting resolution.',
+    };
+  }
+
+  // needs-revision or pending
+  const noun = status === 'needs-revision' ? 'needs revision' : 'pending';
+  return {
+    name: 'contract-agreed',
+    pass: false,
+    detail: `Sprint contract ${noun} (round ${rounds}/${MAX_NEGOTIATION_ROUNDS}). Run: harness-dev contract review`,
+  };
+}

package/cli/lib/detect-stack.mjs

@@ -0,0 +1,235 @@
+/**
+ * Stack detection engine.
+ *
+ * Scans a directory up to 2 levels deep, identifies the project stack
+ * by matching config files and source extensions in priority order.
+ * Pure file-I/O — no external deps, no heavy parsing.
+ */
+
+import { readdirSync } from 'node:fs';
+import { join, extname, basename, resolve } from 'node:path';
+import { readJson } from './file-io.mjs';
+import { STACKS_SCHEMA_PATH } from './paths.mjs';
+import { STACK_SCAN_DEPTH } from './constants.mjs';
+import { loadConfig } from './state.mjs';
+
+/** Directories to skip when scanning. */
+const IGNORE_DIRS = new Set([
+  '.git', 'node_modules', 'venv', '.venv', '__pycache__',
+  'dist', 'build', '.next', 'target',
+  '.tox', '.nox', '.eggs', '*.egg-info',
+  '.mypy_cache', '.pytest_cache', '.ruff_cache',
+  '.dart_tool', '.packages',
+  'third_party', 'vendor',
+]);
+
+/** Maximum directory depth to scan (0 = current dir only). */
+const SCAN_DEPTH = STACK_SCAN_DEPTH;
+
+/**
+ * Recursively collect all file paths up to maxDepth.
+ * @param {string} dir — absolute path to start from
+ * @param {number} maxDepth
+ * @returns {string[]}
+ */
+function scanFiles(dir, maxDepth = SCAN_DEPTH) {
+  const files = [];
+  const queue = [{ path: dir, depth: 0 }];
+
+  while (queue.length > 0) {
+    const { path: current, depth } = queue.shift();
+    if (depth > maxDepth) {continue;}
+
+    let entries;
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue; // permission denied, not found, etc.
+    }
+
+    for (const entry of entries) {
+      const fullPath = join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORE_DIRS.has(entry.name)) {
+          queue.push({ path: fullPath, depth: depth + 1 });
+        }
+      } else if (entry.isFile()) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Detect the project stack in a directory.
+ *
+ * @param {string} targetDir — directory to scan (default: cwd)
+ * @returns {{ name: string, label: string, evidence: string[] }}
+ */
+export function detectStack(targetDir = '.') {
+  const absDir = resolve(targetDir);
+
+  // Quick check: does the directory exist at all?
+  try {
+    if (readdirSync(absDir).length === 0) {
+      process.stderr.write(
+        `Warning: ${absDir} is empty. Could not detect project stack; falling back to "generic".\n`,
+      );
+      return { name: 'generic', label: 'Generic', evidence: ['directory empty or unreadable'] };
+    }
+  } catch {
+    process.stderr.write(
+      `Warning: cannot read ${absDir}. Could not detect project stack; falling back to "generic".\n`,
+    );
+    return { name: 'generic', label: 'Generic', evidence: ['cannot read directory'] };
+  }
+
+  const files = scanFiles(absDir, SCAN_DEPTH);
+
+  // Build detection primitives
+  const topFiles = new Set();          // basenames in target dir only
+  const allExts  = new Set();          // all unique extensions found
+
+  // Extension-group booleans for pair rules
+  let hasC     = false;
+  let hasCpp   = false;
+  let hasVhdl  = false;
+  let hasVerilog = false;
+
+  for (const f of files) {
+    const ext = extname(f).toLowerCase();
+    const name = basename(f);
+    const dir = resolve(f, '..');
+
+    if (ext) {allExts.add(ext);}
+    if (dir === absDir) {topFiles.add(name);}
+
+    // Classify for pair / ext-only rules (avoid re-iterating)
+    if (ext === '.c')              {hasC = true;}
+    if (['.cpp','.hpp','.cc','.cxx'].includes(ext)) {hasCpp = true;}
+    if (['.vhdl','.vhd'].includes(ext)) {hasVhdl = true;}
+    if (['.v','.sv'].includes(ext)) {hasVerilog = true;}
+  }
+
+  // ── helpers ────────────────────────────────────────────────────────────
+  const hasTop  = (name)       => topFiles.has(name);
+  const hasAnyTop = (names)    => names.some(n => topFiles.has(n));
+  const hasExt  = (ext)        => allExts.has(ext);
+  const hasAnyExt = (exts)     => exts.some(e => allExts.has(e));
+
+  // ── detection rules (priority order — first wins) ──────────────────────
+
+  // 1. Python
+  if (hasAnyTop(['pyproject.toml', 'setup.py', 'requirements.txt', 'Pipfile'])) {
+    return { name: 'python', label: 'Python',     evidence: ['config file found'] };
+  }
+  if (hasExt('.py')) {
+    return { name: 'python', label: 'Python',     evidence: ['.py files found'] };
+  }
+
+  // 2. Java
+  if (hasAnyTop(['pom.xml', 'build.gradle'])) {
+    return { name: 'java',   label: 'Java',       evidence: ['config file found'] };
+  }
+  if (hasExt('.java')) {
+    return { name: 'java',   label: 'Java',       evidence: ['.java files found'] };
+  }
+
+  // 3. Kotlin
+  if (hasTop('build.gradle.kts')) {
+    return { name: 'kotlin', label: 'Kotlin',     evidence: ['build.gradle.kts found'] };
+  }
+  if (hasAnyExt(['.kt', '.kts'])) {
+    return { name: 'kotlin', label: 'Kotlin',     evidence: ['.kt/.kts files found'] };
+  }
+
+  // 4. Node
+  if (hasAnyTop(['package.json', 'tsconfig.json', 'yarn.lock', 'pnpm-lock.yaml'])) {
+    return { name: 'node',   label: 'Node.js',    evidence: ['config file found'] };
+  }
+  if (hasAnyExt(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'])) {
+    return { name: 'node',   label: 'Node.js',    evidence: ['JS/TS source files found'] };
+  }
+
+  // 5. Go
+  if (hasTop('go.mod')) {
+    return { name: 'go',     label: 'Go',         evidence: ['go.mod found'] };
+  }
+  if (hasExt('.go')) {
+    return { name: 'go',     label: 'Go',         evidence: ['.go files found'] };
+  }
+
+  // 6. Rust
+  if (hasTop('Cargo.toml')) {
+    return { name: 'rust',   label: 'Rust',       evidence: ['Cargo.toml found'] };
+  }
+  if (hasExt('.rs')) {
+    return { name: 'rust',   label: 'Rust',       evidence: ['.rs files found'] };
+  }
+
+  // 7. C — .c files found
+  if (hasC) {
+    return { name: 'c',      label: 'C',          evidence: ['.c files found'] };
+  }
+
+  // 8. C++ — .cpp/.hpp/.cc/.cxx files found
+  if (hasCpp) {
+    return { name: 'cpp',    label: 'C++',        evidence: ['.cpp/.hpp files found'] };
+  }
+
+  // 9. .NET — .cs/.fs/.vb files found
+  if (hasAnyExt(['.cs', '.fs', '.vb'])) {
+    return { name: 'dotnet', label: '.NET',       evidence: ['.cs/.fs/.vb files found'] };
+  }
+
+  // 10. MATLAB — .m files found (low priority to avoid conflicting with other stacks)
+  if (hasExt('.m')) {
+    return { name: 'matlab', label: 'MATLAB',     evidence: ['.m files found'] };
+  }
+
+  // 11. VHDL
+  if (hasVhdl) {
+    return { name: 'vhdl',   label: 'VHDL',       evidence: ['.vhdl/.vhd files found'] };
+  }
+
+  // 12. Verilog
+  if (hasVerilog) {
+    return { name: 'verilog', label: 'Verilog/SystemVerilog', evidence: ['.v/.sv files found'] };
+  }
+
+  // Fallback: no known stack indicators. Warn so the user knows detection
+  // failed rather than silently getting a generic stack.
+  process.stderr.write(
+    `Warning: could not detect project stack in ${absDir}. Falling back to "generic".\n`,
+  );
+  return { name: 'generic', label: 'Generic',     evidence: ['no known stack indicators'] };
+}
+
+/**
+ * Load stack metadata from the stacks schema, with optional config.stackMeta override.
+ * Priority: config.stackMeta (if targetDir given and config has it) > built-in stacks.json.
+ * @param {string} stackName
+ * @param {string} [targetDir] — optional project dir to read config.stackMeta from
+ * @returns {object|null}
+ */
+export function getStackMeta(stackName, targetDir) {
+  // 1. Read built-in metadata from stacks.json
+  const { ok, data } = readJson(STACKS_SCHEMA_PATH);
+  const builtIn = (ok && data) ? (data[stackName] || data.generic || null) : null;
+
+  // 2. If targetDir given, check config.stackMeta for user/agent overrides
+  if (targetDir) {
+    try {
+      const { config, ok: cfgOk } = loadConfig(targetDir);
+      if (cfgOk && config.stackMeta && typeof config.stackMeta === 'object') {
+        return { ...builtIn, ...config.stackMeta };
+      }
+    } catch {
+      // config unreadable — use built-in
+    }
+  }
+
+  return builtIn;
+}

package/cli/lib/errors.mjs

@@ -0,0 +1,71 @@
+/**
+ * Error handling — exit codes, error classes, formatting.
+ * Every output path supports --json for machine parsing.
+ */
+
+export const EXIT = Object.freeze({
+  SUCCESS: 0,
+  VALIDATION_FAILURE: 1,
+  USAGE_ERROR: 2,
+  INTERNAL_ERROR: 3,
+});
+
+/**
+ * Thrown for user-facing errors (bad args, unknown commands, etc.)
+ */
+export class CliError extends Error {
+  constructor(message, exitCode = EXIT.USAGE_ERROR) {
+    super(message);
+    this.exitCode = exitCode;
+    this.name = 'CliError';
+  }
+}
+
+/**
+ * Thrown when a gate validation check fails.
+ */
+export class ValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.exitCode = EXIT.VALIDATION_FAILURE;
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * Format error for output.
+ * @param {Error} err
+ * @param {boolean} json
+ * @returns {string}
+ */
+export function formatError(err, json = false) {
+  const code = err.exitCode ?? EXIT.INTERNAL_ERROR;
+  if (json) {
+    const payload = {
+      error: err.name ?? 'Error',
+      message: err.message,
+      exitCode: code,
+    };
+    // Include stack trace for internal errors (exit 3) to aid debugging.
+    // User-facing errors (exit 1/2) stay clean for machine parsing.
+    if (code === EXIT.INTERNAL_ERROR && err.stack) {
+      payload.stack = err.stack;
+    }
+    return JSON.stringify(payload);
+  }
+  const label = code === 2 ? 'Usage error' : code === 1 ? 'Validation' : 'Error';
+  return `${label}: ${err.message}`;
+}
+
+/**
+ * Print error to stderr and exit with the appropriate code.
+ * @param {Error} err
+ * @param {boolean} json
+ */
+export function die(err, json = false) {
+  const msg = formatError(err, json);
+  const code = err.exitCode ?? EXIT.INTERNAL_ERROR;
+  // JSON errors always go to stderr so stdout stays parseable
+  process.stderr.write(msg + '\n');
+  process.exit(code);
+}

package/cli/lib/file-io.mjs

@@ -0,0 +1,90 @@
+/**
+ * file-io — Centralized JSON and text file I/O helpers.
+ *
+ * Standardizes the readFileSync + JSON.parse + try/catch pattern duplicated
+ * across state.mjs, contract.mjs, detect-stack.mjs, ralph-inner.mjs, etc.
+ * All helpers return result objects ({ ok, data, error }) and never throw.
+ *
+ * Usage:
+ *   import { readJson, writeJson, readText, writeText } from './file-io.mjs';
+ *   const { ok, data, error } = readJson('/path/to/config.json');
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * Read and parse a JSON file. Never throws.
+ * @param {string} filePath — absolute path
+ * @returns {{ ok: boolean, data: object|null, error: string|null }}
+ */
+export function readJson(filePath) {
+  if (!existsSync(filePath)) {
+    return { ok: false, data: null, error: `Not found: ${filePath}` };
+  }
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const data = JSON.parse(raw);
+    return { ok: true, data, error: null };
+  } catch (err) {
+    return { ok: false, data: null, error: `Invalid JSON in ${filePath}: ${err.message}` };
+  }
+}
+
+/**
+ * Serialize and write a JSON file (pretty-printed, 2-space indent, trailing newline).
+ * Creates parent directories if needed. Never throws.
+ * @param {string} filePath
+ * @param {object} data
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function writeJson(filePath, data) {
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    return { ok: true, error: null };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Read a text file. Never throws.
+ * @param {string} filePath
+ * @returns {{ ok: boolean, data: string|null, error: string|null }}
+ */
+export function readText(filePath) {
+  if (!existsSync(filePath)) {
+    return { ok: false, data: null, error: `Not found: ${filePath}` };
+  }
+  try {
+    const data = readFileSync(filePath, 'utf-8');
+    return { ok: true, data, error: null };
+  } catch (err) {
+    return { ok: false, data: null, error: err.message };
+  }
+}
+
+/**
+ * Write a text file. Creates parent directories if needed. Never throws.
+ * @param {string} filePath
+ * @param {string} text
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function writeText(filePath, text) {
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, text, 'utf-8');
+    return { ok: true, error: null };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Check whether a file exists.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function fileExists(filePath) {
+  return existsSync(filePath);
+}