dev-harness-cli 1.0.0

package/cli/lib/progress.mjs

@@ -0,0 +1,357 @@
+/**
+ * progress — Dual-structure progress.md reader/writer.
+ *
+ * Manages the Session State (overwritten) and Lessons Learned (appended)
+ * sections of progress.md.
+ *
+ * Usage:
+ *   import { readProgress, writeSessionState, appendLesson } from './progress.mjs';
+ *   const { session, lessons } = readProgress('/path/to/project');
+ *   writeSessionState('/path/to/project', { phase: 'build', nextAction: 'fix tests' });
+ *   appendLesson('/path/to/project', 'Found gotcha in X middleware', 'agent');
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { PROGRESS_PATH } from './paths.mjs';
+import { loadConfig } from './state.mjs';
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const SESSION_HEADER = '## Session State';
+const LESSONS_HEADER = '## Lessons';
+
+const DEFAULT_SESSION_FIELDS = {
+  'Current Phase': 'not started',
+  'Current Feature': '—',
+  'Gate Status': 'pending',
+  'Next Action': '—',
+  'Retry Count': '0/3',
+};
+
+const FIELD_ORDER = [
+  'Current Phase',
+  'Current Feature',
+  'Gate Status',
+  'Next Action',
+  'Retry Count',
+];
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Get the path to progress.md for a given project directory.
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function getProgressPath(targetDir) {
+  return PROGRESS_PATH(targetDir);
+}
+
+/**
+ * Format a date as YYYY-MM-DD.
+ * @param {Date} [date]
+ * @returns {string}
+ */
+function fmtDate(date) {
+  const d = date || new Date();
+  return d.toISOString().slice(0, 10);
+}
+
+// ── Read ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse session state lines into a record.
+ * @param {string[]} lines
+ * @returns {Record<string, string>}
+ */
+function parseSessionLines(lines) {
+  const session = {};
+  for (const line of lines) {
+    const match = line.match(/^(\w[\w ]+):\s*(.*)/);
+    if (match) {
+      session[match[1].trim()] = match[2].trim();
+    }
+  }
+  return session;
+}
+
+/**
+ * Read progress.md and return parsed session state + lessons.
+ *
+ * Returns empty/fallback values when file is missing or malformed
+ * (never throws — always returns structured result).
+ *
+ * @param {string} targetDir
+ * @returns {{ session: Record<string,string>, lessons: Array<{date:string,author:string,text:string}>, ok: boolean, path: string }}
+ */
+export function readProgress(targetDir) {
+  const progPath = getProgressPath(targetDir);
+  const fallback = {
+    session: { ...DEFAULT_SESSION_FIELDS },
+    lessons: [],
+    ok: false,
+    path: progPath,
+  };
+
+  if (!existsSync(progPath)) {
+    return fallback;
+  }
+
+  let content;
+  try {
+    content = readFileSync(progPath, 'utf-8');
+  } catch {
+    return fallback;
+  }
+
+  const lines = content.split('\n');
+
+  // Find section boundaries
+  let sessionStart = -1;
+  let sessionEnd = -1;
+  let lessonsStart = -1;
+  let lessonsEnd = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+
+    // Detect section headers
+    if (line === SESSION_HEADER) {
+      sessionStart = i;
+    }
+    if (line === LESSONS_HEADER) {
+      lessonsStart = i;
+    }
+    // Detect section boundaries (next ## header after a section started)
+    if (sessionStart >= 0 && sessionEnd === -1 && line.startsWith('## ') && i > sessionStart) {
+      sessionEnd = i;
+    }
+    if (lessonsStart >= 0 && lessonsEnd === -1 && line.startsWith('## ') && i > lessonsStart) {
+      lessonsEnd = i;
+    }
+  }
+
+  if (sessionEnd === -1 && sessionStart >= 0) {
+    sessionEnd = lines.length;
+  }
+  if (lessonsEnd === -1 && lessonsStart >= 0) {
+    lessonsEnd = lines.length;
+  }
+
+  // Parse session state
+  const session = { ...DEFAULT_SESSION_FIELDS };
+  if (sessionStart >= 0) {
+    const sessionLines = lines.slice(sessionStart + 1, sessionEnd);
+    const parsed = parseSessionLines(sessionLines);
+    // Merge parsed over defaults (keep defaults for missing fields)
+    for (const key of FIELD_ORDER) {
+      if (parsed[key] !== undefined) {
+        session[key] = parsed[key];
+      }
+    }
+  }
+
+  // Parse lessons
+  const lessons = [];
+  const lessonRe = /^(\d{4}-\d{2}-\d{2})\s*\|\s*(.+?)\s*\|\s*(.+)/;
+  if (lessonsStart >= 0) {
+    const lessonLines = lines.slice(lessonsStart + 1, lessonsEnd);
+    for (const line of lessonLines) {
+      const m = line.match(lessonRe);
+      if (m) {
+        lessons.push({
+          date: m[1],
+          author: m[2].trim(),
+          text: m[3].trim(),
+        });
+      }
+    }
+  }
+
+  return { session, lessons, ok: true, path: progPath };
+}
+
+// ── Write session state ──────────────────────────────────────────────────────
+
+/**
+ * Overwrite the Session State section of progress.md.
+ *
+ * If the file doesn't exist, creates it with the minimal structure.
+ * If the ## Session State header doesn't exist, inserts it.
+ *
+ * @param {string} targetDir
+ * @param {Record<string,string>} fields — partial or full session state
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function writeSessionState(targetDir, fields) {
+  const progPath = getProgressPath(targetDir);
+
+  // Build the full session state block
+  const merged = { ...DEFAULT_SESSION_FIELDS, ...fields };
+  const stateBlockLines = [
+    SESSION_HEADER,
+    '',
+    ...FIELD_ORDER.map(k => `${k}: ${merged[k] ?? DEFAULT_SESSION_FIELDS[k]}`),
+    '',
+  ];
+
+  const stateBlock = stateBlockLines.join('\n') + '\n';
+
+  // Read existing content
+  let content;
+  if (existsSync(progPath)) {
+    try {
+      content = readFileSync(progPath, 'utf-8');
+    } catch {
+      content = '';
+    }
+  } else {
+    content = '';
+  }
+
+  const lines = content.split('\n');
+
+  // Find Session State section boundaries
+  let sessionIdx = -1;
+  let sessionEndIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line === SESSION_HEADER) {
+      sessionIdx = i;
+    } else if (sessionIdx >= 0 && sessionEndIdx === -1 && line.startsWith('## ') && i > sessionIdx) {
+      sessionEndIdx = i;
+      break;
+    }
+  }
+  if (sessionIdx >= 0 && sessionEndIdx === -1) {
+    sessionEndIdx = lines.length;
+  }
+
+  let newContent;
+  if (sessionIdx >= 0) {
+    // Replace existing session state section
+    const before = lines.slice(0, sessionIdx).join('\n');
+    const after = lines.slice(sessionEndIdx).join('\n');
+    newContent = (before ? before + '\n' : '') + stateBlock + (after ? after + '\n' : '');
+  } else {
+    // No session state section — prepend to file
+    if (lines.length > 0 && lines[0].trim() !== '') {
+      // File has content — insert after the title
+      newContent = content.replace(/\n## /, '\n' + stateBlock + '\n## ');
+      if (newContent === content) {
+        // Fallback: append
+        newContent = content + '\n' + stateBlock;
+      }
+    } else {
+      // Empty or nearly empty — start fresh
+      newContent = '# Progress\n\n' + stateBlock;
+    }
+  }
+
+  // Ensure trailing newline and write
+  try {
+    mkdirSync(dirname(progPath), { recursive: true });
+    writeFileSync(progPath, newContent.replace(/\n*$/, '\n'), 'utf-8');
+    return { ok: true, error: null };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+// ── Append lesson ────────────────────────────────────────────────────────────
+
+/**
+ * Append a lesson line to the Lessons section of progress.md.
+ *
+ * Creates ## Lessons section if it doesn't exist.
+ *
+ * @param {string} targetDir
+ * @param {string} text — lesson text
+ * @param {string} [author] — defaults to config.agentTool or 'agent'
+ * @param {Date} [date] — defaults to today
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function appendLesson(targetDir, text, author, date) {
+  const progPath = getProgressPath(targetDir);
+  // Resolve author: explicit param > config.agentTool > 'agent' (tool-agnostic default)
+  const resolvedAuthor = author || (() => {
+    try {
+      const { config, ok } = loadConfig(targetDir);
+      return ok && config.agentTool ? config.agentTool : 'agent';
+    } catch {
+      return 'agent';
+    }
+  })();
+  const lessonLine = `${fmtDate(date)} | ${resolvedAuthor} | ${text}`;
+
+  let content;
+  if (existsSync(progPath)) {
+    try {
+      content = readFileSync(progPath, 'utf-8');
+    } catch {
+      content = '';
+    }
+  } else {
+    content = '';
+  }
+
+  const lines = content.split('\n');
+
+  // Find Lessons section
+  let lessonsIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === LESSONS_HEADER) {
+      lessonsIdx = i;
+      break;
+    }
+  }
+
+  let newContent;
+  if (lessonsIdx >= 0) {
+    // Find where to insert — after the last lesson line or after the header
+    let insertAfter = lessonsIdx;
+    for (let i = lessonsIdx + 1; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (line === '' || line.match(/^(\d{4}-\d{2}-\d{2})\s*\|/)) {
+        insertAfter = i;
+      } else if (line.startsWith('## ')) {
+        break;
+      }
+    }
+    const before = lines.slice(0, insertAfter + 1).join('\n');
+    const after = lines.slice(insertAfter + 1).join('\n');
+    newContent = (before ? before + '\n' : '') + lessonLine + '\n' + (after ? after + '\n' : '');
+  } else {
+    // No Lessons section — append at end
+    newContent = content.replace(/\n*$/, '') + '\n\n' + LESSONS_HEADER + '\n\n' + lessonLine + '\n';
+  }
+
+  try {
+    mkdirSync(dirname(progPath), { recursive: true });
+    writeFileSync(progPath, newContent.replace(/\n*$/, '\n'), 'utf-8');
+    return { ok: true, error: null };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Convenience read of just the session state fields.
+ * Returns defaults for any field not found in the file.
+ * @param {string} targetDir
+ * @returns {Record<string,string>}
+ */
+export function readSessionState(targetDir) {
+  const { session } = readProgress(targetDir);
+  return session;
+}
+
+/**
+ * Convenience read of just the lessons list.
+ * @param {string} targetDir
+ * @returns {Array<{date:string,author:string,text:string}>}
+ */
+export function readLessons(targetDir) {
+  const { lessons } = readProgress(targetDir);
+  return lessons;
+}

package/cli/lib/ralph-inner.mjs

@@ -0,0 +1,314 @@
+/**
+ * ralph-inner — Inner Ralph Loop Engine.
+ *
+ * Runs the work → validate → pass/retry loop for every phase.
+ * Two modes:
+ *   - Feature-iterate (BUILD, VERIFY, SIMPLIFY): iterates features/tasks
+ *   - Deliverable-retry (INIT, DEFINE, PLAN, REVIEW, SHIP): retries same deliverable
+ *
+ * The engine prints instructions for the agent. It does NOT do the work itself.
+ *
+ * Usage:
+ *   import { runPhase } from './ralph-inner.mjs';
+ *   const result = runPhase('/path/to/project', 'build');
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { loadConfig } from './state.mjs';
+import { validateAgainstSchema } from './validate-schema.mjs';
+import { gitHardResetClean } from './git.mjs';
+import { phaseLabel } from './command-helpers.mjs';
+import { FEATURE_LIST_SCHEMA_PATH, FEATURE_LIST_PATH } from './paths.mjs';
+import { buildFeatureIterateOutput, buildDeliverableRetryOutput } from './ralph-output.mjs';
+import { DEFAULT_MAX_RETRIES } from './constants.mjs';
+
+// ── Phase type classification ────────────────────────────────────────────────
+
+/** Phases that iterate features (each feature has tasks). */
+const FEATURE_ITERATE = new Set(['build', 'verify', 'simplify']);
+
+/** Phases that produce a single deliverable and retry it on failure. */
+const DELIVERABLE_RETRY = new Set(['init', 'define', 'plan', 'review', 'ship']);
+
+/**
+ * Determine the loop mode for a given phase.
+ * @param {string} phase
+ * @returns {'feature-iterate'|'deliverable-retry'|null}
+ */
+export function getPhaseType(phase) {
+  if (FEATURE_ITERATE.has(phase)) {return 'feature-iterate';}
+  if (DELIVERABLE_RETRY.has(phase)) {return 'deliverable-retry';}
+  return null;
+}
+
+// ── Feature list I/O ─────────────────────────────────────────────────────────
+
+/**
+ * Get path to feature_list.json.
+ * @param {string} targetDir
+ * @returns {string}
+ */
+function getFeatureListPath(targetDir) {
+  return FEATURE_LIST_PATH(targetDir);
+}
+
+/**
+ * Default feature list (empty, one placeholder feature).
+ * @returns {object}
+ */
+function getDefaultFeatureList() {
+  return {
+    version: '0.1',
+    features: [
+      {
+        id: 'feature-001',
+        name: 'Feature 1',
+        description: 'Replace with actual feature description',
+        passes: false,
+        tasks: [
+          { id: 'task-001', description: 'First task', status: 'pending' },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * Load feature_list.json. Returns defaults if missing/invalid.
+ * @param {string} targetDir
+ * @returns {{ features: Array, ok: boolean, path: string }}
+ */
+export function loadFeatureList(targetDir) {
+  const flPath = getFeatureListPath(targetDir);
+  if (!existsSync(flPath)) {
+    return { ...getDefaultFeatureList(), ok: false, path: flPath };
+  }
+  try {
+    const raw = readFileSync(flPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    const result = { version: parsed.version || '0.1', features: parsed.features || [], ok: true, path: flPath };
+    // Schema validation — non-blocking: return errors in result. Library does
+    // NOT write to stderr (keeps error contract clean for --json consumers).
+    const schemaResult = validateAgainstSchema(parsed, FEATURE_LIST_SCHEMA_PATH);
+    result.schemaErrors = schemaResult.ok ? [] : schemaResult.errors;
+    return result;
+  } catch {
+    return { ...getDefaultFeatureList(), ok: false, path: flPath };
+  }
+}
+
+/**
+ * Save feature_list.json.
+ * @param {string} targetDir
+ * @param {object} data
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function saveFeatureList(targetDir, data) {
+  try {
+    const flPath = getFeatureListPath(targetDir);
+    mkdirSync(dirname(flPath), { recursive: true });
+    writeFileSync(flPath, JSON.stringify({ version: '0.1', features: data.features }, null, 2) + '\n', 'utf-8');
+    return { ok: true, error: null };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Find the next incomplete feature (passes=false).
+ * @param {Array} features
+ * @returns {object|null}
+ */
+export function getNextFeature(features) {
+  return features.find(f => !f.passes) || null;
+}
+
+/**
+ * Find the next uncompleted task in a feature.
+ * @param {object} feature
+ * @returns {object|null}
+ */
+export function getNextTask(feature) {
+  if (!feature.tasks) {return null;}
+  return feature.tasks.find(t => t.status === 'pending' || t.status === 'in_progress') || null;
+}
+
+// ── Inner loop ───────────────────────────────────────────────────────────────
+
+/**
+ * Run the inner Ralph loop for a phase.
+ *
+ * This function prints instructions and returns a result object.
+ * It does NOT modify files — the agent reads the instructions and does the work.
+ *
+ * @param {string} targetDir
+ * @param {string} phase
+ * @param {object} [options]
+ * @param {boolean} [options.json] — JSON output mode
+ * @param {boolean} [options.gitOps] — opt-in: execute git reset/clean on retry (default off)
+ * @returns {{ ok: boolean, status: string, message: string, phase: string, iteration: number, mode: string, details: object }}
+ */
+export function runPhase(targetDir, phase, options = {}) {
+  const { json = false, gitOps = false } = options;
+
+  // Load config
+  const { config, ok: configOk } = loadConfig(targetDir);
+  if (!configOk) {
+    return { ok: false, status: 'error', message: 'Cannot load config', phase, iteration: 0, mode: 'unknown', details: {} };
+  }
+
+  const mode = config.mode ?? 'copilot';
+  const maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const resetOnRetry = config.git?.resetOnRetry === true;
+  const autoCommit = config.git?.autoCommit === true;
+  const phaseType = getPhaseType(phase);
+
+  if (!phaseType) {
+    return { ok: false, status: 'error', message: `Unknown phase type for "${phase}"`, phase, iteration: 0, mode, details: {} };
+  }
+
+  // Retry count check: escalate if retries exhausted
+  const retryCount = config.retryCount ?? 0;
+  if (retryCount >= maxRetries) {
+    return {
+      ok: false,
+      status: 'escalated',
+      message: `Retries exhausted (${retryCount}/${maxRetries}) for phase "${phase}". Escalating to human.`,
+      phase,
+      iteration: retryCount,
+      mode,
+      details: { retryCount, maxRetries },
+    };
+  }
+
+  // ── Opt-in git ops: fresh context on retry ──────────────────────────────
+  // When --git-ops is passed AND this is a retry (retryCount > 0), execute a
+  // hard reset to the last commit + clean untracked files. This gives the
+  // "fresh context" Ralph requires without forcing it on agent-agnostic users.
+  let gitResetPerformed = false;
+  if (gitOps && retryCount > 0) {
+    const resetResult = gitHardResetClean(targetDir);
+    if (resetResult.ok) {
+      gitResetPerformed = true;
+      if (!json) {
+        process.stdout.write(`  ↻ Git reset performed (retry ${retryCount}): fresh context restored.\n`);
+      }
+    } else {
+      // Non-fatal: if git ops fail (e.g. not a repo), continue with instructions.
+      process.stderr.write(`Warning: --git-ops reset failed: ${resetResult.error}\n`);
+    }
+  }
+
+  // ── Feature-iterate mode (BUILD, VERIFY, SIMPLIFY) ────────────────────────
+
+  if (phaseType === 'feature-iterate') {
+    const fl = loadFeatureList(targetDir);
+    const feature = getNextFeature(fl.features);
+    const featuresTotal = fl.features.length;
+    const featuresDone = fl.features.filter(f => f.passes).length;
+
+    if (!feature) {
+      // All features pass — phase gate passes
+      return {
+        ok: true,
+        status: 'complete',
+        message: `All ${featuresTotal} feature(s) pass. Phase gate passes.`,
+        phase,
+        iteration: 0,
+        mode,
+        details: { featuresTotal, featuresDone, currentFeature: null, currentTask: null },
+      };
+    }
+
+    const task = getNextTask(feature);
+    if (!task) {
+      // Feature has all tasks complete but passes=false → mark it passing
+      feature.passes = true;
+      saveFeatureList(targetDir, fl);
+      return runPhase(targetDir, phase, options); // Recurse to get next feature
+    }
+
+    const output = buildFeatureIterateOutput(phase, feature, task, mode, maxRetries, resetOnRetry, autoCommit);
+
+    if (json) {
+      return {
+        ok: true,
+        status: 'instruction',
+        message: `${phaseLabel(phase)} — Feature: ${feature.name} — Task: ${task.description}`,
+        phase,
+        iteration: 1,
+        mode,
+        details: {
+          featuresTotal,
+          featuresDone,
+          featureId: feature.id,
+          featureName: feature.name,
+          taskId: task.id,
+          taskDescription: task.description,
+          phaseType,
+          maxRetries,
+          resetOnRetry,
+          autoCommit,
+          gitOps,
+          gitResetPerformed,
+          instructions: output,
+        },
+      };
+    }
+
+    // Human output
+    process.stdout.write(output);
+    process.stdout.write(`\n═══════════════════════════════════════\n`);
+    process.stdout.write(`Run: harness-dev validate --feature ${feature.id} --task ${task.id}\n`);
+    process.stdout.write(`═══════════════════════════════════════\n`);
+
+    return {
+      ok: true,
+      status: 'instruction',
+      message: `Working on: ${feature.name} — ${task.description}`,
+      phase,
+      iteration: 1,
+      mode,
+      details: { featureId: feature.id, taskId: task.id },
+    };
+  }
+
+  // ── Deliverable-retry mode (INIT, DEFINE, PLAN, REVIEW, SHIP) ────────────
+
+  const output = buildDeliverableRetryOutput(phase, mode, maxRetries, resetOnRetry, autoCommit);
+
+  if (json) {
+    return {
+      ok: true,
+      status: 'instruction',
+      message: `${phaseLabel(phase)}: produce the deliverable`,
+      phase,
+      iteration: 1,
+      mode,
+      details: {
+        phaseType,
+        maxRetries,
+        resetOnRetry,
+        autoCommit,
+        instructions: output,
+      },
+    };
+  }
+
+  // Human output
+  process.stdout.write(output);
+  process.stdout.write(`\n═══════════════════════════════════════\n`);
+  process.stdout.write(`Run: harness-dev validate\n`);
+  process.stdout.write(`═══════════════════════════════════════\n`);
+
+  return {
+    ok: true,
+    status: 'instruction',
+    message: `${phaseLabel(phase)}: produce the deliverable`,
+    phase,
+    iteration: 1,
+    mode,
+    details: {},
+  };
+}
+