@pennyfarthing/core 11.3.2 → 11.3.4

package/pennyfarthing-dist/pf/workflow/helpers.py

@@ -0,0 +1,241 @@
+"""
+Shared helpers for workflow commands.
+
+Extracted from complete-step.py and bash scripts. Provides common
+functions for session parsing, workflow file resolution, and step management.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+from pf.common.config import get_project_root
+
+
+def get_workflows_dir(project_root: Path | None = None) -> Path:
+    """Get the workflows directory path."""
+    root = project_root or get_project_root()
+    return root / ".pennyfarthing" / "workflows"
+
+
+def get_session_dir(project_root: Path | None = None) -> Path:
+    """Get the session directory path."""
+    root = project_root or get_project_root()
+    return root / ".session"
+
+
+def find_workflow_file(workflows_dir: Path, workflow_name: str) -> Path | None:
+    """Find workflow YAML definition.
+
+    Supports both flat (name.yaml) and nested (name/workflow.yaml) layouts.
+
+    Returns:
+        Path to the workflow file, or None if not found.
+    """
+    flat = workflows_dir / f"{workflow_name}.yaml"
+    if flat.exists():
+        return flat
+
+    nested = workflows_dir / workflow_name / "workflow.yaml"
+    if nested.exists():
+        return nested
+
+    return None
+
+
+def load_workflow_data(workflow_file: Path) -> dict:
+    """Load and parse workflow YAML file.
+
+    Returns:
+        Parsed YAML data dict.
+    """
+    with open(workflow_file) as f:
+        return yaml.safe_load(f) or {}
+
+
+def get_workflow_type(workflow_data: dict) -> str:
+    """Get workflow type from parsed YAML data.
+
+    Returns:
+        'phased', 'stepped', or 'procedural'
+    """
+    wf = workflow_data.get("workflow", {})
+    wf_type = wf.get("type", "phased")
+    has_steps = wf.get("steps") is not None
+    if has_steps or wf_type == "stepped":
+        return "stepped"
+    return wf_type
+
+
+def resolve_steps_path(
+    workflow_data: dict,
+    workflow_dir: Path,
+    mode: str | None,
+    project_root: Path,
+) -> Path:
+    """Resolve the steps directory path from workflow data.
+
+    Handles mode-specific paths, relative paths, and absolute paths.
+
+    Args:
+        workflow_data: Parsed workflow YAML
+        workflow_dir: Directory containing the workflow.yaml file
+        mode: Active mode (create, validate, edit) or None
+        project_root: Project root directory
+
+    Returns:
+        Resolved absolute Path to steps directory
+    """
+    wf = workflow_data.get("workflow", {})
+
+    # Try mode-specific path first
+    if mode:
+        modes = wf.get("modes", {})
+        mode_path = modes.get(mode)
+        if mode_path and mode_path != "null":
+            return _resolve_path(mode_path, workflow_dir, project_root)
+
+    # Try default mode
+    default_mode = wf.get("modes", {}).get("default")
+    if default_mode:
+        modes = wf.get("modes", {})
+        mode_path = modes.get(default_mode)
+        if mode_path and mode_path != "null":
+            return _resolve_path(mode_path, workflow_dir, project_root)
+
+    # Fall back to steps.path
+    steps_path_str = wf.get("steps", {}).get("path", ".")
+    return _resolve_path(steps_path_str, workflow_dir, project_root)
+
+
+def _resolve_path(path_str: str, workflow_dir: Path, project_root: Path) -> Path:
+    """Resolve a path string relative to workflow dir or project root."""
+    if path_str.startswith("./"):
+        return workflow_dir / path_str[2:]
+    elif not Path(path_str).is_absolute():
+        return project_root / path_str
+    else:
+        return Path(path_str)
+
+
+def count_steps(steps_path: Path) -> int:
+    """Count step files in a directory."""
+    if not steps_path.is_dir():
+        return 0
+    return len([
+        f for f in steps_path.iterdir()
+        if f.is_file() and re.match(r"step-\d+", f.name) and f.suffix == ".md"
+    ])
+
+
+def find_step_file(steps_path: Path, step_number: int) -> Path | None:
+    """Find step file for a given step number.
+
+    Handles naming variants: step-01.md, step-01-name.md, step-1-name.md
+    """
+    padded = f"{step_number:02d}"
+    matches = sorted([
+        f for f in steps_path.iterdir()
+        if f.is_file()
+        and (f.name.startswith(f"step-{padded}") or f.name.startswith(f"step-{step_number}-"))
+        and f.suffix == ".md"
+    ])
+    return matches[0] if matches else None
+
+
+def strip_frontmatter(content: str) -> str:
+    """Remove YAML frontmatter from step file content."""
+    if not content.startswith("---"):
+        return content
+    end = content.find("---", 3)
+    if end == -1:
+        return content
+    return content[end + 3:].lstrip("\n")
+
+
+def parse_session_field(content: str, field: str) -> str:
+    """Extract a field value from session markdown.
+
+    Matches lines like: - **Field:** value
+    """
+    pattern = rf"^- \*\*{re.escape(field)}:\*\*\s*(.+)$"
+    match = re.search(pattern, content, re.MULTILINE)
+    return match.group(1).strip() if match else ""
+
+
+def find_workflow_session(
+    session_dir: Path, workflow_name: str | None
+) -> tuple[Path, str] | None:
+    """Find workflow session file and determine workflow name.
+
+    Args:
+        session_dir: Path to .session/ directory
+        workflow_name: Explicit workflow name, or None to auto-detect
+
+    Returns:
+        Tuple of (session_path, workflow_name), or None if not found
+    """
+    if workflow_name:
+        session_file = session_dir / f"{workflow_name}-workflow-session.md"
+        if session_file.exists():
+            return session_file, workflow_name
+        return None
+
+    # Auto-detect from session directory
+    sessions = sorted(session_dir.glob("*-workflow-session.md"))
+    if not sessions:
+        return None
+
+    session_file = sessions[0]
+    content = session_file.read_text()
+
+    # Try to extract workflow name from content
+    wf_match = re.search(r"^\*\*Workflow:\*\*\s*(.+)$", content, re.MULTILINE)
+    if wf_match:
+        name = wf_match.group(1).strip()
+    else:
+        name = session_file.stem.replace("-workflow-session", "")
+
+    return session_file, name
+
+
+def parse_steps_completed(value: str) -> list[int]:
+    """Parse steps completed array from string like '[1, 2, 3]'."""
+    if not value or value == "[]":
+        return []
+    return [int(n) for n in re.findall(r"\d+", value)]
+
+
+def format_steps_completed(steps: list[int]) -> str:
+    """Format steps list as bracket notation."""
+    if not steps:
+        return "[]"
+    return "[" + ", ".join(str(s) for s in steps) + "]"
+
+
+def find_story_session(session_dir: Path, story_id: str) -> Path | None:
+    """Find a story session file by story ID.
+
+    Handles various naming patterns: 56-1-session.md, MSSCI-12190-session.md
+    Also searches file content for matching Jira/ID fields.
+    """
+    # Try direct filename match
+    story_id_lower = story_id.lower()
+    for pattern in [f"{story_id}-session.md", f"{story_id_lower}-session.md"]:
+        candidate = session_dir / pattern
+        if candidate.exists():
+            return candidate
+
+    # Search file contents for matching story ID
+    for session_file in session_dir.glob("*-session.md"):
+        try:
+            content = session_file.read_text()
+            if f"Jira:** {story_id}" in content or f"ID:** {story_id}" in content:
+                return session_file
+        except OSError:
+            continue
+
+    return None

package/pennyfarthing-dist/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "pennyfarthing-scripts"
+version = "8.1.0"
+requires-python = ">=3.11"
+dependencies = ["pyyaml>=6.0", "ruamel.yaml>=0.18", "httpx>=0.28", "click>=8.0", "pydriller>=2.6"]
+
+[project.optional-dependencies]
+tui = ["textual>=1.0", "websockets>=12.0", "textual-image>=0.7.0"]
+
+[project.scripts]
+pf = "pf.cli:main"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["pf*"]

package/pennyfarthing-dist/scripts/core/agent-session.sh

@@ -8,11 +8,11 @@
 #
 # Session files stored in .session/agents/<session-id> for multi-session support
 
-# Find package root (where pennyfarthing_scripts lives) from script location
+# Find package root (where pf/ lives) from script location
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
-PACKAGE_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd -P)"
+PACKAGE_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd -P)"
 
-# Set PYTHONPATH so Python can find pennyfarthing_scripts
+# Set PYTHONPATH so Python can find pf package
 export PYTHONPATH="${PACKAGE_ROOT}:${PYTHONPATH:-}"
 
 # Agents directory for multi-session support

package/pennyfarthing-dist/scripts/core/check-context.sh

@@ -2,7 +2,7 @@
 # check-context.sh - Check current Claude Code context usage
 # Returns: percentage and recommendation for handoff
 #
-# This is a thin wrapper around pennyfarthing_scripts/context.py
+# This is a thin wrapper around pf/context.py
 #
 # Usage:
 #   ./check-context.sh                    # Output env vars (most recent transcript)
@@ -14,7 +14,7 @@ set -euo pipefail
 
 echo "DEPRECATED: check-context.sh — use 'pf context' instead" >&2
 
-# Find project root (where pennyfarthing_scripts lives)
+# Find project root (where pf lives)
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 
 # Resolve symlinks to find actual location
@@ -29,17 +29,17 @@ if [[ "$REAL_DIR" == *"/pennyfarthing-dist/scripts/core" ]]; then
 elif [[ "$REAL_DIR" == *"/node_modules/"* ]]; then
     # In node_modules, walk up to find project root
     PACKAGE_ROOT="${REAL_DIR}"
-    while [[ "$PACKAGE_ROOT" != "/" ]] && [[ ! -d "$PACKAGE_ROOT/pennyfarthing_scripts" ]]; do
+    while [[ "$PACKAGE_ROOT" != "/" ]] && [[ ! -d "$PACKAGE_ROOT/pf" ]]; do
         PACKAGE_ROOT="$(dirname "$PACKAGE_ROOT")"
     done
 fi
 
-# Try to find pennyfarthing_scripts
+# Try to find pf
 PYTHON_MODULE=""
-if [[ -f "$PACKAGE_ROOT/pennyfarthing_scripts/context.py" ]]; then
-    PYTHON_MODULE="$PACKAGE_ROOT/pennyfarthing_scripts/context.py"
-elif [[ -f "${PROJECT_ROOT:-}/pennyfarthing_scripts/context.py" ]]; then
-    PYTHON_MODULE="${PROJECT_ROOT}/pennyfarthing_scripts/context.py"
+if [[ -f "$PACKAGE_ROOT/pf/context.py" ]]; then
+    PYTHON_MODULE="$PACKAGE_ROOT/pf/context.py"
+elif [[ -f "${PROJECT_ROOT:-}/pf/context.py" ]]; then
+    PYTHON_MODULE="${PROJECT_ROOT}/pf/context.py"
 fi
 
 # If Python module exists, use it

package/pennyfarthing-dist/scripts/hooks/pre-commit.sh

@@ -158,7 +158,7 @@ if [[ -n "$SPRINT_YAML_FILES" ]]; then
         # Set PYTHONPATH to include pennyfarthing source
         PYTHONPATH_ORIG="${PYTHONPATH:-}"
         if [[ -d "$PROJECT_ROOT/pennyfarthing" ]]; then
-            export PYTHONPATH="$PROJECT_ROOT/pennyfarthing${PYTHONPATH_ORIG:+:$PYTHONPATH_ORIG}"
+            export PYTHONPATH="$PROJECT_ROOT/pennyfarthing/pennyfarthing-dist${PYTHONPATH_ORIG:+:$PYTHONPATH_ORIG}"
         fi
 
         VALIDATION_FAILED=0
@@ -171,7 +171,7 @@ if [[ -n "$SPRINT_YAML_FILES" ]]; then
             if ! $PYTHON -c "
 import sys
 from pathlib import Path
-from pennyfarthing_scripts.sprint.validate_cmd import validate_sprint_yaml
+from pf.sprint.validate_cmd import validate_sprint_yaml
 result = validate_sprint_yaml(Path(sys.argv[1]))
 if result.errors:
     for e in result.errors:
@@ -198,7 +198,7 @@ sys.exit(0 if result.valid else 1)
             echo "COMMIT BLOCKED - Sprint YAML validation failed"
             echo ""
             echo "Fix: Review errors above, then run:"
-            echo "  python3 -m pennyfarthing_scripts.sprint.validate_cmd --fix <file>"
+            echo "  python3 -m pf.sprint.validate_cmd --fix <file>"
             echo ""
             exit 1
         fi

package/pennyfarthing-dist/scripts/jira/README.md

@@ -18,7 +18,7 @@ Scripts for Jira integration, synchronization, and story management.
 
 ## Python Implementation
 
-Core logic lives in `pennyfarthing_scripts/jira/`:
+Core logic lives in `pf/jira/`:
 - `sync.py` — Epic and story sync
 - `bidirectional.py` — Two-way YAML ↔ Jira sync
 - `story.py` — Story operations

package/pennyfarthing-dist/scripts/jira/create-jira-epic.sh

@@ -3,7 +3,7 @@
 # Usage: create-jira-epic.sh <epic-id> [--dry-run]
 #
 # Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.jira create epic <epic-id> [--dry-run]
+#   python -m pf.jira create epic <epic-id> [--dry-run]
 
 set -e
 

package/pennyfarthing-dist/scripts/jira/create-jira-story.sh

@@ -3,7 +3,7 @@
 # Usage: create-jira-story.sh <epic-jira-key> <story-id> [--dry-run]
 #
 # Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.jira create story <epic-jira-key> <story-id> [--dry-run]
+#   python -m pf.jira create story <epic-jira-key> <story-id> [--dry-run]
 
 set -e
 

package/pennyfarthing-dist/scripts/jira/jira-claim-story.sh

@@ -3,7 +3,7 @@
 # Usage: jira-claim-story.sh <issue-key> [--claim]
 #
 # Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.jira claim <issue-key> [--claim]
+#   python -m pf.jira claim <issue-key> [--claim]
 #
 # Exit codes:
 #   0 - Story is available or successfully claimed

package/pennyfarthing-dist/scripts/jira/jira-reconcile.sh

@@ -3,7 +3,7 @@
 # Usage: jira-reconcile.sh [--fix]
 #
 # Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.jira reconcile [--fix]
+#   python -m pf.jira reconcile [--fix]
 
 set -e
 

package/pennyfarthing-dist/scripts/jira/jira-sync-story.sh

@@ -3,7 +3,7 @@
 # Usage: jira-sync-story.sh <story_key> [--transition] [--points] [--comment "message"]
 #
 # Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.jira create story <story_key> [options]
+#   python -m pf.jira create story <story_key> [options]
 #
 # Note: The subcommand is 'create story' but it handles sync, not creation.
 

package/pennyfarthing-dist/scripts/jira/sync-epic-jira.sh

@@ -3,7 +3,7 @@
 # Usage: sync-epic-jira.sh <epic-id> [--dry-run] [--transition] [--points] [--all]
 #
 # Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.jira sync <epic-id> [options]
+#   python -m pf.jira sync <epic-id> [options]
 
 set -e
 

package/pennyfarthing-dist/scripts/lib/common.sh

@@ -171,7 +171,7 @@ check_dependencies() {
 #
 # Usage:
 #   get_python
-#   $PYTHON_CMD -m pennyfarthing_scripts.jira view MSSCI-12345
+#   $PYTHON_CMD -m pf.jira view MSSCI-12345
 #
 get_python() {
     # Find project root if not set
@@ -197,7 +197,7 @@ get_python() {
 }
 
 # run_python_module MODULE [ARGS...]
-# Run a pennyfarthing_scripts Python module with proper venv handling
+# Run a pf Python module with proper venv handling
 #
 # Usage:
 #   run_python_module jira view MSSCI-12345
@@ -208,5 +208,5 @@ run_python_module() {
     get_python || return 1
     local module="$1"
     shift
-    exec $PYTHON_CMD -m "pennyfarthing_scripts.${module}" "$@"
+    exec $PYTHON_CMD -m "pf.${module}" "$@"
 }

package/pennyfarthing-dist/scripts/lib/run-pf.sh

@@ -2,8 +2,9 @@
 # Shared utility: Run the `pf` CLI via uv run — no global install needed.
 #
 # Resolution order for pyproject.toml:
-# 1. Dogfooding: $PROJECT_ROOT/pennyfarthing/pyproject.toml (inlined repo)
-# 2. Consumer:   $PROJECT_ROOT/pyproject.toml (project declares dependency)
+# 1. Dogfooding: $PROJECT_ROOT/pennyfarthing/pennyfarthing-dist/pyproject.toml (inlined repo)
+# 2. Consumer:   $PROJECT_ROOT/.pennyfarthing/pyproject.toml (symlinked from dist)
+# 3. Fallback:   $PROJECT_ROOT/pyproject.toml (project declares dependency)
 #
 # Usage from hook shims:
 #   source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
@@ -15,25 +16,22 @@ source "$_lib_dir/find-root.sh"
 
 # Find the pyproject.toml that provides pennyfarthing-scripts
 _pf_project=""
-if [[ -f "$PROJECT_ROOT/pennyfarthing/pyproject.toml" ]]; then
+if [[ -f "$PROJECT_ROOT/pennyfarthing/pennyfarthing-dist/pyproject.toml" ]]; then
     # Dogfooding: inlined framework repo
-    _pf_project="$PROJECT_ROOT/pennyfarthing"
-elif [[ -f "$PROJECT_ROOT/node_modules/@pennyfarthing/core/pyproject.toml" ]]; then
-    # Symlink install: npm package has full Python source
-    _pf_project="$PROJECT_ROOT/node_modules/@pennyfarthing/core"
+    _pf_project="$PROJECT_ROOT/pennyfarthing/pennyfarthing-dist"
+elif [[ -f "$PROJECT_ROOT/.pennyfarthing/pyproject.toml" ]]; then
+    # Consumer: auto-generated by pennyfarthing init (symlinked from dist)
+    _pf_project="$PROJECT_ROOT/.pennyfarthing"
 elif [[ -f "$PROJECT_ROOT/pyproject.toml" ]]; then
     # Consumer: project-level pyproject.toml with pennyfarthing-scripts dep
     _pf_project="$PROJECT_ROOT"
-elif [[ -f "$PROJECT_ROOT/.pennyfarthing/pyproject.toml" ]]; then
-    # Consumer: auto-generated by pennyfarthing init
-    _pf_project="$PROJECT_ROOT/.pennyfarthing"
 fi
 
 if [[ -z "$_pf_project" ]]; then
     echo "Error: No pyproject.toml found for pennyfarthing-scripts" >&2
-    echo "Expected: $PROJECT_ROOT/pennyfarthing/pyproject.toml (dogfooding)" >&2
-    echo "      or: $PROJECT_ROOT/pyproject.toml (consumer)" >&2
-    echo "      or: $PROJECT_ROOT/.pennyfarthing/pyproject.toml (auto-generated)" >&2
+    echo "Expected: $PROJECT_ROOT/pennyfarthing/pennyfarthing-dist/pyproject.toml (dogfooding)" >&2
+    echo "      or: $PROJECT_ROOT/.pennyfarthing/pyproject.toml (consumer)" >&2
+    echo "      or: $PROJECT_ROOT/pyproject.toml (fallback)" >&2
     exit 1
 fi
 

package/pennyfarthing-dist/scripts/sprint/README.md

@@ -40,5 +40,5 @@ pf.sh sprint epic promote epic-41
 ## Migration Note
 
 All bash scripts previously in this directory have been migrated to Python CLI
-commands in `pennyfarthing_scripts/sprint/cli.py`. See PR #716 and the follow-up
+commands in `pf/sprint/cli.py`. See PR #716 and the follow-up
 deprecation commit for details.

package/pennyfarthing-dist/scripts/story/create-story.sh

@@ -6,7 +6,7 @@
 #   --priority P0|P1|P2|P3             Priority (default: P2)
 #
 # Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.story create <epic-id> "<title>" <points> [options]
+#   python -m pf.story create <epic-id> "<title>" <points> [options]
 
 set -e
 

package/pennyfarthing-dist/scripts/story/size-story.sh

@@ -5,7 +5,7 @@
 #   points:  Show specific guidance for that point value
 #
 # Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.story size [points]
+#   python -m pf.story size [points]
 
 set -e
 

package/pennyfarthing-dist/scripts/story/story-template.sh

@@ -5,7 +5,7 @@
 #   type:    Show specific template
 #
 # Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.story template [type]
+#   python -m pf.story template [type]
 
 set -e
 

package/pennyfarthing-dist/scripts/theme/list-themes.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # list-themes.sh - List all available persona themes
 #
-# Thin wrapper: discovery logic lives in pennyfarthing_scripts.common.themes
+# Thin wrapper: discovery logic lives in pf.common.themes
 #
 # Usage: list-themes.sh [--current-only]
 
@@ -14,7 +14,7 @@ export PROJECT_ROOT
 
 if [[ "${1:-}" == "--current-only" ]]; then
     python3 -c "
-from pennyfarthing_scripts.common.themes import get_current_theme
+from pf.common.themes import get_current_theme
 t = get_current_theme()
 if t:
     print(t)
@@ -24,7 +24,7 @@ else:
 "
 else
     python3 -c "
-from pennyfarthing_scripts.common.themes import format_theme_list
+from pf.common.themes import format_theme_list
 print(format_theme_list())
 "
 fi

package/pennyfarthing-dist/templates/pyproject.toml

@@ -1,5 +1,5 @@
 # Auto-generated by pennyfarthing init — provides Python dependencies for hooks.
-# This file enables `uv run --project` to resolve pennyfarthing_scripts.
+# This file enables `uv run --project` to resolve the pf package.
 # Safe to customize: init/update will not overwrite this file once created.
 
 [project]
@@ -17,11 +17,11 @@ dependencies = [
 ]
 
 [project.scripts]
-pf = "pennyfarthing_scripts.cli:main"
+pf = "pf.cli:main"
 
 [build-system]
 requires = ["setuptools>=68.0"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools.packages.find]
-include = ["pennyfarthing_scripts*"]
+include = ["pf*"]

package/pennyfarthing-dist/workflows/project-setup/steps/step-08-theme-packs.md

@@ -139,4 +139,4 @@ To see what's available: /theme list
 
 ## NEXT STEP
 
-After theme packs, proceed to `step-09-cyclist.md` to optionally install Cyclist visual terminal.
+After theme packs, proceed to `step-09-jira.md` to configure the Jira project key.