ralphflow 0.3.0 → 0.4.0

package/README.md

@@ -11,26 +11,27 @@ Define pipelines as loops, coordinate parallel agents via file-based trackers, a
 ## Quick Start
 
 ```bash
-# 1. Make sure you have a CLAUDE.md in your project
-#    (or let Claude create one: claude "Initialize CLAUDE.md for this project")
+# In your project with a CLAUDE.md
+npx ralphflow
+```
 
-# 2. Initialize a flow
-npx ralphflow init --template code-implementation --name my-app
+The interactive menu lets you initialize apps, run individual loops, run all loops in sequence, launch the web dashboard, or check status — no flags needed.
 
-# 3. Run the story loop — describe what you want to build
-npx ralphflow run story
+### Advanced Usage
 
-# 4. Run the tasks loop — agents implement your stories
+```bash
+# Non-interactive commands (same as before)
+npx ralphflow init --template code-implementation --name my-app
+npx ralphflow run story
 npx ralphflow run tasks
-
-# 5. Run with multiple agents for parallel execution
-npx ralphflow run tasks --agents 3
-
-# 6. Deliver — review, get feedback, resolve
+npx ralphflow run tasks --multi-agent   # Multi-agent — one terminal per agent
 npx ralphflow run delivery
-
-# 7. Check progress anytime
 npx ralphflow status
+
+# Web dashboard
+npx ralphflow dashboard                 # Start dashboard at http://localhost:4242
+npx ralphflow run tasks --ui            # Run with live dashboard alongside
+npx ralphflow e2e --ui                  # E2E with live dashboard
 ```
 
 ## How It Works
@@ -41,9 +42,9 @@ The default `code-implementation` template ships with three loops:
 
 | Loop | Purpose | Mode |
 |------|---------|------|
-| **Story Loop** | Break features into stories and tasks | Interactive — Claude asks you questions |
-| **Tasks Loop** | Implement tasks, commit code, update CLAUDE.md | Single or multi-agent (autonomous) |
-| **Delivery Loop** | Review completed work, gather feedback | Interactive — Claude presents deliverables |
+| **Story Loop** | Break features into stories and tasks | Interactive Claude Code session |
+| **Tasks Loop** | Implement tasks, commit code, update CLAUDE.md | Single or multi-agent (`--multi-agent`) |
+| **Delivery Loop** | Review completed work, gather feedback | Interactive Claude Code session |
 
 ### Pipeline Flow
 
@@ -83,20 +84,61 @@ Requires `CLAUDE.md` to exist in your project root. If it doesn't, you'll be pro
 Runs a loop. Handles the iteration cycle — spawning Claude, detecting completion signals, and restarting on `kill -INT $PPID`.
 
 ```bash
-npx ralphflow run story                    # Run story loop
+npx ralphflow run story                    # Run story loop (interactive Claude session)
 npx ralphflow run tasks                    # Run tasks loop (single agent)
-npx ralphflow run tasks --agents 3         # Run with 3 parallel agents
+npx ralphflow run tasks --multi-agent      # Run as a multi-agent instance (auto-assigns agent ID)
 npx ralphflow run delivery                 # Run delivery loop
 npx ralphflow run story --flow my-app      # Specify which flow (when multiple exist)
 npx ralphflow run tasks --max-iterations 5 # Limit iterations
 ```
 
+Each `run` command opens a full interactive Claude Code session. Claude owns the terminal — you see everything it does in real time.
+
+**Multi-agent mode:** Instead of spawning N agents from one process, each terminal is one agent. Open multiple terminals, run `--multi-agent` in each, and they auto-assign sequential agent IDs (`agent-1`, `agent-2`, ...) via PID-based lock files. Stale agents are automatically cleaned up.
+
 **Options:**
-- `-a, --agents <n>` — Number of parallel agents (default: 1)
+- `--multi-agent` — Run as a multi-agent instance (auto-assigns agent ID)
+- `--ui` — Start the web dashboard alongside execution
 - `-m, --model <model>` — Claude model to use
 - `-n, --max-iterations <n>` — Maximum iterations (default: 30)
 - `-f, --flow <name>` — Which flow to run (auto-detected if only one exists)
 
+### `npx ralphflow dashboard`
+
+Starts a real-time web dashboard at `http://localhost:4242`. Shows all apps, loop pipelines, tracker status, and lets you edit prompt files — all updated live via WebSocket as agents work.
+
+```bash
+npx ralphflow dashboard              # Default port 4242
+npx ralphflow dashboard -p 3000      # Custom port
+npx ralphflow ui                     # Alias
+```
+
+**Features:**
+- Live pipeline view with color-coded status (complete/running/pending)
+- Per-loop detail: stage, active item, progress bar, agent table
+- Prompt editor with Cmd+S save and dirty indicator
+- Live tracker viewer (auto-updates as agents write)
+- WebSocket auto-reconnect with exponential backoff
+
+**Options:**
+- `-p, --port <port>` — Port number (default: 4242)
+
+### `npx ralphflow e2e`
+
+Runs all loops end-to-end with SQLite orchestration. Skips loops already completed.
+
+```bash
+npx ralphflow e2e                   # Run all loops
+npx ralphflow e2e --ui              # With live dashboard
+npx ralphflow e2e --flow my-app     # Specific flow
+```
+
+**Options:**
+- `--ui` — Start the web dashboard alongside execution
+- `-m, --model <model>` — Claude model to use
+- `-n, --max-iterations <n>` — Maximum iterations per loop (default: 30)
+- `-f, --flow <name>` — Which flow to run (auto-detected if only one exists)
+
 ### `npx ralphflow status`
 
 Shows the current state of all loops across all flows.
@@ -109,12 +151,10 @@ npx ralphflow status --flow my-app  # Specific flow
 ```
   RalphFlow — my-app
 
-  Loop           Stage              Active  Progress
-  Story Loop     analyze            none    0/0
-  Tasks Loop     —                  none    3/6
-    agent-1      understand-execute TASK-4  2026-03-08T10:00
-    agent-2      verify-document    TASK-5  2026-03-08T10:01
-  Delivery Loop  idle               none    0/0
+  Loop           Stage    Active  Progress
+  Story Loop     analyze  none    0/0
+  Tasks Loop     —        none    3/6
+  Delivery Loop  idle     none    0/0
 ```
 
 **Options:**
@@ -142,7 +182,7 @@ Story → Tasks → Delivery pipeline for code projects. Battle-tested across 28
 
 ### `research`
 
-Multi-loop research pipeline with discovery, research, story, evolution, issue, datapoints, and merge loops. Tested across 467 places and 94 roads in a Kashi/Varanasi research project.
+Discovery → Research → Story → Document pipeline for research projects. Four loops: discovery (decompose topics), research (investigate with multi-agent), story (synthesize narratives), and document (compile final output).
 
 ## Project Structure
 

package/dist/chunk-GVOJO5IN.js

@@ -0,0 +1,274 @@
+// src/core/config.ts
+import { readFileSync, existsSync, readdirSync } from "fs";
+import { join } from "path";
+import { parse as parseYaml } from "yaml";
+var LOOP_ALIASES = {
+  // code-implementation aliases
+  story: "story-loop",
+  stories: "story-loop",
+  tasks: "tasks-loop",
+  task: "tasks-loop",
+  delivery: "delivery-loop",
+  deliver: "delivery-loop",
+  // research aliases
+  discovery: "discovery-loop",
+  discover: "discovery-loop",
+  research: "research-loop",
+  document: "document-loop",
+  doc: "document-loop"
+};
+function listFlows(cwd) {
+  const baseDir = join(cwd, ".ralph-flow");
+  if (!existsSync(baseDir)) return [];
+  return readdirSync(baseDir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith(".")).filter((d) => existsSync(join(baseDir, d.name, "ralphflow.yaml"))).map((d) => d.name);
+}
+function resolveFlowDir(cwd, flowName) {
+  const baseDir = join(cwd, ".ralph-flow");
+  if (!existsSync(baseDir)) {
+    throw new Error("No .ralph-flow/ found. Run `npx ralphflow init` first.");
+  }
+  const flows = listFlows(cwd);
+  if (flows.length === 0) {
+    throw new Error("No flows found in .ralph-flow/. Run `npx ralphflow init` first.");
+  }
+  if (flowName) {
+    if (!flows.includes(flowName)) {
+      throw new Error(`Flow "${flowName}" not found. Available: ${flows.join(", ")}`);
+    }
+    return join(baseDir, flowName);
+  }
+  if (flows.length === 1) {
+    return join(baseDir, flows[0]);
+  }
+  throw new Error(
+    `Multiple flows found: ${flows.join(", ")}. Use --flow <name> to specify which one.`
+  );
+}
+function loadConfig(flowDir) {
+  const configPath = join(flowDir, "ralphflow.yaml");
+  if (!existsSync(configPath)) {
+    throw new Error(`No ralphflow.yaml found in ${flowDir}`);
+  }
+  const raw = readFileSync(configPath, "utf-8");
+  const config = parseYaml(raw);
+  if (!config.name) {
+    throw new Error('ralphflow.yaml: missing required field "name"');
+  }
+  if (!config.loops || Object.keys(config.loops).length === 0) {
+    throw new Error('ralphflow.yaml: missing required field "loops"');
+  }
+  if (!config.dir) {
+    config.dir = ".ralph-flow";
+  }
+  return config;
+}
+function resolveLoop(config, name) {
+  if (config.loops[name]) {
+    return { key: name, loop: config.loops[name] };
+  }
+  const aliased = LOOP_ALIASES[name.toLowerCase()];
+  if (aliased && config.loops[aliased]) {
+    return { key: aliased, loop: config.loops[aliased] };
+  }
+  for (const [key, loop] of Object.entries(config.loops)) {
+    if (key.startsWith(name) || loop.name.toLowerCase().includes(name.toLowerCase())) {
+      return { key, loop };
+    }
+  }
+  const available = Object.keys(config.loops).join(", ");
+  throw new Error(`Unknown loop "${name}". Available: ${available}`);
+}
+
+// src/core/db.ts
+import Database from "better-sqlite3";
+import { join as join2 } from "path";
+import { existsSync as existsSync2, mkdirSync } from "fs";
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS loop_state (
+  flow_name TEXT NOT NULL,
+  loop_key TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  iterations_run INTEGER NOT NULL DEFAULT 0,
+  completed_at TEXT,
+  PRIMARY KEY (flow_name, loop_key)
+);
+`;
+var _db = null;
+function getDb(cwd) {
+  if (_db) return _db;
+  const dir = join2(cwd, ".ralph-flow");
+  if (!existsSync2(dir)) mkdirSync(dir, { recursive: true });
+  _db = new Database(join2(dir, ".ralphflow.db"));
+  _db.pragma("journal_mode = WAL");
+  _db.exec(SCHEMA);
+  return _db;
+}
+function getLoopStatus(db, flow, loopKey) {
+  const row = db.prepare("SELECT status FROM loop_state WHERE flow_name = ? AND loop_key = ?").get(flow, loopKey);
+  return row ? row.status : "pending";
+}
+function isLoopComplete(db, flow, loopKey) {
+  return getLoopStatus(db, flow, loopKey) === "complete";
+}
+function markLoopRunning(db, flow, loopKey) {
+  db.prepare(`
+    INSERT INTO loop_state (flow_name, loop_key, status, iterations_run)
+    VALUES (?, ?, 'running', 0)
+    ON CONFLICT(flow_name, loop_key) DO UPDATE SET status = 'running'
+  `).run(flow, loopKey);
+}
+function incrementIteration(db, flow, loopKey) {
+  db.prepare(`
+    UPDATE loop_state SET iterations_run = iterations_run + 1
+    WHERE flow_name = ? AND loop_key = ?
+  `).run(flow, loopKey);
+}
+function markLoopComplete(db, flow, loopKey) {
+  db.prepare(`
+    UPDATE loop_state SET status = 'complete', completed_at = datetime('now')
+    WHERE flow_name = ? AND loop_key = ?
+  `).run(flow, loopKey);
+}
+function getAllLoopStates(db, flow) {
+  return db.prepare("SELECT * FROM loop_state WHERE flow_name = ?").all(flow);
+}
+
+// src/core/status.ts
+import { readFileSync as readFileSync2, existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+import chalk from "chalk";
+import Table from "cli-table3";
+async function showStatus(cwd, flowName) {
+  const flows = flowName ? [flowName] : listFlows(cwd);
+  if (flows.length === 0) {
+    console.log();
+    console.log(chalk.yellow("  No flows found. Run `npx ralphflow init` first."));
+    console.log();
+    return;
+  }
+  for (const flow of flows) {
+    const flowDir = resolveFlowDir(cwd, flow);
+    const config = loadConfig(flowDir);
+    console.log();
+    console.log(chalk.bold(`  RalphFlow \u2014 ${flow}`));
+    console.log();
+    const table = new Table({
+      chars: {
+        top: "",
+        "top-mid": "",
+        "top-left": "",
+        "top-right": "",
+        bottom: "",
+        "bottom-mid": "",
+        "bottom-left": "",
+        "bottom-right": "",
+        left: "  ",
+        "left-mid": "",
+        mid: "",
+        "mid-mid": "",
+        right: "",
+        "right-mid": "",
+        middle: "  "
+      },
+      style: { "padding-left": 0, "padding-right": 1 },
+      head: [
+        chalk.dim("Loop"),
+        chalk.dim("Stage"),
+        chalk.dim("Active"),
+        chalk.dim("Progress")
+      ]
+    });
+    const sortedLoops = Object.entries(config.loops).sort(([, a], [, b]) => a.order - b.order);
+    for (const [key, loop] of sortedLoops) {
+      const status = parseTracker(loop.tracker, flowDir, loop.name);
+      table.push([
+        loop.name,
+        status.stage,
+        status.active,
+        `${status.completed}/${status.total}`
+      ]);
+      if (status.agents && status.agents.length > 0) {
+        for (const agent of status.agents) {
+          table.push([
+            chalk.dim(`  ${agent.name}`),
+            chalk.dim(agent.stage),
+            chalk.dim(agent.activeTask),
+            chalk.dim(agent.lastHeartbeat)
+          ]);
+        }
+      }
+    }
+    console.log(table.toString());
+  }
+  console.log();
+}
+function parseTracker(trackerPath, flowDir, loopName) {
+  const fullPath = join3(flowDir, trackerPath);
+  const status = {
+    loop: loopName,
+    stage: "\u2014",
+    active: "none",
+    completed: 0,
+    total: 0
+  };
+  if (!existsSync3(fullPath)) {
+    return status;
+  }
+  const content = readFileSync2(fullPath, "utf-8");
+  const lines = content.split("\n");
+  for (const line of lines) {
+    const metaMatch = line.match(/^- (\w[\w_]*): (.+)$/);
+    if (metaMatch) {
+      const [, key, value] = metaMatch;
+      if (key === "stage") status.stage = value.trim();
+      if (key === "active_story" || key === "active_task") status.active = value.trim();
+      if (key === "completed_stories" || key === "completed_tasks") {
+        const arrayMatch = value.match(/\[(.+)\]/);
+        if (arrayMatch) {
+          status.completed = arrayMatch[1].split(",").filter((s) => s.trim()).length;
+        }
+      }
+    }
+  }
+  const unchecked = (content.match(/- \[ \]/g) || []).length;
+  const checked = (content.match(/- \[x\]/gi) || []).length;
+  if (unchecked + checked > 0) {
+    status.total = unchecked + checked;
+    status.completed = checked;
+  }
+  const agentTableMatch = content.match(/\| agent \|.*\n\|[-|]+\n((?:\|.*\n)*)/);
+  if (agentTableMatch) {
+    const agentRows = agentTableMatch[1].trim().split("\n");
+    status.agents = [];
+    for (const row of agentRows) {
+      const cells = row.split("|").map((s) => s.trim()).filter(Boolean);
+      if (cells.length >= 4) {
+        status.agents.push({
+          name: cells[0],
+          activeTask: cells[1],
+          stage: cells[2],
+          lastHeartbeat: cells[3]
+        });
+      }
+    }
+    if (status.agents.length === 0) {
+      status.agents = void 0;
+    }
+  }
+  return status;
+}
+
+export {
+  listFlows,
+  resolveFlowDir,
+  loadConfig,
+  resolveLoop,
+  getDb,
+  isLoopComplete,
+  markLoopRunning,
+  incrementIteration,
+  markLoopComplete,
+  getAllLoopStates,
+  showStatus,
+  parseTracker
+};