holoctl 0.5.0__py3-none-any.whl

holoctl/__init__.py

@@ -0,0 +1,5 @@
+try:
+    from importlib.metadata import version
+    __version__ = version("holoctl")
+except Exception:
+    __version__ = "0.3.0"

holoctl/__main__.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+import sys
+
+if sys.platform == "win32":
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+import typer
+
+from .cli.init_ import app as _init_app, init_cmd
+from .cli.board import app as _board_app
+from .cli.compile_ import app as _compile_app, compile_cmd
+from .cli.sync_ import app as _sync_app, sync_cmd
+from .cli.doctor import app as _doctor_app, doctor_cmd
+from .cli.agent import app as _agent_app
+from .cli.repo import app as _repo_app
+from .cli.serve import app as _serve_app, serve_cmd
+from .cli.overview import app as _overview_app, overview_cmd
+from . import __version__
+
+app = typer.Typer(
+    name="holoctl",
+    help="Universal project operating system for AI coding assistants",
+    no_args_is_help=True,
+)
+
+# Sub-group commands
+app.add_typer(_board_app, name="board", help="Manage the project board")
+app.add_typer(_agent_app, name="agent", help="Manage agent definitions")
+app.add_typer(_repo_app, name="repo", help="Manage repos within a project")
+
+# Direct commands
+app.command("init")(init_cmd)
+app.command("compile")(compile_cmd)
+app.command("sync")(sync_cmd)
+app.command("doctor")(doctor_cmd)
+app.command("serve")(serve_cmd)
+app.command("overview")(overview_cmd)
+
+
+def _version_callback(value: bool):
+    if value:
+        print(__version__)
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    version: bool = typer.Option(None, "--version", "-v", callback=_version_callback, is_eager=True),
+    ctx: typer.Context = typer.Context,
+):
+    pass
+
+
+if __name__ == "__main__":
+    app()

holoctl/cli/_console.py

@@ -0,0 +1,4 @@
+from rich.console import Console
+
+# Force modern Windows terminal rendering — avoids cp1252 encoding errors on legacy console.
+console = Console(legacy_windows=False)

holoctl/cli/agent.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional
+
+import typer
+from ._console import console
+
+from ..lib.config import find_project_root
+from ..lib.markdown import parse_frontmatter
+
+app = typer.Typer(help="Manage agent definitions")
+
+
+def _require_root() -> Path:
+    root = find_project_root()
+    if not root:
+        console.print("[red]No .holoctl/ found. Run `holoctl init` first.[/red]")
+        raise typer.Exit(1)
+    return root
+
+
+@app.command("list")
+def agent_list():
+    """List configured agents."""
+    root = _require_root()
+    agents_dir = root / ".holoctl" / "agents"
+    if not agents_dir.exists():
+        console.print("[dim]No agents configured.[/dim]")
+        return
+
+    for f in sorted(agents_dir.glob("*.md")):
+        data, _ = parse_frontmatter(f.read_text(encoding="utf-8"))
+        model = data.get("model", "standard")
+        trigger = data.get("trigger", "ticket")
+        model_color = "magenta" if model == "reasoning" else "dim" if model == "fast" else "cyan"
+        name = data.get("name", f.stem)
+        console.print(
+            f"  [bold]{name:<16}[/bold] [{model_color}]{model:<10}[/{model_color}] "
+            f"[dim]{trigger:<16}[/dim] {data.get('description', '')}"
+        )
+
+
+@app.command("add")
+def agent_add(
+    name: str = typer.Argument(..., help="Agent name"),
+    from_template: Optional[str] = typer.Option(None, "--from", help="Base on an existing agent"),
+):
+    """Create a new agent definition."""
+    root = _require_root()
+    agents_dir = root / ".holoctl" / "agents"
+    target_path = agents_dir / f"{name}.md"
+
+    if target_path.exists():
+        console.print(f"[yellow]Agent {name} already exists.[/yellow]")
+        raise typer.Exit(1)
+
+    if from_template:
+        source = agents_dir / f"{from_template}.md"
+        if not source.exists():
+            console.print(f"[red]Template agent {from_template} not found.[/red]")
+            raise typer.Exit(1)
+        import re
+        content = source.read_text(encoding="utf-8")
+        content = re.sub(r"^(name:\s*).*$", rf"\g<1>{name}", content, flags=re.MULTILINE)
+        target_path.write_text(content, encoding="utf-8")
+    else:
+        target_path.write_text(
+            f"""---
+name: {name}
+description: "(describe what this agent does)"
+model: standard
+tools: [read, search, edit, write, shell]
+trigger: ticket
+---
+
+# Identity
+
+You are the **{name}** agent. (Define identity and purpose)
+
+# Guard Rail
+
+(Define when this agent should refuse to work)
+
+# Scope
+
+(Define what this agent does and does NOT do)
+
+# Work Order
+
+1. (Step-by-step work process)
+
+# Report Format
+
+- **Done**: bullets with file:line references.
+- **Definition of Done**: each Goal item marked `[x]` or `[ ]`.
+- **Suggested next step**: 1 line.
+""",
+            encoding="utf-8",
+        )
+
+    console.print(f"[green]Created agent: .holoctl/agents/{name}.md[/green]")

holoctl/cli/board.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+from ._console import console
+
+from ..lib.config import find_project_root, load_config
+from ..lib.board import Board
+
+app = typer.Typer(help="Manage the project board (tickets, statuses, sprints)")
+
+
+def _get_board() -> tuple[Board, dict, Path]:
+    root = find_project_root()
+    if not root:
+        console.print("[red]No .holoctl/ found. Run `holoctl init` first.[/red]")
+        raise typer.Exit(1)
+    config = load_config(root)
+    return Board(root, config), config, root
+
+
+@app.command("stat")
+def stat_cmd():
+    """Show ticket counts by status."""
+    board, _, _ = _get_board()
+    print(json.dumps(board.stat(), indent=2))
+
+
+@app.command("get")
+def get_cmd(ticket_id: str = typer.Argument(..., help="Ticket ID")):
+    """Get a single ticket by ID."""
+    board, _, _ = _get_board()
+    ticket = board.get(ticket_id)
+    if not ticket:
+        console.print(f"[red]Ticket {ticket_id} not found[/red]")
+        raise typer.Exit(1)
+    print(json.dumps(ticket, indent=2))
+
+
+@app.command("ls")
+def ls_cmd(
+    priority: Optional[str] = typer.Argument(None, help="Filter by priority (p0, p1, p2, p3)"),
+    sprint: Optional[str] = typer.Option(None, "--sprint"),
+    status: Optional[str] = typer.Option(None, "--status"),
+    agent: Optional[str] = typer.Option(None, "--agent"),
+    tag: Optional[str] = typer.Option(None, "--tag"),
+    project: Optional[str] = typer.Option(None, "--project", help="Filter by project (subdir name discovered in workspace)"),
+):
+    """List tickets with optional filters."""
+    board, _, _ = _get_board()
+    filters: dict = {}
+    if sprint:
+        filters["sprint"] = sprint
+    if status:
+        filters["status"] = status
+    if agent:
+        filters["agent"] = agent
+    if tag:
+        filters["tag"] = tag
+    if project:
+        filters["project"] = project
+    if priority and priority.startswith("p") and len(priority) == 2:
+        filters["priority"] = priority
+
+    tickets = board.ls(filters)
+    if not tickets:
+        console.print("[dim]No tickets match the filters.[/dim]")
+        return
+
+    for t in tickets:
+        dep = f" [dim][dep: {', '.join(t['depends'])}][/dim]" if t.get("depends") else ""
+        agents = ", ".join(t["agent"]) if t.get("agent") else "—"
+        agents_str = f"[green]{agents}[/green]"
+        console.print(
+            f"[bold]{t['id']}[/bold]  {_priority_color(t['priority'])}  "
+            f"{_status_color(t['status'])}  {(t.get('sprint') or '—'):<12}  "
+            f"{agents_str:<20}  {t['title'][:50]}{dep}"
+        )
+
+
+@app.command("move")
+def move_cmd(
+    ticket_id: str = typer.Argument(...),
+    status: str = typer.Argument(...),
+):
+    """Move a ticket to a new status."""
+    board, _, _ = _get_board()
+    try:
+        result = board.move(ticket_id, status)
+        console.print(f"{result['id']}: {result['from']} → [bold]{result['to']}[/bold]")
+    except (ValueError, KeyError) as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command("set")
+def set_cmd(
+    ticket_id: str = typer.Argument(...),
+    field: str = typer.Argument(...),
+    value: list[str] = typer.Argument(...),
+):
+    """Set a field on a ticket."""
+    board, _, _ = _get_board()
+    try:
+        result = board.set(ticket_id, field, " ".join(value))
+        console.print(f"{result['id']}.{result['field']} = {json.dumps(result['value'])}")
+    except (KeyError, ValueError) as e:
+        msg = str(e).strip("'")
+        console.print(f"[red]{msg}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command("add")
+def add_cmd(ticket_json: str = typer.Argument(..., help="JSON ticket data")):
+    """Create a new ticket from JSON."""
+    board, _, _ = _get_board()
+    try:
+        patch = json.loads(ticket_json)
+        ticket = board.add(patch)
+        console.print(f"[green]Created {ticket['id']}: {ticket['title']}[/green]")
+        print(json.dumps(ticket, indent=2))
+    except (json.JSONDecodeError, Exception) as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command("next-id")
+def next_id_cmd():
+    """Show the next available ticket ID."""
+    board, _, _ = _get_board()
+    print(board.next_id())
+
+
+@app.command("rebuild-index")
+def rebuild_index_cmd():
+    """Rebuild index.json from ticket .md files."""
+    board, _, _ = _get_board()
+    result = board.rebuild_index()
+    console.print(f"[green]Rebuilt index: {result['ticketCount']} tickets, nextId: {result['nextId']}[/green]")
+
+
+def _priority_color(p: str) -> str:
+    colors = {"p0": "red", "p1": "yellow", "p2": "blue", "p3": "dim"}
+    color = colors.get(p, "white")
+    return f"[{color}]{p:<2}[/{color}]"
+
+
+def _status_color(s: str) -> str:
+    colors = {"backlog": "dim", "doing": "cyan", "review": "yellow", "done": "green", "cancelled": "strike"}
+    color = colors.get(s, "white")
+    return f"[{color}]{s:<10}[/{color}]"

holoctl/cli/compile_.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+from typing import Optional
+
+import typer
+from ._console import console
+
+from ..lib.config import find_project_root, load_config
+from ..lib.compiler import compile_project
+
+app = typer.Typer()
+
+
+@app.command("compile")
+def compile_cmd(
+    target: Optional[str] = typer.Option(None, "--target", help="Target (claude, cursor, windsurf, copilot, generic)"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview without writing files"),
+):
+    """Compile .holoctl/ to tool-specific files."""
+    root = find_project_root()
+    if not root:
+        console.print("[red]No .holoctl/ found. Run `holoctl init` first.[/red]")
+        raise typer.Exit(1)
+
+    config = load_config(root)
+    targets = [target] if target else config.get("targets", ["claude"])
+
+    for t in targets:
+        try:
+            result = compile_project(root, config, t, dry_run=dry_run)
+            if dry_run:
+                console.print(f"[dim][dry-run] {t}:[/dim]")
+                for f in result["files"]:
+                    console.print(f"  [dim]would write[/dim] {f}")
+            else:
+                console.print(f"[green]✓ {t}[/green] [dim]({len(result['files'])} files)[/dim]")
+                for f in result["files"]:
+                    console.print(f"  [dim]→[/dim] {f}")
+        except ValueError as e:
+            console.print(f"[red]✗ {t}: {e}[/red]")

holoctl/cli/doctor.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+import json
+
+import typer
+from ._console import console
+
+from ..lib.config import find_project_root, load_config
+
+app = typer.Typer()
+
+
+_TARGET_OUTPUTS = {
+    "claude": ["CLAUDE.md", ".claude/commands"],
+    "cursor": [".cursor/commands", ".cursor/rules/holoctl.md"],
+    "windsurf": [".windsurfrules"],
+    "copilot": [".github/copilot-instructions.md"],
+    "devin": ["AGENTS.md", ".devin/skills"],
+}
+
+
+@app.command("doctor")
+def doctor_cmd():
+    """Check project health."""
+    root = find_project_root()
+    if not root:
+        console.print("[red]No .holoctl/ found. Run `holoctl init` first.[/red]")
+        raise typer.Exit(1)
+
+    console.print("\n  [bold]holoctl doctor[/bold]\n")
+    issues = 0
+    config = None
+
+    try:
+        config = load_config(root)
+        _check("Config", ".holoctl/config.json is valid", True)
+    except Exception as e:
+        _check("Config", f".holoctl/config.json: {e}", False)
+        issues += 1
+
+    # Index <-> .md sync
+    index_path = root / ".holoctl" / "board" / "index.json"
+    tickets_dir = root / ".holoctl" / "board" / "tickets"
+    if index_path.exists():
+        try:
+            data = json.loads(index_path.read_text(encoding="utf-8"))
+            indexed = {t["id"] for t in data.get("tickets", [])}
+            on_disk = set()
+            if tickets_dir.exists():
+                from ..lib.markdown import parse_frontmatter
+                for f in tickets_dir.glob("*.md"):
+                    if f.name.startswith("_"):
+                        continue
+                    fm, _ = parse_frontmatter(f.read_text(encoding="utf-8"))
+                    if fm.get("id"):
+                        on_disk.add(fm["id"])
+            drift = indexed.symmetric_difference(on_disk)
+            if drift:
+                _check("Board", f"index.json out of sync ({len(drift)} drift) — run `holoctl board rebuild-index`", False)
+                issues += 1
+            else:
+                _check("Board", f"index.json valid ({len(indexed)} tickets, in sync)", True)
+        except Exception as e:
+            _check("Board", f"index.json parse error: {e}", False)
+            issues += 1
+    else:
+        _check("Board", "index.json exists", False)
+        issues += 1
+
+    # Agents
+    agents_dir = root / ".holoctl" / "agents"
+    if agents_dir.exists():
+        agent_count = len(list(agents_dir.glob("*.md")))
+        ok = agent_count > 0
+        _check("Agents", f"{agent_count} agent(s) defined", ok)
+        if not ok:
+            issues += 1
+    else:
+        _check("Agents", "agents/ directory exists", False)
+        issues += 1
+
+    # Commands
+    commands_dir = root / ".holoctl" / "commands"
+    if commands_dir.exists():
+        cmd_count = len(list(commands_dir.glob("*.md")))
+        ok = cmd_count > 0
+        _check("Commands", f"{cmd_count} command(s) defined", ok)
+        if not ok:
+            issues += 1
+    else:
+        _check("Commands", "commands/ directory exists", False)
+        issues += 1
+
+    # Instructions
+    ok = (root / ".holoctl" / "instructions.md").exists()
+    _check("Instructions", "instructions.md exists", ok)
+    if not ok:
+        issues += 1
+
+    # Context
+    ok = (root / ".holoctl" / "context").exists()
+    _check("Context", "context/ directory exists", ok)
+    if not ok:
+        issues += 1
+
+    # Compile targets
+    if config:
+        targets = config.get("targets", [])
+        for tgt in targets:
+            outputs = _TARGET_OUTPUTS.get(tgt, [])
+            missing = [o for o in outputs if not (root / o).exists()]
+            if missing:
+                _check("Compile", f"target '{tgt}' missing: {', '.join(missing)} — run `holoctl compile`", False)
+                issues += 1
+            else:
+                _check("Compile", f"target '{tgt}' compiled", True)
+
+    console.print("")
+    if issues == 0:
+        console.print("[green]  All checks passed. Project is healthy.[/green]\n")
+    else:
+        console.print(f"[yellow]  {issues} issue(s) found.[/yellow]\n")
+
+
+def _check(category: str, message: str, ok: bool) -> None:
+    icon = "[green]✓[/green]" if ok else "[red]✗[/red]"
+    console.print(f"  {icon} [dim]{category:<14}[/dim] {message}")

holoctl/cli/init_.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+import json
+import re
+from pathlib import Path
+from typing import Optional
+
+import typer
+from ._console import console
+
+from ..lib.config import get_defaults, save_config
+from ..lib.templates import get_templates
+
+app = typer.Typer()
+
+
+@app.command("init")
+def init_cmd(
+    name: Optional[str] = typer.Option(None, "--name", help="Project name"),
+    prefix: Optional[str] = typer.Option(None, "--prefix", help="Ticket ID prefix (e.g. MP)"),
+    targets: Optional[str] = typer.Option(None, "--targets", help="Compile targets (claude,cursor,windsurf,copilot)"),
+    skip_compile: bool = typer.Option(False, "--skip-compile", help="Skip auto-compile after init"),
+):
+    """Initialize .holoctl/ in the current directory."""
+    cwd = Path.cwd()
+    holoctl_dir = cwd / ".holoctl"
+
+    if (holoctl_dir / "config.json").exists():
+        console.print("[yellow].holoctl/ already exists in this directory.[/yellow]")
+        raise typer.Exit(1)
+
+    project_name = name or cwd.name
+    project_prefix = prefix or _derive_prefix(project_name)
+    target_list = [t.strip() for t in targets.split(",")] if targets else ["claude"]
+
+    config = get_defaults()
+    config["project"]["name"] = project_name
+    config["project"]["prefix"] = project_prefix
+    config["targets"] = target_list
+
+    console.print(f"\n  [bold]holoctl init[/bold]\n")
+    console.print(f"  Project:  [green]{project_name}[/green]")
+    console.print(f"  Prefix:   [green]{project_prefix}[/green] (tickets: {project_prefix}-001, {project_prefix}-002, ...)")
+    console.print(f"  Targets:  [green]{', '.join(target_list)}[/green]")
+    console.print("")
+
+    dirs = [
+        ".holoctl",
+        ".holoctl/board",
+        ".holoctl/board/tickets",
+        ".holoctl/agents",
+        ".holoctl/commands",
+        ".holoctl/context",
+        ".holoctl/context/decisions",
+        ".holoctl/context/documents",
+    ]
+    for d in dirs:
+        (cwd / d).mkdir(parents=True, exist_ok=True)
+
+    save_config(cwd, config)
+
+    templates = get_templates(config)
+    for rel_path, content in templates.items():
+        full_path = cwd / rel_path
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+        full_path.write_text(content, encoding="utf-8")
+
+    index_data = {
+        "meta": {"version": 1, "updated": _today(), "nextId": 1, "counts": {}},
+        "tickets": [],
+    }
+    (cwd / ".holoctl" / "board" / "index.json").write_text(
+        json.dumps(index_data, indent="\t") + "\n", encoding="utf-8"
+    )
+    (cwd / ".holoctl" / "activity.jsonl").write_text("", encoding="utf-8")
+
+    console.print(f"  [green]✓ .holoctl/ initialized successfully.[/green]\n")
+
+    if not skip_compile:
+        from ..lib.compiler import compile_project
+        for tgt in target_list:
+            try:
+                result = compile_project(cwd, config, tgt, dry_run=False)
+                count = len(result.get("files", []))
+                console.print(f"  [green]✓ compiled[/green] [bold]{tgt}[/bold] [dim]({count} files)[/dim]")
+            except Exception as e:
+                console.print(f"  [red]✗ compile {tgt}:[/red] {e}")
+
+    console.print("")
+    console.print("  Next steps:")
+    console.print(f"    [dim]$[/dim] holoctl board add '{{\"title\":\"My first ticket\",\"agent\":\"developer\"}}'")
+    console.print(f"    [dim]$[/dim] holoctl serve")
+    console.print("")
+
+
+def _today() -> str:
+    from datetime import date
+    return date.today().isoformat()
+
+
+def _derive_prefix(name: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9]", "", name)
+    if len(cleaned) <= 4:
+        return cleaned.upper()
+    words = re.split(r"[\s_-]+", name)
+    words = [w for w in words if w]
+    if len(words) >= 2:
+        return "".join(w[0] for w in words).upper()[:4]
+    return cleaned[:3].upper()