kiro-kit 0.1.3 → 0.2.0

package/dist/presets/mobile/skills/common/api_key_helper.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""
+Common API Key Detection Helper for Gemini Skills
+
+Supports both Google AI Studio and Vertex AI endpoints.
+
+API Key Detection Order:
+1. Process environment variable
+2. Project root .env file
+3. ./.kiro/.env
+4. ./.kiro/skills/.env
+5. Skill directory .env file
+
+Vertex AI Configuration:
+- GEMINI_USE_VERTEX: Set to "true" to use Vertex AI endpoint
+- VERTEX_PROJECT_ID: GCP project ID (required for Vertex AI)
+- VERTEX_LOCATION: GCP region (default: us-central1)
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+
+def find_api_key(skill_dir: Optional[Path] = None) -> Optional[str]:
+    """
+    Find GEMINI_API_KEY using 5-step lookup:
+    1. Process environment
+    2. Project root .env
+    3. ./.kiro/.env
+    4. ./.kiro/skills/.env
+    5. Skill directory .env
+
+    Args:
+        skill_dir: Path to skill directory (optional, auto-detected if None)
+
+    Returns:
+        API key string or None if not found
+    """
+    # Step 1: Check process environment
+    api_key = os.getenv('GEMINI_API_KEY')
+    if api_key:
+        print("✓ Using API key from environment variable", file=sys.stderr)
+        return api_key
+
+    # Determine paths
+    if skill_dir is None:
+        skill_dir = Path(__file__).parent.parent
+    project_dir = skill_dir.parent.parent.parent  # 3 levels up from skill dir
+
+    # Step 2: Check project root .env
+    project_env = project_dir / '.env'
+    if project_env.exists():
+        api_key = load_env_file(project_env)
+        if api_key:
+            print(f"✓ Using API key from {project_env}", file=sys.stderr)
+            return api_key
+
+    # Step 3: Check ./.kiro/.env
+    claude_env = project_dir / '.claude' / '.env'
+    if claude_env.exists():
+        api_key = load_env_file(claude_env)
+        if api_key:
+            print(f"✓ Using API key from {claude_env}", file=sys.stderr)
+            return api_key
+
+    # Step 4: Check ./.kiro/skills/.env
+    claude_skills_env = project_dir / '.claude' / 'skills' / '.env'
+    if claude_skills_env.exists():
+        api_key = load_env_file(claude_skills_env)
+        if api_key:
+            print(f"✓ Using API key from {claude_skills_env}", file=sys.stderr)
+            return api_key
+
+    # Step 5: Check skill directory .env
+    skill_env = skill_dir / '.env'
+    if skill_env.exists():
+        api_key = load_env_file(skill_env)
+        if api_key:
+            print(f"✓ Using API key from {skill_env}", file=sys.stderr)
+            return api_key
+
+    return None
+
+
+def load_env_file(env_path: Path) -> Optional[str]:
+    """
+    Load GEMINI_API_KEY from .env file
+
+    Args:
+        env_path: Path to .env file
+
+    Returns:
+        API key or None
+    """
+    try:
+        with open(env_path, 'r') as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith('GEMINI_API_KEY='):
+                    # Extract value, removing quotes if present
+                    value = line.split('=', 1)[1].strip()
+                    value = value.strip('"').strip("'")
+                    if value:
+                        return value
+    except Exception as e:
+        print(f"Warning: Error reading {env_path}: {e}", file=sys.stderr)
+
+    return None
+
+
+def load_env_var(env_path: Path, var_name: str) -> Optional[str]:
+    """
+    Load a specific environment variable from .env file
+
+    Args:
+        env_path: Path to .env file
+        var_name: Name of the environment variable
+
+    Returns:
+        Variable value or None
+    """
+    try:
+        with open(env_path, 'r') as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith(f'{var_name}='):
+                    value = line.split('=', 1)[1].strip()
+                    value = value.strip('"').strip("'")
+                    if value:
+                        return value
+    except Exception as e:
+        print(f"Warning: Error reading {env_path}: {e}", file=sys.stderr)
+
+    return None
+
+
+def find_env_var(var_name: str, skill_dir: Optional[Path] = None) -> Optional[str]:
+    """
+    Find environment variable using 5-step lookup (same as API key)
+
+    Args:
+        var_name: Name of environment variable
+        skill_dir: Path to skill directory (optional)
+
+    Returns:
+        Variable value or None
+    """
+    # Step 1: Check process environment
+    value = os.getenv(var_name)
+    if value:
+        return value
+
+    # Determine paths
+    if skill_dir is None:
+        skill_dir = Path(__file__).parent.parent
+    project_dir = skill_dir.parent.parent.parent
+
+    # Step 2-5: Check .env files in order
+    env_files = [
+        project_dir / '.env',
+        project_dir / '.claude' / '.env',
+        project_dir / '.claude' / 'skills' / '.env',
+        skill_dir / '.env'
+    ]
+
+    for env_path in env_files:
+        if env_path.exists():
+            value = load_env_var(env_path, var_name)
+            if value:
+                return value
+
+    return None
+
+
+def get_vertex_config(skill_dir: Optional[Path] = None) -> Dict[str, Any]:
+    """
+    Get Vertex AI configuration from environment variables
+
+    Args:
+        skill_dir: Path to skill directory (optional)
+
+    Returns:
+        Dictionary with Vertex AI configuration:
+        {
+            'use_vertex': bool,
+            'project_id': str or None,
+            'location': str (default: 'us-central1')
+        }
+    """
+    use_vertex_str = find_env_var('GEMINI_USE_VERTEX', skill_dir)
+    use_vertex = use_vertex_str and use_vertex_str.lower() in ('true', '1', 'yes')
+
+    config = {
+        'use_vertex': use_vertex,
+        'project_id': find_env_var('VERTEX_PROJECT_ID', skill_dir) if use_vertex else None,
+        'location': find_env_var('VERTEX_LOCATION', skill_dir) or 'us-central1'
+    }
+
+    return config
+
+
+def get_api_key_or_exit(skill_dir: Optional[Path] = None) -> str:
+    """
+    Get API key or exit with helpful error message
+
+    Args:
+        skill_dir: Path to skill directory (optional, auto-detected if None)
+
+    Returns:
+        API key string
+    """
+    api_key = find_api_key(skill_dir)
+
+    if not api_key:
+        print("\n❌ Error: GEMINI_API_KEY not found!", file=sys.stderr)
+        print("\n📋 Please set your API key using one of these methods (in priority order):", file=sys.stderr)
+
+        if skill_dir is None:
+            skill_dir = Path(__file__).parent.parent
+        project_dir = skill_dir.parent.parent.parent
+
+        print("\n1️⃣  Environment variable (recommended for development):", file=sys.stderr)
+        print("   export GEMINI_API_KEY='your-api-key'", file=sys.stderr)
+
+        print("\n2️⃣  Project root .env file:", file=sys.stderr)
+        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {project_dir}/.env", file=sys.stderr)
+
+        print("\n3️⃣  .kiro/.env file:", file=sys.stderr)
+        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {project_dir}/.kiro/.env", file=sys.stderr)
+
+        print("\n4️⃣  .kiro/skills/.env file (shared across all Gemini skills):", file=sys.stderr)
+        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {project_dir}/.kiro/skills/.env", file=sys.stderr)
+
+        print("\n5️⃣  Skill directory .env file:", file=sys.stderr)
+        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {skill_dir}/.env", file=sys.stderr)
+
+        print("\n🔑 Get your API key at: https://aistudio.google.com/apikey", file=sys.stderr)
+        print("\n💡 Tip: Add .env files to .gitignore to avoid committing API keys", file=sys.stderr)
+        sys.exit(1)
+
+    return api_key
+
+
+def get_client(skill_dir: Optional[Path] = None):
+    """
+    Get appropriate Gemini client (AI Studio or Vertex AI)
+
+    Args:
+        skill_dir: Path to skill directory (optional)
+
+    Returns:
+        genai.Client or vertexai client
+    """
+    vertex_config = get_vertex_config(skill_dir)
+
+    if vertex_config['use_vertex']:
+        # Use Vertex AI
+        import vertexai
+        from vertexai.generative_models import GenerativeModel
+
+        if not vertex_config['project_id']:
+            print("\n❌ Error: VERTEX_PROJECT_ID required when GEMINI_USE_VERTEX=true!", file=sys.stderr)
+            print("\n📋 Set your GCP project ID:", file=sys.stderr)
+            print("   export VERTEX_PROJECT_ID='your-project-id'", file=sys.stderr)
+            print("   Or add to .env file: VERTEX_PROJECT_ID=your-project-id", file=sys.stderr)
+            sys.exit(1)
+
+        print(f"✓ Using Vertex AI endpoint", file=sys.stderr)
+        print(f"  Project: {vertex_config['project_id']}", file=sys.stderr)
+        print(f"  Location: {vertex_config['location']}", file=sys.stderr)
+
+        vertexai.init(
+            project=vertex_config['project_id'],
+            location=vertex_config['location']
+        )
+
+        return {'type': 'vertex', 'config': vertex_config}
+    else:
+        # Use AI Studio
+        from google import genai
+
+        api_key = get_api_key_or_exit(skill_dir)
+        client = genai.Client(api_key=api_key)
+
+        return {'type': 'aistudio', 'client': client}
+
+
+if __name__ == '__main__':
+    # Test the API key detection
+    api_key = get_api_key_or_exit()
+    print(f"✓ Found API key: {api_key[:8]}..." + "*" * (len(api_key) - 8))
+
+    # Test Vertex AI config
+    vertex_config = get_vertex_config()
+    if vertex_config['use_vertex']:
+        print(f"\n✓ Vertex AI enabled:")
+        print(f"  Project: {vertex_config['project_id']}")
+        print(f"  Location: {vertex_config['location']}")

package/dist/presets/mobile/skills/debugging/SKILL.md

@@ -1,7 +1,12 @@
----
-name: debugging
-description: Systematic debugging framework for investigating root causes before applying fixes. Use when encountering bugs, test failures, or unexpected behavior in mobile apps.
----
+---
+name: debugging
+description: >-
+  Systematic debugging framework for investigating root causes before applying
+  fixes. Use when encountering bugs, test failures, or unexpected behavior in
+  mobile apps.
+version: 3.0.0
+languages: all
+---
 
 # Debugging
 

package/dist/presets/mobile/skills/debugging/references/defense-in-depth.md

@@ -0,0 +1,124 @@
+# Defense-in-Depth Validation
+
+Validate at every layer data passes through to make bugs impossible.
+
+## Core Principle
+
+**Validate at EVERY layer data passes through. Make bug structurally impossible.**
+
+When fix bug caused by invalid data, adding validation at one place feels sufficient. But single check can be bypassed by different code paths, refactoring, or mocks.
+
+## Why Multiple Layers
+
+Single validation: "We fixed bug"
+Multiple layers: "We made bug impossible"
+
+Different layers catch different cases:
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // proceed
+}
+```
+
+### Layer 3: Environment Guards
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // proceed
+}
+```
+
+## Applying the Pattern
+
+When find bug:
+
+1. **Trace data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Example from Real Session
+
+Bug: Empty `projectDir` caused `git init` in source code
+
+**Data flow:**
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` runs in `process.cwd()`
+
+**Four layers added:**
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed, bug impossible to reproduce
+
+## Key Insight
+
+All four layers were necessary. During testing, each layer caught bugs others missed:
+- Different code paths bypassed entry validation
+- Mocks bypassed business logic checks
+- Edge cases on different platforms needed environment guards
+- Debug logging identified structural misuse
+
+**Don't stop at one validation point.** Add checks at every layer.

package/dist/presets/mobile/skills/debugging/references/root-cause-tracing.md

@@ -0,0 +1,122 @@
+# Root Cause Tracing
+
+Systematically trace bugs backward through call stack to find original trigger.
+
+## Core Principle
+
+**Trace backward through call chain until finding original trigger, then fix at source.**
+
+Bugs often manifest deep in call stack (git init in wrong directory, file created in wrong location). Instinct is to fix where error appears, but that's treating symptom.
+
+## When to Use
+
+**Use when:**
+- Error happens deep in execution (not at entry point)
+- Stack trace shows long call chain
+- Unclear where invalid data originated
+- Need to find which test/code triggers problem
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in /Users/jesse/project/packages/core
+```
+
+### 2. Find Immediate Cause
+What code directly causes this?
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+What value was passed?
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+Where did empty string come from?
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+When can't trace manually, add instrumentation:
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- Look for test file names
+- Find line number triggering call
+- Identify pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but don't know which test:
+
+Use bisection script: `scripts/find-polluter.sh`
+
+```bash
+./scripts/find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Runs tests one-by-one, stops at first polluter.
+
+## Key Principle
+
+**NEVER fix just where error appears.** Trace back to find original trigger.
+
+When found immediate cause:
+- Can trace one level up? → Trace backwards
+- Is this the source? → Fix at source
+- Then add validation at each layer (see defense-in-depth.md)
+
+## Real Example
+
+**Symptom:** `.git` created in `packages/core/` (source code)
+
+**Trace chain:**
+1. `git init` runs in `process.cwd()` ← empty cwd parameter
+2. WorktreeManager called with empty projectDir
+3. Session.create() passed empty string
+4. Test accessed `context.tempDir` before beforeEach
+5. setupCoreTest() returns `{ tempDir: '' }` initially
+
+**Root cause:** Top-level variable initialization accessing empty value
+
+**Fix:** Made tempDir a getter that throws if accessed before beforeEach
+
+**Also added defense-in-depth:**
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init

package/dist/presets/mobile/skills/debugging/references/systematic-debugging.md

@@ -0,0 +1,102 @@
+# Systematic Debugging
+
+Four-phase debugging framework that ensures root cause investigation before attempting fixes.
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If haven't completed Phase 1, cannot propose fixes.
+
+## The Four Phases
+
+Must complete each phase before proceeding to next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully** - Don't skip past errors/warnings, read stack traces completely
+2. **Reproduce Consistently** - Can trigger reliably? Exact steps? If not reproducible → gather more data
+3. **Check Recent Changes** - What changed? Git diff, recent commits, new dependencies, config changes
+4. **Gather Evidence in Multi-Component Systems**
+   - For EACH component boundary: log data entering/exiting, verify environment propagation
+   - Run once to gather evidence showing WHERE it breaks
+   - THEN analyze to identify failing component
+5. **Trace Data Flow** - Where does bad value originate? Trace up call stack until finding source (see root-cause-tracing.md)
+
+### Phase 2: Pattern Analysis
+
+**Find pattern before fixing:**
+
+1. **Find Working Examples** - Locate similar working code in same codebase
+2. **Compare Against References** - Read reference implementation COMPLETELY, understand fully before applying
+3. **Identify Differences** - List every difference however small, don't assume "that can't matter"
+4. **Understand Dependencies** - What other components, settings, config, environment needed?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis** - "I think X is root cause because Y", be specific not vague
+2. **Test Minimally** - SMALLEST possible change to test hypothesis, one variable at a time
+3. **Verify Before Continuing** - Worked? → Phase 4. Didn't work? → NEW hypothesis. DON'T add more fixes
+4. **When Don't Know** - Say "I don't understand X", don't pretend, ask for help
+
+### Phase 4: Implementation
+
+**Fix root cause, not symptom:**
+
+1. **Create Failing Test Case** - Simplest reproduction, automated if possible, MUST have before fixing
+2. **Implement Single Fix** - Address root cause identified, ONE change, no "while I'm here" improvements
+3. **Verify Fix** - Test passes? No other tests broken? Issue actually resolved?
+4. **If Fix Doesn't Work**
+   - STOP. Count: How many fixes tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question architecture**
+5. **If 3+ Fixes Failed: Question Architecture**
+   - Pattern: Each fix reveals new shared state/coupling problem elsewhere
+   - STOP and question fundamentals: Is pattern sound? Wrong architecture?
+   - Discuss with human partner before more fixes
+
+## Red Flags - STOP and Follow Process
+
+If catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "One more fix attempt" (when already tried 2+)
+
+**ALL mean:** STOP. Return to Phase 1.
+
+## Human Partner Signals You're Doing It Wrong
+
+- "Is that not happening?" - Assumed without verifying
+- "Will it show us...?" - Should have added evidence gathering
+- "Stop guessing" - Proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Approach isn't working
+
+**When see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too |
+| "Emergency, no time for process" | Systematic is FASTER than guess-and-check |
+| "Just try this first, then investigate" | First fix sets pattern. Do right from start |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem |
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common