@pennyfarthing/core 10.1.0 → 10.3.0

package/pennyfarthing_scripts/theme/cli.py

@@ -225,9 +225,10 @@ def create(name: str, base: str | None, user: bool):
     Arguments:
       NAME  - Name for the new theme (lowercase, hyphens allowed)
     """
-    import yaml
     from pathlib import Path
 
+    import yaml
+
     from pennyfarthing_scripts.common.config import get_project_root
     from pennyfarthing_scripts.common.themes import (
         get_current_theme,
@@ -282,5 +283,5 @@ def create(name: str, base: str | None, user: bool):
     click.echo(f"  File: {target_path}")
     click.echo()
     click.echo("Next steps:")
-    click.echo(f"  1. Edit the theme file to customize your agents")
+    click.echo("  1. Edit the theme file to customize your agents")
     click.echo(f"  2. Run 'pf theme set {name}' to activate")

package/pennyfarthing_scripts/validate/__init__.py

@@ -0,0 +1,21 @@
+"""Top-level validate command — auto-discovers and runs project validators."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ValidateReport:
+    """Unified report from a single validator domain."""
+
+    validator: str
+    passed: int = 0
+    warnings: int = 0
+    errors: int = 0
+    details: list[str] = field(default_factory=list)
+    fixed: bool = False
+
+    @property
+    def success(self) -> bool:
+        return self.errors == 0

package/pennyfarthing_scripts/validate/adapters/agent.py

@@ -0,0 +1,239 @@
+"""Agent definition structural validator adapter.
+
+Validates agent definition files in pennyfarthing-dist/agents/.
+Checks required sections, model values, and subagent references.
+
+Story: MSSCI-14710 (91-12)
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+from pennyfarthing_scripts.validate import ValidateReport
+
+VALID_MODELS = {"haiku", "sonnet", "opus"}
+BUILTIN_AGENTS = {"Explore", "Plan"}
+
+# Regex to find XML-like tags in markdown: <tagname> or <tag-name>
+_TAG_RE = re.compile(r"<([a-zA-Z][a-zA-Z0-9_-]*)(?:\s[^>]*)?>", re.MULTILINE)
+
+# Regex to extract **Model:** value from helpers section
+_MODEL_RE = re.compile(r"\*\*Model:\*\*\s+(\S+)", re.IGNORECASE)
+
+# Regex to extract subagent names from markdown table rows: | `name` | purpose |
+_HELPER_TABLE_RE = re.compile(r"^\s*\|\s*`?([^`|]+)`?\s*\|", re.MULTILINE)
+
+
+def _has_frontmatter(content: str) -> bool:
+    """Check if content starts with YAML frontmatter (--- delimited)."""
+    return content.startswith("---\n")
+
+
+def _parse_frontmatter(content: str) -> dict:
+    """Extract YAML frontmatter from content."""
+    if not _has_frontmatter(content):
+        return {}
+    end = content.find("\n---", 3)
+    if end == -1:
+        return {}
+    fm_text = content[4:end]
+    try:
+        return yaml.safe_load(fm_text) or {}
+    except yaml.YAMLError:
+        return {}
+
+
+def _find_tags(content: str) -> set[str]:
+    """Find all XML-like tag names in content."""
+    return {m.group(1) for m in _TAG_RE.finditer(content)}
+
+
+def _extract_section(content: str, tag: str) -> str | None:
+    """Extract content between <tag> and </tag>."""
+    pattern = re.compile(rf"<{re.escape(tag)}[^>]*>(.*?)</{re.escape(tag)}>", re.DOTALL)
+    m = pattern.search(content)
+    return m.group(1) if m else None
+
+
+def classify_agent_files(
+    agents_dir: Path,
+) -> tuple[list[Path], list[Path], list[Path]]:
+    """Classify agent files into main agents, subagents, and skipped.
+
+    Returns:
+        (main_agents, subagents, skipped) — three lists of Path objects.
+    """
+    main: list[Path] = []
+    sub: list[Path] = []
+    skipped: list[Path] = []
+
+    for f in sorted(agents_dir.glob("*.md")):
+        if f.name == "README.md":
+            skipped.append(f)
+            continue
+
+        content = f.read_text()
+        if _has_frontmatter(content):
+            sub.append(f)
+        else:
+            main.append(f)
+
+    return main, sub, skipped
+
+
+def validate_main_agent(
+    path: Path, agents_dir: Path
+) -> tuple[list[str], list[str]]:
+    """Validate a main agent definition file.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    content = path.read_text()
+    tags = _find_tags(content)
+
+    # Required sections
+    if "role" not in tags:
+        errors.append("Missing required <role> section")
+    if "critical" not in tags:
+        errors.append("Missing required <critical> section")
+    if "helpers" not in tags:
+        errors.append("Missing required <helpers> section")
+    if "skills" not in tags:
+        errors.append("Missing required <skills> section")
+
+    # Model validation (only if helpers exists)
+    if "helpers" in tags:
+        helpers_content = _extract_section(content, "helpers")
+        if helpers_content:
+            model_match = _MODEL_RE.search(helpers_content)
+            if model_match:
+                model_val = model_match.group(1).lower()
+                if model_val not in VALID_MODELS:
+                    errors.append(
+                        f"Invalid model '{model_match.group(1)}' in <helpers> "
+                        f"(must be one of: {', '.join(sorted(VALID_MODELS))})"
+                    )
+
+            # Subagent reference validation
+            existing_files = {f.stem for f in agents_dir.glob("*.md") if f.name != "README.md"}
+            # Parse table rows — skip header/separator rows
+            for line in helpers_content.splitlines():
+                m = _HELPER_TABLE_RE.match(line)
+                if not m:
+                    continue
+                name = m.group(1).strip().strip("`")
+                # Skip table header and separator
+                if name.lower() in ("subagent", "---", "") or name.startswith("-"):
+                    continue
+                if name in BUILTIN_AGENTS:
+                    continue
+                if name not in existing_files:
+                    warnings.append(
+                        f"Helper references '{name}' but no matching agent file not found in agents/"
+                    )
+
+    # Recommended sections (warnings)
+    if "on-activation" not in tags:
+        warnings.append("Missing recommended <on-activation> section")
+    if "exit" not in tags and "exit-sequence" not in tags:
+        warnings.append("Missing recommended <exit> or <exit-sequence> section")
+
+    return errors, warnings
+
+
+def validate_subagent(path: Path) -> tuple[list[str], list[str]]:
+    """Validate a subagent definition file.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    content = path.read_text()
+
+    # Frontmatter validation
+    fm = _parse_frontmatter(content)
+    if not fm:
+        errors.append("Missing or invalid YAML frontmatter")
+        return errors, warnings
+
+    for field in ("name", "description", "tools", "model"):
+        if field not in fm:
+            errors.append(f"Missing required frontmatter field: {field}")
+
+    # Model must be haiku for subagents
+    if "model" in fm:
+        model_val = str(fm["model"]).lower()
+        if model_val != "haiku":
+            errors.append(
+                f"Subagent model must be 'haiku', got '{fm['model']}'"
+            )
+
+    # Required tags
+    tags = _find_tags(content)
+    if "output" not in tags:
+        errors.append("Missing required <output> section")
+
+    # Recommended tags
+    if "arguments" not in tags:
+        warnings.append("Missing recommended <arguments> section")
+
+    return errors, warnings
+
+
+def run(root: Path, *, fix: bool = False, strict: bool = False) -> ValidateReport:
+    """Validate all agent definition files."""
+    report = ValidateReport(validator="agent")
+    agents_dir = root / "pennyfarthing-dist" / "agents"
+
+    if not agents_dir.is_dir():
+        report.details.append("[ERROR] agents directory not found")
+        report.errors += 1
+        return report
+
+    main_agents, subagents, _skipped = classify_agent_files(agents_dir)
+
+    for path in main_agents:
+        file_errors, file_warnings = validate_main_agent(path, agents_dir)
+
+        for e in file_errors:
+            report.errors += 1
+            report.details.append(f"[ERROR] {path.name}: {e}")
+
+        for w in file_warnings:
+            if strict:
+                report.errors += 1
+                report.details.append(f"[ERROR] {path.name}: {w}")
+            else:
+                report.warnings += 1
+                report.details.append(f"[WARN] {path.name}: {w}")
+
+        if not file_errors:
+            report.passed += 1
+
+    for path in subagents:
+        file_errors, file_warnings = validate_subagent(path)
+
+        for e in file_errors:
+            report.errors += 1
+            report.details.append(f"[ERROR] {path.name}: {e}")
+
+        for w in file_warnings:
+            if strict:
+                report.errors += 1
+                report.details.append(f"[ERROR] {path.name}: {w}")
+            else:
+                report.warnings += 1
+                report.details.append(f"[WARN] {path.name}: {w}")
+
+        if not file_errors:
+            report.passed += 1
+
+    return report

package/pennyfarthing_scripts/validate/adapters/schema.py

@@ -0,0 +1,30 @@
+"""XML schema validator adapter.
+
+Delegates to migration/validate.validate_all() for session, skill, and workflow step files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pennyfarthing_scripts.validate import ValidateReport
+
+
+def run(root: Path, *, fix: bool = False, strict: bool = False) -> ValidateReport:
+    """Validate XML schema files (sessions, skills, workflow steps)."""
+    from pennyfarthing_scripts.migration.validate import validate_all
+
+    summary = validate_all(root, file_type="all", strict=strict)
+
+    report = ValidateReport(validator="schema")
+    report.passed = summary.passed
+    report.warnings = summary.warnings
+    report.errors = summary.errors
+
+    for result in summary.results:
+        for e in result.errors:
+            report.details.append(f"[ERROR] {result.file_path.name}: {e}")
+        for w in result.warnings:
+            report.details.append(f"[WARN] {result.file_path.name}: {w}")
+
+    return report

package/pennyfarthing_scripts/validate/adapters/skill_command.py

@@ -0,0 +1,291 @@
+"""Skill registry and command file structural validator adapter.
+
+Validates skill-registry.yaml against skill-registry.schema.json and
+command file structure in pennyfarthing-dist/commands/.
+
+Story: MSSCI-14711 (91-13)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import yaml
+
+from pennyfarthing_scripts.validate import ValidateReport
+
+_SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+$")
+
+
+def discover_skill_registry(root: Path) -> Path | None:
+    """Locate skill-registry.yaml in the project.
+
+    Returns:
+        Path to skill-registry.yaml, or None if not found.
+    """
+    path = root / "pennyfarthing-dist" / "skills" / "skill-registry.yaml"
+    return path if path.is_file() else None
+
+
+def discover_command_files(commands_dir: Path) -> list[Path]:
+    """Discover all command markdown files.
+
+    Returns:
+        Sorted list of Path objects for command .md files.
+    """
+    if not commands_dir.is_dir():
+        return []
+    return sorted(f for f in commands_dir.glob("*.md"))
+
+
+def _load_schema(root: Path) -> dict | None:
+    """Load the skill-registry.schema.json file."""
+    schema_path = root / "pennyfarthing-dist" / "skills" / "skill-registry.schema.json"
+    if not schema_path.is_file():
+        return None
+    try:
+        return json.loads(schema_path.read_text())
+    except json.JSONDecodeError:
+        return None
+
+
+def _validate_against_schema(
+    data: dict, schema: dict
+) -> list[str]:
+    """Validate data against a JSON Schema (manual implementation).
+
+    Handles the subset of JSON Schema used by skill-registry.schema.json:
+    - type checking (object, string, array, boolean)
+    - required fields
+    - additionalProperties: false
+    - pattern (regex)
+    - enum
+    - $ref to #/definitions/*
+    - items (for arrays)
+
+    Returns:
+        List of error message strings.
+    """
+    errors: list[str] = []
+
+    def _resolve_ref(ref: str) -> dict:
+        """Resolve a $ref pointer like #/definitions/skill."""
+        parts = ref.lstrip("#/").split("/")
+        result = schema
+        for part in parts:
+            result = result.get(part, {})
+        return result
+
+    def _validate_value(value, prop_schema: dict, path: str) -> None:
+        """Validate a single value against its schema."""
+        # Handle $ref
+        if "$ref" in prop_schema:
+            prop_schema = _resolve_ref(prop_schema["$ref"])
+
+        expected_type = prop_schema.get("type")
+
+        # Type checking
+        if expected_type == "object":
+            if not isinstance(value, dict):
+                errors.append(f"{path}: expected object, got {type(value).__name__}")
+                return
+
+            props = prop_schema.get("properties", {})
+            additional = prop_schema.get("additionalProperties")
+
+            # Required fields
+            for req in prop_schema.get("required", []):
+                if req not in value:
+                    errors.append(f"{path}: missing required field '{req}'")
+
+            # Validate known properties
+            for key, val in value.items():
+                if key in props:
+                    _validate_value(val, props[key], f"{path}.{key}")
+                elif additional is False:
+                    errors.append(
+                        f"{path}: additional property '{key}' not allowed"
+                    )
+                elif isinstance(additional, dict):
+                    _validate_value(val, additional, f"{path}.{key}")
+
+        elif expected_type == "string":
+            if not isinstance(value, str):
+                errors.append(f"{path}: expected string, got {type(value).__name__}")
+                return
+            pattern = prop_schema.get("pattern")
+            if pattern and not re.match(pattern, value):
+                errors.append(f"{path}: value '{value}' does not match pattern '{pattern}'")
+            enum_vals = prop_schema.get("enum")
+            if enum_vals and value not in enum_vals:
+                errors.append(
+                    f"{path}: value '{value}' not in allowed values: "
+                    f"{', '.join(enum_vals)}"
+                )
+
+        elif expected_type == "array":
+            if not isinstance(value, list):
+                errors.append(f"{path}: expected array, got {type(value).__name__}")
+                return
+            items_schema = prop_schema.get("items")
+            if items_schema:
+                for i, item in enumerate(value):
+                    _validate_value(item, items_schema, f"{path}[{i}]")
+
+        elif expected_type == "boolean":
+            if not isinstance(value, bool):
+                errors.append(f"{path}: expected boolean, got {type(value).__name__}")
+
+    _validate_value(data, schema, "")
+    return errors
+
+
+def validate_skill_registry(root: Path) -> tuple[list[str], list[str]]:
+    """Validate skill-registry.yaml against its JSON schema.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    registry_path = discover_skill_registry(root)
+    if registry_path is None:
+        errors.append("skill-registry.yaml not found")
+        return errors, warnings
+
+    schema = _load_schema(root)
+    if schema is None:
+        errors.append("skill-registry.schema.json not found or invalid")
+        return errors, warnings
+
+    try:
+        content = registry_path.read_text()
+        data = yaml.safe_load(content)
+    except yaml.YAMLError:
+        errors.append("skill-registry.yaml: YAML parse error")
+        return errors, warnings
+
+    if not isinstance(data, dict):
+        errors.append("skill-registry.yaml: expected a YAML mapping")
+        return errors, warnings
+
+    schema_errors = _validate_against_schema(data, schema)
+    errors.extend(schema_errors)
+
+    return errors, warnings
+
+
+def _has_frontmatter(content: str) -> bool:
+    """Check if content starts with YAML frontmatter (--- delimited)."""
+    return content.startswith("---\n")
+
+
+def _parse_frontmatter(content: str) -> dict | None:
+    """Extract YAML frontmatter from content.
+
+    Returns:
+        Parsed dict, or None if no valid frontmatter.
+    """
+    if not _has_frontmatter(content):
+        return None
+    end = content.find("\n---", 3)
+    if end == -1:
+        return None
+    fm_text = content[4:end]
+    try:
+        return yaml.safe_load(fm_text) or {}
+    except yaml.YAMLError:
+        return None
+
+
+def _get_body(content: str) -> str:
+    """Extract body content after frontmatter."""
+    if not _has_frontmatter(content):
+        return content
+    end = content.find("\n---", 3)
+    if end == -1:
+        return ""
+    return content[end + 4:].strip()
+
+
+def validate_command_file(path: Path) -> tuple[list[str], list[str]]:
+    """Validate a command markdown file.
+
+    Checks:
+    - YAML frontmatter present
+    - description field in frontmatter (non-empty)
+    - Body content not empty (warning)
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    content = path.read_text()
+
+    fm = _parse_frontmatter(content)
+    if fm is None:
+        errors.append("Missing YAML frontmatter")
+        return errors, warnings
+
+    desc = fm.get("description")
+    if desc is None:
+        errors.append("Missing required frontmatter field: description")
+    elif not isinstance(desc, str) or not desc.strip():
+        errors.append("Frontmatter description must be a non-empty string")
+
+    body = _get_body(content)
+    if not body:
+        warnings.append("Command body is empty — consider adding content")
+
+    return errors, warnings
+
+
+def run(root: Path, *, fix: bool = False, strict: bool = False) -> ValidateReport:
+    """Validate skill registry and command files."""
+    report = ValidateReport(validator="skill-command")
+
+    # --- Skill registry validation ---
+    registry_errors, registry_warnings = validate_skill_registry(root)
+
+    for e in registry_errors:
+        report.errors += 1
+        report.details.append(f"[ERROR] skill-registry.yaml: {e}")
+
+    for w in registry_warnings:
+        if strict:
+            report.errors += 1
+            report.details.append(f"[ERROR] skill-registry.yaml: {w}")
+        else:
+            report.warnings += 1
+            report.details.append(f"[WARN] skill-registry.yaml: {w}")
+
+    if not registry_errors:
+        report.passed += 1
+
+    # --- Command file validation ---
+    commands_dir = root / "pennyfarthing-dist" / "commands"
+    command_files = discover_command_files(commands_dir)
+
+    for path in command_files:
+        file_errors, file_warnings = validate_command_file(path)
+
+        for e in file_errors:
+            report.errors += 1
+            report.details.append(f"[ERROR] {path.name}: {e}")
+
+        for w in file_warnings:
+            if strict:
+                report.errors += 1
+                report.details.append(f"[ERROR] {path.name}: {w}")
+            else:
+                report.warnings += 1
+                report.details.append(f"[WARN] {path.name}: {w}")
+
+        if not file_errors:
+            report.passed += 1
+
+    return report

package/pennyfarthing_scripts/validate/adapters/sprint.py

@@ -0,0 +1,69 @@
+"""Sprint YAML validator adapter.
+
+Auto-discovers sprint files and delegates to sprint/validate_cmd.validate_sprint_yaml().
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pennyfarthing_scripts.validate import ValidateReport
+
+
+def _discover_files(root: Path) -> list[Path]:
+    """Find all validatable YAML in sprint/."""
+    sprint_dir = root / "sprint"
+    if not sprint_dir.is_dir():
+        return []
+
+    files: list[Path] = []
+
+    cs = sprint_dir / "current-sprint.yaml"
+    if cs.exists():
+        files.append(cs)
+
+    files.extend(sorted(sprint_dir.glob("epic-*.yaml")))
+    files.extend(sorted(sprint_dir.glob("initiative-*.yaml")))
+
+    future = sprint_dir / "future.yaml"
+    if future.exists():
+        files.append(future)
+
+    return files
+
+
+def run(root: Path, *, fix: bool = False, strict: bool = False) -> ValidateReport:
+    """Validate all sprint YAML files."""
+    from pennyfarthing_scripts.sprint.validate_cmd import validate_sprint_yaml
+
+    report = ValidateReport(validator="sprint")
+    files = _discover_files(root)
+
+    for path in files:
+        result = validate_sprint_yaml(path, fix=fix)
+
+        if result.errors:
+            report.errors += len(result.errors)
+            for err in result.errors:
+                line_info = f" (line {err.line})" if err.line else ""
+                report.details.append(
+                    f"[{err.category.upper()}] {path.name}: {err.message}{line_info}"
+                )
+
+        if result.format_issues:
+            for issue in result.format_issues:
+                if strict:
+                    report.errors += 1
+                else:
+                    report.warnings += 1
+                report.details.append(
+                    f"[FORMAT] {path.name}: {issue.message}"
+                )
+
+        if result.valid and not result.errors:
+            report.passed += 1
+
+        if result.fixed:
+            report.fixed = True
+
+    return report