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

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

@@ -0,0 +1,262 @@
+#!/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 (v1 configs)."""
+    # v2 configs use get_config_freshness_v2() instead
+    config_file = Path('.flydocs/config.json')
+    if config_file.exists():
+        try:
+            config = json.loads(config_file.read_text())
+            if config.get('configFormat') == 2:
+                return None  # Skip v1 check for v2 configs
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    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 get_config_freshness_v2() -> str | None:
+    """Check config freshness via config/check endpoint (v2 configs only, FLY-540)."""
+    config_file = Path('.flydocs/config.json')
+    if not config_file.exists():
+        return None
+
+    try:
+        config = json.loads(config_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    if config.get('configFormat') != 2 or config.get('tier') != 'cloud':
+        return None
+
+    # Resolve API key: env var > global credentials
+    api_key = os.environ.get('FLYDOCS_API_KEY')
+    if not api_key:
+        cred_file = Path.home() / '.flydocs' / 'credentials'
+        if cred_file.exists():
+            try:
+                cred = json.loads(cred_file.read_text())
+                api_key = cred.get('apiKey')
+            except (json.JSONDecodeError, OSError):
+                pass
+
+    if not api_key:
+        return None
+
+    # Call config/check — lightweight, ~50ms
+    base_url = os.environ.get('FLYDOCS_RELAY_URL', 'https://app.flydocs.ai/api/relay').rstrip('/')
+    try:
+        import urllib.request
+        req = urllib.request.Request(
+            f'{base_url}/config/check',
+            headers={
+                'Authorization': f'Bearer {api_key}',
+                'Accept': 'application/json',
+            },
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = json.loads(resp.read().decode('utf-8'))
+    except Exception:
+        # Server unreachable — silently continue, never block a session
+        return None
+
+    if data.get('needsSync'):
+        stale_fields: list[str] = []
+        local_config_version = config.get('configVersion', 0)
+        if data.get('configVersion', 0) > local_config_version:
+            stale_fields.append('config')
+        if data.get('templateVersion', 0) > 0:
+            stale_fields.append('templates')
+        if data.get('contextVersion', 0) > 0:
+            stale_fields.append('context')
+        detail = f' ({", ".join(stale_fields)})' if stale_fields else ''
+        return f'Config updated{detail} — run `flydocs sync`'
+
+    return None
+
+
+def check_skills_manifest() -> str | None:
+    """Alert-mode skills manifest validation (FLY-541)."""
+    config_file = Path('.flydocs/config.json')
+    if not config_file.exists():
+        return None
+
+    try:
+        config = json.loads(config_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    expected = config.get('skills', {}).get('installed', [])
+    if not expected:
+        return None
+
+    skills_dir = Path('.claude/skills')
+    if not skills_dir.is_dir():
+        return f'Skills directory missing — run `flydocs sync`'
+
+    # Check for installed directories
+    try:
+        installed = {d.name for d in skills_dir.iterdir() if d.is_dir()}
+    except OSError:
+        return None
+
+    expected_set = set(expected)
+    missing = expected_set - installed
+    unexpected = installed - expected_set
+
+    warnings: list[str] = []
+    if missing:
+        warnings.append(f'Missing skills: {", ".join(sorted(missing))} — run `flydocs sync`')
+    if unexpected:
+        warnings.append(f'Unexpected skills: {", ".join(sorted(unexpected))}')
+
+    return ' | '.join(warnings) if warnings else 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)
+
+    freshness_v2 = get_config_freshness_v2()
+    if freshness_v2:
+        parts.append(freshness_v2)
+
+    skills_warning = check_skills_manifest()
+    if skills_warning:
+        parts.append(skills_warning)
+
+    if not parts:
+        print('{}')
+        sys.exit(0)
+
+    output = {
+        "hookSpecificOutput": {
+            "additionalContext": " | ".join(parts)
+        }
+    }
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/template/.claude/hooks/stop-gate.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: stop-gate.py
+Triggered: Stop (every time the agent finishes responding)
+Purpose: Gate agent completion on workflow state — blocks finish if issue
+         is still In Progress, warns if acceptance criteria are incomplete.
+
+Exit codes:
+  0 - Allow stop (optional JSON output parsed)
+  2 - Block stop (stderr shown to Claude as instruction)
+"""
+
+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}] [stop-gate] {message}\n')
+    except (OSError, IOError):
+        pass
+
+ISSUE_ID_PATTERN = re.compile(r"[A-Z]+-[0-9]+")
+CHECKBOX_DONE = re.compile(r"- \[x\]", re.IGNORECASE)
+CHECKBOX_ALL = re.compile(r"- \[[ x]\]", re.IGNORECASE)
+
+
+def read_file_safe(path):
+    """Read file contents, returning None on any error."""
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except (OSError, ValueError):
+        return None
+
+
+def extract_issue_id(text):
+    """Extract first issue ID matching PROJ-123 pattern."""
+    match = ISSUE_ID_PATTERN.search(text)
+    return match.group(0) if match else None
+
+
+def main():
+    # -- Parse stdin --
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        input_data = {}
+
+    # -- Loop guard: if the hook itself triggered this stop, exit cleanly --
+    if input_data.get("stop_hook_active"):
+        sys.exit(0)
+
+    # -- Resolve working directory --
+    cwd = input_data.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR", "")
+    if not cwd:
+        sys.exit(0)
+
+    try:
+        os.chdir(cwd)
+    except OSError:
+        sys.exit(0)
+
+    session_dir = Path(".flydocs/session")
+
+    # -- Check for active focus --
+    focus_text = read_file_safe(session_dir / "focus.md")
+    if not focus_text:
+        sys.exit(0)
+
+    issue_id = extract_issue_id(focus_text)
+    if not issue_id:
+        sys.exit(0)
+
+    # -- Read current status --
+    status_text = read_file_safe(session_dir / "status")
+    if not status_text:
+        sys.exit(0)
+
+    status = status_text.strip().upper()
+    debug_log(f"Issue {issue_id} status={status}")
+
+    # -- READY: warn that transition to IMPLEMENTING was missed --
+    if status == "READY":
+        # Check if any code edits happened (heuristic: git has uncommitted changes)
+        try:
+            import subprocess
+            result = subprocess.run(
+                ["git", "diff", "--quiet"], capture_output=True, timeout=5
+            )
+            has_changes = result.returncode != 0
+        except (FileNotFoundError, subprocess.TimeoutExpired, subprocess.SubprocessError):
+            has_changes = False
+
+        if has_changes:
+            msg = (
+                "Issue {} is still in READY but code changes were made. "
+                "Transition to IMPLEMENTING before continuing:\n"
+                "  python3 .claude/skills/flydocs-workflow/scripts/issues.py "
+                "transition {} IMPLEMENTING \"Starting implementation\""
+            ).format(issue_id, issue_id)
+            sys.stderr.write(msg)
+            sys.exit(2)
+
+    # -- IMPLEMENTING: block completion --
+    if status == "IMPLEMENTING":
+        msg = (
+            "Issue {} is still In Progress. "
+            "Transition to Review before finishing:\n"
+            "  python3 .claude/skills/flydocs-workflow/scripts/issues.py "
+            "transition {} REVIEW \"Implementation complete\""
+        ).format(issue_id, issue_id)
+        sys.stderr.write(msg)
+        sys.exit(2)
+
+    # -- REVIEW: block on incomplete acceptance criteria --
+    if status == "REVIEW":
+        ac_text = read_file_safe(session_dir / "acceptance-criteria.md")
+        if ac_text:
+            total = len(CHECKBOX_ALL.findall(ac_text))
+            done = len(CHECKBOX_DONE.findall(ac_text))
+            if total > 0 and done < total:
+                msg = (
+                    "Issue {}: {}/{} acceptance criteria checked. "
+                    "All AC must be verified before completion. "
+                    "Update the issue description with checked criteria:\n"
+                    "  python3 .claude/skills/flydocs-workflow/scripts/issues.py "
+                    "description {} --text \"<updated description with checked AC>\""
+                ).format(issue_id, done, total, issue_id)
+                sys.stderr.write(msg)
+                sys.exit(2)
+
+    # -- BLOCKED: inform that issue needs unblocking --
+    if status == "BLOCKED":
+        result = {
+            "hookSpecificOutput": {
+                "additionalContext": (
+                    "Issue {} is BLOCKED. Resolve the blocker before continuing, "
+                    "then transition back to IMPLEMENTING."
+                ).format(issue_id)
+            }
+        }
+        print(json.dumps(result))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/settings.json

@@ -2,11 +2,11 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Bash",
+        "matcher": "Bash|Edit|Write",
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/auto-approve.py",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-approve.py",
             "timeout": 5
           }
         ]
@@ -18,10 +18,25 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/post-edit.py",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit.py",
             "timeout": 30
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-pr-check.py",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-transition-check.py",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -29,7 +44,29 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/prompt-submit.py",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/prompt-submit.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-gate.py",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-start.py",
             "timeout": 10
           }
         ]

package/template/.claude/skills/README.md

@@ -11,16 +11,12 @@
 Owned and maintained by FlyDocs. May include executable scripts and premium
 functionality gated via API relay.
 
-| Skill               | Category         | Purpose                                                 |
-| ------------------- | ---------------- | ------------------------------------------------------- |
-| `flydocs-workflow`  | Core             | Lifecycle stages, session management, comment templates |
-| `flydocs-local`     | Mechanism (free) | File-based issue management                             |
-| `flydocs-cloud`     | Mechanism (paid) | Linear/provider issue management via API                |
-| `flydocs-context7`  | Core             | Library documentation lookup via Context7 API           |
-| `flydocs-figma`     | Premium          | Design extraction from Figma                            |
-| `flydocs-estimates` | Premium          | AI token/labor cost estimation                          |
+| Skill              | Purpose                                                                      |
+| ------------------ | ---------------------------------------------------------------------------- |
+| `flydocs-workflow` | Unified skill — lifecycle, issues, projects, Figma, estimates, context graph |
 
-Only one mechanism skill is active at a time. Determined by `tier` in `.flydocs/config.json`.
+All functionality consolidated into a single skill. Tier (local vs cloud) is
+auto-detected from `.flydocs/config.json` — no separate mechanism skills.
 
 ### Unprefixed — Community Skills
 
@@ -101,8 +97,8 @@ The body serves as a **compressed index** — not a documentation dump. Target ~
 ```markdown
 # Skill Name
 
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for
-[domain]. Read the relevant section before acting.
+Use this skill when performing [domain]-specific operations.
+For general coding, skip this — just write code.
 
 ## Key Rules (always apply)
 
@@ -191,12 +187,13 @@ CLAUDE.md and AGENTS.md between markers:
 
 ## Skills Index
 
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
+Consult the workflow skill for **issue operations and status transitions only**.
+For general coding tasks, skip this — just write code.
 
-| Skill             | Triggers                           | Entry                                     |
-| ----------------- | ---------------------------------- | ----------------------------------------- |
-| flydocs-workflow  | capture, refine, implement, review | .claude/skills/flydocs-workflow/SKILL.md  |
-| typescript-strict | TypeScript, type error, any type   | .claude/skills/typescript-strict/SKILL.md |
+| Skill             | Triggers                                      | Entry                                     |
+| ----------------- | --------------------------------------------- | ----------------------------------------- |
+| flydocs-workflow  | create issue, transition, assign, close issue | .claude/skills/flydocs-workflow/SKILL.md  |
+| typescript-strict | TypeScript, type error, any type              | .claude/skills/typescript-strict/SKILL.md |
 
 <!-- flydocs:skills-manifest:end -->
 ```
@@ -257,17 +254,18 @@ For detailed patterns, see `reference/patterns.md`.
 
 ---
 
-## Mechanism Contract
+## Unified Dispatcher Model
 
-Both mechanism skills (`flydocs-local`, `flydocs-cloud`) implement the same
-script interface, making the backend swap transparent:
+All operations route through grouped dispatcher scripts in
+`flydocs-workflow/scripts/`. The unified client (`flydocs_api.py`) auto-detects
+tier from `.flydocs/config.json` — scripts never check tier directly.
 
-**Shared contract:**
-`create_issue.py`, `transition.py`, `comment.py`, `list_issues.py`,
-`get_issue.py`, `assign.py`, `update_description.py`
-
-**Cloud-only extensions:**
-`update_issue.py`, `project_update.py`, `estimate.py`, `priority.py`, `link.py`, cycle/milestone management.
+| Dispatcher     | Operations                                             |
+| -------------- | ------------------------------------------------------ |
+| `issues.py`    | create, get, list, transition, assign, update, comment |
+| `projects.py`  | list-projects, create-project, milestones, cycles      |
+| `workspace.py` | validate, labels, statuses, teams, config, identity    |
+| `session.py`   | project-update, status-summary                         |
 
 ---