@towles/tool 0.0.18 → 0.0.41

package/src/commands/ralph/lib/formatter.ts

@@ -0,0 +1,298 @@
+import { execFileSync } from "node:child_process";
+import type { RalphTask, TaskStatus, RalphState } from "./state.js";
+
+// ============================================================================
+// Clipboard Utility
+// ============================================================================
+
+export function copyToClipboard(text: string): boolean {
+  try {
+    const platform = process.platform;
+    if (platform === "darwin") {
+      execFileSync("pbcopy", [], { input: text });
+    } else if (platform === "linux") {
+      // Try xclip first, then xsel
+      try {
+        execFileSync("xclip", ["-selection", "clipboard"], { input: text });
+      } catch {
+        execFileSync("xsel", ["--clipboard", "--input"], { input: text });
+      }
+    } else if (platform === "win32") {
+      execFileSync("clip", [], { input: text });
+    } else {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================================
+// Task Formatting
+// ============================================================================
+
+export function formatTasksForPrompt(tasks: RalphTask[]): string {
+  if (tasks.length === 0) {
+    return "No tasks.";
+  }
+
+  const statusIcon = (status: TaskStatus): string => {
+    switch (status) {
+      case "done":
+        return "✓";
+      case "ready":
+        return "○";
+      case "blocked":
+        return "⏸";
+      case "cancelled":
+        return "✗";
+    }
+  };
+
+  const lines: string[] = [];
+  for (const t of tasks) {
+    const checkbox = t.status === "done" ? "[x]" : "[ ]";
+    lines.push(`- ${checkbox} #${t.id} ${t.description} \`${statusIcon(t.status)} ${t.status}\``);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format tasks as markdown with checkboxes and status badges.
+ */
+export function formatTasksAsMarkdown(tasks: RalphTask[]): string {
+  if (tasks.length === 0) {
+    return "# Tasks\n\nNo tasks.\n";
+  }
+
+  const statusBadge = (status: TaskStatus): string => {
+    switch (status) {
+      case "done":
+        return "`✓ done`";
+      case "ready":
+        return "`○ ready`";
+      case "blocked":
+        return "`⏸ blocked`";
+      case "cancelled":
+        return "`✗ cancelled`";
+    }
+  };
+
+  const ready = tasks.filter((t) => t.status === "ready");
+  const done = tasks.filter((t) => t.status === "done");
+
+  const lines: string[] = ["# Tasks", ""];
+  lines.push(
+    `**Total:** ${tasks.length} | **Done:** ${done.length} | **Ready:** ${ready.length}`,
+    "",
+  );
+
+  if (ready.length > 0) {
+    lines.push("## Ready", "");
+    for (const t of ready) {
+      lines.push(`- [ ] **#${t.id}** ${t.description} ${statusBadge(t.status)}`);
+    }
+    lines.push("");
+  }
+
+  if (done.length > 0) {
+    lines.push("## Done", "");
+    for (const t of done) {
+      lines.push(`- [x] **#${t.id}** ${t.description} ${statusBadge(t.status)}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format tasks as a plan with markdown and optional mermaid graph.
+ */
+export function formatPlanAsMarkdown(tasks: RalphTask[], state: RalphState): string {
+  const lines: string[] = ["# Ralph Plan", ""];
+
+  // Summary section
+  const ready = tasks.filter((t) => t.status === "ready").length;
+  const done = tasks.filter((t) => t.status === "done").length;
+
+  lines.push("## Summary", "");
+  lines.push(`- **Status:** ${state.status}`);
+  lines.push(`- **Iteration:** ${state.iteration}/${state.maxIterations}`);
+  lines.push(`- **Total Tasks:** ${tasks.length}`);
+  lines.push(`- **Done:** ${done} | **Ready:** ${ready}`);
+  if (state.sessionId) {
+    lines.push(`- **Session ID:** ${state.sessionId.slice(0, 8)}...`);
+  }
+  lines.push("");
+
+  // Tasks section with checkboxes
+  lines.push("## Tasks", "");
+  for (const t of tasks) {
+    const checkbox = t.status === "done" ? "[x]" : "[ ]";
+    const status = t.status === "done" ? "`done`" : "`ready`";
+    lines.push(`- ${checkbox} **#${t.id}** ${t.description} ${status}`);
+  }
+  lines.push("");
+
+  // Mermaid graph section
+  lines.push("## Progress Graph", "");
+  lines.push("```mermaid");
+  lines.push("graph LR");
+  lines.push(`    subgraph Progress["Tasks: ${done}/${tasks.length} done"]`);
+
+  for (const t of tasks) {
+    const shortDesc =
+      t.description.length > 30 ? t.description.slice(0, 27) + "..." : t.description;
+    // Escape quotes in descriptions
+    const safeDesc = shortDesc.replace(/"/g, "'");
+    const nodeId = `T${t.id}`;
+
+    if (t.status === "done") {
+      lines.push(`        ${nodeId}["#${t.id}: ${safeDesc}"]:::done`);
+    } else {
+      lines.push(`        ${nodeId}["#${t.id}: ${safeDesc}"]:::ready`);
+    }
+  }
+
+  lines.push("    end");
+  lines.push("    classDef done fill:#22c55e,color:#fff");
+  lines.push("    classDef ready fill:#94a3b8,color:#000");
+  lines.push("```");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Format tasks as JSON for programmatic consumption.
+ */
+export function formatPlanAsJson(tasks: RalphTask[], state: RalphState): string {
+  return JSON.stringify(
+    {
+      status: state.status,
+      iteration: state.iteration,
+      maxIterations: state.maxIterations,
+      sessionId: state.sessionId,
+      summary: {
+        total: tasks.length,
+        done: tasks.filter((t) => t.status === "done").length,
+        ready: tasks.filter((t) => t.status === "ready").length,
+      },
+      tasks: tasks.map((t) => ({
+        id: t.id,
+        description: t.description,
+        status: t.status,
+        addedAt: t.addedAt,
+        completedAt: t.completedAt,
+      })),
+    },
+    null,
+    2,
+  );
+}
+
+// ============================================================================
+// Duration Formatting
+// ============================================================================
+
+export function formatDuration(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+
+  if (hours > 0) {
+    const remainingMins = minutes % 60;
+    return `${hours}h ${remainingMins}m`;
+  }
+  if (minutes > 0) {
+    const remainingSecs = seconds % 60;
+    return `${minutes}m ${remainingSecs}s`;
+  }
+  return `${seconds}s`;
+}
+
+// ============================================================================
+// Output Summary
+// ============================================================================
+
+export function extractOutputSummary(output: string, maxLength: number = 2000): string {
+  const lines = output
+    .split("\n")
+    .filter((l) => l.trim())
+    .slice(-5);
+  let summary = lines.join(" ").trim();
+
+  if (summary.length > maxLength) {
+    summary = summary.substring(0, maxLength) + "...";
+  }
+
+  return summary || "(no output)";
+}
+
+// ============================================================================
+// Prompt Building
+// ============================================================================
+
+export interface BuildPromptOptions {
+  completionMarker: string;
+  progressFile: string;
+  focusedTaskId: number | null;
+  skipCommit?: boolean;
+  progressContent?: string;
+  taskList: string;
+}
+
+export function buildIterationPrompt({
+  completionMarker,
+  progressFile,
+  focusedTaskId,
+  skipCommit = false,
+  progressContent,
+  taskList,
+}: BuildPromptOptions): string {
+  // prompt inspired by https://www.aihero.dev/tips-for-ai-coding-with-ralph-wiggum#2-start-with-hitl-then-go-afk
+
+  let step = 1;
+
+  //IMPORTANT Always tell it to APPEND to progress file, save a lot of tokens by not reading it to update.
+
+  const prompt = `
+<input-current-tasks>
+${taskList}
+</input-current-tasks>
+
+<instructions>
+${step++}. ${
+    focusedTaskId
+      ? `**Work on Task #${focusedTaskId}** (you've been asked to focus on this one).`
+      : `**Choose** which ready task to work on next based on YOUR judgment of priority/dependencies.`
+  }
+${step++}. Work on that single task.
+${step++}. Run type checks and tests.
+${step++}. Mark the task done using CLI: \`tt ralph task done <id>\`
+${step++}. Append to @${progressFile} with what you did.
+${skipCommit ? "" : `${step++}. Make a git commit.`}
+
+**ONE TASK PER ITERATION**
+
+**Before ending:** Run \`tt ralph task list\` to check remaining tasks.
+**ONLY if ALL TASKS are done** then Output: <promise>${completionMarker}</promise>
+</instructions>
+
+<prior-context note="Reference only - these tasks are already completed, do not work on them">
+${progressContent || "(No prior progress)"}
+</prior-context>
+`;
+  return prompt.trim();
+}
+
+// ============================================================================
+// Marker Detection
+// ============================================================================
+
+export function detectCompletionMarker(output: string, marker: string): boolean {
+  return output.includes(marker);
+}

package/src/commands/ralph/lib/index.ts

@@ -0,0 +1,4 @@
+// Re-export all modules for external use
+export * from "./state.js";
+export * from "./formatter.js";
+export * from "./execution.js";

package/src/commands/ralph/lib/marker.ts

@@ -0,0 +1,108 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { homedir } from "node:os";
+import * as readline from "node:readline";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const MARKER_PREFIX = "RALPH_MARKER_";
+const CLAUDE_DIR = path.join(homedir(), ".claude");
+const PROJECTS_DIR = path.join(CLAUDE_DIR, "projects");
+
+// ============================================================================
+// Marker Generation
+// ============================================================================
+
+/**
+ * Generate a random marker string (8 chars alphanumeric)
+ */
+export function generateMarker(): string {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  for (let i = 0; i < 8; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+// ============================================================================
+// Session Search
+// ============================================================================
+
+/**
+ * Get the project directory path for the current working directory
+ */
+function getProjectDir(): string | null {
+  const cwd = process.cwd();
+  // Claude stores projects with path separators replaced by dashes
+  const projectName = cwd.replace(/\//g, "-");
+  const projectDir = path.join(PROJECTS_DIR, projectName);
+
+  if (fs.existsSync(projectDir)) {
+    return projectDir;
+  }
+  return null;
+}
+
+/**
+ * Search for a marker in session files and return the session ID.
+ * Expects the full marker (e.g., RALPH_MARKER_abc123).
+ */
+export async function findSessionByMarker(marker: string): Promise<string | null> {
+  const projectDir = getProjectDir();
+  if (!projectDir) {
+    return null;
+  }
+
+  // Get all .jsonl files in the project directory
+  const files = fs
+    .readdirSync(projectDir)
+    .filter((f) => f.endsWith(".jsonl"))
+    .map((f) => ({
+      name: f,
+      path: path.join(projectDir, f),
+      mtime: fs.statSync(path.join(projectDir, f)).mtime.getTime(),
+    }))
+    // Sort by most recent first
+    .sort((a, b) => b.mtime - a.mtime);
+
+  for (const file of files) {
+    const found = await searchFileForMarker(file.path, marker);
+    if (found) {
+      // Session ID is the filename without .jsonl
+      return file.name.replace(".jsonl", "");
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Search a single file for the marker (streaming to handle large files)
+ */
+async function searchFileForMarker(filePath: string, marker: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const stream = fs.createReadStream(filePath, { encoding: "utf8" });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+
+    let found = false;
+
+    rl.on("line", (line) => {
+      if (line.includes(marker)) {
+        found = true;
+        rl.close();
+        stream.destroy();
+      }
+    });
+
+    rl.on("close", () => {
+      resolve(found);
+    });
+
+    rl.on("error", () => {
+      resolve(false);
+    });
+  });
+}

package/src/commands/ralph/lib/state.ts

@@ -0,0 +1,191 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import pc from "picocolors";
+import { z } from "zod";
+import type { RalphSettings } from "../../../config/settings";
+import { RalphSettingsSchema } from "../../../config/settings";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const DEFAULT_MAX_ITERATIONS = 10;
+export const DEFAULT_STATE_DIR = "./.claude/.ralph";
+export const DEFAULT_COMPLETION_MARKER = "RALPH_DONE";
+
+// File names within stateDir
+const STATE_FILE_NAME = "ralph-state.local.json";
+const LOG_FILE_NAME = "ralph-log.local.md";
+const PROGRESS_FILE_NAME = "ralph-progress.local.md";
+const HISTORY_FILE_NAME = "ralph-history.local.log";
+
+// ============================================================================
+// Path Helpers (use stateDir from settings)
+// ============================================================================
+
+export function getRalphPaths(settings?: RalphSettings) {
+  const stateDir = settings?.stateDir ?? RalphSettingsSchema.parse({}).stateDir;
+  return {
+    stateFile: path.join(stateDir, STATE_FILE_NAME),
+    logFile: path.join(stateDir, LOG_FILE_NAME),
+    progressFile: path.join(stateDir, PROGRESS_FILE_NAME),
+    historyFile: path.join(stateDir, HISTORY_FILE_NAME),
+  };
+}
+
+// Legacy defaults for backwards compatibility (used in flag descriptions)
+export const DEFAULT_STATE_FILE = `${DEFAULT_STATE_DIR}/${STATE_FILE_NAME}`;
+export const DEFAULT_LOG_FILE = `${DEFAULT_STATE_DIR}/${LOG_FILE_NAME}`;
+export const DEFAULT_PROGRESS_FILE = `${DEFAULT_STATE_DIR}/${PROGRESS_FILE_NAME}`;
+export const DEFAULT_HISTORY_FILE = `${DEFAULT_STATE_DIR}/${HISTORY_FILE_NAME}`;
+
+/**
+ * Resolve ralph file path - uses flag value if provided, otherwise computes from settings
+ */
+export function resolveRalphPath(
+  flagValue: string | undefined,
+  pathType: "stateFile" | "logFile" | "progressFile" | "historyFile",
+  settings?: RalphSettings,
+): string {
+  if (flagValue !== undefined) {
+    return flagValue;
+  }
+  const paths = getRalphPaths(settings);
+  return paths[pathType];
+}
+export const CLAUDE_DEFAULT_ARGS = [
+  "--print",
+  "--verbose",
+  "--output-format",
+  "stream-json",
+  "--permission-mode",
+  "bypassPermissions",
+];
+
+// ============================================================================
+// State Validation Schemas
+// ============================================================================
+
+const TaskStatusSchema = z.enum(["ready", "done", "blocked", "cancelled"]);
+
+const RalphTaskSchema = z.object({
+  id: z.number(),
+  description: z.string(),
+  status: TaskStatusSchema,
+  addedAt: z.string(),
+  completedAt: z.string().optional(),
+  sessionId: z.string().optional(),
+  marker: z.string().optional(),
+  label: z.string().optional(),
+});
+
+const RalphStateSchema = z.object({
+  version: z.number(),
+  tasks: z.array(RalphTaskSchema),
+  startedAt: z.string(),
+  iteration: z.number(),
+  maxIterations: z.number(),
+  status: z.enum(["running", "completed", "max_iterations_reached", "error"]),
+  sessionId: z.string().optional(),
+});
+
+// ============================================================================
+// Types (derived from Zod schemas)
+// ============================================================================
+
+export interface IterationHistory {
+  iteration: number;
+  startedAt: string;
+  completedAt: string;
+  durationMs: number;
+  durationHuman: string;
+  outputSummary: string;
+  markerFound: boolean;
+  contextUsedPercent?: number;
+}
+
+export type TaskStatus = z.infer<typeof TaskStatusSchema>;
+export type RalphTask = z.infer<typeof RalphTaskSchema>;
+export type RalphState = z.infer<typeof RalphStateSchema>;
+
+// ============================================================================
+// State Management
+// ============================================================================
+
+export function createInitialState(maxIterations: number): RalphState {
+  return {
+    version: 1,
+    tasks: [],
+    startedAt: new Date().toISOString(),
+    iteration: 0,
+    maxIterations,
+    status: "running",
+  };
+}
+
+/**
+ * Append iteration history as a JSON line to the history log file.
+ * Each line is a complete JSON object for easy parsing.
+ */
+export function appendHistory(
+  history: IterationHistory,
+  historyFile: string = DEFAULT_HISTORY_FILE,
+): void {
+  fs.mkdirSync(path.dirname(historyFile), { recursive: true });
+  const line = JSON.stringify(history) + "\n";
+  fs.appendFileSync(historyFile, line);
+}
+
+export function saveState(state: RalphState, stateFile: string): void {
+  fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+  fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+}
+
+export function loadState(stateFile: string): RalphState | null {
+  try {
+    if (!fs.existsSync(stateFile)) {
+      return null;
+    }
+    const content = fs.readFileSync(stateFile, "utf-8");
+    const parsed = JSON.parse(content);
+
+    // Ensure tasks array exists for backwards compatibility
+    if (!parsed.tasks) {
+      parsed.tasks = [];
+    }
+
+    const result = RalphStateSchema.safeParse(parsed);
+    if (!result.success) {
+      const errors = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ");
+      console.warn(pc.yellow(`Warning: Invalid state file ${stateFile}: ${errors}`));
+      return null;
+    }
+    return result.data;
+  } catch (err) {
+    console.warn(pc.yellow(`Warning: Failed to load state file ${stateFile}: ${err}`));
+    return null;
+  }
+}
+
+export function addTaskToState(
+  state: RalphState,
+  description: string,
+  sessionId?: string,
+  marker?: string,
+  label?: string,
+): RalphTask {
+  const nextId = state.tasks.length > 0 ? Math.max(...state.tasks.map((t) => t.id)) + 1 : 1;
+
+  const newTask: RalphTask = {
+    id: nextId,
+    description,
+    status: "ready",
+    addedAt: new Date().toISOString(),
+    ...(sessionId && { sessionId }),
+    ...(marker && { marker }),
+    ...(label && { label }),
+  };
+
+  state.tasks.push(newTask);
+  return newTask;
+}

package/src/commands/ralph/marker/create.ts

@@ -0,0 +1,23 @@
+import { BaseCommand } from "../../base.js";
+import { generateMarker, MARKER_PREFIX } from "../lib/marker.js";
+
+/**
+ * Generate a random marker for session tracking.
+ * Output this marker during research, then use --findMarker when adding tasks.
+ */
+export default class MarkerCreate extends BaseCommand {
+  static override description = "Generate a random marker for session tracking";
+
+  static override examples = ["<%= config.bin %> ralph marker create"];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+  };
+
+  async run(): Promise<void> {
+    await this.parse(MarkerCreate);
+
+    const marker = generateMarker();
+    console.log(`${MARKER_PREFIX}${marker}`);
+  }
+}

package/src/commands/ralph/plan.ts

@@ -0,0 +1,73 @@
+import { Flags } from "@oclif/core";
+import pc from "picocolors";
+import { BaseCommand } from "../base.js";
+import { DEFAULT_STATE_FILE, loadState, resolveRalphPath } from "./lib/state.js";
+import { formatPlanAsMarkdown, formatPlanAsJson, copyToClipboard } from "./lib/formatter.js";
+
+/**
+ * Show plan summary with status, tasks, and mermaid graph
+ */
+export default class Plan extends BaseCommand {
+  static override description = "Show plan summary with status, tasks, and mermaid graph";
+
+  static override examples = [
+    "<%= config.bin %> ralph plan",
+    "<%= config.bin %> ralph plan --format json",
+    "<%= config.bin %> ralph plan --copy",
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    stateFile: Flags.string({
+      char: "s",
+      description: `State file path (default: ${DEFAULT_STATE_FILE})`,
+    }),
+    format: Flags.string({
+      char: "f",
+      description: "Output format",
+      default: "default",
+      options: ["default", "markdown", "json"],
+    }),
+    copy: Flags.boolean({
+      description: "Copy output to clipboard",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(Plan);
+    const ralphSettings = this.settings.settingsFile.settings.ralphSettings;
+    const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
+
+    const state = loadState(stateFile);
+
+    if (!state) {
+      console.log(pc.yellow(`No state file found at: ${stateFile}`));
+      return;
+    }
+
+    if (state.tasks.length === 0) {
+      console.log(pc.yellow("No tasks in state file."));
+      console.log(pc.dim('Use: tt ralph task add "description"'));
+      return;
+    }
+
+    let output: string;
+
+    if (flags.format === "json") {
+      output = formatPlanAsJson(state.tasks, state);
+    } else {
+      output = formatPlanAsMarkdown(state.tasks, state);
+    }
+
+    console.log(output);
+
+    if (flags.copy) {
+      if (copyToClipboard(output)) {
+        console.log(pc.green("✓ Copied to clipboard"));
+      } else {
+        console.log(pc.yellow("⚠ Could not copy to clipboard (xclip/xsel not installed?)"));
+      }
+    }
+  }
+}