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

package/template/.claude/hooks/prompt-submit.py

@@ -0,0 +1,513 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: prompt-submit.py
+Triggered: When user submits a prompt
+Purpose: Inject context and validate workflow state
+
+Exit codes:
+  0 - Success (plain text output adds context to conversation)
+  2 - Block prompt (stderr shown as reason)
+
+NOTE: Uses plain text output instead of JSON due to Claude Code bug (Issue #13912)
+where JSON output from UserPromptSubmit hooks causes "hook error" despite documentation.
+"""
+
+import json
+import os
+import re
+import subprocess
+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}] {message}\n')
+    except (OSError, IOError):
+        pass
+
+
+def get_git_context() -> str | None:
+    """Get git branch and uncommitted status."""
+    try:
+        # Check if in git repo
+        result = subprocess.run(
+            ['git', 'rev-parse', '--is-inside-work-tree'],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        if result.returncode != 0:
+            return None
+
+        # Get branch name
+        result = subprocess.run(
+            ['git', 'branch', '--show-current'],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        branch = result.stdout.strip() or 'detached'
+
+        # Check for uncommitted changes
+        uncommitted = 'no'
+        result = subprocess.run(['git', 'diff', '--quiet'], capture_output=True, timeout=5)
+        if result.returncode != 0:
+            uncommitted = 'yes'
+        result = subprocess.run(['git', 'diff', '--cached', '--quiet'], capture_output=True, timeout=5)
+        if result.returncode != 0:
+            uncommitted = 'yes'
+
+        return f'Git: branch={branch}, uncommitted={uncommitted}'
+    except (subprocess.TimeoutExpired, FileNotFoundError, subprocess.SubprocessError):
+        return None
+
+
+def get_issue_context() -> tuple[str | None, str | None]:
+    """Get active issue and status from session files."""
+    focus_file = Path('.flydocs/session/focus.md')
+    status_file = Path('.flydocs/session/status')
+
+    issue_id = None
+    status = None
+
+    if focus_file.exists():
+        try:
+            content = focus_file.read_text()
+            match = re.search(r'[A-Z]+-[0-9]+', content)
+            if match:
+                issue_id = match.group(0)
+        except (OSError, IOError):
+            pass
+
+    if status_file.exists():
+        try:
+            status = status_file.read_text().strip()
+        except (OSError, IOError):
+            pass
+
+    return issue_id, status
+
+
+def get_issue_context_line() -> str | None:
+    """Build a rich single-line issue context for prompt injection.
+
+    Consolidates issue ID, status, AC progress, and assignment into one
+    compact line that gives the agent full situational awareness.
+    """
+    issue_id, status = get_issue_context()
+    if not issue_id:
+        return None
+
+    parts = [issue_id]
+
+    # Status
+    status_display = {
+        'BACKLOG': 'Backlog',
+        'READY': 'Ready',
+        'IMPLEMENTING': 'In Progress',
+        'BLOCKED': 'Blocked',
+        'REVIEW': 'In Review',
+        'TESTING': 'QA',
+        'COMPLETE': 'Done',
+    }
+    if status:
+        parts.append(status_display.get(status, status))
+
+    # AC progress
+    ac_file = Path('.flydocs/session/acceptance-criteria.md')
+    if ac_file.exists():
+        try:
+            content = ac_file.read_text()
+            total = len(re.findall(r'^\s*-\s*\[', content, re.MULTILINE))
+            done = len(re.findall(r'^\s*-\s*\[x\]', content, re.MULTILINE | re.IGNORECASE))
+            if total > 0:
+                parts.append(f'AC {done}/{total}')
+        except (OSError, IOError):
+            pass
+
+    # Assignee from focus file
+    focus_file = Path('.flydocs/session/focus.md')
+    if focus_file.exists():
+        try:
+            content = focus_file.read_text()
+            assignee_match = re.search(r'[Aa]ssignee:\s*(.+)', content)
+            if assignee_match:
+                parts.append(f'Assigned: {assignee_match.group(1).strip()}')
+        except (OSError, IOError):
+            pass
+
+    # Workflow nudge based on status
+    if status == 'READY':
+        parts.append('[Transition to In Progress before starting work]')
+    elif status == 'IMPLEMENTING':
+        parts.append('[Update AC as you go, transition to Review when done]')
+    elif status == 'REVIEW':
+        parts.append('[Verify AC before approving]')
+
+    return f'Issue: {" | ".join(parts)}'
+
+
+def get_ac_progress() -> str | None:
+    """Get acceptance criteria progress."""
+    ac_file = Path('.flydocs/session/acceptance-criteria.md')
+    if not ac_file.exists():
+        return None
+
+    try:
+        content = ac_file.read_text()
+        total = len(re.findall(r'^\s*-\s*\[', content, re.MULTILINE))
+        done = len(re.findall(r'^\s*-\s*\[x\]', content, re.MULTILINE | re.IGNORECASE))
+        if total > 0:
+            return f'AC: {done}/{total} complete'
+    except (OSError, IOError):
+        pass
+
+    return None
+
+
+def get_workflow_reminder(status: str) -> str | None:
+    """Get workflow reminder based on current status."""
+    reminders = {
+        'IMPLEMENTING': '[Reminder: Log progress with comments, run tests before REVIEW]',
+        'REVIEW': '[Reminder: Check acceptance criteria before approving]',
+        'TESTING': '[Reminder: Validate all AC met before marking COMPLETE]'
+    }
+    return reminders.get(status)
+
+
+def get_orientation_context() -> str | None:
+    """Read lightweight orientation files directly (no subprocess).
+
+    Replaces the old get_graph_context() which shelled out to graph_context.py.
+    graph_context.py still exists for manual use — we just don't call it from
+    the prompt hook anymore.
+    """
+    parts = []
+
+    # 1. Previous session continuity
+    summary_file = Path('.flydocs/session/last-summary.json')
+    if summary_file.exists():
+        try:
+            data = json.loads(summary_file.read_text())
+            pending = data.get('pending', [])
+            blockers = data.get('blockers', [])
+            issues = data.get('issues', [])
+            bits = []
+            if issues:
+                bits.append(f'issues={",".join(issues)}')
+            if pending:
+                bits.append(f'pending={len(pending)}')
+            if blockers:
+                bits.append(f'blockers={len(blockers)}')
+            if bits:
+                parts.append(f'Last session: {", ".join(bits)}')
+        except (json.JSONDecodeError, OSError, IOError):
+            pass
+
+    # 2. Topology and workspace orientation
+    config_file = Path('.flydocs/config.json')
+    if config_file.exists():
+        try:
+            config = json.loads(config_file.read_text())
+            topo = config.get('topology')
+            if topo:
+                topo_label = topo.get('label', '')
+                topo_type = topo.get('type', '')
+                siblings = topo.get('siblingRepos', [])
+                if topo_label == 'sibling-repos' and siblings:
+                    parts.append(f'Topology: {topo_label} ({len(siblings)} repos: {", ".join(siblings[:4])})')
+                elif topo_label in ('monorepo-multi', 'monorepo-single'):
+                    parts.append(f'Topology: {topo_label}')
+        except (json.JSONDecodeError, OSError, IOError):
+            pass
+
+    # 3. Product context (first ~10 lines)
+    project_file = Path('flydocs/context/project.md')
+    if project_file.exists():
+        try:
+            lines = project_file.read_text().splitlines()[:10]
+            # Extract title line (first non-empty, non-heading-marker line)
+            for line in lines:
+                stripped = line.strip().lstrip('#').strip()
+                if stripped:
+                    parts.append(f'Product: {stripped}')
+                    break
+        except (OSError, IOError):
+            pass
+
+    if not parts:
+        return None
+
+    return ' | '.join(parts)
+
+
+def check_integrity_drift() -> str | None:
+    """Lightweight integrity drift check with 30-minute TTL.
+
+    Reads .flydocs/integrity.json and checks owned files/directories exist.
+    Caches result to avoid re-checking on every prompt.
+    """
+    integrity_file = Path('.flydocs/integrity.json')
+    if not integrity_file.exists():
+        return None
+
+    # TTL check — skip if checked within 30 minutes
+    cache_file = Path('.flydocs/integrity-cache.json')
+    if cache_file.exists():
+        try:
+            cache = json.loads(cache_file.read_text())
+            from datetime import datetime, timezone
+            cached_at = datetime.fromisoformat(cache.get('checkedAt', '').replace('Z', '+00:00'))
+            now = datetime.now(timezone.utc)
+            age_minutes = (now - cached_at).total_seconds() / 60
+            if age_minutes < 30:
+                # Return cached result if still fresh
+                missing = cache.get('missing', [])
+                if missing:
+                    return f'[Integrity drift: {len(missing)} owned file(s) missing — run /flydocs-update]'
+                return None
+        except (json.JSONDecodeError, OSError, ValueError, KeyError):
+            pass
+
+    # Run check
+    try:
+        data = json.loads(integrity_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    missing = []
+    for f in data.get('ownedFiles', []):
+        if not Path(f).exists():
+            missing.append(f)
+    for d in data.get('ownedDirectories', []):
+        if not Path(d).exists():
+            missing.append(d)
+
+    # Write cache
+    try:
+        from datetime import datetime, timezone
+        cache_data = {
+            'checkedAt': datetime.now(timezone.utc).isoformat(),
+            'missing': missing,
+        }
+        cache_file.write_text(json.dumps(cache_data))
+    except (OSError, IOError):
+        pass
+
+    if missing:
+        return f'[Integrity drift: {len(missing)} owned file(s) missing — run /flydocs-update]'
+    return None
+
+
+def get_flydocs_version() -> str | None:
+    """Get FlyDocs version."""
+    version_file = Path('.flydocs/version')
+    if version_file.exists():
+        try:
+            return version_file.read_text().strip()
+        except (OSError, IOError):
+            pass
+    return None
+
+
+def get_setup_nudge() -> str | None:
+    """Check if setup has been completed, return nudge if not.
+
+    Reads validation cache (written by validate_setup.py) for specific
+    missing items. Falls back to generic nudge if cache is absent.
+    """
+    config_file = Path('.flydocs/config.json')
+    if not config_file.exists():
+        return None
+    try:
+        config = json.loads(config_file.read_text())
+        if config.get('setupComplete') is not False:
+            return None
+
+        # Check validation cache for specific missing items
+        cache_file = Path('.flydocs/validation-cache.json')
+        if cache_file.exists():
+            try:
+                cache = json.loads(cache_file.read_text())
+                missing = cache.get('missing', [])
+                warnings = cache.get('warnings', [])
+                parts = []
+                if missing:
+                    parts.append(f'missing: {", ".join(missing)}')
+                if warnings:
+                    parts.append(f'warnings: {", ".join(warnings)}')
+                if parts:
+                    detail = '; '.join(parts)
+                    return f'[Setup incomplete — {detail}. Run /flydocs-setup or fix in dashboard]'
+            except (json.JSONDecodeError, OSError, IOError):
+                pass
+
+        return '[Setup incomplete — run /flydocs-setup to configure your project]'
+    except (json.JSONDecodeError, OSError, IOError):
+        pass
+    return None
+
+
+def get_config_freshness_nudge() -> str | None:
+    """Nudge if validation cache is stale (>24h old).
+
+    Only applies to cloud tier with setupComplete=true. Encourages
+    periodic re-validation so config stays in sync with the server.
+    """
+    config_file = Path('.flydocs/config.json')
+    if not config_file.exists():
+        return None
+    try:
+        config = json.loads(config_file.read_text())
+        # Only check freshness for cloud tier with completed setup
+        if config.get('tier') != 'cloud' or config.get('setupComplete') is not True:
+            return None
+
+        cache_file = Path('.flydocs/validation-cache.json')
+        if not cache_file.exists():
+            return '[Config not validated — run: python3 .claude/skills/flydocs-workflow/scripts/workspace.py validate]'
+
+        from datetime import datetime, timezone
+        cache = json.loads(cache_file.read_text())
+        timestamp_str = cache.get('timestamp')
+        if not timestamp_str:
+            return None
+
+        # Parse ISO timestamp
+        cached_at = datetime.fromisoformat(timestamp_str.replace('Z', '+00:00'))
+        now = datetime.now(timezone.utc)
+        age_hours = (now - cached_at).total_seconds() / 3600
+
+        if age_hours > 24:
+            return '[Config stale (>24h) — run: python3 .claude/skills/flydocs-workflow/scripts/workspace.py validate]'
+    except (json.JSONDecodeError, OSError, IOError, ValueError):
+        pass
+    return None
+
+
+def main() -> None:
+    """Main hook execution."""
+    debug_log('=== Hook invoked ===')
+    debug_log(f'PWD: {os.getcwd()}')
+    debug_log(f'SCRIPT_DIR: {SCRIPT_DIR}')
+    debug_log(f'CLAUDE_PROJECT_DIR: {os.environ.get("CLAUDE_PROJECT_DIR", "<not set>")}')
+
+    # Read hook input from stdin
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        input_data = {}
+
+    prompt = input_data.get('prompt', '')
+    session_id = input_data.get('session_id', '')
+    cwd = input_data.get('cwd', '')
+
+    debug_log(f'Parsed PROMPT: {prompt[:100]}...' if prompt else 'Parsed PROMPT: <empty>')
+    debug_log(f'Parsed SESSION_ID: {session_id}')
+    debug_log(f'Parsed CWD: {cwd}')
+
+    # Change to working directory
+    debug_log('Attempting to change directory...')
+    if cwd and Path(cwd).is_dir():
+        debug_log(f'Using CWD from input: {cwd}')
+        os.chdir(cwd)
+    elif os.environ.get('CLAUDE_PROJECT_DIR') and Path(os.environ['CLAUDE_PROJECT_DIR']).is_dir():
+        debug_log(f'Using CLAUDE_PROJECT_DIR: {os.environ["CLAUDE_PROJECT_DIR"]}')
+        os.chdir(os.environ['CLAUDE_PROJECT_DIR'])
+    else:
+        debug_log(f'No valid directory to change to, staying in: {os.getcwd()}')
+
+    debug_log(f'Now in directory: {os.getcwd()}')
+
+    # Build context parts
+    context_parts = []
+
+    # Git context
+    git_context = get_git_context()
+    branch = None
+    if git_context:
+        debug_log(f'Git context: {git_context}')
+        context_parts.append(git_context)
+        # Extract branch name for graph context
+        branch_match = re.search(r'branch=(\S+)', git_context)
+        if branch_match:
+            branch = branch_match.group(1).rstrip(',')
+
+    # Active project context
+    config_file = Path('.flydocs/config.json')
+    if config_file.exists():
+        try:
+            cfg = json.loads(config_file.read_text())
+            active_projects = cfg.get('workspace', {}).get('activeProjects', [])
+            if active_projects:
+                context_parts.append(f'ActiveProject: {active_projects[0]}')
+            elif cfg.get('tier') == 'cloud' and cfg.get('setupComplete'):
+                context_parts.append('[No active project set — run workspace.py set-active-project]')
+        except (json.JSONDecodeError, OSError, IOError):
+            pass
+
+    # Rich issue context (consolidated: ID, status, AC, assignment, nudge)
+    issue_line = get_issue_context_line()
+    if issue_line:
+        context_parts.append(issue_line)
+
+    # Setup completion nudge OR onboard nudge OR config freshness nudge
+    setup_nudge = get_setup_nudge()
+    if setup_nudge:
+        context_parts.append(setup_nudge)
+    else:
+        # Check if onboarding has been completed
+        try:
+            config_data = json.loads(Path('.flydocs/config.json').read_text())
+            if config_data.get('setupComplete') and not config_data.get('onboardComplete'):
+                context_parts.append('[Run /onboard to get oriented to this project]')
+        except (json.JSONDecodeError, OSError, IOError):
+            pass
+
+        freshness_nudge = get_config_freshness_nudge()
+        if freshness_nudge:
+            context_parts.append(freshness_nudge)
+
+    # Integrity drift check (TTL-cached, runs at most every 30 min)
+    drift = check_integrity_drift()
+    if drift:
+        context_parts.append(drift)
+
+    # FlyDocs version
+    version = get_flydocs_version()
+    if version:
+        context_parts.append(f'FlyDocs: {version}')
+
+    # Output status line
+    context = ' | '.join(context_parts)
+    debug_log(f'Final CONTEXT: {context}')
+
+    if context:
+        debug_log(f'Outputting plain text context: {context}')
+        print(context)
+
+    # Orientation context (lightweight file reads, no subprocess)
+    orientation = get_orientation_context()
+    if orientation:
+        debug_log(f'Orientation context: {orientation[:100]}...')
+        print(orientation)
+
+    debug_log('=== Hook completed successfully ===')
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/template/.claude/hooks/session-start.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: session-start.py
+Triggered: When a new Claude Code session begins (SessionStart)
+Purpose: Inject continuity context from previous session, active issue, and config state
+
+Exit codes:
+  0 - Success (JSON output with additionalContext)
+"""
+
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def get_previous_session_summary() -> str | None:
+    """Extract key details from last session summary."""
+    summary_file = Path('.flydocs/session/last-summary.json')
+    if not summary_file.exists():
+        return None
+    try:
+        data = json.loads(summary_file.read_text())
+        bits: list[str] = []
+        issues = data.get('issues', [])
+        if issues:
+            bits.append(f'issues={",".join(issues)}')
+        pending = data.get('pending', [])
+        if pending:
+            bits.append(f'pending={len(pending)}')
+        blockers = data.get('blockers', [])
+        if blockers:
+            bits.append(f'blockers={len(blockers)}')
+        notes = data.get('notes')
+        if notes:
+            bits.append(f'notes={notes[:80]}')
+        if bits:
+            return f'Last session: {" | ".join(bits)}'
+    except (json.JSONDecodeError, OSError, IOError):
+        pass
+    return None
+
+
+def get_active_issue_context() -> str | None:
+    """Build active issue status line from session files."""
+    issue_id = None
+    status = None
+
+    focus_file = Path('.flydocs/session/focus.md')
+    if focus_file.exists():
+        try:
+            match = re.search(r'[A-Z]+-[0-9]+', focus_file.read_text())
+            if match:
+                issue_id = match.group(0)
+        except (OSError, IOError):
+            pass
+
+    status_file = Path('.flydocs/session/status')
+    if status_file.exists():
+        try:
+            status = status_file.read_text().strip()
+        except (OSError, IOError):
+            pass
+
+    if not issue_id:
+        return None
+
+    ac_part = ''
+    ac_file = Path('.flydocs/session/acceptance-criteria.md')
+    if ac_file.exists():
+        try:
+            content = ac_file.read_text()
+            total = len(re.findall(r'^\s*-\s*\[', content, re.MULTILINE))
+            done = len(re.findall(r'^\s*-\s*\[x\]', content, re.MULTILINE | re.IGNORECASE))
+            if total > 0:
+                ac_part = f' | AC: {done}/{total}'
+        except (OSError, IOError):
+            pass
+
+    status_label = f' ({status})' if status else ''
+    return f'Active: {issue_id}{status_label}{ac_part}'
+
+
+def get_config_freshness() -> str | None:
+    """Warn if validation cache is stale or missing."""
+    cache_file = Path('.flydocs/validation-cache.json')
+    if not cache_file.exists():
+        return None
+    try:
+        data = json.loads(cache_file.read_text())
+        timestamp_str = data.get('timestamp')
+        if not timestamp_str:
+            return None
+        cached_at = datetime.fromisoformat(timestamp_str.replace('Z', '+00:00'))
+        age_hours = (datetime.now(timezone.utc) - cached_at).total_seconds() / 3600
+        if age_hours > 24:
+            return 'Config validation stale (>24h) — consider running: python3 .claude/skills/flydocs-workflow/scripts/workspace.py validate'
+    except (json.JSONDecodeError, OSError, IOError, ValueError):
+        pass
+    return None
+
+
+def main() -> None:
+    """Main hook execution."""
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        input_data = {}
+
+    cwd = input_data.get('cwd', '')
+    if cwd and Path(cwd).is_dir():
+        os.chdir(cwd)
+    elif os.environ.get('CLAUDE_PROJECT_DIR') and Path(os.environ['CLAUDE_PROJECT_DIR']).is_dir():
+        os.chdir(os.environ['CLAUDE_PROJECT_DIR'])
+
+    parts: list[str] = []
+
+    summary = get_previous_session_summary()
+    if summary:
+        parts.append(summary)
+
+    issue_ctx = get_active_issue_context()
+    if issue_ctx:
+        parts.append(issue_ctx)
+
+    freshness = get_config_freshness()
+    if freshness:
+        parts.append(freshness)
+
+    if not parts:
+        print('{}')
+        sys.exit(0)
+
+    output = {
+        "hookSpecificOutput": {
+            "additionalContext": " | ".join(parts)
+        }
+    }
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()