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

package/template/.flydocs/scripts/skill_manager.py

@@ -1,541 +0,0 @@
-#!/usr/bin/env python3
-"""FlyDocs Skill Manager — search, add, remove, and list community skills.
-
-Usage:
-    python3 skill_manager.py search <keyword>
-    python3 skill_manager.py add <source>
-    python3 skill_manager.py remove <name>
-    python3 skill_manager.py list
-
-Source formats for add:
-    Known name:      react-best-practices
-    Repo reference:  vercel-labs/agent-skills:react-best-practices
-    GitHub URL:      https://github.com/owner/repo/tree/main/skills/name
-"""
-
-import argparse
-import json
-import os
-import re
-import shutil
-import subprocess
-import sys
-import urllib.error
-import urllib.request
-
-
-RED = "\033[0;31m"
-GREEN = "\033[0;32m"
-BLUE = "\033[0;34m"
-YELLOW = "\033[1;33m"
-CYAN = "\033[0;36m"
-NC = "\033[0m"
-
-# ─── Curated community skills catalog ────────────────────────────────────────
-# Mirrors install.sh COMMUNITY_SKILLS_MAP. Designed to swap with real API later.
-
-COMMUNITY_SKILLS = [
-    {
-        "name": "react-best-practices",
-        "repo": "vercel-labs/agent-skills",
-        "description": "React/Next.js performance optimization (40+ rules from Vercel)",
-        "tags": ["react", "nextjs", "performance", "components"],
-    },
-    {
-        "name": "web-design-guidelines",
-        "repo": "vercel-labs/agent-skills",
-        "description": "UI/UX accessibility and design patterns (100+ rules)",
-        "tags": ["design", "accessibility", "ux", "ui", "nextjs", "web"],
-    },
-    {
-        "name": "convex-best-practices",
-        "repo": "waynesutton/convexskills",
-        "description": "Convex database patterns and best practices",
-        "tags": ["convex", "database", "backend"],
-    },
-    {
-        "name": "convex-functions",
-        "repo": "waynesutton/convexskills",
-        "description": "Convex query/mutation/action patterns",
-        "tags": ["convex", "functions", "query", "mutation"],
-    },
-    {
-        "name": "tailwind-v4",
-        "repo": "blencorp/claude-code-kit",
-        "description": "Tailwind CSS v4 patterns and configuration",
-        "tags": ["tailwind", "css", "styling"],
-    },
-    {
-        "name": "clerk-auth",
-        "repo": "blencorp/claude-code-kit",
-        "description": "Clerk authentication patterns",
-        "tags": ["clerk", "auth", "authentication"],
-    },
-]
-
-
-# ─── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def find_project_root():
-    """Find the project root by walking up to .flydocs/config.json."""
-    path = os.getcwd()
-    while True:
-        if os.path.isfile(os.path.join(path, ".flydocs", "config.json")):
-            return path
-        parent = os.path.dirname(path)
-        if parent == path:
-            break
-        path = parent
-    return os.getcwd()
-
-
-def load_config(root):
-    """Load .flydocs/config.json."""
-    config_path = os.path.join(root, ".flydocs", "config.json")
-    if not os.path.isfile(config_path):
-        print(f"{RED}✗{NC} No .flydocs/config.json found. Is FlyDocs installed?", file=sys.stderr)
-        sys.exit(1)
-    with open(config_path, "r", encoding="utf-8") as f:
-        return json.load(f)
-
-
-def save_config(root, config):
-    """Save .flydocs/config.json."""
-    config_path = os.path.join(root, ".flydocs", "config.json")
-    with open(config_path, "w", encoding="utf-8") as f:
-        json.dump(config, f, indent=2)
-        f.write("\n")
-
-
-def parse_frontmatter(text):
-    """Parse YAML frontmatter from a SKILL.md file.
-
-    Duplicated from generate_manifest.py — each script is self-contained.
-    """
-    match = re.match(r"^---\s*\n(.*?)\n---", text, re.DOTALL)
-    if not match:
-        return None
-
-    block = match.group(1)
-    result = {}
-    current_key = None
-    current_mode = None  # "scalar", "block", "list"
-    current_lines = []
-
-    for line in block.split("\n"):
-        key_match = re.match(r"^(\w[\w-]*):\s*(.*)", line)
-        if key_match and not line.startswith("  "):
-            if current_key is not None:
-                result[current_key] = _flush(current_mode, current_lines)
-
-            current_key = key_match.group(1)
-            value = key_match.group(2).strip()
-
-            if value in ("|", ">"):
-                current_mode = "block"
-                current_lines = []
-            elif value == "":
-                current_mode = "list"
-                current_lines = []
-            else:
-                current_mode = "scalar"
-                current_lines = [value.strip("\"'")]
-            continue
-
-        stripped = line.strip()
-        if current_key is not None:
-            if current_mode == "list" and stripped.startswith("- "):
-                current_lines.append(stripped[2:].strip().strip("\"'"))
-            elif current_mode == "block":
-                current_lines.append(line.lstrip())
-
-    if current_key is not None:
-        result[current_key] = _flush(current_mode, current_lines)
-
-    return result
-
-
-def _flush(mode, lines):
-    if mode == "scalar":
-        return lines[0] if lines else ""
-    elif mode == "list":
-        return lines
-    elif mode == "block":
-        return "\n".join(lines).strip()
-    return ""
-
-
-def is_platform_skill(name):
-    """Check if a skill name is platform-managed."""
-    return name.startswith("flydocs-")
-
-
-def regenerate_manifest(root):
-    """Run generate_manifest.py to update CLAUDE.md/AGENTS.md."""
-    script = os.path.join(root, ".flydocs", "scripts", "generate_manifest.py")
-    if not os.path.isfile(script):
-        print(f"{YELLOW}⚠{NC} generate_manifest.py not found — skipping manifest update.")
-        return
-
-    try:
-        subprocess.run(
-            [sys.executable, script, "--root", root],
-            check=True,
-            capture_output=True,
-            text=True,
-        )
-        print(f"{GREEN}✓{NC} Regenerated skill manifest")
-    except subprocess.CalledProcessError as e:
-        print(f"{YELLOW}⚠{NC} Manifest regeneration failed: {e.stderr.strip()}")
-
-
-# ─── search ──────────────────────────────────────────────────────────────────
-
-
-def cmd_search(args):
-    """Search curated community skills catalog."""
-    keyword = args.keyword.lower()
-    matches = []
-
-    for skill in COMMUNITY_SKILLS:
-        searchable = f"{skill['name']} {skill['description']} {' '.join(skill['tags'])}".lower()
-        if keyword in searchable:
-            matches.append(skill)
-
-    if not matches:
-        print(f"\n  No skills found matching '{args.keyword}'.")
-        print(f"  Browse more at: https://skills.sh/\n")
-        return
-
-    print(f"\n  Found {len(matches)} skill(s) matching '{args.keyword}':\n")
-    for skill in matches:
-        print(f"  {CYAN}{skill['name']}{NC}")
-        print(f"    {skill['description']}")
-        print(f"    Source: {skill['repo']}")
-        print(f"    Tags: {', '.join(skill['tags'])}")
-        print()
-
-    print(f"  Install with: flydocs skills add <name>")
-    print(f"  Browse more at: https://skills.sh/\n")
-
-
-# ─── add ─────────────────────────────────────────────────────────────────────
-
-
-def parse_source(source):
-    """Parse a skill source into (repo, skill_name).
-
-    Accepts:
-      - Known name: "react-best-practices"
-      - Repo reference: "vercel-labs/agent-skills:react-best-practices"
-      - GitHub URL: "https://github.com/owner/repo/tree/main/skills/name"
-    """
-    # GitHub URL
-    url_match = re.match(
-        r"https?://github\.com/([^/]+/[^/]+)/tree/[^/]+/skills/([^/]+)/?$",
-        source,
-    )
-    if url_match:
-        return url_match.group(1), url_match.group(2)
-
-    # Repo reference (owner/repo:skill-name)
-    if ":" in source:
-        repo, name = source.rsplit(":", 1)
-        if "/" in repo:
-            return repo, name
-
-    # Known name — lookup in curated catalog
-    for skill in COMMUNITY_SKILLS:
-        if skill["name"] == source:
-            return skill["repo"], skill["name"]
-
-    print(f"{RED}✗{NC} Unknown skill: {source}", file=sys.stderr)
-    print(f"  Try: flydocs skills search <keyword>", file=sys.stderr)
-    print(f"  Or use full reference: owner/repo:skill-name", file=sys.stderr)
-    sys.exit(1)
-
-
-def download_skill_tree(repo, skill_name, target_dir):
-    """Download a skill directory tree via GitHub Contents API (recursive)."""
-    api_url = f"https://api.github.com/repos/{repo}/contents/skills/{skill_name}"
-
-    def fetch_json(url):
-        req = urllib.request.Request(url, headers={"User-Agent": "flydocs-cli"})
-        try:
-            with urllib.request.urlopen(req, timeout=15) as resp:
-                return json.loads(resp.read().decode("utf-8"))
-        except urllib.error.HTTPError as e:
-            if e.code == 404:
-                return None
-            raise
-
-    def download_recursive(url, dest_dir):
-        items = fetch_json(url)
-        if items is None:
-            return False
-
-        # Single file response comes as dict, directory as list
-        if isinstance(items, dict):
-            items = [items]
-
-        os.makedirs(dest_dir, exist_ok=True)
-
-        for item in items:
-            dest_path = os.path.join(dest_dir, item["name"])
-            if item["type"] == "file":
-                if item.get("download_url"):
-                    req = urllib.request.Request(
-                        item["download_url"],
-                        headers={"User-Agent": "flydocs-cli"},
-                    )
-                    with urllib.request.urlopen(req, timeout=15) as resp:
-                        content = resp.read()
-                    with open(dest_path, "wb") as f:
-                        f.write(content)
-            elif item["type"] == "dir":
-                download_recursive(item["url"], dest_path)
-
-        return True
-
-    return download_recursive(api_url, target_dir)
-
-
-def cmd_add(args):
-    """Install a community skill."""
-    root = find_project_root()
-    config = load_config(root)
-    source = args.source
-
-    # Platform guard (check before parse_source which would reject as "unknown")
-    if is_platform_skill(source):
-        print(f"{RED}✗{NC} Cannot install platform skill '{source}'.")
-        print(f"  Platform skills (flydocs-*) are managed by the installer.")
-        sys.exit(1)
-
-    repo, skill_name = parse_source(source)
-
-    # Platform guard (for repo references that resolve to a flydocs-* name)
-    if is_platform_skill(skill_name):
-        print(f"{RED}✗{NC} Cannot install platform skill '{skill_name}'.")
-        print(f"  Platform skills (flydocs-*) are managed by the installer.")
-        sys.exit(1)
-
-    # Already installed check
-    skills_dir = os.path.join(root, ".claude", "skills", skill_name)
-    if os.path.isdir(skills_dir):
-        print(f"{YELLOW}⚠{NC} Skill '{skill_name}' is already installed.")
-        print(f"  Remove first: flydocs skills remove {skill_name}")
-        sys.exit(1)
-
-    print(f"\n{BLUE}→{NC} Installing {CYAN}{skill_name}{NC} from {repo}...\n")
-
-    # Download
-    try:
-        success = download_skill_tree(repo, skill_name, skills_dir)
-    except Exception as e:
-        if os.path.isdir(skills_dir):
-            shutil.rmtree(skills_dir)
-        print(f"{RED}✗{NC} Download failed: {e}")
-        sys.exit(1)
-
-    if not success:
-        if os.path.isdir(skills_dir):
-            shutil.rmtree(skills_dir)
-        print(f"{RED}✗{NC} Skill not found at {repo}/skills/{skill_name}")
-        sys.exit(1)
-
-    # Validate SKILL.md exists
-    skill_md = os.path.join(skills_dir, "SKILL.md")
-    if not os.path.isfile(skill_md):
-        shutil.rmtree(skills_dir)
-        print(f"{RED}✗{NC} Invalid skill: SKILL.md not found.")
-        sys.exit(1)
-
-    # Validate frontmatter
-    with open(skill_md, "r", encoding="utf-8") as f:
-        content = f.read()
-
-    fm = parse_frontmatter(content)
-    if fm is None or not fm.get("name") or not fm.get("description"):
-        shutil.rmtree(skills_dir)
-        print(f"{RED}✗{NC} Invalid skill: SKILL.md missing required frontmatter (name, description).")
-        sys.exit(1)
-
-    if not fm.get("triggers"):
-        print(f"{YELLOW}⚠{NC} SKILL.md has no triggers — skill won't appear in manifest index.")
-
-    print(f"{GREEN}✓{NC} Downloaded skill files")
-
-    # Copy cursor-rule.mdc if present
-    cursor_rule = os.path.join(skills_dir, "cursor-rule.mdc")
-    if os.path.isfile(cursor_rule):
-        cursor_rules_dir = os.path.join(root, ".cursor", "rules")
-        os.makedirs(cursor_rules_dir, exist_ok=True)
-        dest = os.path.join(cursor_rules_dir, f"{skill_name}.mdc")
-        shutil.copy2(cursor_rule, dest)
-        print(f"{GREEN}✓{NC} Installed cursor rule")
-
-    # Update config.json skills.installed[]
-    installed = config.get("skills", {}).get("installed", [])
-    entry = f"{repo}/{skill_name}"
-    if entry not in installed:
-        installed.append(entry)
-        if "skills" not in config:
-            config["skills"] = {"installed": [], "custom": []}
-        config["skills"]["installed"] = installed
-        save_config(root, config)
-        print(f"{GREEN}✓{NC} Updated config.json")
-
-    # Regenerate manifest
-    regenerate_manifest(root)
-
-    print(f"\n{GREEN}✓{NC} Installed {CYAN}{skill_name}{NC}\n")
-
-
-# ─── remove ──────────────────────────────────────────────────────────────────
-
-
-def cmd_remove(args):
-    """Remove an installed community skill."""
-    root = find_project_root()
-    config = load_config(root)
-    skill_name = args.name
-
-    # Platform guard
-    if is_platform_skill(skill_name):
-        print(f"{RED}✗{NC} Cannot remove platform skill '{skill_name}'.")
-        print(f"  Platform skills (flydocs-*) are managed by the installer.")
-        sys.exit(1)
-
-    skills_dir = os.path.join(root, ".claude", "skills", skill_name)
-    if not os.path.isdir(skills_dir):
-        print(f"{RED}✗{NC} Skill '{skill_name}' is not installed.")
-        sys.exit(1)
-
-    # Remove skill directory
-    shutil.rmtree(skills_dir)
-    print(f"{GREEN}✓{NC} Removed skill directory")
-
-    # Remove cursor rule
-    cursor_rule = os.path.join(root, ".cursor", "rules", f"{skill_name}.mdc")
-    if os.path.isfile(cursor_rule):
-        os.remove(cursor_rule)
-        print(f"{GREEN}✓{NC} Removed cursor rule")
-
-    # Update config.json
-    installed = config.get("skills", {}).get("installed", [])
-    config["skills"]["installed"] = [
-        s for s in installed if not s.endswith(f"/{skill_name}")
-    ]
-    save_config(root, config)
-    print(f"{GREEN}✓{NC} Updated config.json")
-
-    # Regenerate manifest
-    regenerate_manifest(root)
-
-    print(f"\n{GREEN}✓{NC} Removed {CYAN}{skill_name}{NC}\n")
-
-
-# ─── list ────────────────────────────────────────────────────────────────────
-
-
-def cmd_list(args):
-    """List all installed skills with type and trigger count."""
-    root = find_project_root()
-    skills_dir = os.path.join(root, ".claude", "skills")
-
-    if not os.path.isdir(skills_dir):
-        print(f"\n  No skills installed.\n")
-        return
-
-    platform = []
-    community = []
-
-    for entry in sorted(os.listdir(skills_dir)):
-        skill_file = os.path.join(skills_dir, entry, "SKILL.md")
-        if not os.path.isfile(skill_file):
-            continue
-
-        with open(skill_file, "r", encoding="utf-8") as f:
-            content = f.read()
-
-        fm = parse_frontmatter(content)
-        name = fm.get("name", entry) if fm else entry
-        triggers = fm.get("triggers", []) if fm else []
-        if isinstance(triggers, str):
-            triggers = [t.strip() for t in triggers.split(",") if t.strip()]
-
-        info = {
-            "name": name,
-            "dir": entry,
-            "type": "platform" if is_platform_skill(entry) else "community",
-            "triggers": len(triggers),
-        }
-
-        if info["type"] == "platform":
-            platform.append(info)
-        else:
-            community.append(info)
-
-    total = len(platform) + len(community)
-    if total == 0:
-        print(f"\n  No skills installed.\n")
-        return
-
-    print(f"\n  {total} skill(s) installed:\n")
-
-    if platform:
-        print(f"  {YELLOW}Platform{NC}")
-        for s in platform:
-            print(f"    {CYAN}{s['name']}{NC} ({s['triggers']} triggers)")
-
-    if community:
-        if platform:
-            print()
-        print(f"  {YELLOW}Community{NC}")
-        for s in community:
-            print(f"    {CYAN}{s['name']}{NC} ({s['triggers']} triggers)")
-
-    print()
-
-
-# ─── main ────────────────────────────────────────────────────────────────────
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        prog="flydocs skills",
-        description="Manage FlyDocs skills — search, install, and remove community skills.",
-    )
-    sub = parser.add_subparsers(dest="command")
-
-    search_p = sub.add_parser("search", help="Search available community skills")
-    search_p.add_argument("keyword", help="Keyword to search for")
-
-    add_p = sub.add_parser("add", help="Install a community skill")
-    add_p.add_argument("source", help="Skill name, repo:name, or GitHub URL")
-
-    remove_p = sub.add_parser("remove", help="Remove an installed community skill")
-    remove_p.add_argument("name", help="Skill directory name")
-
-    sub.add_parser("list", help="List installed skills")
-
-    args = parser.parse_args()
-
-    if args.command is None:
-        parser.print_help()
-        sys.exit(1)
-
-    commands = {
-        "search": cmd_search,
-        "add": cmd_add,
-        "remove": cmd_remove,
-        "list": cmd_list,
-    }
-
-    commands[args.command](args)
-
-
-if __name__ == "__main__":
-    main()

package/template/.flydocs/templates/bug.md

@@ -1,166 +0,0 @@
-<!-- AGENT INSTRUCTIONS
-When creating or refining a bug issue:
-
-1. CONTEXT SECTION:
-   - Capture when/how the bug was discovered
-   - Assess user impact (how many affected, how severe)
-   - Note frequency (always, sometimes, specific conditions)
-
-2. BUG DESCRIPTION:
-   - Expected vs Actual must be crystal clear
-   - Steps to reproduce must be detailed enough for anyone to follow
-   - Include specific data conditions if relevant
-   - Note environment details (browser, OS, user role)
-
-3. ACCEPTANCE CRITERIA:
-   - "Fix Verification" should mirror the reproduction steps
-   - Include regression concerns (what else might break)
-   - Tests section should include regression test requirement
-
-4. TECHNICAL NOTES:
-   - Start with hypothesis if cause unknown
-   - Update "Confirmed Cause" after investigation
-   - Include specific file/function where bug exists
-   - Assess risk of the fix
-
-5. SEVERITY GUIDANCE:
-   - Critical: System unusable, data loss, security issue
-   - High: Major feature broken, no workaround
-   - Medium: Feature impaired but workaround exists
-   - Low: Minor issue, cosmetic, edge case
-
-Remove these instructions when creating the final issue.
--->
-
-## Context
-
-**When Discovered:** [Date or event when bug was found]
-**Discovered By:** [User, developer, automated test, etc.]
-**Impact:** [How this affects users - be specific about scope]
-**Frequency:** [Always | Sometimes | Rarely | Under specific conditions]
-
-[Additional context about the bug]
-
----
-
-## Bug Description
-
-### Expected Behavior
-[Describe what SHOULD happen - the correct behavior]
-
-### Actual Behavior
-[Describe what ACTUALLY happens - the broken behavior]
-
-### Steps to Reproduce
-1. [First action - be specific]
-2. [Second action - include any data/conditions needed]
-3. [Third action]
-4. [Observe the bug]
-
-### Environment
-- **Browser/Platform:** [Chrome, Safari, Mobile, etc.]
-- **OS:** [macOS, Windows, iOS, Android, etc.]
-- **User Role:** [Which user type experiences this]
-- **Data Conditions:** [Specific data state that triggers bug]
-
-### Screenshots/Evidence
-<!-- Add as attachments -->
-
----
-
-## Acceptance Criteria
-
-### Fix Verification
-- [ ] Bug no longer reproducible using original steps
-- [ ] Expected behavior now works correctly
-- [ ] Fix doesn't break related functionality
-- [ ] No new error messages or console errors
-
-### Tests
-- [ ] Regression test added to prevent recurrence
-- [ ] Related edge cases tested
-- [ ] All tests passing
-
-### Documentation
-- [ ] Root cause documented (if significant pattern)
-- [ ] Prevention notes added to knowledge base (if applicable)
-- [ ] N/A - No significant documentation needed
-
----
-
-## Technical Notes
-
-### Root Cause Analysis
-**Hypothesis:** [What you think is causing the bug]
-
-**Investigation Findings:**
-- [Finding 1 from debugging]
-- [Finding 2 from debugging]
-
-**Confirmed Cause:** [What's actually wrong - file, function, logic error]
-
-### Fix Approach
-[Describe the fix strategy - what needs to change]
-
-**Files to Modify:**
-- `path/to/file.tsx` - [What needs to change]
-
-**Risk Assessment:**
-- **Regression Risk:** Low | Medium | High
-- **Testing Required:** [What needs to be tested]
-
----
-
-## Dependencies
-
-**Related Systems:**
-- [System or feature where bug occurs]
-
-**Blocks:**
-- [Work that can't proceed until bug is fixed]
-- OR: Nothing blocked
-
-**Related Bugs:**
-- [Link to related bug if applicable]
-- OR: No related issues
-
----
-
-## AI Effort Estimate
-<!-- 
-AGENT: Fill this section during /refine using the flydocs-estimates skill.
-See .claude/skills/flydocs-estimates/SKILL.md for calculation details.
-Update Actuals section during /close for calibration.
--->
-
-### Sizing Factors
-
-| Factor | Value | Multiplier |
-|--------|-------|------------|
-| **Task Type** | bug | base: 20k |
-| **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]  
-**Calculated Tokens**: ~[X]k  
-**Confidence**: ±[40-60]%  
-**Token Range**: [low]k - [high]k  
-**Cost Range**: $[low] - $[high]
-
-### Actuals (fill on /close)
-**Actual Tokens**: [fill after completion]  
-**Variance**: [+/-X]% [under/over estimate]  
-**Notes**: [what drove variance - investigation time, fix complexity, retries]
-
----
-
-_Reported: YYYY-MM-DD_
-
-
-
-
-