bingo-light 2.0.0

package/bingo_core/state.py

@@ -0,0 +1,306 @@
+"""
+bingo_core.state — State management (.bingo/ directory) for bingo-light.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+from datetime import datetime, timezone
+from typing import List, Optional, Tuple
+
+from bingo_core import (
+    BINGO_DIR,
+    CIRCUIT_BREAKER_LIMIT,
+    SYNC_HISTORY_MAX,
+)
+from bingo_core.exceptions import BingoError
+
+
+class State:
+    """Manages .bingo/ directory state: undo, circuit breaker, metadata, etc."""
+
+    def __init__(self, repo_dir: str):
+        self.repo_dir = repo_dir
+        self.bingo_dir = os.path.join(repo_dir, BINGO_DIR)
+        self.metadata_file = os.path.join(self.bingo_dir, "metadata.json")
+        self.sync_history_file = os.path.join(self.bingo_dir, "sync-history.json")
+        self.session_file = os.path.join(self.bingo_dir, "session.md")
+
+    def _ensure_dir(self) -> None:
+        """Create .bingo/ directory if it doesn't exist."""
+        os.makedirs(self.bingo_dir, exist_ok=True)
+
+    def acquire_lock(self) -> None:
+        """Acquire an exclusive operation lock. Raises BingoError if locked."""
+        self._ensure_dir()
+        lock_path = os.path.join(self.bingo_dir, ".lock")
+        if os.path.isfile(lock_path):
+            try:
+                with open(lock_path) as f:
+                    pid = int(f.read().strip())
+                # Check if the locking process is still running
+                os.kill(pid, 0)
+                raise BingoError(
+                    f"Another bingo-light operation is in progress (pid {pid}). "
+                    "If this is stale, remove .bingo/.lock"
+                )
+            except (ValueError, OSError):
+                pass  # Stale lock — process is gone
+        with open(lock_path, "w") as f:
+            f.write(str(os.getpid()))
+
+    def release_lock(self) -> None:
+        """Release the operation lock."""
+        lock_path = os.path.join(self.bingo_dir, ".lock")
+        try:
+            os.unlink(lock_path)
+        except OSError:
+            pass
+
+    # -- Undo --
+
+    def save_undo(self, head: str, tracking: str) -> None:
+        """Save undo state for rollback."""
+        self._ensure_dir()
+        self._write(os.path.join(self.bingo_dir, ".undo-head"), head)
+        self._write(os.path.join(self.bingo_dir, ".undo-tracking"), tracking)
+        # Clear undo marker -- new sync starts a new cycle
+        self._remove(os.path.join(self.bingo_dir, ".undo-active"))
+
+    def load_undo(self) -> Tuple[Optional[str], Optional[str]]:
+        """Load saved undo state. Returns (head, tracking) or (None, None)."""
+        head = self._read(os.path.join(self.bingo_dir, ".undo-head"))
+        tracking = self._read(os.path.join(self.bingo_dir, ".undo-tracking"))
+        return head, tracking
+
+    def mark_undo_active(self) -> None:
+        """Mark that undo was used -- prevents _fix_stale_tracking from auto-advancing."""
+        self._ensure_dir()
+        self._write(os.path.join(self.bingo_dir, ".undo-active"), "")
+
+    def is_undo_active(self) -> bool:
+        """Check if undo marker is set."""
+        return os.path.isfile(os.path.join(self.bingo_dir, ".undo-active"))
+
+    def clear_undo_tracking(self) -> None:
+        """Remove the undo tracking file after restoring."""
+        self._remove(os.path.join(self.bingo_dir, ".undo-tracking"))
+
+    # -- Circuit Breaker --
+
+    def check_circuit_breaker(self, upstream_target: str) -> bool:
+        """Check if circuit breaker is tripped (3+ failures on same commit).
+
+        Returns True if we should STOP (breaker is tripped).
+        """
+        path = os.path.join(self.bingo_dir, ".sync-failures")
+        if not os.path.isfile(path):
+            return False
+        try:
+            content = self._read(path)
+            if content is None:
+                return False
+            lines = content.strip().split("\n")
+            if len(lines) < 2:
+                return False
+            target = lines[0]
+            count = int(lines[1])
+            return target == upstream_target and count >= CIRCUIT_BREAKER_LIMIT
+        except (ValueError, IndexError):
+            return False
+
+    def record_circuit_breaker(self, upstream_target: str) -> None:
+        """Record a sync failure for circuit breaker."""
+        self._ensure_dir()
+        path = os.path.join(self.bingo_dir, ".sync-failures")
+        prev_count = 0
+        if os.path.isfile(path):
+            try:
+                content = self._read(path)
+                if content:
+                    lines = content.strip().split("\n")
+                    if len(lines) >= 2 and lines[0] == upstream_target:
+                        prev_count = int(lines[1])
+            except (ValueError, IndexError):
+                pass
+        self._write(path, f"{upstream_target}\n{prev_count + 1}")
+
+    def clear_circuit_breaker(self) -> None:
+        """Reset circuit breaker on success."""
+        self._remove(os.path.join(self.bingo_dir, ".sync-failures"))
+
+    # -- Metadata --
+
+    def _load_metadata(self) -> dict:
+        """Load metadata.json, creating it if needed."""
+        self._ensure_dir()
+        if not os.path.isfile(self.metadata_file):
+            return {"patches": {}}
+        try:
+            with open(self.metadata_file) as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return {"patches": {}}
+
+    def _save_metadata(self, data: dict) -> None:
+        """Atomically write metadata.json."""
+        self._ensure_dir()
+        self._write_json(self.metadata_file, data)
+
+    def patch_meta_get(self, patch_name: str) -> dict:
+        """Get metadata for a patch."""
+        data = self._load_metadata()
+        return data.get("patches", {}).get(
+            patch_name,
+            {
+                "reason": "",
+                "tags": [],
+                "expires": None,
+                "upstream_pr": "",
+                "status": "permanent",
+            },
+        )
+
+    def patch_meta_set(self, patch_name: str, key: str, value: str) -> None:
+        """Set a metadata field for a patch."""
+        data = self._load_metadata()
+        patches = data.setdefault("patches", {})
+        p = patches.setdefault(
+            patch_name,
+            {
+                "reason": "",
+                "tags": [],
+                "expires": None,
+                "upstream_pr": "",
+                "status": "permanent",
+                "created": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            },
+        )
+        if key in ("tag", "tags"):
+            tags_list = p.setdefault("tags", [])
+            for t in (v.strip() for v in value.split(",")):
+                if t and t not in tags_list:
+                    tags_list.append(t)
+        elif key in ("reason", "expires", "upstream_pr", "status"):
+            p[key] = value
+        self._save_metadata(data)
+
+    # -- Sync History --
+
+    def record_sync(
+        self,
+        behind: int,
+        upstream_before: str,
+        upstream_after: str,
+        patches: List[dict],
+    ) -> None:
+        """Record a sync event."""
+        self._ensure_dir()
+        data: dict = {"syncs": []}
+        if os.path.isfile(self.sync_history_file):
+            try:
+                with open(self.sync_history_file) as f:
+                    data = json.load(f)
+            except (json.JSONDecodeError, IOError):
+                data = {"syncs": []}
+
+        data["syncs"].append(
+            {
+                "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                "upstream_before": upstream_before,
+                "upstream_after": upstream_after,
+                "upstream_commits_integrated": behind,
+                "patches": patches,
+            }
+        )
+        # Keep only the last N entries
+        data["syncs"] = data["syncs"][-SYNC_HISTORY_MAX:]
+        self._write_json(self.sync_history_file, data)
+
+    def get_sync_history(self) -> dict:
+        """Get sync history."""
+        if not os.path.isfile(self.sync_history_file):
+            return {"syncs": []}
+        try:
+            with open(self.sync_history_file) as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return {"syncs": []}
+
+    # -- Session --
+
+    def update_session(self, content: str) -> None:
+        """Write session notes."""
+        self._ensure_dir()
+        self._write(self.session_file, content)
+
+    def get_session(self) -> Optional[str]:
+        """Read session notes."""
+        return self._read(self.session_file)
+
+    # -- Hooks --
+
+    def run_hook(self, event: str, data: Optional[dict] = None) -> None:
+        """Run a hook script if it exists: .bingo/hooks/<event>."""
+        hook_path = os.path.join(self.bingo_dir, "hooks", event)
+        if os.path.isfile(hook_path) and os.access(hook_path, os.X_OK):
+            try:
+                json_data = json.dumps(data or {})
+                result = subprocess.run(
+                    [hook_path],
+                    cwd=self.repo_dir,
+                    input=json_data,
+                    capture_output=True,
+                    text=True,
+                    timeout=30,
+                )
+                if result.returncode != 0:
+                    import sys
+                    print(
+                        f"warning: hook '{event}' exited {result.returncode}",
+                        file=sys.stderr,
+                    )
+            except subprocess.TimeoutExpired:
+                import sys
+                print(f"warning: hook '{event}' timed out", file=sys.stderr)
+            except OSError:
+                pass  # Hook not executable or missing interpreter
+
+    # -- Internal helpers --
+
+    def _write(self, path: str, content: str) -> None:
+        with open(path, "w") as f:
+            f.write(content)
+
+    def _read(self, path: str) -> Optional[str]:
+        if not os.path.isfile(path):
+            return None
+        try:
+            with open(path) as f:
+                return f.read().strip()
+        except IOError:
+            return None
+
+    def _remove(self, path: str) -> None:
+        try:
+            os.remove(path)
+        except FileNotFoundError:
+            pass
+
+    def _write_json(self, path: str, data: dict) -> None:
+        """Atomically write JSON file using temp file + rename."""
+        dir_name = os.path.dirname(path) or "."
+        fd, tmp_path = tempfile.mkstemp(suffix=".tmp", dir=dir_name)
+        try:
+            with os.fdopen(fd, "w") as f:
+                json.dump(data, f, indent=2)
+            os.replace(tmp_path, path)
+        except Exception:
+            try:
+                os.unlink(tmp_path)
+            except FileNotFoundError:
+                pass
+            raise

package/completions/bingo-light.bash

@@ -0,0 +1,118 @@
+# Bash completion for bingo-light
+# Source this file or place it in /etc/bash_completion.d/
+#
+# Usage:
+#   source bingo-light.bash
+#   # or
+#   cp bingo-light.bash /etc/bash_completion.d/bingo-light
+
+_bingo_light() {
+    local cur prev words cword
+    _init_completion || return
+
+    local -r toplevel_commands="init setup patch sync status doctor auto-sync log undo diff version help conflict-analyze conflict-resolve config history test workspace smart-sync session"
+    local -r toplevel_aliases="p s st d ws"
+    local -r all_toplevel="${toplevel_commands} ${toplevel_aliases}"
+
+    local -r patch_subcommands="new list show edit drop export import reorder squash meta"
+    local -r patch_aliases="ls add create rm remove"
+    local -r all_patch="${patch_subcommands} ${patch_aliases}"
+
+    # Walk backward through the command line to find the active command context.
+    local cmd=""
+    local subcmd=""
+    local i
+    for (( i=1; i < cword; i++ )); do
+        case "${words[i]}" in
+            patch|p)
+                cmd="patch"
+                ;;
+            sync|s)
+                cmd="sync"
+                ;;
+            status|st)
+                cmd="status"
+                ;;
+            diff|d)
+                cmd="diff"
+                ;;
+            init|setup|doctor|auto-sync|log|undo|version|help|conflict-analyze|conflict-resolve|config|history|test|workspace|ws|smart-sync|session)
+                cmd="${words[i]}"
+                ;;
+            *)
+                # If we already have a command, this may be a subcommand.
+                if [[ -n "$cmd" && -z "$subcmd" ]]; then
+                    subcmd="${words[i]}"
+                fi
+                ;;
+        esac
+    done
+
+    # ---- Completions based on context ----
+
+    # Inside "patch" (or alias "p") -- complete subcommands and flags
+    if [[ "$cmd" == "patch" ]]; then
+        # If a subcommand is already chosen, offer its flags
+        case "$subcmd" in
+            list|ls)
+                COMPREPLY=( $(compgen -W "-v --verbose --help -h" -- "$cur") )
+                return
+                ;;
+            new|add|create|show|edit|drop|rm|remove|export|import|reorder)
+                COMPREPLY=( $(compgen -W "--help -h" -- "$cur") )
+                return
+                ;;
+        esac
+
+        # No subcommand yet -- offer patch subcommands (including aliases)
+        if [[ "$cur" == -* ]]; then
+            COMPREPLY=( $(compgen -W "--help -h" -- "$cur") )
+        else
+            COMPREPLY=( $(compgen -W "${all_patch}" -- "$cur") )
+        fi
+        return
+    fi
+
+    # Inside "sync" (or alias "s") -- complete flags
+    if [[ "$cmd" == "sync" ]]; then
+        COMPREPLY=( $(compgen -W "--dry-run -n --force -f --help -h" -- "$cur") )
+        return
+    fi
+
+    # Inside "status" (or alias "st")
+    if [[ "$cmd" == "status" ]]; then
+        COMPREPLY=( $(compgen -W "--help -h" -- "$cur") )
+        return
+    fi
+
+    # Inside "diff" (or alias "d")
+    if [[ "$cmd" == "diff" ]]; then
+        COMPREPLY=( $(compgen -W "--help -h" -- "$cur") )
+        return
+    fi
+
+    # Inside "workspace" (or alias "ws") -- complete subcommands
+    if [[ "$cmd" == "workspace" || "$cmd" == "ws" ]]; then
+        if [[ -z "$subcmd" ]]; then
+            COMPREPLY=( $(compgen -W "init add remove list sync status" -- "$cur") )
+        else
+            COMPREPLY=( $(compgen -W "--help -h" -- "$cur") )
+        fi
+        return
+    fi
+
+    # Other known commands that take no further subcommands
+    if [[ -n "$cmd" ]]; then
+        COMPREPLY=( $(compgen -W "--help -h" -- "$cur") )
+        return
+    fi
+
+    # Top-level: no command selected yet
+    if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--help -h --version --json --yes -y" -- "$cur") )
+    else
+        COMPREPLY=( $(compgen -W "${all_toplevel}" -- "$cur") )
+    fi
+}
+
+complete -F _bingo_light bingo-light

package/completions/bingo-light.fish

@@ -0,0 +1,197 @@
+# Fish completion for bingo-light
+# Place in ~/.config/fish/completions/ or source directly.
+#
+# Usage:
+#   cp bingo-light.fish ~/.config/fish/completions/
+
+# ---- Helper: detect whether a specific command/subcommand is already on the line ----
+
+# Returns true when no subcommand has been given yet (top-level completions).
+function __bingo_light_needs_command
+    set -l cmd (commandline -opc)
+    if test (count $cmd) -eq 1
+        return 0
+    end
+    return 1
+end
+
+# Returns true when the first positional argument matches any of the supplied values.
+function __bingo_light_using_command
+    set -l cmd (commandline -opc)
+    if test (count $cmd) -lt 2
+        return 1
+    end
+    for arg in $argv
+        if test "$cmd[2]" = "$arg"
+            return 0
+        end
+    end
+    return 1
+end
+
+# Returns true when we are inside "patch" (or "p") and need a patch subcommand.
+function __bingo_light_patch_needs_subcommand
+    set -l cmd (commandline -opc)
+    if test (count $cmd) -lt 2
+        return 1
+    end
+    if test "$cmd[2]" != patch -a "$cmd[2]" != p
+        return 1
+    end
+    if test (count $cmd) -eq 2
+        return 0
+    end
+    return 1
+end
+
+# Returns true when the patch subcommand matches any of the supplied values.
+function __bingo_light_patch_using_subcommand
+    set -l cmd (commandline -opc)
+    if test (count $cmd) -lt 3
+        return 1
+    end
+    if test "$cmd[2]" != patch -a "$cmd[2]" != p
+        return 1
+    end
+    for arg in $argv
+        if test "$cmd[3]" = "$arg"
+            return 0
+        end
+    end
+    return 1
+end
+
+# ---- Disable file completions by default ----
+complete -c bingo-light -f
+
+# ---- Top-level commands ----
+complete -c bingo-light -n __bingo_light_needs_command -a init    -d 'Initialize a new bingo-light project'
+complete -c bingo-light -n __bingo_light_needs_command -a setup   -d 'Configure MCP for AI tools (interactive)'
+complete -c bingo-light -n __bingo_light_needs_command -a patch   -d 'Manage patches'
+complete -c bingo-light -n __bingo_light_needs_command -a sync    -d 'Synchronize changes with upstream'
+complete -c bingo-light -n __bingo_light_needs_command -a status  -d 'Show current status'
+complete -c bingo-light -n __bingo_light_needs_command -a doctor  -d 'Diagnose and fix common problems'
+complete -c bingo-light -n __bingo_light_needs_command -a auto-sync -d 'Enable or configure automatic synchronization'
+complete -c bingo-light -n __bingo_light_needs_command -a log     -d 'Show change log'
+complete -c bingo-light -n __bingo_light_needs_command -a undo    -d 'Undo the last operation'
+complete -c bingo-light -n __bingo_light_needs_command -a diff    -d 'Show differences between states'
+complete -c bingo-light -n __bingo_light_needs_command -a version -d 'Print version information'
+complete -c bingo-light -n __bingo_light_needs_command -a help    -d 'Show help for a command'
+complete -c bingo-light -n __bingo_light_needs_command -a conflict-analyze -d 'Analyze conflicts during rebase'
+complete -c bingo-light -n __bingo_light_needs_command -a conflict-resolve -d 'Resolve a conflict file and continue'
+complete -c bingo-light -n __bingo_light_needs_command -a config  -d 'Get/set/list configuration'
+complete -c bingo-light -n __bingo_light_needs_command -a history -d 'Show sync history with hash mappings'
+complete -c bingo-light -n __bingo_light_needs_command -a test    -d 'Run configured test suite'
+complete -c bingo-light -n __bingo_light_needs_command -a workspace -d 'Manage multiple forks'
+complete -c bingo-light -n __bingo_light_needs_command -a smart-sync -d 'Smart sync with circuit breaker and partial state'
+complete -c bingo-light -n __bingo_light_needs_command -a session -d 'Manage session memory'
+
+# Short aliases
+complete -c bingo-light -n __bingo_light_needs_command -a p  -d 'Alias for patch'
+complete -c bingo-light -n __bingo_light_needs_command -a s  -d 'Alias for sync'
+complete -c bingo-light -n __bingo_light_needs_command -a st -d 'Alias for status'
+complete -c bingo-light -n __bingo_light_needs_command -a d  -d 'Alias for diff'
+complete -c bingo-light -n __bingo_light_needs_command -a ws -d 'Alias for workspace'
+
+# Global flags
+complete -c bingo-light -n __bingo_light_needs_command -s h -l help    -d 'Show help'
+complete -c bingo-light -n __bingo_light_needs_command      -l version -d 'Show version'
+complete -c bingo-light                                    -l json    -d 'Output structured JSON'
+complete -c bingo-light                                    -l yes     -d 'Non-interactive mode, auto-confirm prompts'
+complete -c bingo-light                               -s y            -d 'Non-interactive mode (short for --yes)'
+
+# ---- sync flags (also alias "s") ----
+complete -c bingo-light -n '__bingo_light_using_command sync s' -s n -l dry-run -d 'Show what would be done without making changes'
+complete -c bingo-light -n '__bingo_light_using_command sync s' -s f -l force   -d 'Force sync, overwriting conflicts'
+complete -c bingo-light -n '__bingo_light_using_command sync s' -s t -l test    -d 'Run test suite after sync'
+complete -c bingo-light -n '__bingo_light_using_command sync s' -s h -l help    -d 'Show help'
+
+# ---- status flags (also alias "st") ----
+complete -c bingo-light -n '__bingo_light_using_command status st' -s h -l help -d 'Show help'
+
+# ---- diff flags (also alias "d") ----
+complete -c bingo-light -n '__bingo_light_using_command diff d' -s h -l help -d 'Show help'
+
+# ---- Simple commands (no subcommands, just --help) ----
+complete -c bingo-light -n '__bingo_light_using_command init'      -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_using_command doctor'    -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_using_command auto-sync' -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_using_command log'       -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_using_command undo'      -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_using_command version'   -s h -l help -d 'Show help'
+
+# ---- conflict-resolve flags ----
+complete -c bingo-light -n '__bingo_light_using_command conflict-resolve' -s h -l help -d 'Show help'
+
+# ---- help: complete with command names ----
+complete -c bingo-light -n '__bingo_light_using_command help' -a 'init setup patch sync status doctor auto-sync log undo diff version conflict-analyze conflict-resolve config history test workspace smart-sync session' -d 'Command'
+
+# ---- patch subcommands (also alias "p") ----
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a new     -d 'Create a new patch'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a list    -d 'List all patches'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a show    -d 'Show details of a patch'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a edit    -d 'Edit an existing patch'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a drop    -d 'Remove a patch'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a export  -d 'Export patches to files'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a import  -d 'Import patches from files'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a reorder -d 'Reorder the patch stack'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a squash  -d 'Squash two patches into one'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a meta    -d 'Get/set patch metadata'
+
+# Patch short aliases
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a ls     -d 'Alias for list'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a add    -d 'Alias for new'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a create -d 'Alias for new'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a rm     -d 'Alias for drop'
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -a remove -d 'Alias for drop'
+
+# Help flag for patch itself
+complete -c bingo-light -n __bingo_light_patch_needs_subcommand -s h -l help -d 'Show help'
+
+# ---- patch list / ls flags ----
+complete -c bingo-light -n '__bingo_light_patch_using_subcommand list ls' -s v -l verbose -d 'Show detailed patch information'
+complete -c bingo-light -n '__bingo_light_patch_using_subcommand list ls' -s h -l help    -d 'Show help'
+
+# ---- patch subcommands that only take --help ----
+complete -c bingo-light -n '__bingo_light_patch_using_subcommand new add create'    -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_patch_using_subcommand show'              -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_patch_using_subcommand edit'              -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_patch_using_subcommand drop rm remove'    -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_patch_using_subcommand export'            -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_patch_using_subcommand import'            -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_patch_using_subcommand reorder'           -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_patch_using_subcommand squash'            -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_patch_using_subcommand meta'              -s h -l help -d 'Show help'
+
+# ---- workspace subcommands (also alias "ws") ----
+
+# Returns true when we are inside "workspace" (or "ws") and need a workspace subcommand.
+function __bingo_light_workspace_needs_subcommand
+    set -l cmd (commandline -opc)
+    if test (count $cmd) -lt 2
+        return 1
+    end
+    if test "$cmd[2]" != workspace -a "$cmd[2]" != ws
+        return 1
+    end
+    if test (count $cmd) -eq 2
+        return 0
+    end
+    return 1
+end
+
+complete -c bingo-light -n __bingo_light_workspace_needs_subcommand -a init   -d 'Initialize workspace'
+complete -c bingo-light -n __bingo_light_workspace_needs_subcommand -a add    -d 'Add a repo to workspace'
+complete -c bingo-light -n __bingo_light_workspace_needs_subcommand -a remove -d 'Remove a repo from workspace'
+complete -c bingo-light -n __bingo_light_workspace_needs_subcommand -a list   -d 'List workspace repos'
+complete -c bingo-light -n __bingo_light_workspace_needs_subcommand -a sync   -d 'Sync all workspace repos'
+complete -c bingo-light -n __bingo_light_workspace_needs_subcommand -a status -d 'Show workspace status'
+
+# ---- New top-level command flags ----
+complete -c bingo-light -n '__bingo_light_using_command conflict-analyze' -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_using_command config'           -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_using_command history'          -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_using_command test'             -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_using_command workspace ws'     -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_using_command smart-sync'      -s h -l help -d 'Show help'
+complete -c bingo-light -n '__bingo_light_using_command session'         -s h -l help -d 'Show help'