anchi-toolkit 1.2.0 → 1.2.1

package/dist/.cursor/scripts/resolve_env.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""
+Centralized environment variable resolver for Claude Code skills.
+
+Resolves environment variables following the Claude Code hierarchy:
+1. process.env                    - Runtime environment (HIGHEST)
+2. .cursor/skills/<skill>/.env    - Project skill-specific
+3. .cursor/skills/.env            - Project shared
+4. .cursor/.env                   - Project global
+5. ~/.cursor/skills/<skill>/.env  - User skill-specific
+6. ~/.cursor/skills/.env          - User shared
+7. ~/.cursor/.env                 - User global (LOWEST)
+
+Usage:
+    from resolve_env import resolve_env
+
+    api_key = resolve_env('GEMINI_API_KEY', skill='ai-multimodal')
+    api_key = resolve_env('GEMINI_API_KEY')  # Without skill context
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional, Dict, List, Tuple
+
+def _parse_env_file_fallback(path) -> Dict[str, str]:
+    """
+    Pure-Python fallback .env parser when python-dotenv is not installed.
+
+    Handles basic .env format:
+    - KEY=value
+    - KEY="quoted value"
+    - KEY='single quoted'
+    - # comments (full line)
+    - Empty lines ignored
+
+    Args:
+        path: Path to .env file (str or Path)
+
+    Returns:
+        Dictionary of environment variables
+    """
+    env_vars = {}
+    try:
+        with open(path, 'r') as f:
+            for line in f:
+                line = line.strip()
+                # Skip empty lines and comments
+                if not line or line.startswith('#'):
+                    continue
+                # Parse KEY=value
+                if '=' in line:
+                    key, value = line.split('=', 1)
+                    key = key.strip()
+                    value = value.strip()
+                    # Remove surrounding quotes
+                    if (value.startswith('"') and value.endswith('"')) or \
+                       (value.startswith("'") and value.endswith("'")):
+                        value = value[1:-1]
+                    env_vars[key] = value
+    except Exception:
+        pass
+    return env_vars
+
+
+try:
+    from dotenv import dotenv_values
+except ImportError:
+    # Use fallback parser when python-dotenv not installed
+    dotenv_values = _parse_env_file_fallback
+
+
+def find_project_root() -> Optional[Path]:
+    """Find project root by looking for .git or .cursor directory."""
+    current = Path.cwd()
+
+    # Check current directory and all parents
+    for directory in [current] + list(current.parents):
+        if (directory / '.git').exists() or (directory / '.cursor').exists():
+            return directory
+
+    return None
+
+
+def get_env_file_paths(skill: Optional[str] = None) -> List[Tuple[str, Path]]:
+    """
+    Get all potential .env file paths in priority order.
+
+    Args:
+        skill: Optional skill name for skill-specific configs
+
+    Returns:
+        List of (description, path) tuples in priority order (highest to lowest)
+    """
+    paths = []
+
+    # Find project root
+    project_root = find_project_root()
+
+    # User home directory
+    home = Path.home()
+
+    # Priority 2-4: Project-level configs (if project root found)
+    if project_root:
+        if skill:
+            paths.append((
+                f"Project skill-specific ({skill})",
+                project_root / '.cursor' / 'skills' / skill / '.env'
+            ))
+
+        paths.append((
+            "Project skills shared",
+            project_root / '.cursor' / 'skills' / '.env'
+        ))
+
+        paths.append((
+            "Project global",
+            project_root / '.cursor' / '.env'
+        ))
+
+    # Priority 5-7: User-level configs
+    if skill:
+        paths.append((
+            f"User skill-specific ({skill})",
+            home / '.cursor' / 'skills' / skill / '.env'
+        ))
+
+    paths.append((
+        "User skills shared",
+        home / '.cursor' / 'skills' / '.env'
+    ))
+
+    paths.append((
+        "User global",
+        home / '.cursor' / '.env'
+    ))
+
+    return paths
+
+
+def resolve_env(
+    var_name: str,
+    skill: Optional[str] = None,
+    default: Optional[str] = None,
+    verbose: bool = False
+) -> Optional[str]:
+    """
+    Resolve environment variable following Claude Code hierarchy.
+
+    Args:
+        var_name: Name of the environment variable to resolve
+        skill: Optional skill name for skill-specific resolution
+        default: Default value if variable not found anywhere
+        verbose: If True, print resolution details
+
+    Returns:
+        Resolved value or default if not found
+    """
+    # Priority 1: Check process environment (HIGHEST)
+    value = os.getenv(var_name)
+    if value:
+        if verbose:
+            print(f"✓ {var_name} found in: Runtime environment (process.env)")
+        return value
+
+    if verbose:
+        print(f"✗ {var_name} not in: Runtime environment")
+
+    # Note: dotenv_values is always available (uses fallback if python-dotenv not installed)
+
+    # Priority 2-7: Check .env files in order
+    env_paths = get_env_file_paths(skill)
+
+    for description, path in env_paths:
+        if path.exists():
+            try:
+                env_vars = dotenv_values(path)
+                value = env_vars.get(var_name)
+
+                if value:
+                    if verbose:
+                        print(f"✓ {var_name} found in: {description}")
+                        print(f"  Path: {path}")
+                    return value
+                else:
+                    if verbose:
+                        print(f"✗ {var_name} not in: {description} (file exists)")
+            except Exception as e:
+                if verbose:
+                    print(f"⚠ Error reading {description}: {e}")
+        else:
+            if verbose:
+                print(f"✗ {var_name} not in: {description} (file not found)")
+
+    # Not found anywhere
+    if verbose:
+        print(f"\n❌ {var_name} not found in any location")
+        if default:
+            print(f"   Using default: {default}")
+
+    return default
+
+
+def find_all(var_name: str, skill: Optional[str] = None) -> List[Tuple[str, str, Path]]:
+    """
+    Find all locations where a variable is defined.
+
+    Args:
+        var_name: Name of the environment variable
+        skill: Optional skill name
+
+    Returns:
+        List of (description, value, path) tuples for all found locations
+    """
+    results = []
+
+    # Check process environment
+    value = os.getenv(var_name)
+    if value:
+        results.append(("Runtime environment", value, None))
+
+    # Check all .env files (dotenv_values always available via fallback)
+    env_paths = get_env_file_paths(skill)
+
+    for description, path in env_paths:
+        if path.exists():
+            try:
+                env_vars = dotenv_values(path)
+                value = env_vars.get(var_name)
+
+                if value:
+                    results.append((description, value, path))
+            except Exception:
+                pass
+
+    return results
+
+
+def show_hierarchy(skill: Optional[str] = None):
+    """Print the environment variable resolution hierarchy."""
+    print("Environment Variable Resolution Hierarchy")
+    print("=" * 60)
+    print("\nPriority order (highest to lowest):")
+    print("1. process.env - Runtime environment")
+
+    env_paths = get_env_file_paths(skill)
+    for i, (description, path) in enumerate(env_paths, start=2):
+        exists = "✓" if path.exists() else "✗"
+        print(f"{i}. {description:30} {exists} {path}")
+
+    print("\n" + "=" * 60)
+
+
+def main():
+    """CLI interface for environment variable resolution."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description='Resolve environment variables following Claude Code hierarchy',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Resolve GEMINI_API_KEY for ai-multimodal skill
+  %(prog)s GEMINI_API_KEY --skill ai-multimodal
+
+  # Resolve with verbose output
+  %(prog)s GEMINI_API_KEY --skill ai-multimodal --verbose
+
+  # Find all locations where variable is defined
+  %(prog)s GEMINI_API_KEY --find-all
+
+  # Show hierarchy
+  %(prog)s --show-hierarchy --skill ai-multimodal
+        """
+    )
+
+    parser.add_argument('var_name', nargs='?', help='Environment variable name to resolve')
+    parser.add_argument('--skill', help='Skill name for skill-specific resolution')
+    parser.add_argument('--default', help='Default value if not found')
+    parser.add_argument('--verbose', '-v', action='store_true', help='Show resolution details')
+    parser.add_argument('--find-all', action='store_true', help='Find all locations where variable is defined')
+    parser.add_argument('--show-hierarchy', action='store_true', help='Show resolution hierarchy')
+    parser.add_argument('--export', action='store_true', help='Output in export format for shell sourcing')
+
+    args = parser.parse_args()
+
+    if args.show_hierarchy:
+        show_hierarchy(args.skill)
+        sys.exit(0)
+
+    if not args.var_name:
+        parser.error("var_name is required unless --show-hierarchy is used")
+
+    if args.find_all:
+        results = find_all(args.var_name, args.skill)
+
+        if results:
+            print(f"Variable '{args.var_name}' found in {len(results)} location(s):")
+            print("=" * 60)
+
+            for i, (description, value, path) in enumerate(results, start=1):
+                priority = i if i == 1 else i + 1  # Account for process.env being priority 1
+                print(f"\n{priority}. {description}")
+                if path:
+                    print(f"   Path: {path}")
+                print(f"   Value: {value[:50]}{'...' if len(value) > 50 else ''}")
+
+            print("\n" + "=" * 60)
+            print(f"✓ Resolved value (highest priority): {results[0][1][:50]}{'...' if len(results[0][1]) > 50 else ''}")
+        else:
+            print(f"❌ Variable '{args.var_name}' not found in any location")
+            sys.exit(1)
+    else:
+        value = resolve_env(args.var_name, args.skill, args.default, args.verbose)
+
+        if value:
+            if args.export:
+                print(f"export {args.var_name}='{value}'")
+            else:
+                print(value)
+            sys.exit(0)
+        else:
+            if not args.verbose:
+                print(f"Error: {args.var_name} not found", file=sys.stderr)
+            sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/dist/.cursor/scripts/scan_commands.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""
+Scan .cursor/commands directory and extract command metadata.
+"""
+
+import re
+from pathlib import Path
+from typing import Dict, List
+import yaml
+
+def extract_frontmatter(content: str) -> Dict:
+    """Extract YAML frontmatter from markdown content."""
+    match = re.match(r'^---\s*\n(.*?)\n---\s*\n', content, re.DOTALL)
+    if match:
+        try:
+            return yaml.safe_load(match.group(1))
+        except:
+            return {}
+    return {}
+
+def scan_commands(base_path: Path) -> List[Dict]:
+    """Scan all command files and extract metadata."""
+    commands = []
+
+    for cmd_file in sorted(base_path.rglob('*.md')):
+        # Get relative path from commands directory
+        rel_path = cmd_file.relative_to(base_path)
+
+        # Build command name from path
+        parts = list(rel_path.parts[:-1]) + [rel_path.stem]
+        command_name = '/ck:' + ':'.join(parts)
+
+        # Read file and extract frontmatter
+        try:
+            content = cmd_file.read_text()
+            frontmatter = extract_frontmatter(content)
+
+            description = frontmatter.get('description', '')
+            arg_hint = frontmatter.get('argument-hint', '')
+
+            # Extract power level (⚡ count)
+            power_level = description.count('⚡')
+            clean_desc = description.replace('⚡', '').strip()
+
+            commands.append({
+                'name': command_name,
+                'path': str(rel_path),
+                'description': clean_desc,
+                'argument_hint': arg_hint,
+                'power_level': power_level,
+                'category': parts[0] if len(parts) > 1 else 'core'
+            })
+        except Exception as e:
+            print(f"Error processing {cmd_file}: {e}")
+
+    return commands
+
+def group_by_category(commands: List[Dict]) -> Dict[str, List[Dict]]:
+    """Group commands by category."""
+    categories = {}
+
+    for cmd in commands:
+        category = cmd['category']
+        if category not in categories:
+            categories[category] = []
+        categories[category].append(cmd)
+
+    return categories
+
+def main():
+    """Main execution."""
+    base_path = Path('.cursor/commands')
+
+    if not base_path.exists():
+        print(f"Error: {base_path} not found")
+        return
+
+    print("Scanning commands...")
+    commands = scan_commands(base_path)
+
+    print(f"\nFound {len(commands)} commands\n")
+
+    # Group by category
+    categories = group_by_category(commands)
+
+    for category, cmds in sorted(categories.items()):
+        print(f"\n{category.upper()}:")
+        for cmd in cmds:
+            power = '⚡' * cmd['power_level'] if cmd['power_level'] > 0 else ''
+            print(f"  {cmd['name']:40} {power:10} {cmd['description'][:80]}")
+
+    # Output JSON for processing
+    import json
+    output_path = Path('.cursor/scripts/commands_data.json')
+    output_path.write_text(json.dumps(commands, indent=2))
+    print(f"\n✓ Saved metadata to {output_path}")
+
+if __name__ == '__main__':
+    main()

package/dist/.cursor/scripts/scan_skills.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""
+Scan .cursor/skills directory and extract skill metadata.
+"""
+
+import re
+from pathlib import Path
+from typing import Dict, List
+import yaml
+
+def extract_frontmatter(content: str) -> Dict:
+    """Extract YAML frontmatter from markdown content."""
+    match = re.match(r'^---\s*\n(.*?)\n---\s*\n', content, re.DOTALL)
+    if match:
+        try:
+            return yaml.safe_load(match.group(1))
+        except:
+            return {}
+    return {}
+
+def extract_first_paragraph(content: str) -> str:
+    """Extract first meaningful paragraph after frontmatter."""
+    # Remove frontmatter
+    content = re.sub(r'^---\s*\n.*?\n---\s*\n', '', content, flags=re.DOTALL)
+
+    # Find first paragraph (after headings)
+    lines = content.split('\n')
+    paragraph = []
+
+    for line in lines:
+        line = line.strip()
+        # Skip headings and empty lines
+        if line.startswith('#') or not line:
+            if paragraph:  # If we've started collecting, stop
+                break
+            continue
+
+        paragraph.append(line)
+
+        # Stop after first paragraph
+        if line.endswith('.') and len(' '.join(paragraph)) > 50:
+            break
+
+    return ' '.join(paragraph)[:200]
+
+def scan_skills(base_path: Path) -> List[Dict]:
+    """Scan all skill files and extract metadata."""
+    skills = []
+
+    for skill_file in sorted(base_path.rglob('SKILL.md')):
+        # Get skill directory name
+        skill_dir = skill_file.parent
+        skill_name = skill_dir.name
+
+        # Skip template
+        if skill_name == 'template-skill':
+            continue
+
+        # Handle nested skills (like document-skills/*)
+        if skill_dir.parent.name != 'skills':
+            parent_name = skill_dir.parent.name
+            skill_name = f"{parent_name}/{skill_name}"
+
+        try:
+            content = skill_file.read_text()
+            frontmatter = extract_frontmatter(content)
+
+            description = frontmatter.get('description', '')
+            if not description:
+                description = extract_first_paragraph(content)
+
+            # Categorize based on content/name
+            category = categorize_skill(skill_name, description, content)
+
+            skills.append({
+                'name': skill_name,
+                'path': str(skill_file.relative_to(Path('.cursor/skills'))),
+                'description': description,
+                'category': category,
+                'has_scripts': (skill_dir / 'scripts').exists(),
+                'has_references': (skill_dir / 'references').exists()
+            })
+        except Exception as e:
+            print(f"Error processing {skill_file}: {e}")
+
+    return skills
+
+def categorize_skill(name: str, description: str, content: str) -> str:
+    """Categorize skill based on name and content."""
+    lower_name = name.lower()
+    lower_desc = description.lower()
+    lower_content = content[:500].lower()
+
+    # AI/ML
+    if any(x in lower_name for x in ['ai-', 'gemini', 'multimodal', 'adk']):
+        return 'ai-ml'
+
+    # Frontend
+    if any(x in lower_name for x in ['frontend', 'ui', 'design', 'aesthetic', 'threejs']):
+        return 'frontend'
+
+    # Backend
+    if any(x in lower_name for x in ['backend', 'auth', 'payment']):
+        return 'backend'
+
+    # Infrastructure
+    if any(x in lower_name for x in ['devops', 'docker', 'cloudflare', 'gcloud']):
+        return 'infrastructure'
+
+    # Database
+    if any(x in lower_name for x in ['database', 'mongodb', 'postgresql', 'sql']):
+        return 'database'
+
+    # Development Tools
+    if any(x in lower_name for x in ['mcp', 'skill-creator', 'claude-code', 'repomix', 'docs-seeker']):
+        return 'dev-tools'
+
+    # Multimedia
+    if any(x in lower_name for x in ['media', 'chrome-devtools', 'document-skills']):
+        return 'multimedia'
+
+    # Frameworks
+    if any(x in lower_name for x in ['web-frameworks', 'mobile', 'shopify']):
+        return 'frameworks'
+
+    # Utilities
+    if any(x in lower_name for x in ['debug', 'problem', 'code-review', 'planning', 'research', 'sequential']):
+        return 'utilities'
+
+    return 'other'
+
+def group_by_category(skills: List[Dict]) -> Dict[str, List[Dict]]:
+    """Group skills by category."""
+    categories = {}
+
+    for skill in skills:
+        category = skill['category']
+        if category not in categories:
+            categories[category] = []
+        categories[category].append(skill)
+
+    return categories
+
+def main():
+    """Main execution."""
+    base_path = Path('.cursor/skills')
+
+    if not base_path.exists():
+        print(f"Error: {base_path} not found")
+        return
+
+    print("Scanning skills...")
+    skills = scan_skills(base_path)
+
+    print(f"\nFound {len(skills)} skills\n")
+
+    # Group by category
+    categories = group_by_category(skills)
+
+    category_names = {
+        'ai-ml': 'AI & Machine Learning',
+        'frontend': 'Frontend & Design',
+        'backend': 'Backend Development',
+        'infrastructure': 'Infrastructure & DevOps',
+        'database': 'Database & Storage',
+        'dev-tools': 'Development Tools',
+        'multimedia': 'Multimedia & Processing',
+        'frameworks': 'Frameworks & Platforms',
+        'utilities': 'Utilities & Helpers',
+        'other': 'Other'
+    }
+
+    for category, skills_list in sorted(categories.items()):
+        print(f"\n{category_names.get(category, category.upper())}:")
+        for skill in skills_list:
+            scripts = '📦' if skill['has_scripts'] else '  '
+            refs = '📚' if skill['has_references'] else '  '
+            print(f"  {scripts}{refs} {skill['name']:30} {skill['description'][:80]}")
+
+    # Output JSON for processing
+    import json
+    output_path = Path('.cursor/scripts/skills_data.json')
+    output_path.write_text(json.dumps(skills, indent=2))
+    print(f"\n✓ Saved metadata to {output_path}")
+
+if __name__ == '__main__':
+    main()