@towles/tool 0.0.53 → 0.0.55

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

@@ -0,0 +1,63 @@
+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,
+  fileExists,
+  git,
+  log,
+  logStep,
+  resolveTemplate,
+  runClaude,
+} from "../utils.js";
+import type { IssueContext } from "../utils.js";
+
+export async function stepImplement(ctx: IssueContext): Promise<boolean> {
+  const completedPath = join(ctx.issueDir, ARTIFACTS.completedSummary);
+  const maxIterations = getConfig().maxImplementIterations;
+
+  if (fileExists(completedPath)) {
+    logStep(STEP_LABELS.implement, ctx, true);
+    return true;
+  }
+
+  logStep(STEP_LABELS.implement, ctx);
+
+  await git(["checkout", ctx.branch]);
+
+  for (let i = 1; i <= maxIterations; i++) {
+    log(`Implementation iteration ${i}/${maxIterations}`);
+
+    const tokens = buildTokens(ctx);
+    const promptFile = resolveTemplate(TEMPLATES.implement, tokens, ctx.issueDir);
+
+    const result = await runClaude({
+      promptFile,
+      permissionMode: "acceptEdits",
+      maxTurns: getConfig().maxTurns,
+    });
+
+    if (result.is_error) {
+      consola.error(`Implement iteration ${i} failed: ${result.result}`);
+      return false;
+    }
+
+    if (fileExists(completedPath)) {
+      log(`Implementation complete after ${i} iteration(s)`);
+      await commitArtifacts(
+        ctx,
+        `chore(auto-claude): implementation complete for ${ctx.repo}#${ctx.number}`,
+      );
+      return true;
+    }
+
+    log(`Iteration ${i} finished but completed-summary.md not yet created — tasks remain`);
+  }
+
+  consola.error(`Implementation did not complete after ${maxIterations} iterations`);
+  return false;
+}

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

@@ -0,0 +1,54 @@
+import { renameSync } 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,
+  fileExists,
+  log,
+  logStep,
+  resolveTemplate,
+  runClaude,
+} from "../utils.js";
+import type { IssueContext } from "../utils.js";
+
+export async function stepPlanAnnotations(ctx: IssueContext): Promise<boolean> {
+  const annotationsPath = join(ctx.issueDir, ARTIFACTS.planAnnotations);
+  const addressedPath = join(ctx.issueDir, ARTIFACTS.planAnnotationsAddressed);
+
+  if (!fileExists(annotationsPath)) {
+    return true;
+  }
+
+  if (fileExists(addressedPath)) {
+    logStep(STEP_LABELS.planAnnotations, ctx, true);
+    return true;
+  }
+
+  logStep(STEP_LABELS.planAnnotations, ctx);
+  log("Found plan-annotations.md — addressing reviewer notes");
+
+  const tokens = buildTokens(ctx);
+  const promptFile = resolveTemplate(TEMPLATES.planAnnotations, tokens, ctx.issueDir);
+
+  const result = await runClaude({
+    promptFile,
+    permissionMode: "acceptEdits",
+    maxTurns: getConfig().maxTurns,
+  });
+
+  if (result.is_error) {
+    consola.error(`Plan-Annotations step failed: ${result.result}`);
+    return false;
+  }
+
+  renameSync(annotationsPath, addressedPath);
+  log("Annotations addressed — renamed to plan-annotations-addressed.md");
+
+  await commitArtifacts(ctx, `chore(auto-claude): plan annotations for ${ctx.repo}#${ctx.number}`);
+  return true;
+}

package/src/lib/auto-claude/steps/plan-implementation.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 stepPlanImplementation(ctx: IssueContext): Promise<boolean> {
+  return runStepWithArtifact({
+    stepName: STEP_LABELS.planImplementation,
+    ctx,
+    artifactPath: join(ctx.issueDir, ARTIFACTS.planImplementation),
+    templateName: TEMPLATES.planImplementation,
+  });
+}

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");
+  });
+});