ai-qakit 1.0.0

package/templates/.cursor/scripts/helper.py

@@ -0,0 +1,723 @@
+#!/usr/bin/env python3
+"""
+AI-DevKit Helper Command - All-in-one guide with dynamic command discovery.
+Scans .cursor/commands/ directory to build catalog at runtime.
+
+Usage:
+    python helper.py                      # Overview with quick start
+    python helper.py version              # Show AI-DevKit version
+    python helper.py fix                  # Category guide with workflow
+    python helper.py spec                 # Spec workflow guide
+    python helper.py spec:plan            # Command details
+    python helper.py debug login error    # Task recommendations
+    python helper.py component react      # Search (unknown words)
+    python helper.py frontend             # Frontend generation commands
+    python helper.py backend              # Backend generation commands
+
+Categories: fix, debug, scout, analyze, refactor, research, spec, spec-lite,
+            review, config, docs, frontend, backend, skill, create-test, version
+"""
+
+import sys
+import re
+import io
+from pathlib import Path
+
+# Fix Windows console encoding for Unicode characters
+if sys.platform == 'win32':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+
+
+# Output type markers for LLM presentation guidance
+# Format:  @OUTPUT_TYPE:<type>
+# Types:
+#   - comprehensive-docs: Full documentation, show verbatim + add context
+#   - category-guide: Workflow guide, show full + explain workflow
+#   - command-details: Single command, show + offer to run
+#   - search-results: Search matches, show + offer alternatives
+#   - task-recommendations: Task-based suggestions, explain reasoning
+OUTPUT_TYPES = {
+    "comprehensive-docs": "Show FULL output verbatim, then ADD helpful context, examples, and real-world tips",
+    "category-guide": "Show complete workflow, then ENHANCE with practical usage scenarios",
+    "command-details": "Show command info, then ADD usage examples and related commands",
+    "search-results": "Show all matches, then HELP user narrow down or explore",
+    "task-recommendations": "Show recommendations, then EXPLAIN why these fit and offer to start",
+}
+
+
+def emit_output_type(output_type: str) -> None:
+    """Emit output type marker for LLM presentation guidance."""
+    print(f" @OUTPUT_TYPE:{output_type}")
+    print()
+
+
+# Task keyword mappings for intent detection
+TASK_MAPPINGS = {
+    # Version info
+    "version": ["version", "v", "release", "what version", "which version", "devkit version",
+                "changelog", "changes", "what's new", "updates", "release notes"],
+
+    # Core commands
+    "fix": ["fix", "bug", "error", "broken", "issue", "crash", "fail", "wrong", "not working"],
+    "debug": ["debug", "trace", "investigate", "diagnose", "troubleshoot", "why"],
+    "scout": ["find", "search", "locate", "explore", "scan", "where", "look for"],
+    "analyze": ["analyze", "audit", "inspect", "quality", "security", "performance"],
+    "refactor": ["refactor", "clean", "simplify", "improve", "optimize"],
+    "research": ["research", "learn", "understand", "discover", "investigate"],
+
+    # Spec workflow (complex tasks)
+    "spec": ["spec", "task", "feature", "requirement", "plan", "implement", "brainstorm",
+             "capture", "update", "deep"],
+    "spec-lite": ["quick", "small", "simple", "lite", "fast task", "minor"],
+
+    # Review
+    "review": ["review", "check", "validate", "verify", "code review"],
+
+    # Config & Setup
+    "config": ["config", "configure", "init", "setup", "bootstrap", "initialize", "project"],
+
+    # Documentation
+    "docs": ["document", "readme", "docs", "explain", "knowledge", "summarize"],
+
+    # Frontend
+    "frontend": ["component", "page", "form", "table", "storybook", "react", "ui", "frontend"],
+
+    # Backend
+    "backend": ["api", "endpoint", "schema", "migration", "rest", "graphql", "backend", "server"],
+
+    # Skills
+    "skill": ["skill", "agent", "automate", "workflow", "command"],
+
+    # Testing
+    "create-test": ["test", "coverage", "unit", "integration", "spec"],
+}
+
+# Category workflows and tips
+CATEGORY_GUIDES = {
+    # Version Info
+    "version": {
+        "title": "AI-DevKit Version",
+        "workflow": [],
+        "tip": "Version is stored in .cursor/settings.json under env.AI_DEVKIT_VERSION",
+    },
+
+    # Core Commands
+    "fix": {
+        "title": "Bug Fixing",
+        "workflow": [
+            ("Quick fix", "`/fix` \"describe issue\" → auto-routes"),
+            ("Fast mode", "`/fix:fast` \"small issue\""),
+            ("Hard issues", "`/fix:hard` \"complex problem\""),
+            ("Debug first", "`/debug` \"investigate issue\""),
+        ],
+        "tip": "Include error messages and stack traces for better results",
+    },
+    "debug": {
+        "title": "Debugging",
+        "workflow": [
+            ("Start", "`/debug` \"describe the problem\""),
+            ("7-step method", "Observe → Hypothesis → Test → Analyze → Fix → Verify → Document"),
+        ],
+        "tip": "Debug uses systematic methodology - provide all context upfront",
+    },
+    "scout": {
+        "title": "Codebase Search",
+        "workflow": [
+            ("Find files", "`/scout` \"what to find\""),
+            ("Uses parallel Explore agents for fast results"),
+        ],
+        "tip": "Be specific: 'authentication logic' beats 'auth'",
+    },
+    "analyze": {
+        "title": "Code Analysis",
+        "workflow": [
+            ("Full analysis", "`/analyze` <target>"),
+            ("Focus areas", "`/analyze` --focus quality|security|performance|architecture"),
+        ],
+        "tip": "Use --focus to narrow scope for faster results",
+    },
+    "refactor": {
+        "title": "Refactoring",
+        "workflow": [
+            ("Start", "`/refactor` <file|function|module>"),
+            ("Follows simplification + verification gates"),
+        ],
+        "tip": "Refactor includes tests verification - no manual testing needed",
+    },
+    "research": {
+        "title": "Research",
+        "workflow": [
+            ("Deep dive", "`/research` \"topic or question\""),
+            ("Includes docs discovery and report generation"),
+        ],
+        "tip": "Research generates detailed reports - great for learning new tech",
+    },
+
+    # Spec Workflow (Complex Tasks)
+    "spec": {
+        "title": "Spec Workflow (Complex Tasks)",
+        "workflow": [
+            ("1. Create task", "`/spec:task` <TASK-ID>"),
+            ("2a. Brainstorm", "`/spec:brainstorm` <TASK-ID> \"description\" (new features)"),
+            ("2b. Capture", "`/spec:capture-requirement` <TASK-ID> (existing code/tickets)"),
+            ("2c. Deep capture", "`/spec:deep-capture-requirement` <TASK-ID> (complex codebase)"),
+            ("3. Plan", "`/spec:plan` <TASK-ID>"),
+            ("4. Implement", "`/spec:implement` <TASK-ID>"),
+            ("5. Test", "`/spec:test` <TASK-ID>"),
+            ("Update req", "`/spec:update-requirement` <TASK-ID> \"changes\""),
+            ("Update plan", "`/spec:update-plan` <TASK-ID> \"changes\""),
+        ],
+        "tip": "Use capture-requirement for existing code, brainstorm for new features",
+    },
+    "spec-lite": {
+        "title": "Spec-Lite (Fast Small Tasks)",
+        "workflow": [
+            ("1. Create", "`/spec-lite:task` <TASK-ID>"),
+            ("2. Plan", "`/spec-lite:plan` <TASK-ID>"),
+            ("3. Do", "`/spec-lite:do` <TASK-ID>"),
+            ("4. Test", "`/spec-lite:test` <TASK-ID>"),
+            ("Update plan", "`/spec-lite:update-plan` <TASK-ID> \"changes\""),
+        ],
+        "tip": "Faster than full spec - use for well-defined small tasks",
+    },
+
+    # Review
+    "review": {
+        "title": "Code Review",
+        "workflow": [
+            ("Single file", "`/review:code` <file>"),
+            ("Folder", "`/review:code` <folder>"),
+            ("Changed files", "`/review:code` --changed"),
+            ("Full codebase", "`/review:codebase`"),
+        ],
+        "tip": "Reviews against ./docs/ rules - fixes violations automatically",
+    },
+
+    # Config & Setup
+    "config": {
+        "title": "Project Configuration",
+        "workflow": [
+            ("Bootstrap", "`/config:bootstrap` \"requirements\""),
+            ("Init frontend", "`/config:init-frontend`"),
+            ("Init backend", "`/config:init-backend`"),
+        ],
+        "tip": "Bootstrap sets up docs/, and project structure",
+    },
+
+    # Documentation
+    "docs": {
+        "title": "Documentation",
+        "workflow": [
+            ("Initialize", "`/docs:init`"),
+            ("Update", "`/docs:update`"),
+            ("Summarize", "`/docs:summarize`"),
+            ("Capture", "`/docs:capture-knowledge`"),
+        ],
+        "tip": "Keep docs in sync - run /docs:update after major changes",
+    },
+
+    # Frontend
+    "frontend": {
+        "title": "Frontend Generation",
+        "workflow": [
+            ("Component", "`/frontend:create-component` \"specs\""),
+            ("Page", "`/frontend:create-page` \"specs\""),
+            ("Form", "`/frontend:create-form` \"specs\""),
+            ("Table", "`/frontend:create-table` \"specs\""),
+            ("Storybook", "`/frontend:create-storybook` <component>"),
+        ],
+        "tip": "Generated code follows project patterns in ./docs/",
+    },
+
+    # Backend
+    "backend": {
+        "title": "Backend Generation",
+        "workflow": [
+            ("API endpoint", "`/backend:create-api` \"specs\""),
+            ("DB schema", "`/backend:create-schema` \"specs\""),
+            ("Migration", "`/backend:create-migration` \"specs\""),
+            ("Design REST", "`/backend:design-rest-api`"),
+            ("Design GraphQL", "`/backend:design-graphql-api`"),
+        ],
+        "tip": "APIs follow REST/GraphQL patterns from ./docs/",
+    },
+
+    # Skills
+    "skill": {
+        "title": "Skill Management",
+        "workflow": [
+            ("Create new", "`/skill:create`"),
+            ("Add existing", "`/skill:add`"),
+            ("Optimize", "`/skill:optimize`"),
+        ],
+        "tip": "Skills extend agent capabilities - check ./cursor/skills/ catalog",
+    },
+
+    # Testing
+    "create-test": {
+        "title": "Test Generation",
+        "workflow": [
+            ("Generate tests", "`/create-test` <file>"),
+            ("Targets 99% coverage"),
+        ],
+        "tip": "Generated tests follow project testing patterns",
+    },
+}
+
+
+def detect_prefix(commands_dir: Path) -> str:
+    """Detect if commands use /devkit: prefix based on directory structure."""
+    devkit_commands_dir = commands_dir / "devkit"
+    return "devkit:" if devkit_commands_dir.exists() and devkit_commands_dir.is_dir() else ""
+
+
+def parse_frontmatter(file_path: Path) -> dict:
+    """Parse YAML frontmatter from a markdown file."""
+    try:
+        content = file_path.read_text(encoding='utf-8')
+    except Exception:
+        return {}
+
+    # Check for frontmatter
+    if not content.startswith('---'):
+        return {}
+
+    # Find closing ---
+    end_idx = content.find('---', 3)
+    if end_idx == -1:
+        return {}
+
+    frontmatter = content[3:end_idx].strip()
+    result = {}
+
+    for line in frontmatter.split('\n'):
+        if ':' in line:
+            key, value = line.split(':', 1)
+            result[key.strip()] = value.strip()
+
+    return result
+
+
+def discover_commands(commands_dir: Path, prefix: str) -> dict:
+    """Scan .cursor/commands/ and build command catalog."""
+    commands = {}
+    categories = {}
+
+    if not commands_dir.exists():
+        return {"commands": commands, "categories": categories}
+
+    # Determine base directory for scanning
+    # If prefix is "devkit:", scan from devkit/ subdirectory
+    if prefix == "devkit:":
+        scan_dir = commands_dir / "devkit"
+        if not scan_dir.exists():
+            scan_dir = commands_dir
+    else:
+        scan_dir = commands_dir
+
+    # Scan all .md files
+    for md_file in scan_dir.rglob("*.md"):
+        # Skip non-command files
+        rel_path = md_file.relative_to(scan_dir)
+        parts = rel_path.parts
+
+        # Get command name from path
+        # e.g., fix/fast.md -> fix:fast, plan.md -> plan
+        if len(parts) == 1:
+            # Root command: plan.md -> plan
+            cmd_name = parts[0].replace('.md', '')
+            category = "core"
+        else:
+            # Nested command: fix/fast.md -> fix:fast
+            category = parts[0]
+            cmd_name = ':'.join([p.replace('.md', '') for p in parts])
+
+        # Parse frontmatter
+        fm = parse_frontmatter(md_file)
+        description = fm.get('description', '')
+
+        # Skip if no description (not a real command)
+        if not description:
+            continue
+
+        # Clean description (remove emoji indicators)
+        clean_desc = re.sub(r'^[^\w\s]+\s*', '', description).strip()
+
+        # Format command name with prefix
+        formatted_name = f"/{prefix}{cmd_name}" if prefix else f"/{cmd_name}"
+
+        # Add to commands
+        if category not in commands:
+            commands[category] = []
+
+        commands[category].append({
+            "name": formatted_name,
+            "description": clean_desc,
+            "category": category,
+        })
+
+        # Track categories
+        if category not in categories:
+            categories[category] = category.title()
+
+    # Sort commands within each category
+    for cat in commands:
+        commands[cat].sort(key=lambda x: x["name"])
+
+    return {"commands": commands, "categories": categories}
+
+
+def read_version(cursor_dir: Path) -> str:
+    """Read version from .cursor/settings.json env.AI_DEVKIT_VERSION."""
+    import json
+    settings_file = cursor_dir / "settings.json"
+    if settings_file.exists():
+        try:
+            content = settings_file.read_text(encoding='utf-8')
+            settings = json.loads(content)
+            return settings.get("env", {}).get("AI_DEVKIT_VERSION", "unknown")
+        except Exception:
+            pass
+    return "unknown"
+
+
+def read_changelog(cursor_dir: Path, max_entries: int = 3) -> str:
+    """Read CHANGELOG.md from .cursor directory and return recent entries."""
+    changelog_file = cursor_dir / "CHANGELOG.md"
+
+    if not changelog_file.exists():
+        return ""
+
+    try:
+        content = changelog_file.read_text(encoding='utf-8')
+        lines = content.split('\n')
+
+        # Find version entries (## X.Y.Z)
+        result_lines = []
+        entry_count = 0
+        in_entry = False
+        skip_header = True
+
+        for line in lines:
+            # Skip header lines until first version entry
+            if skip_header:
+                if line.startswith('## ') and re.match(r'^## \d+\.\d+\.\d+', line):
+                    skip_header = False
+                else:
+                    continue
+
+            # Count version entries
+            if line.startswith('## ') and re.match(r'^## \d+\.\d+\.\d+', line):
+                entry_count += 1
+                if entry_count > max_entries:
+                    break
+                in_entry = True
+
+            if in_entry:
+                result_lines.append(line)
+
+        return '\n'.join(result_lines).strip()
+    except Exception:
+        return ""
+
+
+def show_version(cursor_dir: Path) -> None:
+    """Display AI-DevKit version information and recent changelog."""
+    emit_output_type("command-details")
+
+    version = read_version(cursor_dir)
+    changelog = read_changelog(cursor_dir, max_entries=2)
+
+    print("# AI-DevKit Version")
+    print()
+    print(f"**Current Version:** {version}")
+    print()
+    print("**Version File:** `.cursor/settings.json` (env.AI_DEVKIT_VERSION)")
+    print()
+    print("**Changelog:** `.cursor/CHANGELOG.md`")
+
+    if changelog:
+        print()
+        print("---")
+        print()
+        print("## Recent Changes")
+        print()
+        print(changelog)
+
+    print()
+    print("---")
+    print()
+    print("**Full Changelog:** [GitLab Repository](https://gitlab.enouvo.com/development-team/base-projects/ai-toolkits/ai-devkit/-/blob/main/CHANGELOG.md)")
+    print()
+    print("*Run `/devkit:help version` for version info.*")
+
+
+def detect_intent(input_str: str, categories: list) -> str:
+    """Smart auto-detection of user intent."""
+    if not input_str:
+        return "overview"
+
+    input_lower = input_str.lower()
+
+    # Check for version/changelog query
+    version_keywords = ["version", "v", "what version", "which version", "devkit version",
+                        "changelog", "changes", "what's new", "whats new", "release notes", "updates"]
+    if any(kw == input_lower or input_lower.startswith(kw) for kw in version_keywords):
+        return "version"
+
+    # Check if it's a known category
+    if input_lower in [c.lower() for c in categories]:
+        return "category"
+
+    # Check if it looks like a command (has colon)
+    if ':' in input_str:
+        return "command"
+
+    # Multiple words = task description
+    if len(input_str.split()) >= 2:
+        return "task"
+
+    return "search"
+
+
+def show_overview(data: dict, prefix: str) -> None:
+    """Display overview with quick start guide."""
+    emit_output_type("category-guide")
+
+    commands = data["commands"]
+    categories = data["categories"]
+    total = sum(len(cmds) for cmds in commands.values())
+    help_cmd = f"/{prefix}help" if prefix else "/help"
+
+    print("# AI-DevKit Commands")
+    print()
+    print(f"{total} commands across {len(categories)} categories.")
+    print()
+    print("**Quick Start:**")
+    print(f"- `/{prefix}help` - This guide")
+    print(f"- `/{prefix}ask` - Intelligent routing to the right command")
+    print(f"- `/{prefix}scout` - Fast codebase search")
+    print()
+    print("**Common Workflows:**")
+    print(f"- `/{prefix}fix` → `/{prefix}debug` - Bug fixing")
+    print(f"- `/{prefix}spec:task` → `/{prefix}spec:plan` → `/{prefix}spec:implement` - Complex features (use TASK-ID like FE-001)")
+    print(f"- `/{prefix}spec-lite:task` → `/{prefix}spec-lite:do` - Quick tasks")
+    print(f"- `/{prefix}review:code` → `/{prefix}refactor` - Code quality")
+    print()
+    print("**Categories:**")
+    for cat_key in sorted(categories.keys()):
+        count = len(commands.get(cat_key, []))
+        print(f"- `{cat_key}` ({count})")
+    print()
+    print("**Usage:**")
+    print(f"- `{help_cmd} <category>` - Category guide with workflow")
+    print(f"- `{help_cmd} <command>` - Command details")
+    print(f"- `{help_cmd} <task description>` - Task recommendations")
+
+
+def show_category_guide(data: dict, category: str, prefix: str) -> None:
+    """Display category guide with workflow and tips."""
+    emit_output_type("category-guide")
+
+    categories = data["categories"]
+    commands = data["commands"]
+
+    # Find matching category (case-insensitive)
+    cat_key = None
+    for key in categories:
+        if key.lower() == category.lower():
+            cat_key = key
+            break
+
+    if not cat_key:
+        print(f"Category '{category}' not found.")
+        print()
+        print("Available: " + ", ".join(f"`{c}`" for c in sorted(categories.keys())))
+        return
+
+    cmds = commands.get(cat_key, [])
+    guide = CATEGORY_GUIDES.get(cat_key, {})
+
+    print(f"# {guide.get('title', cat_key.title())}")
+    print()
+
+    # Workflow first (most important)
+    if "workflow" in guide:
+        print("**Workflow:**")
+        for step, cmd in guide["workflow"]:
+            print(f"- {step}: {cmd}")
+        print()
+
+    # Commands list
+    print("**Commands:**")
+    for cmd in cmds:
+        print(f"- `{cmd['name']}` - {cmd['description']}")
+
+    # Tip at the end
+    if "tip" in guide:
+        print()
+        print(f"*Tip: {guide['tip']}*")
+
+
+def show_command(data: dict, command: str, prefix: str) -> None:
+    """Display command details."""
+    emit_output_type("command-details")
+
+    commands = data["commands"]
+
+    # Normalize search term (remove prefix and separators)
+    search = command.lower().replace("/devkit:", "").replace("/", "").replace(":", "")
+
+    found = None
+    for cmds in commands.values():
+        for cmd in cmds:
+            # Normalize command name for comparison
+            name = cmd["name"].lower().replace("/devkit:", "").replace("/", "").replace(":", "")
+            if name == search:
+                found = cmd
+                break
+        if found:
+            break
+
+    if not found:
+        print(f"Command '{command}' not found.")
+        print()
+        do_search(data, command.replace(":", " "), prefix)
+        return
+
+    print(f"# `{found['name']}`")
+    print()
+    print(found['description'])
+    print()
+    print(f"**Category:** {found['category']}")
+    print()
+    print(f"**Usage:** `{found['name']} <your-input>`")
+
+    # Show related commands (same category)
+    cat = found['category']
+    if cat in commands:
+        related = [c for c in commands[cat] if c['name'] != found['name']][:3]
+        if related:
+            related_names = ", ".join(f"`{r['name']}`" for r in related)
+            print()
+            print(f"**Related:** {related_names}")
+
+
+def do_search(data: dict, term: str, prefix: str) -> None:
+    """Search commands by keyword."""
+    emit_output_type("search-results")
+
+    commands = data["commands"]
+    term_lower = term.lower()
+    matches = []
+
+    for cmds in commands.values():
+        for cmd in cmds:
+            if term_lower in cmd["name"].lower() or term_lower in cmd["description"].lower():
+                matches.append(cmd)
+
+    if not matches:
+        print(f"No commands found for '{term}'.")
+        print()
+        print("Try browsing categories: " + ", ".join(f"`{c}`" for c in sorted(data["categories"].keys())))
+        return
+
+    print(f"# Search: {term}")
+    print()
+    print(f"Found {len(matches)} matches:")
+    for cmd in matches[:8]:
+        print(f"- `{cmd['name']}` - {cmd['description']}")
+
+
+def recommend_task(data: dict, task: str, prefix: str) -> None:
+    """Recommend commands for a task description."""
+    emit_output_type("task-recommendations")
+
+    commands = data["commands"]
+    task_lower = task.lower()
+
+    # Score categories by keyword matches
+    scores = {}
+    for cat, keywords in TASK_MAPPINGS.items():
+        score = sum(1 for kw in keywords if kw in task_lower)
+        if score > 0:
+            scores[cat] = score
+
+    if not scores:
+        print(f"Not sure about: {task}")
+        print()
+        print("Try being more specific, or browse categories: " + ", ".join(f"`{c}`" for c in sorted(data["categories"].keys())))
+        return
+
+    sorted_cats = sorted(scores.items(), key=lambda x: -x[1])
+    top_cat = sorted_cats[0][0]
+    guide = CATEGORY_GUIDES.get(top_cat, {})
+
+    print(f"# Recommended for: {task}")
+    print()
+
+    # Show workflow first (most actionable)
+    if "workflow" in guide:
+        print("**Workflow:**")
+        for step, cmd in guide["workflow"][:3]:
+            print(f"- {step}: {cmd}")
+        print()
+
+    # Show relevant commands
+    print("**Commands:**")
+    shown = 0
+    for cat, _ in sorted_cats[:2]:
+        if cat in commands:
+            for cmd in commands[cat][:2]:
+                print(f"- `{cmd['name']}` - {cmd['description']}")
+                shown += 1
+                if shown >= 4:
+                    break
+        if shown >= 4:
+            break
+
+    if "tip" in guide:
+        print()
+        print(f"*Tip: {guide['tip']}*")
+
+def main():
+    # Find .cursor/commands directory
+    script_path = Path(__file__).resolve()
+    cursor_dir = script_path.parent.parent  # .cursor/scripts -> .cursor
+    commands_dir = cursor_dir / "commands"
+
+    if not commands_dir.exists():
+        print("Error: .cursor/commands/ directory not found.")
+        sys.exit(1)
+
+    # Detect prefix and discover commands
+    prefix = detect_prefix(commands_dir)
+    data = discover_commands(commands_dir, prefix)
+
+    if not data["commands"]:
+        print("No commands found in .cursor/commands/")
+        sys.exit(1)
+
+    # Parse input
+    args = sys.argv[1:]
+    input_str = " ".join(args).strip()
+
+    # Detect intent and route
+    intent = detect_intent(input_str, list(data["categories"].keys()))
+
+    if intent == "overview":
+        show_overview(data, prefix)
+    elif intent == "version":
+        show_version(cursor_dir)
+    elif intent == "category":
+        show_category_guide(data, input_str, prefix)
+    elif intent == "command":
+        show_command(data, input_str, prefix)
+    elif intent == "task":
+        recommend_task(data, input_str, prefix)
+    else:
+        do_search(data, input_str, prefix)
+
+
+if __name__ == "__main__":
+    main()