@senomas/pi-git-hat 0.1.0

package/lib/searchable-select-list.ts

@@ -0,0 +1,112 @@
+/**
+ * SearchableSelectList: extends @mariozechner/pi-tui's SelectList
+ * with incremental search/filter by typing printable characters.
+ *
+ * This avoids patching node_modules directly.
+ */
+
+import { SelectList, getKeybindings, parseKey } from "@earendil-works/pi-tui";
+
+export class SearchableSelectList extends SelectList {
+  filterString = "";
+
+  /**
+   * Override setFilter() to:
+   * - Store the filter string
+   * - Use `includes` (not `startsWith`)
+   * - Search both `value` and `label`
+   * - Keep disabled items visible (role headers)
+   */
+  setFilter(filter: string): void {
+    this.filterString = filter;
+    this.filteredItems = this.items.filter((item) => {
+      if (item.disabled) return true; // keep role headers
+      const q = filter.toLowerCase();
+      const val = (item.value || "").toLowerCase();
+      const lbl = (item.label || "").toLowerCase();
+      return val.includes(q) || lbl.includes(q);
+    });
+    this.selectedIndex = 0;
+  }
+
+  /** Convenience: clear the filter. */
+  clearFilter(): void {
+    this.setFilter("");
+  }
+
+  /**
+   * Override render() to show a filter bar when filterString is non-empty.
+   */
+  render(width: number): string[] {
+    const lines: string[] = [];
+
+    // Show filter bar when filtering
+    if (this.filterString.length > 0) {
+      lines.push(this.theme.noMatch(`\uD83D\uDD0D ${this.filterString}`));
+    }
+
+    // Delegate remaining rendering to the base class
+    const baseLines = super.render(width);
+    // super.render() prepends "No matching commands" when filteredItems is empty,
+    // but we already show a filter bar above. Squelch duplicates.
+    if (this.filteredItems.length === 0 && this.filterString.length > 0) {
+      // Already showing filter bar; skip the "No matching commands" message
+      return lines;
+    }
+    lines.push(...baseLines);
+    return lines;
+  }
+
+  /**
+   * Override handleInput() to intercept search keystrokes before
+   * delegating navigation keys to the base class.
+   */
+  handleInput(keyData: string): void {
+    const kb = getKeybindings();
+
+    // Backspace → remove last char of filter
+    if (kb.matches(keyData, "tui.editor.deleteCharBackward")) {
+      if (this.filterString.length > 0) {
+        this.setFilter(this.filterString.slice(0, -1));
+        return;
+      }
+      // If filter is already empty, treat as cancel
+      if (this.onCancel) {
+        this.onCancel();
+      }
+      return;
+    }
+
+    // Ctrl+U → clear filter entirely
+    if (kb.matches(keyData, "tui.editor.deleteToLineStart")) {
+      if (this.filterString.length > 0) {
+        this.clearFilter();
+        return;
+      }
+      // fall through to base if filter already empty
+    }
+
+    // Escape → if filter active, clear it; otherwise cancel
+    if (kb.matches(keyData, "tui.select.cancel")) {
+      if (this.filterString.length > 0) {
+        this.clearFilter();
+        return;
+      }
+      // fall through to base for actual cancel
+    }
+
+    // Printable character → append to filter.
+    // parseKey() returns the single character for printable key input
+    // (handles Kitty CSI-u, ModifyOtherKeys, and legacy raw ASCII).
+    // It returns multi-character key IDs ("up", "enter", etc.) for
+    // non-printable keys, which are filtered out by the length check.
+    const parsed = parseKey(keyData);
+    if (parsed && parsed.length === 1) {
+      this.setFilter(this.filterString + parsed);
+      return;
+    }
+
+    // Delegate navigation and other keys to the base class
+    super.handleInput(keyData);
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+	"name": "@senomas/pi-git-hat",
+	"version": "0.1.0",
+	"description": "Pi extension for role-based Git branch workflows — wear different hats by switching branches",
+	"type": "module",
+	"keywords": ["pi-package", "git", "workflow", "branching", "roles"],
+	"license": "MIT",
+	"files": [
+		"git-hat.ts",
+		"lib/",
+		"roles/",
+		"scripts/validate-role-prompts.py",
+		"LICENSE",
+		"README.md"
+	],
+	"pi": {
+		"extensions": ["./git-hat.ts"]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"dependencies": {}
+}

package/roles/admin.md

@@ -0,0 +1,13 @@
+# Admin
+
+You are **ADMIN**. Switching branch does not switch your role.
+
+## What you do
+- Edit `.pi/` files — role prompts, roles.json
+- Edit `README.md` and `AGENTS.md`
+- Explore the codebase (read-only)
+
+## What you do NOT do
+- Edit source code
+- Create or modify `todo/`, `plan/`, `report/` files
+- Switch branches (the user handles that)

package/roles/implementor.md

@@ -0,0 +1,20 @@
+# Implementor
+
+You are **IMPLEMENTOR**. Your responsibility is to read todo/*.md files, implement and write reports. That is it. Switching branch does not switch your role.
+
+## Report format: `report/NN-name.md`
+- Same NN and same headers as the todo
+- Add implementation notes, decisions, and ```bash results
+
+## How to implement
+1. Read `todo/NN-name.md` (lowest NN first)
+2. If `todo/NN-name.detail.md` exists, read it too
+3. Implement each `- [ ]` item using `edit`/`write`
+4. After each item (or batch), update `report/NN-name.md`
+5. When done, move to the next NN
+
+## What you do NOT do
+- Switch branches (the user handles that)
+- Write to `todo/`, `plan/`, or `.pi/` — create reports only; let others verify and mark items done
+- Create todo files (that's the planner's job)
+- Modify or mark items in todo files (that's the reviewer's job after verification)

package/roles/planner.md

@@ -0,0 +1,25 @@
+# Planner
+
+You are **PLANNER**. Your sole responsibility is to research (just collecting data for others to solved the problem) and create
+`todo/NN-name.md` files. That is it. Switching branch does not switch your role.
+
+## What you do
+1. Research with `read` / `grep` / `find` / `ls`
+2. Create `todo/NN-name.md` with sequenced, actionable items
+3. Present the plan to the user
+
+## What you do NOT do
+- `edit`/`write` any file outside `todo/`
+- Switch branches (the user handles that)
+- Implement anything (that's the implementor)
+- Write reports (that's the implementor)
+
+## File format: `todo/NN-name.md`
+- `- [ ]` pending, `- [x]` done
+- First line after checkbox = **header**
+- Indented lines = **body**
+- Blank lines separate items
+
+## NN sequence rule
+Every `todo/NN-name.md` must use NN **higher** than the highest NN in both
+`todo/` **and** `report/`.

package/roles/reviewer.md

@@ -0,0 +1,22 @@
+# Reviewer
+
+You are **REVIEWER**. Your sole responsibility is to verify that reports fully cover their corresponding todos, and mark items done in `todo/`. That is it. Switching branch does not switch your role.
+
+## What you do
+1. Read `todo/NN-name.md` and `report/NN-name.md`
+2. Match each pending `- [ ]` todo item against a section in the report
+3. **Covered** → mark `- [x]` in the todo file
+4. **Missing** → leave `- [ ]`, tell the user
+5. Also check for orphan reports and stale todos
+
+## What you do NOT do
+- `edit`/`write` any file outside `todo/`
+- Write reports (that's the implementor)
+- Create `todo/` or `plan/` files (that's the planner)
+- Switch branches (the user handles that)
+- Write to `.pi/`
+
+## Key rules
+- **Covered** items get `- [x]` in the todo file
+- **Missing** items stay `- [ ]` — explain why to the user
+- Read source files and `review/` and `todo/` as needed to verify

package/roles/roles.json

@@ -0,0 +1,8 @@
+{
+  "roles": {
+    "planner":      { "pattern": "^plan(-|/|$)", "description": "Plan work by creating todo/plan files" },
+    "implementor":  { "pattern": "^(implementor$|feature|feat|impl$|work$)(-|/|$)", "description": "Feature/impl/work branches" },
+    "reviewer":     { "pattern": "^review(-|/|$)", "description": "Review implementations against todos" },
+    "admin":        { "pattern": "^(main|master)$", "description": "Project configuration and docs" }
+  }
+}

package/scripts/validate-role-prompts.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+Validate that BUILTIN_INSTRUCTIONS (hardcoded in git-hat.ts) match
+the canonical roles/*.md files in content (body text, not wrappers).
+
+Run from the git-hat project root:
+    python3 scripts/validate-role-prompts.py
+
+Returns exit code 0 if all match, 1 on any mismatch.
+"""
+
+import re
+import sys
+import os
+
+# --- Find repo root (script lives in scripts/) ---
+script_dir = os.path.dirname(os.path.abspath(__file__))
+repo_root = os.path.dirname(script_dir)
+
+# --- Extract BUILTIN_INSTRUCTIONS from git-hat.ts ---
+source_path = os.path.join(repo_root, "git-hat.ts")
+with open(source_path, "r", encoding="utf-8") as f:
+    source = f.read()
+
+# Find the BUILTIN_INSTRUCTIONS object
+pattern = r"const BUILTIN_INSTRUCTIONS:\s*Record<string,\s*string>\s*=\s*({[\s\S]*?});"
+m = re.search(pattern, source)
+if not m:
+    print("❌ Could not find BUILTIN_INSTRUCTIONS in git-hat.ts", file=sys.stderr)
+    sys.exit(1)
+
+# Parse the object literal using eval-like approach.
+# We need to convert the TS object to a Python dict.
+obj_str = m.group(1)
+
+# Extract string key-value pairs:  key: `value`
+builtin = {}
+# Match patterns like:   planner: `\n\n...content...\n`,
+key_pattern = re.compile(
+    r'^\s+(\w+):\s*`((?:[^`\\]|\\.)*)`\s*,?\s*$',
+    re.MULTILINE
+)
+for match in key_pattern.finditer(obj_str):
+    key = match.group(1)
+    value = match.group(2)
+    builtin[key] = value
+
+if not builtin:
+    print("❌ Failed to parse BUILTIN_INSTRUCTIONS keys from git-hat.ts", file=sys.stderr)
+    # Try a more lenient approach
+    print("  Raw match snippet:", obj_str[:200], file=sys.stderr)
+    sys.exit(1)
+
+# --- Load roles/*.md files ---
+roles_dir = os.path.join(repo_root, "roles")
+if not os.path.isdir(roles_dir):
+    print("❌ Could not find roles/ directory", file=sys.stderr)
+    sys.exit(1)
+
+role_files = sorted([f for f in os.listdir(roles_dir) if f.endswith(".md")])
+role_names = set(f.replace(".md", "").lower() for f in role_files)
+# Map lowercase role name to actual filename (handles case-sensitive filesystems)
+role_file_map = {f.replace(".md", "").lower(): f for f in role_files}
+
+# --- Comparison helpers ---
+
+def strip_builtin_wrapper(text):
+    """Strip the header wrapper that BUILTIN_INSTRUCTIONS adds for system prompt injection.
+    BUILTIN strings start with \n\n## Your Role: <Name>\n\n
+    We extract everything after the first blank-line-separated header block.
+    Also unescape backticks (escaped as backslash-backtick in TS template literals).
+    """
+    # Remove leading newlines, then the ## Your Role: ... header and its following blank line
+    result = re.sub(r'^\n+', '', text)
+    result = re.sub(r'^## Your Role: .+?\n\n', '', result)
+    # Unescape backticks that are escaped in TS template literals
+    result = result.replace('\\`', '`')
+    return result.rstrip() + '\n'
+
+def normalize_file_content(text):
+    """Normalize a roles/*.md file content for comparison.
+    Strips the # Rolename header (redundant with the ## Your Role: wrapper
+    that BUILTIN_INSTRUCTIONS adds at injection time) and trailing whitespace.
+    """
+    # Strip the # Rolename level-1 header if present
+    result = re.sub(r'^# \w+\n\n', '', text)
+    return result.rstrip() + '\n'
+
+
+all_pass = True
+errors = []
+
+for role_name in sorted(role_names):
+    # Find matching builtin key (case-insensitive)
+    builtin_key = None
+    for k in builtin:
+        if k.lower() == role_name:
+            builtin_key = k
+            break
+
+    if builtin_key is None:
+        errors.append(f"❌ roles/{role_name}.md has no matching key in BUILTIN_INSTRUCTIONS")
+        all_pass = False
+        continue
+
+    actual_filename = role_file_map.get(role_name, f"{role_name}.md")
+    with open(os.path.join(roles_dir, actual_filename), "r", encoding="utf-8") as f:
+        file_content = normalize_file_content(f.read())
+
+    builtin_content = strip_builtin_wrapper(builtin[builtin_key])
+
+    if file_content == builtin_content:
+        print(f"✅ {role_name}: BUILTIN_INSTRUCTIONS matches roles/{role_name}.md")
+    else:
+        errors.append(f"❌ {role_name}: BUILTIN_INSTRUCTIONS differs from roles/{role_name}.md")
+        # Show first diff chunk
+        file_lines = file_content.split('\n')
+        builtin_lines = builtin_content.split('\n')
+        max_len = max(len(file_lines), len(builtin_lines))
+        first_diff = -1
+        for i in range(max_len):
+            fl = file_lines[i] if i < len(file_lines) else None
+            bl = builtin_lines[i] if i < len(builtin_lines) else None
+            if fl != bl:
+                first_diff = i
+                break
+        if first_diff >= 0:
+            fl = file_lines[first_diff] if first_diff < len(file_lines) else "(end)"
+            bl = builtin_lines[first_diff] if first_diff < len(builtin_lines) else "(end)"
+            errors.append(f"  First difference at line {first_diff + 1}:")
+            errors.append(f"  file:    {repr(fl)}")
+            errors.append(f"  builtin: {repr(bl)}")
+        all_pass = False
+
+# Check for builtin keys that have no corresponding roles/ file
+for key in builtin:
+    if key.lower() not in role_names:
+        errors.append(f"❌ BUILTIN_INSTRUCTIONS[\"{key}\"] has no corresponding roles/{key}.md file")
+        all_pass = False
+
+print()
+if all_pass:
+    print("✅ All role prompts are in sync.")
+else:
+    print("❌ Mismatches found:")
+    for err in errors:
+        print(f"  {err}")
+
+sys.exit(0 if all_pass else 1)