@towles/tool 0.0.20 → 0.0.48

package/src/commands/ralph/run.ts

@@ -0,0 +1,345 @@
+import * as fs from "node:fs";
+import { Flags } from "@oclif/core";
+import consola from "consola";
+import { colors } from "consola/utils";
+import { BaseCommand } from "../base.js";
+import {
+  DEFAULT_STATE_FILE,
+  DEFAULT_LOG_FILE,
+  DEFAULT_MAX_ITERATIONS,
+  DEFAULT_COMPLETION_MARKER,
+  CLAUDE_DEFAULT_ARGS,
+  loadState,
+  saveState,
+  appendHistory,
+  resolveRalphPath,
+  getRalphPaths,
+} from "../../lib/ralph/state.js";
+import {
+  buildIterationPrompt,
+  formatDuration,
+  extractOutputSummary,
+  detectCompletionMarker,
+} from "../../lib/ralph/formatter.js";
+import { checkClaudeCli, runIteration } from "../../lib/ralph/execution.js";
+import type { RalphPlan } from "../../lib/ralph/state.js";
+
+/** Get the plan to work on: focused plan or first incomplete */
+function getCurrentPlan(plans: RalphPlan[], focusedPlanId: number | null): RalphPlan | undefined {
+  if (focusedPlanId !== null) {
+    return plans.find((p) => p.id === focusedPlanId);
+  }
+  return plans.find((p) => p.status !== "done");
+}
+
+/**
+ * Run the autonomous ralph loop
+ */
+export default class Run extends BaseCommand {
+  static override description = "Start the autonomous ralph loop";
+
+  static override examples = [
+    { description: "Start the autonomous loop", command: "<%= config.bin %> <%= command.id %>" },
+    {
+      description: "Limit to 20 iterations",
+      command: "<%= config.bin %> <%= command.id %> --maxIterations 20",
+    },
+    {
+      description: "Focus on specific plan",
+      command: "<%= config.bin %> <%= command.id %> --planId 5",
+    },
+    {
+      description: "Run without auto-committing",
+      command: "<%= config.bin %> <%= command.id %> --no-autoCommit",
+    },
+    {
+      description: "Preview config without executing",
+      command: "<%= config.bin %> <%= command.id %> --dryRun",
+    },
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    stateFile: Flags.string({
+      char: "s",
+      description: `State file path (default: ${DEFAULT_STATE_FILE})`,
+    }),
+    planId: Flags.integer({
+      char: "p",
+      description: "Focus on specific plan ID",
+    }),
+    maxIterations: Flags.integer({
+      char: "m",
+      description: "Max iterations",
+      default: DEFAULT_MAX_ITERATIONS,
+    }),
+    autoCommit: Flags.boolean({
+      description: "Auto-commit after each completed plan",
+      default: true,
+      allowNo: true,
+    }),
+    dryRun: Flags.boolean({
+      char: "n",
+      description: "Show config without executing",
+      default: false,
+    }),
+    claudeArgs: Flags.string({
+      description: "Extra args to pass to claude CLI (space-separated)",
+    }),
+    logFile: Flags.string({
+      description: `Log file path (default: ${DEFAULT_LOG_FILE})`,
+    }),
+    completionMarker: Flags.string({
+      description: "Completion marker",
+      default: DEFAULT_COMPLETION_MARKER,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(Run);
+    const ralphSettings = this.settings.settings.ralphSettings;
+    const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
+    const logFile = resolveRalphPath(flags.logFile, "logFile", ralphSettings);
+    const ralphPaths = getRalphPaths(ralphSettings);
+
+    const maxIterations = flags.maxIterations;
+    const extraClaudeArgs = flags.claudeArgs?.split(" ").filter(Boolean) || [];
+    const focusedPlanId = flags.planId ?? null;
+
+    // Load existing state
+    let state = loadState(stateFile);
+
+    if (!state) {
+      this.error(`No state file found at: ${stateFile}\nUse: tt ralph plan add --file path.md`);
+    }
+
+    const remainingPlans = state.plans.filter((t) => t.status !== "done");
+    if (remainingPlans.length === 0) {
+      consola.log(colors.green("✅ All plans are done!"));
+      return;
+    }
+
+    // Validate focused plan if specified
+    if (focusedPlanId !== null) {
+      const focusedPlan = state.plans.find((t) => t.id === focusedPlanId);
+      if (!focusedPlan) {
+        this.error(`Plan #${focusedPlanId} not found. Use: tt ralph plan list`);
+      }
+      if (focusedPlan.status === "done") {
+        consola.log(colors.yellow(`Plan #${focusedPlanId} is already done.`));
+        return;
+      }
+    }
+
+    // Get current plan to work on
+    const currentPlan = getCurrentPlan(state.plans, focusedPlanId);
+    if (!currentPlan) {
+      consola.log(colors.green("✅ All plans are done!"));
+      return;
+    }
+
+    // Dry run mode
+    if (flags.dryRun) {
+      consola.log(colors.bold("\n=== DRY RUN ===\n"));
+      consola.log(colors.cyan("Config:"));
+      consola.log(`  Max iterations: ${maxIterations}`);
+      consola.log(`  State file: ${stateFile}`);
+      consola.log(`  Log file: ${logFile}`);
+      consola.log(`  Completion marker: ${flags.completionMarker}`);
+      consola.log(`  Auto-commit: ${flags.autoCommit}`);
+      consola.log(`  Claude args: ${[...CLAUDE_DEFAULT_ARGS, ...extraClaudeArgs].join(" ")}`);
+      consola.log(`  Remaining plans: ${remainingPlans.length}`);
+
+      consola.log(colors.cyan("\nCurrent plan:"));
+      consola.log(`  #${currentPlan.id}: ${currentPlan.description}`);
+
+      // Show prompt preview
+      const prompt = buildIterationPrompt({
+        completionMarker: flags.completionMarker,
+        plan: currentPlan,
+        skipCommit: !flags.autoCommit,
+      });
+      consola.log(colors.dim("─".repeat(60)));
+      consola.log(colors.bold("Prompt Preview"));
+      consola.log(colors.dim("─".repeat(60)));
+      consola.log(prompt);
+      consola.log(colors.dim("─".repeat(60)));
+
+      consola.log(colors.bold("\n=== END DRY RUN ===\n"));
+      return;
+    }
+
+    // Check claude CLI is available
+    if (!(await checkClaudeCli())) {
+      this.error(
+        "claude CLI not found in PATH\nInstall Claude Code: https://docs.anthropic.com/en/docs/claude-code",
+      );
+    }
+
+    // Update state for this run
+    state.status = "running";
+
+    // Create log stream (append mode)
+    const logStream = fs.createWriteStream(logFile, { flags: "a" });
+
+    const ready = state.plans.filter((t) => t.status === "ready").length;
+    const done = state.plans.filter((t) => t.status === "done").length;
+
+    logStream.write(`\n${"=".repeat(60)}\n`);
+    logStream.write(`Ralph Loop Started: ${new Date().toISOString()}\n`);
+    logStream.write(`${"=".repeat(60)}\n\n`);
+
+    consola.log(colors.bold(colors.blue("\nRalph Loop Starting\n")));
+    consola.log(colors.dim(`Focus: ${focusedPlanId ? `Plan #${focusedPlanId}` : "Ralph picks"}`));
+    consola.log(colors.dim(`Max iterations: ${maxIterations}`));
+    consola.log(colors.dim(`Log file: ${logFile}`));
+    consola.log(colors.dim(`Auto-commit: ${flags.autoCommit}`));
+    consola.log(colors.dim(`Tasks: ${state.plans.length} (${done} done, ${ready} ready)`));
+    consola.log("");
+
+    logStream.write(`Focus: ${focusedPlanId ? `Plan #${focusedPlanId}` : "Ralph picks"}\n`);
+    logStream.write(`Max iterations: ${maxIterations}\n`);
+    logStream.write(`Tasks: ${state.plans.length} (${done} done, ${ready} ready)\n\n`);
+
+    // Handle SIGINT gracefully
+    let interrupted = false;
+    process.on("SIGINT", () => {
+      if (interrupted) {
+        logStream.end();
+        process.exit(130);
+      }
+      interrupted = true;
+      const msg = "\n\nInterrupted. Press Ctrl+C again to force exit.\n";
+      consola.log(colors.yellow(msg));
+      logStream.write(msg);
+      state.status = "error";
+      saveState(state, stateFile);
+    });
+
+    // Main loop
+    let completed = false;
+    let iteration = 0;
+
+    while (iteration < maxIterations && !interrupted && !completed) {
+      iteration++;
+
+      const iterHeader = `Iteration ${iteration}/${maxIterations}`;
+      logStream.write(`\n━━━ ${iterHeader} ━━━\n`);
+
+      const iterationStart = new Date().toISOString();
+      // Get current plan for this iteration
+      const plan = getCurrentPlan(state.plans, focusedPlanId);
+      if (!plan) {
+        completed = true;
+        state.status = "completed";
+        saveState(state, stateFile);
+        consola.log(
+          colors.bold(colors.green(`\n✅ All plans completed after ${iteration} iteration(s)`)),
+        );
+        logStream.write(`\n✅ All plans completed after ${iteration} iteration(s)\n`);
+        break;
+      }
+      const prompt = buildIterationPrompt({
+        completionMarker: flags.completionMarker,
+        plan: plan,
+        skipCommit: !flags.autoCommit,
+      });
+
+      // Log the prompt
+      logStream.write(`\n--- Prompt ---\n${prompt}\n--- End Prompt ---\n\n`);
+
+      // Build claude args
+      const iterClaudeArgs = [...extraClaudeArgs];
+
+      // Print iteration header
+      consola.log("");
+      consola.log(colors.bold(colors.blue(`━━━ ${iterHeader} ━━━`)));
+      consola.log(colors.dim("─".repeat(60)));
+      consola.log(colors.bold("Prompt"));
+      consola.log(colors.dim("─".repeat(60)));
+      consola.log(prompt);
+      consola.log(colors.dim("─".repeat(60)));
+
+      // Run iteration - output goes directly to stdout
+      const iterResult = await runIteration(prompt, iterClaudeArgs, logStream);
+
+      // Reload state from disk to pick up changes made by child claude process
+      const freshState = loadState(stateFile);
+      if (freshState) {
+        Object.assign(state, freshState);
+      }
+
+      const iterationEnd = new Date().toISOString();
+      const markerFound = detectCompletionMarker(iterResult.output, flags.completionMarker);
+
+      // Calculate duration
+      const startTime = new Date(iterationStart).getTime();
+      const endTime = new Date(iterationEnd).getTime();
+      const durationMs = endTime - startTime;
+      const durationHuman = formatDuration(durationMs);
+
+      // Record history
+      appendHistory(
+        {
+          iteration,
+          startedAt: iterationStart,
+          completedAt: iterationEnd,
+          durationMs,
+          durationHuman,
+          outputSummary: extractOutputSummary(iterResult.output),
+          markerFound,
+          contextUsedPercent: iterResult.contextUsedPercent,
+        },
+        ralphPaths.historyFile,
+      );
+
+      // Save state
+      saveState(state, stateFile);
+
+      // Log summary
+      const contextInfo =
+        iterResult.contextUsedPercent !== undefined
+          ? ` | Context: ${iterResult.contextUsedPercent}%`
+          : "";
+      logStream.write(
+        `\n━━━ Iteration ${iteration} Summary ━━━\nDuration: ${durationHuman}${contextInfo}\nMarker found: ${markerFound ? "yes" : "no"}\n`,
+      );
+      consola.log(
+        colors.dim(
+          `Duration: ${durationHuman}${contextInfo} | Marker: ${markerFound ? colors.green("yes") : colors.yellow("no")}`,
+        ),
+      );
+
+      // Check completion
+      if (markerFound) {
+        completed = true;
+        state.status = "completed";
+        saveState(state, stateFile);
+        consola.log(
+          colors.bold(colors.green(`\n✅ Plan completed after ${iteration} iteration(s)`)),
+        );
+        logStream.write(`\n✅ Plan completed after ${iteration} iteration(s)\n`);
+      }
+    }
+
+    logStream.end();
+
+    // Final status
+    if (completed) {
+      return;
+    }
+
+    if (!interrupted && iteration >= maxIterations) {
+      state.status = "max_iterations_reached";
+      saveState(state, stateFile);
+      consola.log(
+        colors.bold(
+          colors.yellow(`\n⚠️  Max iterations (${maxIterations}) reached without completion`),
+        ),
+      );
+      consola.log(colors.dim(`State saved to: ${stateFile}`));
+      logStream.write(`\n⚠️  Max iterations (${maxIterations}) reached without completion\n`);
+      this.exit(1);
+    }
+  }
+}

package/src/commands/ralph/show.ts

@@ -0,0 +1,88 @@
+import { Flags } from "@oclif/core";
+import consola from "consola";
+import { colors } from "consola/utils";
+import { BaseCommand } from "../base.js";
+import { DEFAULT_STATE_FILE, loadState, resolveRalphPath } from "../../lib/ralph/state.js";
+import {
+  formatPlanAsMarkdown,
+  formatPlanAsJson,
+  copyToClipboard,
+} from "../../lib/ralph/formatter.js";
+
+/**
+ * Show plan summary with status, tasks, and mermaid graph
+ */
+export default class Show extends BaseCommand {
+  static override description = "Show plan summary with status, tasks, and mermaid graph";
+
+  static override examples = [
+    {
+      description: "Show plan summary with mermaid graph",
+      command: "<%= config.bin %> <%= command.id %>",
+    },
+    {
+      description: "Output plan as JSON",
+      command: "<%= config.bin %> <%= command.id %> --format json",
+    },
+    {
+      description: "Copy plan output to clipboard",
+      command: "<%= config.bin %> <%= command.id %> --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({
+      char: "c",
+      description: "Copy output to clipboard",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(Show);
+    const ralphSettings = this.settings.settings.ralphSettings;
+    const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
+
+    const state = loadState(stateFile);
+
+    if (!state) {
+      consola.log(colors.yellow(`No state file found at: ${stateFile}`));
+      return;
+    }
+
+    if (state.plans.length === 0) {
+      consola.log(colors.yellow("No tasks in state file."));
+      consola.log(colors.dim('Use: tt ralph plan add "description"'));
+      return;
+    }
+
+    let output: string;
+
+    if (flags.format === "json") {
+      output = formatPlanAsJson(state.plans, state);
+    } else {
+      output = formatPlanAsMarkdown(state.plans, state);
+    }
+
+    consola.log(output);
+
+    if (flags.copy) {
+      if (copyToClipboard(output)) {
+        consola.log(colors.green("✓ Copied to clipboard"));
+      } else {
+        consola.log(colors.yellow("⚠ Could not copy to clipboard (xclip/xsel not installed?)"));
+      }
+    }
+  }
+}

package/src/config/settings.ts

@@ -0,0 +1,136 @@
+import { z } from "zod/v4";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { homedir } from "node:os";
+import consola from "consola";
+import { colors } from "consola/utils";
+
+const TOOL_NAME = "towles-tool";
+
+/** Default config directory */
+export const DEFAULT_CONFIG_DIR = path.join(homedir(), ".config", TOOL_NAME);
+
+/** User settings file path */
+export const USER_SETTINGS_PATH = path.join(DEFAULT_CONFIG_DIR, `${TOOL_NAME}.settings.json`);
+
+export const RalphSettingsSchema = z.object({
+  // Base directory for ralph files (relative to cwd or absolute)
+  stateDir: z.string().default("./.claude/.ralph"),
+});
+
+export type RalphSettings = z.infer<typeof RalphSettingsSchema>;
+
+export const JournalSettingsSchema = z.object({
+  // Base folder where all journal files are stored
+  baseFolder: z.string().default(path.join(homedir())),
+  // https://moment.github.io/luxon/#/formatting?id=table-of-tokens
+  dailyPathTemplate: z
+    .string()
+    .default(
+      path.join(
+        "journal/{monday:yyyy}/{monday:MM}/daily-notes/{monday:yyyy}-{monday:MM}-{monday:dd}-daily-notes.md",
+      ),
+    ),
+  meetingPathTemplate: z
+    .string()
+    .default(path.join("journal/{yyyy}/{MM}/meetings/{yyyy}-{MM}-{dd}-{title}.md")),
+  notePathTemplate: z
+    .string()
+    .default(path.join("journal/{yyyy}/{MM}/notes/{yyyy}-{MM}-{dd}-{title}.md")),
+  // Directory for external templates (fallback to hardcoded if not found)
+  templateDir: z.string().default(path.join(homedir(), ".config", TOOL_NAME, "templates")),
+});
+
+export type JournalSettings = z.infer<typeof JournalSettingsSchema>;
+
+export const UserSettingsSchema = z.object({
+  preferredEditor: z.string().default("code"),
+  journalSettings: JournalSettingsSchema.optional().transform(
+    (v) => v ?? JournalSettingsSchema.parse({}),
+  ),
+  ralphSettings: RalphSettingsSchema.optional().transform(
+    (v) => v ?? RalphSettingsSchema.parse({}),
+  ),
+});
+
+type UserSettings = z.infer<typeof UserSettingsSchema>;
+
+export interface SettingsFile {
+  settings: UserSettings;
+  path: string;
+}
+
+function createDefaultSettings(): UserSettings {
+  return UserSettingsSchema.parse({});
+}
+
+function createAndSaveDefaultSettings(): UserSettings {
+  const userSettings = createDefaultSettings();
+  saveSettings({
+    path: USER_SETTINGS_PATH,
+    settings: userSettings,
+  });
+  return userSettings;
+}
+
+export function saveSettings(settingsFile: SettingsFile): void {
+  try {
+    // Ensure the directory exists
+    const dirPath = path.dirname(settingsFile.path);
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+
+    fs.writeFileSync(settingsFile.path, JSON.stringify(settingsFile.settings, null, 2), "utf-8");
+  } catch (error) {
+    consola.error("Error saving user settings file:", error);
+  }
+}
+
+export async function loadSettings(): Promise<SettingsFile> {
+  let userSettings: UserSettings | null = null;
+
+  // Load user settings
+  if (fs.existsSync(USER_SETTINGS_PATH)) {
+    const userContent = fs.readFileSync(USER_SETTINGS_PATH, "utf-8");
+    const parsedUserSettings: unknown = JSON.parse(userContent);
+
+    userSettings = UserSettingsSchema.parse(parsedUserSettings);
+    // made add a save here if the default values differ from the current values
+    if (JSON.stringify(parsedUserSettings) !== JSON.stringify(userSettings)) {
+      consola.warn(`Settings file ${USER_SETTINGS_PATH} has been updated with default values.`);
+      const tempSettingsFile: SettingsFile = {
+        path: USER_SETTINGS_PATH,
+        settings: userSettings,
+      };
+
+      saveSettings(tempSettingsFile);
+    }
+  } else {
+    // Settings file doesn't exist
+    const isNonInteractive = process.env.CI || !process.stdout.isTTY;
+
+    if (isNonInteractive) {
+      // Auto-create in CI/non-TTY environments
+      consola.info(`Creating settings file: ${USER_SETTINGS_PATH}`);
+      userSettings = createAndSaveDefaultSettings();
+    } else {
+      // Interactive: ask user if they want to create it
+      const confirmed = await consola.prompt(
+        `Settings file not found. Create ${colors.cyan(USER_SETTINGS_PATH)}?`,
+        {
+          type: "confirm",
+        },
+      );
+      if (!confirmed) {
+        throw new Error(`Settings file not found and user chose not to create it.`);
+      }
+      userSettings = createAndSaveDefaultSettings();
+    }
+  }
+
+  return {
+    path: USER_SETTINGS_PATH,
+    settings: userSettings!,
+  };
+}