spec-and-loop 1.0.8 → 2.0.0-rc.1

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,91 @@
+'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 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,
+  _tasks: tasks,
+  _prompt: prompt,
+  _runner: runner,
+  _status: status,
+};

package/lib/mini-ralph/invoker.js

@@ -0,0 +1,205 @@
+'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');
+const path = require('path');
+
+/**
+ * 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   - .ralph/ directory (used for temp prompt file)
+ * @returns {Promise<{stdout: string, exitCode: number, toolUsage: Array, filesChanged: Array}>}
+ */
+async function invoke(opts) {
+  const {
+    prompt,
+    model,
+    noCommit = false,
+    verbose = false,
+    ralphDir,
+  } = opts;
+
+  // Write the prompt to a temp file to avoid shell escaping issues
+  const fs = require('fs');
+  const os = require('os');
+  const tmpPromptFile = path.join(
+    os.tmpdir(),
+    `ralph-prompt-${Date.now()}-${process.pid}.md`
+  );
+
+  try {
+    fs.writeFileSync(tmpPromptFile, prompt, 'utf8');
+
+    const args = ['--print', tmpPromptFile];
+    if (model) {
+      args.push('--model', model);
+    }
+
+    if (verbose) {
+      process.stderr.write(`[mini-ralph] invoking: opencode ${args.join(' ')}\n`);
+    }
+
+    // Snapshot git-tracked files before invocation for file-change detection
+    const preSnapshot = _gitSnapshot();
+
+    const result = await _spawnOpenCode(args, verbose);
+
+    // Detect which files changed during this iteration
+    const postSnapshot = _gitSnapshot();
+    const filesChanged = _diffSnapshots(preSnapshot, postSnapshot);
+
+    return {
+      stdout: result.stdout,
+      exitCode: result.exitCode,
+      toolUsage: _extractToolUsage(result.stdout),
+      filesChanged,
+    };
+  } finally {
+    // Clean up temp prompt file
+    try {
+      fs.unlinkSync(tmpPromptFile);
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * 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 });
+    });
+  });
+}
+
+/**
+ * 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, _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 };