@pennyfarthing/core 11.3.3 → 11.3.4

package/pennyfarthing-dist/pf/schema_validation_hook.py

@@ -0,0 +1,10 @@
+"""
+Backward-compatibility shim — schema validation hook moved to hooks/schema_validation.py.
+
+This file will be removed in a future version.
+"""
+
+from pf.hooks.schema_validation import main  # noqa: F401
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,87 @@
+"""
+Session CLI - Click-based CLI for session lifecycle management.
+
+Usage:
+    pf session [COMMAND] [ARGS]...
+
+Commands:
+    new       Start the next available story from the backlog
+    continue  Resume work from a saved checkpoint
+"""
+
+import click
+
+
+@click.group()
+def session():
+    """Session lifecycle management.
+
+    \b
+    Commands:
+      new       - Start the next available story from backlog
+      continue  - Resume from saved checkpoint after context circuit breaker
+    """
+    pass
+
+
+@session.command("new")
+def session_new():
+    """Start the next available story from the sprint backlog.
+
+    Equivalent to: pf sprint work next
+    """
+    # Delegate to sprint work command
+    from pf.sprint.work import start_work
+
+    start_work("next")
+
+
+@session.command("continue")
+@click.option("--list", "list_only", is_flag=True, help="Just display available checkpoints")
+@click.option("--story-id", help="Resume specific story directly")
+def session_continue(list_only: bool, story_id: str | None):
+    """Resume work from a saved checkpoint after context circuit breaker.
+
+    \b
+    Options:
+      --list       Display available checkpoints without restoring
+      --story-id   Resume specific story directly (skip selection)
+    """
+    from pf.common.config import get_project_root
+
+    root = get_project_root()
+    session_dir = root / ".session"
+
+    if not session_dir.is_dir():
+        click.echo("No .session/ directory found", err=True)
+        raise SystemExit(1)
+
+    checkpoints = sorted(session_dir.glob("*-checkpoint.md"))
+
+    if not checkpoints:
+        click.echo("No saved checkpoints found")
+        click.echo("Use /pf-session new to start a new story")
+        return
+
+    if list_only:
+        click.echo("Available checkpoints:")
+        for cp in checkpoints:
+            click.echo(f"  {cp.stem}")
+        return
+
+    if story_id:
+        matches = [cp for cp in checkpoints if story_id in cp.stem]
+        if not matches:
+            click.echo(f"No checkpoint found for story {story_id}", err=True)
+            raise SystemExit(1)
+        target = matches[0]
+    else:
+        click.echo("Available checkpoints:")
+        for i, cp in enumerate(checkpoints, 1):
+            click.echo(f"  {i}. {cp.stem}")
+        target = checkpoints[0]
+
+    click.echo("\nTo resume, load the agent with checkpoint context:")
+    click.echo(f"  Read: {target}")
+
+

package/pennyfarthing-dist/pf/session_start_hook.py

@@ -0,0 +1,10 @@
+"""
+Backward-compatibility shim — session start hook moved to hooks/session_start.py.
+
+This file will be removed in a future version.
+"""
+
+from pf.hooks.session_start import main  # noqa: F401
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,55 @@
+"""
+Settings CLI group — view and manage .pennyfarthing/config.local.yaml.
+
+Usage:
+    pf settings show          # Pretty-print interesting settings
+    pf settings get <key>     # Get value by dot-path
+    pf settings set <key> <value>  # Set value by dot-path
+"""
+
+import click
+
+
+@click.group()
+def settings():
+    """View and manage .pennyfarthing/config.local.yaml settings."""
+    pass
+
+
+@settings.command()
+def show():
+    """Pretty-print all interesting settings."""
+    from pf.settings.settings import show_settings
+
+    click.echo(show_settings())
+
+
+@settings.command()
+@click.argument("key")
+def get(key: str):
+    """Get a setting value by dot-path (e.g. workflow.relay_mode)."""
+    from pf.settings.settings import get_setting
+
+    try:
+        value = get_setting(key)
+    except KeyError:
+        click.echo(f"Key not found: {key}", err=True)
+        raise SystemExit(1) from None
+
+    if isinstance(value, dict):
+        import yaml
+
+        click.echo(yaml.dump(value, default_flow_style=False, sort_keys=False).rstrip())
+    else:
+        click.echo(value)
+
+
+@settings.command()
+@click.argument("key")
+@click.argument("value")
+def set(key: str, value: str):
+    """Set a setting value by dot-path (e.g. workflow.bell_mode true)."""
+    from pf.settings.settings import set_setting
+
+    set_setting(key, value)
+    click.echo(f"{key} = {value}")

package/pennyfarthing-dist/pf/settings/settings.py

@@ -0,0 +1,98 @@
+"""
+Settings logic for reading and writing .pennyfarthing/config.local.yaml.
+
+Provides dot-path traversal for get/set operations with type coercion.
+"""
+
+from typing import Any
+
+import yaml
+
+from pf.common.config import get_project_root, load_pennyfarthing_config
+
+# Top-level keys to show in `pf settings show` (skip layout/panel blobs)
+SHOW_KEYS = ("theme", "workflow", "jira", "display", "split", "last_panel")
+
+
+def _coerce_value(value: str) -> Any:
+    """Coerce a string value to bool, int, or leave as str."""
+    lower = value.lower()
+    if lower == "true":
+        return True
+    if lower == "false":
+        return False
+    try:
+        return int(value)
+    except ValueError:
+        return value
+
+
+def _get_by_path(data: dict, key: str) -> Any:
+    """Traverse a dict by dot-separated path.
+
+    Returns the value at the path, or raises KeyError if not found.
+    """
+    parts = key.split(".")
+    current: Any = data
+    for part in parts:
+        if not isinstance(current, dict) or part not in current:
+            raise KeyError(key)
+        current = current[part]
+    return current
+
+
+def _set_by_path(data: dict, key: str, value: Any) -> None:
+    """Set a value in a dict by dot-separated path, creating intermediates."""
+    parts = key.split(".")
+    current = data
+    for part in parts[:-1]:
+        if part not in current or not isinstance(current[part], dict):
+            current[part] = {}
+        current = current[part]
+    current[parts[-1]] = value
+
+
+def get_setting(key: str) -> Any:
+    """Get a setting value by dot-path."""
+    config = load_pennyfarthing_config()
+    return _get_by_path(config, key)
+
+
+def set_setting(key: str, value: str) -> dict:
+    """Set a setting value by dot-path. Returns the updated config."""
+    root = get_project_root()
+    config_path = root / ".pennyfarthing" / "config.local.yaml"
+
+    config = load_pennyfarthing_config(root)
+    coerced = _coerce_value(value)
+    _set_by_path(config, key, coerced)
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(config_path, "w") as f:
+        yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+
+    return config
+
+
+def show_settings() -> str:
+    """Format interesting top-level settings for display."""
+    config = load_pennyfarthing_config()
+    lines: list[str] = []
+
+    for key in SHOW_KEYS:
+        if key not in config:
+            continue
+        val = config[key]
+        if isinstance(val, dict):
+            lines.append(f"{key}:")
+            for k, v in val.items():
+                if isinstance(v, dict):
+                    nested = yaml.dump({k: v}, default_flow_style=False, sort_keys=False)
+                    for line in nested.rstrip().split("\n"):
+                        lines.append(f"  {line}")
+                else:
+                    lines.append(f"  {k}: {v}")
+        else:
+            lines.append(f"{key}: {val}")
+
+    return "\n".join(lines) if lines else "(no settings found)"

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

@@ -0,0 +1,64 @@
+"""
+Sprint management package for Pennyfarthing scripts.
+
+This package provides:
+- loader: Sprint YAML loading and parsing
+- status: Sprint status operations
+- work: Work session management
+- archive: Story archiving
+
+Usage:
+    # Use the loader module
+    from pf.sprint import load_sprint, find_epic
+    sprint_data = load_sprint()
+    epic = find_epic(sprint_data, "63")
+
+    # Use CLI
+    python -m pf.sprint <subcommand> [args]
+"""
+
+# Re-export from loader for backwards compatibility
+# Import submodules to make them accessible
+# CLI entry point - import module, not function, so "from sprint import cli" gets the module
+from pf.sprint import (
+    archive,
+    cli,
+    loader,
+    status,
+    work,
+)
+from pf.sprint.cli import main
+from pf.sprint.loader import (
+    find_epic,
+    find_story,
+    get_all_stories,
+    get_epic_by_id,
+    get_sprint_info,
+    get_stories_by_status,
+    get_story_by_id,
+    get_story_field,
+    load_current_sprint,
+    load_sprint,
+)
+
+__all__ = [
+    # Loader functions
+    "find_epic",
+    "find_story",
+    "get_all_stories",
+    "get_epic_by_id",
+    "get_sprint_info",
+    "get_stories_by_status",
+    "get_story_by_id",
+    "get_story_field",
+    "load_current_sprint",
+    "load_sprint",
+    # Submodules
+    "archive",
+    "loader",
+    "status",
+    "work",
+    # CLI
+    "cli",
+    "main",
+]

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

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

package/pennyfarthing-dist/pf/sprint/archive.py

@@ -0,0 +1,164 @@
+"""
+Sprint story archiving.
+
+Provides functions for archiving completed stories.
+"""
+
+from typing import Any
+
+from pf.common.config import get_project_root
+from pf.sprint.loader import get_story_by_id
+
+
+def archive_story(
+    story_id: str,
+    pr_number: str | None = None,
+    *,
+    dry_run: bool = False,
+    apply: bool = False,
+) -> dict[str, Any]:
+    """Archive a completed story to the sprint archive file.
+
+    Args:
+        story_id: Story ID to archive
+        pr_number: PR number if merged via PR
+        dry_run: If True, show what would be done
+        apply: If True, also remove from current-sprint.yaml
+
+    Returns:
+        Dict with success status and details
+    """
+    import re
+    from datetime import date
+
+    import yaml
+
+    # Find the story
+    story = get_story_by_id(story_id)
+    if not story:
+        return {
+            "success": False,
+            "error": f"Story '{story_id}' not found in sprint YAML",
+        }
+
+    # Check status
+    status = story.get("status", "backlog")
+    if status not in ("done", "completed", "review"):
+        return {
+            "success": False,
+            "error": f"Story status is '{status}', expected 'done' or 'completed'",
+        }
+
+    root = get_project_root()
+    sprint_file = root / "sprint" / "current-sprint.yaml"
+
+    if not sprint_file.exists():
+        return {"success": False, "error": f"Sprint file not found: {sprint_file}"}
+
+    # Get sprint name for archive file
+    with open(sprint_file) as f:
+        sprint_data = yaml.safe_load(f.read())
+
+    sprint_name = sprint_data.get("sprint", {}).get("jira_sprint_name", "")
+    match = re.search(r"(\d{4})", sprint_name)
+    sprint_num = match.group(1) if match else "unknown"
+    archive_file = root / "sprint" / "archive" / f"sprint-{sprint_num}-completed.yaml"
+
+    # Find parent epic
+    epic_id = ""
+    for epic in sprint_data.get("epics", []):
+        if isinstance(epic, dict):
+            for s in epic.get("stories", []):
+                if s.get("id") == story_id:
+                    epic_id = str(epic.get("id", ""))
+                    break
+
+    completed_date = str(date.today())
+
+    if dry_run:
+        return {
+            "success": True,
+            "dry_run": True,
+            "story": story,
+            "pr_number": pr_number,
+            "message": f"Would archive {story_id} to {archive_file}",
+        }
+
+    # Append to archive file
+    if not archive_file.exists():
+        return {"success": False, "error": f"Archive file not found: {archive_file}"}
+
+    entry_lines = [
+        f"  - id: {story_id}",
+        f"    epic: {epic_id}",
+        f'    title: "{story.get("title", "Unknown")}"',
+        f"    points: {story.get('points', 0)}",
+        f"    completed: {completed_date}",
+    ]
+    if pr_number:
+        entry_lines.append(f"    pr: {pr_number}")
+
+    with open(archive_file, "a") as f:
+        f.write("\n".join(entry_lines) + "\n")
+
+    msg = f"Archived {story_id} to {archive_file.name}"
+
+    # Remove from current sprint if --apply
+    if apply:
+        for epic in sprint_data.get("epics", []):
+            if isinstance(epic, dict):
+                epic["stories"] = [s for s in epic.get("stories", []) if s.get("id") != story_id]
+
+        from pf.sprint.yaml_io import write_sprint
+        write_sprint(sprint_file, sprint_data)
+        msg += f" and removed from {sprint_file.name}"
+
+    return {
+        "success": True,
+        "story": story,
+        "pr_number": pr_number,
+        "message": msg,
+    }
+
+
+def main(args: list[str] | None = None) -> int:
+    """CLI entry point for sprint archive.
+
+    Args:
+        args: Command line arguments
+
+    Returns:
+        Exit code
+    """
+    import argparse
+    import sys
+
+    parser = argparse.ArgumentParser(description="Archive a completed story")
+    parser.add_argument("story_id", help="Story ID to archive")
+    parser.add_argument("pr_number", nargs="?", help="PR number if merged via PR")
+    parser.add_argument("--apply", action="store_true", help="Also remove from current-sprint.yaml")
+    parser.add_argument("--dry-run", action="store_true", help="Show what would be done")
+
+    parsed = parser.parse_args(args)
+
+    result = archive_story(
+        parsed.story_id,
+        pr_number=parsed.pr_number,
+        dry_run=parsed.dry_run,
+        apply=parsed.apply,
+    )
+
+    if result.get("success"):
+        if result.get("dry_run"):
+            print(f"[DRY-RUN] {result.get('message')}")
+        else:
+            print(result.get("message"))
+        return 0
+    else:
+        print(f"Failed: {result.get('error')}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())