@towles/tool 0.0.53 → 0.0.55

package/src/lib/auto-claude/utils.ts

@@ -0,0 +1,334 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import consola from "consola";
+import { x } from "tinyexec";
+
+import { getConfig } from "./config.js";
+import { ARTIFACTS } from "./prompt-templates/index.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const TEMPLATES_DIR = join(__dirname, "prompt-templates");
+
+// ── Shell helpers ──
+
+async function exec(cmd: string, args: string[]): Promise<string> {
+  const result = await x(cmd, args, { nodeOptions: { cwd: process.cwd() }, throwOnError: true });
+  return result.stdout.trim();
+}
+
+export async function execSafe(
+  cmd: string,
+  args: string[],
+): Promise<{ stdout: string; ok: boolean }> {
+  const result = await x(cmd, args, { nodeOptions: { cwd: process.cwd() }, throwOnError: false });
+  return { stdout: (result.stdout ?? "").trim(), ok: result.exitCode === 0 };
+}
+
+export async function gh<T = unknown>(args: string[]): Promise<T> {
+  const out = await exec("gh", args);
+  return JSON.parse(out) as T;
+}
+
+export async function ghRaw(args: string[]): Promise<string> {
+  const result = await execSafe("gh", args);
+  return result.stdout;
+}
+
+export async function git(args: string[]): Promise<string> {
+  return exec("git", args);
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ── Claude CLI ──
+
+export interface ClaudeResult {
+  result: string;
+  is_error: boolean;
+  total_cost_usd: number;
+  num_turns: number;
+}
+
+export async function runClaude(opts: {
+  promptFile: string;
+  permissionMode: "plan" | "acceptEdits";
+  maxTurns?: number;
+  retry?: boolean;
+}): Promise<ClaudeResult> {
+  const args = [
+    "-p",
+    "--output-format",
+    "json",
+    "--permission-mode",
+    opts.permissionMode,
+    ...(opts.maxTurns ? ["--max-turns", String(opts.maxTurns)] : []),
+    `@${opts.promptFile}`,
+  ];
+
+  const cfg = getConfig();
+  let retryDelay = cfg.retryDelayMs;
+  let retries = 0;
+
+  while (true) {
+    try {
+      const proc = await x("claude", args, {
+        nodeOptions: { cwd: process.cwd(), stdio: ["ignore", "pipe", "inherit"] },
+        throwOnError: true,
+      });
+      const stdout = proc.stdout;
+
+      try {
+        const parsed = JSON.parse(stdout) as ClaudeResult;
+        consola.success(`Done — $${parsed.total_cost_usd.toFixed(4)} | ${parsed.num_turns} turns`);
+        if (parsed.result) {
+          consola.box(parsed.result);
+        }
+        return parsed;
+      } catch {
+        consola.warn("Done — failed to parse Claude output");
+        if (stdout.trim()) {
+          consola.box(stdout.trim());
+        }
+        return { result: stdout.trim(), is_error: false, total_cost_usd: 0, num_turns: 0 };
+      }
+    } catch (e) {
+      const shouldRetry = opts.retry ?? cfg.loopRetryEnabled ?? false;
+      if (!shouldRetry) throw e;
+
+      retries++;
+      if (retries >= cfg.maxRetries) {
+        throw new Error(`Claude failed after ${cfg.maxRetries} retries: ${e}`);
+      }
+
+      consola.warn(`Claude process error (attempt ${retries}/${cfg.maxRetries}): ${e}`);
+      consola.info(`Retrying in ${retryDelay / 1000}s...`);
+      await sleep(retryDelay);
+      retryDelay = Math.min(retryDelay * 2, cfg.maxRetryDelayMs);
+    }
+  }
+}
+
+// ── Template resolution ──
+
+export interface TokenValues {
+  SCOPE_PATH: string;
+  ISSUE_DIR: string;
+  MAIN_BRANCH: string;
+}
+
+export function resolveTemplate(
+  templateName: string,
+  tokens: TokenValues,
+  issueDir: string,
+): string {
+  const templatePath = join(TEMPLATES_DIR, templateName);
+  let template = readFileSync(templatePath, "utf-8");
+
+  for (const [key, value] of Object.entries(tokens)) {
+    template = template.replaceAll(`{{${key}}}`, value);
+  }
+
+  const resolvedPath = join(issueDir, templateName);
+  ensureDir(dirname(resolvedPath));
+  writeFileSync(resolvedPath, template, "utf-8");
+
+  return relative(process.cwd(), resolvedPath);
+}
+
+// ── File helpers ──
+
+export function ensureDir(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+}
+
+export function fileExists(path: string): boolean {
+  return existsSync(path);
+}
+
+export function readFile(path: string): string {
+  return readFileSync(path, "utf-8");
+}
+
+export function writeFile(path: string, content: string): void {
+  ensureDir(dirname(path));
+  writeFileSync(path, content, "utf-8");
+}
+
+// ── Git helpers ──
+
+export async function commitArtifacts(ctx: IssueContext, message: string): Promise<void> {
+  await git(["add", ctx.issueDirRel]);
+  const staged = await execSafe("git", ["diff", "--cached", "--name-only"]);
+  if (staged.ok && staged.stdout.length > 0) {
+    await git(["commit", "-m", message]);
+  }
+}
+
+// ── Issue context ──
+
+export interface IssueContext {
+  number: number;
+  title: string;
+  body: string;
+  repo: string;
+  scopePath: string;
+  issueDir: string;
+  issueDirRel: string;
+  branch: string;
+}
+
+export function buildIssueContext(
+  issue: { number: number; title: string; body: string },
+  repo: string,
+  scopePath: string,
+): IssueContext {
+  const issueDirRel = `.auto-claude/issue-${issue.number}`;
+  return {
+    number: issue.number,
+    title: issue.title,
+    body: issue.body,
+    repo,
+    scopePath,
+    issueDir: join(process.cwd(), issueDirRel),
+    issueDirRel,
+    branch: `auto-claude/issue-${issue.number}`,
+  };
+}
+
+export function buildTokens(ctx: IssueContext): TokenValues {
+  return {
+    SCOPE_PATH: ctx.scopePath,
+    ISSUE_DIR: ctx.issueDirRel,
+    MAIN_BRANCH: getConfig().mainBranch,
+  };
+}
+
+export function buildContextFromArtifacts(issueNumber: number): IssueContext {
+  const cfg = getConfig();
+  const issueDirRel = `.auto-claude/issue-${issueNumber}`;
+  const ramblingsPath = join(process.cwd(), issueDirRel, ARTIFACTS.initialRamblings);
+
+  if (!fileExists(ramblingsPath)) {
+    throw new Error(`No artifacts found at ${issueDirRel}. Run the pipeline first.`);
+  }
+
+  const content = readFile(ramblingsPath);
+  const titleMatch = content.match(/^# (.+)$/m);
+  const title = titleMatch?.[1] ?? `Issue #${issueNumber}`;
+
+  // Body starts after the second blank line (past the title and metadata lines)
+  const secondBlankIdx = findNthBlankLine(content.split("\n"), 2);
+  const body = content
+    .split("\n")
+    .slice(secondBlankIdx + 1)
+    .join("\n")
+    .trim();
+
+  return buildIssueContext({ number: issueNumber, title, body }, cfg.repo, cfg.scopePath);
+}
+
+function findNthBlankLine(lines: string[], n: number): number {
+  let count = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === "") {
+      count++;
+      if (count === n) return i;
+    }
+  }
+  return 0;
+}
+
+export function log(msg: string): void {
+  consola.info(`[auto-claude] ${msg}`);
+}
+
+export function logStep(step: string, ctx: IssueContext, skipped = false): void {
+  const tag = skipped ? "SKIP" : "RUN";
+  consola.box({ title: `[${tag}] ${step}`, message: `${ctx.repo}#${ctx.number} — ${ctx.title}` });
+}
+
+// ── Git branch helpers ──
+
+export async function ensureBranch(branch: string): Promise<void> {
+  const { mainBranch, remote } = getConfig();
+
+  try {
+    const branches = await git(["branch", "--list", branch]);
+    if (branches.includes(branch)) {
+      await git(["checkout", branch]);
+      return;
+    }
+  } catch {
+    /* ignore */
+  }
+
+  try {
+    await git(["fetch", remote, branch]);
+    await git(["checkout", branch]);
+    return;
+  } catch {
+    /* doesn't exist remotely */
+  }
+
+  await git(["checkout", mainBranch]);
+  await git(["pull", remote, mainBranch]);
+  await git(["checkout", "-b", branch]);
+}
+
+// ── Common step runner ──
+
+export interface StepRunnerOptions {
+  stepName: string;
+  ctx: IssueContext;
+  artifactPath: string;
+  templateName: string;
+  artifactValidator?: (path: string) => boolean;
+}
+
+/**
+ * Runs a standard pipeline step: check artifact (skip if exists), run Claude
+ * with a template, validate the artifact was produced, and commit.
+ *
+ * Used by plan, plan-implementation, review, and similar steps that follow
+ * the same pattern.
+ */
+export async function runStepWithArtifact(opts: StepRunnerOptions): Promise<boolean> {
+  const { stepName, ctx, artifactPath, templateName, artifactValidator } = opts;
+
+  const isValid = artifactValidator ?? fileExists;
+  if (isValid(artifactPath)) {
+    logStep(stepName, ctx, true);
+    return true;
+  }
+
+  logStep(stepName, ctx);
+
+  const tokens = buildTokens(ctx);
+  const promptFile = resolveTemplate(templateName, tokens, ctx.issueDir);
+
+  const result = await runClaude({
+    promptFile,
+    permissionMode: "acceptEdits",
+    maxTurns: getConfig().maxTurns,
+  });
+
+  if (result.is_error) {
+    consola.error(`${stepName} step failed: ${result.result}`);
+    return false;
+  }
+
+  if (!isValid(artifactPath)) {
+    consola.error(`${stepName} step did not produce expected artifact`);
+    return false;
+  }
+
+  await commitArtifacts(
+    ctx,
+    `chore(auto-claude): ${stepName.toLowerCase()} for ${ctx.repo}#${ctx.number}`,
+  );
+  return true;
+}

package/src/commands/ralph/plan/add.ts

@@ -1,69 +0,0 @@
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { Args, Flags } from "@oclif/core";
-import consola from "consola";
-import { colors } from "consola/utils";
-import { BaseCommand } from "../../base.js";
-import {
-  DEFAULT_STATE_FILE,
-  loadState,
-  saveState,
-  createInitialState,
-  addPlanToState,
-  resolveRalphPath,
-} from "../../../lib/ralph/state.js";
-
-/**
- * Add a new plan to ralph state from a file
- */
-export default class PlanAdd extends BaseCommand {
-  static override description = "Add a new plan from a file";
-
-  static override examples = [
-    {
-      description: "Add a plan from a markdown file",
-      command: "<%= config.bin %> <%= command.id %> docs/plans/2025-01-18-feature.md",
-    },
-  ];
-
-  static override args = {
-    file: Args.string({
-      description: "Path to plan file (markdown)",
-      required: true,
-    }),
-  };
-
-  static override flags = {
-    ...BaseCommand.baseFlags,
-    stateFile: Flags.string({
-      char: "s",
-      description: `State file path (default: ${DEFAULT_STATE_FILE})`,
-    }),
-  };
-
-  async run(): Promise<void> {
-    const { args, flags } = await this.parse(PlanAdd);
-    const ralphSettings = this.settings.settings.ralphSettings;
-    const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
-
-    const planFilePath = resolve(args.file);
-
-    if (!existsSync(planFilePath)) {
-      this.error(`Plan file not found: ${planFilePath}`);
-    }
-
-    let state = loadState(stateFile);
-
-    if (!state) {
-      state = createInitialState();
-    }
-
-    const newPlan = addPlanToState(state, planFilePath);
-    saveState(state, stateFile);
-
-    consola.log(colors.green(`✓ Added plan #${newPlan.id}`));
-    consola.log(colors.dim(`  File: ${planFilePath}`));
-    consola.log(colors.dim(`State saved to: ${stateFile}`));
-    consola.log(colors.dim(`Total plans: ${state.plans.length}`));
-  }
-}

package/src/commands/ralph/plan/done.ts

@@ -1,82 +0,0 @@
-import { Args, Flags } from "@oclif/core";
-import consola from "consola";
-import { colors } from "consola/utils";
-import { BaseCommand } from "../../base.js";
-import {
-  DEFAULT_STATE_FILE,
-  loadState,
-  saveState,
-  resolveRalphPath,
-} from "../../../lib/ralph/state.js";
-
-/**
- * Mark a ralph plan as done
- */
-export default class PlanDone extends BaseCommand {
-  static override description = "Mark a plan as done by ID";
-
-  static override examples = [
-    { description: "Mark plan #1 as done", command: "<%= config.bin %> <%= command.id %> 1" },
-    {
-      description: "Mark done using custom state file",
-      command: "<%= config.bin %> <%= command.id %> 5 --stateFile custom-state.json",
-    },
-  ];
-
-  static override args = {
-    id: Args.integer({
-      description: "Plan ID to mark done",
-      required: true,
-    }),
-  };
-
-  static override flags = {
-    ...BaseCommand.baseFlags,
-    stateFile: Flags.string({
-      char: "s",
-      description: `State file path (default: ${DEFAULT_STATE_FILE})`,
-    }),
-  };
-
-  async run(): Promise<void> {
-    const { args, flags } = await this.parse(PlanDone);
-    const ralphSettings = this.settings.settings.ralphSettings;
-    const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
-
-    const planId = args.id;
-
-    if (planId < 1) {
-      this.error("Invalid plan ID");
-    }
-
-    const state = loadState(stateFile);
-
-    if (!state) {
-      this.error(`No state file found at: ${stateFile}`);
-    }
-
-    const plan = state.plans.find((p) => p.id === planId);
-
-    if (!plan) {
-      this.error(`Plan #${planId} not found. Use: tt ralph plan list`);
-    }
-
-    if (plan.status === "done") {
-      consola.log(colors.yellow(`Plan #${planId} is already done.`));
-      return;
-    }
-
-    plan.status = "done";
-    plan.completedAt = new Date().toISOString();
-    saveState(state, stateFile);
-
-    consola.log(colors.green(`✓ Marked plan #${planId} as done: ${plan.planFilePath}`));
-
-    const remaining = state.plans.filter((p) => p.status !== "done").length;
-    if (remaining === 0) {
-      consola.log(colors.bold(colors.green("All plans complete!")));
-    } else {
-      consola.log(colors.dim(`Remaining plans: ${remaining}`));
-    }
-  }
-}

package/src/commands/ralph/plan/list.test.ts

@@ -1,48 +0,0 @@
-/**
- * Integration tests for oclif ralph plan list command
- * Note: --help output goes through oclif's own routing
- */
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import { runCommand } from "@oclif/test";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { writeFileSync, unlinkSync, existsSync } from "node:fs";
-
-describe("ralph plan list command", () => {
-  const tempStateFile = join(tmpdir(), `ralph-test-list-${Date.now()}.json`);
-
-  beforeAll(() => {
-    // Create state file with one plan to minimize output during tests
-    writeFileSync(
-      tempStateFile,
-      JSON.stringify({
-        version: 1,
-        iteration: 0,
-        maxIterations: 10,
-        status: "running",
-        tasks: [{ id: 1, description: "test", status: "done", addedAt: new Date().toISOString() }],
-        startedAt: new Date().toISOString(),
-      }),
-    );
-  });
-
-  afterAll(() => {
-    if (existsSync(tempStateFile)) unlinkSync(tempStateFile);
-  });
-
-  it("runs task list without error", async () => {
-    const { error } = await runCommand(["ralph:plan:list", "-s", tempStateFile]);
-    expect(error).toBeUndefined();
-  });
-
-  it("supports --format flag", async () => {
-    const { error } = await runCommand([
-      "ralph:plan:list",
-      "--format",
-      "markdown",
-      "-s",
-      tempStateFile,
-    ]);
-    expect(error).toBeUndefined();
-  });
-});

package/src/commands/ralph/plan/list.ts

@@ -1,100 +0,0 @@
-import { Flags } from "@oclif/core";
-import pc from "picocolors";
-import { BaseCommand } from "../../base.js";
-import { DEFAULT_STATE_FILE, loadState, resolveRalphPath } from "../../../lib/ralph/state.js";
-import { formatPlansAsMarkdown } from "../../../lib/ralph/formatter.js";
-
-/**
- * List all ralph plans
- */
-export default class PlanList extends BaseCommand {
-  static override description = "List all plans";
-
-  static override examples = [
-    { description: "List all plans", command: "<%= config.bin %> <%= command.id %>" },
-    {
-      description: "Output as markdown",
-      command: "<%= config.bin %> <%= command.id %> --format markdown",
-    },
-  ];
-
-  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, markdown",
-      default: "default",
-      options: ["default", "markdown"],
-    }),
-  };
-
-  async run(): Promise<void> {
-    const { flags } = await this.parse(PlanList);
-    const ralphSettings = this.settings.settings.ralphSettings;
-    const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
-
-    const state = loadState(stateFile);
-
-    if (!state) {
-      this.log(pc.yellow(`No state file found at: ${stateFile}`));
-      return;
-    }
-
-    const plans = state.plans;
-
-    if (plans.length === 0) {
-      this.log(pc.yellow("No plans in state file."));
-      this.log(pc.dim('Use: tt ralph plan add "description"'));
-      return;
-    }
-
-    if (flags.format === "markdown") {
-      this.log(formatPlansAsMarkdown(plans));
-      return;
-    }
-
-    // Default format output - compact with truncation
-    const ready = plans.filter((p) => p.status === "ready");
-    const done = plans.filter((p) => p.status === "done");
-
-    const truncate = (s: string, len: number) => (s.length > len ? s.slice(0, len - 1) + "…" : s);
-    const termWidth = process.stdout.columns || 120;
-
-    // Summary header
-    this.log(
-      pc.bold("\nPlans: ") +
-        pc.green(`${done.length} done`) +
-        pc.dim(" / ") +
-        pc.yellow(`${ready.length} ready`),
-    );
-    this.log();
-
-    // Show ready plans first (these are actionable)
-    // Reserve ~10 chars for "  ○ #XX " prefix
-    const pathWidth = Math.max(40, termWidth - 12);
-
-    if (ready.length > 0) {
-      for (const plan of ready) {
-        const icon = pc.dim("○");
-        const id = pc.cyan(`#${plan.id}`);
-        const filePath = truncate(plan.planFilePath, pathWidth);
-        const errorSuffix = plan.error ? pc.red(` ⚠ ${truncate(plan.error, 30)}`) : "";
-        this.log(`  ${icon} ${id} ${filePath}${errorSuffix}`);
-      }
-    }
-
-    // Show done plans collapsed
-    if (done.length > 0) {
-      this.log(pc.dim(`  ─── ${done.length} completed ───`));
-      for (const plan of done) {
-        const filePath = truncate(plan.planFilePath, pathWidth - 5);
-        this.log(pc.dim(`  ✓ #${plan.id} ${filePath}`));
-      }
-    }
-    this.log();
-  }
-}

package/src/commands/ralph/plan/remove.ts

@@ -1,71 +0,0 @@
-import { Args, Flags } from "@oclif/core";
-import consola from "consola";
-import { colors } from "consola/utils";
-import { BaseCommand } from "../../base.js";
-import {
-  DEFAULT_STATE_FILE,
-  loadState,
-  saveState,
-  resolveRalphPath,
-} from "../../../lib/ralph/state.js";
-
-/**
- * Remove a ralph plan by ID
- */
-export default class PlanRemove extends BaseCommand {
-  static override description = "Remove a plan by ID";
-
-  static override examples = [
-    { description: "Remove plan #1", command: "<%= config.bin %> <%= command.id %> 1" },
-    {
-      description: "Remove from custom state file",
-      command: "<%= config.bin %> <%= command.id %> 5 --stateFile custom-state.json",
-    },
-  ];
-
-  static override args = {
-    id: Args.integer({
-      description: "Plan ID to remove",
-      required: true,
-    }),
-  };
-
-  static override flags = {
-    ...BaseCommand.baseFlags,
-    stateFile: Flags.string({
-      char: "s",
-      description: `State file path (default: ${DEFAULT_STATE_FILE})`,
-    }),
-  };
-
-  async run(): Promise<void> {
-    const { args, flags } = await this.parse(PlanRemove);
-    const ralphSettings = this.settings.settings.ralphSettings;
-    const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
-
-    const planId = args.id;
-
-    if (planId < 1) {
-      this.error("Invalid plan ID");
-    }
-
-    const state = loadState(stateFile);
-
-    if (!state) {
-      this.error(`No state file found at: ${stateFile}`);
-    }
-
-    const planIndex = state.plans.findIndex((p) => p.id === planId);
-
-    if (planIndex === -1) {
-      this.error(`Plan #${planId} not found. Use: tt ralph plan list`);
-    }
-
-    const removedPlan = state.plans[planIndex];
-    state.plans.splice(planIndex, 1);
-    saveState(state, stateFile);
-
-    consola.log(colors.green(`✓ Removed plan #${planId}: ${removedPlan.planFilePath}`));
-    consola.log(colors.dim(`Remaining plans: ${state.plans.length}`));
-  }
-}