@pennyfarthing/core 11.4.0 → 12.0.0

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

@@ -0,0 +1,303 @@
+"""
+Migration CLI - Click-based CLI for XML schema migration tools.
+
+Usage:
+    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()

package/pennyfarthing-dist/src/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/src/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()}}