@senomas/pi-git-hat 0.2.5 → 0.2.7

package/lib/branch-history.ts

@@ -0,0 +1,143 @@
+/**
+ * Branch history persistence for git-hat.
+ *
+ * Tracks which branch was last used for each role, and maintains a
+ * chronological switch log capped at 50 entries.
+ */
+
+import { readFileSync } from "node:fs";
+import { writeFile, mkdir } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import os from "node:os";
+
+import type { MergedConfig, BranchHistory, SwitchLogEntry, BranchEntry } from "./types.js";
+import { detectRole } from "./config.js";
+
+// -- Persistence paths ------------------------------------------------
+
+const AGENT_DIR = resolve(os.homedir(), ".pi", "agent");
+const BRANCH_HISTORY_FILE = resolve(AGENT_DIR, "role_branch.json");
+
+/** Load branch history from disk. Handles backward compat: old flat format {role: branch}
+ *  is converted to new format with a history array.
+ *  Returns the role→branch mapping and the switch history entries separately. */
+export function loadBranchHistory(): { mapping: BranchHistory; history: SwitchLogEntry[] } {
+  try {
+    const raw = JSON.parse(readFileSync(BRANCH_HISTORY_FILE, "utf-8"));
+    // Detect new format (has "history" array) vs old format (flat {role: branch})
+    if (raw && typeof raw === "object" && !Array.isArray(raw) && "history" in raw) {
+      const { history, ...mapping } = raw;
+      return {
+        mapping: mapping as BranchHistory,
+        history: Array.isArray(history) ? (history as SwitchLogEntry[]) : [],
+      };
+    }
+    // Old format: flat object — wrap into new shape with empty history
+    return { mapping: raw as BranchHistory, history: [] };
+  } catch {
+    return { mapping: {}, history: [] };
+  }
+}
+
+/** Persist mapping + history to disk. */
+export async function saveBranchHistory(mapping: BranchHistory, history: SwitchLogEntry[]): Promise<void> {
+  await mkdir(AGENT_DIR, { recursive: true });
+  await writeFile(
+    BRANCH_HISTORY_FILE,
+    JSON.stringify({ ...mapping, history }, null, 2),
+    "utf-8",
+  );
+}
+
+/** Record a branch switch for a role. Persisted immediately. */
+export async function recordBranchUsage(role: string, branch: string): Promise<void> {
+  if (!role || !branch) return;
+  const { mapping, history } = loadBranchHistory();
+  mapping[role] = branch;
+  history.push({ ts: new Date().toISOString(), role, branch });
+  // Cap at 50 entries (trim oldest)
+  if (history.length > 50) {
+    history.splice(0, history.length - 50);
+  }
+  await saveBranchHistory(mapping, history);
+}
+
+/** List all git branches and match them to roles. */
+export async function listBranchesByRole(config: MergedConfig, cwd: string): Promise<{
+  entries: BranchEntry[];
+  grouped: Record<string, BranchEntry[]>;
+  roleOrder: string[];
+  unmatched: string[];
+}> {
+  const { mapping: history } = loadBranchHistory();
+  const entries: BranchEntry[] = [];
+  const grouped: Record<string, BranchEntry[]> = {};
+  const unmatched: string[] = [];
+
+  // Get current branch
+  let currentBranch: string | null = null;
+  try {
+    const stdout = execFileSync("git", ["branch", "--show-current"], {
+      cwd,
+      encoding: "utf-8",
+    }) as string;
+    currentBranch = stdout.trim() || null;
+  } catch {
+    /* not a git repo */
+  }
+
+  // Get all branches
+  let branches: string[] = [];
+  try {
+    const stdout = execFileSync("git", ["branch", "--format", "%(refname:short)"], {
+      cwd,
+      encoding: "utf-8",
+    }) as string;
+    branches = stdout.trim().split("\n").filter(Boolean);
+  } catch {
+    return { entries, grouped, roleOrder: [], unmatched };
+  }
+
+  // Match each branch to a role
+  for (const branch of branches) {
+    const role = detectRole(branch, config);
+    if (!role) {
+      unmatched.push(branch);
+      continue;
+    }
+
+    const isCurrent = branch === currentBranch;
+    const isLastUsed = history[role] === branch;
+    const entry: BranchEntry = { branch, role, isCurrent, isLastUsed };
+    entries.push(entry);
+    if (!grouped[role]) grouped[role] = [];
+    grouped[role].push(entry);
+  }
+
+  // Sort within each role: current -> last-used -> rest (alpha)
+  for (const role of Object.keys(grouped)) {
+    grouped[role].sort((a, b) => {
+      if (a.isCurrent) return -1;
+      if (b.isCurrent) return 1;
+      if (a.isLastUsed) return -1;
+      if (b.isLastUsed) return 1;
+      return a.branch.localeCompare(b.branch);
+    });
+  }
+
+  // Role order: roles with current branch first, then last-used, then alpha
+  const roleOrder = [...new Set(entries.map((e) => e.role))].sort((a, b) => {
+    const aHasCurrent = grouped[a]?.some((e) => e.isCurrent);
+    const bHasCurrent = grouped[b]?.some((e) => e.isCurrent);
+    if (aHasCurrent && !bHasCurrent) return -1;
+    if (!aHasCurrent && bHasCurrent) return 1;
+    const aHasLast = grouped[a]?.some((e) => e.isLastUsed);
+    const bHasLast = grouped[b]?.some((e) => e.isLastUsed);
+    if (aHasLast && !bHasLast) return -1;
+    if (!aHasLast && bHasLast) return 1;
+    return a.localeCompare(b);
+  });
+
+  return { entries, grouped, roleOrder, unmatched };
+}

package/lib/config.ts

@@ -0,0 +1,103 @@
+/**
+ * Config loading for git-hat.
+ *
+ * Loads roles.json from project .pi/ or global ~/.pi/agent/,
+ * then walks up from CWD for .pi-project.json overrides.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import os from "node:os";
+
+import type { MergedConfig, RolesConfig } from "./types.js";
+
+const HOME_PI_DIR = resolve(os.homedir(), ".pi");
+
+/** Load and merge roles configuration from disk. */
+export function loadConfig(): MergedConfig {
+  const merged: MergedConfig = {
+    roles: {},
+    fileDir: ".pi",
+    caseInsensitive: true,
+
+    postSwitchLog: true,
+  };
+
+  // Search paths for roles.json (first found wins):
+  //   1. {PROJECT_ROOT}/.pi/roles.json  (project-specific, inside .pi/)
+  //   2. ~/.pi/agent/roles.json          (global fallback, inside git repo)
+  const roleFileCandidates = [
+    resolve(process.cwd(), ".pi", "roles.json"),
+    resolve(HOME_PI_DIR, "agent", "roles.json"),
+  ];
+
+  let loadedRoles = false;
+  for (const candidatePath of roleFileCandidates) {
+    if (existsSync(candidatePath)) {
+      try {
+        const raw = JSON.parse(readFileSync(candidatePath, "utf-8")) as RolesConfig;
+        if (raw.roles) {
+          Object.assign(merged.roles, raw.roles);
+          loadedRoles = true;
+        }
+        if (raw.fileDir) merged.fileDir = raw.fileDir;
+        if (raw.caseInsensitive !== undefined) merged.caseInsensitive = raw.caseInsensitive;
+
+        if (raw.postSwitchLog !== undefined) merged.postSwitchLog = raw.postSwitchLog;
+        if (raw.default) {
+          if (raw.default["pre-tool"] !== undefined) merged.preTool = raw.default["pre-tool"];
+          if (raw.default["post-tool"] !== undefined) merged.postTool = raw.default["post-tool"];
+        }
+      } catch {
+        // ignore parse errors
+      }
+      merged.configFile = candidatePath;
+      break; // first matching path wins
+    }
+  }
+
+  if (!loadedRoles) {
+    const searched = roleFileCandidates.join(", ");
+    throw new Error(
+      `roles.json not found. Searched:\n  ${searched}\n\n` +
+        `Create one at the project root (~/.pi/agent/roles.json) or inside `.pi/` ({project}/.pi/roles.json).`
+    );
+  }
+
+  // Walk up from CWD to find .pi-project.json for project overrides
+  // Project-level roles fully override matching base roles
+  let dir = process.cwd();
+  while (true) {
+    const candidate = resolve(dir, ".pi-project.json");
+    if (existsSync(candidate)) {
+      try {
+        const projectRaw = JSON.parse(readFileSync(candidate, "utf-8")) as RolesConfig;
+        if (projectRaw.roles) {
+          for (const [name, def] of Object.entries(projectRaw.roles)) {
+            merged.roles[name] = def;
+          }
+        }
+      } catch {
+        // ignore parse errors
+      }
+      break;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return merged;
+}
+
+/** Detect the role for a given branch name by iterating merged roles. */
+export function detectRole(branch: string, config: MergedConfig): string | null {
+  for (const [roleName, roleDef] of Object.entries(config.roles)) {
+    try {
+      if (new RegExp(roleDef.pattern).test(branch)) return roleName;
+    } catch {
+      // skip invalid regex
+    }
+  }
+  return null; // no match -> "unknown"
+}

package/lib/git-ui.ts

@@ -0,0 +1,217 @@
+/**
+ * Git UI helpers for git-hat.
+ *
+ * Functions for displaying colored git logs, role icons,
+ * ANSI colorization of ref names, and working tree status.
+ */
+
+/**
+ * Exec function signature matching ExtensionAPI.exec().
+ * Accepts a command and args array, returns { stdout, stderr, code }.
+ */
+export type ExecFunction = (
+  command: string,
+  args: string[],
+) => Promise<{ stdout: string; stderr: string; code: number }>;
+
+/** Role icon for status bar display. */
+export function roleIcon(role: string): string {
+  const lower = role.toLowerCase();
+  if (lower === "planner") return "\uD83D\uDCCB";
+  if (lower === "implementor") return "\uD83D\uDEE0";
+  if (lower === "reviewer") return "\uD83D\uDD0D";
+  if (lower === "admin") return "\u2699";
+  if (lower === "researcher") return "\uD83D\uDD2C";
+  return "\uD83E\uDDE2";
+}
+
+// -- ANSI color palette for git ref log decoration ----------------
+
+const REF_COLORS = [
+  "38;5;51",   // cyan
+  "38;5;118",  // green
+  "38;5;226",  // yellow
+  "38;5;207",  // magenta
+  "38;5;196",  // red
+  "38;5;75",   // blue
+  "38;5;214",  // orange
+  "38;5;201",  // purple
+];
+
+const HEAD_ANSI = "1;37"; // bold bright white
+
+/**
+ * Colorize ref names in `git log --oneline --decorate` output.
+ * Parses `(ref-list)` patterns and wraps each ref in distinct ANSI
+ * 256-color codes. HEAD gets a fixed bold white. All other refs
+ * (branches, tags) rotate through an 8-color palette consistently.
+ */
+export function colorizeLog(log: string): string {
+  // First pass: collect all unique ref names for consistent color assignment
+  const refNames = new Set<string>();
+  const refListRe = /\(([^)]+)\)/g;
+  let m: RegExpExecArray | null;
+  while ((m = refListRe.exec(log)) !== null) {
+    for (const part of m[1].split(/,\s*/)) {
+      const trimmed = part
+        .replace(/^(HEAD -> |HEAD\b|tag: |tags: )/g, "")
+        .trim();
+      if (trimmed) refNames.add(trimmed);
+    }
+  }
+
+  // Assign a rotating color to each unique ref name
+  const colorMap = new Map<string, string>();
+  let idx = 0;
+  for (const name of refNames) {
+    colorMap.set(name, REF_COLORS[idx % REF_COLORS.length]);
+    idx++;
+  }
+
+  // Second pass: wrap each ref in the `(...)` list with ANSI codes
+  return log
+    .split("\n")
+    .map((line) => {
+      return line.replace(
+        /\(([^)]+)\)/g,
+        (_, refList: string) => {
+          const colored = refList
+            .split(/,\s*/)
+            .map((ref: string) => {
+              // "HEAD -> branchname"
+              const headArrow = ref.match(/^(HEAD)\s*->\s*(.+)$/);
+              if (headArrow) {
+                const head = `\x1b[${HEAD_ANSI}mHEAD\x1b[0m`;
+                const branchColor = colorMap.get(headArrow[2]) || REF_COLORS[0];
+                const branch = `\x1b[${branchColor}m${headArrow[2]}\x1b[0m`;
+                return `${head} -> ${branch}`;
+              }
+              // bare HEAD (detached)
+              if (ref === "HEAD") {
+                return `\x1b[${HEAD_ANSI}mHEAD\x1b[0m`;
+              }
+              // "tag: tagname"
+              const tagMatch = ref.match(/^tag:\s*(.+)$/);
+              if (tagMatch) {
+                const color = colorMap.get(tagMatch[1]) || REF_COLORS[0];
+                return `\x1b[${color}m${ref}\x1b[0m`;
+              }
+              // plain ref (branch, remote)
+              const color = colorMap.get(ref) || REF_COLORS[0];
+              return `\x1b[${color}m${ref}\x1b[0m`;
+            })
+            .join(", ");
+          return `(${colored})`;
+        },
+      );
+    })
+    .join("\n");
+}
+
+/**
+ * Run a colored git log and display it in the TUI.
+ * Shared between /hatl and the post-switch log in /hat.
+ *
+ * @param ctx - TUI context with ui.notify
+ * @param count - Number of log lines (default 10)
+ * @param execFn - Optional exec function (e.g. pi.exec). If omitted, falls back
+ *                 to child_process.execFileSync for backward compatibility.
+ */
+export async function showGitLog(
+  ctx: { ui: { notify: (msg: string, level: string) => void } },
+  count: number = 10,
+  execFn?: ExecFunction,
+): Promise<void> {
+  const validCount = Number.isFinite(count) && count > 0 ? count : 10;
+
+  try {
+    let raw: string;
+
+    if (execFn) {
+      // Use the provided exec function (e.g. pi.exec from the extension API)
+      const result = await execFn("git", [
+        "log",
+        "--graph",
+        "--oneline",
+        "--decorate",
+        "--all",
+        `-${validCount}`,
+      ]);
+      raw = result.stdout.trim();
+    } else {
+      // Fallback to child_process.execFileSync for backward compatibility
+      const result = await import("child_process").then((cp) =>
+        cp.execFileSync("git", [
+          "log",
+          "--graph",
+          "--oneline",
+          "--decorate",
+          "--all",
+          `-${validCount}`,
+        ], { encoding: "utf-8" }),
+      ) as string;
+      raw = result.trim();
+    }
+
+    if (!raw) {
+      return; // silently ignore empty log
+    }
+
+    const colored = colorizeLog(raw);
+    const footer = `\n\x1b[90m\u2022 /hatl N  for more lines\x1b[0m`;
+    ctx.ui.notify(colored + footer, "info");
+  } catch {
+    // non-critical — silently ignore
+  }
+}
+
+/**
+ * Display git working tree status.
+ *
+ * - If the working tree is clean: shows a green checkmark summary.
+ * - If dirty: runs full `git status` and displays the raw output.
+ *
+ * @param ctx - TUI context with ui.notify
+ * @param branch - Current branch name
+ * @param execFn - Optional exec function (e.g. pi.exec). If omitted, falls back
+ *                 to child_process.execFileSync for backward compatibility.
+ */
+export async function showGitStatus(
+  ctx: { ui: { notify: (msg: string, level: string) => void } },
+  branch: string,
+  execFn?: ExecFunction,
+): Promise<void> {
+  try {
+    let shortOutput: string;
+
+    if (execFn) {
+      const result = await execFn("git", ["status", "--short"]);
+      shortOutput = result.stdout;
+    } else {
+      const result = await import("child_process").then((cp) =>
+        cp.execFileSync("git", ["status", "--short"], { encoding: "utf-8" }),
+      ) as string;
+      shortOutput = result as string;
+    }
+
+    if (shortOutput.trim().length === 0) {
+      // Clean working tree
+      ctx.ui.notify(`\x1b[32m\u2713\x1b[0m working tree clean (branch: ${branch})`, "info");
+    } else {
+      // Dirty — show full status
+      let fullOutput: string;
+      if (execFn) {
+        const result = await execFn("git", ["status"]);
+        fullOutput = result.stdout;
+      } else {
+        const result = await import("child_process").then((cp) =>
+          cp.execFileSync("git", ["status"], { encoding: "utf-8" }),
+        ) as string;
+        fullOutput = result as string;
+      }
+      ctx.ui.notify(fullOutput.trim(), "info");
+    }
+  } catch {
+    // non-critical — silently ignore
+  }
+}

package/lib/paths.ts

@@ -0,0 +1,79 @@
+/**
+ * Path utilities for git-hat.
+ *
+ * Helpers for normalising file paths, stripping cd prefixes,
+ * checking if a path is inside allowed directories, and matching
+ * writable path entries.
+ */
+
+import { resolve } from "node:path";
+
+import type { WritablePathEntry } from "./types.js";
+
+/** Normalise a file path argument: strip leading ./, absolute -> relative. */
+export function normalisePath(raw: string, cwd: string, cwdAbsolute: string): string {
+  let path = raw;
+  if (path.startsWith(cwdAbsolute + "/")) path = path.slice(cwdAbsolute.length + 1);
+  if (path.startsWith("./")) path = path.slice(2);
+  return path;
+}
+
+/**
+ * Strip a leading `cd <dir> && ` prefix from a bash command if <dir> resolves
+ * to a path inside the project. Supports relative paths (resolved against cwd).
+ *
+ * Examples:
+ *   "cd docs && ls -la"         → "ls -la"
+ *   "cd ../outside && ls"      → "cd ../outside && ls" (unchanged — outside project)
+ *   "ls -la"                    → "ls -la" (unchanged — no cd prefix)
+ */
+export function stripCdPrefix(cmd: string, cwd: string, cwdAbsolute: string): string {
+  const match = cmd.match(/^cd\s+(\S+)\s*&&\s*/);
+  if (!match) return cmd;
+  const dir = match[1];
+  const rest = cmd.slice(match[0].length);
+  // Resolve the directory: absolute path, relative path, or ~
+  let resolved: string;
+  if (dir.startsWith("/")) {
+    resolved = dir;
+  } else if (dir.startsWith("~")) {
+    return cmd; // home dir — can't guarantee it's inside project, keep as-is
+  } else {
+    resolved = resolve(cwd, dir);
+  }
+  // Check if resolved path is inside the project
+  if (resolved.startsWith(cwdAbsolute)) {
+    return rest;
+  }
+  return cmd;
+}
+
+/** Check if a path is inside one of the given directories. */
+export function isInside(path: string, dirs: string[]): boolean {
+  return dirs.some((d) => path === d || path.startsWith(d + "/"));
+}
+
+/**
+ * Check if a path matches one of the given writable path entries.
+ *
+ * - If `entry.path` is empty string, only root-level files match.
+ * - If `entry.extension` is set, the path must end with that extension.
+ * - A trailing slash is appended automatically when matching directories.
+ */
+export function isWritablePath(path: string, writablePaths: WritablePathEntry[]): boolean {
+  return writablePaths.some((entry) => {
+    const dir = entry.path;
+    const ext = entry.extension;
+    // Check directory match
+    const inDir =
+      dir === ""
+        ? !path.includes("/") // root level only
+        : path === dir || path.startsWith(dir + "/");
+    if (!inDir) return false;
+    // Check extension filter (if set)
+    if (ext) {
+      return path.endsWith("." + ext);
+    }
+    return true; // no extension filter = allow any file in this dir
+  });
+}