@manhnv319/codexkit 0.1.0

package/.codex/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. .agents/skills/<skill>/.env    - Project skill-specific
+3. .agents/skills/.env            - Project shared
+4. .codex/.env                   - Project global
+5. ~/.codex/skills/<skill>/.env  - User skill-specific
+6. ~/.codex/skills/.env          - User shared
+7. ~/.codex/.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 .codex directory."""
+    current = Path.cwd()
+
+    # Check current directory and all parents
+    for directory in [current] + list(current.parents):
+        if (directory / '.git').exists() or (directory / '.codex').exists() or (directory / '.agents').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 / '.agents' / 'skills' / skill / '.env'
+            ))
+
+        paths.append((
+            "Project skills shared",
+            project_root / '.agents' / 'skills' / '.env'
+        ))
+
+        paths.append((
+            "Project global",
+            project_root / '.codex' / '.env'
+        ))
+
+    # Priority 5-7: User-level configs
+    if skill:
+        paths.append((
+            f"User skill-specific ({skill})",
+            home / '.codex' / 'skills' / skill / '.env'
+        ))
+
+    paths.append((
+        "User skills shared",
+        home / '.codex' / 'skills' / '.env'
+    ))
+
+    paths.append((
+        "User global",
+        home / '.codex' / '.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/.codex/scripts/scan_commands.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""
+Legacy command scanner (deprecated).
+
+Commands were migrated to skills. This script now writes an empty commands dataset
+for backward compatibility with older tooling.
+"""
+
+from pathlib import Path
+
+
+def main() -> None:
+    output_path = Path(".codex/scripts/commands_data.yaml")
+    output_path.write_text(
+        "# Commands have been migrated to skills.\n"
+        "# See .agents/skills/ck-help/scripts/skills_data.yaml for the current catalog.\n"
+        "[]\n",
+        encoding="utf-8",
+    )
+    print("Commands are deprecated; wrote empty commands catalog for compatibility.")
+    print(f"✓ Saved metadata to {output_path}")
+
+
+if __name__ == "__main__":
+    main()

package/.codex/scripts/scan_skills.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""
+Scan .agents/skills directory and extract skill metadata.
+"""
+
+import re
+from pathlib import Path
+from typing import Dict, List
+try:
+    import yaml
+except ModuleNotFoundError:
+    raise SystemExit(
+        "PyYAML is required. Install with: python3 -m pip install -r .codex/scripts/requirements.txt"
+    )
+
+# Exact mappings for high-signal CK skills to avoid falling into "other".
+EXACT_CATEGORY_MAP = {
+    "ask": "utilities",
+    "code-review": "utilities",
+    "coding-level": "utilities",
+    "debug": "utilities",
+    "docs": "utilities",
+    "journal": "utilities",
+    "plan": "utilities",
+    "research": "utilities",
+    "sequential-thinking": "utilities",
+    "test": "utilities",
+    "watzup": "utilities",
+    "ck-help": "dev-tools",
+    "find-skills": "dev-tools",
+    "git": "dev-tools",
+    "kanban": "dev-tools",
+    "plans-kanban": "dev-tools",
+    "scout": "dev-tools",
+    "use-mcp": "dev-tools",
+    "worktree": "dev-tools",
+    "preview": "utilities",
+    "project-management": "utilities",
+    "bootstrap": "utilities",
+    "brainstorm": "utilities",
+    "cook": "utilities",
+    "fix": "utilities",
+    "team": "dev-tools",
+}
+
+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)
+
+            skill_entry = {
+                'name': skill_name,
+                'path': str(skill_file.relative_to(Path('.agents/skills'))),
+                'description': description,
+                'category': category,
+                'has_scripts': (skill_dir / 'scripts').exists(),
+                'has_references': (skill_dir / 'references').exists()
+            }
+
+            # Include argument-hint if present in frontmatter
+            argument_hint = frontmatter.get('argument-hint', '')
+            if argument_hint:
+                skill_entry['argument_hint'] = str(argument_hint)
+
+            skills.append(skill_entry)
+        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()
+    if lower_name in EXACT_CATEGORY_MAP:
+        return EXACT_CATEGORY_MAP[lower_name]
+
+    # 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', '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('.agents/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 YAML to ck-help scripts directory
+    output_path = Path('.agents/skills/ck-help/scripts/skills_data.yaml')
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(yaml.dump(skills, allow_unicode=True, default_flow_style=False))
+    print(f"\n✓ Saved metadata to {output_path}")
+
+    # Legacy location now points to canonical source to avoid data drift.
+    legacy_path = Path('.codex/scripts/skills_data.yaml')
+    legacy_path.write_text(
+        "# Skills catalog moved to .agents/skills/ck-help/scripts/skills_data.yaml\n"
+        "# Regenerate via: python3 .codex/scripts/scan_skills.py\n",
+        encoding='utf-8',
+    )
+
+if __name__ == '__main__':
+    main()

package/.codex/scripts/set-active-plan.cjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Update session state with new active plan
+ *
+ * Usage: node .codex/scripts/set-active-plan.cjs <plan-path>
+ *
+ * This script updates the session temp file with the new active plan path,
+ * allowing subagents to receive the latest plan context via SubagentStart hook.
+ *
+ * The session temp file (/tmp/ck-session-{id}.json) is the source of truth
+ * for plan context within a session. Env vars ($CK_ACTIVE_PLAN) are just
+ * the initial snapshot from session start.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { writeSessionState, readSessionState } = require('../hooks/lib/ck-config-utils.cjs');
+
+const sessionId = process.env.CK_SESSION_ID;
+const newPlan = process.argv[2];
+
+if (!newPlan) {
+  console.error('Error: Plan path required');
+  console.log('Usage: node .codex/scripts/set-active-plan.cjs <plan-path>');
+  console.log('Example: node .codex/scripts/set-active-plan.cjs plans/251207-1030-feature-name');
+  process.exit(1);
+}
+
+// Issue #335: Resolve to absolute path to support brownfield/subdirectory workflows
+// When agent navigates away from session origin, relative paths become invalid
+const absolutePlan = path.resolve(newPlan);
+
+if (!sessionId) {
+  const stateDir = path.join(process.cwd(), '.codex', 'state');
+  const statePath = path.join(stateDir, 'active-plan.json');
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(statePath, `${JSON.stringify({
+      activePlan: absolutePlan,
+      sessionOrigin: process.cwd(),
+      timestamp: Date.now(),
+      source: 'project-state'
+    }, null, 2)}\n`);
+    console.log(`Active plan set in project state: ${absolutePlan}`);
+    console.log(`State file: ${statePath}`);
+    process.exit(0);
+  } catch (error) {
+    console.error(`Failed to write project active plan state: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+const current = readSessionState(sessionId) || {};
+const success = writeSessionState(sessionId, {
+  ...current,
+  activePlan: absolutePlan,
+  timestamp: Date.now()
+});
+
+if (success) {
+  console.log(`Active plan set to: ${absolutePlan}`);
+} else {
+  console.error('Failed to update session state');
+  process.exit(1);
+}

package/.codex/scripts/skills_data.yaml

@@ -0,0 +1,2 @@
+# Skills catalog moved to .agents/skills/ck-help/scripts/skills_data.yaml
+# Regenerate via: python3 .codex/scripts/scan_skills.py