@flydocs/cli 0.6.0-alpha.2 → 0.6.0-alpha.21

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

@@ -0,0 +1,132 @@
+#!/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
+
+
+# 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 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
+    if tool_name == 'Bash':
+        command = tool_input.get('command', '')
+        if should_approve(command):
+            skill, script = get_script_info(command)
+            result = {
+                "hookSpecificOutput": {
+                    "permissionDecision": "allow",
+                    "additionalContext": f"Auto-approved FlyDocs script: {skill}/{script}"
+                }
+            }
+            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,94 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: post-transition-check.py
+Triggered: PostToolUse (Bash)
+Purpose: Validate that issue transitions include comments
+
+Fires after every Bash command. Only acts on `issues.py transition`
+commands. Warns when a transition is missing a comment argument and
+flags unusual state transitions.
+
+Exit codes:
+  0 - Always (non-blocking)
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+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 build_output(message: str) -> str:
+    return json.dumps({"hookSpecificOutput": {"additionalContext": message}})
+
+
+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", "")
+    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))
+            sys.exit(0)
+
+    print("{}")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()