@towles/tool 0.0.18 → 0.0.41

package/src/commands/doctor.ts

@@ -0,0 +1,133 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { x } from "tinyexec";
+import pc from "picocolors";
+import { BaseCommand } from "./base.js";
+
+interface CheckResult {
+  name: string;
+  version: string | null;
+  ok: boolean;
+  warning?: string;
+}
+
+/**
+ * Check system dependencies and environment
+ */
+export default class Doctor extends BaseCommand {
+  static override description = "Check system dependencies and environment";
+
+  static override examples = ["<%= config.bin %> <%= command.id %>"];
+
+  async run(): Promise<void> {
+    await this.parse(Doctor);
+
+    this.log("Checking dependencies...\n");
+
+    const checks: CheckResult[] = await Promise.all([
+      this.checkCommand("git", ["--version"], /git version ([\d.]+)/),
+      this.checkCommand("gh", ["--version"], /gh version ([\d.]+)/),
+      this.checkCommand("node", ["--version"], /v?([\d.]+)/),
+      this.checkCommand("bun", ["--version"], /([\d.]+)/),
+    ]);
+
+    // Display results
+    for (const check of checks) {
+      const icon = check.ok ? pc.green("✓") : pc.red("✗");
+      const version = check.version ?? "not found";
+      this.log(`${icon} ${check.name}: ${version}`);
+      if (check.warning) {
+        this.log(`  ${pc.yellow("⚠")} ${check.warning}`);
+      }
+    }
+
+    // Check gh auth
+    this.log("");
+    const ghAuth = await this.checkGhAuth();
+    const authIcon = ghAuth.ok ? pc.green("✓") : pc.yellow("⚠");
+    this.log(`${authIcon} gh auth: ${ghAuth.ok ? "authenticated" : "not authenticated"}`);
+    if (!ghAuth.ok) {
+      this.log(`  ${pc.dim("Run: gh auth login")}`);
+    }
+
+    // Node version check
+    const nodeCheck = checks.find((c) => c.name === "node");
+    if (nodeCheck?.version) {
+      const major = Number.parseInt(nodeCheck.version.split(".")[0], 10);
+      if (major < 18) {
+        this.log("");
+        this.log(`${pc.yellow("⚠")} Node.js 18+ recommended (found ${nodeCheck.version})`);
+      }
+    }
+
+    // Check ralph files in .gitignore
+    this.log("");
+    const gitignoreCheck = this.checkRalphGitignore();
+    const gitignoreIcon = gitignoreCheck.ok ? pc.green("✓") : pc.yellow("⚠");
+    this.log(
+      `${gitignoreIcon} .gitignore: ${gitignoreCheck.ok ? "ralph-* excluded" : "ralph-* NOT excluded"}`,
+    );
+    if (!gitignoreCheck.ok) {
+      this.log(`  ${pc.dim('Add "ralph-*" to .gitignore to exclude local ralph state files')}`);
+    }
+
+    // Summary
+    const allOk = checks.every((c) => c.ok) && ghAuth.ok && gitignoreCheck.ok;
+    this.log("");
+    if (allOk) {
+      this.log(pc.green("All checks passed!"));
+    } else {
+      this.log(pc.yellow("Some checks failed. See above for details."));
+    }
+  }
+
+  private async checkCommand(
+    name: string,
+    args: string[],
+    versionPattern: RegExp,
+  ): Promise<CheckResult> {
+    try {
+      // tinyexec is safe - uses execFile internally, no shell injection risk
+      const result = await x(name, args);
+      const output = result.stdout + result.stderr;
+      const match = output.match(versionPattern);
+      return {
+        name,
+        version: match?.[1] ?? output.trim().slice(0, 20),
+        ok: true,
+      };
+    } catch {
+      return { name, version: null, ok: false };
+    }
+  }
+
+  private async checkGhAuth(): Promise<{ ok: boolean }> {
+    try {
+      // tinyexec is safe - uses execFile internally, no shell injection risk
+      const result = await x("gh", ["auth", "status"]);
+      return { ok: result.exitCode === 0 };
+    } catch {
+      return { ok: false };
+    }
+  }
+
+  private checkRalphGitignore(): { ok: boolean } {
+    const gitignorePath = path.join(process.cwd(), ".gitignore");
+    try {
+      if (!fs.existsSync(gitignorePath)) {
+        return { ok: false };
+      }
+      const content = fs.readFileSync(gitignorePath, "utf-8");
+      // Check for ralph-* pattern or specific ralph files
+      const hasRalphPattern = content.split("\n").some((line) => {
+        const trimmed = line.trim();
+        return (
+          trimmed === "ralph-*" || trimmed === "ralph-*.json" || trimmed === "ralph-state.json"
+        );
+      });
+      return { ok: hasRalphPattern };
+    } catch {
+      return { ok: false };
+    }
+  }
+}

package/src/commands/gh/branch-clean.ts

@@ -0,0 +1,110 @@
+import { Flags } from "@oclif/core";
+import { colors } from "consola/utils";
+import consola from "consola";
+import { x } from "tinyexec";
+
+import { BaseCommand } from "../base.js";
+
+/**
+ * Clean up merged branches
+ */
+export default class BranchClean extends BaseCommand {
+  static override description = "Delete local branches that have been merged into main";
+
+  static override examples = [
+    "<%= config.bin %> gh branch-clean",
+    "<%= config.bin %> gh branch-clean --dry-run",
+    "<%= config.bin %> gh branch-clean --force",
+    "<%= config.bin %> gh branch-clean --base develop",
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    force: Flags.boolean({
+      char: "f",
+      description: "Skip confirmation prompt",
+      default: false,
+    }),
+    "dry-run": Flags.boolean({
+      char: "d",
+      description: "Preview branches without deleting",
+      default: false,
+    }),
+    base: Flags.string({
+      char: "b",
+      description: "Base branch to check against",
+      default: "main",
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(BranchClean);
+    const baseBranch = flags.base;
+    const dryRun = flags["dry-run"];
+
+    // Get current branch
+    const currentResult = await x("git", ["branch", "--show-current"]);
+    const currentBranch = currentResult.stdout.trim();
+
+    // Get merged branches
+    const mergedResult = await x("git", ["branch", "--merged", baseBranch]);
+    const allMerged = mergedResult.stdout
+      .split("\n")
+      .map((b) => b.trim().replace(/^\* /, ""))
+      .filter((b) => b.length > 0);
+
+    // Exclude protected branches
+    const protectedBranches = ["main", "master", "develop", "dev", baseBranch, currentBranch];
+    const toDelete = allMerged.filter((b) => !protectedBranches.includes(b));
+
+    if (toDelete.length === 0) {
+      consola.info(colors.green("No merged branches to clean up"));
+      return;
+    }
+
+    consola.log(colors.cyan(`Found ${toDelete.length} merged branch(es):`));
+    for (const branch of toDelete) {
+      consola.log(`  - ${branch}`);
+    }
+
+    if (dryRun) {
+      consola.info(colors.yellow("Dry run - no branches deleted"));
+      return;
+    }
+
+    if (!flags.force) {
+      const answer = await consola.prompt(`Delete ${toDelete.length} branch(es)?`, {
+        type: "confirm",
+        initial: false,
+      });
+
+      if (!answer) {
+        consola.info(colors.dim("Canceled"));
+        return;
+      }
+    }
+
+    // Delete branches
+    let deleted = 0;
+    let failed = 0;
+
+    for (const branch of toDelete) {
+      try {
+        await x("git", ["branch", "-d", branch]);
+        consola.log(colors.green(`✓ Deleted ${branch}`));
+        deleted++;
+      } catch {
+        consola.log(colors.red(`✗ Failed to delete ${branch}`));
+        failed++;
+      }
+    }
+
+    consola.log("");
+    if (deleted > 0) {
+      consola.info(colors.green(`Deleted ${deleted} branch(es)`));
+    }
+    if (failed > 0) {
+      consola.warn(colors.yellow(`Failed to delete ${failed} branch(es)`));
+    }
+  }
+}

package/src/commands/gh/branch.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import type { Issue } from "../../utils/git/gh-cli-wrapper";
+import GhBranch from "./branch";
+
+const createBranchNameFromIssue = GhBranch.createBranchNameFromIssue;
+
+describe("gh-branch", () => {
+  describe("createBranchNameFromIssue", () => {
+    it("creates branch name from issue with basic title", () => {
+      const issue: Issue = {
+        number: 4,
+        title: "Long Issue Title - with a lot of words     and stuff ",
+        state: "open",
+        labels: [],
+      };
+      const branchName = createBranchNameFromIssue(issue);
+      expect(branchName).toBe("feature/4-long-issue-title-with-a-lot-of-words-and-stuff");
+    });
+
+    it("handles special characters in title", () => {
+      const issue: Issue = {
+        number: 123,
+        title: "Fix bug: @user reported $100 issue!",
+        state: "open",
+        labels: [],
+      };
+      const branchName = createBranchNameFromIssue(issue);
+      expect(branchName).toBe("feature/123-fix-bug-user-reported-100-issue");
+    });
+
+    it("handles title with only numbers", () => {
+      const issue: Issue = {
+        number: 42,
+        title: "123 456",
+        state: "open",
+        labels: [],
+      };
+      const branchName = createBranchNameFromIssue(issue);
+      expect(branchName).toBe("feature/42-123-456");
+    });
+
+    it("trims trailing dashes", () => {
+      const issue: Issue = {
+        number: 7,
+        title: "Update docs ---",
+        state: "open",
+        labels: [],
+      };
+      const branchName = createBranchNameFromIssue(issue);
+      expect(branchName).toBe("feature/7-update-docs");
+    });
+
+    it("handles unicode characters", () => {
+      const issue: Issue = {
+        number: 99,
+        title: "Fix für Übersetzung",
+        state: "open",
+        labels: [],
+      };
+      const branchName = createBranchNameFromIssue(issue);
+      expect(branchName).toBe("feature/99-fix-f-r-bersetzung");
+    });
+
+    it("handles empty-ish title", () => {
+      const issue: Issue = {
+        number: 1,
+        title: "   ",
+        state: "open",
+        labels: [],
+      };
+      const branchName = createBranchNameFromIssue(issue);
+      expect(branchName).toBe("feature/1-");
+    });
+
+    it("handles title with underscores", () => {
+      const issue: Issue = {
+        number: 50,
+        title: "snake_case_title",
+        state: "open",
+        labels: [],
+      };
+      const branchName = createBranchNameFromIssue(issue);
+      expect(branchName).toBe("feature/50-snake_case_title");
+    });
+
+    it("handles very long titles", () => {
+      const issue: Issue = {
+        number: 200,
+        title: "This is a very long issue title that goes on and on with many words",
+        state: "open",
+        labels: [],
+      };
+      const branchName = createBranchNameFromIssue(issue);
+      expect(branchName).toBe(
+        "feature/200-this-is-a-very-long-issue-title-that-goes-on-and-on-with-many-words",
+      );
+    });
+
+    it("collapses multiple consecutive dashes", () => {
+      const issue: Issue = {
+        number: 15,
+        title: "Fix   multiple    spaces",
+        state: "open",
+        labels: [],
+      };
+      const branchName = createBranchNameFromIssue(issue);
+      expect(branchName).toBe("feature/15-fix-multiple-spaces");
+    });
+
+    it("handles title with brackets and parentheses", () => {
+      const issue: Issue = {
+        number: 33,
+        title: "[Bug] Fix (critical) issue",
+        state: "open",
+        labels: [],
+      };
+      const branchName = createBranchNameFromIssue(issue);
+      expect(branchName).toBe("feature/33--bug-fix-critical-issue");
+    });
+  });
+
+  // TODO: Integration tests for githubBranchCommand require module mocking
+  // which works differently in bun:test vs vitest
+});

package/src/commands/gh/branch.ts

@@ -0,0 +1,132 @@
+import { Flags } from "@oclif/core";
+import prompts from "prompts";
+import type { Choice } from "prompts";
+import { colors } from "consola/utils";
+import { Fzf } from "fzf";
+import consola from "consola";
+
+import { BaseCommand } from "../base.js";
+import { getIssues, isGithubCliInstalled } from "../../utils/git/gh-cli-wrapper.js";
+import type { Issue } from "../../utils/git/gh-cli-wrapper.js";
+import { createBranch } from "../../utils/git/git-wrapper.js";
+import { getTerminalColumns, limitText, printWithHexColor } from "../../utils/render.js";
+
+/**
+ * Create a git branch from a GitHub issue
+ */
+export default class GhBranch extends BaseCommand {
+  static override description = "Create a git branch from a GitHub issue";
+
+  static override examples = [
+    "<%= config.bin %> gh branch",
+    "<%= config.bin %> gh branch --assignedToMe",
+    "<%= config.bin %> gh branch -a",
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    assignedToMe: Flags.boolean({
+      char: "a",
+      description: "Only show issues assigned to me",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(GhBranch);
+
+    // Check prerequisites
+    const cliInstalled = await isGithubCliInstalled();
+    if (!cliInstalled) {
+      consola.log("Github CLI not installed");
+      this.exit(1);
+    }
+
+    consola.log("Assigned to me:", flags.assignedToMe);
+
+    const currentIssues = await getIssues({ assignedToMe: flags.assignedToMe, cwd: process.cwd() });
+    if (currentIssues.length === 0) {
+      consola.log(colors.yellow("No issues found, check assignments"));
+      this.exit(1);
+    } else {
+      consola.log(colors.green(`${currentIssues.length} Issues found assigned to you`));
+    }
+
+    // Format table with nice labels
+    let lineMaxLength = getTerminalColumns();
+    const longestNumber = Math.max(...currentIssues.map((i) => i.number.toString().length));
+    const longestLabels = Math.max(
+      ...currentIssues.map((i) => i.labels.map((x) => x.name).join(", ").length),
+    );
+
+    lineMaxLength = lineMaxLength > 130 ? 130 : lineMaxLength;
+    const descriptionLength = lineMaxLength - longestNumber - longestLabels - 15;
+
+    const choices: Choice[] = currentIssues.map((i) => {
+      const labelText = i.labels
+        .map((l) => printWithHexColor({ msg: l.name, hex: l.color }))
+        .join(", ");
+      const labelTextNoColor = i.labels.map((l) => l.name).join(", ");
+      const labelStartpad = longestLabels - labelTextNoColor.length;
+      return {
+        title: i.number.toString(),
+        value: i.number,
+        description: `${limitText(i.title, descriptionLength).padEnd(descriptionLength)} ${"".padStart(labelStartpad)}${labelText}`,
+      } as Choice;
+    });
+    choices.push({ title: "Cancel", value: "cancel" });
+
+    const fzf = new Fzf(choices, {
+      selector: (item) => `${item.value} ${item.description}`,
+      casing: "case-insensitive",
+    });
+
+    try {
+      const result = await prompts(
+        {
+          name: "issueNumber",
+          message: "Github issue to create branch for:",
+          type: "autocomplete",
+          choices,
+          async suggest(input: string, choices: Choice[]) {
+            consola.log(input);
+            const results = fzf.find(input);
+            return results.map((r) => choices.find((c) => c.value === r.item.value));
+          },
+        },
+        {
+          onCancel: () => {
+            consola.info(colors.dim("Canceled"));
+            this.exit(0);
+          },
+        },
+      );
+
+      if (result.issueNumber === "cancel") {
+        consola.log(colors.dim("Canceled"));
+        this.exit(0);
+      }
+
+      const selectedIssue = currentIssues.find((i) => i.number === result.issueNumber)!;
+      consola.log(
+        `Selected issue ${colors.green(selectedIssue.number)} - ${colors.green(selectedIssue.title)}`,
+      );
+
+      const branchName = GhBranch.createBranchNameFromIssue(selectedIssue);
+      createBranch({ branchName });
+    } catch {
+      this.exit(1);
+    }
+  }
+
+  static createBranchNameFromIssue(selectedIssue: Issue): string {
+    let slug = selectedIssue.title.toLowerCase();
+    slug = slug.trim();
+    slug = slug.replaceAll(" ", "-");
+    slug = slug.replace(/[^0-9a-zA-Z_-]/g, "-");
+    slug = slug.replace(/-+/g, "-");
+    slug = slug.replace(/-+$/, "");
+
+    return `feature/${selectedIssue.number}-${slug}`;
+  }
+}

package/src/commands/gh/pr.ts

@@ -0,0 +1,168 @@
+import { Flags } from "@oclif/core";
+import { x } from "tinyexec";
+import consola from "consola";
+import { colors } from "consola/utils";
+
+import { BaseCommand } from "../base.js";
+import { isGithubCliInstalled } from "../../utils/git/gh-cli-wrapper.js";
+
+/**
+ * Create a pull request from the current branch
+ * Note: Uses tinyexec which is safe (execFile-based, no shell injection)
+ */
+export default class Pr extends BaseCommand {
+  static override description = "Create a pull request from the current branch";
+
+  static override examples = [
+    "<%= config.bin %> gh pr",
+    "<%= config.bin %> gh pr --draft",
+    "<%= config.bin %> gh pr --base develop",
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    draft: Flags.boolean({
+      description: "Create as draft PR",
+      default: false,
+    }),
+    base: Flags.string({
+      char: "b",
+      description: "Base branch for the PR",
+      default: "main",
+    }),
+    yes: Flags.boolean({
+      char: "y",
+      description: "Skip confirmation prompt",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(Pr);
+
+    // Check prerequisites
+    const cliInstalled = await isGithubCliInstalled();
+    if (!cliInstalled) {
+      consola.error("GitHub CLI not installed");
+      this.exit(1);
+    }
+
+    // Get current branch
+    const branchResult = await x("git", ["branch", "--show-current"]);
+    const currentBranch = branchResult.stdout.trim();
+
+    if (!currentBranch) {
+      consola.error("Not on a branch (detached HEAD?)");
+      this.exit(1);
+    }
+
+    if (currentBranch === flags.base) {
+      consola.error(`Already on base branch ${flags.base}`);
+      this.exit(1);
+    }
+
+    consola.info(`Current branch: ${colors.cyan(currentBranch)}`);
+    consola.info(`Base branch: ${colors.cyan(flags.base)}`);
+
+    // Get commits between base and current branch
+    const logResult = await x("git", ["log", `${flags.base}..HEAD`, "--pretty=format:%s"]);
+
+    const commits = logResult.stdout.trim().split("\n").filter(Boolean);
+
+    if (commits.length === 0) {
+      consola.error(`No commits between ${flags.base} and ${currentBranch}`);
+      this.exit(1);
+    }
+
+    consola.info(`Found ${colors.green(commits.length.toString())} commits`);
+
+    // Generate PR title and body
+    const { title, body } = this.generatePrContent(currentBranch, commits);
+
+    consola.box({
+      title: "PR Preview",
+      message: `Title: ${title}\n\n${body}`,
+    });
+
+    // Confirm unless --yes
+    if (!flags.yes) {
+      const confirmed = await consola.prompt("Create this PR?", {
+        type: "confirm",
+        initial: true,
+      });
+
+      if (!confirmed) {
+        consola.info(colors.dim("Canceled"));
+        this.exit(0);
+      }
+    }
+
+    // Push branch if needed
+    const statusResult = await x("git", ["status", "-sb"]);
+    const needsPush = !statusResult.stdout.includes("origin/");
+
+    if (needsPush) {
+      consola.info("Pushing branch to remote...");
+      await x("git", ["push", "-u", "origin", currentBranch]);
+    }
+
+    // Create PR
+    const prArgs = ["pr", "create", "--title", title, "--body", body, "--base", flags.base];
+
+    if (flags.draft) {
+      prArgs.push("--draft");
+    }
+
+    const prResult = await x("gh", prArgs);
+    const prUrl = prResult.stdout.trim();
+
+    consola.success(`PR created: ${colors.cyan(prUrl)}`);
+  }
+
+  private generatePrContent(branch: string, commits: string[]): { title: string; body: string } {
+    // Extract issue number from branch name if present (e.g., feature/123-some-feature)
+    const issueMatch = branch.match(/(\d+)/);
+    const issueNumber = issueMatch ? issueMatch[1] : null;
+
+    // Generate title from first commit or branch name
+    let title: string;
+    if (commits.length === 1) {
+      title = commits[0];
+    } else {
+      // Use branch name, cleaned up
+      title = branch
+        .replace(/^(feature|fix|bugfix|hotfix|chore|refactor)\//, "")
+        .replace(/^\d+-/, "")
+        .replace(/-/g, " ")
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+    }
+
+    // Generate body
+    const lines: string[] = ["## Summary", ""];
+
+    if (commits.length === 1) {
+      lines.push(`- ${commits[0]}`);
+    } else {
+      for (const commit of commits.slice(0, 10)) {
+        lines.push(`- ${commit}`);
+      }
+      if (commits.length > 10) {
+        lines.push(`- ... and ${commits.length - 10} more commits`);
+      }
+    }
+
+    lines.push("");
+
+    if (issueNumber) {
+      lines.push(`Closes #${issueNumber}`);
+      lines.push("");
+    }
+
+    lines.push("## Test plan");
+    lines.push("");
+    lines.push("- [ ] Tests pass");
+    lines.push("- [ ] Manual testing");
+
+    return { title, body: lines.join("\n") };
+  }
+}