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

package/lib/mini-ralph/status.js

@@ -0,0 +1,211 @@
+'use strict';
+
+/**
+ * status.js - Status dashboard renderer for mini-ralph.
+ *
+ * Reads the current loop state, history, context, and tasks to produce
+ * a human-readable status report. Also surfaces struggle indicators when
+ * the loop appears stuck (no-progress or repeated errors).
+ */
+
+const state = require('./state');
+const history = require('./history');
+const context = require('./context');
+const tasks = require('./tasks');
+
+/**
+ * Render a status dashboard string for the given .ralph/ directory.
+ *
+ * @param {string} ralphDir
+ * @param {string} [tasksFile]  - Optional path to the tasks.md file for task progress
+ * @returns {string}
+ */
+function render(ralphDir, tasksFile) {
+  const lines = [];
+
+  const loopState = state.read(ralphDir);
+  if (!loopState) {
+    lines.push('No active or recent loop state found.');
+    lines.push(`(Looking in: ${ralphDir})`);
+    return lines.join('\n');
+  }
+
+  // Header
+  lines.push('=== mini-ralph status ===');
+  lines.push('');
+
+  // Loop state
+  const active = loopState.active ? 'ACTIVE' : 'INACTIVE';
+  lines.push(`Status:        ${active}`);
+  lines.push(`Iteration:     ${loopState.iteration || '?'} / ${loopState.maxIterations || '?'}`);
+
+  if (loopState.startedAt) {
+    const elapsed = _elapsed(loopState.startedAt);
+    lines.push(`Started:       ${loopState.startedAt}  (${elapsed} ago)`);
+  }
+
+  if (loopState.completedAt) {
+    lines.push(`Completed:     ${loopState.completedAt}`);
+  }
+
+  lines.push(`Tasks mode:    ${loopState.tasksMode ? 'yes' : 'no'}`);
+  lines.push(`Completion:    <promise>${loopState.completionPromise || 'COMPLETE'}</promise>`);
+  lines.push(`Task promise:  <promise>${loopState.taskPromise || 'READY_FOR_NEXT_TASK'}</promise>`);
+
+  // Prompt summary
+  const promptSummary = _promptSummary(loopState);
+  if (promptSummary) {
+    lines.push('');
+    lines.push(`Prompt:        ${promptSummary}`);
+  }
+
+  // Pending context
+  const pendingCtx = context.read(ralphDir);
+  if (pendingCtx) {
+    lines.push('');
+    lines.push('--- Pending Context (injected next iteration) ---');
+    lines.push(pendingCtx.substring(0, 500) + (pendingCtx.length > 500 ? '\n...(truncated)' : ''));
+    lines.push('-'.repeat(50));
+  }
+
+  // Task progress
+  const resolvedTasksFile = tasksFile || _findTasksFile(loopState);
+  if (resolvedTasksFile) {
+    try {
+      const counts = tasks.countTasks(resolvedTasksFile);
+      lines.push('');
+      lines.push(`Tasks:         ${counts.completed} completed, ${counts.inProgress} in-progress, ${counts.incomplete} incomplete (${counts.total} total)`);
+      const current = tasks.currentTask(resolvedTasksFile);
+      if (current) {
+        const num = current.number ? `${current.number} ` : '';
+        lines.push(`Current task:  ${num}${current.description}`);
+      }
+    } catch {
+      // tasks file unreadable - skip
+    }
+  }
+
+  // Recent history
+  const recentHistory = history.recent(ralphDir, 5);
+  if (recentHistory.length > 0) {
+    lines.push('');
+    lines.push('--- Recent History ---');
+    for (const entry of recentHistory) {
+      const durationSec = entry.duration ? `${(entry.duration / 1000).toFixed(1)}s` : '?';
+      const completed = entry.completionDetected ? ' [COMPLETE]' : (entry.taskDetected ? ' [TASK]' : '');
+      const toolSummary = _formatToolUsage(entry.toolUsage);
+      lines.push(`  Iteration ${entry.iteration}: ${durationSec}${completed}${toolSummary ? `  tools: ${toolSummary}` : ''}`);
+    }
+    lines.push('-'.repeat(50));
+  }
+
+  // Struggle indicators
+  const struggles = _detectStruggles(recentHistory);
+  if (struggles.length > 0) {
+    lines.push('');
+    lines.push('--- Struggle Indicators ---');
+    for (const s of struggles) {
+      lines.push(`  WARNING: ${s}`);
+    }
+    lines.push('Tip: Use `ralph-run --add-context "..."` to provide guidance for the next iteration.');
+    lines.push('-'.repeat(50));
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Format elapsed time from an ISO timestamp to a human-readable string.
+ *
+ * @param {string} isoString
+ * @returns {string}
+ */
+function _elapsed(isoString) {
+  const start = new Date(isoString);
+  const now = new Date();
+  const ms = now - start;
+  if (isNaN(ms) || ms < 0) return 'unknown';
+  const secs = Math.floor(ms / 1000);
+  if (secs < 60) return `${secs}s`;
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return `${mins}m ${secs % 60}s`;
+  const hours = Math.floor(mins / 60);
+  return `${hours}h ${mins % 60}m`;
+}
+
+/**
+ * Extract a brief prompt summary from loop state.
+ *
+ * @param {object} loopState
+ * @returns {string}
+ */
+function _promptSummary(loopState) {
+  if (loopState.promptFile) {
+    return `file: ${loopState.promptFile}`;
+  }
+  if (loopState.prompt) {
+    const firstLine = loopState.prompt.split('\n')[0].substring(0, 80);
+    return `"${firstLine}${firstLine.length >= 80 ? '...' : ''}"`;
+  }
+  return '';
+}
+
+/**
+ * Try to find a tasks file path from loop state.
+ *
+ * @param {object} loopState
+ * @returns {string|null}
+ */
+function _findTasksFile(loopState) {
+  if (loopState.tasksFile) return loopState.tasksFile;
+  return null;
+}
+
+/**
+ * Format tool usage array to a short string.
+ *
+ * @param {Array} toolUsage
+ * @returns {string}
+ */
+function _formatToolUsage(toolUsage) {
+  if (!Array.isArray(toolUsage) || toolUsage.length === 0) return '';
+  return toolUsage.map((t) => `${t.tool}(${t.count})`).join(', ');
+}
+
+/**
+ * Detect struggle indicators from recent history.
+ *
+ * @param {Array<object>} recentHistory
+ * @returns {Array<string>} Warning messages
+ */
+function _detectStruggles(recentHistory) {
+  const warnings = [];
+  if (recentHistory.length < 2) return warnings;
+
+  // No-progress: multiple iterations with no files changed
+  const noProgressCount = recentHistory.filter(
+    (e) => !e.filesChanged || e.filesChanged.length === 0
+  ).length;
+
+  if (noProgressCount >= 2 && noProgressCount === recentHistory.length) {
+    warnings.push(
+      `No file changes detected in the last ${noProgressCount} iterations. The loop may be stuck.`
+    );
+  }
+
+  // Repeated errors: multiple non-zero exit codes
+  const errorCount = recentHistory.filter((e) => e.exitCode !== 0).length;
+  if (errorCount >= 2) {
+    warnings.push(
+      `OpenCode exited with errors in ${errorCount} of the last ${recentHistory.length} iterations.`
+    );
+  }
+
+  return warnings;
+}
+
+module.exports = { render, _elapsed, _detectStruggles, _formatToolUsage };

package/lib/mini-ralph/tasks.js

@@ -0,0 +1,209 @@
+'use strict';
+
+/**
+ * tasks.js - Task file helpers for mini-ralph.
+ *
+ * Provides utilities to:
+ *   - Establish the .ralph/ralph-tasks.md symlink pointing to the OpenSpec tasks.md
+ *   - Parse tasks from a tasks.md file (incomplete, in-progress, completed)
+ *   - Compute a stable hash of the tasks file for change detection
+ *
+ * The OpenSpec tasks.md is always the source of truth. The symlink at
+ * .ralph/ralph-tasks.md exists only as a convenience reference for the loop
+ * engine; both paths resolve to the same inode.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const TASKS_LINK_NAME = 'ralph-tasks.md';
+
+/**
+ * Return the path to the managed tasks symlink inside ralphDir.
+ *
+ * @param {string} ralphDir
+ * @returns {string}
+ */
+function tasksLinkPath(ralphDir) {
+  return path.join(ralphDir, TASKS_LINK_NAME);
+}
+
+/**
+ * Create or update the .ralph/ralph-tasks.md symlink to point to tasksFile.
+ * Uses an absolute path for the symlink target so it is portable.
+ *
+ * @param {string} ralphDir   - Absolute path to .ralph/ directory
+ * @param {string} tasksFile  - Path to the OpenSpec tasks.md (absolute or resolvable)
+ */
+function syncLink(ralphDir, tasksFile) {
+  _ensureDir(ralphDir);
+
+  const absTasksFile = path.resolve(tasksFile);
+  const linkPath = tasksLinkPath(ralphDir);
+
+  if (!fs.existsSync(absTasksFile)) {
+    throw new Error(`mini-ralph tasks: tasks file not found: ${absTasksFile}`);
+  }
+
+  // Remove existing file or symlink if it already exists
+  if (fs.existsSync(linkPath) || _isSymlink(linkPath)) {
+    fs.unlinkSync(linkPath);
+  }
+
+  fs.symlinkSync(absTasksFile, linkPath);
+}
+
+/**
+ * Parse all tasks from a tasks.md file.
+ * Returns an array of task objects with: { number, description, status }
+ * where status is one of: 'incomplete', 'in_progress', 'completed'.
+ *
+ * Lines are matched by the checkbox prefix:
+ *   - [ ]  -> incomplete
+ *   - [/]  -> in_progress
+ *   - [x]  -> completed
+ *
+ * Task numbers are extracted from the description (e.g., "1.1 Some task").
+ *
+ * @param {string} tasksFile
+ * @returns {Array<{number: string, description: string, status: string, raw: string}>}
+ */
+function parseTasks(tasksFile) {
+  if (!fs.existsSync(tasksFile)) return [];
+
+  const lines = fs.readFileSync(tasksFile, 'utf8').split('\n');
+  const tasks = [];
+
+  for (const line of lines) {
+    const match = line.match(/^-\s+\[([ x/])\]\s+(.+)$/);
+    if (!match) continue;
+
+    const checkChar = match[1];
+    const description = match[2].trim();
+    let status;
+    if (checkChar === 'x') status = 'completed';
+    else if (checkChar === '/') status = 'in_progress';
+    else status = 'incomplete';
+
+    // Try to extract a leading task number like "1.1" or "4.2"
+    const numMatch = description.match(/^(\d+\.\d+)\s+(.+)$/);
+    const number = numMatch ? numMatch[1] : '';
+    const text = numMatch ? numMatch[2] : description;
+
+    tasks.push({ number, description: text, fullDescription: description, status, raw: line });
+  }
+
+  return tasks;
+}
+
+/**
+ * Return the first incomplete or in-progress task, or null if all are done.
+ *
+ * @param {string} tasksFile
+ * @returns {object|null}
+ */
+function currentTask(tasksFile) {
+  const all = parseTasks(tasksFile);
+  return (
+    all.find((t) => t.status === 'in_progress') ||
+    all.find((t) => t.status === 'incomplete') ||
+    null
+  );
+}
+
+/**
+ * Compute an MD5 hash of the tasks file content for change detection.
+ * Returns '0' if the file does not exist.
+ *
+ * @param {string} tasksFile
+ * @returns {string}
+ */
+function hashFile(tasksFile) {
+  if (!fs.existsSync(tasksFile)) return '0';
+  const content = fs.readFileSync(tasksFile);
+  return crypto.createHash('md5').update(content).digest('hex');
+}
+
+/**
+ * Count tasks by status.
+ *
+ * @param {string} tasksFile
+ * @returns {{ total: number, completed: number, inProgress: number, incomplete: number }}
+ */
+function countTasks(tasksFile) {
+  const all = parseTasks(tasksFile);
+  return {
+    total: all.length,
+    completed: all.filter((t) => t.status === 'completed').length,
+    inProgress: all.filter((t) => t.status === 'in_progress').length,
+    incomplete: all.filter((t) => t.status === 'incomplete').length,
+  };
+}
+
+/**
+ * Build a compact task-context block for the current tasks file.
+ * Mirrors the shell-side task context format so prompts can render a fresh
+ * snapshot on every iteration without regenerating the whole PRD.
+ *
+ * @param {string} tasksFile
+ * @returns {string}
+ */
+function taskContext(tasksFile) {
+  const all = parseTasks(tasksFile);
+  if (all.length === 0) return '';
+
+  const current =
+    all.find((task) => task.status === 'in_progress') ||
+    all.find((task) => task.status === 'incomplete') ||
+    null;
+  const completed = all.filter((task) => task.status === 'completed');
+
+  const sections = [];
+
+  if (current) {
+    sections.push('## Current Task');
+    sections.push(`- ${current.fullDescription || current.description}`);
+  }
+
+  if (completed.length > 0) {
+    if (sections.length > 0) {
+      sections.push('');
+    }
+    sections.push('## Completed Tasks for Git Commit');
+    sections.push(
+      ...completed.map((task) => `- [x] ${task.fullDescription || task.description}`)
+    );
+  }
+
+  return sections.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function _ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function _isSymlink(p) {
+  try {
+    fs.lstatSync(p);
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  syncLink,
+  parseTasks,
+  currentTask,
+  hashFile,
+  countTasks,
+  taskContext,
+  tasksLinkPath,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-and-loop",
-  "version": "1.0.8",
+  "version": "2.0.0-rc.1",
   "description": "OpenSpec + Ralph Loop integration for iterative development with opencode",
   "main": "index.js",
   "bin": {
@@ -17,8 +17,7 @@
     "lint": "shellcheck scripts/*.sh"
   },
   "dependencies": {
-    "@fission-ai/openspec": "1.2.0",
-    "@th0rgal/ralph-wiggum": "1.2.2"
+    "@fission-ai/openspec": "1.2.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",
@@ -49,7 +48,6 @@
   },
   "keywords": [
     "openspec",
-    "ralph-wiggum",
     "opencode",
     "iterative-development",
     "agentic-coding"
@@ -62,6 +60,7 @@
   },
   "files": [
     "bin/",
+    "lib/",
     "scripts/",
     "README.md",
     "QUICKSTART.md"

package/scripts/mini-ralph-cli.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * mini-ralph-cli.js - Private runner entrypoint for the internal mini Ralph loop engine.
+ *
+ * This script is invoked by scripts/ralph-run.sh after it prepares the OpenSpec
+ * artifacts. It is NOT a documented end-user interface. Users should use ralph-run.
+ *
+ * Usage (internal):
+ *   node scripts/mini-ralph-cli.js [options]
+ *
+ * Options:
+ *   --prompt-file <path>       Prompt file to use (required unless --prompt-text given)
+ *   --prompt-text <text>       Inline prompt text
+ *   --prompt-template <path>   Prompt template file
+ *   --ralph-dir <path>         .ralph/ directory (default: .ralph)
+ *   --tasks-file <path>        Path to tasks.md for tasks mode
+ *   --tasks                    Enable tasks mode
+ *   --min-iterations <n>       Minimum iterations (default: 1)
+ *   --max-iterations <n>       Maximum iterations (default: 50)
+ *   --completion-promise <s>   Completion promise string (default: COMPLETE)
+ *   --task-promise <s>         Task promise string (default: READY_FOR_NEXT_TASK)
+ *   --no-commit                Suppress auto-commit
+ *   --model <name>             Optional model override
+ *   --verbose                  Verbose output
+ *   --status                   Print status dashboard and exit
+ *   --add-context <text>       Add pending context and exit
+ *   --clear-context            Clear pending context and exit
+ *   --help                     Show this help
+ */
+
+const path = require('path');
+const miniRalph = require('../lib/mini-ralph/index');
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const opts = {
+    promptFile: null,
+    promptText: null,
+    promptTemplate: null,
+    ralphDir: '.ralph',
+    tasksFile: null,
+    tasksMode: false,
+    minIterations: 1,
+    maxIterations: 50,
+    completionPromise: 'COMPLETE',
+    taskPromise: 'READY_FOR_NEXT_TASK',
+    noCommit: false,
+    model: '',
+    verbose: false,
+    // Control commands
+    status: false,
+    addContext: null,
+    clearContext: false,
+    help: false,
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    switch (arg) {
+      case '--prompt-file':
+        opts.promptFile = args[++i];
+        break;
+      case '--prompt-text':
+        opts.promptText = args[++i];
+        break;
+      case '--prompt-template':
+        opts.promptTemplate = args[++i];
+        break;
+      case '--ralph-dir':
+        opts.ralphDir = args[++i];
+        break;
+      case '--tasks-file':
+        opts.tasksFile = args[++i];
+        break;
+      case '--tasks':
+        opts.tasksMode = true;
+        break;
+      case '--min-iterations':
+        opts.minIterations = parseInt(args[++i], 10);
+        break;
+      case '--max-iterations':
+        opts.maxIterations = parseInt(args[++i], 10);
+        break;
+      case '--completion-promise':
+        opts.completionPromise = args[++i];
+        break;
+      case '--task-promise':
+        opts.taskPromise = args[++i];
+        break;
+      case '--no-commit':
+        opts.noCommit = true;
+        break;
+      case '--model':
+        opts.model = args[++i];
+        break;
+      case '--verbose':
+        opts.verbose = true;
+        break;
+      case '--status':
+        opts.status = true;
+        break;
+      case '--add-context':
+        opts.addContext = args[++i];
+        break;
+      case '--clear-context':
+        opts.clearContext = true;
+        break;
+      case '--help':
+      case '-h':
+        opts.help = true;
+        break;
+      default:
+        process.stderr.write(`mini-ralph-cli: unknown option: ${arg}\n`);
+        process.exit(1);
+    }
+    i++;
+  }
+
+  return opts;
+}
+
+function printHelp() {
+  process.stdout.write(`
+mini-ralph-cli - Internal mini Ralph loop engine runner
+
+This is an internal script. Use ralph-run as the documented interface.
+
+Options:
+  --prompt-file <path>       Prompt file
+  --prompt-text <text>       Inline prompt text
+  --prompt-template <path>   Prompt template file
+  --ralph-dir <path>         .ralph/ directory (default: .ralph)
+  --tasks-file <path>        Path to tasks.md
+  --tasks                    Enable tasks mode
+  --min-iterations <n>       Minimum iterations (default: 1)
+  --max-iterations <n>       Maximum iterations (default: 50)
+  --completion-promise <s>   Completion promise string
+  --task-promise <s>         Task promise string
+  --no-commit                Suppress auto-commit
+  --model <name>             Model override
+  --verbose                  Verbose output
+  --status                   Print status dashboard and exit
+  --add-context <text>       Add pending context and exit
+  --clear-context            Clear pending context and exit
+  --help                     Show this help
+`.trim() + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const opts = parseArgs(process.argv);
+
+  if (opts.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const ralphDir = path.resolve(opts.ralphDir);
+
+  // Handle control commands (status, add-context, clear-context)
+  if (opts.status) {
+    const tasksFile = opts.tasksFile ? path.resolve(opts.tasksFile) : null;
+    const output = miniRalph.getStatus(ralphDir, tasksFile);
+    process.stdout.write(output + '\n');
+    process.exit(0);
+  }
+
+  if (opts.addContext !== null) {
+    miniRalph.addContext(ralphDir, opts.addContext);
+    process.stdout.write(`Context added to ${path.join(ralphDir, 'ralph-context.md')}\n`);
+    process.exit(0);
+  }
+
+  if (opts.clearContext) {
+    miniRalph.clearContext(ralphDir);
+    process.stdout.write('Pending context cleared.\n');
+    process.exit(0);
+  }
+
+  // Run the loop
+  const runOpts = {
+    promptFile: opts.promptFile ? path.resolve(opts.promptFile) : null,
+    promptText: opts.promptText || null,
+    promptTemplate: opts.promptTemplate ? path.resolve(opts.promptTemplate) : null,
+    ralphDir,
+    tasksFile: opts.tasksFile ? path.resolve(opts.tasksFile) : null,
+    tasksMode: opts.tasksMode,
+    minIterations: opts.minIterations,
+    maxIterations: opts.maxIterations,
+    completionPromise: opts.completionPromise,
+    taskPromise: opts.taskPromise,
+    noCommit: opts.noCommit,
+    model: opts.model,
+    verbose: opts.verbose,
+  };
+
+  try {
+    const result = await miniRalph.run(runOpts);
+
+    if (opts.verbose) {
+      process.stderr.write(
+        `[mini-ralph] loop finished: completed=${result.completed} iterations=${result.iterations} reason=${result.exitReason}\n`
+      );
+    }
+
+    process.exit(result.completed ? 0 : 1);
+  } catch (err) {
+    process.stderr.write(`[mini-ralph] error: ${err.message}\n`);
+    if (opts.verbose && err.stack) {
+      process.stderr.write(err.stack + '\n');
+    }
+    process.exit(1);
+  }
+}
+
+main();