spec-and-loop 1.0.8 → 1.2.0

package/lib/mini-ralph/errors.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ERRORS_FILE = 'errors.md';
+
+function errorsPath(ralphDir) {
+  return path.join(ralphDir, ERRORS_FILE);
+}
+
+function read(ralphDir, limit) {
+  const entries = _readRawEntries(ralphDir);
+  if (!entries.length) return '';
+  if (limit !== undefined && limit < entries.length) {
+    return entries.slice(-limit).join('\n---\n');
+  }
+  return entries.join('\n---\n');
+}
+
+function readEntries(ralphDir, limit) {
+  const entries = _readRawEntries(ralphDir).map(_parseEntry).filter(Boolean);
+  if (limit !== undefined && limit < entries.length) {
+    return entries.slice(-limit);
+  }
+  return entries;
+}
+
+function count(ralphDir) {
+  return _readRawEntries(ralphDir).length;
+}
+
+function latest(ralphDir) {
+  const entries = readEntries(ralphDir, 1);
+  return entries.length > 0 ? entries[0] : null;
+}
+
+function append(ralphDir, entry) {
+  _ensureDir(ralphDir);
+  const file = errorsPath(ralphDir);
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const separator = existing && !existing.endsWith('\n') ? '\n' : '';
+  const timestamp = new Date().toISOString();
+  const text = [
+    '---',
+    `Timestamp: ${timestamp}`,
+    `Iteration: ${entry.iteration}`,
+    `Task: ${entry.task}`,
+    `Exit Code: ${entry.exitCode}`,
+    '',
+    '### stderr',
+    entry.stderr || '',
+    '',
+    '### stdout',
+    entry.stdout || '',
+    '',
+  ].join('\n');
+  fs.writeFileSync(file, `${existing}${separator}${text}`, 'utf8');
+}
+
+function clear(ralphDir) {
+  const file = errorsPath(ralphDir);
+  if (fs.existsSync(file)) {
+    fs.unlinkSync(file);
+  }
+}
+
+function archive(ralphDir) {
+  const file = errorsPath(ralphDir);
+  if (!fs.existsSync(file)) return null;
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const archiveFile = path.join(ralphDir, `errors_${timestamp}.md`);
+  fs.copyFileSync(file, archiveFile);
+  return archiveFile;
+}
+
+function _ensureDir(ralphDir) {
+  if (!fs.existsSync(ralphDir)) {
+    fs.mkdirSync(ralphDir, { recursive: true });
+  }
+}
+
+function _readRawEntries(ralphDir) {
+  const file = errorsPath(ralphDir);
+  if (!fs.existsSync(file)) return [];
+  const content = fs.readFileSync(file, 'utf8').trim();
+  if (!content) return [];
+  return content.split(/^---$/m).filter((entry) => entry.trim());
+}
+
+function _parseEntry(entry) {
+  const trimmed = entry.trim();
+  if (!trimmed) return null;
+
+  const timestampMatch = trimmed.match(/^Timestamp: (.+)$/m);
+  const iterationMatch = trimmed.match(/^Iteration: (.+)$/m);
+  const taskMatch = trimmed.match(/^Task: (.+)$/m);
+  const exitCodeMatch = trimmed.match(/^Exit Code: (.+)$/m);
+  const stderrMatch = trimmed.match(/(?:^|\n)### stderr\n([\s\S]*?)(?=\n### stdout\n|$)/);
+  const stdoutMatch = trimmed.match(/(?:^|\n)### stdout\n([\s\S]*?)$/);
+
+  return {
+    timestamp: timestampMatch ? timestampMatch[1].trim() : '',
+    iteration: iterationMatch ? Number(iterationMatch[1].trim()) : NaN,
+    task: taskMatch ? taskMatch[1].trim() : '',
+    exitCode: exitCodeMatch ? Number(exitCodeMatch[1].trim()) : NaN,
+    stderr: stderrMatch ? stderrMatch[1].trim() : '',
+    stdout: stdoutMatch ? stdoutMatch[1].trim() : '',
+  };
+}
+
+module.exports = { errorsPath, read, readEntries, count, latest, append, clear, archive };

package/lib/mini-ralph/history.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * history.js - Iteration history persistence for mini-ralph.
+ *
+ * Manages reading and writing ralph-history.json under the .ralph/ directory.
+ * Each completed iteration appends an entry with duration, completion
+ * detection, tool usage summaries, and file-change information.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const HISTORY_FILE = 'ralph-history.json';
+
+/**
+ * Return the absolute path to the history file.
+ *
+ * @param {string} ralphDir
+ * @returns {string}
+ */
+function historyPath(ralphDir) {
+  return path.join(ralphDir, HISTORY_FILE);
+}
+
+/**
+ * Read history entries. Returns an empty array if the file does not exist.
+ *
+ * @param {string} ralphDir
+ * @returns {Array<object>}
+ */
+function read(ralphDir) {
+  const file = historyPath(ralphDir);
+  if (!fs.existsSync(file)) return [];
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Append an iteration result entry to history.
+ *
+ * @param {string} ralphDir
+ * @param {object} entry
+ * @param {number} entry.iteration         - Iteration number
+ * @param {number} entry.duration          - Duration in milliseconds
+ * @param {boolean} entry.completionDetected
+ * @param {boolean} entry.taskDetected
+ * @param {Array}  entry.toolUsage         - Tool usage summary array
+ * @param {Array}  entry.filesChanged      - Files changed in this iteration
+ * @param {number} entry.exitCode          - OpenCode exit code
+ */
+function append(ralphDir, entry) {
+  _ensureDir(ralphDir);
+  const entries = read(ralphDir);
+  entries.push(Object.assign({ timestamp: new Date().toISOString() }, entry));
+  _write(ralphDir, entries);
+}
+
+/**
+ * Return the N most recent history entries.
+ *
+ * @param {string} ralphDir
+ * @param {number} [n=5]
+ * @returns {Array<object>}
+ */
+function recent(ralphDir, n = 5) {
+  const entries = read(ralphDir);
+  return entries.slice(-n);
+}
+
+/**
+ * Clear all history.
+ *
+ * @param {string} ralphDir
+ */
+function clear(ralphDir) {
+  _write(ralphDir, []);
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function _ensureDir(ralphDir) {
+  if (!fs.existsSync(ralphDir)) {
+    fs.mkdirSync(ralphDir, { recursive: true });
+  }
+}
+
+function _write(ralphDir, data) {
+  _ensureDir(ralphDir);
+  fs.writeFileSync(historyPath(ralphDir), JSON.stringify(data, null, 2), 'utf8');
+}
+
+module.exports = { read, append, recent, clear, historyPath };

package/lib/mini-ralph/index.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * mini-ralph: Internal Ralph-style iteration engine for spec-and-loop.
+ *
+ * This module provides a self-contained loop runtime that replaces the
+ * external @th0rgal/ralph-wiggum dependency. It supports the critical
+ * OpenSpec-first subset: iterative OpenCode invocation, task-mode
+ * progression, prompt file/template support, completion/task promises,
+ * loop state/history persistence, status dashboard, add/clear context,
+ * and --no-commit.
+ *
+ * This is an internal implementation detail. The documented user-facing
+ * interface is ralph-run.
+ */
+
+const runner = require('./runner');
+const state = require('./state');
+const history = require('./history');
+const context = require('./context');
+const errors = require('./errors');
+const tasks = require('./tasks');
+const status = require('./status');
+const prompt = require('./prompt');
+
+/**
+ * Run the mini Ralph loop with the provided options.
+ *
+ * @param {object} options
+ * @param {string} options.promptFile        - Path to the prompt file (required unless promptText given)
+ * @param {string} [options.promptText]      - Inline prompt text
+ * @param {string} [options.promptTemplate]  - Path to a prompt template file
+ * @param {string} options.ralphDir          - Path to the .ralph/ working directory
+ * @param {number} [options.minIterations]   - Minimum iterations before completion (default: 1)
+ * @param {number} [options.maxIterations]   - Maximum iterations (default: 50)
+ * @param {string} [options.completionPromise] - Promise string signaling loop completion (default: "COMPLETE")
+ * @param {string} [options.taskPromise]     - Promise string signaling task completion (default: "READY_FOR_NEXT_TASK")
+ * @param {boolean} [options.tasksMode]      - Enable tasks mode (default: false)
+ * @param {string} [options.tasksFile]       - Path to tasks file when tasksMode is true
+ * @param {boolean} [options.noCommit]       - Suppress auto-commit (default: false)
+ * @param {string} [options.model]           - Optional model override
+ * @param {boolean} [options.verbose]        - Enable verbose output (default: false)
+ * @returns {Promise<object>} Result object with { completed, iterations, exitReason }
+ */
+async function run(options) {
+  return runner.run(options);
+}
+
+/**
+ * Print the status dashboard for the current loop state.
+ *
+ * @param {string} ralphDir - Path to the .ralph/ working directory
+ * @param {string} [tasksFile] - Optional path to the tasks.md file for task progress
+ * @returns {string} Formatted status output
+ */
+function getStatus(ralphDir, tasksFile) {
+  return status.render(ralphDir, tasksFile || null);
+}
+
+/**
+ * Add pending context to be injected into the next iteration.
+ *
+ * @param {string} ralphDir  - Path to the .ralph/ working directory
+ * @param {string} text      - Context text to add
+ */
+function addContext(ralphDir, text) {
+  context.add(ralphDir, text);
+}
+
+/**
+ * Clear all pending context.
+ *
+ * @param {string} ralphDir - Path to the .ralph/ working directory
+ */
+function clearContext(ralphDir) {
+  context.clear(ralphDir);
+}
+
+module.exports = {
+  run,
+  getStatus,
+  addContext,
+  clearContext,
+  // Expose sub-modules for internal use and testing
+  _state: state,
+  _history: history,
+  _context: context,
+  _errors: errors,
+  _tasks: tasks,
+  _prompt: prompt,
+  _runner: runner,
+  _status: status,
+};

package/lib/mini-ralph/invoker.js

@@ -0,0 +1,243 @@
+'use strict';
+
+/**
+ * invoker.js - OpenCode process invocation for mini-ralph.
+ *
+ * Isolates child_process.spawn() calls so the runner module can be tested
+ * with a mocked invoker. Streams stdout/stderr to the terminal while also
+ * capturing output for promise detection and history recording.
+ *
+ * This module focuses on a single agent: opencode. Multi-agent support is
+ * explicitly out of scope for the first-pass mini Ralph subset.
+ */
+
+const { spawn, execFileSync } = require('child_process');
+
+/**
+ * Invoke OpenCode with the given prompt and return a result object.
+ *
+ * @param {object} opts
+ * @param {string} opts.prompt      - Rendered prompt text to send to OpenCode
+ * @param {string} [opts.model]     - Optional model override
+ * @param {boolean} [opts.noCommit] - Skip git commit if true
+ * @param {boolean} [opts.verbose]  - Enable verbose output
+ * @param {string}  [opts.ralphDir] - Reserved for caller compatibility
+ * @returns {Promise<{stdout: string, exitCode: number, toolUsage: Array, filesChanged: Array}>}
+ */
+async function invoke(opts) {
+  const {
+    prompt,
+    model,
+    noCommit = false,
+    verbose = false,
+  } = opts;
+
+  if (!prompt || !prompt.trim()) {
+    throw new Error('mini-ralph invoker: prompt is empty');
+  }
+
+  const args = ['run'];
+  if (model) {
+    args.push('--model', model);
+  }
+  args.push(prompt);
+
+  if (verbose) {
+    process.stderr.write(
+      `[mini-ralph] invoking: opencode ${args.slice(0, -1).join(' ')} <prompt>\n`
+    );
+  }
+
+  // Snapshot git-tracked files before invocation for file-change detection
+  const preSnapshot = _gitSnapshot();
+
+  const result = await _spawnOpenCode(args, verbose);
+  const combinedOutput = [result.stdout, result.stderr].filter(Boolean).join('\n');
+
+  if (_looksLikeCliHelp(combinedOutput)) {
+    throw new Error(
+      'mini-ralph invoker: opencode printed CLI help instead of running the prompt. ' +
+      'The installed opencode CLI is likely incompatible with this version of spec-and-loop.'
+    );
+  }
+
+  // Detect which files changed during this iteration
+  const postSnapshot = _gitSnapshot();
+  const filesChanged = _diffSnapshots(preSnapshot, postSnapshot);
+
+  return {
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.exitCode,
+    toolUsage: _extractToolUsage(result.stdout),
+    filesChanged,
+  };
+}
+
+/**
+ * Spawn the opencode process and stream output to terminal while capturing.
+ *
+ * @param {Array<string>} args
+ * @param {boolean} verbose
+ * @returns {Promise<{stdout: string, exitCode: number}>}
+ */
+function _spawnOpenCode(args, verbose) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('opencode', args, {
+      stdio: ['inherit', 'pipe', 'pipe'],
+      env: process.env,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (chunk) => {
+      const text = chunk.toString();
+      stdout += text;
+      process.stdout.write(chunk);
+    });
+
+    child.stderr.on('data', (chunk) => {
+      const text = chunk.toString();
+      stderr += text;
+      process.stderr.write(chunk);
+    });
+
+    child.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        reject(new Error('mini-ralph invoker: opencode CLI not found. Please install opencode: npm install -g opencode-ai'));
+      } else {
+        reject(new Error(`mini-ralph invoker: failed to start opencode: ${err.message}`));
+      }
+    });
+
+    child.on('close', (code) => {
+      resolve({ stdout, stderr, exitCode: code || 0 });
+    });
+  });
+}
+
+/**
+ * Detect whether OpenCode printed its CLI help banner instead of executing the
+ * requested prompt. This usually means the invocation contract drifted.
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+function _looksLikeCliHelp(text) {
+  if (!text) return false;
+
+  // Only inspect the opening portion of the transcript so help-like strings
+  // echoed later in diffs or test output do not masquerade as a CLI banner.
+  const normalized = text
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/\r/g, '');
+  const lines = normalized
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const openingText = lines.slice(0, 40).join('\n');
+
+  const looksLikeRunHelp =
+    openingText.includes('opencode run [message..]') &&
+    openingText.includes('run opencode with a message') &&
+    openingText.includes('Positionals:') &&
+    openingText.includes('Options:');
+
+  const looksLikeTopLevelHelp =
+    openingText.includes('Commands:') &&
+    openingText.includes('Options:') &&
+    openingText.includes('opencode [project]') &&
+    openingText.includes('opencode run [message..]');
+
+  return looksLikeRunHelp || looksLikeTopLevelHelp;
+}
+
+/**
+ * Extract a compact tool usage summary from OpenCode output.
+ * Returns an array of { tool, count } objects.
+ *
+ * @param {string} text
+ * @returns {Array<{tool: string, count: number}>}
+ */
+function _extractToolUsage(text) {
+  if (!text) return [];
+
+  // Heuristic: count occurrences of common tool call patterns in output
+  const toolPatterns = [
+    'Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep', 'Task',
+    'TodoWrite', 'WebFetch',
+  ];
+
+  const usage = [];
+  for (const tool of toolPatterns) {
+    const regex = new RegExp(`\\b${tool}\\b`, 'g');
+    const matches = text.match(regex);
+    if (matches && matches.length > 0) {
+      usage.push({ tool, count: matches.length });
+    }
+  }
+
+  return usage;
+}
+
+/**
+ * Take a snapshot of modified/untracked files via git status.
+ * Returns a Set of file paths relative to the repo root.
+ * Returns an empty Set if git is unavailable or not in a repo.
+ *
+ * @returns {Set<string>}
+ */
+function _gitSnapshot() {
+  try {
+    // git status --porcelain outputs modified, added, deleted, untracked files
+    const output = execFileSync('git', ['status', '--porcelain'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const files = new Set();
+    for (const line of output.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      // Format: XY filename  (first two chars are status, then space, then path)
+      const filePath = line.slice(3).trim();
+      if (filePath) files.add(filePath);
+    }
+    return files;
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Return an array of files that appear in postSnapshot but not preSnapshot,
+ * or whose presence changed between the two snapshots.
+ *
+ * @param {Set<string>} preSnapshot
+ * @param {Set<string>} postSnapshot
+ * @returns {Array<string>}
+ */
+function _diffSnapshots(preSnapshot, postSnapshot) {
+  const changed = [];
+  for (const file of postSnapshot) {
+    if (!preSnapshot.has(file)) {
+      changed.push(file);
+    }
+  }
+  // Also capture files that were in pre but are gone (e.g., deleted)
+  for (const file of preSnapshot) {
+    if (!postSnapshot.has(file)) {
+      changed.push(file);
+    }
+  }
+  return changed;
+}
+
+module.exports = {
+  invoke,
+  _spawnOpenCode,
+  _looksLikeCliHelp,
+  _extractToolUsage,
+  _gitSnapshot,
+  _diffSnapshots,
+};

package/lib/mini-ralph/prompt.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * prompt.js - Prompt loading and template rendering for mini-ralph.
+ *
+ * Supports three prompt sources:
+ *   1. Inline prompt text (options.promptText)
+ *   2. Prompt file (options.promptFile)
+ *   3. Prompt template file (options.promptTemplate) which wraps sources 1 or 2
+ *
+ * Template variables (mustache-style double-braces):
+ *   {{iteration}}          - Current iteration number
+ *   {{max_iterations}}     - Configured max iterations
+ *   {{change_dir}}         - Change directory path (from options.changeDir)
+ *   {{tasks}}              - Raw tasks file content
+ *   {{task_context}}       - Fresh current-task and completed-task summary
+ *   {{task_promise}}       - Configured task promise string
+ *   {{completion_promise}} - Configured completion promise string
+ *   {{context}}            - Pending context (passed in, already consumed)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const tasks = require('./tasks');
+
+/**
+ * Load the base prompt text from the configured source.
+ * Throws a clear error if the prompt file is missing or empty.
+ *
+ * @param {object} options
+ * @returns {string}
+ */
+function loadBase(options) {
+  if (options.promptText) {
+    if (!options.promptText.trim()) {
+      throw new Error('mini-ralph prompt: promptText is empty');
+    }
+    return options.promptText;
+  }
+
+  if (options.promptFile) {
+    if (!fs.existsSync(options.promptFile)) {
+      throw new Error(`mini-ralph prompt: prompt file not found: ${options.promptFile}`);
+    }
+    const text = fs.readFileSync(options.promptFile, 'utf8');
+    if (!text.trim()) {
+      throw new Error(`mini-ralph prompt: prompt file is empty: ${options.promptFile}`);
+    }
+    return text;
+  }
+
+  throw new Error('mini-ralph prompt: no prompt source configured');
+}
+
+/**
+ * Render the prompt for a given iteration.
+ * If a promptTemplate is specified, renders the template with iteration variables.
+ * Otherwise returns the base prompt as-is.
+ *
+ * @param {object}  options
+ * @param {number}  iteration  - Current 1-based iteration number
+ * @returns {string}
+ */
+function render(options, iteration) {
+  const base = loadBase(options);
+
+  if (!options.promptTemplate) {
+    return base;
+  }
+
+  const templatePath = options.promptTemplate;
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`mini-ralph prompt: template file not found: ${templatePath}`);
+  }
+
+  const template = fs.readFileSync(templatePath, 'utf8');
+  if (!template.trim()) {
+    throw new Error(`mini-ralph prompt: template file is empty: ${templatePath}`);
+  }
+
+  // Load tasks content if a tasksFile is configured
+  let tasksContent = '';
+  if (options.tasksFile && fs.existsSync(options.tasksFile)) {
+    tasksContent = fs.readFileSync(options.tasksFile, 'utf8');
+  }
+
+  const taskContext = options.tasksFile ? tasks.taskContext(options.tasksFile) : '';
+
+  const vars = {
+    iteration: String(iteration),
+    max_iterations: String(options.maxIterations || 50),
+    change_dir: options.changeDir || '',
+    tasks: tasksContent,
+    task_context: taskContext,
+    task_promise: options.taskPromise || 'READY_FOR_NEXT_TASK',
+    completion_promise: options.completionPromise || 'COMPLETE',
+    context: '',  // Pending context is injected by runner after rendering
+  };
+
+  return _renderTemplate(template, vars);
+}
+
+/**
+ * Replace all {{key}} occurrences in a template string with the provided values.
+ *
+ * @param {string} template
+ * @param {object} vars  - Map of variable name -> value
+ * @returns {string}
+ */
+function _renderTemplate(template, vars) {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    return Object.prototype.hasOwnProperty.call(vars, key) ? vars[key] : match;
+  });
+}
+
+module.exports = { loadBase, render, _renderTemplate };