kingdom-cli 0.3.2__tar.gz → 0.4.0__tar.gz

{kingdom_cli-0.3.2 → kingdom_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kingdom-cli
-Version: 0.3.2
+Version: 0.4.0
 Summary: A markdown file-based CLI for software development with multi-agent council design, markdown tickets, and background worker loops.
 Author: James Robinson-Bohnslav
 License-Expression: Apache-2.0

{kingdom_cli-0.3.2 → kingdom_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kingdom-cli"
-version = "0.3.2"
+version = "0.4.0"
 description = "A markdown file-based CLI for software development with multi-agent council design, markdown tickets, and background worker loops."
 readme = "README.md"
 requires-python = ">=3.10"

{kingdom_cli-0.3.2 → kingdom_cli-0.4.0}/src/kingdom/cli/__init__.py

@@ -40,6 +40,7 @@ from .council import council_app
 from .design import design_app, get_branch_paths, get_doc_status  # noqa: F401 (re-export)
 from .display import error_console, print_error, styled_echo
 from .helpers import install_skill, is_git_repo, require_project_root, verbose_echo  # noqa: F401
+from .hook import hook_app
 from .peasant import (  # noqa: F401
     PeasantContext,
     launch_work_background,
@@ -47,6 +48,7 @@ from .peasant import (  # noqa: F401
     peasant_app,
     resolve_peasant_context,
 )
+from .plugin import plugin_app
 from .ticket import format_ticket_line, format_ticket_summary, get_tickets_dir, ticket_app  # noqa: F401
 
 NO_COLOR = "NO_COLOR" in os.environ or os.environ.get("TERM") == "dumb"
@@ -78,6 +80,8 @@ app.add_typer(council_app, name="council")
 app.add_typer(design_app, name="design")
 app.add_typer(peasant_app, name="peasant")
 app.add_typer(config_app, name="config")
+app.add_typer(hook_app, name="hook")
+app.add_typer(plugin_app, name="plugin")
 app.add_typer(ticket_app, name="ticket")
 app.add_typer(ticket_app, name="tk", hidden=True)  # Alias for muscle memory
 
@@ -133,7 +137,10 @@ def start(
     if current_path.exists() and not force:
         existing = current_path.read_text(encoding="utf-8").strip()
         print_error(f"A session is already active: {existing}")
-        error_console.print("  Use --force to override, or run `kd done` first.")
+        error_console.print(
+            "  If that branch is finished, run `kd done` to clean it up before starting a new session.\n"
+            "  If you need to switch mid-work, use `kd start --force` to override."
+        )
         raise typer.Exit(code=1)
 
     # Determine branch name
@@ -168,6 +175,109 @@ def start(
     typer.echo(f"  Design: {design_path}")
 
 
+@app.command(help="Switch the active kd session to another branch.")
+def switch(
+    branch: Annotated[str | None, typer.Argument(help="Branch name to switch to.")] = None,
+) -> None:
+    """Switch the active kd session without changing git branch.
+
+    With an argument: validate the branch exists in .kd/branches/ and update .kd/current.
+    Without arguments: list all tracked branches, marking the current session and git branch.
+    """
+    base = require_project_root()
+    console = Console()
+
+    if branch is None:
+        # List mode: show all tracked branches
+        branches_dir = base / ".kd" / "branches"
+        if not branches_dir.exists() or not any(branches_dir.iterdir()):
+            typer.echo("No tracked branches. Use `kd start <branch>` to create one.")
+            return
+
+        # Determine current kd session
+        current_session: str | None = None
+        current_path = base / ".kd" / "current"
+        if current_path.exists():
+            current_session = current_path.read_text(encoding="utf-8").strip() or None
+
+        # Determine current git branch
+        git_branch = get_current_git_branch()
+        git_normalized = normalize_branch_name(git_branch) if git_branch else None
+
+        for branch_dir in sorted(branches_dir.iterdir()):
+            if not branch_dir.is_dir():
+                continue
+            name = branch_dir.name
+
+            # Read original branch name from state.json
+            state_path = branch_dir / "state.json"
+            original = name
+            branch_status = ""
+            if state_path.exists():
+                try:
+                    state = read_json(state_path)
+                    original = state.get("branch", name)
+                    if state.get("status") == "done":
+                        branch_status = " [dim](done)[/dim]"
+                except (FileNotFoundError, KeyError):
+                    pass
+
+            # Count open tickets
+            tickets_dir = branch_dir / "tickets"
+            ticket_count = 0
+            if tickets_dir.exists():
+                ticket_count = sum(1 for f in tickets_dir.glob("*.md"))
+
+            # Build markers
+            markers = []
+            if name == current_session:
+                markers.append("[bold cyan]* session[/bold cyan]")
+            if name == git_normalized:
+                markers.append("[green]* git[/green]")
+            marker_str = f"  ({', '.join(markers)})" if markers else ""
+
+            console.print(f"  {original}{branch_status}  [{ticket_count} tickets]{marker_str}")
+        return
+
+    # Switch mode: validate and update
+    normalized = normalize_branch_name(branch)
+    branch_dir = base / ".kd" / "branches" / normalized
+    if not branch_dir.exists():
+        print_error(f"Branch '{branch}' not found in .kd/branches/.")
+        error_console.print("Available branches:")
+        branches_dir = base / ".kd" / "branches"
+        if branches_dir.exists():
+            for d in sorted(branches_dir.iterdir()):
+                if d.is_dir():
+                    error_console.print(f"  {d.name}")
+        raise typer.Exit(code=1)
+
+    set_current_run(base, normalized)
+
+    # Print summary
+    state_path = branch_dir / "state.json"
+    original = branch
+    if state_path.exists():
+        try:
+            state = read_json(state_path)
+            original = state.get("branch", branch)
+        except (FileNotFoundError, KeyError):
+            pass
+
+    tickets_dir = branch_dir / "tickets"
+    tickets = list_tickets(tickets_dir) if tickets_dir.exists() else []
+    open_count = sum(1 for t in tickets if t.status != "closed")
+    closed_count = sum(1 for t in tickets if t.status == "closed")
+
+    git_branch = get_current_git_branch()
+    git_info = f"  git: {git_branch}" if git_branch else ""
+    if git_branch and normalize_branch_name(git_branch) != normalized:
+        git_info += " [yellow](mismatch)[/yellow]"
+
+    console.print(f"Switched to [bold]{original}[/bold]")
+    console.print(f"  {open_count} open, {closed_count} closed tickets{git_info}")
+
+
 @app.command(help="Mark the current session as done.")
 def done(
     feature: Annotated[str | None, typer.Argument(help="Branch name (defaults to current session).")] = None,

{kingdom_cli-0.3.2 → kingdom_cli-0.4.0}/src/kingdom/cli/council.py

@@ -135,7 +135,9 @@ def topic_for_thread(base: Path, feature: str, thread_id: str) -> str:
 def council_ask(
     prompt: Annotated[str, typer.Argument(help="Prompt to send to council members.")],
     to: Annotated[str | None, typer.Option("--to", help="Send to a specific member only.")] = None,
-    new_thread: Annotated[bool, typer.Option("--new-thread", help="Start a fresh thread.")] = False,
+    continue_thread: Annotated[
+        bool, typer.Option("--continue", "-c", help="Continue the current council thread.")
+    ] = False,
     json_output: Annotated[bool, typer.Option("--json", help="Output JSON format.")] = False,
     async_mode: Annotated[
         bool, typer.Option("--async", help="Dispatch in background, then watch for responses.")
@@ -203,16 +205,19 @@ def council_ask(
             print_error(f"Available: {', '.join(sorted(available_names))}")
             raise typer.Exit(code=1)
 
-    # Determine thread: continue current, or create new
+    # Determine thread: new by default, or continue current
     current = get_current_thread(base, feature)
-    start_new = new_thread or current is None
 
-    # Recover from stale pointer: current_thread set but directory missing
-    if not start_new and not thread_dir(base, feature, current).exists():
-        set_current_thread(base, feature, None)
+    if continue_thread:
+        # --continue: reuse existing thread, error if none exists
+        if current is None or not thread_dir(base, feature, current).exists():
+            print_error("No active council thread on this branch. Drop --continue to start a new one.")
+            raise typer.Exit(code=1)
+        thread_id = current
+        start_new = False
+    else:
+        # Default: always start a new thread
         start_new = True
-
-    if start_new:
         thread_id = f"council-{secrets.token_hex(2)}"
         if to:
             member_names = [to]
@@ -220,8 +225,6 @@ def council_ask(
             member_names = [m.name for m in c.members]
         create_thread(base, feature, thread_id, ["king", *member_names], "council")
         set_current_thread(base, feature, thread_id)
-    else:
-        thread_id = current
 
     tdir = thread_dir(base, feature, thread_id)
     verbose_echo(f"thread: {thread_id} ({'new' if start_new else 'continuing'})")
@@ -444,11 +447,10 @@ def council_review(
         worklog=worklog,
     )
 
-    # Delegate to council_ask with --new-thread and review phase
+    # Delegate to council_ask — new thread by default now
     council_ask(
         prompt=review_prompt,
         to=to,
-        new_thread=True,
         json_output=False,
         async_mode=async_mode,
         no_watch=no_watch,
@@ -670,6 +672,7 @@ def council_list() -> None:
 
         # Get topic from first king message
         messages = list_messages(base, feature, t.id)
+        msg_count = len(messages)
         topic = ""
         for msg in messages:
             if msg.from_ == "king":
@@ -686,7 +689,8 @@ def council_list() -> None:
             member_parts.append(f"{symbol} {name}")
         members_str = "  ".join(member_parts) if member_parts else ""
 
-        console.print(f"[bold]{t.id}[/bold]  [dim]{created}[/dim]{marker}")
+        count_str = f"[dim]{msg_count} msg{'s' if msg_count != 1 else ''}[/dim]"
+        console.print(f"[bold]{t.id}[/bold]  [dim]{created}[/dim]  {count_str}{marker}")
         if topic:
             console.print(f"  {topic}")
         if members_str:
@@ -1114,7 +1118,6 @@ def display_rich_panels(responses, thread_id, console):
 @council_app.command("chat", help="Open council chat TUI.")
 def council_chat(
     thread_id: Annotated[str | None, typer.Argument(help="Thread ID to open.")] = None,
-    new: Annotated[bool, typer.Option("--new", help="Create a new thread.")] = False,
     debug: Annotated[
         bool,
         typer.Option(
@@ -1136,53 +1139,25 @@ def council_chat(
 ) -> None:
     """Open the council chat TUI.
 
-    Opens an existing thread, creates a new one, or lists recent threads.
+    Creates a new thread by default, or opens an existing one by ID.
     """
     import kingdom.cli as _cli
     from kingdom.config import load_config
-    from kingdom.thread import create_thread, list_threads
+    from kingdom.thread import create_thread
 
     base = require_project_root()
     feature = _cli.resolve_current_run(base)
     cfg = load_config(base)
 
-    if new:
+    if thread_id:
+        tid = resolve_council_thread_id(base, feature, thread_id, command="chat")
+        set_current_thread(base, feature, tid)
+    else:
+        # Default: new thread (same as ask)
         tid = f"council-{secrets.token_hex(2)}"
         member_names = cfg.council.members or list(cfg.agents)
         create_thread(base, feature, tid, ["king", *member_names], "council")
         set_current_thread(base, feature, tid)
-    elif thread_id:
-        tid = resolve_council_thread_id(base, feature, thread_id, command="chat")
-        set_current_thread(base, feature, tid)
-    else:
-        current = get_current_thread(base, feature)
-        if current:
-            from kingdom.thread import thread_dir
-
-            if thread_dir(base, feature, current).exists():
-                tid = current
-            else:
-                set_current_thread(base, feature, None)
-                current = None
-
-        if not current:
-            threads = list_threads(base, feature)
-            if threads:
-                typer.echo("Recent threads:")
-                for t in reversed(threads[-5:]):
-                    created = t.created_at.strftime("%Y-%m-%d %H:%M")
-                    members = ", ".join(m for m in t.members if m != "king")
-                    typer.echo(f"  {t.id}  {created}  [{members}]")
-                typer.echo()
-                typer.echo("Usage: kd council chat <thread-id>  or  kd council chat --new")
-                raise typer.Exit(code=0)
-            else:
-                # Auto-create a thread when none exist
-                tid = f"council-{secrets.token_hex(2)}"
-                member_names = cfg.council.members or list(cfg.agents)
-                create_thread(base, feature, tid, ["king", *member_names], "council")
-                set_current_thread(base, feature, tid)
-                typer.echo(f"Created new thread: {tid}")
 
     from kingdom.tui.app import ChatApp
     from kingdom.tui.terminal import in_tmux_control_mode

kingdom_cli-0.4.0/src/kingdom/cli/hook.py

@@ -0,0 +1,225 @@
+"""Hook event handlers for Claude Code integration.
+
+The ``kd hook run`` subcommand reads a JSON payload from stdin, dispatches to
+the appropriate handler based on ``hook_event_name``, and writes any response
+JSON to stdout.  It is designed to be invoked by Claude Code as the hook
+command registered in ``.claude/settings.json``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import typer
+
+hook_app = typer.Typer(name="hook", help="Claude Code hook handlers (internal).")
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+SESSION_START_BRIEF = (
+    "KINGDOM WORKFLOW: You are working in a project managed by the kd CLI."
+    " Before coding or research, ensure work is tracked with a ticket.\n"
+    " 1. TICKET FIRST — King says something? Ask yourself: does this need a"
+    " ticket? Bug, idea, complaint, scope change → kd tk create immediately.\n"
+    " 2. LOG PROACTIVELY — Decision made, root cause found, scope changed,"
+    " work completed → kd tk log. The King should never have to ask.\n"
+    " 3. MOVE vs CREATE — Work belongs elsewhere → kd tk move. New problem"
+    " noticed → kd tk create --backlog."
+)
+
+USER_PROMPT_REMINDER = (
+    "Kingdom: keep the ticket accurate (body/AC/status/worklog)."
+    " Requirement or acceptance-criteria change -> edit ticket markdown now."
+    " Work/findings -> kd tk log. New bug/scope -> kd tk create|move."
+)
+
+WORK_TOOLS = {"WebSearch", "WebFetch", "Edit", "Write"}
+
+STALE_TTL_SECONDS = 86400  # 24 hours
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def runtime_dir(project_dir: str | None = None) -> Path:
+    """Return the .kd/runtime directory, creating it if needed."""
+    base = Path(project_dir) if project_dir else Path(".")
+    d = base / ".kd" / "runtime"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def state_file_for(project_dir: str | None, session_id: str) -> Path:
+    """Return the turn-state file path for a given session."""
+    return runtime_dir(project_dir) / f"turn-{session_id}.json"
+
+
+def read_turn_state(path: Path) -> dict | None:
+    """Read turn state, returning None on any error (fail-open)."""
+    try:
+        return json.loads(path.read_text())
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def write_turn_state(path: Path, state: dict) -> None:
+    path.write_text(json.dumps(state))
+
+
+# ---------------------------------------------------------------------------
+# Event handlers — each returns a string to print to stdout (or empty).
+# ---------------------------------------------------------------------------
+
+
+def handle_session_start(data: dict) -> str:
+    return json.dumps(
+        {
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": SESSION_START_BRIEF,
+            }
+        }
+    )
+
+
+def handle_user_prompt_submit(data: dict) -> str:
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    session_id = data.get("session_id", "")
+
+    if session_id:
+        sf = state_file_for(project_dir, session_id)
+        write_turn_state(sf, {"had_work": False, "did_log": False})
+
+        # TTL cleanup: remove stale turn-state files.
+        cutoff = time.time() - STALE_TTL_SECONDS
+        rd = runtime_dir(project_dir)
+        for f in rd.glob("turn-*.json"):
+            try:
+                if f.stat().st_mtime < cutoff:
+                    f.unlink()
+            except OSError:
+                pass
+
+    return json.dumps(
+        {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": USER_PROMPT_REMINDER,
+            }
+        }
+    )
+
+
+def handle_post_tool_use(data: dict) -> str:
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    session_id = data.get("session_id", "")
+    if not session_id:
+        return ""
+
+    sf = state_file_for(project_dir, session_id)
+    state = read_turn_state(sf)
+    if state is None:
+        return ""
+
+    tool = data.get("tool_name", "")
+
+    if tool in WORK_TOOLS:
+        state["had_work"] = True
+
+    if tool == "Bash":
+        cmd = data.get("tool_input", {}).get("command", "")
+        if "kd tk log" in cmd or "kd ticket log" in cmd:
+            state["did_log"] = True
+
+    write_turn_state(sf, state)
+    return ""
+
+
+def handle_stop(data: dict) -> str:
+    # If stop_hook_active is set, another stop handler is running — bail.
+    if data.get("stop_hook_active", False):
+        return ""
+
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    session_id = data.get("session_id", "")
+    if not session_id:
+        return ""
+
+    sf = state_file_for(project_dir, session_id)
+    state = read_turn_state(sf)
+    if state is None:
+        return ""
+
+    if not (state.get("had_work") and not state.get("did_log")):
+        return ""
+
+    # Check for an active ticket (fail-open on any error).
+    try:
+        proc = subprocess.run(
+            ["kd", "tk", "current", "--id"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        ticket_id = proc.stdout.strip()
+        if proc.returncode != 0 or not ticket_id:
+            return ""  # No active ticket — fail open.
+    except Exception:
+        return ""  # Timeout or error — fail open.
+
+    result = {
+        "decision": "block",
+        "reason": (
+            f"KINGDOM: You did meaningful work this turn but didn't log it."
+            f" Run: kd tk log {ticket_id} 'summary of what you did'"
+        ),
+    }
+    return json.dumps(result)
+
+
+# Map event names to handlers.
+HANDLERS = {
+    "SessionStart": handle_session_start,
+    "UserPromptSubmit": handle_user_prompt_submit,
+    "PostToolUse": handle_post_tool_use,
+    "Stop": handle_stop,
+}
+
+# ---------------------------------------------------------------------------
+# CLI command
+# ---------------------------------------------------------------------------
+
+
+@hook_app.command("run", help="Process a Claude Code hook event from stdin.")
+def hook_run() -> None:
+    """Read hook payload JSON from stdin, dispatch by event, write response."""
+    # Bypass all processing if requested.
+    if os.environ.get("KD_HOOK_BYPASS") == "1":
+        return
+
+    try:
+        raw = sys.stdin.read()
+        data = json.loads(raw) if raw.strip() else {}
+    except (json.JSONDecodeError, OSError):
+        return  # Fail open on bad input.
+
+    event = data.get("hook_event_name", "")
+    handler = HANDLERS.get(event)
+    if handler is None:
+        return  # Unknown event — silent.
+
+    try:
+        output = handler(data)
+    except Exception:
+        return  # Fail open on handler errors.
+
+    if output:
+        typer.echo(output)