spec-and-loop 2.0.1 → 2.1.0

package/lib/mini-ralph/errors.js

@@ -10,11 +10,7 @@ function errorsPath(ralphDir) {
 }
 
 function read(ralphDir, limit) {
-  const file = errorsPath(ralphDir);
-  if (!fs.existsSync(file)) return '';
-  const content = fs.readFileSync(file, 'utf8').trim();
-  if (!content) return '';
-  const entries = content.split(/^---$/m).filter(e => e.trim());
+  const entries = _readRawEntries(ralphDir);
   if (!entries.length) return '';
   if (limit !== undefined && limit < entries.length) {
     return entries.slice(-limit).join('\n---\n');
@@ -22,6 +18,23 @@ function read(ralphDir, limit) {
   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);
@@ -67,4 +80,33 @@ function _ensureDir(ralphDir) {
   }
 }
 
-module.exports = { errorsPath, read, append, clear, archive };
+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/invoker.js

@@ -127,13 +127,30 @@ function _spawnOpenCode(args, verbose) {
 function _looksLikeCliHelp(text) {
   if (!text) return false;
 
-  const hasHelpSections = text.includes('Commands:') && text.includes('Options:');
-  const hasOpenCodeUsage =
-    text.includes('opencode [project]') ||
-    text.includes('opencode run [message..]') ||
-    text.includes('run opencode with a message');
-
-  return hasHelpSections && hasOpenCodeUsage;
+  // 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;
 }
 
 /**

package/lib/mini-ralph/runner.js

@@ -94,8 +94,8 @@ async function run(opts) {
 
     // Build the prompt for this iteration
     const renderedPrompt = await prompt.render(options, iterationCount);
-    const errorContent = errors.read(ralphDir, 3);
-    const iterationFeedback = _buildIterationFeedback(history.recent(ralphDir, 3), errorContent);
+    const errorEntries = errors.readEntries(ralphDir, 3);
+    const iterationFeedback = _buildIterationFeedback(history.recent(ralphDir, 3), errorEntries);
 
     // Inject any pending context
     const pendingContext = context.consume(ralphDir);
@@ -187,17 +187,16 @@ async function run(opts) {
     }
   }
 
-  if (completed) {
-    const archivePath = errors.archive(ralphDir);
-    if (archivePath && options.verbose) {
-      process.stderr.write(`[mini-ralph] errors archived to ${archivePath}\n`);
+  try {
+    if (completed) {
+      _cleanupCompletedErrors(ralphDir, options.verbose);
     }
-    errors.clear(ralphDir);
+  } finally {
+    // A completed loop must not remain marked active because post-completion
+    // cleanup failed.
+    state.update(ralphDir, { active: false, completedAt: new Date().toISOString() });
   }
 
-  // Mark loop as inactive
-  state.update(ralphDir, { active: false, completedAt: new Date().toISOString() });
-
   return { completed, iterations: iterationCount, exitReason };
 }
 
@@ -342,7 +341,7 @@ function _formatAutoCommitMessage(iteration, completedTasks) {
  * @param {Array<object>} recentHistory
  * @returns {string}
  */
-function _buildIterationFeedback(recentHistory, errorContent) {
+function _buildIterationFeedback(recentHistory, errorEntries) {
   if (!Array.isArray(recentHistory) || recentHistory.length === 0) {
     return '';
   }
@@ -367,8 +366,8 @@ function _buildIterationFeedback(recentHistory, errorContent) {
     if (issues.length > 0) {
       let line = `- Iteration ${entry.iteration}: ${issues.join('; ')}.`;
 
-      if (entry.exitCode !== 0 && errorContent) {
-        const errorDetails = _extractErrorForIteration(errorContent, entry.iteration);
+      if (entry.exitCode !== 0 && errorEntries) {
+        const errorDetails = _extractErrorForIteration(errorEntries, entry.iteration);
         if (errorDetails) {
           line += '\n  Error output:';
           if (errorDetails.stderr) {
@@ -394,30 +393,19 @@ function _buildIterationFeedback(recentHistory, errorContent) {
   ].join('\n');
 }
 
-function _extractErrorForIteration(errorContent, iteration) {
-  if (!errorContent) return null;
-
-  const entries = errorContent.split(/^---$/m).filter((e) => e.trim());
-
-  for (const entry of entries) {
-    if (!entry.includes(`Iteration: ${iteration}`)) continue;
+function _extractErrorForIteration(errorEntries, iteration) {
+  if (!Array.isArray(errorEntries) || errorEntries.length === 0) return null;
 
-    let stderr = '';
-    let stdout = '';
+  const match = errorEntries.find((entry) => entry.iteration === iteration);
+  if (!match) return null;
 
-    const stderrMatch = entry.match(/### stderr\n([\s\S]*?)(?=\n### stdout|$)/);
-    const stdoutMatch = entry.match(/### stdout\n([\s\S]*?)$/);
+  let stderr = match.stderr || '';
+  let stdout = match.stdout || '';
 
-    if (stderrMatch) stderr = stderrMatch[1].trim();
-    if (stdoutMatch) stdout = stdoutMatch[1].trim();
+  if (stderr.length > 2000) stderr = stderr.substring(0, 2000) + '...';
+  if (stdout.length > 500) stdout = stdout.substring(0, 500) + '...';
 
-    if (stderr.length > 2000) stderr = stderr.substring(0, 2000) + '...';
-    if (stdout.length > 500) stdout = stdout.substring(0, 500) + '...';
-
-    return { stderr, stdout };
-  }
-
-  return null;
+  return { stderr, stdout };
 }
 
 function _getCurrentTaskDescription(tasksBefore) {
@@ -427,6 +415,26 @@ function _getCurrentTaskDescription(tasksBefore) {
   return 'N/A';
 }
 
+function _cleanupCompletedErrors(ralphDir, verbose) {
+  let archivePath = null;
+
+  try {
+    archivePath = errors.archive(ralphDir);
+    if (archivePath && verbose) {
+      process.stderr.write(`[mini-ralph] errors archived to ${archivePath}\n`);
+    }
+  } catch (err) {
+    process.stderr.write(`[mini-ralph] warning: failed to archive error history: ${err.message}\n`);
+    return;
+  }
+
+  try {
+    errors.clear(ralphDir);
+  } catch (err) {
+    process.stderr.write(`[mini-ralph] warning: failed to clear active error history: ${err.message}\n`);
+  }
+}
+
 function _taskIdentity(task) {
   return task.number
     ? `${task.number}|${task.fullDescription || task.description}`
@@ -483,4 +491,5 @@ module.exports = {
   _buildIterationFeedback,
   _extractErrorForIteration,
   _getCurrentTaskDescription,
+  _cleanupCompletedErrors,
 };

package/lib/mini-ralph/status.js

@@ -101,14 +101,13 @@ function render(ralphDir, tasksFile) {
   }
 
   // Error history
-  const errorContent = errors.read(ralphDir, 3);
-  if (errorContent) {
-    const entries = errorContent.split(/^---$/m).filter(e => e.trim());
-    const count = entries.length;
-    const preview = entries[entries.length - 1].substring(0, 200).trim();
+  const errorCount = errors.count(ralphDir);
+  if (errorCount > 0) {
+    const latestError = errors.latest(ralphDir);
+    const preview = _formatErrorPreview(latestError);
     lines.push('');
     lines.push('--- Error History ---');
-    lines.push(`  Errors: ${count}`);
+    lines.push(`  Errors: ${errorCount}`);
     lines.push(`  Most recent: ${preview}`);
     lines.push('-'.repeat(50));
   }
@@ -222,4 +221,18 @@ function _detectStruggles(recentHistory) {
   return warnings;
 }
 
-module.exports = { render, _elapsed, _detectStruggles, _formatToolUsage };
+function _formatErrorPreview(entry) {
+  if (!entry) return '';
+
+  const source = entry.stderr || entry.stdout || _fallbackErrorPreview(entry);
+  return source.substring(0, 200).trim();
+}
+
+function _fallbackErrorPreview(entry) {
+  const parts = [];
+  if (entry.task) parts.push(entry.task);
+  if (!Number.isNaN(entry.exitCode)) parts.push(`exit code ${entry.exitCode}`);
+  return parts.join(' | ');
+}
+
+module.exports = { render, _elapsed, _detectStruggles, _formatToolUsage, _formatErrorPreview };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-and-loop",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "OpenSpec + Ralph Loop integration for iterative development with opencode",
   "main": "index.js",
   "bin": {