pf 0.0.1 → 0.0.4

package/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: npm publish

package/.husky/pre-push

@@ -0,0 +1 @@
+node scripts/check-version.ts

package/README.md

@@ -0,0 +1,57 @@
+# pf
+
+A humane utility for git worktrees.
+
+## Install
+
+```
+npm i -g pf
+```
+
+## Usage
+
+```
+pf <command> [options]
+
+Commands:
+  new [name]   Create a branch and worktree with the specified name (default: "pf-[hash]")
+  open <name>  Open a worktree in a subshell
+  ls           List all tracked worktrees
+  rm <name>    Remove a worktree
+
+Options:
+  --help, -h       Show help
+  --version, -v    Show version
+```
+
+## Why `pf`?
+
+In agentic development, you often want to spin up isolated workspaces for specific tasks—without stashing or committing your current changes. pf makes this effortless.
+
+Create a new worktree for a task:
+
+```
+$ pf new add-login-button
+```
+
+This creates a branch and worktree, then drops you into a subshell. Open it in your editor or point an AI coding agent at it. Your changes are completely independent of any other work on your machine.
+
+When you're done, push to GitHub and create a PR:
+
+```
+$ git push -u origin add-login-button
+```
+
+Or merge directly back into main:
+
+```
+$ git checkout main && git merge add-login-button
+```
+
+Then just `exit` to pop out of the worktree and back to your main repo. Clean up when you're done:
+
+```
+$ pf rm add-login-button
+```
+
+Use `pf ls` to see your active worktrees, and `pf open <name>` to return to one later.

package/build.ts

@@ -0,0 +1,24 @@
+import * as esbuild from "esbuild";
+
+const watch = process.argv.includes("--watch");
+
+const options: esbuild.BuildOptions = {
+  entryPoints: ["index.ts"],
+  bundle: true,
+  platform: "node",
+  target: "node24",
+  format: "esm",
+  outfile: "dist/index.js",
+  banner: {
+    js: "#!/usr/bin/env node",
+  },
+};
+
+if (watch) {
+  const ctx = await esbuild.context(options);
+  await ctx.watch();
+  console.log("Watching...");
+} else {
+  await esbuild.build(options);
+  console.log("Built dist/index.js");
+}

package/commands/completion.ts

@@ -0,0 +1,197 @@
+import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from "fs";
+import { dirname, join } from "path";
+import { homedir } from "os";
+import { createInterface } from "readline";
+import { success, dim } from "../utils.js";
+
+function detectShell(): string | null {
+  const shell = process.env.SHELL || "";
+  if (shell.includes("zsh")) return "zsh";
+  if (shell.includes("bash")) return "bash";
+  if (shell.includes("fish")) return "fish";
+  return null;
+}
+
+function getCompletionPath(shell: string): string {
+  const home = homedir();
+  switch (shell) {
+    case "zsh":
+      return join(home, ".zsh/completions/_pf");
+    case "bash":
+      return join(home, ".bash_completion.d/pf");
+    case "fish":
+      return join(home, ".config/fish/completions/pf.fish");
+    default:
+      return "";
+  }
+}
+
+function getRcConfig(shell: string): { path: string; lines: string[] } | null {
+  const home = homedir();
+  switch (shell) {
+    case "zsh":
+      return {
+        path: join(home, ".zshrc"),
+        lines: [
+          'fpath=(~/.zsh/completions $fpath)',
+          'autoload -Uz compinit && compinit',
+        ],
+      };
+    case "bash":
+      return {
+        path: join(home, ".bashrc"),
+        lines: ['source ~/.bash_completion.d/pf'],
+      };
+    case "fish":
+      return null; // Fish auto-loads from completions dir
+    default:
+      return null;
+  }
+}
+
+function fileContains(path: string, substr: string): boolean {
+  try {
+    const data = readFileSync(path, "utf-8");
+    return data.includes(substr);
+  } catch {
+    return false;
+  }
+}
+
+function getCompletionScript(shell: string): string {
+  switch (shell) {
+    case "zsh":
+      return `#compdef pf
+
+_pf() {
+  local -a commands worktrees
+  commands=(
+    'new:Create a new worktree with a branch'
+    'open:Open a worktree'
+    'ls:List all tracked worktrees'
+    'rm:Remove a worktree'
+    'completion:Install shell completions'
+  )
+
+  _arguments -C \\
+    "1: :->command" \\
+    "*::arg:->args"
+
+  case "$state" in
+    command)
+      _describe 'command' commands
+      ;;
+    args)
+      case "$words[1]" in
+        open|rm)
+          worktrees=(\${(f)"\$(pf ls --plain 2>/dev/null | cut -f1)"})
+          _describe 'worktree' worktrees
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_pf "$@"
+`;
+    case "bash":
+      return `_pf() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  local commands="new open ls rm completion"
+
+  case "$prev" in
+    open|rm)
+      local worktrees="\$(pf ls --plain 2>/dev/null | cut -f1)"
+      COMPREPLY=($(compgen -W "$worktrees" -- "$cur"))
+      return
+      ;;
+  esac
+
+  COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+}
+complete -F _pf pf
+`;
+    case "fish":
+      return `complete -c pf -n "__fish_use_subcommand" -a new -d "Create a new worktree with a branch"
+complete -c pf -n "__fish_use_subcommand" -a open -d "Open a worktree"
+complete -c pf -n "__fish_use_subcommand" -a ls -d "List all tracked worktrees"
+complete -c pf -n "__fish_use_subcommand" -a rm -d "Remove a worktree"
+complete -c pf -n "__fish_use_subcommand" -a completion -d "Install shell completions"
+complete -c pf -n "__fish_seen_subcommand_from open rm" -a "(pf ls --plain 2>/dev/null | cut -f1)" -d "worktree"
+`;
+    default:
+      return "";
+  }
+}
+
+async function prompt(question: string): Promise<string> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+export async function completionCommand(shell?: string): Promise<void> {
+  // If shell specified, output script to stdout
+  if (shell) {
+    const script = getCompletionScript(shell);
+    if (!script) {
+      console.error(`Unknown shell: ${shell}`);
+      process.exit(1);
+    }
+    console.log(script);
+    return;
+  }
+
+  // Interactive mode
+  const detectedShell = detectShell();
+  if (!detectedShell) {
+    console.error("Could not detect shell. Run: pf completion [bash|zsh|fish]");
+    process.exit(1);
+  }
+
+  const completionPath = getCompletionPath(detectedShell);
+  const rcConfig = getRcConfig(detectedShell);
+
+  let desc = `1. Write completion script to ${completionPath}\n`;
+  if (rcConfig && !fileContains(rcConfig.path, rcConfig.lines[0])) {
+    desc += `2. Add to ${rcConfig.path}:\n`;
+    for (const line of rcConfig.lines) {
+      desc += `   ${line}\n`;
+    }
+  }
+
+  console.log(`Install ${detectedShell} completions? This will:`);
+  console.log(desc);
+  const response = await prompt("Proceed? [y/N] ");
+
+  if (response.toLowerCase() !== "y" && response.toLowerCase() !== "yes") {
+    console.log("Canceled.");
+    return;
+  }
+
+  // Write completion script
+  mkdirSync(dirname(completionPath), { recursive: true });
+  writeFileSync(completionPath, getCompletionScript(detectedShell));
+  console.log(success("✓"), "Wrote", completionPath);
+
+  // Update rc file if needed
+  if (rcConfig && !fileContains(rcConfig.path, rcConfig.lines[0])) {
+    appendFileSync(rcConfig.path, "\n# pf completions\n" + rcConfig.lines.join("\n") + "\n");
+    console.log(success("✓"), "Updated", rcConfig.path);
+  }
+
+  console.log();
+  if (rcConfig) {
+    console.log("Restart your shell or run:", dim(`source ${rcConfig.path}`));
+  } else {
+    console.log("Restart your shell to enable completions.");
+  }
+}

package/commands/ls.ts

@@ -0,0 +1,49 @@
+import { resolve } from "path";
+import Table from "cli-table3";
+import pc from "picocolors";
+import { loadStore } from "../store.js";
+import { getWorktreeBranch, getWorktreeStatus } from "../utils.js";
+
+export function lsCommand(plain: boolean = false): void {
+  const store = loadStore();
+
+  if (store.worktrees.length === 0) {
+    console.log("No worktrees. Use 'pf new <name>' to create one.");
+    return;
+  }
+
+  // Detect current worktree
+  const cwd = process.cwd();
+  let currentWorktree = "";
+  for (const wt of store.worktrees) {
+    const absPath = resolve(wt.path);
+    if (cwd.startsWith(absPath)) {
+      currentWorktree = wt.name;
+      break;
+    }
+  }
+
+  if (plain) {
+    for (const wt of store.worktrees) {
+      const branch = getWorktreeBranch(wt.path);
+      const status = getWorktreeStatus(wt.path);
+      console.log(`${wt.name}\t${branch}\t${status}`);
+    }
+    return;
+  }
+
+  const table = new Table({
+    head: ["name", "branch", "git status"],
+    style: { head: [], border: [] },
+    chars: { mid: "", "left-mid": "", "mid-mid": "", "right-mid": "" },
+  });
+
+  for (const wt of store.worktrees) {
+    const branch = getWorktreeBranch(wt.path);
+    const status = getWorktreeStatus(wt.path);
+    const name = wt.name === currentWorktree ? `${pc.green("*")}${wt.name}` : wt.name;
+    table.push([name, branch, status]);
+  }
+
+  console.log(table.toString());
+}

package/commands/new.ts

@@ -0,0 +1,82 @@
+import { basename, dirname, join } from "path";
+import { mkdirSync } from "fs";
+import {
+  loadStore,
+  saveStore,
+  addWorktree,
+  findWorktree,
+  getGitRoot,
+  getGitCommonDir,
+} from "../store.js";
+import {
+  branchExists,
+  isInsideWorktree,
+  getCurrentBranch,
+  createWorktree,
+  generateName,
+  spawnShell,
+  success,
+  bold,
+  dim,
+} from "../utils.js";
+
+export function newCommand(name?: string): void {
+  const worktreeName = name ?? generateName();
+
+  // Check if inside a worktree
+  if (isInsideWorktree()) {
+    console.error("Error: You are inside a pf worktree.");
+    console.error("");
+    console.error("Each time you run 'pf new' or 'pf open', pf starts a subshell in the");
+    console.error("worktree directory. To keep subshells shallow and avoid nesting, pf");
+    console.error("requires you to return to the main repo before opening another worktree.");
+    console.error("");
+    console.error("To exit the current worktree:");
+    console.error("  exit");
+    console.error("");
+    console.error("Then re-run:");
+    console.error(`  pf new ${worktreeName}`);
+    process.exit(1);
+  }
+
+  // Check if branch already exists
+  if (branchExists(worktreeName)) {
+    console.error(`Error: branch '${worktreeName}' already exists`);
+    process.exit(1);
+  }
+
+  // Check if worktree already exists in store
+  const store = loadStore();
+  if (findWorktree(store, worktreeName)) {
+    console.error(`Error: worktree '${worktreeName}' already exists - use 'pf open ${worktreeName}'`);
+    process.exit(1);
+  }
+
+  const baseBranch = getCurrentBranch();
+  const gitRoot = getGitRoot();
+  const gitDir = getGitCommonDir();
+  const repoName = basename(gitRoot);
+  const worktreePath = join(gitDir, "pf", "worktrees", worktreeName, repoName);
+
+  // Create directory
+  mkdirSync(dirname(worktreePath), { recursive: true });
+
+  // Create worktree
+  createWorktree(worktreeName, worktreePath);
+
+  // Track in store
+  addWorktree(store, worktreeName, worktreePath);
+  saveStore(store);
+
+  console.log();
+  console.log(success(bold(worktreeName)), dim(`(from ${baseBranch})`));
+  console.log(dim("  Subshell started. Type 'exit' to return."));
+  console.log();
+
+  // Spawn shell
+  spawnShell(worktreePath);
+
+  console.log();
+  console.log(dim("  Back in main worktree"));
+  console.log();
+}

package/commands/open.ts

@@ -0,0 +1,61 @@
+import { existsSync } from "fs";
+import { loadStore, findWorktree } from "../store.js";
+import {
+  isInsideWorktree,
+  hasUncommittedChanges,
+  getWorktreeBranch,
+  spawnShell,
+  success,
+  bold,
+  dim,
+} from "../utils.js";
+
+export function openCommand(name: string): void {
+  // Check if inside a worktree
+  if (isInsideWorktree()) {
+    console.error("Error: You are inside a pf worktree.");
+    console.error("");
+    console.error("Each time you run 'pf new' or 'pf open', pf starts a subshell in the");
+    console.error("worktree directory. To keep subshells shallow and avoid nesting, pf");
+    console.error("requires you to return to the main repo before opening another worktree.");
+    console.error("");
+    console.error("To exit the current worktree:");
+    console.error("  exit");
+    console.error("");
+    console.error("Then re-run:");
+    console.error(`  pf open ${name}`);
+    process.exit(1);
+  }
+
+  // Check for uncommitted changes
+  if (hasUncommittedChanges()) {
+    console.error("Error: uncommitted changes in current worktree - commit or stash first");
+    process.exit(1);
+  }
+
+  const store = loadStore();
+  const wt = findWorktree(store, name);
+
+  if (!wt) {
+    console.error(`Error: worktree '${name}' not found`);
+    process.exit(1);
+  }
+
+  if (!existsSync(wt.path)) {
+    console.error(`Error: worktree directory does not exist: ${wt.path}`);
+    process.exit(1);
+  }
+
+  const branch = getWorktreeBranch(wt.path);
+
+  console.log();
+  console.log(success(bold(name)), dim(`(${branch})`));
+  console.log(dim("  Subshell started. Type 'exit' to return."));
+  console.log();
+
+  spawnShell(wt.path);
+
+  console.log();
+  console.log(dim("  Back in main worktree"));
+  console.log();
+}

package/commands/rm.ts

@@ -0,0 +1,61 @@
+import { resolve } from "path";
+import { loadStore, saveStore, findWorktree, removeWorktree as removeFromStore } from "../store.js";
+import {
+  getWorktreeBranch,
+  removeWorktree,
+  pruneWorktrees,
+  deleteBranch,
+  success,
+  bold,
+  dim,
+} from "../utils.js";
+
+export function rmCommand(name: string, deleteBranchFlag: boolean = false): void {
+  const store = loadStore();
+  const wt = findWorktree(store, name);
+
+  if (!wt) {
+    console.error(`Error: worktree '${name}' not found`);
+    process.exit(1);
+  }
+
+  // Check if we're currently in this worktree
+  const cwd = process.cwd();
+  const absWtPath = resolve(wt.path);
+  const absCwd = resolve(cwd);
+  if (absCwd.startsWith(absWtPath)) {
+    console.error("Error: cannot remove current worktree - exit first");
+    process.exit(1);
+  }
+
+  // Get branch before removing
+  const branch = getWorktreeBranch(wt.path);
+
+  // Remove worktree
+  try {
+    removeWorktree(wt.path);
+  } catch {
+    // May already be gone
+  }
+
+  pruneWorktrees();
+
+  // Delete branch if requested
+  if (deleteBranchFlag && branch !== "[missing]" && branch !== "[detached]") {
+    try {
+      deleteBranch(branch);
+    } catch (err) {
+      console.error(`Warning: failed to delete branch ${branch}`);
+    }
+  }
+
+  // Remove from store
+  removeFromStore(store, name);
+  saveStore(store);
+
+  if (deleteBranchFlag && branch !== "[missing]" && branch !== "[detached]") {
+    console.log(success("Removed"), bold(name), dim("(branch deleted)"));
+  } else {
+    console.log(success("Removed"), bold(name));
+  }
+}