@pennyfarthing/core 11.3.8 → 11.5.0-alpha.0

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

@@ -0,0 +1,112 @@
+"""Release CLI - Click-based CLI for release management operations.
+
+Usage:
+    pf release [COMMAND] [ARGS]...
+
+Commands:
+    deprecate    Mark a published version as deprecated
+    dry-run      Simulate release pipeline without executing
+"""
+
+from __future__ import annotations
+
+import click
+
+
+@click.group()
+def release():
+    """Release management operations.
+
+    \b
+    Commands:
+      deprecate  - Mark a published version as deprecated
+      dry-run    - Simulate release pipeline without executing
+    """
+    pass
+
+
+@release.command()
+@click.option("--version", required=True, help="Semver version to deprecate (e.g., 11.3.7)")
+@click.option("--reason", required=True, help="Reason for deprecation")
+@click.option("--dry-run", is_flag=True, help="Preview actions without executing")
+@click.option("--package", default="pennyfarthing", help="Package name (default: pennyfarthing)")
+def deprecate(version: str, reason: str, dry_run: bool, package: str):
+    """Mark a published npm version as deprecated.
+
+    Deprecates the version in the npm registry, appends a deprecation
+    entry to CHANGELOG.md, and creates a git note on the version tag.
+
+    \b
+    Examples:
+      pf release deprecate --version=11.3.7 --reason="workspace:* leak"
+      pf release deprecate --version=11.3.7 --reason="broken deps" --dry-run
+    """
+    from pf.common.config import get_project_root
+    from pf.release.deprecate import deprecate_version
+
+    root = get_project_root()
+    result = deprecate_version(
+        root,
+        version,
+        reason,
+        dry_run=dry_run,
+        package_name=package,
+    )
+
+    if result.get("dry_run"):
+        click.echo("DRY RUN — no changes made")
+        for step in result.get("steps", []):
+            click.echo(f"  [{step['action']}] {step.get('detail', '')}")
+        return
+
+    if result["success"]:
+        click.echo(f"Deprecated {package}@{version}: {reason}")
+        for step in result.get("steps", []):
+            status = "ok" if step.get("success", True) else "FAIL"
+            click.echo(f"  [{status}] {step['action']}: {step.get('detail', '')}")
+    else:
+        click.echo(f"Error: {result['error']}", err=True)
+        raise SystemExit(1)
+
+
+@release.command("dry-run")
+@click.option("--version", default=None, help="Explicit target version (overrides --bump)")
+@click.option(
+    "--bump",
+    type=click.Choice(["major", "minor", "patch"], case_sensitive=False),
+    default=None,
+    help="Bump type to simulate (default: patch)",
+)
+def dry_run(version: str | None, bump: str | None):
+    """Simulate the release pipeline without executing.
+
+    Runs through version bump, changelog, build, and pack steps
+    without committing, tagging, or publishing. Shows exactly what
+    would happen during a real release.
+
+    \b
+    Examples:
+      pf release dry-run --bump=patch
+      pf release dry-run --bump=minor
+      pf release dry-run --version=12.0.0
+      pf release dry-run  # defaults to current version
+    """
+    from pf.common.config import get_project_root
+    from pf.release.dry_run import dry_run_release
+
+    root = get_project_root()
+    result = dry_run_release(root, version=version, bump=bump)
+
+    if result["success"]:
+        data = result.get("data", {})
+        click.echo("DRY RUN — Release Pipeline Simulation")
+        click.echo(f"  Current: {data.get('current_version', '?')}")
+        click.echo(f"  Target:  {data.get('target_version', '?')}")
+        click.echo("")
+        click.echo("Steps:")
+        for step in result.get("steps", []):
+            status = "ok" if step.get("success", True) else "FAIL"
+            click.echo(f"  [{status}] {step['action']}: {step.get('detail', '')}")
+    else:
+        click.echo(f"Error: {result['error']}", err=True)
+        raise SystemExit(1)

package/pennyfarthing-dist/pf/release/deprecate.py

@@ -0,0 +1,187 @@
+"""Core logic for deprecating npm package versions.
+
+Handles:
+- npm deprecate command execution
+- CHANGELOG.md deprecation entry insertion
+- Git notes creation on version tags
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from datetime import UTC, datetime
+from pathlib import Path
+
+
+def deprecate_version(
+    project_root: Path,
+    version: str,
+    reason: str,
+    *,
+    dry_run: bool = False,
+    package_name: str = "pennyfarthing",
+) -> dict:
+    """Deprecate a published npm package version.
+
+    Steps:
+    1. Validate inputs and CHANGELOG existence
+    2. Validate version exists in npm registry
+    3. Check if already deprecated
+    4. Run npm deprecate to mark version in registry
+    5. Append deprecation entry to CHANGELOG.md
+    6. Create git note on the version tag
+
+    Returns:
+        Result dict per ADR-0008: {success, data?, error?, steps?}
+    """
+    # --- Input validation ---
+    if not version or not version.strip():
+        return {"success": False, "error": "Version is required"}
+
+    if not reason or not reason.strip():
+        return {"success": False, "error": "Reason is required"}
+
+    changelog_path = project_root / "CHANGELOG.md"
+    if not changelog_path.is_file():
+        return {"success": False, "error": "CHANGELOG.md not found in project root"}
+
+    # --- Validate version exists in npm ---
+    ver_result = subprocess.run(
+        ["npm", "view", f"{package_name}@{version}", "version"],
+        capture_output=True,
+        text=True,
+    )
+    if ver_result.returncode != 0:
+        return {
+            "success": False,
+            "error": f"Version {version} not found in npm registry",
+        }
+
+    version_str = ver_result.stdout.strip()
+
+    # --- Dry run: return planned steps without executing ---
+    if dry_run:
+        return {
+            "success": True,
+            "dry_run": True,
+            "steps": [
+                {
+                    "action": "npm_deprecate",
+                    "detail": f"Would deprecate {package_name}@{version}",
+                },
+                {
+                    "action": "changelog_update",
+                    "detail": f"Would add [DEPRECATED] marker to {version}",
+                },
+                {
+                    "action": "git_notes",
+                    "detail": f"Would add note to v{version}",
+                },
+            ],
+        }
+
+    # --- Check if already deprecated (only for real runs) ---
+    dep_result = subprocess.run(
+        ["npm", "view", f"{package_name}@{version}", "deprecated"],
+        capture_output=True,
+        text=True,
+    )
+    dep_msg = dep_result.stdout.strip()
+    if dep_result.returncode == 0 and dep_msg and dep_msg != version_str:
+        return {
+            "success": False,
+            "error": f"Version {version} is already deprecated: {dep_msg}",
+        }
+
+    # --- Execute deprecation ---
+    steps = []
+
+    # Step 1: npm deprecate
+    npm_result = subprocess.run(
+        ["npm", "deprecate", f"{package_name}@{version}", reason],
+        capture_output=True,
+        text=True,
+    )
+    if npm_result.returncode != 0:
+        return {
+            "success": False,
+            "error": f"npm deprecate failed: {npm_result.stderr.strip()}",
+            "steps": [
+                {
+                    "action": "npm_deprecate",
+                    "detail": f"{package_name}@{version}",
+                    "success": False,
+                },
+            ],
+        }
+    steps.append({
+        "action": "npm_deprecate",
+        "detail": f"{package_name}@{version}",
+        "success": True,
+    })
+
+    # Step 2: Update CHANGELOG.md
+    today = datetime.now(UTC).strftime("%Y-%m-%d")
+    changelog_ok = _update_changelog(changelog_path, version, reason, today)
+    steps.append({
+        "action": "changelog_update",
+        "detail": f"Added [DEPRECATED] marker to {version}",
+        "success": changelog_ok,
+    })
+
+    # Step 3: Add git note
+    note_msg = f"Deprecated: {reason}\nDate: {today}\nPackage: {package_name}@{version}"
+    git_result = subprocess.run(
+        ["git", "notes", "add", "-m", note_msg, f"v{version}"],
+        capture_output=True,
+        text=True,
+        cwd=str(project_root),
+    )
+    git_ok = git_result.returncode == 0
+    steps.append({
+        "action": "git_notes",
+        "detail": f"Note added to v{version}" if git_ok else git_result.stderr.strip(),
+        "success": git_ok,
+    })
+
+    all_ok = all(s.get("success", True) for s in steps)
+    return {"success": all_ok, "steps": steps}
+
+
+def _update_changelog(
+    changelog_path: Path,
+    version: str,
+    reason: str,
+    today: str,
+) -> bool:
+    """Add [DEPRECATED] marker and deprecation notice to a version section."""
+    content = changelog_path.read_text()
+
+    # Find the version header line: ## [X.Y.Z] - YYYY-MM-DD
+    pattern = re.compile(
+        rf"(## \[{re.escape(version)}\] - \d{{4}}-\d{{2}}-\d{{2}})"
+    )
+    match = pattern.search(content)
+    if not match:
+        return False
+
+    old_header = match.group(1)
+    new_header = f"{old_header} [DEPRECATED]"
+
+    # Add deprecation notice after the header's existing content.
+    # Find the next section boundary (--- or ## [) after the header.
+    header_end = match.end()
+    next_section = re.search(r"\n(?:---|\n## \[)", content[header_end:])
+    if next_section:
+        insert_pos = header_end + next_section.start()
+    else:
+        insert_pos = len(content)
+
+    deprecation_notice = f"\n\n### Deprecated\n\n- **Version deprecated ({today})** — {reason}\n"
+
+    # Replace header and insert notice
+    content = content[:match.start()] + new_header + content[header_end:insert_pos] + deprecation_notice + content[insert_pos:]
+
+    changelog_path.write_text(content)
+    return True

package/pennyfarthing-dist/pf/release/dry_run.py

@@ -0,0 +1,187 @@
+"""Core logic for dry-run release simulation.
+
+Simulates the full release pipeline without side effects:
+- Version bump (reads package.json, computes new version)
+- Changelog update (checks CHANGELOG.md)
+- Build validation (TypeScript compilation check)
+- Pack validation (npm pack --dry-run)
+
+Does NOT commit, tag, or publish.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from pathlib import Path
+
+_SEMVER_RE = re.compile(
+    r"^\d+\.\d+\.\d+(-[a-zA-Z0-9]+(\.\d+)?)?$"
+)
+
+_VALID_BUMPS = {"major", "minor", "patch"}
+
+
+def dry_run_release(
+    project_root: Path,
+    *,
+    version: str | None = None,
+    bump: str | None = None,
+) -> dict:
+    """Simulate a release pipeline without executing.
+
+    Args:
+        project_root: Path to the project root.
+        version: Explicit target version (overrides bump).
+        bump: Bump type (major, minor, patch). Ignored if version is set.
+
+    Returns:
+        Result dict per ADR-0008: {success, dry_run, data?, error?, steps?}
+    """
+    # --- Input validation ---
+    if bump and bump not in _VALID_BUMPS:
+        return {"success": False, "error": f"Invalid bump type: {bump}"}
+
+    if version and not _SEMVER_RE.match(version):
+        return {"success": False, "error": f"Invalid version: {version}"}
+
+    # --- Read current version from package.json ---
+    pkg_path = project_root / "package.json"
+    if not pkg_path.is_file():
+        return {"success": False, "error": "package.json not found in project root"}
+
+    try:
+        pkg_data = json.loads(pkg_path.read_text())
+    except (json.JSONDecodeError, ValueError):
+        return {"success": False, "error": "Failed to parse package.json"}
+
+    current_version = pkg_data.get("version", "0.0.0")
+
+    # --- Compute target version ---
+    if version:
+        target_version = version
+    elif bump:
+        target_version = _bump_version(current_version, bump)
+    else:
+        target_version = current_version
+
+    # --- Discover workspace packages ---
+    packages = _discover_packages(project_root, pkg_data)
+
+    # --- Build version files list ---
+    version_files = ["package.json"]
+    if (project_root / "VERSION").is_file():
+        version_files.append("VERSION")
+
+    # --- Simulate steps ---
+    steps = []
+
+    # Step 1: Version bump
+    steps.append({
+        "action": "version_bump",
+        "detail": f"{current_version} -> {target_version} ({', '.join(version_files)})",
+        "success": True,
+    })
+
+    # Step 2: Changelog update
+    changelog_path = project_root / "CHANGELOG.md"
+    if changelog_path.is_file():
+        content = changelog_path.read_text()
+        has_unreleased = "## [Unreleased]" in content
+        steps.append({
+            "action": "changelog_update",
+            "detail": f"Would update CHANGELOG.md (unreleased section: {'yes' if has_unreleased else 'no'})",
+            "success": True,
+        })
+    else:
+        steps.append({
+            "action": "changelog_update",
+            "detail": "CHANGELOG.md not found",
+            "success": False,
+        })
+
+    # Step 3: Build check (tsc --noEmit)
+    build_result = subprocess.run(
+        ["npx", "tsc", "--noEmit"],
+        capture_output=True,
+        text=True,
+        cwd=str(project_root),
+    )
+    build_ok = build_result.returncode == 0
+    steps.append({
+        "action": "build",
+        "detail": "TypeScript compilation check (tsc --noEmit)"
+                  if build_ok
+                  else f"Build failed: {build_result.stderr.strip()[:200]}",
+        "success": build_ok,
+    })
+
+    # Step 4: Pack check (npm pack --dry-run)
+    pack_result = subprocess.run(
+        ["npm", "pack", "--dry-run"],
+        capture_output=True,
+        text=True,
+        cwd=str(project_root),
+    )
+    pack_ok = pack_result.returncode == 0
+    steps.append({
+        "action": "pack",
+        "detail": "npm pack --dry-run"
+                  if pack_ok
+                  else f"Pack failed: {pack_result.stderr.strip()[:200]}",
+        "success": pack_ok,
+    })
+
+    return {
+        "success": True,
+        "dry_run": True,
+        "data": {
+            "current_version": current_version,
+            "target_version": target_version,
+            "packages": packages,
+        },
+        "steps": steps,
+    }
+
+
+def _bump_version(current: str, bump: str) -> str:
+    """Compute a new version from a bump type."""
+    base = current.split("-")[0]
+    parts = base.split(".")
+    major, minor, patch = int(parts[0]), int(parts[1]), int(parts[2])
+
+    if bump == "major":
+        return f"{major + 1}.0.0"
+    elif bump == "minor":
+        return f"{major}.{minor + 1}.0"
+    else:  # patch
+        return f"{major}.{minor}.{patch + 1}"
+
+
+def _discover_packages(project_root: Path, root_pkg: dict) -> list[dict]:
+    """Discover root and workspace packages."""
+    packages = []
+
+    # Root package
+    packages.append({
+        "name": root_pkg.get("name", "unknown"),
+        "version": root_pkg.get("version", "0.0.0"),
+    })
+
+    # Workspace packages
+    packages_dir = project_root / "packages"
+    if packages_dir.is_dir():
+        for pkg_dir in sorted(packages_dir.iterdir()):
+            pkg_json = pkg_dir / "package.json"
+            if pkg_json.is_file():
+                try:
+                    data = json.loads(pkg_json.read_text())
+                    packages.append({
+                        "name": data.get("name", pkg_dir.name),
+                        "version": data.get("version", "0.0.0"),
+                    })
+                except (json.JSONDecodeError, ValueError):
+                    pass
+
+    return packages

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

@@ -11,7 +11,27 @@ 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")
+SHOW_KEYS = ("theme", "bell_mode", "relay_mode", "permission_mode", "workflow", "jira", "display", "split", "last_panel")
+
+# Default values for all known settings
+DEFAULTS: dict[str, Any] = {
+    "theme": "firefly",
+    "bell_mode": "standard",
+    "relay_mode": False,
+    "permission_mode": "standard",
+    "workflow": {
+        "bell_mode": False,
+        "git_monitor": False,
+        "relay_mode": False,
+        "permission_mode": "standard",
+        "pr_mode": "draft",
+        "pr_merge": "auto",
+    },
+    "display": {
+        "colorPreset": "catppuccin",
+    },
+    "last_panel": "sprint",
+}
 
 
 def _coerce_value(value: str) -> Any:
@@ -74,25 +94,41 @@ def set_setting(key: str, value: str) -> dict:
     return config
 
 
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Deep-merge override into base, returning a new dict."""
+    result = dict(base)
+    for k, v in override.items():
+        if k in result and isinstance(result[k], dict) and isinstance(v, dict):
+            result[k] = _deep_merge(result[k], v)
+        else:
+            result[k] = v
+    return result
+
+
 def show_settings() -> str:
-    """Format interesting top-level settings for display."""
+    """Format all settings with defaults, annotating which are user-set."""
     config = load_pennyfarthing_config()
+    merged = _deep_merge(DEFAULTS, config)
     lines: list[str] = []
 
     for key in SHOW_KEYS:
-        if key not in config:
+        if key not in merged:
             continue
-        val = config[key]
+        val = merged[key]
+        is_set = key in config
+        suffix = "" if is_set else "  # (default)"
         if isinstance(val, dict):
             lines.append(f"{key}:")
+            user_dict = config.get(key, {}) if isinstance(config.get(key), dict) else {}
             for k, v in val.items():
+                k_suffix = "" if k in user_dict else "  # (default)"
                 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}")
+                    for i, line in enumerate(nested.rstrip().split("\n")):
+                        lines.append(f"  {line}{k_suffix if i == 0 else ''}")
                 else:
-                    lines.append(f"  {k}: {v}")
+                    lines.append(f"  {k}: {v}{k_suffix}")
         else:
-            lines.append(f"{key}: {val}")
+            lines.append(f"{key}: {val}{suffix}")
 
     return "\n".join(lines) if lines else "(no settings found)"