@flydocs/cli 0.6.0-alpha.3 → 0.6.0-alpha.30

package/template/.claude/hooks/auto-approve.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""
+PreToolUse Hook: Auto-approve FlyDocs scripts + workflow state nudges
+
+1. Auto-approves Bash commands that execute scripts in the unified skill:
+   .claude/skills/flydocs-workflow/scripts/
+
+2. Nudges the agent when Edit/Write is attempted but the active issue
+   isn't in IMPLEMENTING status (non-blocking, informational only).
+
+Exit codes:
+- 0 with JSON: Approved or nudge context (decision in output)
+- 0 with no output: No opinion, continue normally
+- 2: Block (stderr shown to AI)
+"""
+
+import sys
+import json
+import os
+import re
+from pathlib import Path
+
+DEBUG_HOOK = os.environ.get('DEBUG_HOOK', '0') == '1'
+SCRIPT_DIR = Path(__file__).parent.resolve()
+DEBUG_LOG = SCRIPT_DIR.parent / 'logs' / 'hook-debug.log'
+
+
+def debug_log(message: str) -> None:
+    """Write debug message to log file if DEBUG_HOOK is enabled."""
+    if not DEBUG_HOOK:
+        return
+    try:
+        DEBUG_LOG.parent.mkdir(parents=True, exist_ok=True)
+        from datetime import datetime
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        with open(DEBUG_LOG, 'a') as f:
+            f.write(f'[{timestamp}] [auto-approve] {message}\n')
+    except (OSError, IOError):
+        pass
+
+
+# Pattern matches the unified flydocs-workflow scripts directory.
+# Uses ^ and $ anchors to prevent injection via command chaining
+# (e.g., "python3 script.py; evil" would match without anchors).
+APPROVED_PATTERN = re.compile(
+    r'^python3?\s+(?:["\']?(?:\$CLAUDE_PROJECT_DIR|\$\{CLAUDE_PROJECT_DIR\}|\.)["\']?/)?\.?claude/skills/flydocs-workflow/scripts/\w+\.py(?:\s+[^;&|`$()]*)?$'
+)
+
+
+def should_approve(command: str) -> bool:
+    """Check if command executes a FlyDocs skill script."""
+    return bool(APPROVED_PATTERN.match(command))
+
+
+def get_script_info(command: str) -> tuple[str, str]:
+    """Extract skill name and script name from command."""
+    match = re.search(
+        r'\.claude/skills/(flydocs-\w+)/scripts/(\w+\.py)', command
+    )
+    if match:
+        return match.group(1), match.group(2)
+    return "unknown", "unknown"
+
+
+def validate_create_args(command: str) -> list[str]:
+    """Validate arguments on issues.py create commands.
+
+    Returns a list of warning messages for missing or suspicious arguments.
+    These are advisory — the script itself enforces hard failures.
+    """
+    if 'create' not in command:
+        return []
+
+    warnings = []
+
+    # Check for missing --description (the script will reject, but warn early)
+    if '--description' not in command and '--description-file' not in command:
+        warnings.append(
+            'Missing --description: issues.py create requires a description. '
+            'Read the issue template in .flydocs/templates/ for the expected format.'
+        )
+
+    # Check for suspiciously short descriptions (e.g., --description "")
+    desc_match = re.search(r'--description\s+"([^"]*)"', command)
+    if desc_match and len(desc_match.group(1).strip()) < 20:
+        warnings.append(
+            'Description looks too short. Use the issue template from '
+            '.flydocs/templates/ for structured descriptions with AC checkboxes.'
+        )
+
+    return warnings
+
+
+COMMENT_TEMPLATES: dict[str, str] = {
+    'IMPLEMENTING': 'Comment format: "Starting implementation — [scope/approach description]"',
+    'REVIEW': 'Comment format: "Implementation complete — [what was done, what to verify]"',
+    'COMPLETE': 'Comment format: "All AC verified — [summary of what was delivered]"',
+    'BLOCKED': 'Comment format: "Blocked by [blocker] — [what needs to happen to unblock]"',
+    'CANCELED': 'Comment format: "Canceled — [reason for cancellation]"',
+    'TESTING': 'Comment format: "Ready for QA — [test focus areas]"',
+}
+
+
+def get_transition_comment_hint(command: str) -> str | None:
+    """Inject comment template guidance for transition commands."""
+    match = re.search(r'transition\s+\S+\s+(\S+)', command)
+    if not match:
+        return None
+    target = match.group(1).upper()
+    return COMMENT_TEMPLATES.get(target)
+
+
+def check_workflow_state_for_edit() -> str | None:
+    """Check if an active issue needs transition before code changes.
+
+    Returns a nudge message if the issue isn't in IMPLEMENTING, or None.
+    Non-blocking — the edit is allowed regardless.
+    """
+    focus_file = Path('.flydocs/session/focus.md')
+    status_file = Path('.flydocs/session/status')
+
+    if not focus_file.exists():
+        return None
+
+    try:
+        content = focus_file.read_text()
+        match = re.search(r'[A-Z]+-[0-9]+', content)
+        if not match:
+            return None
+        issue_id = match.group(0)
+    except (OSError, IOError):
+        return None
+
+    if not status_file.exists():
+        return None
+
+    try:
+        status = status_file.read_text().strip()
+    except (OSError, IOError):
+        return None
+
+    if status in ('IMPLEMENTING', 'REVIEW', 'TESTING', 'COMPLETE', 'CANCELED'):
+        return None
+
+    return (
+        f'Issue {issue_id} is in {status}, not In Progress. '
+        f'Transition before making changes: '
+        f'python3 .claude/skills/flydocs-workflow/scripts/issues.py '
+        f'transition {issue_id} IMPLEMENTING "Starting implementation"'
+    )
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        sys.exit(0)
+
+    tool_name = input_data.get('tool_name', '')
+    tool_input = input_data.get('tool_input', {})
+
+    # Auto-approve FlyDocs workflow scripts (with argument validation)
+    if tool_name == 'Bash':
+        command = tool_input.get('command', '')
+        if should_approve(command):
+            skill, script = get_script_info(command)
+
+            # Validate arguments and inject context
+            warnings = validate_create_args(command) if script == 'issues.py' else []
+            transition_hint = get_transition_comment_hint(command) if script == 'issues.py' else None
+
+            context = f"Auto-approved FlyDocs script: {skill}/{script}"
+            if warnings:
+                context += "\nWARNING: " + " | ".join(warnings)
+                debug_log(f"Create validation warnings: {warnings}")
+            if transition_hint:
+                context += f"\n{transition_hint}"
+                debug_log(f"Transition hint: {transition_hint}")
+
+            debug_log(f"Approved: {skill}/{script}")
+            result = {
+                "hookSpecificOutput": {
+                    "permissionDecision": "allow",
+                    "additionalContext": context
+                }
+            }
+            print(json.dumps(result))
+            sys.exit(0)
+
+    # Workflow state nudge for Edit/Write
+    if tool_name in ('Edit', 'Write'):
+        # Change to project dir for file reads
+        cwd = os.environ.get('CLAUDE_PROJECT_DIR', '')
+        if cwd and Path(cwd).is_dir():
+            os.chdir(cwd)
+
+        nudge = check_workflow_state_for_edit()
+        if nudge:
+            result = {
+                "hookSpecificOutput": {
+                    "additionalContext": nudge
+                }
+            }
+            print(json.dumps(result))
+            sys.exit(0)
+
+    # No opinion
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/hooks/post-pr-check.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: post-pr-check.py
+Triggered: PostToolUse (Bash)
+Purpose: Warn when PRs are created without the standard template
+
+Detects direct `gh pr create` or `glab mr create` commands that bypass
+the `issues.py pr` dispatcher, and checks if the PR body contains
+required sections.
+
+Exit codes:
+  0 - Success (optional message output)
+  Non-zero - Non-blocking warning
+"""
+
+import json
+import re
+import sys
+
+
+REQUIRED_SECTIONS = ["## Summary", "## Test Plan"]
+
+PR_CREATE_PATTERNS = [
+    re.compile(r"^g(?:h)\s+pr\s+create"),
+    re.compile(r"^glab\s+mr\s+create"),
+]
+
+# Pattern for our own dispatcher — don't warn on these
+DISPATCHER_PATTERN = re.compile(
+    r"python3?\s+.*flydocs-workflow/scripts/issues\.py\s+pr"
+)
+
+
+def is_pr_create_command(command: str) -> bool:
+    """Check if command creates a PR/MR directly (not through dispatcher)."""
+    if DISPATCHER_PATTERN.search(command):
+        return False
+    return any(p.search(command) for p in PR_CREATE_PATTERNS)
+
+
+def extract_body(command: str) -> str | None:
+    """Try to extract PR body from command arguments."""
+    # Match --body "..." or --body '...'
+    match = re.search(r'--body\s+["\'](.+?)["\']', command, re.DOTALL)
+    if match:
+        return match.group(1)
+    # Match --body "$(cat <<'EOF' ... EOF)"  (heredoc pattern)
+    match = re.search(r"--body\s+\"\$\(cat\s+<<['\"]?EOF['\"]?\n(.+?)\nEOF", command, re.DOTALL)
+    if match:
+        return match.group(1)
+    # Match --description (GitLab)
+    match = re.search(r'--description\s+["\'](.+?)["\']', command, re.DOTALL)
+    if match:
+        return match.group(1)
+    return None
+
+
+def check_body(body: str) -> list[str]:
+    """Check if PR body contains required sections. Returns list of missing sections."""
+    missing = []
+    for section in REQUIRED_SECTIONS:
+        if section.lower() not in body.lower():
+            missing.append(section)
+    return missing
+
+
+def main() -> None:
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    if tool_name != "Bash":
+        sys.exit(0)
+
+    command = tool_input.get("command", "")
+
+    if not is_pr_create_command(command):
+        sys.exit(0)
+
+    # Check if body contains required sections
+    body = extract_body(command)
+
+    if body is None:
+        # No body found — PR was created without a body or with a file
+        print(
+            "[PR Template Notice] PR created without using `issues.py pr`. "
+            "For consistent PR descriptions with auto-populated issue context, "
+            "use: `python3 .claude/skills/flydocs-workflow/scripts/issues.py pr --issue <ref>`"
+        )
+        sys.exit(0)
+
+    missing = check_body(body)
+    if missing:
+        sections = ", ".join(missing)
+        print(
+            f"[PR Template Notice] PR body is missing required sections: {sections}. "
+            "Consider using `issues.py pr --issue <ref>` for standard template."
+        )
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/hooks/post-transition-check.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: post-transition-check.py
+Triggered: PostToolUse (Bash)
+Purpose: Validate transitions and manage session files
+
+Fires after every Bash command. Only acts on `issues.py transition`
+commands. Validates comment presence, flags unusual transitions, and
+updates local session files to keep hooks in sync.
+
+Exit codes:
+  0 - Always (non-blocking)
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+DEBUG_HOOK = os.environ.get('DEBUG_HOOK', '0') == '1'
+SCRIPT_DIR = Path(__file__).parent.resolve()
+DEBUG_LOG = SCRIPT_DIR.parent / 'logs' / 'hook-debug.log'
+
+
+def debug_log(message: str) -> None:
+    """Write debug message to log file if DEBUG_HOOK is enabled."""
+    if not DEBUG_HOOK:
+        return
+    try:
+        DEBUG_LOG.parent.mkdir(parents=True, exist_ok=True)
+        from datetime import datetime
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        with open(DEBUG_LOG, 'a') as f:
+            f.write(f'[{timestamp}] [post-transition] {message}\n')
+    except (OSError, IOError):
+        pass
+
+TRANSITION_PATTERN = re.compile(
+    r"issues\.py\s+transition\s+(\S+)\s+(\S+)(?:\s+(.+))?"
+)
+
+VALID_TRANSITIONS: dict[str, set[str]] = {
+    "BACKLOG": {"READY", "IMPLEMENTING", "CANCELED"},
+    "READY": {"IMPLEMENTING", "CANCELED"},
+    "IMPLEMENTING": {"REVIEW", "BLOCKED", "CANCELED"},
+    "BLOCKED": {"IMPLEMENTING", "CANCELED"},
+    "REVIEW": {"COMPLETE", "TESTING", "IMPLEMENTING", "CANCELED"},
+    "TESTING": {"COMPLETE", "IMPLEMENTING", "CANCELED"},
+}
+
+
+def read_current_status() -> str | None:
+    """Read current issue status from session file."""
+    try:
+        return Path(".flydocs/session/status").read_text().strip().upper()
+    except (OSError, ValueError):
+        return None
+
+
+def post_create_audit(command: str, input_data: dict) -> str | None:
+    """Audit a newly created issue for completeness.
+
+    Checks the command output (tool_result) for the created issue identifier,
+    then verifies the command included expected arguments.
+    """
+    warnings = []
+
+    # Check for description presence in the command
+    if "--description" not in command and "--description-file" not in command:
+        if "--triage" not in command:
+            warnings.append("Created without --description (script should have rejected this)")
+
+    # Check for type
+    if "--type" not in command:
+        warnings.append("Created without --type")
+
+    # Check tool result for success
+    tool_result = input_data.get("tool_result", {})
+    stdout = tool_result.get("stdout", "")
+    if stdout:
+        try:
+            result = json.loads(stdout)
+            identifier = result.get("identifier", "")
+            auto_resolved = result.get("autoResolved", {})
+            if auto_resolved:
+                resolved_parts = [f"{k}={v}" for k, v in auto_resolved.items()]
+                warnings.append(f"Auto-resolved: {', '.join(resolved_parts)}")
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+    # Track compliance score
+    _update_compliance_score(has_findings=len(warnings) > 0, input_data=input_data)
+
+    if not warnings:
+        return None
+    return "Post-create audit: " + " | ".join(warnings)
+
+
+def _update_compliance_score(has_findings: bool, input_data: dict) -> None:
+    """Track per-session compliance score in validation cache.
+
+    Increments total_created and compliant_created counters. Resets
+    when a new session is detected (different session_id).
+    """
+    cwd = input_data.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR", "")
+    if not cwd:
+        return
+    cache_file = Path(cwd) / ".flydocs" / "validation-cache.json"
+    try:
+        cache = json.loads(cache_file.read_text()) if cache_file.exists() else {}
+    except (json.JSONDecodeError, OSError):
+        cache = {}
+
+    compliance = cache.get("compliance", {"totalCreated": 0, "compliantCreated": 0})
+    compliance["totalCreated"] = compliance.get("totalCreated", 0) + 1
+    if not has_findings:
+        compliance["compliantCreated"] = compliance.get("compliantCreated", 0) + 1
+    total = compliance["totalCreated"]
+    compliant = compliance["compliantCreated"]
+    compliance["score"] = round(compliant / total * 100) if total > 0 else 100
+    cache["compliance"] = compliance
+
+    try:
+        cache_file.parent.mkdir(parents=True, exist_ok=True)
+        cache_file.write_text(json.dumps(cache, indent=2))
+        debug_log(f"Compliance: {compliant}/{total} = {compliance['score']}%")
+    except OSError:
+        pass
+
+
+def build_output(message: str) -> str:
+    return json.dumps({"hookSpecificOutput": {"additionalContext": message}})
+
+
+def update_session_files(ref: str, status: str, input_data: dict) -> None:
+    """Update local session files after a transition.
+
+    Keeps .flydocs/session/ in sync with issue state so that other hooks
+    (stop-gate, prompt-submit) have reliable local state to work with.
+    """
+    # Resolve working directory
+    cwd = input_data.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR", "")
+    if cwd and Path(cwd).is_dir():
+        os.chdir(cwd)
+
+    session_dir = Path(".flydocs/session")
+    try:
+        session_dir.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return
+
+    # Always write the new status
+    try:
+        (session_dir / "status").write_text(status)
+    except OSError:
+        pass
+
+    # Update focus file with the issue ref
+    try:
+        focus_file = session_dir / "focus.md"
+        if not focus_file.exists() or ref not in focus_file.read_text():
+            focus_file.write_text(f"# Active Issue\n\n{ref}\n")
+    except OSError:
+        pass
+
+    # On IMPLEMENTING transition, try to cache acceptance criteria
+    if status == "IMPLEMENTING":
+        _cache_acceptance_criteria(ref, session_dir)
+
+    # On COMPLETE or CANCELED, clean up session files
+    if status in ("COMPLETE", "CANCELED"):
+        for f in ("focus.md", "status", "acceptance-criteria.md"):
+            try:
+                (session_dir / f).unlink(missing_ok=True)
+            except OSError:
+                pass
+
+
+def _cache_acceptance_criteria(ref: str, session_dir: Path) -> None:
+    """Fetch and cache acceptance criteria from the issue description.
+
+    Extracts checkbox lines from the issue description and writes them
+    to acceptance-criteria.md for local hook use.
+    """
+    try:
+        import subprocess
+        result = subprocess.run(
+            [
+                "python3",
+                ".claude/skills/flydocs-workflow/scripts/issues.py",
+                "get", ref, "--fields", "full",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+        if result.returncode != 0:
+            return
+        issue = json.loads(result.stdout)
+        description = issue.get("description", "")
+        if not description:
+            return
+
+        # Extract checkbox lines
+        ac_lines = [
+            line for line in description.splitlines()
+            if re.match(r"^\s*-\s*\[[ x]\]", line, re.IGNORECASE)
+        ]
+        if ac_lines:
+            (session_dir / "acceptance-criteria.md").write_text(
+                "# Acceptance Criteria\n\n" + "\n".join(ac_lines) + "\n"
+            )
+    except (subprocess.TimeoutExpired, json.JSONDecodeError, OSError, FileNotFoundError):
+        pass
+
+
+def main() -> None:
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        print("{}")
+        sys.exit(0)
+
+    if input_data.get("tool_name") != "Bash":
+        print("{}")
+        sys.exit(0)
+
+    command = input_data.get("tool_input", {}).get("command", "")
+
+    # Post-create audit — check if a new issue was created
+    if "issues.py" in command and " create " in command:
+        audit_msg = post_create_audit(command, input_data)
+        if audit_msg:
+            print(build_output(audit_msg))
+        else:
+            print("{}")
+        sys.exit(0)
+
+    match = TRANSITION_PATTERN.search(command)
+
+    if not match:
+        print("{}")
+        sys.exit(0)
+
+    ref = match.group(1)
+    status = match.group(2).upper()
+    comment = match.group(3)
+
+    if not comment or not comment.strip():
+        msg = (
+            f"Transition to {status} is missing a comment. "
+            f"Every status transition requires a comment — add one now: "
+            f'python3 .claude/skills/flydocs-workflow/scripts/issues.py '
+            f'comment {ref} "<describe what changed>"'
+        )
+        print(build_output(msg))
+        sys.exit(0)
+
+    from_status = read_current_status()
+    if from_status and from_status in VALID_TRANSITIONS:
+        allowed = VALID_TRANSITIONS[from_status]
+        if status not in allowed:
+            msg = (
+                f"Unusual transition: {from_status} -> {status}. "
+                f"Verify this is intentional."
+            )
+            print(build_output(msg))
+            # Still update session files even for unusual transitions
+            update_session_files(ref, status, input_data)
+            sys.exit(0)
+
+    # Update session files after successful transition
+    update_session_files(ref, status, input_data)
+
+    print("{}")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()