pi-agent-toolkit 0.1.0

package/dist/dotfiles/global-skills/technical-docs/scripts/validate_docs.py

@@ -0,0 +1,352 @@
+#!/usr/bin/env python3
+"""Validate documentation against technical-docs standards.
+
+This script provides automated validation checks for documentation quality,
+helping catch common issues before manual review.
+
+Usage:
+    python validate_docs.py <file_path>
+    python validate_docs.py --check-docstrings <python_file>
+    python validate_docs.py --check-links <markdown_file>
+"""
+
+import argparse
+import ast
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+class ValidationResult:
+    """Container for validation results."""
+
+    def __init__(self) -> None:
+        """Initialize validation result tracker."""
+        self.errors: list[str] = []
+        self.warnings: list[str] = []
+        self.passed: list[str] = []
+
+    def add_error(self, message: str) -> None:
+        """Add an error message.
+
+        :param message: Error description
+        """
+        self.errors.append(f"❌ ERROR: {message}")
+
+    def add_warning(self, message: str) -> None:
+        """Add a warning message.
+
+        :param message: Warning description
+        """
+        self.warnings.append(f"⚠️  WARNING: {message}")
+
+    def add_pass(self, message: str) -> None:
+        """Add a passing check message.
+
+        :param message: Success description
+        """
+        self.passed.append(f"✅ PASS: {message}")
+
+    def has_errors(self) -> bool:
+        """Check if any errors were found.
+
+        :returns: True if errors exist
+        """
+        return len(self.errors) > 0
+
+    def print_summary(self) -> None:
+        """Print validation results summary."""
+        print("\n" + "=" * 60)
+        print("VALIDATION RESULTS")
+        print("=" * 60 + "\n")
+
+        if self.passed:
+            print("Passed Checks:")
+            for msg in self.passed:
+                print(f"  {msg}")
+            print()
+
+        if self.warnings:
+            print("Warnings:")
+            for msg in self.warnings:
+                print(f"  {msg}")
+            print()
+
+        if self.errors:
+            print("Errors:")
+            for msg in self.errors:
+                print(f"  {msg}")
+            print()
+
+        print("-" * 60)
+        print(
+            f"Summary: {len(self.passed)} passed, {len(self.warnings)} warnings, {len(self.errors)} errors"
+        )
+        print("-" * 60 + "\n")
+
+
+def validate_docstring_format(file_path: Path) -> ValidationResult:
+    """Validate Python docstrings follow Sphinx-style format.
+
+    Checks for:
+    - Presence of docstrings on functions/classes
+    - Sphinx-style :param, :returns, :raises tags
+    - Parameter documentation completeness
+    - Type hint presence
+
+    :param file_path: Path to Python file to validate
+    :returns: ValidationResult with findings
+    :raises FileNotFoundError: If file_path does not exist
+    :raises SyntaxError: If Python file has syntax errors
+    """
+    result = ValidationResult()
+
+    if not file_path.exists():
+        result.add_error(f"File not found: {file_path}")
+        return result
+
+    content = file_path.read_text(encoding="utf-8")
+
+    try:
+        tree = ast.parse(content, filename=str(file_path))
+    except SyntaxError as e:
+        result.add_error(f"Python syntax error: {e}")
+        return result
+
+    functions = [node for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)]
+    classes = [node for node in ast.walk(tree) if isinstance(node, ast.ClassDef)]
+
+    # Check functions
+    for func in functions:
+        if func.name.startswith("_") and func.name != "__init__":
+            continue  # Skip private functions
+
+        docstring = ast.get_docstring(func)
+
+        if not docstring:
+            result.add_warning(
+                f"Function '{func.name}' at line {func.lineno} has no docstring"
+            )
+            continue
+
+        # Check for Sphinx-style tags
+        has_param = ":param" in docstring
+        has_returns = ":returns:" in docstring or ":return:" in docstring
+        has_raises = ":raises" in docstring
+
+        # Check parameters
+        params = [arg.arg for arg in func.args.args if arg.arg != "self"]
+        if params and not has_param:
+            result.add_warning(
+                f"Function '{func.name}' at line {func.lineno} has parameters but no :param tags"
+            )
+
+        # Check return type
+        if func.returns and not has_returns:
+            result.add_warning(
+                f"Function '{func.name}' at line {func.lineno} has return type but no :returns: tag"
+            )
+
+        # Type hints
+        if params:
+            missing_hints = [
+                arg.arg for arg in func.args.args if arg.annotation is None and arg.arg != "self"
+            ]
+            if missing_hints:
+                result.add_warning(
+                    f"Function '{func.name}' at line {func.lineno} missing type hints for: {', '.join(missing_hints)}"
+                )
+
+        if docstring and has_param and (not params or has_returns):
+            result.add_pass(f"Function '{func.name}' has proper Sphinx docstring")
+
+    # Check classes
+    for cls in classes:
+        docstring = ast.get_docstring(cls)
+        if not docstring:
+            result.add_warning(
+                f"Class '{cls.name}' at line {cls.lineno} has no docstring"
+            )
+        else:
+            result.add_pass(f"Class '{cls.name}' has docstring")
+
+    return result
+
+
+def validate_markdown_links(file_path: Path) -> ValidationResult:
+    """Validate links in markdown files.
+
+    Checks for:
+    - Broken internal links (file references)
+    - Malformed link syntax
+    - Anchor references to non-existent sections
+
+    :param file_path: Path to markdown file to validate
+    :returns: ValidationResult with findings
+    :raises FileNotFoundError: If file_path does not exist
+    """
+    result = ValidationResult()
+
+    if not file_path.exists():
+        result.add_error(f"File not found: {file_path}")
+        return result
+
+    content = file_path.read_text(encoding="utf-8")
+
+    # Pattern for markdown links: [text](url)
+    link_pattern = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+    matches = link_pattern.findall(content)
+
+    if not matches:
+        result.add_pass("No links found to validate")
+        return result
+
+    base_dir = file_path.parent
+
+    for text, url in matches:
+        # Skip external URLs
+        if url.startswith(("http://", "https://", "mailto:", "#")):
+            continue
+
+        # Parse internal file links
+        link_parts = url.split("#")
+        file_ref = link_parts[0]
+
+        if not file_ref:
+            continue  # Anchor-only link
+
+        # Resolve relative path
+        target_path = (base_dir / file_ref).resolve()
+
+        if not target_path.exists():
+            result.add_error(
+                f"Broken link: [{text}]({url}) - target does not exist: {target_path}"
+            )
+        else:
+            result.add_pass(f"Valid internal link: [{text}]({url})")
+
+    return result
+
+
+def validate_code_blocks(file_path: Path) -> ValidationResult:
+    """Validate code blocks in markdown files.
+
+    Checks for:
+    - Code blocks have language tags
+    - Python code blocks are syntactically valid
+    - Consistent code formatting
+
+    :param file_path: Path to markdown file to validate
+    :returns: ValidationResult with findings
+    """
+    result = ValidationResult()
+
+    if not file_path.exists():
+        result.add_error(f"File not found: {file_path}")
+        return result
+
+    content = file_path.read_text(encoding="utf-8")
+
+    # Find code blocks
+    code_block_pattern = re.compile(r"```(\w*)\n(.*?)```", re.DOTALL)
+    matches = code_block_pattern.findall(content)
+
+    if not matches:
+        result.add_pass("No code blocks found")
+        return result
+
+    for i, (language, code) in enumerate(matches, 1):
+        if not language:
+            result.add_warning(f"Code block #{i} is missing language tag")
+            continue
+
+        result.add_pass(f"Code block #{i} has language tag: {language}")
+
+        # Validate Python syntax
+        if language.lower() in ("python", "py"):
+            try:
+                ast.parse(code)
+                result.add_pass(f"Python code block #{i} has valid syntax")
+            except SyntaxError as e:
+                result.add_warning(
+                    f"Python code block #{i} has syntax error: {e.msg} at line {e.lineno}"
+                )
+
+    return result
+
+
+def validate_file(file_path: Path, check_type: str | None = None) -> ValidationResult:
+    """Validate a file based on its type or specified check.
+
+    :param file_path: Path to file to validate
+    :param check_type: Optional specific check type (docstrings, links, code-blocks)
+    :returns: Combined validation results
+    """
+    combined = ValidationResult()
+
+    if check_type == "docstrings" or (check_type is None and file_path.suffix == ".py"):
+        print(f"Validating docstrings in {file_path}...")
+        result = validate_docstring_format(file_path)
+        combined.errors.extend(result.errors)
+        combined.warnings.extend(result.warnings)
+        combined.passed.extend(result.passed)
+
+    if check_type == "links" or (check_type is None and file_path.suffix == ".md"):
+        print(f"Validating links in {file_path}...")
+        result = validate_markdown_links(file_path)
+        combined.errors.extend(result.errors)
+        combined.warnings.extend(result.warnings)
+        combined.passed.extend(result.passed)
+
+    if check_type == "code-blocks" or (check_type is None and file_path.suffix == ".md"):
+        print(f"Validating code blocks in {file_path}...")
+        result = validate_code_blocks(file_path)
+        combined.errors.extend(result.errors)
+        combined.warnings.extend(result.warnings)
+        combined.passed.extend(result.passed)
+
+    return combined
+
+
+def main() -> int:
+    """Main entry point for validation script.
+
+    :returns: Exit code (0 for success, 1 for errors)
+    """
+    parser = argparse.ArgumentParser(
+        description="Validate documentation against technical-docs standards"
+    )
+    parser.add_argument("file_path", type=Path, help="Path to file to validate")
+    parser.add_argument(
+        "--check-docstrings",
+        action="store_true",
+        help="Check Python docstring format",
+    )
+    parser.add_argument(
+        "--check-links", action="store_true", help="Check markdown links"
+    )
+    parser.add_argument(
+        "--check-code-blocks", action="store_true", help="Check markdown code blocks"
+    )
+
+    args = parser.parse_args()
+
+    # Determine check type
+    check_type = None
+    if args.check_docstrings:
+        check_type = "docstrings"
+    elif args.check_links:
+        check_type = "links"
+    elif args.check_code_blocks:
+        check_type = "code-blocks"
+
+    # Run validation
+    result = validate_file(args.file_path, check_type)
+    result.print_summary()
+
+    return 1 if result.has_errors() else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/dist/dotfiles/global-skills/whats-new/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: whats-new
+description: Analyze git changes between branches and generate a changelog entry. Use when catching up on repo changes, after merges, or when asking "what's new in the codebase?"
+context: main
+---
+
+# whats-new
+
+Analyze git changes and generate a changelog entry to help track what's new in the codebase.
+
+## Trigger
+
+- `/whats-new` - Compare current branch to origin/master (default)
+- `/whats-new <branch>` - Compare to a specific branch
+- `/whats-new --since "2 weeks ago"` - Time-based comparison
+- "What's new in the repo?"
+- "Catch me up on changes"
+
+## Workflow
+
+### Step 1: Determine Comparison Target
+
+Parse the user's input to determine what to compare against:
+- If no argument: compare `HEAD` to `origin/master`
+- If branch name provided: compare `HEAD` to that branch
+- If `--since` provided: use time-based git log
+
+### Step 2: Gather Git Information
+
+Run these commands to understand the changes:
+
+```bash
+# Fetch latest from remote
+git fetch origin
+
+# Get commit summary
+git log --oneline HEAD..<target> 2>/dev/null || git log --oneline <target>..HEAD
+
+# Get file change statistics
+git diff --stat HEAD..<target> 2>/dev/null || git diff --stat <target>..HEAD
+
+# Get list of new files
+git diff --name-status HEAD..<target> 2>/dev/null | grep "^A" || git diff --name-status <target>..HEAD | grep "^A"
+
+# Get list of modified files
+git diff --name-only HEAD..<target> 2>/dev/null || git diff --name-only <target>..HEAD
+```
+
+### Step 3: Analyze Changes
+
+For each significant area of change, provide architectural context:
+
+**Areas to analyze:**
+- `src/model/` - New data models, schema changes
+- `src/service/` - New business logic, services
+- `src/tasks/` - Celery tasks, background jobs
+- `src/api/` - New endpoints, API changes
+- `src/cli/` - New commands, CLI enhancements
+- `src/repository/` - Data access patterns
+- `src/schema/` - Pydantic validation schemas
+- `etc/settings.toml` - Configuration changes
+- `migrations/` - Database migrations
+
+**For each new file or significant change:**
+1. Read the file to understand its purpose
+2. Identify key classes, functions, patterns
+3. Note how it relates to existing code
+4. Highlight any new dependencies or patterns introduced
+
+### Step 4: Generate Changelog Entry
+
+Create a markdown file at `.notes/changelog/YYYY-MM-DD-<branch-name>.md` with this structure:
+
+```markdown
+---
+date: YYYY-MM-DD
+branch: <branch-name>
+compared_to: <target-branch>
+author: <from git log if available>
+---
+
+# <Branch Name> Changes
+
+## Summary
+<1-2 sentence overview of what this branch adds>
+
+## New Capabilities
+- <Capability 1>: Brief description
+- <Capability 2>: Brief description
+
+## New Files
+
+### Models
+| File | Purpose |
+|------|---------|
+| `src/model/example.py` | Description |
+
+### Services
+| File | Purpose |
+|------|---------|
+| `src/service/example.py` | Description |
+
+### Tasks
+| File | Purpose |
+|------|---------|
+| `src/tasks/example.py` | Description |
+
+<... other sections as needed ...>
+
+## Modified Files
+- `path/to/file.py` - What changed and why
+
+## New Patterns to Know
+- **Pattern name**: Explanation of new pattern or convention introduced
+- **Configuration**: Any new settings in `etc/settings.toml`
+
+## New CLI Commands
+```bash
+# command - description
+python -m src.cli <command>
+```
+
+## New API Endpoints
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/v1/...` | Description |
+
+## Database Changes
+- New migrations: `migrations/versions/xxx_description.py`
+- Schema changes: ...
+
+## Dependencies
+- New packages added to `pyproject.toml`
+```
+
+### Step 5: Report Summary
+
+After creating the changelog entry:
+1. Display a brief summary to the user
+2. Show the path to the created file
+3. Highlight the most important things to know
+
+## Output Location
+
+All changelog entries go to: `.notes/changelog/`
+
+Naming convention: `YYYY-MM-DD-<branch-name-slug>.md`
+
+Examples:
+- `2025-01-13-dmng-3-monitoring.md`
+- `2025-01-10-dmng-2-data-model.md`
+
+## Notes
+
+- Always fetch from origin before comparing to ensure you have latest changes
+- Focus on architectural significance, not just file listings
+- Identify patterns that the user should adopt in future work
+- If comparing to a branch that has YOUR changes (you're ahead), flip the comparison direction
+- Keep the changelog entry focused and scannable

package/dist/dotfiles/intercepted-commands/pip

@@ -0,0 +1,7 @@
+#!/bin/bash
+echo "Error: pip is disabled. Use uv instead:" >&2
+echo "" >&2
+echo "  To install a package for a script: uv run --with PACKAGE python script.py" >&2
+echo "  To add a dependency to the project: uv add PACKAGE" >&2
+echo "" >&2
+exit 1

package/dist/dotfiles/intercepted-commands/pip3

@@ -0,0 +1,7 @@
+#!/bin/bash
+echo "Error: pip3 is disabled. Use uv instead:" >&2
+echo "" >&2
+echo "  To install a package for a script: uv run --with PACKAGE python script.py" >&2
+echo "  To add a dependency to the project: uv add PACKAGE" >&2
+echo "" >&2
+exit 1

package/dist/dotfiles/intercepted-commands/poetry

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+echo "Error: poetry is disabled. Use uv instead:" >&2
+echo "" >&2
+echo "  To initialize a project: uv init" >&2
+echo "  To add a dependency: uv add PACKAGE" >&2
+echo "  To sync dependencies: uv sync" >&2
+echo "  To run commands: uv run COMMAND" >&2
+echo "" >&2
+exit 1

package/dist/dotfiles/intercepted-commands/python

@@ -0,0 +1,104 @@
+#!/bin/bash
+
+# Check for disallowed module invocations
+for arg in "$@"; do
+    case "$arg" in
+        -mpip|-m\ pip|pip)
+            echo "Error: 'python -m pip' is disabled. Use uv instead:" >&2
+            echo "" >&2
+            echo "  To install a package for a script: uv run --with PACKAGE python script.py" >&2
+            echo "  To add a dependency to the project: uv add PACKAGE" >&2
+            echo "" >&2
+            exit 1
+            ;;
+        -mvenv|-m\ venv|venv)
+            echo "Error: 'python -m venv' is disabled. Use uv instead:" >&2
+            echo "" >&2
+            echo "  To create a virtual environment: uv venv" >&2
+            echo "" >&2
+            exit 1
+            ;;
+        -mpy_compile|-m\ py_compile|py_compile)
+            echo "Error: 'python -m py_compile' is disabled because it writes .pyc files to __pycache__." >&2
+            echo "" >&2
+            echo "  To verify syntax without bytecode output: uv run python -m ast path/to/file.py >/dev/null" >&2
+            echo "" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Check for -m flag followed by pip or venv
+prev=""
+for arg in "$@"; do
+    if [ "$prev" = "-m" ]; then
+        case "$arg" in
+            pip)
+                echo "Error: 'python -m pip' is disabled. Use uv instead:" >&2
+                echo "" >&2
+                echo "  To install a package for a script: uv run --with PACKAGE python script.py" >&2
+                echo "  To add a dependency to the project: uv add PACKAGE" >&2
+                echo "" >&2
+                exit 1
+                ;;
+            venv)
+                echo "Error: 'python -m venv' is disabled. Use uv instead:" >&2
+                echo "" >&2
+                echo "  To create a virtual environment: uv venv" >&2
+                echo "" >&2
+                exit 1
+                ;;
+            py_compile)
+                echo "Error: 'python -m py_compile' is disabled because it writes .pyc files to __pycache__." >&2
+                echo "" >&2
+                echo "  To verify syntax without bytecode output: uv run python -m ast path/to/file.py >/dev/null" >&2
+                echo "" >&2
+                exit 1
+                ;;
+        esac
+    fi
+    prev="$arg"
+done
+
+# Resolve a Python interpreter for uv. Prefer uv-managed Python to match
+# `uv run python` defaults, while still avoiding shim recursion.
+resolve_uv_python() {
+    local shim_dir candidate candidate_dir
+    shim_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+    candidate="$(uv python find --managed-python 2>/dev/null || true)"
+    if [ -n "$candidate" ] && [ -x "$candidate" ]; then
+        candidate_dir="$(cd "$(dirname "$candidate")" && pwd)"
+        if [ "$candidate_dir" != "$shim_dir" ]; then
+            echo "$candidate"
+            return 0
+        fi
+    fi
+
+    while IFS= read -r candidate; do
+        [ -n "$candidate" ] || continue
+        candidate_dir="$(cd "$(dirname "$candidate")" && pwd)"
+        [ "$candidate_dir" = "$shim_dir" ] && continue
+        echo "$candidate"
+        return 0
+    done < <(type -aP python3 2>/dev/null)
+
+    while IFS= read -r candidate; do
+        [ -n "$candidate" ] || continue
+        candidate_dir="$(cd "$(dirname "$candidate")" && pwd)"
+        [ "$candidate_dir" = "$shim_dir" ] && continue
+        echo "$candidate"
+        return 0
+    done < <(type -aP python 2>/dev/null)
+
+    return 1
+}
+
+UV_PYTHON="$(resolve_uv_python)"
+if [ -z "$UV_PYTHON" ]; then
+    echo "Error: Unable to locate a Python interpreter outside intercepted-commands." >&2
+    exit 1
+fi
+
+# Dispatch through uv with an explicit interpreter path to avoid recursion.
+exec uv run --python "$UV_PYTHON" python "$@"