aiwcli 0.9.0

package/dist/templates/_shared/lib/base/constants.py

@@ -0,0 +1,299 @@
+"""Constants and path utilities for shared context management.
+
+Data hierarchy:
+  events.jsonl (source of truth)
+    → context.json (L1 cache)
+      → index.json (L2 cache)
+
+All data written to _output/contexts/ (method-agnostic).
+No method subfolders - method is just metadata on the context.
+"""
+import os
+import re
+from pathlib import Path
+
+# Directory names (relative to project root)
+OUTPUT_DIR = "_output"
+CONTEXTS_DIR = "contexts"
+ARCHIVE_DIR = "archive"
+INDEX_FILENAME = "index.json"
+
+# Context ID validation
+MAX_CONTEXT_ID_LENGTH = 64
+VALID_CONTEXT_ID_PATTERN = re.compile(r'^[a-z0-9][a-z0-9_-]*[a-z0-9]$|^[a-z0-9]$')
+
+# File size limits
+MAX_EVENT_SIZE = 64 * 1024  # 64KB per event (reasonable limit)
+MAX_INDEX_SIZE = 1024 * 1024  # 1MB for index.json
+
+# Performance constants
+MAX_RETRY_ATTEMPTS = 2
+RETRY_BACKOFF_MS = [500, 1000]
+
+
+def sanitize_context_id(context_id: str) -> str:
+    """
+    Sanitize a string into a valid context ID.
+
+    Performs these transformations:
+    - Convert to lowercase
+    - Replace invalid characters with hyphens
+    - Collapse consecutive hyphens/underscores
+    - Strip leading/trailing non-alphanumeric
+    - Truncate to MAX_CONTEXT_ID_LENGTH
+
+    Args:
+        context_id: Raw input string
+
+    Returns:
+        Valid context ID string, or "context" if input is empty/invalid
+    """
+    if not context_id:
+        return "context"
+
+    # Normalize to lowercase
+    result = context_id.lower()
+
+    # Replace any character that's not alphanumeric, hyphen, or underscore
+    result = re.sub(r'[^a-z0-9_-]', '-', result)
+
+    # Collapse consecutive hyphens/underscores into single hyphen
+    result = re.sub(r'[-_]+', '-', result)
+
+    # Strip leading/trailing non-alphanumeric
+    result = result.strip('-_')
+
+    # Truncate to max length
+    if len(result) > MAX_CONTEXT_ID_LENGTH:
+        result = result[:MAX_CONTEXT_ID_LENGTH].rstrip('-_')
+
+    # If nothing left, return default
+    return result if result else "context"
+
+
+def validate_context_id(context_id: str) -> str:
+    """
+    Validate and normalize context ID.
+
+    Auto-sanitizes invalid input instead of throwing errors for format issues.
+    Only throws for security violations (path traversal).
+
+    Valid context IDs:
+    - 1-64 characters
+    - lowercase alphanumeric, hyphens, underscores
+    - must start and end with alphanumeric
+    - no consecutive hyphens/underscores
+
+    Raises:
+        ValueError: Only for path traversal attempts
+    """
+    if not context_id:
+        return "context"
+
+    # SECURITY: Check for path traversal BEFORE any normalization
+    # This prevents encoded or case-variant attacks
+    if '..' in context_id or '/' in context_id or '\\' in context_id:
+        raise ValueError(f"Invalid context ID '{context_id}': path traversal not allowed")
+
+    # Also check for URL-encoded variants
+    if '%2e' in context_id.lower() or '%2f' in context_id.lower() or '%5c' in context_id.lower():
+        raise ValueError(f"Invalid context ID '{context_id}': encoded path traversal not allowed")
+
+    # Sanitize instead of throwing for format issues
+    sanitized = sanitize_context_id(context_id)
+
+    return sanitized
+
+
+def get_output_dir(project_root: Path = None) -> Path:
+    """
+    Get the output directory path.
+
+    Args:
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/
+    """
+    if project_root is None:
+        project_root = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+    return Path(project_root) / OUTPUT_DIR
+
+
+def get_contexts_dir(project_root: Path = None) -> Path:
+    """
+    Get the contexts directory path.
+
+    Args:
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/contexts/
+    """
+    return get_output_dir(project_root) / CONTEXTS_DIR
+
+
+def get_context_dir(context_id: str, project_root: Path = None) -> Path:
+    """
+    Get the directory path for a specific context.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/contexts/{context_id}/
+
+    Raises:
+        ValueError: If context_id is invalid or path escapes expected directory
+    """
+    validated_id = validate_context_id(context_id)
+    contexts_dir = get_contexts_dir(project_root)
+    result_path = contexts_dir / validated_id
+
+    # SECURITY: Verify resolved path stays within contexts directory
+    # This prevents symlink attacks and any path manipulation we might have missed
+    try:
+        resolved = result_path.resolve()
+        contexts_resolved = contexts_dir.resolve()
+        # Check that resolved path starts with the contexts directory
+        # Use os.path for cross-platform compatibility
+        import os
+        resolved_str = os.path.normcase(str(resolved))
+        contexts_str = os.path.normcase(str(contexts_resolved))
+        if not resolved_str.startswith(contexts_str):
+            raise ValueError(f"Invalid context ID '{context_id}': path escapes contexts directory")
+    except (OSError, ValueError) as e:
+        if isinstance(e, ValueError):
+            raise
+        # OSError can occur if path doesn't exist yet, which is fine for creation
+        pass
+
+    return result_path
+
+
+def get_context_plans_dir(context_id: str, project_root: Path = None) -> Path:
+    """
+    Get the plans directory for a specific context.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/contexts/{context_id}/plans/
+    """
+    return get_context_dir(context_id, project_root) / "plans"
+
+
+def get_context_handoffs_dir(context_id: str, project_root: Path = None) -> Path:
+    """
+    Get the handoffs directory for a specific context.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/contexts/{context_id}/handoffs/
+    """
+    return get_context_dir(context_id, project_root) / "handoffs"
+
+
+def get_context_reviews_dir(context_id: str, project_root: Path = None) -> Path:
+    """
+    Get the reviews directory for a specific context.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/contexts/{context_id}/reviews/
+    """
+    return get_context_dir(context_id, project_root) / "reviews"
+
+
+def get_index_path(project_root: Path = None) -> Path:
+    """
+    Get the global index file path.
+
+    Args:
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/index.json
+    """
+    return get_output_dir(project_root) / INDEX_FILENAME
+
+
+def get_context_file_path(context_id: str, project_root: Path = None) -> Path:
+    """
+    Get the context.json file path for a specific context.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/contexts/{context_id}/context.json
+    """
+    return get_context_dir(context_id, project_root) / "context.json"
+
+
+def get_events_file_path(context_id: str, project_root: Path = None) -> Path:
+    """
+    Get the events.jsonl file path for a specific context.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/contexts/{context_id}/events.jsonl
+    """
+    return get_context_dir(context_id, project_root) / "events.jsonl"
+
+
+def get_archive_dir(project_root: Path = None) -> Path:
+    """
+    Get the archive directory path.
+
+    Args:
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/contexts/archive/
+    """
+    return get_contexts_dir(project_root) / ARCHIVE_DIR
+
+
+def get_archive_context_dir(context_id: str, project_root: Path = None) -> Path:
+    """
+    Get the archive directory for a specific context.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/contexts/archive/{context_id}/
+
+    Raises:
+        ValueError: If context_id is invalid
+    """
+    validated_id = validate_context_id(context_id)
+    return get_archive_dir(project_root) / validated_id
+
+
+def get_archive_index_path(project_root: Path = None) -> Path:
+    """
+    Get the archive index file path.
+
+    Args:
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/contexts/archive/index.json
+    """
+    return get_archive_dir(project_root) / INDEX_FILENAME

package/dist/templates/_shared/lib/base/inference.py

@@ -0,0 +1,189 @@
+"""Inference utility for AI-powered text processing.
+
+Provides a unified interface for Claude API calls using the claude CLI.
+Supports multiple model tiers: fast (Haiku), standard (Sonnet), smart (Opus).
+"""
+import subprocess
+import sys
+import os
+from typing import Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class InferenceResult:
+    """Result from an inference call."""
+    success: bool
+    output: str
+    error: Optional[str] = None
+    latency_ms: int = 0
+
+
+# Model configurations
+MODELS = {
+    "fast": "claude-3-haiku-20240307",
+    "standard": "claude-sonnet-4-20250514",
+    "smart": "claude-opus-4-20250514",
+}
+
+TIMEOUTS = {
+    "fast": 15,      # 15 seconds
+    "standard": 30,  # 30 seconds
+    "smart": 90,     # 90 seconds
+}
+
+
+def inference(
+    system_prompt: str,
+    user_prompt: str,
+    level: str = "fast",
+    timeout: Optional[int] = None,
+) -> InferenceResult:
+    """
+    Run inference using the claude CLI.
+
+    Args:
+        system_prompt: System instructions for the model
+        user_prompt: User message to process
+        level: Model level - "fast" (Haiku), "standard" (Sonnet), "smart" (Opus)
+        timeout: Custom timeout in seconds (uses level default if not specified)
+
+    Returns:
+        InferenceResult with success status, output, and any error
+    """
+    import time
+    start_time = time.time()
+
+    model = MODELS.get(level, MODELS["fast"])
+    timeout_sec = timeout or TIMEOUTS.get(level, TIMEOUTS["fast"])
+
+    # Combine prompts
+    full_prompt = f"{system_prompt}\n\n{user_prompt}"
+
+    # Build command
+    cmd = [
+        "claude",
+        "--model", model,
+        "--print",
+        "--no-hooks",
+        "-p", full_prompt,
+    ]
+
+    # Remove ANTHROPIC_API_KEY to force subscription auth
+    env = os.environ.copy()
+    env.pop("ANTHROPIC_API_KEY", None)
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout_sec,
+            env=env,
+            # Windows needs shell=True for command resolution
+            shell=(sys.platform == "win32"),
+        )
+
+        latency_ms = int((time.time() - start_time) * 1000)
+
+        if result.returncode != 0:
+            return InferenceResult(
+                success=False,
+                output=result.stdout.strip() if result.stdout else "",
+                error=result.stderr.strip() if result.stderr else f"Exit code: {result.returncode}",
+                latency_ms=latency_ms,
+            )
+
+        return InferenceResult(
+            success=True,
+            output=result.stdout.strip(),
+            latency_ms=latency_ms,
+        )
+
+    except subprocess.TimeoutExpired:
+        latency_ms = int((time.time() - start_time) * 1000)
+        return InferenceResult(
+            success=False,
+            output="",
+            error=f"Timeout after {timeout_sec}s",
+            latency_ms=latency_ms,
+        )
+    except FileNotFoundError:
+        latency_ms = int((time.time() - start_time) * 1000)
+        return InferenceResult(
+            success=False,
+            output="",
+            error="claude CLI not found",
+            latency_ms=latency_ms,
+        )
+    except Exception as e:
+        latency_ms = int((time.time() - start_time) * 1000)
+        return InferenceResult(
+            success=False,
+            output="",
+            error=str(e),
+            latency_ms=latency_ms,
+        )
+
+
+# System prompt for generating context ID summaries
+CONTEXT_ID_SYSTEM_PROMPT = """Generate a 10-word summary of what the user wants to do. Start with a gerund (verb ending in -ing).
+
+Rules:
+- Exactly 10 words
+- Start with gerund: Creating, Fixing, Adding, Updating, Implementing, etc.
+- Be specific about the task
+- No punctuation
+- No quotes
+
+Examples:
+- "I want to add user authentication" -> "Adding user authentication with JWT tokens to the web app"
+- "Fix the bug in the login flow" -> "Fixing critical bug in user login flow validation logic"
+- "Can you help me refactor this code" -> "Refactoring legacy code for better maintainability and cleaner architecture"
+- "Update the README with new instructions" -> "Updating README with new setup instructions and configuration examples"
+
+Output ONLY the 10-word summary, nothing else."""
+
+
+def generate_semantic_summary(prompt: str, timeout: int = 15) -> Optional[str]:
+    """
+    Generate a semantic 10-word summary of a user prompt.
+
+    Uses Sonnet for quality inference. Returns None if inference fails.
+
+    Args:
+        prompt: User prompt to summarize
+        timeout: Timeout in seconds (default 15)
+
+    Returns:
+        10-word summary string or None if failed
+    """
+    # Pass full prompt - AI can summarize any length into 10 words
+    result = inference(
+        system_prompt=CONTEXT_ID_SYSTEM_PROMPT,
+        user_prompt=prompt,
+        level="standard",
+        timeout=timeout,
+    )
+
+    if not result.success or not result.output:
+        return None
+
+    # Clean up the output
+    summary = result.output.strip()
+    # Remove any quotes
+    summary = summary.strip('"\'')
+    # Remove trailing punctuation
+    summary = summary.rstrip('.!?')
+
+    # Validate it starts with a gerund (capital letter + letters + "ing")
+    import re
+    if not re.match(r'^[A-Z][a-z]*ing\b', summary):
+        return None
+
+    # Validate roughly 10 words (allow 8-12 for flexibility)
+    words = summary.split()
+    if len(words) < 8 or len(words) > 12:
+        return None
+
+    return summary

package/dist/templates/_shared/lib/base/utils.py

@@ -0,0 +1,216 @@
+"""Core utilities for shared context management.
+
+Provides common functions used across all shared modules:
+- eprint: Print to stderr
+- now_local: Get current local datetime
+- project_dir: Get project directory from environment
+- sanitize_filename: Sanitize string for use in filenames
+- generate_context_id: Generate a slug from summary text
+"""
+import os
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+def eprint(*args: Any) -> None:
+    """Print to stderr."""
+    print(*args, file=sys.stderr)
+
+
+def now_local() -> datetime:
+    """Get current local datetime."""
+    return datetime.now()
+
+
+def now_iso() -> str:
+    """Get current time as ISO 8601 string."""
+    return datetime.now().isoformat()
+
+
+def project_dir(payload: Optional[Dict[str, Any]] = None) -> Path:
+    """
+    Get project directory from payload or environment.
+
+    Priority:
+    1. CLAUDE_PROJECT_DIR environment variable
+    2. 'cwd' from payload (if provided)
+    3. Current working directory
+
+    Args:
+        payload: Optional hook payload with 'cwd' field
+
+    Returns:
+        Path to project directory
+
+    Note:
+        CLAUDE_PROJECT_DIR is validated to be an absolute path when provided.
+    """
+    p = os.environ.get("CLAUDE_PROJECT_DIR")
+    if p:
+        # Validate that CLAUDE_PROJECT_DIR is an absolute path
+        path = Path(p)
+        if not path.is_absolute():
+            eprint(f"[utils] WARNING: CLAUDE_PROJECT_DIR is not absolute, using cwd instead")
+            p = None
+        else:
+            # Check for suspicious patterns
+            if '..' in str(path):
+                eprint(f"[utils] WARNING: CLAUDE_PROJECT_DIR contains '..' pattern, using cwd instead")
+                p = None
+
+    if not p and payload:
+        p = payload.get("cwd")
+    if not p:
+        p = os.getcwd()
+    return Path(p)
+
+
+# Windows reserved filenames that should be blocked
+_WINDOWS_RESERVED = frozenset([
+    'CON', 'PRN', 'AUX', 'NUL',
+    'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+    'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
+])
+
+
+def sanitize_filename(s: str, max_len: int = 32, allow_leading_dot: bool = False) -> str:
+    """
+    Sanitize string for use in filename.
+
+    Replaces non-alphanumeric characters (except ._-) with underscores,
+    strips leading/trailing special characters, and truncates.
+
+    Args:
+        s: Input string
+        max_len: Maximum length (default: 32)
+        allow_leading_dot: Whether to allow leading dots (default: False for security)
+
+    Returns:
+        Sanitized filename-safe string
+    """
+    s = re.sub(r"[^A-Za-z0-9._-]+", "_", s)
+    result = s.strip("._-")[:max_len] or "unknown"
+
+    # Remove leading dots unless explicitly allowed (prevents hidden files)
+    if not allow_leading_dot:
+        result = result.lstrip('.')
+
+    # Check for Windows reserved names
+    base_name = result.split('.')[0].upper()
+    if base_name in _WINDOWS_RESERVED:
+        result = f"_{result}"
+
+    return result or "unknown"
+
+
+def sanitize_title(s: str, max_len: int = 50) -> str:
+    """
+    Sanitize title for use in context ID or filename.
+
+    Converts spaces to hyphens, replaces special characters,
+    and normalizes to lowercase.
+
+    Args:
+        s: Input string
+        max_len: Maximum length (default: 50)
+
+    Returns:
+        Sanitized slug-like string
+    """
+    s = s.lower().strip()
+    s = s.replace(' ', '-')
+    s = re.sub(r"[^a-z0-9._-]+", "_", s)
+    s = re.sub(r"[-_]+", "-", s)
+    result = s.strip("._-")[:max_len] or "unknown"
+
+    # Check for Windows reserved names
+    base_name = result.split('.')[0].upper()
+    if base_name in _WINDOWS_RESERVED:
+        result = f"_{result}"
+
+    return result or "unknown"
+
+
+def generate_context_id(summary: str, existing_ids: Optional[set] = None) -> str:
+    """
+    Generate a context ID from a summary string.
+
+    Uses AI inference to create a semantic 10-word summary, then slugifies it.
+    Falls back to truncate-and-slugify if inference fails.
+
+    Args:
+        summary: Context summary text
+        existing_ids: Optional set of existing context IDs to avoid
+
+    Returns:
+        Unique context ID string
+    """
+    if not summary or not summary.strip():
+        base_id = "context"
+    else:
+        # Try AI-powered semantic summary first
+        base_id = None
+        try:
+            from .inference import generate_semantic_summary
+            semantic = generate_semantic_summary(summary)
+            if semantic:
+                # Slugify the semantic summary
+                base_id = sanitize_title(semantic, max_len=60)
+                eprint(f"[utils] Semantic context ID: {base_id}")
+        except Exception as e:
+            eprint(f"[utils] Inference failed, using fallback: {e}")
+
+        # Fallback to old method if inference failed
+        if not base_id:
+            base_id = sanitize_title(summary[:50])
+
+    if not existing_ids:
+        return base_id
+
+    # Ensure uniqueness by appending counter if needed
+    if base_id not in existing_ids:
+        return base_id
+
+    counter = 2
+    while f"{base_id}-{counter}" in existing_ids:
+        counter += 1
+
+    return f"{base_id}-{counter}"
+
+
+def format_timestamp(dt: Optional[datetime] = None) -> str:
+    """
+    Format datetime for display.
+
+    Args:
+        dt: Datetime to format (default: now)
+
+    Returns:
+        Formatted string like "2026-01-25 10:30:00"
+    """
+    if dt is None:
+        dt = now_local()
+    return dt.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def parse_iso_timestamp(iso_str: str) -> Optional[datetime]:
+    """
+    Parse ISO 8601 timestamp string.
+
+    Args:
+        iso_str: ISO format timestamp
+
+    Returns:
+        datetime object or None if parsing fails
+    """
+    try:
+        # Handle both with and without microseconds
+        if '.' in iso_str:
+            return datetime.fromisoformat(iso_str)
+        else:
+            return datetime.fromisoformat(iso_str.replace('Z', '+00:00'))
+    except (ValueError, TypeError):
+        return None