@pennyfarthing/core 10.4.0 → 11.0.0

package/pennyfarthing_scripts/CLAUDE.md

@@ -0,0 +1,182 @@
+# CLAUDE.md — pf CLI
+
+Python Click CLI for Pennyfarthing. Entry point: `pennyfarthing_scripts/cli.py`. Invoked as `pf`.
+
+## Command Index
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf sprint` | Sprint status and story operations | `sprint/cli.py` |
+| `pf jira` | Jira issue management | `jira/cli.py` |
+| `pf theme` | Persona theme management | `theme/cli.py` |
+| `pf bc` | Panel focus and layout management | `bc/cli.py` |
+| `pf validate` | Project validators | `validate/cli.py` |
+| `pf agent` | Agent session management | `cli.py` (inline) |
+| `pf workflow` | Workflow state and phase management | `cli.py` (inline) |
+| `pf bikerack` | BikeRack dashboard launcher | `bikerack/cli.py` |
+| `pf debug` | Analysis tools (hotspots, deadcode, healthscore) | `cli.py` (inline group) |
+
+### Sugar Shortcuts
+
+| Shortcut | Expands To |
+|----------|------------|
+| `pf status` | `pf sprint status` |
+| `pf backlog` | `pf sprint backlog` |
+| `pf work` | `pf sprint work` |
+| `pf story` | `pf sprint story` |
+
+## pf sprint
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf sprint status [FILTER]` | Show sprint status. Filter: `all`, `backlog`, `in-progress`, `done`, `review` | `sprint/status.py` |
+| `pf sprint backlog` | Available stories grouped by epic | `sprint/cli.py` |
+| `pf sprint work [STORY_ID]` | Start work on a story (`next` for auto-select) | `sprint/work.py` |
+| `pf sprint check IDENTIFIER` | Check story/epic availability (JSON output) | `sprint/cli.py` |
+| `pf sprint info` | Sprint header as JSON | `sprint/cli.py` |
+| `pf sprint metrics` | Sprint metrics and velocity | `sprint/cli.py` |
+| `pf sprint future [EPIC_ID]` | Future initiatives overview | `sprint/cli.py` |
+| `pf sprint new` | Initialize a new sprint | `sprint/cli.py` |
+| `pf sprint archive STORY_ID PR` | Archive a completed story | `sprint/archive.py` |
+| `pf sprint standalone TITLE` | Wrap changes into standalone Jira story + PR | `sprint/cli.py` |
+| `pf sprint validate` | Validate sprint YAML | `sprint/validate_cmd.py` |
+
+### pf sprint story
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf sprint story show ID` | Show story details | `sprint/cli.py` |
+| `pf sprint story add EPIC_ID TITLE POINTS` | Add story to epic | `sprint/story_add.py` |
+| `pf sprint story update ID [OPTIONS]` | Update story fields | `sprint/story_update.py` |
+| `pf sprint story field ID FIELD` | Get single field value | `sprint/cli.py` |
+| `pf sprint story size [POINTS]` | Sizing guidelines | `sprint/cli.py` |
+| `pf sprint story template [TYPE]` | Story templates | `sprint/cli.py` |
+| `pf sprint story finish ID` | Complete story (archive, merge, Jira) | `sprint/story_finish.py` |
+| `pf sprint story claim JIRA_KEY` | Claim/unclaim in Jira | `sprint/cli.py` |
+
+### pf sprint epic
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf sprint epic show ID` | Show epic details | `sprint/cli.py` |
+| `pf sprint epic add ID TITLE` | Add new epic | `sprint/epic_add.py` |
+| `pf sprint epic update ID [OPTIONS]` | Update epic fields | `sprint/epic_update.py` |
+| `pf sprint epic field ID FIELD` | Get single field value | `sprint/cli.py` |
+| `pf sprint epic promote ID` | Move from future to current sprint | `sprint/cli.py` |
+| `pf sprint epic archive [ID]` | Archive completed epics | `sprint/archive_epic.py` |
+| `pf sprint epic cancel ID` | Cancel epic and all stories | `sprint/cli.py` |
+| `pf sprint epic import FILE` | Import BMAD epics to future.yaml | `sprint/import_epic.py` |
+| `pf sprint epic remove ID` | Remove from future.yaml | `sprint/cli.py` |
+
+### pf sprint initiative
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf sprint initiative show ID` | Show initiative details | `sprint/cli.py` |
+| `pf sprint initiative cancel ID` | Cancel initiative and all children | `sprint/cli.py` |
+
+## pf jira
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf jira view KEY` | View issue details | `jira/cli.py` |
+| `pf jira check KEY` | Check if story is available | `jira/cli.py` |
+| `pf jira claim KEY` | Assign to self + In Progress | `jira/claim.py` |
+| `pf jira assign KEY USER` | Assign to user (email or GitHub username) | `jira/cli.py` |
+| `pf jira move KEY STATUS` | Transition issue status | `jira/cli.py` |
+| `pf jira link KEY1 KEY2 [TYPE]` | Link two issues | `jira/cli.py` |
+| `pf jira search JQL` | Search by JQL | `jira/cli.py` |
+| `pf jira create epic EPIC_ID` | Create epic + children from YAML | `jira/epic.py` |
+| `pf jira create story EPIC_KEY STORY_ID` | Create single story under epic | `jira/story.py` |
+| `pf jira create standalone TITLE` | Create standalone story, add to sprint, Done | `jira/create.py` |
+| `pf jira sync EPIC_ID` | Sync YAML to Jira | `jira/sync.py` |
+| `pf jira bidirectional` | Bidirectional sync (Jira wins by default) | `jira/bidirectional.py` |
+| `pf jira reconcile` | Report mismatches between YAML and Jira | `jira/reconcile.py` |
+| `pf jira sprint add SPRINT_ID KEY` | Add issue to sprint | `jira/cli.py` |
+
+## pf theme
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf theme list` | All available themes | `theme/cli.py` |
+| `pf theme show [NAME]` | Theme details (current if no name) | `theme/cli.py` |
+| `pf theme set NAME` | Set active theme | `theme/cli.py` |
+| `pf theme create NAME` | Create custom theme from base | `theme/cli.py` |
+
+## pf bc
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf bc <panel>` | Focus panel (sprint, git, diffs, todo, workflow, background, audit-log, changed, ac, debug, settings, tty) | `bc/cli.py` |
+| `pf bc reset` | Clear focus | `bc/cli.py` |
+| `pf bc save NAME` | Save current layout | `bc/cli.py` |
+| `pf bc load NAME` | Load saved layout | `bc/cli.py` |
+| `pf bc list` | List saved layouts | `bc/cli.py` |
+| `pf bc clear NAME` | Delete layout | `bc/cli.py` |
+| `pf bc clear-all` | Delete all layouts | `bc/cli.py` |
+
+## pf validate
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf validate` | Run all validators | `validate/cli.py` |
+| `pf validate sprint` | Sprint YAML validation | `validate/cli.py` |
+| `pf validate schema` | XML schema validation | `validate/cli.py` |
+| `pf validate agent` | Agent definition validation | `validate/cli.py` |
+| `pf validate workflow` | Workflow definition validation | `validate/cli.py` |
+
+Options: `--fix` (auto-fix), `--strict` (warnings as errors)
+
+## pf agent
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf agent start NAME` | Start agent session with context | `prime/` |
+
+Options: `--session-id`, `--no-persona`, `--json`, `--minimal`, `--full`, `--quiet`, `--tier {full,refresh,handoff,minimal}`
+
+## pf workflow
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf workflow check` | Current workflow state | `workflow.py` |
+| `pf workflow phase-check WORKFLOW PHASE` | Check phase owner | `workflow.py` |
+| `pf workflow handoff AGENT` | Emit handoff marker | `cli.py` (inline) |
+
+## pf bikerack
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf bikerack start` | Start BikeRack + Claude CLI | `bikerack/cli.py` |
+| `pf bikerack stop` | Stop running instance | `bikerack/cli.py` |
+| `pf bikerack status` | Show running state | `bikerack/cli.py` |
+
+## pf debug
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf debug hotspots analyze` | Full hotspot analysis | `hotspots/analyze.py` |
+| `pf debug hotspots files` | File-level hotspot report | `hotspots/cli.py` |
+| `pf debug hotspots dirs` | Directory-level hotspot report | `hotspots/cli.py` |
+| `pf debug deadcode stale` | Files with no recent commits | `deadcode/analyze.py` |
+| `pf debug deadcode exports` | Unused TypeScript exports | `deadcode/cli.py` |
+| `pf debug healthscore analyze` | Composite health score | `healthscore/cli.py` |
+
+## Hooks (non-CLI)
+
+| File | Hook Type | Purpose |
+|------|-----------|---------|
+| `hooks.py` | PostToolUse | Main hook dispatcher |
+| `bellmode_hook.py` | PostToolUse | Bell mode message injection |
+| `pretooluse_hook.py` | PreToolUse | Permission and safety gates |
+| `schema_validation_hook.py` | PreToolUse:Write | Schema validation on file writes |
+| `welcome_hook.py` | PostToolUse | Welcome message on session start |
+| `patch_mode.py` | PostToolUse | Patch mode interrupt handling |
+
+## Architecture
+
+- **Framework:** Click (lazy-loaded groups for <200ms startup)
+- **Entry point:** `cli.py` registers all groups, `pyproject.toml` maps `pf` to `pennyfarthing_scripts.cli:main`
+- **Pattern:** Each command group is a subpackage with `cli.py` defining Click commands and sibling modules for logic
+- **Output:** JSON for machine consumption (`--json`), formatted text for humans
+- **Dry run:** Most mutating commands support `--dry-run` to preview changes

package/pennyfarthing_scripts/bc/__init__.py

@@ -0,0 +1 @@
+"""BC — Panel focus management for BikeShow."""

package/pennyfarthing_scripts/bc/cli.py

@@ -0,0 +1,223 @@
+"""BC CLI — Panel focus management for Cyclist.
+
+Usage:
+    pf bc <panel>    Set focus to a panel
+    pf bc reset      Clear focus setting
+    pf bc save       Save a named layout
+    pf bc load       Load a named layout
+    pf bc list       List saved layouts
+    pf bc clear      Delete a named layout
+    pf bc clear-all  Delete all named layouts
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import urllib.error
+import urllib.request
+
+import click
+
+from pennyfarthing_scripts.bc.focus import (
+    VALID_PANELS,
+    clear_all_named_layouts,
+    clear_named_layout,
+    clear_panel_focus,
+    list_named_layouts,
+    load_named_layout,
+    save_named_layout,
+    set_panel_focus,
+)
+
+
+def _get_current_layout() -> dict | None:
+    """Fetch the current layout from a running Cyclist or BikeRack server.
+
+    Checks .bikerack-port first, then .cyclist-port, and fetches the
+    appropriate layout endpoint.
+
+    Returns:
+        Layout dict, or None if no server is running or fetch fails.
+    """
+    from pennyfarthing_scripts.bc.focus import _get_root
+
+    root = _get_root()
+
+    # Try BikeRack first (bikerack-layout), then Cyclist (layout)
+    candidates = [
+        (root / ".bikerack-port", "/api/settings/bikerack-layout"),
+        (root / ".cyclist-port", "/api/settings/bikerack-layout"),
+    ]
+
+    for port_file, endpoint in candidates:
+        if not port_file.exists():
+            continue
+        try:
+            port = int(port_file.read_text().strip())
+        except (ValueError, OSError):
+            continue
+
+        url = f"http://localhost:{port}{endpoint}"
+        try:
+            req = urllib.request.Request(url, headers={"Accept": "application/json"})
+            with urllib.request.urlopen(req, timeout=3) as resp:
+                data = json.loads(resp.read().decode())
+                layout = data.get("layout")
+                if layout and isinstance(layout, dict) and layout.get("panels"):
+                    return layout
+        except (urllib.error.URLError, OSError, json.JSONDecodeError):
+            continue
+
+    return None
+
+
+@click.group()
+def bc():
+    """Panel focus management.
+
+    \b
+    Commands:
+      sprint      - Focus on Sprint panel
+      git         - Focus on Git panel
+      diffs       - Focus on Diffs panel
+      todo        - Focus on Todo panel
+      workflow    - Focus on Workflow panel
+      background  - Focus on Background panel
+      audit-log   - Focus on Audit Log panel
+      changed     - Focus on Changed panel
+      ac          - Focus on Acceptance Criteria panel
+      debug       - Focus on Debug panel
+      settings    - Focus on Settings panel
+      tty         - Focus on TTY panel
+      reset       - Clear focus setting
+    """
+    pass
+
+
+def _make_focus_command(panel_name: str):
+    """Create a Click command for a panel."""
+
+    @click.command(panel_name, help=f"Focus on {panel_name} panel.")
+    @click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+    def focus_cmd(dry_run):
+        if dry_run:
+            click.echo(json.dumps({"dry_run": True, "action": "set_focus", "panel": panel_name}))
+            return
+        result = set_panel_focus(panel_name)
+        if result["success"]:
+            click.echo(json.dumps({"success": True, "panel": result["data"]}))
+        else:
+            click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
+            sys.exit(1)
+
+    return focus_cmd
+
+
+for _panel in VALID_PANELS:
+    bc.add_command(_make_focus_command(_panel))
+
+
+@bc.command("reset")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def reset_focus(dry_run):
+    """Clear focus setting."""
+    if dry_run:
+        click.echo(json.dumps({"dry_run": True, "action": "clear_focus"}))
+        return
+    result = clear_panel_focus()
+    if result["success"]:
+        click.echo(json.dumps({"success": True, "message": result.get("message", "focus cleared")}))
+    else:
+        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
+        sys.exit(1)
+
+
+# --- Story 104-4: Named layout commands ---
+
+
+@bc.command("save")
+@click.argument("name")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def save_layout(name: str, dry_run: bool):
+    """Save current layout under a name.
+
+    Fetches the active layout from the running Cyclist/BikeRack server
+    and stores it in config.local.yaml under the given name.
+    """
+    layout_data = _get_current_layout()
+    if not layout_data:
+        click.echo(
+            json.dumps({"success": False, "error": "No running Cyclist/BikeRack server found, or layout is empty"}),
+            err=True,
+        )
+        sys.exit(1)
+    if dry_run:
+        panel_count = len(layout_data.get("panels", {}))
+        click.echo(json.dumps({"dry_run": True, "action": "save_layout", "name": name, "panels": panel_count}))
+        return
+    result = save_named_layout(name, layout_data)
+    if result["success"]:
+        panel_count = len(layout_data.get("panels", {}))
+        click.echo(json.dumps({"success": True, "name": result["data"], "panels": panel_count}))
+    else:
+        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
+        sys.exit(1)
+
+
+@bc.command("load")
+@click.argument("name")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def load_layout(name: str, dry_run: bool):
+    """Load a previously saved named layout."""
+    if dry_run:
+        click.echo(json.dumps({"dry_run": True, "action": "load_layout", "name": name}))
+        return
+    result = load_named_layout(name)
+    if result["success"]:
+        click.echo(json.dumps({"success": True, "name": name, "layout": result["data"]}))
+    else:
+        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
+        sys.exit(1)
+
+
+@bc.command("list")
+def list_layouts():
+    """List all saved named layouts."""
+    result = list_named_layouts()
+    if result["success"]:
+        click.echo(json.dumps({"success": True, "layouts": result["data"]}))
+    else:
+        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
+        sys.exit(1)
+
+
+@bc.command("clear")
+@click.argument("name")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def clear_layout(name: str, dry_run: bool):
+    """Delete a specific named layout."""
+    if dry_run:
+        click.echo(json.dumps({"dry_run": True, "action": "clear_layout", "name": name}))
+        return
+    result = clear_named_layout(name)
+    if result["success"]:
+        click.echo(json.dumps({"success": True, "message": result.get("message", "layout cleared")}))
+    else:
+        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
+        sys.exit(1)
+
+
+@bc.command("clear-all")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def clear_all_layouts(dry_run: bool):
+    """Delete all named layouts."""
+    if dry_run:
+        click.echo(json.dumps({"dry_run": True, "action": "clear_all_layouts"}))
+        return
+    result = clear_all_named_layouts()
+    if result["success"]:
+        click.echo(json.dumps({"success": True, "message": result.get("message", "all layouts cleared")}))
+    else:
+        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
+        sys.exit(1)