@pennyfarthing/core 11.4.0 → 11.5.0-alpha.0

package/pennyfarthing-dist/pf/jira/client.py

@@ -122,76 +122,6 @@ def is_jira_cli_available() -> bool:
     return shutil.which("jira") is not None
 
 
-def get_issue(issue_key: str) -> dict[str, Any] | None:
-    """Fetch issue details from Jira.
-
-    Args:
-        issue_key: Jira issue key (e.g., "MSSCI-12398")
-
-    Returns:
-        Issue data as dict, or None if not found
-    """
-    if not is_jira_cli_available():
-        return None
-
-    result = subprocess.run(
-        ["jira", "issue", "view", issue_key, "--raw"],
-        capture_output=True,
-        text=True,
-    )
-
-    if result.returncode != 0:
-        return None
-
-    try:
-        return json.loads(result.stdout)
-    except json.JSONDecodeError:
-        return None
-
-
-def update_issue_status(issue_key: str, status: str) -> bool:
-    """Transition an issue to a new status.
-
-    Args:
-        issue_key: Jira issue key
-        status: Target status name
-
-    Returns:
-        True if successful, False otherwise
-    """
-    if not is_jira_cli_available():
-        return False
-
-    result = subprocess.run(
-        ["jira", "issue", "move", issue_key, status],
-        capture_output=True,
-        text=True,
-    )
-
-    return result.returncode == 0
-
-
-def add_comment(issue_key: str, comment: str) -> bool:
-    """Add a comment to an issue.
-
-    Args:
-        issue_key: Jira issue key
-        comment: Comment text
-
-    Returns:
-        True if successful, False otherwise
-    """
-    if not is_jira_cli_available():
-        return False
-
-    result = subprocess.run(
-        ["jira", "issue", "comment", "add", issue_key, "--body", comment],
-        capture_output=True,
-        text=True,
-    )
-
-    return result.returncode == 0
-
 
 def get_jira_field(issue_json: dict[str, Any], field_path: str, default: Any = None) -> Any:
     """Extract field from Jira issue JSON using dot notation.
@@ -226,13 +156,13 @@ def get_story_points(issue_key: str, issue_json: dict[str, Any] | None = None) -
 
     Args:
         issue_key: Jira issue key
-        issue_json: Optional pre-fetched issue JSON
+        issue_json: Optional pre-fetched issue JSON (required if no default client)
 
     Returns:
         Story points as int, or None if not set
     """
     if issue_json is None:
-        issue_json = get_issue(issue_key)
+        issue_json = get_client().get_issue_sync(issue_key)
     if not issue_json:
         return None
 
@@ -349,13 +279,11 @@ def get_current_user_email() -> str:
 class JiraClient:
     """Unified Jira REST API client with sync and async support.
 
-    Consolidates REST API access previously scattered across:
-    - jira_sync.py (httpx async)
-    - jira_epic_creation.py (curl subprocess)
+    Consolidates all Jira REST API access.
 
     Usage (sync):
         client = JiraClient()
-        issue = client.get_issue("MSSCI-12345")
+        issue = client.get_issue_sync("MSSCI-12345")
 
     Usage (async):
         client = JiraClient()
@@ -510,7 +438,7 @@ class JiraClient:
             "GET", f"/rest/api/3/issue/{issue_key}/transitions"
         )
         if not transitions_data:
-            return {"success": False, "reason": "Could not get transitions"}
+            return {"success": False, "error": "Could not get transitions"}
 
         transitions = transitions_data.get("transitions", [])
         transition_id = None
@@ -523,7 +451,7 @@ class JiraClient:
             available = [t.get("name") for t in transitions]
             return {
                 "success": False,
-                "reason": f"No transition to '{target_status}' available. "
+                "error": f"No transition to '{target_status}' available. "
                 f"Available: {available}",
             }
 
@@ -558,7 +486,7 @@ class JiraClient:
             if not users or not isinstance(users, list) or len(users) == 0:
                 return {
                     "success": False,
-                    "reason": f"User not found: {assignee_email}",
+                    "error": f"User not found: {assignee_email}",
                 }
             account_id = users[0].get("accountId")
         else:
@@ -571,6 +499,41 @@ class JiraClient:
         # Assign PUT returns empty body on success (204)
         return {"success": True}
 
+    def add_comment_sync(self, issue_key: str, comment: str) -> dict[str, Any]:
+        """Add a comment to a Jira issue via REST API.
+
+        Args:
+            issue_key: Jira issue key
+            comment: Comment body text
+
+        Returns:
+            Result dict with success status
+        """
+        payload = {
+            "body": {
+                "type": "doc",
+                "version": 1,
+                "content": [
+                    {
+                        "type": "paragraph",
+                        "content": [{"type": "text", "text": comment}],
+                    }
+                ],
+            }
+        }
+        result = self._call_api_sync(
+            "POST",
+            f"/rest/api/3/issue/{issue_key}/comment",
+            payload,
+        )
+        if result is None:
+            # POST comment returns the created comment on success;
+            # _call_api_sync returns None on empty/failed response
+            # but also returns None on JSON decode failure for 201 with empty body.
+            # Treat None as success since the API may return 201 with no body.
+            pass
+        return {"success": True}
+
     def add_to_sprint_sync(self, sprint_id: int | str, issue_key: str) -> dict[str, Any]:
         """Add issue to a sprint via Agile REST API.
 
@@ -609,9 +572,10 @@ class JiraClient:
 
         encoded_jql = urllib.parse.quote(jql)
         fields_param = ",".join(fields)
+        # Jira Cloud deprecated /rest/api/3/search — use /rest/api/3/search/jql
         result = self._call_api_sync(
             "GET",
-            f"/rest/api/3/search?jql={encoded_jql}&fields={fields_param}"
+            f"/rest/api/3/search/jql?jql={encoded_jql}&fields={fields_param}"
             f"&maxResults={max_results}",
         )
         if not result:
@@ -680,7 +644,7 @@ class JiraClient:
             target_status: Target status name (e.g., "In Progress", "Done")
 
         Returns:
-            Result dict with success status and optional reason
+            Result dict with success status and optional error
         """
         import httpx
 
@@ -694,7 +658,7 @@ class JiraClient:
                 if response.status_code != 200:
                     return {
                         "success": False,
-                        "reason": f"Could not get transitions: {response.status_code}",
+                        "error": f"Could not get transitions: {response.status_code}",
                     }
 
                 transitions = response.json().get("transitions", [])
@@ -707,7 +671,7 @@ class JiraClient:
                 if not transition_id:
                     return {
                         "success": False,
-                        "reason": f"No transition to '{target_status}' available",
+                        "error": f"No transition to '{target_status}' available",
                     }
 
                 # Execute transition
@@ -722,11 +686,11 @@ class JiraClient:
                     return {"success": True}
                 return {
                     "success": False,
-                    "reason": f"Transition failed: {response.status_code}",
+                    "error": f"Transition failed: {response.status_code}",
                 }
 
             except httpx.HTTPError as e:
-                return {"success": False, "reason": str(e)}
+                return {"success": False, "error": str(e)}
 
     async def update_fields_async(
         self, issue_key: str, fields: dict[str, Any]
@@ -756,10 +720,10 @@ class JiraClient:
 
                 if response.status_code in (200, 204):
                     return {"success": True}
-                return {"success": False, "reason": f"HTTP {response.status_code}"}
+                return {"success": False, "error": f"HTTP {response.status_code}"}
 
             except httpx.HTTPError as e:
-                return {"success": False, "reason": str(e)}
+                return {"success": False, "error": str(e)}
 
     async def sync_story_points_async(
         self,

package/pennyfarthing-dist/pf/jira/reconcile.py

@@ -252,7 +252,7 @@ def reconcile(
                 print("  Done")
                 fixed.append(key)
             else:
-                print(f"  Failed: {result.get('reason', 'unknown')}")
+                print(f"  Failed: {result.get('error', 'unknown')}")
 
         report_lines.extend([
             "",

package/pennyfarthing-dist/pf/jira/story.py

@@ -88,7 +88,7 @@ def fetch_jira_issue(jira_key: str) -> dict[str, Any] | None:
     Returns:
         Issue JSON if found, None otherwise
     """
-    return jira_client.get_issue(jira_key)
+    return jira_client.get_client().get_issue_sync(jira_key)
 
 
 def sync_story(
@@ -147,10 +147,11 @@ def sync_story(
             if dry_run:
                 actions.append(f"[DRY-RUN] {action}")
             else:
-                if jira_client.update_issue_status(jira_key, target_status):
+                result = jira_client.get_client().transition_sync(jira_key, target_status)
+                if result.get("success"):
                     actions.append(action)
                 else:
-                    errors.append(f"Failed to transition {jira_key}")
+                    errors.append(f"Failed to transition {jira_key}: {result.get('error', 'unknown')}")
         else:
             actions.append(f"status already {current_jira_status}")
 
@@ -173,7 +174,8 @@ def sync_story(
         if dry_run:
             actions.append(f"[DRY-RUN] {action}")
         else:
-            if jira_client.add_comment(jira_key, comment):
+            result = jira_client.get_client().add_comment_sync(jira_key, comment)
+            if result.get("success"):
                 actions.append(action)
             else:
                 errors.append(f"Failed to add comment to {jira_key}")

package/pennyfarthing-dist/pf/jira/sync.py

@@ -150,7 +150,7 @@ async def sync_story(
         if result.get("success"):
             actions.append(f"transitioned: {current_status} -> {target_status}")
         else:
-            actions.append(f"transition failed: {result.get('reason')}")
+            actions.append(f"transition failed: {result.get('error')}")
 
     # Sync points if requested
     story_points = story.get("points")
@@ -167,7 +167,7 @@ async def sync_story(
             else:
                 actions.append(f"synced points: {story_points}")
         else:
-            actions.append(f"points sync failed: {result.get('reason')}")
+            actions.append(f"points sync failed: {result.get('error')}")
 
     return SyncResult(
         story_id=story_id,

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

@@ -8,7 +8,7 @@ to conform to the XML schema definitions:
 - Workflow step files -> guides/workflow-step-schema.md
 
 Usage:
-    python -m pf.migration [command] [options]
+    pf migration [command] [options]
 
 Commands:
     session   Migrate session files to XML format

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

@@ -3,7 +3,6 @@ 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

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()}}