@towles/tool 0.0.54 → 0.0.56

package/src/lib/auto-claude/steps/plan.ts

@@ -0,0 +1,14 @@
+import { join } from "node:path";
+
+import { ARTIFACTS, STEP_LABELS, TEMPLATES } from "../prompt-templates/index.js";
+import { runStepWithArtifact } from "../utils.js";
+import type { IssueContext } from "../utils.js";
+
+export async function stepPlan(ctx: IssueContext): Promise<boolean> {
+  return runStepWithArtifact({
+    stepName: STEP_LABELS.plan,
+    ctx,
+    artifactPath: join(ctx.issueDir, ARTIFACTS.plan),
+    templateName: TEMPLATES.plan,
+  });
+}

package/src/lib/auto-claude/steps/refresh.ts

@@ -0,0 +1,114 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+
+import consola from "consola";
+
+import { getConfig } from "../config.js";
+import { ARTIFACTS, STEP_LABELS, TEMPLATES } from "../prompt-templates/index.js";
+import {
+  buildTokens,
+  commitArtifacts,
+  execSafe,
+  fileExists,
+  git,
+  log,
+  logStep,
+  resolveTemplate,
+  runClaude,
+} from "../utils.js";
+import type { IssueContext } from "../utils.js";
+
+export async function stepRefresh(ctx: IssueContext): Promise<boolean> {
+  logStep(STEP_LABELS.refresh, ctx);
+  const { mainBranch, remote } = getConfig();
+
+  const branchList = await git(["branch", "--list", ctx.branch]);
+  if (!branchList.includes(ctx.branch.split("/").pop()!)) {
+    try {
+      await git(["fetch", remote, ctx.branch]);
+      await git(["checkout", ctx.branch]);
+    } catch {
+      log(`Branch ${ctx.branch} does not exist locally or remotely.`);
+      return false;
+    }
+  }
+
+  await git(["checkout", mainBranch]);
+  await git(["pull", remote, mainBranch]);
+  await git(["checkout", ctx.branch]);
+
+  if (await isBranchUpToDate(mainBranch)) {
+    log(`Branch is already up-to-date with ${mainBranch}.`);
+  } else {
+    await rebaseOrMerge(mainBranch);
+  }
+
+  const tokens = buildTokens(ctx);
+  const promptFile = resolveTemplate(TEMPLATES.refresh, tokens, ctx.issueDir);
+  const result = await runClaude({
+    promptFile,
+    permissionMode: "acceptEdits",
+    maxTurns: getConfig().maxTurns,
+  });
+
+  if (result.is_error) {
+    consola.error(`Refresh step failed: ${result.result}`);
+    await git(["checkout", mainBranch]).catch(() => {});
+    return false;
+  }
+
+  await commitArtifacts(ctx, `chore(auto-claude): refresh for ${ctx.repo}#${ctx.number}`);
+  await invalidateStaleArtifacts(ctx);
+
+  await git(["push", "--force-with-lease", "-u", remote, ctx.branch]);
+  await git(["checkout", mainBranch]).catch(() => {});
+
+  return true;
+}
+
+async function isBranchUpToDate(mainBranch: string): Promise<boolean> {
+  try {
+    await git(["merge-base", "--is-ancestor", mainBranch, "HEAD"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function rebaseOrMerge(mainBranch: string): Promise<void> {
+  try {
+    await git(["rebase", mainBranch]);
+  } catch {
+    await git(["rebase", "--abort"]).catch(() => {});
+    try {
+      await git(["merge", mainBranch, "--no-edit"]);
+    } catch {
+      const conflicts = await execSafe("git", ["diff", "--name-only", "--diff-filter=U"]);
+      if (conflicts.stdout.length > 0) {
+        await git(["merge", "--abort"]);
+        throw new Error(`Merge conflicts detected in: ${conflicts.stdout}`);
+      }
+      await git(["add", "."]);
+      await git(["commit", "--no-edit"]);
+    }
+  }
+}
+
+async function invalidateStaleArtifacts(ctx: IssueContext): Promise<void> {
+  const paths = [
+    join(ctx.issueDir, ARTIFACTS.review),
+    join(ctx.issueDir, ARTIFACTS.completedSummary),
+  ];
+
+  const removed = paths.filter((p) => {
+    if (fileExists(p)) {
+      rmSync(p);
+      return true;
+    }
+    return false;
+  });
+
+  if (removed.length > 0) {
+    await commitArtifacts(ctx, "chore(auto-claude): invalidate stale artifacts after refresh");
+  }
+}

package/src/lib/auto-claude/steps/remove-label.ts

@@ -0,0 +1,22 @@
+import { getConfig } from "../config.js";
+import { STEP_LABELS } from "../prompt-templates/index.js";
+import { ghRaw, log, logStep } from "../utils.js";
+import type { IssueContext } from "../utils.js";
+
+export async function stepRemoveLabel(ctx: IssueContext): Promise<boolean> {
+  logStep(STEP_LABELS.removeLabel, ctx);
+
+  const cfg = getConfig();
+  await ghRaw([
+    "issue",
+    "edit",
+    String(ctx.number),
+    "--repo",
+    ctx.repo,
+    "--remove-label",
+    cfg.triggerLabel,
+  ]);
+
+  log(`Removed "${cfg.triggerLabel}" label from ${ctx.repo}#${ctx.number}`);
+  return true;
+}

package/src/lib/auto-claude/steps/research.ts

@@ -0,0 +1,21 @@
+import { join } from "node:path";
+
+import { ARTIFACTS, STEP_LABELS, TEMPLATES } from "../prompt-templates/index.js";
+import { ensureBranch, fileExists, readFile, runStepWithArtifact } from "../utils.js";
+import type { IssueContext } from "../utils.js";
+
+function isValidResearch(path: string): boolean {
+  return fileExists(path) && readFile(path).length > 200;
+}
+
+export async function stepResearch(ctx: IssueContext): Promise<boolean> {
+  await ensureBranch(ctx.branch);
+
+  return runStepWithArtifact({
+    stepName: STEP_LABELS.research,
+    ctx,
+    artifactPath: join(ctx.issueDir, ARTIFACTS.research),
+    templateName: TEMPLATES.research,
+    artifactValidator: isValidResearch,
+  });
+}

package/src/lib/auto-claude/steps/review.ts

@@ -0,0 +1,14 @@
+import { join } from "node:path";
+
+import { ARTIFACTS, STEP_LABELS, TEMPLATES } from "../prompt-templates/index.js";
+import { runStepWithArtifact } from "../utils.js";
+import type { IssueContext } from "../utils.js";
+
+export async function stepReview(ctx: IssueContext): Promise<boolean> {
+  return runStepWithArtifact({
+    stepName: STEP_LABELS.review,
+    ctx,
+    artifactPath: join(ctx.issueDir, ARTIFACTS.review),
+    templateName: TEMPLATES.review,
+  });
+}

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

@@ -0,0 +1,136 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+
+import { initConfig } from "./config";
+import {
+  buildContextFromArtifacts,
+  buildIssueContext,
+  buildTokens,
+  resolveTemplate,
+} from "./utils";
+
+// Initialize config once for tests that need getConfig()
+beforeAll(async () => {
+  await initConfig({ repo: "test/repo", mainBranch: "main" });
+});
+
+describe("buildIssueContext", () => {
+  it("should build context with correct fields", () => {
+    const ctx = buildIssueContext(
+      { number: 42, title: "Fix the bug", body: "Something is broken" },
+      "owner/repo",
+      "src/",
+    );
+
+    expect(ctx.number).toBe(42);
+    expect(ctx.title).toBe("Fix the bug");
+    expect(ctx.body).toBe("Something is broken");
+    expect(ctx.repo).toBe("owner/repo");
+    expect(ctx.scopePath).toBe("src/");
+    expect(ctx.issueDirRel).toBe(".auto-claude/issue-42");
+    expect(ctx.issueDir).toContain(".auto-claude/issue-42");
+    expect(ctx.branch).toBe("auto-claude/issue-42");
+  });
+
+  it("should derive branch name from issue number", () => {
+    const ctx = buildIssueContext({ number: 7, title: "t", body: "" }, "r", ".");
+    expect(ctx.branch).toBe("auto-claude/issue-7");
+  });
+});
+
+describe("buildTokens", () => {
+  it("should produce expected token keys", () => {
+    const ctx = buildIssueContext({ number: 1, title: "t", body: "" }, "test/repo", "lib/");
+    const tokens = buildTokens(ctx);
+
+    expect(tokens.SCOPE_PATH).toBe("lib/");
+    expect(tokens.ISSUE_DIR).toBe(".auto-claude/issue-1");
+    expect(tokens.MAIN_BRANCH).toBe("main");
+  });
+});
+
+describe("resolveTemplate", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "auto-claude-test-"));
+  });
+
+  afterAll(() => {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("should replace token placeholders and write resolved file", () => {
+    // Use an actual template from the templates dir
+    const tokens = { SCOPE_PATH: "src/", ISSUE_DIR: ".auto-claude/issue-99", MAIN_BRANCH: "main" };
+    const issueDir = join(tmpDir, "issue-99");
+    mkdirSync(issueDir, { recursive: true });
+
+    const result = resolveTemplate("01-prompt-research.md", tokens, issueDir);
+
+    // Should return a relative path
+    expect(result).toContain("issue-99");
+    expect(result).toContain("01-prompt-research.md");
+
+    // Resolved file should exist and have tokens replaced
+    const content = readFileSync(join(issueDir, "01-prompt-research.md"), "utf-8");
+    expect(content).toContain("src/");
+    expect(content).toContain(".auto-claude/issue-99");
+    expect(content).not.toContain("{{SCOPE_PATH}}");
+    expect(content).not.toContain("{{ISSUE_DIR}}");
+  });
+});
+
+describe("buildContextFromArtifacts", () => {
+  let tmpDir: string;
+  let originalCwd: string;
+
+  beforeAll(() => {
+    originalCwd = process.cwd();
+    tmpDir = mkdtempSync(join(tmpdir(), "auto-claude-artifacts-"));
+    process.chdir(tmpDir);
+  });
+
+  afterAll(() => {
+    process.chdir(originalCwd);
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("should throw when no artifacts exist", () => {
+    expect(() => buildContextFromArtifacts(999)).toThrow("No artifacts found");
+  });
+
+  it("should parse title and body from initial-ramblings.md", async () => {
+    // Re-init config in the temp dir context
+    await initConfig({ repo: "test/repo", mainBranch: "main" });
+
+    const issueDir = join(tmpDir, ".auto-claude/issue-77");
+    mkdirSync(issueDir, { recursive: true });
+    writeFileSync(
+      join(issueDir, "initial-ramblings.md"),
+      "# My Great Feature\n\n> test/repo#77\n\nThis is the body of the issue.\nWith multiple lines.",
+    );
+
+    const ctx = buildContextFromArtifacts(77);
+
+    expect(ctx.number).toBe(77);
+    expect(ctx.title).toBe("My Great Feature");
+    expect(ctx.body).toContain("This is the body of the issue.");
+    expect(ctx.repo).toBe("test/repo");
+    expect(ctx.branch).toBe("auto-claude/issue-77");
+  });
+
+  it("should fallback title when heading is missing", async () => {
+    await initConfig({ repo: "test/repo", mainBranch: "main" });
+
+    const issueDir = join(tmpDir, ".auto-claude/issue-88");
+    mkdirSync(issueDir, { recursive: true });
+    writeFileSync(join(issueDir, "initial-ramblings.md"), "No heading here\n\njust text");
+
+    const ctx = buildContextFromArtifacts(88);
+    expect(ctx.title).toBe("Issue #88");
+  });
+});

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

@@ -0,0 +1,347 @@
+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 pc from "picocolors";
+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.num_turns} turns`);
+        if (parsed.result) {
+          consola.log(parsed.result);
+        }
+        return parsed;
+      } catch {
+        consola.warn("Done — failed to parse Claude output");
+        if (stdout.trim()) {
+          consola.log(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 logBanner(label: string, width = 60): void {
+  const inner = `  ${label}  `;
+  const totalDashes = Math.max(0, width - inner.length - 2);
+  const left = Math.ceil(totalDashes / 2);
+  const right = Math.floor(totalDashes / 2);
+  const dashes = pc.cyan;
+  consola.log(
+    `${dashes("#" + "-".repeat(left))}${pc.bold(inner)}${dashes("-".repeat(right) + "#")}`,
+  );
+}
+
+export function logStep(step: string, ctx: IssueContext, skipped = false): void {
+  const tag = skipped ? pc.yellow("SKIP") : pc.green("RUN");
+  logBanner(`[${tag}] ${step}`);
+  consola.log(pc.dim(`${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;
+}