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

package/template/.claude/skills/flydocs-context7/scripts/context7.py

@@ -1,293 +0,0 @@
-#!/usr/bin/env python3
-"""Context7 API client for fetching library documentation.
-
-Queries the Context7 REST API to search for libraries and retrieve
-LLM-ready documentation. Replaces the Context7 MCP server with a
-lightweight script that follows the FlyDocs mechanism pattern.
-
-Usage:
-    python3 .claude/skills/flydocs-context7/scripts/context7.py \\
-        search <library_name> [query]
-
-    python3 .claude/skills/flydocs-context7/scripts/context7.py \\
-        docs <library_id> <query> [--type txt|json] [--tokens N]
-"""
-
-import argparse
-import json
-import os
-import sys
-import urllib.error
-import urllib.parse
-import urllib.request
-from pathlib import Path
-
-BASE_URL = "https://context7.com/api/v2"
-DEFAULT_TIMEOUT = 10
-DEFAULT_TOKENS = 5000
-
-
-# --- Helpers ---
-
-
-def fail(message):
-    """Print error to stderr and exit 1."""
-    print(message, file=sys.stderr)
-    sys.exit(1)
-
-
-def output_json(data):
-    """Print JSON to stdout."""
-    print(json.dumps(data, indent=2))
-
-
-def find_project_root(start=None):
-    """Walk up from start (or script location) to find the directory containing .flydocs/."""
-    current = Path(start) if start else Path(__file__).resolve().parent
-    for parent in [current] + list(current.parents):
-        if (parent / ".flydocs").is_dir():
-            return parent
-    return None
-
-
-def read_env_file(root):
-    """Read .env file at project root and return a dict of key=value pairs."""
-    env_path = root / ".env"
-    if not env_path.is_file():
-        return {}
-
-    env_vars = {}
-    try:
-        with open(env_path, "r", encoding="utf-8") as f:
-            for line in f:
-                line = line.strip()
-                # Skip empty lines and comments
-                if not line or line.startswith("#"):
-                    continue
-                if "=" not in line:
-                    continue
-                key, _, value = line.partition("=")
-                key = key.strip()
-                value = value.strip()
-                # Strip surrounding quotes if present
-                if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
-                    value = value[1:-1]
-                env_vars[key] = value
-    except OSError:
-        pass
-
-    return env_vars
-
-
-def resolve_api_key(args_key):
-    """Resolve the API key from flag, env var, or .env file. Returns None if unavailable."""
-    # 1. Explicit flag
-    if args_key:
-        return args_key
-
-    # 2. Environment variable
-    env_key = os.environ.get("CONTEXT7_API_KEY")
-    if env_key:
-        return env_key
-
-    # 3. .env file at project root
-    root = find_project_root()
-    if root:
-        env_vars = read_env_file(root)
-        dotenv_key = env_vars.get("CONTEXT7_API_KEY")
-        if dotenv_key:
-            return dotenv_key
-
-    # 4. Anonymous (no key)
-    return None
-
-
-def api_request(path, params, api_key=None):
-    """Make a GET request to the Context7 API and return parsed response data.
-
-    Handles HTTP errors, timeouts, and network failures with clear messages.
-    """
-    query_string = urllib.parse.urlencode(params)
-    url = f"{BASE_URL}/{path}?{query_string}"
-
-    request = urllib.request.Request(url)
-    request.add_header("User-Agent", "flydocs-context7/1.0")
-
-    if api_key:
-        request.add_header("Authorization", f"Bearer {api_key}")
-
-    try:
-        with urllib.request.urlopen(request, timeout=DEFAULT_TIMEOUT) as response:
-            body = response.read().decode("utf-8")
-            content_type = response.headers.get("Content-Type", "")
-            if "application/json" in content_type:
-                return json.loads(body)
-            return body
-    except urllib.error.HTTPError as e:
-        if e.code == 429:
-            fail("Rate limited by Context7 API. Wait a moment and try again.")
-        body_text = ""
-        try:
-            body_text = e.read().decode("utf-8", errors="replace")
-        except Exception:
-            pass
-        fail(f"Context7 API error (HTTP {e.code}): {e.reason}\n{body_text}".strip())
-    except urllib.error.URLError as e:
-        if "timed out" in str(e.reason).lower():
-            fail("Context7 API request timed out (10s). The service may be slow or unavailable.")
-        fail(f"Cannot reach Context7 API. Check your network connection.\nDetails: {e.reason}")
-    except OSError as e:
-        fail(f"Network error connecting to Context7 API: {e}")
-
-
-# --- Commands ---
-
-
-def cmd_search(args):
-    """Search for libraries by name and optional query."""
-    params = {"libraryName": args.library_name}
-    if args.query:
-        params["query"] = args.query
-
-    api_key = resolve_api_key(args.key)
-    data = api_request("libs/search", params, api_key=api_key)
-
-    # Normalize response — API wraps results in {"results": [...]}
-    if isinstance(data, dict) and "results" in data:
-        results = data["results"]
-    elif isinstance(data, list):
-        results = data
-    else:
-        results = []
-
-    if args.type == "json" or args.type is None:
-        # Default for search is JSON
-        compact = []
-        for lib in results:
-            compact.append({
-                "id": lib.get("id", ""),
-                "name": lib.get("title", lib.get("name", "")),
-                "description": lib.get("description", ""),
-                "trustScore": lib.get("trustScore", 0),
-            })
-        output_json(compact)
-    else:
-        # txt format for search — one line per result
-        for lib in results:
-            name = lib.get("title", lib.get("name", "unknown"))
-            lib_id = lib.get("id", "")
-            desc = lib.get("description", "")
-            score = lib.get("trustScore", 0)
-            print(f"{lib_id}  {name}  (trust: {score})")
-            if desc:
-                print(f"  {desc}")
-            print()
-
-
-def cmd_docs(args):
-    """Fetch documentation for a specific library."""
-    params = {
-        "libraryId": args.library_id,
-        "query": args.query,
-    }
-
-    output_type = args.type if args.type else "txt"
-    params["type"] = output_type
-
-    if args.tokens:
-        params["tokens"] = str(args.tokens)
-
-    api_key = resolve_api_key(args.key)
-    data = api_request("context", params, api_key=api_key)
-
-    if output_type == "json":
-        if isinstance(data, str):
-            # API returned text when we asked for JSON; wrap it
-            output_json({"content": data})
-        else:
-            output_json(data)
-    else:
-        # txt — print directly
-        if isinstance(data, str):
-            print(data)
-        elif isinstance(data, dict):
-            content = data.get("content", data.get("text", ""))
-            if content:
-                print(content)
-            else:
-                output_json(data)
-        else:
-            output_json(data)
-
-
-# --- Main ---
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Context7 API client — search libraries and fetch documentation"
-    )
-    parser.add_argument(
-        "--key", type=str, default=None,
-        help="API key override (default: CONTEXT7_API_KEY env var or .env file)"
-    )
-
-    subparsers = parser.add_subparsers(dest="command", required=True)
-
-    # search subcommand
-    search_parser = subparsers.add_parser(
-        "search",
-        help="Search for libraries by name"
-    )
-    search_parser.add_argument(
-        "library_name",
-        help="Library name to search for (e.g., 'react', 'next.js')"
-    )
-    search_parser.add_argument(
-        "query", nargs="?", default=None,
-        help="Optional search query to refine results"
-    )
-    search_parser.add_argument(
-        "--type", choices=["txt", "json"], default=None,
-        help="Output format (default: json for search)"
-    )
-    search_parser.add_argument(
-        "--tokens", type=int, default=DEFAULT_TOKENS,
-        help=f"Max tokens budget hint (default: {DEFAULT_TOKENS})"
-    )
-
-    # docs subcommand
-    docs_parser = subparsers.add_parser(
-        "docs",
-        help="Fetch documentation for a library"
-    )
-    docs_parser.add_argument(
-        "library_id",
-        help="Library ID from search results (e.g., '/vercel/next.js')"
-    )
-    docs_parser.add_argument(
-        "query",
-        help="Documentation query (e.g., 'server components', 'routing')"
-    )
-    docs_parser.add_argument(
-        "--type", choices=["txt", "json"], default=None,
-        help="Output format (default: txt for docs)"
-    )
-    docs_parser.add_argument(
-        "--tokens", type=int, default=DEFAULT_TOKENS,
-        help=f"Max tokens budget hint (default: {DEFAULT_TOKENS})"
-    )
-
-    args = parser.parse_args()
-
-    if args.command == "search":
-        cmd_search(args)
-    elif args.command == "docs":
-        cmd_docs(args)
-    else:
-        parser.print_help()
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()

package/template/.claude/skills/flydocs-estimates/SKILL.md

@@ -1,384 +0,0 @@
----
-name: flydocs-estimates
-description: "FlyDocs premium: Estimates token usage and API costs for AI development tasks. Apply when refining issues, activating work, or when user asks about costs. v1.0: Guidance-only. Future: Scripts via API relay for premium functionality."
-triggers:
-  - estimate
-  - cost
-  - token usage
-  - API cost
-  - labor estimate
-  - sizing
-  - effort
----
-
-# FlyDocs Estimates
-
-> **Purpose**: Estimate token usage and API costs for AI-driven development tasks before implementation begins.
-
----
-
-## Opt-In Feature
-
-**This skill is disabled by default.** To enable, set in `.flydocs/config.json`:
-
-```json
-{
-  "aiLabor": {
-    "enabled": true
-  }
-}
-```
-
-### Before Using This Skill
-
-```
-□ 1. CHECK config: Read .flydocs/config.json
-□ 2. IF aiLabor.enabled !== true:
-     → DO NOT apply any rules from this skill
-     → DO NOT warn about missing estimates
-     → DO NOT add estimate sections to issues
-     → Proceed with standard workflow
-□ 3. IF aiLabor.enabled === true:
-     → Apply all rules below
-```
-
-**When disabled**: This skill is completely silent. No warnings, no prompts, no estimate tracking.
-
----
-
-## Overview
-
-This skill enables agents to:
-1. **Analyze specs** to predict token consumption
-2. **Calculate cost ranges** based on provider pricing
-3. **Track actuals** for calibration over time
-4. **Compare** Human vs AI vs Hybrid cost projections
-
----
-
-## When to Use (Only if enabled)
-
-| Trigger | Action |
-|---------|--------|
-| `/refine [spec]` | Calculate estimate, add to issue |
-| `/activate [spec]` | Validate estimate exists; if missing, offer to calculate; warn on high estimates |
-| `/implement [spec]` | Show estimate in checklist if present |
-| `/close [spec]` | Record actuals, calculate variance |
-| Implementation complete | Estimate tokens used, update actuals in issue |
-| User asks "how much will this cost?" | Run estimation |
-
-### Validation Flow (for /activate and /implement) — Only When Enabled
-
-```
-1. Read issue description
-2. Search for "## AI Effort Estimate" section
-3. IF missing:
-   → OFFER: "Would you like me to calculate an AI Effort Estimate?"
-   → IF yes: Run estimation, update description
-   → IF no: Proceed normally
-4. IF present but has placeholders ([X]k):
-   → OFFER: "Estimate exists but incomplete. Fill it now?"
-5. IF estimate exceeds thresholds:
-   → tokens > 200k OR cost > $5: Show warning
-   → cost > $10: Require explicit approval
-6. Continue with activation/implementation
-```
-
----
-
-## Estimation Formula
-
-```
-estimated_tokens = base_tokens × scope_mult × novelty_mult × clarity_mult × codebase_mult
-
-Where:
-  base_tokens     = task type baseline (see table below)
-  scope_mult      = 0.5 (S) / 1.0 (M) / 2.0 (L) / 4.0 (XL)
-  novelty_mult    = 0.7 (existing pattern) / 1.2 (partial new) / 2.0 (greenfield)
-  clarity_mult    = 0.8 (well-defined) / 1.5 (needs discovery) / 2.5 (exploratory)
-  codebase_mult   = 0.8 (simple) / 1.0 (moderate) / 1.5 (complex)
-
-Confidence Range:
-  low_estimate    = estimated_tokens × 0.6
-  high_estimate   = estimated_tokens × 2.5
-```
-
-### Base Tokens by Task Type
-
-| Task Type | Base Tokens | Rationale |
-|-----------|-------------|-----------|
-| **feature** | 40,000 | Full cycle: plan, implement, iterate, review |
-| **bug** | 20,000 | Investigation + targeted fix |
-| **chore** | 10,000 | Usually straightforward |
-| **idea** | 5,000 | Quick exploration only |
-
----
-
-## Scoring Multipliers
-
-### Scope (from Complexity field)
-
-| Complexity | Multiplier | Indicators |
-|------------|------------|------------|
-| **S** | 0.5 | 1-3 acceptance criteria, single file |
-| **M** | 1.0 | 4-6 acceptance criteria, 2-5 files |
-| **L** | 2.0 | 7-10 acceptance criteria, multiple modules |
-| **XL** | 4.0 | 10+ criteria, cross-cutting changes |
-
-### Novelty (from Technical Notes)
-
-| Level | Multiplier | Indicators |
-|-------|------------|------------|
-| **existing-pattern** | 0.7 | "Follow existing X pattern", references similar code |
-| **partial-new** | 1.2 | Mix of new + existing, some exploration needed |
-| **greenfield** | 2.0 | New patterns, no precedent in codebase |
-
-### Clarity (from Acceptance Criteria quality)
-
-| Level | Multiplier | Indicators |
-|-------|------------|------------|
-| **well-defined** | 0.8 | All criteria specific & testable |
-| **needs-discovery** | 1.5 | Some vague criteria, needs investigation |
-| **exploratory** | 2.5 | Research-heavy, unclear solution |
-
-### Codebase Complexity (from `stack.md`)
-
-| Level | Multiplier | Indicators |
-|-------|------------|------------|
-| **simple** | 0.8 | Small codebase, clear patterns |
-| **moderate** | 1.0 | Standard project, documented patterns |
-| **complex** | 1.5 | Large codebase, multiple integrations |
-
----
-
-## Cost Calculation
-
-```
-cost = tokens × (input_rate × input_ratio + output_rate × output_ratio)
-
-Where:
-  input_rate   = provider cost per 1M input tokens
-  output_rate  = provider cost per 1M output tokens
-  input_ratio  = 0.70 (typical for development)
-  output_ratio = 0.30 (typical for development)
-```
-
-See `references/provider-costs.md` for current pricing.
-
----
-
-## Issue Template Section
-
-Add this to Linear issue description during `/refine`:
-
-```markdown
----
-
-## AI Effort Estimate
-
-### Sizing Factors
-
-| Factor | Value | Multiplier |
-|--------|-------|------------|
-| **Task Type** | [feature/bug/chore] | base: [X]k |
-| **Scope** | [S/M/L/XL] | ×[0.5/1.0/2.0/4.0] |
-| **Novelty** | [existing/partial/greenfield] | ×[0.7/1.2/2.0] |
-| **Clarity** | [defined/discovery/exploratory] | ×[0.8/1.5/2.5] |
-| **Codebase** | [simple/moderate/complex] | ×[0.8/1.0/1.5] |
-
-### Estimate
-
-**Provider**: [Claude Sonnet 4 / GPT-4o / etc.]  
-**Calculated Tokens**: ~[X]k  
-**Confidence**: ±[40-60]%  
-**Token Range**: [low]k - [high]k  
-**Cost Range**: $[low] - $[high]
-
-### Comparison
-
-| Approach | Est. Cost | Est. Time | Best For |
-|----------|-----------|-----------|----------|
-| **Full AI** | $[X] | [X] hrs | Well-defined, pattern-matching |
-| **AI-Assisted** | $[X] + [X]hrs human | [X] hrs | Complex decisions |
-| **Human-Led** | $[X] (review) + [X]hrs | [X] hrs | Novel architecture |
-
----
-```
-
----
-
-## Recording Actuals (on /close)
-
-Add to issue comment on completion:
-
-```markdown
-## AI Effort Actuals
-
-**Estimated Tokens**: [X]k  
-**Actual Tokens**: [X]k (from session/API logs if available)  
-**Variance**: [+/-X]% [under/over]  
-**Actual Cost**: $[X]
-
-### Variance Notes
-- [What drove the variance - blockers, scope change, retries, etc.]
-- [Lessons for future estimation]
-
-### Calibration Data
-- Task Type: [feature]
-- Final Complexity: [M]
-- Novelty Actual: [partial-new]
-- Clarity Actual: [well-defined]
-```
-
----
-
-## Agent Instructions
-
-### During /refine (PM Agent)
-
-1. **Read the spec** completely
-2. **Identify task type** from labels (feature, bug, chore, idea)
-3. **Score each factor**:
-   - Count acceptance criteria → scope
-   - Check Technical Notes for patterns → novelty
-   - Assess criteria specificity → clarity
-   - Reference `stack.md` → codebase complexity
-4. **Calculate estimate** using formula
-5. **Look up provider costs** from `references/provider-costs.md` or `.flydocs/config.json`
-6. **Add estimate section** to issue description (replace placeholders with values)
-7. **If estimate exceeds threshold**, flag for human review:
-   - \> 200k tokens → Consider breaking down the issue
-   - \> $5 estimated → Confirm before proceeding
-8. **Include estimate in refine comment**: `AI Estimate: ~Xk tokens ($X-$X)`
-
-### During /activate (PM Agent)
-
-1. **Search issue description** for "## AI Effort Estimate"
-2. **If missing**:
-   - WARN: "⚠️ This issue is missing an AI Effort Estimate."
-   - ASK: "Would you like me to calculate one now before activation?"
-   - If yes → Calculate and add to description
-   - If no → Proceed but note: "No baseline for actuals comparison"
-3. **If present but incomplete** (still has `[X]k` placeholders):
-   - OFFER: "AI Effort Estimate exists but has placeholder values. Complete it now?"
-4. **If present and exceeds thresholds**:
-   - \> 200k tokens or \> $5 → Show warning, ask for confirmation
-   - \> $10 → Require explicit "yes proceed" before continuing
-5. **Include in activation comment**: `AI Effort: ~Xk tokens ($X-$X)`
-
-### During /implement (Implementation Agent)
-
-1. **Search issue description** for "## AI Effort Estimate"
-2. **If missing**:
-   - WARN: "⚠️ Missing AI Effort Estimate - tracking actuals won't have comparison baseline."
-   - OFFER: "Calculate estimate before starting implementation?"
-   - If yes → Calculate estimate, update description
-   - If no → Proceed with warning
-3. **If present**:
-   - Show estimate in implementation checklist
-   - Note: "Tracking against estimate of ~Xk tokens"
-4. **During implementation**:
-   - Keep rough mental model of token usage
-   - Note if work is going significantly over estimate (scope discovery, retries)
-
-### On Implementation Complete (Implementation Agent)
-
-1. **Estimate actual tokens used**:
-   - Rough method: conversation turns × ~2k tokens/turn
-   - Or estimate based on files changed, complexity of work
-2. **Update AI Effort Estimate section** in issue description:
-   - Fill "Actual Tokens" field
-   - Calculate variance percentage
-   - Add notes on variance drivers
-3. **Include in completion comment**: `AI Effort: ~Xk actual (estimated Xk, +/-X% variance)`
-
-### During /close (PM Agent)
-
-1. **Verify actuals were recorded** (from implementation completion)
-2. **If actuals missing**: Estimate based on issue activity/comments
-3. **Calculate final variance** from estimate
-4. **Add final actuals to issue** if not already present
-5. **Log patterns for calibration**:
-   - Which factor assessments were off?
-   - What should be adjusted for similar future work?
-6. **Include in close comment**: `Final AI Effort: ~Xk tokens (+/-X% from estimate)`
-
----
-
-## Configuration
-
-In `.flydocs/config.json`:
-
-```json
-{
-  "aiLabor": {
-    "enabled": false,
-    "defaultProvider": "claude-sonnet-4",
-    "thresholds": {
-      "warnTokens": 200000,
-      "warnCost": 5.00,
-      "requireApproval": 10.00
-    },
-    "tracking": {
-      "recordActuals": true,
-      "calibrationEnabled": true
-    }
-  }
-}
-```
-
-**To enable**, change `"enabled": false` to `"enabled": true`.
-
-When enabled, the skill will:
-- Add AI Effort Estimate sections during `/refine`
-- Offer to calculate estimates during `/activate` and `/implement`
-- Track actuals on completion
-- Warn on high-cost estimates based on thresholds
-
----
-
-## Example Calculation
-
-**Spec**: "Add user profile photo upload"
-
-| Factor | Assessment | Value |
-|--------|------------|-------|
-| Type | Feature | 40k base |
-| Scope | M (5 criteria, ~4 files) | ×1.0 |
-| Novelty | Existing pattern (similar to doc upload) | ×0.7 |
-| Clarity | Well-defined (clear criteria) | ×0.8 |
-| Codebase | Moderate | ×1.0 |
-
-**Calculation**:
-```
-40,000 × 1.0 × 0.7 × 0.8 × 1.0 = 22,400 tokens
-
-Range: 13,440 - 56,000 tokens (±60% confidence)
-
-Cost (Claude Sonnet 4 @ $3/$15 per 1M):
-  Low:  13.4k × (0.7×$3 + 0.3×$15)/1M = $0.09
-  High: 56k × (0.7×$3 + 0.3×$15)/1M = $0.37
-```
-
-**Result**: ~22k tokens, $0.09 - $0.37 estimated cost
-
----
-
-## Related Skills
-
-- `flydocs-workflow` - For workflow lifecycle and issue operations
-- `spec-templates` - Template structure reference
-
----
-
-## Calibration Over Time
-
-Track estimates vs actuals to improve accuracy:
-
-1. **Log all estimates and actuals** in issue comments
-2. **Review monthly** for patterns:
-   - Which task types are consistently over/under?
-   - Which factors need adjustment?
-3. **Adjust multipliers** based on your codebase patterns
-4. **Document adjustments** in `.flydocs/knowledge/notes/`
-