@pennyfarthing/core 11.3.8 → 11.5.0-alpha.0

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

@@ -0,0 +1,186 @@
+"""Package CLI — theme package installation and portrait downloads.
+
+Usage:
+    pf package list              # Show all theme packages with status
+    pf package install comedy    # Install package + download portraits
+    pf package install-portraits comedy  # Download portraits for installed package
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+
+
+@click.group()
+def package():
+    """Theme package management.
+
+    \b
+    Commands:
+      list               - Show all theme packages with status
+      install            - Install a theme package (npm + portraits)
+      install-portraits  - Download portraits for installed packages
+    """
+    pass
+
+
+@package.command("list")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON.")
+def list_cmd(output_json: bool):
+    """Show all theme packages with installation status.
+
+    Displays each of the 7 theme packages with their current state:
+    installed, not installed, and whether portraits are downloaded.
+    """
+    from pf.package.discovery import get_package_status
+
+    statuses = get_package_status()
+
+    if output_json:
+        click.echo(json.dumps(statuses, indent=2))
+        return
+
+    click.echo("Theme Packages")
+    click.echo("=" * 50)
+    click.echo("")
+
+    for pkg in statuses:
+        name = pkg["name"]
+        if not pkg["installed"]:
+            status = "not installed"
+        elif pkg["portraits"]:
+            status = "installed + portraits"
+        else:
+            status = "installed (no portraits)"
+        click.echo(f"  {name:<22} {status}")
+
+    click.echo("")
+    installed = sum(1 for p in statuses if p["installed"])
+    with_portraits = sum(1 for p in statuses if p["portraits"])
+    click.echo(f"{installed}/{len(statuses)} installed, {with_portraits} with portraits")
+
+
+@package.command()
+@click.argument("name")
+@click.option("--skip-portraits", is_flag=True, help="Skip portrait download after install.")
+@click.option("--all-sizes", is_flag=True, help="Download all portrait sizes (default: large only).")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes.")
+def install(name: str, skip_portraits: bool, all_sizes: bool, dry_run: bool):
+    """Install a theme package and download its portraits.
+
+    Runs npm install for the package, then downloads portraits from
+    the GitHub monorepo via the gh CLI. Portraits are saved into the
+    package's node_modules directory where the portrait-resolver
+    already looks for them.
+
+    \b
+    Arguments:
+      NAME  - Theme package name (comedy, literary, mythology-fantasy,
+              prestige-tv, realistic, scifi, superheroes)
+    """
+    from pf.package.discovery import is_package_installed, npm_install
+    from pf.package.portraits import download_portraits
+
+    # Step 1: npm install
+    if is_package_installed(name) and not dry_run:
+        click.echo(f"@pennyfarthing/themes-{name} already installed, skipping npm install")
+    else:
+        if dry_run:
+            click.echo(f"[DRY-RUN] Would run: npm install @pennyfarthing/themes-{name}")
+        else:
+            click.echo(f"Installing @pennyfarthing/themes-{name}...")
+
+        result = npm_install(name, dry_run=dry_run)
+        if not result["success"]:
+            click.echo(f"Error: {result['error']}", err=True)
+            sys.exit(1)
+
+        if dry_run:
+            click.echo(f"  Command: {result['data']['command']}")
+        else:
+            click.echo("  Installed successfully")
+
+    # Step 2: download portraits
+    if skip_portraits:
+        if not dry_run:
+            click.echo("Skipping portrait download (--skip-portraits)")
+        return
+
+    if dry_run:
+        click.echo(f"[DRY-RUN] Would download portraits (sizes: {'all' if all_sizes else 'large only'})")
+    else:
+        click.echo(f"Downloading portraits ({'all sizes' if all_sizes else 'large only'})...")
+
+    result = download_portraits(name, all_sizes=all_sizes, dry_run=dry_run)
+    if not result["success"]:
+        click.echo(f"Error: {result['error']}", err=True)
+        sys.exit(1)
+
+    data = result["data"]
+    if dry_run:
+        click.echo(f"  {data['total_files']} files to download")
+        click.echo(f"  Destination: {data['destination']}")
+        if data.get("files"):
+            for f in data["files"]:
+                click.echo(f"    {f}")
+            if data.get("truncated"):
+                click.echo("    ...")
+    else:
+        click.echo(f"  Downloaded: {data['downloaded']}, Skipped: {data['skipped']}, Total: {data['total']}")
+        if data.get("error_count"):
+            click.echo(f"  Errors: {data['error_count']}")
+
+
+@package.command("install-portraits")
+@click.argument("name", required=False)
+@click.option("--all", "install_all", is_flag=True, help="Download portraits for all installed packages.")
+@click.option("--all-sizes", is_flag=True, help="Download all portrait sizes (default: large only).")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes.")
+def install_portraits(name: str | None, install_all: bool, all_sizes: bool, dry_run: bool):
+    """Download portraits for already-installed theme packages.
+
+    Requires either a package NAME or --all. Downloads portrait images
+    from the GitHub monorepo and saves them into the package's
+    node_modules directory.
+
+    \b
+    Arguments:
+      NAME  - Theme package name (optional if --all is used)
+    """
+    from pf.package.discovery import THEME_PACKAGES, is_package_installed
+    from pf.package.portraits import download_portraits
+
+    if not name and not install_all:
+        click.echo("Error: provide a package name or use --all", err=True)
+        sys.exit(1)
+
+    packages = THEME_PACKAGES if install_all else [name]
+
+    for pkg_name in packages:
+        if not is_package_installed(pkg_name):
+            if install_all:
+                continue  # silently skip uninstalled packages in --all mode
+            click.echo(
+                f"Error: @pennyfarthing/themes-{pkg_name} is not installed. "
+                f"Run: pf package install {pkg_name}",
+                err=True,
+            )
+            sys.exit(1)
+
+        click.echo(f"Downloading portraits for {pkg_name} ({'all sizes' if all_sizes else 'large only'})...")
+
+        result = download_portraits(pkg_name, all_sizes=all_sizes, dry_run=dry_run)
+        if not result["success"]:
+            click.echo(f"  Error: {result['error']}", err=True)
+            if not install_all:
+                sys.exit(1)
+            continue
+
+        data = result["data"]
+        if dry_run:
+            click.echo(f"  [DRY-RUN] {data['total_files']} files would be downloaded")
+        else:
+            click.echo(f"  Downloaded: {data['downloaded']}, Skipped: {data['skipped']}, Total: {data['total']}")

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

@@ -0,0 +1,130 @@
+"""Package discovery and npm install wrapper for theme packages.
+
+Checks installation status of @pennyfarthing/themes-* packages and
+provides npm install functionality.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from pf.common.config import get_project_root
+
+THEME_PACKAGES = [
+    "comedy",
+    "literary",
+    "mythology-fantasy",
+    "prestige-tv",
+    "realistic",
+    "scifi",
+    "superheroes",
+]
+
+PORTRAIT_SIZES = ["small", "medium", "large", "xlarge"]
+
+
+def _node_modules_dir(project_root: Path | None = None) -> Path:
+    """Return the node_modules/@pennyfarthing directory."""
+    root = project_root or get_project_root()
+    return root / "node_modules" / "@pennyfarthing"
+
+
+def get_package_dir(name: str, project_root: Path | None = None) -> Path:
+    """Return the path to a theme package in node_modules."""
+    return _node_modules_dir(project_root) / f"themes-{name}"
+
+
+def is_package_installed(name: str, project_root: Path | None = None) -> bool:
+    """Check if a theme package is installed in node_modules."""
+    pkg_dir = get_package_dir(name, project_root)
+    pkg_json = pkg_dir / "package.json"
+    if not pkg_json.is_file():
+        return False
+    try:
+        data = json.loads(pkg_json.read_text())
+        return data.get("pennyfarthing-theme-pack") is True
+    except Exception:
+        return False
+
+
+def has_portraits(name: str, project_root: Path | None = None) -> bool:
+    """Check if a theme package has portraits downloaded."""
+    pkg_dir = get_package_dir(name, project_root)
+    portraits_dir = pkg_dir / "portraits"
+    if not portraits_dir.is_dir():
+        return False
+    # Check for at least one image file in any subdirectory
+    for child in portraits_dir.rglob("*"):
+        if child.is_file() and child.suffix.lower() in (".png", ".jpg", ".jpeg", ".webp"):
+            return True
+    return False
+
+
+def get_package_status(
+    project_root: Path | None = None,
+) -> list[dict[str, Any]]:
+    """Get installation status for all theme packages.
+
+    Returns:
+        List of dicts with keys: name, installed, portraits
+    """
+    results = []
+    for name in THEME_PACKAGES:
+        installed = is_package_installed(name, project_root)
+        portraits = has_portraits(name, project_root) if installed else False
+        results.append({
+            "name": name,
+            "installed": installed,
+            "portraits": portraits,
+        })
+    return results
+
+
+def npm_install(
+    name: str,
+    project_root: Path | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Install a theme package via npm.
+
+    Args:
+        name: Theme package name (e.g. "comedy")
+        project_root: Project root (auto-detected if not provided)
+        dry_run: If True, show what would happen without executing
+
+    Returns:
+        Result dict with success, data?, error?
+    """
+    if name not in THEME_PACKAGES:
+        return {"success": False, "error": f"Unknown theme package: {name}"}
+
+    if shutil.which("npm") is None:
+        return {"success": False, "error": "npm not found. Install Node.js first."}
+
+    root = project_root or get_project_root()
+    pkg_spec = f"@pennyfarthing/themes-{name}"
+
+    if dry_run:
+        return {
+            "success": True,
+            "data": {"action": "dry-run", "command": f"npm install {pkg_spec}", "cwd": str(root)},
+        }
+
+    result = subprocess.run(
+        ["npm", "install", pkg_spec],
+        capture_output=True,
+        text=True,
+        cwd=str(root),
+    )
+
+    if result.returncode != 0:
+        return {
+            "success": False,
+            "error": f"npm install failed: {result.stderr.strip()}",
+        }
+
+    return {"success": True, "data": {"package": pkg_spec, "output": result.stdout.strip()}}

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

@@ -0,0 +1,243 @@
+"""Portrait download via GitHub Contents API + gh CLI.
+
+Downloads portrait images from the pennyfarthing monorepo using the
+GitHub CLI, saving them into the installed theme package's portraits/
+directory in node_modules.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from pf.package.discovery import (
+    PORTRAIT_SIZES,
+    THEME_PACKAGES,
+    get_package_dir,
+    is_package_installed,
+)
+
+GITHUB_REPO = "1898andCo/pennyfarthing"
+GITHUB_BRANCH = "develop"
+
+
+def _gh_available() -> bool:
+    """Check if the gh CLI is available."""
+    return shutil.which("gh") is not None
+
+
+def _list_contents(path: str) -> dict[str, Any]:
+    """List contents of a path in the GitHub repo via gh API.
+
+    Args:
+        path: Repo-relative path (e.g. "packages/themes-comedy/portraits")
+
+    Returns:
+        Result dict with success, data (list of entries), or error
+    """
+    result = subprocess.run(
+        [
+            "gh", "api",
+            f"repos/{GITHUB_REPO}/contents/{path}?ref={GITHUB_BRANCH}",
+        ],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        return {"success": False, "error": result.stderr.strip()}
+
+    try:
+        data = json.loads(result.stdout)
+        if isinstance(data, dict) and data.get("message"):
+            return {"success": False, "error": data["message"]}
+        return {"success": True, "data": data if isinstance(data, list) else [data]}
+    except json.JSONDecodeError:
+        return {"success": False, "error": f"Invalid JSON response for {path}"}
+
+
+def _collect_portrait_files(
+    name: str,
+    all_sizes: bool = False,
+) -> dict[str, Any]:
+    """Recursively collect portrait file paths from GitHub.
+
+    Uses the Contents API to walk the portrait directory tree.
+    Default: only collects files under the 'large/' size directory.
+    With all_sizes: collects all 4 resolution directories.
+
+    Args:
+        name: Theme package name (e.g. "comedy")
+        all_sizes: If True, download all portrait sizes
+
+    Returns:
+        Result dict with success, data (list of file entries), or error
+    """
+    base_path = f"packages/themes-{name}/portraits"
+    allowed_sizes = set(PORTRAIT_SIZES) if all_sizes else {"large"}
+
+    # List top-level portrait directory — expect theme subdirectories
+    top_result = _list_contents(base_path)
+    if not top_result["success"]:
+        return top_result
+
+    files_to_download: list[dict[str, str]] = []
+
+    # Each entry at top level is a theme subdirectory (e.g. "classical-composers")
+    for theme_entry in top_result["data"]:
+        if theme_entry.get("type") != "dir":
+            continue
+
+        theme_name = theme_entry["name"]
+        theme_path = f"{base_path}/{theme_name}"
+
+        # List size directories under each theme
+        sizes_result = _list_contents(theme_path)
+        if not sizes_result["success"]:
+            continue
+
+        for size_entry in sizes_result["data"]:
+            if size_entry.get("type") != "dir":
+                continue
+            if size_entry["name"] not in allowed_sizes:
+                continue
+
+            size_path = f"{theme_path}/{size_entry['name']}"
+
+            # List image files in this size directory
+            images_result = _list_contents(size_path)
+            if not images_result["success"]:
+                continue
+
+            for img_entry in images_result["data"]:
+                if img_entry.get("type") != "file":
+                    continue
+                files_to_download.append({
+                    "path": img_entry["path"],
+                    "download_url": img_entry.get("download_url", ""),
+                    "name": img_entry["name"],
+                    "relative": f"{theme_name}/{size_entry['name']}/{img_entry['name']}",
+                })
+
+    return {"success": True, "data": files_to_download}
+
+
+def _download_file(download_url: str, dest: Path) -> dict[str, Any]:
+    """Download a single file using curl.
+
+    Args:
+        download_url: Direct download URL (from GitHub Contents API download_url field)
+        dest: Local destination path
+
+    Returns:
+        Result dict with success or error
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    result = subprocess.run(
+        ["curl", "-fsSL", "-o", str(dest), download_url],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        dest.unlink(missing_ok=True)
+        return {"success": False, "error": result.stderr.strip()}
+
+    return {"success": True}
+
+
+def download_portraits(
+    name: str,
+    project_root: Path | None = None,
+    all_sizes: bool = False,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Download portraits for a theme package.
+
+    1. Validates gh CLI is available
+    2. Validates the package is installed
+    3. Lists portrait files from GitHub Contents API
+    4. Downloads each file, skipping already-existing ones
+
+    Args:
+        name: Theme package name (e.g. "comedy")
+        project_root: Project root (auto-detected if not provided)
+        all_sizes: If True, download all portrait sizes (default: large only)
+        dry_run: If True, show what would happen without downloading
+
+    Returns:
+        Result dict with success, data (download stats), or error
+    """
+    if name not in THEME_PACKAGES:
+        return {"success": False, "error": f"Unknown theme package: {name}"}
+
+    if not _gh_available():
+        return {
+            "success": False,
+            "error": "gh CLI not found. Install with: brew install gh",
+        }
+
+    if not dry_run and not is_package_installed(name, project_root):
+        return {
+            "success": False,
+            "error": f"Package @pennyfarthing/themes-{name} is not installed. Run: pf package install {name}",
+        }
+
+    if dry_run:
+        pkg_dir = get_package_dir(name, project_root)
+        portraits_dir = pkg_dir / "portraits"
+        return {
+            "success": True,
+            "data": {
+                "action": "dry-run",
+                "total_files": "(would query GitHub API)",
+                "destination": str(portraits_dir),
+                "sizes": "all" if all_sizes else "large only",
+            },
+        }
+
+    # Collect file list from GitHub
+    collect_result = _collect_portrait_files(name, all_sizes=all_sizes)
+    if not collect_result["success"]:
+        return collect_result
+
+    files = collect_result["data"]
+    if not files:
+        return {"success": True, "data": {"downloaded": 0, "skipped": 0, "message": "No portrait files found"}}
+
+    pkg_dir = get_package_dir(name, project_root)
+    portraits_dir = pkg_dir / "portraits"
+
+    downloaded = 0
+    skipped = 0
+    errors = []
+
+    for file_entry in files:
+        dest = portraits_dir / file_entry["relative"]
+
+        # Skip files that already exist (idempotent)
+        if dest.is_file():
+            skipped += 1
+            continue
+
+        dl_result = _download_file(file_entry["download_url"], dest)
+        if dl_result["success"]:
+            downloaded += 1
+        else:
+            errors.append(f"{file_entry['relative']}: {dl_result['error']}")
+
+    result_data: dict[str, Any] = {
+        "downloaded": downloaded,
+        "skipped": skipped,
+        "total": len(files),
+        "destination": str(portraits_dir),
+    }
+    if errors:
+        result_data["errors"] = errors[:5]
+        result_data["error_count"] = len(errors)
+
+    return {"success": True, "data": result_data}

package/pennyfarthing-dist/pf/prime/loader.py

@@ -15,7 +15,7 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
-from pf.common.config import get_project_root
+from pf.common.config import get_dist_root, get_project_root
 
 
 def load_agent_definition(agent_name: str, project_root: Path | None = None) -> str | None:
@@ -31,10 +31,17 @@ def load_agent_definition(agent_name: str, project_root: Path | None = None) ->
     root = project_root or get_project_root()
     agent_file = root / ".pennyfarthing" / "agents" / f"{agent_name}.md"
 
-    if not agent_file.exists():
-        return None
+    if agent_file.exists():
+        return agent_file.read_text()
+
+    # Fallback: pennyfarthing-dist via get_dist_root (npm context)
+    dist_root = get_dist_root(project_root=root)
+    if dist_root:
+        agent_file = dist_root / "agents" / f"{agent_name}.md"
+        if agent_file.exists():
+            return agent_file.read_text()
 
-    return agent_file.read_text()
+    return None
 
 
 def load_behavior_guide(project_root: Path | None = None) -> str | None:
@@ -49,10 +56,17 @@ def load_behavior_guide(project_root: Path | None = None) -> str | None:
     root = project_root or get_project_root()
     guide_file = root / ".pennyfarthing" / "guides" / "agent-behavior.md"
 
-    if not guide_file.exists():
-        return None
+    if guide_file.exists():
+        return guide_file.read_text()
+
+    # Fallback: pennyfarthing-dist via get_dist_root (npm context)
+    dist_root = get_dist_root(project_root=root)
+    if dist_root:
+        guide_file = dist_root / "guides" / "agent-behavior.md"
+        if guide_file.exists():
+            return guide_file.read_text()
 
-    return guide_file.read_text()
+    return None
 
 
 def load_sprint_context(project_root: Path | None = None) -> str | None:

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

@@ -15,7 +15,7 @@ from typing import Any
 
 import yaml
 
-from pf.common.config import get_project_root
+from pf.common.config import get_dist_root, get_project_root
 from pf.prime.models import WorkflowState, WorkflowStatus
 
 
@@ -133,7 +133,11 @@ def get_phase_owner(workflow: str, phase: str, project_root: Path) -> str | None
     Returns:
         Agent name (sm, tea, dev, reviewer), or None if not found
     """
-    workflow_path = project_root / "pennyfarthing-dist" / "workflows" / f"{workflow}.yaml"
+    dist_root = get_dist_root(project_root=project_root)
+    if dist_root:
+        workflow_path = dist_root / "workflows" / f"{workflow}.yaml"
+    else:
+        workflow_path = project_root / "pennyfarthing-dist" / "workflows" / f"{workflow}.yaml"
 
     if not workflow_path.exists():
         # Fallback to symlinked location
@@ -296,7 +300,11 @@ def get_phase_tandem_config(
         or None if no tandem config on this phase.
     """
     root = project_root or get_project_root()
-    workflow_path = root / "pennyfarthing-dist" / "workflows" / f"{workflow_name}.yaml"
+    dist_root = get_dist_root(project_root=root)
+    if dist_root:
+        workflow_path = dist_root / "workflows" / f"{workflow_name}.yaml"
+    else:
+        workflow_path = root / "pennyfarthing-dist" / "workflows" / f"{workflow_name}.yaml"
 
     if not workflow_path.exists():
         return None