@pennyfarthing/core 11.3.2 → 11.3.4

package/pennyfarthing-dist/pf/launch/cli.py

@@ -0,0 +1,231 @@
+"""Launch CLI — mid-session GUI/TUI launcher commands.
+
+Usage:
+    pf gui                 # Ensure WheelHub, open browser
+    pf tui                 # Start TUI (auto-detects interactivity)
+    pf launch gui          # Full path
+    pf launch tui          # Full path
+    pf launch status       # Is WheelHub running?
+    pf launch stop         # Kill WheelHub
+"""
+
+from __future__ import annotations
+
+import sys
+import webbrowser
+from pathlib import Path
+
+import click
+
+
+def _ensure_wheelhub(project_dir: Path) -> tuple[int, int, bool]:
+    """Ensure WheelHub is running. Returns (port, pid, was_already_running).
+
+    If already running, reuses existing instance.
+    If not, starts a new one and prints a mid-session OTEL note.
+    """
+    from pf.bikerack.launcher import (
+        is_already_running,
+        poll_for_port_file,
+        start_wheelhub,
+        write_pid_file,
+    )
+
+    running, pid, port = is_already_running(project_dir)
+    if running:
+        return port, pid, True
+
+    click.echo("Starting WheelHub server...")
+    proc = start_wheelhub(project_dir)
+    write_pid_file(project_dir, proc.pid)
+    port = poll_for_port_file(project_dir)
+    click.echo(f"WheelHub listening on http://localhost:{port}")
+    click.echo(
+        "Note: OTEL telemetry requires Claude to be started with BikeRack env vars. "
+        "File-based panels (sprint, git, diffs) work independently."
+    )
+    return port, proc.pid, False
+
+
+@click.group()
+def launch():
+    """Mid-session GUI/TUI launcher.
+
+    \b
+    Commands:
+      gui     - Open BikeRack dashboard in browser
+      tui     - Launch terminal UI
+      status  - Show WheelHub running state
+      stop    - Stop WheelHub server
+    """
+    pass
+
+
+@launch.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory. Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+@click.option("--no-open", is_flag=True, help="Print URL only, don't open browser.")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes.")
+def gui(project_dir, no_open, dry_run):
+    """Open BikeRack dashboard in browser.
+
+    Ensures WheelHub is running (starts it if needed), then opens
+    the dashboard URL. Safe to call multiple times — reuses existing server.
+    """
+    from pf.bikerack.launcher import resolve_project_dir
+
+    project_dir = resolve_project_dir(project_dir)
+
+    if dry_run:
+        click.echo("[DRY-RUN] Would launch BikeRack GUI")
+        click.echo(f"  Project: {project_dir}")
+        click.echo("  Actions: ensure WheelHub running, open browser to dashboard")
+        return
+
+    try:
+        port, pid, reused = _ensure_wheelhub(project_dir)
+    except TimeoutError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    url = f"http://localhost:{port}/bikerack"
+
+    if no_open:
+        click.echo(f"Dashboard: {url}")
+    else:
+        click.echo(f"Opening {url}")
+        webbrowser.open(url)
+
+
+@launch.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory. Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+@click.option("--foreground", "mode", flag_value="foreground", help="Force TUI in current terminal.")
+@click.option("--detach", "mode", flag_value="detach", help="Force TUI in new Terminal.app window.")
+@click.option("--port", type=int, default=None, help="WheelHub port (skip auto-start).")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes.")
+def tui(project_dir, mode, port, dry_run):
+    """Launch BikeRack TUI.
+
+    Auto-detects terminal interactivity:
+    - Interactive terminal → runs TUI in foreground
+    - Non-interactive (e.g. Claude's Bash tool) → opens new Terminal.app window
+
+    Use --foreground or --detach to override auto-detection.
+    """
+    from pf.bikerack.launcher import resolve_project_dir
+
+    project_dir = resolve_project_dir(project_dir)
+
+    # Auto-detect mode if not specified
+    if mode is None:
+        mode = "foreground" if sys.stdin.isatty() else "detach"
+
+    if dry_run:
+        click.echo("[DRY-RUN] Would launch BikeRack TUI")
+        click.echo(f"  Project: {project_dir}")
+        click.echo(f"  Mode: {mode}")
+        if port:
+            click.echo(f"  Port: {port} (user-specified, skip WheelHub start)")
+        else:
+            click.echo("  Actions: ensure WheelHub running, launch TUI")
+        return
+
+    # Resolve port — either user-specified or ensure WheelHub is running
+    if port is None:
+        try:
+            port, _pid, _reused = _ensure_wheelhub(project_dir)
+        except TimeoutError as e:
+            click.echo(f"Error: {e}", err=True)
+            sys.exit(1)
+
+    if mode == "foreground":
+        from pf.bikerack.tui import main as tui_main
+
+        tui_main(port=port, project_dir=project_dir)
+    else:
+        _launch_tui_detached(project_dir, port)
+
+
+def _launch_tui_detached(project_dir: Path, port: int) -> None:
+    """Launch TUI in a new Terminal.app window via osascript."""
+    import subprocess
+
+    python = sys.executable
+    cmd = f"{python} -m pf.bikerack.tui --port {port} --project-dir {project_dir}"
+
+    applescript = f'''
+    tell application "Terminal"
+        activate
+        do script "{cmd}"
+    end tell
+    '''
+
+    try:
+        subprocess.run(["osascript", "-e", applescript], check=True, capture_output=True)
+        click.echo(f"TUI launched in new Terminal.app window (port {port})")
+    except subprocess.CalledProcessError as e:
+        click.echo(f"Error launching Terminal.app: {e.stderr.decode().strip()}", err=True)
+        click.echo(f"Run manually: {cmd}")
+        sys.exit(1)
+
+
+@launch.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory. Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+def status(project_dir):
+    """Show WheelHub running state."""
+    from pf.bikerack.launcher import get_status, resolve_project_dir
+
+    project_dir = resolve_project_dir(project_dir)
+    result = get_status(project_dir)
+
+    if result["running"]:
+        click.echo("WheelHub is running")
+        click.echo(f"  PID: {result['pid']}")
+        click.echo(f"  Port: {result['port']}")
+        click.echo(f"  Dashboard: {result['dashboard']}")
+        if result.get("tui_pid"):
+            click.echo(f"  TUI PID: {result['tui_pid']}")
+    else:
+        click.echo("WheelHub is not running")
+
+
+@launch.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory. Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes.")
+def stop(project_dir, dry_run):
+    """Stop WheelHub server."""
+    from pf.bikerack.launcher import resolve_project_dir, stop_bikerack
+
+    project_dir = resolve_project_dir(project_dir)
+
+    if dry_run:
+        click.echo("[DRY-RUN] Would stop WheelHub server")
+        click.echo(f"  Project: {project_dir}")
+        return
+
+    result = stop_bikerack(project_dir)
+
+    if result["success"]:
+        click.echo(result["message"])
+    else:
+        click.echo(result["message"], err=True)
+        sys.exit(1)

package/pennyfarthing-dist/pf/migration/__init__.py

@@ -0,0 +1,39 @@
+"""
+XML Schema Migration Tools for Pennyfarthing.
+
+This module provides tools to migrate and validate Pennyfarthing files
+to conform to the XML schema definitions:
+- Session files -> guides/session-schema.md
+- Skill files -> guides/skill-schema.md
+- Workflow step files -> guides/workflow-step-schema.md
+
+Usage:
+    python -m pf.migration [command] [options]
+
+Commands:
+    session   Migrate session files to XML format
+    skill     Audit/migrate skill files
+    step      Audit/migrate workflow step files
+    validate  Validate files against schemas
+"""
+
+from pf.migration.session import (
+    SessionFile,
+    convert_session_file,
+    parse_markdown_session,
+)
+from pf.migration.skill import audit_skill_file, audit_skills
+from pf.migration.step import audit_step_file, audit_workflow_steps
+from pf.migration.validate import validate_all, validate_file
+
+__all__ = [
+    "SessionFile",
+    "convert_session_file",
+    "parse_markdown_session",
+    "audit_skill_file",
+    "audit_skills",
+    "audit_step_file",
+    "audit_workflow_steps",
+    "validate_file",
+    "validate_all",
+]

package/pennyfarthing-dist/pf/migration/__main__.py

@@ -0,0 +1,10 @@
+"""
+Entry point for python -m pf.migration
+"""
+
+import sys
+
+from pf.migration.cli import cli
+
+if __name__ == "__main__":
+    sys.exit(cli())

package/pennyfarthing-dist/pf/migration/cli.py

@@ -0,0 +1,304 @@
+"""
+Migration CLI - Click-based CLI for XML schema migration tools.
+
+Usage:
+    pf migration [COMMAND] [ARGS]...
+    python -m pf.migration [COMMAND] [ARGS]...
+
+Commands:
+    session   Migrate session files to XML format
+    skill     Audit skill files for required tags
+    step      Audit workflow step files
+    validate  Validate files against XML schemas
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from pf.common.output import error, info, success, warn
+
+
+def _find_project_root() -> Path:
+    """Find project root by looking for .pennyfarthing directory."""
+    cwd = Path.cwd()
+
+    # Walk up looking for .pennyfarthing
+    for parent in [cwd, *cwd.parents]:
+        if (parent / ".pennyfarthing").exists():
+            return parent
+
+    # Fall back to cwd
+    return cwd
+
+
+@click.group()
+def migration():
+    """XML schema migration tools.
+
+    \b
+    Commands:
+      session   - Migrate session files to XML format
+      skill     - Audit skill files for required tags
+      step      - Audit workflow step files
+      validate  - Validate files against schemas
+    """
+    pass
+
+
+@migration.command()
+@click.argument("file", required=False, type=click.Path(exists=True))
+@click.option("--dry-run", is_flag=True, help="Show what would be done without writing")
+@click.option("--all", "convert_all", is_flag=True, help="Convert all session files")
+def session(file: str | None, dry_run: bool, convert_all: bool):
+    """Migrate session files to XML format.
+
+    \b
+    Arguments:
+      FILE  - Specific session file to convert (optional)
+
+    \b
+    Examples:
+      pf migration session --dry-run .session/archive/MSSCI-12142-session.md
+      pf migration session --all --dry-run
+      pf migration session --all
+    """
+    from pf.migration.session import (
+        convert_session_file,
+        find_session_files,
+    )
+
+    root = _find_project_root()
+
+    if file:
+        file_path = Path(file)
+        result = convert_session_file(file_path, dry_run=dry_run)
+
+        if result.get("skipped"):
+            info(f"{file_path.name}: Already in XML format")
+        elif result.get("success"):
+            if dry_run:
+                click.echo(f"\n=== Would convert {file_path.name} to: ===\n")
+                click.echo(result.get("content"))
+                click.echo("\n=== End ===")
+            else:
+                success(f"Converted: {file_path.name}")
+        else:
+            error(result.get("message", "Conversion failed"))
+            raise click.Abort()
+
+    elif convert_all:
+        files = find_session_files(root)
+        if not files:
+            warn("No session files found")
+            return
+
+        info(f"Found {len(files)} session files")
+        converted = 0
+        skipped = 0
+
+        for file_path in files:
+            result = convert_session_file(file_path, dry_run=dry_run)
+
+            if result.get("skipped"):
+                skipped += 1
+            elif result.get("success"):
+                converted += 1
+                if dry_run:
+                    info(f"Would convert: {file_path.name}")
+                else:
+                    success(f"Converted: {file_path.name}")
+            else:
+                error(f"Failed: {file_path.name} - {result.get('message')}")
+
+        click.echo("")
+        info(f"Summary: {converted} converted, {skipped} already XML")
+
+    else:
+        # Show available files
+        files = find_session_files(root)
+        if not files:
+            warn("No session files found")
+            return
+
+        info(f"Session files found: {len(files)}")
+        for f in files[:10]:
+            click.echo(f"  {f.relative_to(root)}")
+        if len(files) > 10:
+            click.echo(f"  ... and {len(files) - 10} more")
+        click.echo("")
+        info("Use --all to convert all, or specify a file path")
+
+
+@migration.command()
+@click.argument("skill_name", required=False)
+@click.option("--report", is_flag=True, help="Generate detailed report")
+def skill(skill_name: str | None, report: bool):
+    """Audit skill files for required XML tags.
+
+    \b
+    Arguments:
+      SKILL_NAME  - Specific skill to audit (optional)
+
+    \b
+    Examples:
+      pf migration skill --report
+      pf migration skill sprint
+    """
+    from pf.migration.skill import audit_skills
+
+    root = _find_project_root()
+    results = audit_skills(root, skill_name=skill_name)
+
+    if results["summary"].get("error"):
+        error(results["summary"]["error"])
+        raise click.Abort()
+
+    # Print results
+    for result in results["results"]:
+        if result.status == "OK":
+            success(f"{result.skill_name}: All tags present")
+        elif result.status == "PARTIAL":
+            warn(f"{result.skill_name}: Missing recommended: {', '.join(result.missing_recommended)}")
+        else:
+            error(f"{result.skill_name}: Missing required: {', '.join(result.missing_required)}")
+
+        if report and (result.missing_required or result.missing_recommended):
+            click.echo(f"    Present: {', '.join(result.present_tags)}")
+
+    # Print summary
+    summary = results["summary"]
+    click.echo("")
+    info("=== Summary ===")
+    click.echo(f"  Total:       {summary['total']}")
+    click.echo(f"  Valid:       {summary['valid']}")
+    click.echo(f"  Partial:     {summary['partial']}")
+    click.echo(f"  Needs work:  {summary['needs_update']}")
+
+    if summary["needs_update"] > 0:
+        click.echo("")
+        info("Skills needing updates:")
+        for result in results["results"]:
+            if not result.is_valid:
+                click.echo(f"  - {result.skill_name}")
+
+
+@migration.command()
+@click.argument("workflow_name", required=False)
+@click.option("--report", is_flag=True, help="Generate detailed report")
+def step(workflow_name: str | None, report: bool):
+    """Audit workflow step files for required XML tags.
+
+    \b
+    Arguments:
+      WORKFLOW_NAME  - Specific workflow to audit (optional)
+
+    \b
+    Examples:
+      pf migration step --report
+      pf migration step architecture
+    """
+    from pf.migration.step import audit_workflow_steps
+
+    root = _find_project_root()
+    results = audit_workflow_steps(root, workflow_name=workflow_name)
+
+    # Print results by workflow
+    for workflow in results["workflows"]:
+        info(f"Workflow: {workflow.workflow_name} ({workflow.total_steps} steps)")
+
+        for result in workflow.step_results:
+            if result.status == "OK":
+                if report:
+                    success(f"  {result.step_name}: OK")
+            elif result.status == "PARTIAL":
+                warn(f"  {result.step_name}: Missing recommended: {', '.join(result.missing_recommended)}")
+            else:
+                error(f"  {result.step_name}: Missing required: {', '.join(result.missing_required)}")
+
+    # Print summary
+    summary = results["summary"]
+    click.echo("")
+    info("=== Summary ===")
+    click.echo(f"  Workflows:   {summary['total_workflows']}")
+    click.echo(f"  Step files:  {summary['total_files']}")
+    click.echo(f"  Valid:       {summary['valid']}")
+    click.echo(f"  Needs work:  {summary['needs_update']}")
+
+    if summary["needs_update"] > 0:
+        click.echo("")
+        info("Workflows with missing required tags:")
+        for workflow in results["workflows"]:
+            if workflow.needs_update > 0:
+                click.echo(f"  - {workflow.workflow_name} ({workflow.needs_update} files)")
+
+
+@migration.command()
+@click.option(
+    "--type",
+    "file_type",
+    type=click.Choice(["session", "skill", "step", "all"]),
+    default="all",
+    help="Type of files to validate",
+)
+@click.option("--strict", is_flag=True, help="Treat warnings as errors")
+def validate(file_type: str, strict: bool):
+    """Validate files against XML schemas.
+
+    \b
+    Examples:
+      pf migration validate
+      pf migration validate --type skill
+      pf migration validate --strict
+    """
+    from pf.migration.validate import validate_all
+
+    root = _find_project_root()
+    summary = validate_all(root, file_type=file_type, strict=strict)
+
+    # Print results
+    for result in summary.results:
+        rel_path = result.file_path.relative_to(root) if root in result.file_path.parents else result.file_path
+        if result.status == "PASS":
+            success(f"{rel_path}")
+        elif result.status == "WARN":
+            warn(f"{rel_path}")
+            for w in result.warnings:
+                click.echo(f"    - {w}")
+        else:
+            error(f"{rel_path}")
+            for e in result.errors:
+                click.echo(f"    - {e}")
+
+    # Print summary
+    click.echo("")
+    info("=== Summary ===")
+    click.echo(f"  Passed:   {summary.passed}")
+    click.echo(f"  Warnings: {summary.warnings}")
+    click.echo(f"  Errors:   {summary.errors}")
+
+    if not summary.success:
+        raise click.Abort()
+
+    if strict and summary.warnings > 0:
+        error("Warnings treated as errors in strict mode")
+        raise click.Abort()
+
+
+# Alias for backwards compatibility
+cli = migration
+
+
+def main(args: list[str] | None = None) -> int:
+    """Entry point."""
+    try:
+        migration(args)
+        return 0
+    except SystemExit as e:
+        return e.code if isinstance(e.code, int) else 0
+
+
+if __name__ == "__main__":
+    migration()