spex-cli 0.1.0__py3-none-any.whl

spex_cli/__init__.py

@@ -0,0 +1,69 @@
+from rich.align import Align
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from spex_cli.spex import main as _main
+
+_BANNER_LINES = [
+    " ███████╗██████╗ ███████╗██╗  ██╗",
+    " ██╔════╝██╔══██╗██╔════╝╚██╗██╔╝",
+    " ███████╗██████╔╝█████╗   ╚███╔╝ ",
+    " ╚════██║██╔═══╝ ██╔══╝   ██╔██╗ ",
+    " ███████║██║     ███████╗██╔╝ ██╗",
+    " ╚══════╝╚═╝     ╚══════╝╚═╝  ╚═╝",
+]
+
+_ROW_COLORS = [
+    "#F97316",
+    "#F97316",
+    "#FBBF24",
+    "#FBBF24",
+    "#EC4899",
+    "#EC4899",
+]
+
+
+def print_banner() -> None:
+    console = Console(stderr=True)
+
+    art = Text(justify="center")
+    for i, (line, color) in enumerate(zip(_BANNER_LINES, _ROW_COLORS)):
+        art.append(line, style=f"bold {color}")
+        if i < len(_BANNER_LINES) - 1:
+            art.append("\n")
+
+    subtitle = Text(justify="center")
+    subtitle.append("Autonomous Engineering experience", style="bold #8B5CF6")
+    subtitle.append("  ·  ", style="dim")
+    subtitle.append("v0.1.0", style="#FBBF24")
+
+    console.print(
+        Panel(
+            Align.center(Text.assemble(art, "\n\n", subtitle)),
+            border_style="#8B5CF6",
+            padding=(1, 4),
+        )
+    )
+
+
+_BANNER_COMMANDS = frozenset({"healthcheck", "enable", "disable"})
+
+
+def _should_show_banner() -> bool:
+    import sys
+    args = sys.argv[1:]
+    if not args:
+        return True
+    first = args[0]
+    if first in ("-h", "--help"):
+        return True
+    if first in _BANNER_COMMANDS:
+        return True
+    return False
+
+
+def main() -> None:
+    if _should_show_banner():
+        print_banner()
+    _main()

spex_cli/_help.py

@@ -0,0 +1,130 @@
+import json
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+_console = Console()
+
+_COMMANDS = [
+    ("Developers", [
+        ("enable",      [], "Set up spex in the current repository"),
+        ("disable",     [], "Remove spex git hook and revert agent settings"),
+        ("healthcheck", [], "Audit hooks and memory integrity"),
+    ]),
+    ("Memory", [
+        ("requirement", ["add", "deprecate"],                  "Track functional and non-functional requirements"),
+        ("decision",    ["add", "deprecate"],                  "Record technical decisions with rationale and impact"),
+        ("policy",      ["add", "deprecate"],                  "Project-wide policies and guidelines"),
+        ("app",         ["add", "update"],                     "Register applications and libraries"),
+        ("plan",        ["add", "update-status", "deprecate"], "Feature planning lifecycle"),
+    ]),
+    ("System", [
+        ("trace", ["add"],               "Link commits to decisions via git trailers"),
+        ("blame", ["<file>[:<lines>]"],  "Find decisions and requirements for a file or line range"),
+        ("validate-and-route", ["--feature-name", "--target-state"], "Enforce state machine transitions"),
+    ]),
+]
+
+_SUBCOMMANDS = {
+    "requirement": [
+        ("add",       "Add a new requirement to memory"),
+        ("deprecate", "Deprecate an existing requirement"),
+    ],
+    "decision": [
+        ("add",       "Add a new technical decision"),
+        ("deprecate", "Mark a decision as obsolete"),
+    ],
+    "policy": [
+        ("add",       "Add a new project-wide policy or guideline"),
+        ("deprecate", "Deprecate an existing policy"),
+    ],
+    "app": [
+        ("add",    "Register a new application or library"),
+        ("update", "Update app or library details"),
+    ],
+    "plan": [
+        ("add",           "Create a new feature plan"),
+        ("update-status", "Update the current status of a plan"),
+        ("deprecate",     "Abandon a plan"),
+    ],
+    "trace": [
+        ("add", "Link a commit hash to a decision"),
+    ],
+}
+
+
+def print_help() -> None:
+    _console.print()
+    _console.print(
+        "  [bold]Usage:[/bold]  [bold #F97316]spex[/bold #F97316] "
+        "[#FBBF24]<command>[/#FBBF24] [dim][options][/dim]"
+    )
+    _console.print()
+
+    for section, commands in _COMMANDS:
+        _console.rule(f"[bold #8B5CF6] {section} [/bold #8B5CF6]", style="dim #8B5CF6")
+        _console.print()
+
+        table = Table(box=None, padding=(0, 2, 0, 4), show_header=False, expand=False)
+        table.add_column("cmd",     style="bold #F97316", no_wrap=True)
+        table.add_column("actions", no_wrap=True)
+        table.add_column("desc",    style="dim", no_wrap=False)
+
+        for cmd, actions, desc in commands:
+            action_text = Text()
+            for i, action in enumerate(actions):
+                if i > 0:
+                    action_text.append("  ", style="dim")
+                action_text.append(action, style="#FBBF24")
+            table.add_row(cmd, action_text, desc)
+
+        _console.print(table)
+        _console.print()
+
+    _console.print(
+        "  [dim]Run [/dim][bold #F97316]spex[/bold #F97316]"
+        " [dim]<command> --help for more information.[/dim]"
+    )
+    _console.print()
+
+
+def print_subcommand_help(command: str) -> None:
+    actions = _SUBCOMMANDS.get(command, [])
+    _console.print()
+    _console.rule(
+        f"[bold #8B5CF6] spex {command} [/bold #8B5CF6]",
+        style="dim #8B5CF6",
+    )
+    _console.print()
+
+    table = Table(box=None, padding=(0, 2, 0, 4), show_header=False, expand=False)
+    table.add_column("action", style="bold #FBBF24", no_wrap=True)
+    table.add_column("desc",   style="dim", no_wrap=True)
+
+    for action, desc in actions:
+        table.add_row(action, desc)
+
+    _console.print(table)
+    _console.print()
+    _console.print(
+        f"  [dim]Run [/dim][bold #F97316]spex {command}[/bold #F97316]"
+        " [dim]<action> --help for details.[/dim]"
+    )
+    _console.print()
+
+
+def print_help_json() -> None:
+    output = {
+        "usage": "spex <command> [options]",
+        "sections": [
+            {
+                "section": section,
+                "commands": [
+                    {"name": cmd, "actions": actions, "description": desc}
+                    for cmd, actions, desc in commands
+                ],
+            }
+            for section, commands in _COMMANDS
+        ],
+    }
+    print(json.dumps(output, indent=2))

spex_cli/agents.py

@@ -0,0 +1,33 @@
+AGENT_CONFIG = {
+    "claude": {
+        "name": "Claude Code",
+        "folder": ".claude/",
+        "settings_file": "claude_settings/settings.json",
+    },
+    "gemini": {
+        "name": "Gemini CLI",
+        "folder": ".gemini/",
+        "settings_file": "claude_settings/settings.json"
+    },
+    "cursor-agent": {
+        "name": "Cursor",
+        "folder": ".cursor/",
+        "settings_file": "claude_settings/settings.json"
+    },
+    "opencode": {
+        "name": "opencode",
+        "folder": ".opencode/"
+    },
+    "codex": {
+        "name": "Codex CLI",
+        "folder": ".codex/"
+    },
+    "agy": {
+        "name": "Antigravity",
+        "folder": ".agent/"
+    },
+    "copilot": {
+        "name": "GitHub Copilot",
+        "folder": ".github/"
+    }
+}

spex_cli/claude_settings/settings.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 .spex/scripts/spex.py:*)",
+      "Bash(python .spex/scripts/spex.py:*)",
+      "Edit(.spex/**)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cat .spex/init.md"
+          }
+        ]
+      }
+    ]
+  }
+}

spex_cli/disable.py

@@ -0,0 +1,173 @@
+"""Disable command — removes spex git hook and reverts agent settings."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm
+from rich.text import Text
+
+from spex_cli.agents import AGENT_CONFIG
+from spex_cli.enable import _agent_settings_src, _select_agent
+
+console = Console()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _deep_remove(base: dict, to_remove: dict) -> dict:
+    """Return base with all entries present in to_remove subtracted."""
+    result = dict(base)
+    for key, value in to_remove.items():
+        if key not in result:
+            continue
+        if isinstance(result[key], dict) and isinstance(value, dict):
+            cleaned = _deep_remove(result[key], value)
+            if cleaned:
+                result[key] = cleaned
+            else:
+                del result[key]
+        elif isinstance(result[key], list) and isinstance(value, list):
+            spex_set = {json.dumps(item, sort_keys=True) for item in value}
+            result[key] = [
+                item for item in result[key]
+                if json.dumps(item, sort_keys=True) not in spex_set
+            ]
+            if not result[key]:
+                del result[key]
+        else:
+            if result[key] == value:
+                del result[key]
+    return result
+
+
+def _revert_agent_settings(repo_root: Path, agent_key: str) -> bool:
+    """Remove spex entries from the agent's settings.json. Returns True if file was updated."""
+    src = _agent_settings_src(agent_key)
+    if src is None:
+        return False
+
+    dst = repo_root / AGENT_CONFIG[agent_key]["folder"] / "settings.json"
+    if not dst.exists():
+        return False
+
+    with open(dst) as f:
+        existing = json.load(f)
+    with open(src) as f:
+        spex_settings = json.load(f)
+
+    cleaned = _deep_remove(existing, spex_settings)
+
+    with open(dst, "w") as f:
+        json.dump(cleaned, f, indent=2)
+        f.write("\n")
+
+    return True
+
+
+def _remove_git_hook(repo_root: Path) -> bool:
+    """Unset core.hooksPath if it points to .spex/hooks. Returns True if unset."""
+    result = subprocess.run(
+        ["git", "config", "core.hooksPath"],
+        capture_output=True,
+        text=True,
+        cwd=str(repo_root),
+    )
+    if result.returncode != 0 or result.stdout.strip() != ".spex/hooks":
+        return False
+
+    subprocess.run(
+        ["git", "config", "--unset", "core.hooksPath"],
+        check=True,
+        cwd=str(repo_root),
+    )
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def run_disable() -> None:
+    try:
+        repo_root = Path(
+            subprocess.check_output(
+                ["git", "rev-parse", "--show-toplevel"],
+                text=True,
+                stderr=subprocess.DEVNULL,
+            ).strip()
+        )
+    except subprocess.CalledProcessError:
+        console.print(
+            Panel(
+                "[red]Not inside a git repository.[/red]\n"
+                "Run [bold]spex disable[/bold] from within a git-tracked project.",
+                border_style="red",
+                title="Error",
+            )
+        )
+        sys.exit(1)
+
+    console.print(
+        Panel(
+            Text.assemble(
+                ("Disabling Spex for this repository\n", "bold white"),
+                (str(repo_root), "dim"),
+            ),
+            border_style="#EC4899",
+            padding=(0, 2),
+        )
+    )
+
+    # ── Interactive prompts (collected up front) ────────────────────────────
+    console.print()
+    console.print("[bold #FBBF24]Step 1[/bold #FBBF24]  Select your AI agent")
+    agent_key = _select_agent()
+    agent_name = AGENT_CONFIG[agent_key]["name"]
+
+    console.print()
+    confirmed = Confirm.ask(
+        f"  Remove spex git hook and revert [bold]{agent_name}[/bold] settings?",
+        default=False,
+    )
+    if not confirmed:
+        console.print("\n  [dim]Aborted.[/dim]")
+        sys.exit(0)
+
+    # ── Execution ────────────────────────────────────────────────────────────
+    console.print()
+    console.print("[bold #FBBF24]Step 2[/bold #FBBF24]  Removing git hook")
+    if _remove_git_hook(repo_root):
+        console.print("  [green]✓[/green] [bold]core.hooksPath[/bold] unset")
+    else:
+        console.print("  [dim]–[/dim] core.hooksPath was not pointing to .spex/hooks, skipped")
+
+    agent_settings_src = _agent_settings_src(agent_key)
+    if agent_settings_src is not None:
+        console.print()
+        console.print("[bold #FBBF24]Step 3[/bold #FBBF24]  Reverting agent settings")
+        agent_folder = AGENT_CONFIG[agent_key]["folder"]
+        if _revert_agent_settings(repo_root, agent_key):
+            console.print(f"  [green]✓[/green] Spex entries removed from [bold]{agent_folder}settings.json[/bold]")
+        else:
+            console.print(f"  [dim]–[/dim] {agent_folder}settings.json not found or nothing to revert")
+
+    # ── Done ────────────────────────────────────────────────────────────────
+    console.print()
+    console.print(
+        Panel(
+            Text.assemble(
+                ("Spex disabled.\n\n", "bold #EC4899"),
+                ("Your memory (", "white"),
+                (".spex/memory/", "bold"),
+                (") has not been touched.", "white"),
+            ),
+            border_style="#EC4899",
+            padding=(1, 2),
+        )
+    )