@towles/tool 0.0.20 → 0.0.48

package/src/lib/ralph/formatter.ts

@@ -0,0 +1,238 @@
+import { execFileSync } from "node:child_process";
+import type { RalphPlan, PlanStatus, 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;
+  }
+}
+
+/**
+ * Format plans as markdown with checkboxes and status badges.
+ */
+export function formatPlansAsMarkdown(plans: RalphPlan[]): string {
+  if (plans.length === 0) {
+    return "# Plans\n\nNo plans.\n";
+  }
+
+  const statusBadge = (status: PlanStatus): string => {
+    switch (status) {
+      case "done":
+        return "`✓ done`";
+      case "ready":
+        return "`○ ready`";
+      case "blocked":
+        return "`⏸ blocked`";
+      case "cancelled":
+        return "`✗ cancelled`";
+    }
+  };
+
+  const ready = plans.filter((p) => p.status === "ready");
+  const done = plans.filter((p) => p.status === "done");
+
+  const lines: string[] = ["# Plans", ""];
+  lines.push(
+    `**Total:** ${plans.length} | **Done:** ${done.length} | **Ready:** ${ready.length}`,
+    "",
+  );
+
+  if (ready.length > 0) {
+    lines.push("## Ready", "");
+    for (const p of ready) {
+      lines.push(`- [ ] **#${p.id}** ${p.description} ${statusBadge(p.status)}`);
+    }
+    lines.push("");
+  }
+
+  if (done.length > 0) {
+    lines.push("## Done", "");
+    for (const p of done) {
+      lines.push(`- [x] **#${p.id}** ${p.description} ${statusBadge(p.status)}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format plans with markdown and optional mermaid graph.
+ */
+export function formatPlanAsMarkdown(plans: RalphPlan[], state: RalphState): string {
+  const lines: string[] = ["# Ralph Plan", ""];
+
+  // Summary section
+  const ready = plans.filter((p) => p.status === "ready").length;
+  const done = plans.filter((p) => p.status === "done").length;
+
+  lines.push("## Summary", "");
+  lines.push(`- **Status:** ${state.status}`);
+  lines.push(`- **Total:** ${plans.length}`);
+  lines.push(`- **Done:** ${done} | **Ready:** ${ready}`);
+  lines.push("");
+
+  // Plans section with checkboxes
+  lines.push("## Plans", "");
+  for (const p of plans) {
+    const checkbox = p.status === "done" ? "[x]" : "[ ]";
+    const status = p.status === "done" ? "`done`" : "`ready`";
+    lines.push(`- ${checkbox} **#${p.id}** ${p.description} ${status}`);
+  }
+  lines.push("");
+
+  // Mermaid graph section
+  lines.push("## Progress Graph", "");
+  lines.push("```mermaid");
+  lines.push("graph LR");
+  lines.push(`    subgraph Progress["Plans: ${done}/${plans.length} done"]`);
+
+  for (const p of plans) {
+    const shortDesc =
+      p.description.length > 30 ? p.description.slice(0, 27) + "..." : p.description;
+    // Escape quotes in descriptions
+    const safeDesc = shortDesc.replace(/"/g, "'");
+    const nodeId = `P${p.id}`;
+
+    if (p.status === "done") {
+      lines.push(`        ${nodeId}["#${p.id}: ${safeDesc}"]:::done`);
+    } else {
+      lines.push(`        ${nodeId}["#${p.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 plans as JSON for programmatic consumption.
+ */
+export function formatPlanAsJson(plans: RalphPlan[], state: RalphState): string {
+  return JSON.stringify(
+    {
+      status: state.status,
+      summary: {
+        total: plans.length,
+        done: plans.filter((p) => p.status === "done").length,
+        ready: plans.filter((p) => p.status === "ready").length,
+      },
+      plans: plans.map((p) => ({
+        id: p.id,
+        description: p.description,
+        status: p.status,
+        addedAt: p.addedAt,
+        completedAt: p.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;
+  plan: RalphPlan;
+  skipCommit?: boolean;
+}
+
+export function buildIterationPrompt({
+  completionMarker,
+  plan,
+  skipCommit = false,
+}: BuildPromptOptions): string {
+  let step = 1;
+
+  const prompt = `
+<plan>
+#${plan.id}: ${plan.description}
+</plan>
+
+<instructions>
+${step++}. Work on the plan above.
+${step++}. Run type checks and tests.
+${step++}. Mark done: \`tt ralph plan done ${plan.id}\`
+${skipCommit ? "" : `${step++}. Make a git commit.`}
+
+**Before ending:** Run \`tt ralph plan list\` to check remaining plans.
+**ONLY if ALL PLANS are done** then Output: <promise>${completionMarker}</promise>
+</instructions>
+`;
+  return prompt.trim();
+}
+
+// ============================================================================
+// Marker Detection
+// ============================================================================
+
+export function detectCompletionMarker(output: string, marker: string): boolean {
+  return output.includes(marker);
+}

package/src/lib/ralph/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/lib/ralph/state.ts

@@ -0,0 +1,166 @@
+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.js";
+import { RalphSettingsSchema } from "../../config/settings.js";
+
+// ============================================================================
+// 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 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),
+    historyFile: path.join(stateDir, HISTORY_FILE_NAME),
+  };
+}
+
+// Defaults 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_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" | "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 PlanStatusSchema = z.enum(["ready", "done", "blocked", "cancelled"]);
+
+const RalphPlanSchema = z.object({
+  id: z.number(),
+  description: z.string(),
+  status: PlanStatusSchema,
+  addedAt: z.string(),
+  completedAt: z.string().optional(),
+});
+
+const RalphStateSchema = z.object({
+  version: z.number(),
+  plans: z.array(RalphPlanSchema),
+  startedAt: z.string(),
+  status: z.enum(["running", "completed", "max_iterations_reached", "error"]),
+});
+
+// ============================================================================
+// 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 PlanStatus = z.infer<typeof PlanStatusSchema>;
+export type RalphPlan = z.infer<typeof RalphPlanSchema>;
+export type RalphState = z.infer<typeof RalphStateSchema>;
+
+// ============================================================================
+// State Management
+// ============================================================================
+
+export function createInitialState(): RalphState {
+  return {
+    version: 1,
+    plans: [],
+    startedAt: new Date().toISOString(),
+    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);
+
+    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 addPlanToState(state: RalphState, description: string): RalphPlan {
+  const nextId = state.plans.length > 0 ? Math.max(...state.plans.map((p) => p.id)) + 1 : 1;
+
+  const newPlan: RalphPlan = {
+    id: nextId,
+    description,
+    status: "ready",
+    addedAt: new Date().toISOString(),
+  };
+
+  state.plans.push(newPlan);
+  return newPlan;
+}

package/src/types/journal.ts

@@ -0,0 +1,16 @@
+/**
+ * Journal types and constants
+ */
+
+export const JOURNAL_TYPES = {
+  DAILY_NOTES: "daily-notes",
+  MEETING: "meeting",
+  NOTE: "note",
+} as const;
+
+export type JournalType = (typeof JOURNAL_TYPES)[keyof typeof JOURNAL_TYPES];
+
+export interface JournalArgs {
+  title?: string;
+  journalType: JournalType;
+}

package/src/utils/date-utils.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { formatDate, generateJournalFilename, getMondayOfWeek, getWeekInfo } from "./date-utils";
+
+describe("date utilities", () => {
+  it("should get Monday of the week correctly", () => {
+    // Test with a Wednesday (July 9, 2025)
+    const wednesday = new Date(2025, 6, 9); // July 9, 2025
+    const monday = getMondayOfWeek(wednesday);
+    expect(formatDate(monday)).toBe("2025-07-07");
+
+    // Test with a Friday (July 11, 2025)
+    const friday = new Date(2025, 6, 11); // July 11, 2025
+    const mondayFromFriday = getMondayOfWeek(friday);
+    expect(formatDate(mondayFromFriday)).toBe("2025-07-07");
+
+    // Test with a Sunday (July 13, 2025) - should return Monday of previous week
+    const sunday = new Date(2025, 6, 13); // July 13, 2025
+    const mondayFromSunday = getMondayOfWeek(sunday);
+    expect(formatDate(mondayFromSunday)).toBe("2025-07-07");
+
+    // Test with a Monday (July 7, 2025)
+    const actualMonday = new Date(2025, 6, 7); // July 7, 2025
+    const mondayFromMonday = getMondayOfWeek(actualMonday);
+    expect(formatDate(mondayFromMonday)).toBe("2025-07-07");
+  });
+
+  it("should generate correct journal filename", () => {
+    // Test with different days in the same week
+    const wednesday = new Date(2025, 6, 9); // July 9, 2025
+    const filename = generateJournalFilename(wednesday);
+    expect(filename).toBe("2025-07-07-week.md");
+
+    const friday = new Date(2025, 6, 11); // July 11, 2025
+    const filenameFromFriday = generateJournalFilename(friday);
+    expect(filenameFromFriday).toBe("2025-07-07-week.md");
+  });
+
+  it("should format date correctly", () => {
+    // Use local date constructor (year, month-1, day), not ISO string which is UTC
+    const date = new Date(2025, 6, 7); // July 7, 2025 in local time
+    expect(formatDate(date)).toBe("2025-07-07");
+  });
+
+  it("should get week info correctly", () => {
+    // Test with Monday July 7, 2025
+    const monday = new Date(2025, 6, 7);
+    const weekInfo = getWeekInfo(monday);
+
+    expect(formatDate(weekInfo.mondayDate)).toBe("2025-07-07");
+    expect(formatDate(weekInfo.tuesdayDate)).toBe("2025-07-08");
+    expect(formatDate(weekInfo.wednesdayDate)).toBe("2025-07-09");
+    expect(formatDate(weekInfo.thursdayDate)).toBe("2025-07-10");
+    expect(formatDate(weekInfo.fridayDate)).toBe("2025-07-11");
+  });
+
+  it("should handle edge cases correctly", () => {
+    // Test with year boundary - Monday December 30, 2024
+    const mondayEndOfYear = new Date(2024, 11, 30);
+    const weekInfo = getWeekInfo(mondayEndOfYear);
+
+    expect(formatDate(weekInfo.mondayDate)).toBe("2024-12-30");
+    expect(formatDate(weekInfo.tuesdayDate)).toBe("2024-12-31");
+    expect(formatDate(weekInfo.wednesdayDate)).toBe("2025-01-01");
+    expect(formatDate(weekInfo.thursdayDate)).toBe("2025-01-02");
+    expect(formatDate(weekInfo.fridayDate)).toBe("2025-01-03");
+  });
+
+  it("should handle month boundary correctly", () => {
+    // Test with month boundary - Monday January 29, 2025
+    const mondayEndOfMonth = new Date(2025, 0, 27);
+    const weekInfo = getWeekInfo(mondayEndOfMonth);
+
+    expect(formatDate(weekInfo.mondayDate)).toBe("2025-01-27");
+    expect(formatDate(weekInfo.tuesdayDate)).toBe("2025-01-28");
+    expect(formatDate(weekInfo.wednesdayDate)).toBe("2025-01-29");
+    expect(formatDate(weekInfo.thursdayDate)).toBe("2025-01-30");
+    expect(formatDate(weekInfo.fridayDate)).toBe("2025-01-31");
+  });
+
+  it("should handle getMondayOfWeek with different timezones", () => {
+    // Test with a specific time to ensure hours are reset
+    const dateWithTime = new Date(2025, 6, 9, 15, 30, 45); // July 9, 2025 at 3:30:45 PM
+    const monday = getMondayOfWeek(dateWithTime);
+
+    expect(formatDate(monday)).toBe("2025-07-07");
+    expect(monday.getHours()).toBe(0);
+    expect(monday.getMinutes()).toBe(0);
+    expect(monday.getSeconds()).toBe(0);
+    expect(monday.getMilliseconds()).toBe(0);
+  });
+
+  it("should handle formatDate with different times", () => {
+    // Test that formatDate only considers the date part
+    const dateWithTime = new Date(2025, 6, 7, 10, 30, 45); // July 7, 2025 at 10:30:45 AM
+    expect(formatDate(dateWithTime)).toBe("2025-07-07");
+  });
+});

package/src/utils/date-utils.ts

@@ -0,0 +1,54 @@
+/**
+ * Get the Monday of the week for a given date
+ */
+export function getMondayOfWeek(date: Date): Date {
+  const newDate = new Date(date);
+  const day = newDate.getDay();
+  const diff = newDate.getDate() - day + (day === 0 ? -6 : 1);
+  newDate.setDate(diff);
+  newDate.setHours(0, 0, 0, 0);
+  return newDate;
+}
+
+interface weekInfo {
+  mondayDate: Date;
+  tuesdayDate: Date;
+  wednesdayDate: Date;
+  thursdayDate: Date;
+  fridayDate: Date;
+}
+
+export function getWeekInfo(mondayDate: Date): weekInfo {
+  const tuesdayDate = new Date(mondayDate);
+  tuesdayDate.setDate(mondayDate.getDate() + 1);
+  const wednesdayDate = new Date(mondayDate);
+  wednesdayDate.setDate(mondayDate.getDate() + 2);
+  const thursdayDate = new Date(mondayDate);
+  thursdayDate.setDate(mondayDate.getDate() + 3);
+  const fridayDate = new Date(mondayDate);
+  fridayDate.setDate(mondayDate.getDate() + 4);
+
+  return {
+    mondayDate,
+    tuesdayDate,
+    wednesdayDate,
+    thursdayDate,
+    fridayDate,
+  };
+}
+
+/**
+ * Format date as YYYY-MM-DD in local timezone
+ */
+export function formatDate(date: Date): string {
+  return date.toLocaleDateString("en-CA");
+}
+
+/**
+ * Generate journal filename based on Monday of the current week
+ * Format: YYYY-MM-DD-week.md (always uses Monday's date)
+ */
+export function generateJournalFilename(date: Date = new Date()): string {
+  const monday = getMondayOfWeek(new Date(date));
+  return `${formatDate(monday)}-week.md`;
+}

package/src/utils/git/gh-cli-wrapper.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { getIssues, isGithubCliInstalled } from "./gh-cli-wrapper";
+
+describe.skipIf(!!process.env.CI)("gh-cli-wrapper", () => {
+  it("should return true if gh is installed", async () => {
+    const result = await isGithubCliInstalled();
+    expect(result).toBe(true);
+  });
+
+  it("get issues", async () => {
+    const issues = await getIssues({ assignedToMe: false, cwd: "." });
+    expect(issues.length).toBeGreaterThan(0);
+  });
+});

package/src/utils/git/gh-cli-wrapper.ts

@@ -0,0 +1,54 @@
+import stripAnsi from "strip-ansi";
+import { x } from "tinyexec";
+
+export const isGithubCliInstalled = async (): Promise<boolean> => {
+  try {
+    const proc = await x(`gh`, ["--version"]);
+    return proc.stdout.indexOf("https://github.com/cli/cli") > 0;
+  } catch (e) {
+    return false;
+  }
+};
+
+export interface Issue {
+  labels: {
+    name: string;
+    color: string;
+  }[];
+  number: number;
+  title: string;
+  state: string;
+}
+
+export const getIssues = async ({
+  assignedToMe,
+  cwd,
+}: {
+  assignedToMe: boolean;
+  cwd: string;
+}): Promise<Issue[]> => {
+  let issues: Issue[] = [];
+
+  const flags = ["issue", "list", "--json", "labels,number,title,state"];
+
+  if (assignedToMe) {
+    flags.push("--assignee");
+    flags.push("@me");
+  }
+
+  //console.log('Current working directory:', cwd.stdout.trim())
+
+  const result = await x(`gh`, flags);
+  // Setting NO_COLOR=1 didn't remove colors so had to use stripAnsi
+  const stripped = stripAnsi(result.stdout);
+
+  try {
+    issues = JSON.parse(stripped);
+  } catch {
+    throw new Error(
+      `Failed to parse GitHub CLI output as JSON. Raw output: ${stripped.slice(0, 200)}${stripped.length > 200 ? "..." : ""}`,
+    );
+  }
+
+  return issues;
+};

package/src/utils/git/git-wrapper.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { isGitDirectory } from "./git-wrapper";
+
+describe.skip("git-wrapper", () => {
+  it("isGitDirectory", async () => {
+    const result = await isGitDirectory();
+    expect(result).toBe(true);
+  });
+
+  // it('getMergedBranches', async () => {
+  //   const result = await getMergedBranches()
+
+  //   if (result.length > 0) // may not have branches to cleanup so just check for no errors
+  //     expect(result[0].trim()).toBe(result[0])
+  // })
+
+  // it('getLocalBranchNames', async () => {
+  //   const result = await getLocalBranchNames()
+  //   expect(result.includes('main')).toBeDefined()
+  // })
+
+  // it('getDefaultMainBranchName', async () => {
+  //   const result = await getDefaultMainBranchName()
+  //   expect(result).toBe('main')
+  // })
+});

package/src/utils/git/git-wrapper.ts

@@ -0,0 +1,15 @@
+import { exec } from "tinyexec";
+
+export const isGitDirectory = async (): Promise<boolean> => {
+  try {
+    const result = await exec(`git`, ["status"]);
+    return result.stdout.includes("On branch");
+  } catch (e) {
+    return false;
+  }
+};
+
+export const createBranch = async ({ branchName }: { branchName: string }): Promise<string> => {
+  const result = await exec(`git`, ["checkout", "-b", branchName]);
+  return result.stdout;
+};