bingo-light 2.0.1 → 2.1.0

package/.claude/commands/bingo.md

@@ -0,0 +1,116 @@
+---
+name: bingo
+description: Manage forked git repos with bingo-light — sync upstream, resolve conflicts, manage patch stack
+allowed-tools: Bash(bingo-light *) Bash(git add *) Bash(git rebase --continue) Read Edit
+---
+
+You are managing a forked git repository using bingo-light. Your patches live as a clean stack on top of upstream. Your job: keep the fork in sync, resolve conflicts, and manage patches — autonomously.
+
+## Decision Loop
+
+Always start with status. The `recommended_action` field tells you what to do:
+
+```bash
+bingo-light status --json --yes
+```
+
+Response includes `recommended_action`:
+- `"up_to_date"` → Nothing to do. Tell the user.
+- `"sync_safe"` → Run sync directly (no conflict risk).
+- `"sync_risky"` → Dry-run first, then sync if clean, resolve if conflicts.
+- `"resolve_conflict"` → Already mid-rebase. Analyze and resolve.
+- `"unknown"` → Run doctor for diagnostics.
+
+## Sync Flow
+
+### Use smart-sync (preferred — one call does everything)
+```bash
+bingo-light smart-sync --json --yes
+```
+
+Responses:
+- `{"ok":true, "action":"none"}` → Already up to date
+- `{"ok":true, "action":"synced", "conflicts_resolved":0}` → Clean sync
+- `{"ok":true, "action":"synced_with_rerere", "conflicts_auto_resolved":N}` → Conflicts auto-resolved by rerere
+- `{"ok":false, "action":"needs_human", "remaining_conflicts":[...]}` → Needs manual resolution (see below)
+
+### When smart-sync returns needs_human
+
+The response includes `remaining_conflicts` with full context:
+```json
+{
+  "remaining_conflicts": [
+    {"file": "app.py", "ours": "upstream code", "theirs": "your code", "merge_hint": "Keep both"}
+  ],
+  "resolution_steps": ["1. Read ours/theirs", "2. Write merged", "3. git add", "4. git rebase --continue"]
+}
+```
+
+For each conflict:
+1. Read the `merge_hint` — it tells you the strategy
+2. Read the actual file (has <<<<<<< ======= >>>>>>> markers)
+3. Write the merged version (usually: keep BOTH changes)
+4. `git add <file>`
+5. `git rebase --continue`
+6. Run `bingo-light status --json` to verify
+
+### Fallback: manual sync (for fine-grained control)
+```bash
+bingo-light sync --dry-run --json --yes   # Preview
+bingo-light sync --json --yes             # Execute
+bingo-light conflict-analyze --json       # If conflict
+```
+
+## Patch Management
+
+```bash
+# Create a patch (always set BINGO_DESCRIPTION)
+BINGO_DESCRIPTION="what this patch does" bingo-light patch new <name> --json --yes
+
+# List patches
+bingo-light patch list --json --yes
+
+# Show a specific patch diff
+bingo-light patch show <name-or-index> --json --yes
+
+# Remove a patch
+bingo-light patch drop <name-or-index> --json --yes
+
+# Reorder patches (provide ALL indices)
+bingo-light patch reorder --order "3,1,2" --json --yes
+
+# Merge two adjacent patches
+bingo-light patch squash <idx1> <idx2> --json --yes
+
+# Edit a patch (stage changes first, then edit)
+git add <files>
+bingo-light patch edit <name-or-index> --json --yes
+```
+
+## Diagnostics
+
+```bash
+bingo-light doctor --json --yes     # Full health check
+bingo-light diff --json --yes       # All changes vs upstream
+bingo-light history --json --yes    # Sync history with hashes
+bingo-light undo --json --yes       # Revert last sync
+```
+
+## Configuration
+
+```bash
+bingo-light config set test.command "make test"    # Run tests after sync
+bingo-light config set sync.auto-test true         # Auto-test on sync
+bingo-light test --json --yes                      # Run tests manually
+```
+
+## Key Rules
+
+1. **Always use `--json --yes`** when calling via Bash
+2. **Always check `recommended_action`** from status before deciding what to do
+3. **Read `merge_hint`** from conflict-analyze — it tells you the resolution strategy
+4. **After resolving conflicts**: `git add` then `git rebase --continue`, NOT `bingo-light sync`
+5. **BINGO_DESCRIPTION** env var sets patch description (required for `patch new`)
+6. Patch names: alphanumeric + hyphens + underscores only
+7. `bingo-light undo` reverts the last sync — use it if sync went wrong
+8. rerere remembers conflict resolutions — same conflict auto-resolves on next sync

package/bingo_core/__init__.py

@@ -14,7 +14,7 @@ import re
 
 # --- Constants ---
 
-VERSION = "2.0.0"
+VERSION = "2.1.0"
 PATCH_PREFIX = "[bl]"
 CONFIG_FILE = ".bingolight"
 BINGO_DIR = ".bingo"

package/bingo_core/setup.py

@@ -299,48 +299,114 @@ def _read_key_tty() -> str:
         os.close(fd)
 
 
+# ─── UI Primitives (clack-style tree-line) ───────────────────────────────────
+
+# ANSI helpers
+_B = "\033[1m"       # bold
+_D = "\033[2m"       # dim
+_R = "\033[0m"       # reset
+_G = "\033[32m"      # green
+_C = "\033[36m"      # cyan
+_Y = "\033[33m"      # yellow
+_RD = "\033[31m"     # red
+_BG = "\033[38;5;75m"  # branded blue
+
+BAR = f"{_D}│{_R}"   # vertical connector
+END = f"{_D}└{_R}"   # end connector
+DOT = f"{_C}◆{_R}"   # active section marker
+CHK = f"{_G}◇{_R}"   # completed section marker
+
+
+def _ui_header(out, version: str) -> None:
+    out.write(f"\n  {_BG}{_B}◆  bingo-light setup{_R}  {_D}v{version}{_R}\n")
+    out.write(f"  {BAR}\n")
+
+
+def _ui_section(out, title: str, subtitle: str = "") -> None:
+    out.write(f"  {BAR}\n")
+    out.write(f"  {DOT}  {_B}{title}{_R}\n")
+    if subtitle:
+        out.write(f"  {BAR}  {_D}{subtitle}{_R}\n")
+
+
+def _ui_info(out, text: str) -> None:
+    out.write(f"  {BAR}  {_D}{text}{_R}\n")
+
+
+def _ui_ok(out, text: str) -> None:
+    out.write(f"  {BAR}  {_G}✓{_R} {text}\n")
+
+
+def _ui_fail(out, text: str) -> None:
+    out.write(f"  {BAR}  {_RD}✗{_R} {text}\n")
+
+
+def _ui_skip(out, text: str) -> None:
+    out.write(f"  {BAR}  {_D}⊘ {text}{_R}\n")
+
+
+def _ui_done(out, text: str) -> None:
+    out.write(f"  {BAR}\n")
+    out.write(f"  {END}  {_G}{_B}{text}{_R}\n\n")
+
+
+def _ui_bar(out) -> None:
+    out.write(f"  {BAR}\n")
+
+
 def multiselect(
+    out,
     items: List[Dict[str, Any]],
     pre_selected: Optional[List[int]] = None,
 ) -> List[int]:
-    """Interactive multi-select with arrow keys and spacebar.
+    """Interactive multi-select with clack-style rendering.
 
     items: list of {"label": str, "hint": str, "detected": bool}
-    pre_selected: indices that start checked
-
     Returns list of selected indices.
     """
-    out = sys.stderr
     selected = set(pre_selected or [])
     cursor = 0
     n = len(items)
 
     def render():
         for i, item in enumerate(items):
-            prefix = " >" if i == cursor else "  "
-            check = "\033[32m[x]\033[0m" if i in selected else "[ ]"
-            label = item["label"]
-            hint = item.get("hint", "")
+            is_cur = (i == cursor)
+            is_sel = (i in selected)
             detected = item.get("detected", False)
+            hint = item.get("hint", "")
 
-            if i == cursor:
-                label = f"\033[1m{label}\033[0m"
+            # Checkbox
+            if is_sel:
+                check = f"{_G}■{_R}"
+            elif is_cur:
+                check = f"{_C}□{_R}"
+            else:
+                check = f"{_D}□{_R}"
 
-            if hint:
-                if detected:
-                    hint_str = f"  \033[2m{hint}\033[0m"
-                else:
-                    hint_str = "  \033[2m(not detected)\033[0m"
+            # Label
+            label = item["label"]
+            if is_cur:
+                label = f"{_B}{label}{_R}"
+
+            # Hint
+            if hint and detected:
+                hint_str = f"  {_D}{hint}{_R}"
+            elif hint:
+                hint_str = f"  {_D}(not detected){_R}"
             else:
                 hint_str = ""
 
-            out.write(f"{prefix} {check} {label}{hint_str}\n")
+            # Cursor indicator
+            cur = f"{_C}›{_R}" if is_cur else " "
+
+            out.write(f"  {BAR}  {cur} {check} {label}{hint_str}\n")
 
     def clear():
         for _ in range(n):
             out.write("\033[1A\033[2K")
 
-    # Hide cursor
+    out.write(f"  {BAR}  {_D}↑/↓ navigate · space select · a all · enter confirm{_R}\n")
+    out.write(f"  {BAR}\n")
     out.write("\033[?25l")
     out.flush()
 
@@ -367,11 +433,11 @@ def multiselect(
                     selected = set(range(n))
             elif key in ("\r", "\n"):  # Enter = confirm
                 clear()
-                # Show final state (non-interactive)
                 for i, item in enumerate(items):
-                    check = "\033[32m[x]\033[0m" if i in selected else "\033[2m[ ]\033[0m"
-                    label = item["label"]
-                    out.write(f"   {check} {label}\n")
+                    if i in selected:
+                        out.write(f"  {BAR}    {_G}■{_R} {item['label']}\n")
+                    else:
+                        out.write(f"  {BAR}    {_D}□ {item['label']}{_R}\n")
                 out.flush()
                 return sorted(selected)
             elif key in ("\x03", "\x04"):  # Ctrl-C / Ctrl-D
@@ -441,6 +507,148 @@ def install_completions(shell: str, source_dir: str) -> Dict[str, Any]:
     return {"ok": True, "shell": shell, "path": dst}
 
 
+# ─── Skill / Custom Instructions ─────────────────────────────────────────────
+
+SKILL_MARKER = "<!-- bingo-light-skill -->"
+
+
+@dataclass
+class SkillTarget:
+    """Describes where to install the bingo-light skill/rules for one AI tool."""
+
+    id: str
+    name: str
+    dest_path: str        # ~ expanded at runtime
+    mode: str             # "copy" = drop file, "append" = append to existing file
+    detect_dirs: List[str] = field(default_factory=list)
+    detect_cmds: List[str] = field(default_factory=list)
+    note: str = ""
+
+    def expand_dest(self) -> str:
+        return os.path.expandvars(os.path.expanduser(self.dest_path))
+
+    def is_detected(self) -> bool:
+        for d in self.detect_dirs:
+            if os.path.isdir(os.path.expanduser(d)):
+                return True
+        for c in self.detect_cmds:
+            if shutil.which(c):
+                return True
+        return False
+
+
+def _get_skill_targets() -> List[SkillTarget]:
+    """Return all supported skill/rules targets."""
+    cline_rules = "~/Documents/Cline/Rules"
+
+    return [
+        SkillTarget(
+            id="claude-code",
+            name="Claude Code",
+            dest_path="~/.claude/commands/bingo.md",
+            mode="copy",
+            detect_dirs=["~/.claude"],
+            detect_cmds=["claude"],
+            note="/bingo slash command",
+        ),
+        SkillTarget(
+            id="windsurf",
+            name="Windsurf",
+            dest_path="~/.codeium/windsurf/memories/global_rules.md",
+            mode="append",
+            detect_dirs=["~/.codeium/windsurf"],
+            note="Appends to global rules (6000 char limit)",
+        ),
+        SkillTarget(
+            id="continue",
+            name="Continue",
+            dest_path="~/.continue/rules/bingo.md",
+            mode="copy",
+            detect_dirs=["~/.continue"],
+        ),
+        SkillTarget(
+            id="cline",
+            name="Cline",
+            dest_path=cline_rules + "/bingo.md",
+            mode="copy",
+            detect_dirs=[cline_rules],
+        ),
+        SkillTarget(
+            id="roo-code",
+            name="Roo Code",
+            dest_path="~/.roo/rules/bingo.md",
+            mode="copy",
+            detect_dirs=["~/.roo"],
+        ),
+        SkillTarget(
+            id="gemini-cli",
+            name="Gemini CLI",
+            dest_path="~/.gemini/GEMINI.md",
+            mode="append",
+            detect_dirs=["~/.gemini"],
+            detect_cmds=["gemini"],
+            note="Appends to GEMINI.md",
+        ),
+    ]
+
+
+def find_skill_file() -> Optional[str]:
+    """Find the bingo.md skill file in common locations."""
+    candidates = []
+
+    script_dir = os.path.dirname(os.path.abspath(sys.argv[0]))
+    candidates.append(os.path.join(script_dir, ".claude", "commands", "bingo.md"))
+
+    pkg_dir = os.path.dirname(os.path.abspath(__file__))
+    repo_dir = os.path.dirname(pkg_dir)
+    candidates.append(os.path.join(repo_dir, ".claude", "commands", "bingo.md"))
+
+    # npm package layout
+    candidates.append(os.path.join(script_dir, "..", ".claude", "commands", "bingo.md"))
+
+    for c in candidates:
+        if os.path.isfile(c):
+            return os.path.abspath(c)
+    return None
+
+
+def install_skill_to(target: SkillTarget, content: str) -> Dict[str, Any]:
+    """Install skill content to one target. Returns result dict."""
+    dest = target.expand_dest()
+    dest_dir = os.path.dirname(dest)
+
+    try:
+        os.makedirs(dest_dir, exist_ok=True)
+    except OSError as e:
+        return {"ok": False, "id": target.id, "error": str(e)}
+
+    try:
+        if target.mode == "copy":
+            with open(dest, "w") as f:
+                f.write(content)
+            return {"ok": True, "id": target.id, "path": dest, "action": "created"}
+
+        elif target.mode == "append":
+            # Check if already present
+            existing = ""
+            if os.path.isfile(dest):
+                with open(dest) as f:
+                    existing = f.read()
+            if SKILL_MARKER in existing:
+                return {"ok": True, "id": target.id, "path": dest, "action": "unchanged"}
+            # Append with marker
+            with open(dest, "a") as f:
+                if existing and not existing.endswith("\n"):
+                    f.write("\n")
+                f.write(f"\n{SKILL_MARKER}\n{content}\n")
+            return {"ok": True, "id": target.id, "path": dest, "action": "appended"}
+
+    except OSError as e:
+        return {"ok": False, "id": target.id, "error": str(e)}
+
+    return {"ok": False, "id": target.id, "error": "Unknown mode"}
+
+
 # ─── Main Setup Flow ────────────────────────────────────────────────────────
 
 
@@ -453,19 +661,24 @@ def run_setup(
 
     Returns a result dict summarizing what was configured.
     """
+    from bingo_core import VERSION
+
     out = sys.stderr
     tools = _get_tools()
     command, args = find_mcp_server()
     results: List[Dict[str, Any]] = []
     is_tty = hasattr(sys.stderr, "isatty") and sys.stderr.isatty()
 
-    # ── Header ──
+    # ═════════════════════════════════════════════════════════════════════════
+    # Header
+    # ═════════════════════════════════════════════════════════════════════════
     if not json_mode and is_tty:
-        out.write("\n  \033[1mbingo-light setup\033[0m\n")
-        out.write("  \033[2mConfigure MCP server for your AI tools\033[0m\n\n")
-        out.write(f"  MCP server: \033[2m{command} {' '.join(args)}\033[0m\n\n")
+        _ui_header(out, VERSION)
+        _ui_info(out, f"MCP server: {command} {' '.join(args)}")
 
-    # ── Detect tools ──
+    # ═════════════════════════════════════════════════════════════════════════
+    # Step 1: MCP Server Configuration
+    # ═════════════════════════════════════════════════════════════════════════
     items = []
     detected_indices = []
     for i, tool in enumerate(tools):
@@ -478,72 +691,147 @@ def run_setup(
         if detected:
             detected_indices.append(i)
 
-    # ── Select tools ──
+    if not json_mode and is_tty:
+        _ui_section(out, "MCP Server", "Connect bingo-light tools to your AI coding assistants")
+
     if yes:
-        # Non-interactive: configure all detected tools
         selected = detected_indices
         if not json_mode and is_tty:
-            out.write("  Auto-configuring detected tools:\n")
             for i in selected:
-                out.write(f"   \033[32m[x]\033[0m {tools[i].name}\n")
-            out.write("\n")
+                out.write(f"  {BAR}    {_G}■{_R} {tools[i].name}\n")
     elif is_tty:
-        # Interactive multi-select
-        out.write("  Select tools to configure:\n")
-        out.write("  \033[2m↑/↓ navigate  SPACE select  a toggle all  ENTER confirm\033[0m\n\n")
-        selected = multiselect(items, pre_selected=detected_indices)
-        out.write("\n")
+        selected = multiselect(out, items, pre_selected=detected_indices)
     else:
-        # Non-TTY fallback: configure detected tools
         selected = detected_indices
 
     if not selected:
         if not json_mode and is_tty:
-            out.write("  No tools selected.\n\n")
-        return {"ok": True, "configured": [], "skipped": True}
+            _ui_skip(out, "No tools selected")
 
-    # ── Configure each selected tool ──
+    # Configure each selected tool
     for idx in selected:
         tool = tools[idx]
         result = write_mcp_config(tool, command, args)
         results.append(result)
-
         if not json_mode and is_tty:
             if result["ok"]:
-                path = _tildify(result["config_path"])
-                out.write(f"  \033[32m✓\033[0m {tool.name} → {path}\n")
+                _ui_ok(out, f"{tool.name} → {_tildify(result['config_path'])}")
             else:
-                out.write(f"  \033[31mx\033[0m {tool.name}: {result.get('error', 'unknown error')}\n")
+                _ui_fail(out, f"{tool.name}: {result.get('error', '?')}")
+
+    # ═════════════════════════════════════════════════════════════════════════
+    # Step 2: Skills / Custom Instructions
+    # ═════════════════════════════════════════════════════════════════════════
+    skill_results: List[Dict[str, Any]] = []
+    skill_src = find_skill_file()
+
+    if skill_src:
+        with open(skill_src) as f:
+            skill_content = f.read()
 
-    # ── Shell completions ──
+        skill_targets = _get_skill_targets()
+
+        if not json_mode and is_tty:
+            _ui_section(out, "Skills / Custom Instructions", "Teach your AI how to use bingo-light")
+
+        skill_items = []
+        skill_detected = []
+        for i, st in enumerate(skill_targets):
+            detected = st.is_detected()
+            hint = _tildify(st.expand_dest())
+            if st.note:
+                hint = f"{hint}  ({st.note})"
+            skill_items.append({
+                "label": st.name,
+                "hint": hint,
+                "detected": detected,
+            })
+            if detected:
+                skill_detected.append(i)
+
+        if yes:
+            skill_selected = skill_detected
+            if not json_mode and is_tty:
+                for i in skill_selected:
+                    out.write(f"  {BAR}    {_G}■{_R} {skill_targets[i].name}\n")
+        elif is_tty:
+            skill_selected = multiselect(out, skill_items, pre_selected=skill_detected)
+        else:
+            skill_selected = skill_detected
+
+        for idx in skill_selected:
+            st = skill_targets[idx]
+            sr = install_skill_to(st, skill_content)
+            skill_results.append(sr)
+            if not json_mode and is_tty:
+                if sr["ok"]:
+                    action = sr.get("action", "")
+                    suffix = f" {_D}({action}){_R}" if action == "unchanged" else ""
+                    _ui_ok(out, f"{st.name} → {_tildify(sr['path'])}{suffix}")
+                else:
+                    _ui_fail(out, f"{st.name}: {sr.get('error', '?')}")
+
+    # ═════════════════════════════════════════════════════════════════════════
+    # Step 3: Shell Completions
+    # ═════════════════════════════════════════════════════════════════════════
     if not no_completions:
         shell = detect_shell()
-        # Find source dir (completions/ alongside bingo-light script)
         script_dir = os.path.dirname(os.path.abspath(sys.argv[0]))
         pkg_dir = os.path.dirname(os.path.abspath(__file__))
-        source_dir = script_dir if os.path.isdir(os.path.join(script_dir, "completions")) else os.path.dirname(pkg_dir)
+        source_dir = (
+            script_dir if os.path.isdir(os.path.join(script_dir, "completions"))
+            else os.path.dirname(pkg_dir)
+        )
 
         if os.path.isdir(os.path.join(source_dir, "completions")):
+            if not json_mode and is_tty:
+                _ui_section(out, "Shell Completions")
             comp_result = install_completions(shell, source_dir)
             if not json_mode and is_tty:
                 if comp_result["ok"]:
-                    out.write(f"  \033[32m✓\033[0m {shell} completions installed\n")
+                    _ui_ok(out, f"{shell} → {_tildify(comp_result['path'])}")
                 else:
-                    out.write(f"  \033[2m⊘ {shell} completions: {comp_result.get('error', 'skipped')}\033[0m\n")
+                    _ui_skip(out, f"{shell}: {comp_result.get('error', 'skipped')}")
 
-    # ── Summary ──
+    # ═════════════════════════════════════════════════════════════════════════
+    # Summary
+    # ═════════════════════════════════════════════════════════════════════════
     configured = [r for r in results if r["ok"]]
     failed = [r for r in results if not r["ok"]]
+    skills_ok = [r for r in skill_results if r["ok"]]
+    skills_fail = [r for r in skill_results if not r["ok"]]
+    all_fail = len(failed) + len(skills_fail)
 
     if not json_mode and is_tty:
-        out.write(f"\n  \033[1m\033[32m✓ {len(configured)} tool(s) configured\033[0m")
-        if failed:
-            out.write(f", \033[31m{len(failed)} failed\033[0m")
-        out.write("\n\n")
+        parts = []
+        if configured:
+            parts.append(f"{len(configured)} MCP")
+        if skills_ok:
+            parts.append(f"{len(skills_ok)} skill(s)")
+        summary = " + ".join(parts) if parts else "0"
+
+        if all_fail:
+            _ui_done(out, f"{summary} configured, {all_fail} failed")
+        else:
+            _ui_done(out, f"{summary} configured — ready to go!")
+
+        # Next steps box
+        out.write(f"  {_D}┌─────────────────────────────────────────────────┐{_R}\n")
+        out.write(f"  {_D}│{_R}  {_B}Next steps:{_R}                                    {_D}│{_R}\n")
+        out.write(f"  {_D}│{_R}                                                 {_D}│{_R}\n")
+        out.write(f"  {_D}│{_R}    cd your-forked-project                      {_D}│{_R}\n")
+        out.write(f"  {_D}│{_R}    {_C}bingo-light init{_R} <upstream-url>              {_D}│{_R}\n")
+        out.write(f"  {_D}│{_R}    {_C}bingo-light sync{_R}                              {_D}│{_R}\n")
+        out.write(f"  {_D}│{_R}                                                 {_D}│{_R}\n")
+        out.write(f"  {_D}│{_R}  Re-run anytime: {_C}bingo-light setup{_R}              {_D}│{_R}\n")
+        out.write(f"  {_D}└─────────────────────────────────────────────────┘{_R}\n")
+        out.write("\n")
 
     return {
-        "ok": len(failed) == 0,
+        "ok": all_fail == 0,
         "configured": [r["tool"] for r in configured],
         "failed": [r["tool"] for r in failed],
+        "skills": [r["id"] for r in skills_ok],
         "results": results,
+        "skill_results": skill_results,
     }

package/mcp-server.py

@@ -754,7 +754,7 @@ def main():
                 "capabilities": {"tools": {}},
                 "serverInfo": {
                     "name": "bingo-light",
-                    "version": "2.0.0",
+                    "version": "2.1.0",
                 },
             }))
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bingo-light",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "AI-native fork maintenance — manage customizations as a clean patch stack on top of upstream",
   "keywords": ["git", "fork", "patch", "mcp", "ai", "maintenance", "upstream", "rebase"],
   "homepage": "https://github.com/DanOps-1/bingo-light",
@@ -23,6 +23,7 @@
     "mcp-server.py",
     "bingo_core/*.py",
     "completions/",
+    ".claude/commands/bingo.md",
     "LICENSE",
     "README.md"
   ],