aiwcli 0.10.2 → 0.11.0

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

@@ -1,358 +0,0 @@
-"""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_auto_state_path(context_id: str, project_root: Path = None) -> Path:
-    """
-    Get the auto-state.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}/auto-state.json
-    """
-    return get_context_dir(context_id, project_root) / "auto-state.json"
-
-
-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
-
-
-def get_handoff_folder_path(context_id: str, project_root: Path = None) -> Path:
-    """Get path for a new handoff folder with datetime naming.
-
-    Returns: _output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/
-    Handles collisions by appending -N suffix if folder exists.
-
-    Args:
-        context_id: Context identifier
-        project_root: Project root directory (default: cwd)
-
-    Returns:
-        Path to new handoff folder (not yet created)
-    """
-    from datetime import datetime
-    handoffs_dir = get_context_handoffs_dir(context_id, project_root)
-    timestamp = datetime.now().strftime("%Y-%m-%d-%H%M")
-    folder = handoffs_dir / timestamp
-
-    counter = 1
-    while folder.exists():
-        folder = handoffs_dir / f"{timestamp}-{counter}"
-        counter += 1
-
-    return folder
-
-
-def get_review_folder_path(context_id: str, iteration: int, project_root: Path = None) -> Path:
-    """Get path for a new review folder with datetime and iteration naming.
-
-    Returns: _output/contexts/{context_id}/reviews/cc-native/{YYYY-MM-DD-HHMM-iteration-N}/
-
-    Args:
-        context_id: Context identifier
-        iteration: Iteration number (1-based)
-        project_root: Project root directory (default: cwd)
-
-    Returns:
-        Path to new review folder (not yet created)
-    """
-    from datetime import datetime
-    reviews_dir = get_context_reviews_dir(context_id, project_root) / "cc-native"
-    timestamp = datetime.now().strftime("%Y-%m-%d-%H%M")
-    return reviews_dir / f"{timestamp}-iteration-{iteration}"

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

@@ -1,341 +0,0 @@
-"""Common utilities for hook scripts.
-
-Provides standardized boilerplate for:
-- Path setup for imports
-- JSON parsing from stdin
-- Hook payload validation
-- Error handling decorators
-"""
-
-import json
-import os
-import sys
-from datetime import datetime, timezone
-from functools import wraps
-from pathlib import Path
-from typing import Any, Callable, Dict, Optional, TypeVar
-
-from .logger import log_hook_error, hook_log, log_debug, log_info, log_warn, log_error, log_diagnostic, set_context_path, _get_context_path
-
-
-# Context window baseline: tokens not visible in hook data
-# (system prompt, tools, MCP tokens)
-# See: https://github.com/anthropics/claude-code/issues/13783
-CONTEXT_BASELINE_TOKENS = 22_600
-DEFAULT_CONTEXT_WINDOW_SIZE = 200_000
-
-
-def parse_context_window(hook_input: dict) -> tuple:
-    """Parse context window from hook input.
-
-    Returns (tokens_used, max_tokens) or (None, None).
-    tokens_used includes baseline offset for system prompt/tools.
-    """
-    context_window = hook_input.get("context_window")
-    if not context_window:
-        return None, None
-    current_usage = context_window.get("current_usage")
-    if not current_usage:
-        return None, None
-    cache_read = current_usage.get("cache_read_input_tokens", 0) or 0
-    input_tokens = current_usage.get("input_tokens", 0) or 0
-    cache_creation = current_usage.get("cache_creation_input_tokens", 0) or 0
-    output_tokens = current_usage.get("output_tokens", 0) or 0
-    content_tokens = cache_read + input_tokens + cache_creation + output_tokens
-    tokens_used = content_tokens + CONTEXT_BASELINE_TOKENS
-    max_tokens = context_window.get("context_window_size") or DEFAULT_CONTEXT_WINDOW_SIZE
-    return tokens_used, max_tokens
-
-
-def get_context_percent_remaining(hook_input: dict) -> tuple:
-    """Get context percentage remaining with context.json fallback.
-
-    Tries two sources in order:
-    1. Hook input context_window data (most accurate, real-time)
-    2. context.json remaining_percentage (written by status_line.py)
-
-    Returns:
-        (percent_remaining, tokens_used, max_tokens) where tokens_used and
-        max_tokens may be None if data came from context.json fallback.
-        Returns (None, None, None) if no data available from either source.
-    """
-    # Source 1: Hook input (most accurate)
-    tokens_used, max_tokens = parse_context_window(hook_input)
-    if tokens_used is not None and max_tokens is not None and max_tokens > 0:
-        remaining = max_tokens - tokens_used
-        percent_remaining = max(0, min(100, int((remaining / max_tokens) * 100)))
-        return percent_remaining, tokens_used, max_tokens
-
-    # Source 2: context.json fallback (written by status_line.py)
-    try:
-        from .utils import project_dir
-        from ..context.context_store import get_context_by_session_id
-
-        session_id = hook_input.get("session_id")
-        if session_id:
-            project_root = project_dir(hook_input)
-            context = get_context_by_session_id(session_id, project_root)
-            if context and context.last_session:
-                pct = context.last_session.get("context_remaining_pct")
-                if pct is not None:
-                    return pct, None, None
-    except Exception:
-        pass  # Fallback failed — degrade gracefully
-
-    return None, None, None
-
-
-# Type variable for generic decorators
-F = TypeVar('F', bound=Callable[..., Any])
-
-# Event metadata stash — populated by load_hook_input(), read by run_hook()
-_last_hook_event: Optional[str] = None
-_last_tool_name: Optional[str] = None
-
-
-def load_hook_input() -> Optional[Dict[str, Any]]:
-    """
-    Load and parse JSON from stdin.
-
-    Returns:
-        Parsed JSON dict, or None if stdin is empty or invalid JSON
-    """
-    global _last_hook_event, _last_tool_name
-    try:
-        input_data = sys.stdin.read().strip()
-        if not input_data:
-            return None
-        result = json.loads(input_data)
-        if isinstance(result, dict):
-            _last_hook_event = result.get("hook_event_name")
-            _last_tool_name = result.get("tool_name")
-        return result
-    except json.JSONDecodeError:
-        return None
-
-
-def validate_hook_event(
-    payload: Dict[str, Any],
-    expected_event: str,
-    expected_tool: Optional[str] = None
-) -> bool:
-    """
-    Validate hook event type and optional tool name.
-
-    Args:
-        payload: Hook payload from stdin
-        expected_event: Expected hook_event_name (e.g., "PostToolUse", "PreToolUse")
-        expected_tool: Optional expected tool_name (e.g., "TaskCreate")
-
-    Returns:
-        True if payload matches expected event/tool, False otherwise
-    """
-    if payload.get("hook_event_name") != expected_event:
-        return False
-    if expected_tool and payload.get("tool_name") != expected_tool:
-        return False
-    return True
-
-
-def get_tool_input(payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-    """
-    Extract and validate tool_input from payload.
-
-    Args:
-        payload: Hook payload from stdin
-
-    Returns:
-        tool_input dict, or None if missing/invalid
-    """
-    tool_input = payload.get("tool_input", {})
-    return tool_input if isinstance(tool_input, dict) else None
-
-
-def check_skip_persistence(payload: Dict[str, Any], hook_name: str = "hook") -> bool:
-    """
-    Check if persistence should be skipped based on metadata flags.
-
-    Args:
-        payload: Hook payload from stdin
-        hook_name: Name of hook for logging
-
-    Returns:
-        True if skip_persistence flag is set, False otherwise
-    """
-    tool_input = get_tool_input(payload)
-    if not tool_input:
-        return False
-
-    metadata = tool_input.get("metadata", {})
-    if isinstance(metadata, dict) and metadata.get("skip_persistence"):
-        log_debug(hook_name, "Skipping persistence (skip_persistence flag set)")
-        return True
-    return False
-
-
-def safe_hook_main(hook_name: str) -> Callable[[F], F]:
-    """
-    Decorator for hook main functions with standard error handling.
-
-    Catches exceptions, logs them to stderr, and returns 0 (non-blocking).
-
-    Args:
-        hook_name: Name of hook for error messages
-
-    Returns:
-        Decorator function
-
-    Example:
-        @safe_hook_main("my_hook")
-        def main() -> int:
-            # ... hook logic ...
-            return 0
-    """
-    def decorator(func: F) -> F:
-        @wraps(func)
-        def wrapper(*args, **kwargs):
-            try:
-                return func(*args, **kwargs)
-            except json.JSONDecodeError as e:
-                import traceback
-                tb = traceback.format_exc()
-                log_hook_error(hook_name, e, traceback_str=tb)
-                log_error(hook_name, f"JSON decode error: {e}")
-                return 0
-            except Exception as e:
-                import traceback
-                tb = traceback.format_exc()
-                log_hook_error(hook_name, e, traceback_str=tb)
-                log_error(hook_name, f"Unexpected error: {e}", traceback_str=tb)
-                return 0
-        return wrapper  # type: ignore
-    return decorator
-
-
-def emit_context(additional_context: str, ensure_ascii: bool = False) -> None:
-    """Emit hookSpecificOutput with additionalContext to stdout.
-
-    Args:
-        additional_context: Context string to inject into Claude's context
-        ensure_ascii: If True, escape non-ASCII characters in JSON output
-    """
-    out = {
-        "hookSpecificOutput": {
-            "additionalContext": additional_context,
-        }
-    }
-    print(json.dumps(out, ensure_ascii=ensure_ascii))
-
-
-def emit_context_and_block(
-    additional_context: str,
-    reason: str,
-    ensure_ascii: bool = True,
-) -> None:
-    """Emit hookSpecificOutput that denies the tool call with context and reason.
-
-    Args:
-        additional_context: Context string to inject into Claude's context
-        reason: Reason shown to Claude for why the tool call was denied
-        ensure_ascii: If True, escape non-ASCII characters in JSON output
-    """
-    out = {
-        "hookSpecificOutput": {
-            "additionalContext": additional_context,
-            "permissionDecision": "deny",
-            "permissionDecisionReason": reason,
-        }
-    }
-    print(json.dumps(out, ensure_ascii=ensure_ascii))
-
-
-def _detect_template(script_path: str = "") -> str:
-    """Auto-detect template origin from the hook script path.
-
-    Returns "shared", a template name (e.g., "cc-native"), or "unknown".
-    """
-    import re
-    path = (script_path or (sys.argv[0] if sys.argv else "")).replace("\\", "/")
-    if "/_shared/hooks/" in path or path.startswith("_shared/hooks/"):
-        return "shared"
-    match = re.search(r'_([a-z][a-z0-9-]*)/hooks/', path)
-    if match:
-        return match.group(1)  # e.g., "cc-native"
-    return "unknown"
-
-
-def run_hook(main_func: Callable[[], int], hook_name: str = "unknown") -> None:
-    """
-    Standard hook entry point wrapper with lifecycle logging.
-
-    Logs HOOK_START before calling main, HOOK_END after completion.
-    Catches unhandled exceptions and logs them before exiting cleanly.
-
-    Args:
-        main_func: Hook main function that returns exit code
-        hook_name: Name of the hook for error logging
-
-    Example:
-        if __name__ == "__main__":
-            run_hook(main, "my_hook")
-    """
-    import time
-    start_time = time.monotonic()
-    template = _detect_template()
-    event = _last_hook_event or "unknown"
-    tool = _last_tool_name
-
-    # HOOK_START
-    start_data: Dict[str, Any] = {"lifecycle": "start", "template": template, "event": event}
-    if tool:
-        start_data["tool"] = tool
-    log_info(hook_name, "HOOK_START", data=start_data)
-
-    exit_code = 0
-    status = "success"
-    error_info = None
-
-    try:
-        result = main_func()
-        exit_code = result if isinstance(result, int) else 0
-        status = "blocked" if exit_code != 0 else "success"
-    except SystemExit as e:
-        exit_code = e.code if isinstance(e.code, int) else (1 if e.code else 0)
-        status = "blocked" if exit_code != 0 else "success"
-    except Exception as e:
-        import traceback
-        exit_code = 0  # Non-blocking
-        status = "error"
-        error_info = (e, traceback.format_exc())
-
-    # Retroactive HOOK_START: if main() set a context path, re-emit HOOK_START
-    # to the per-context log (original HOOK_START went to global log before
-    # context was resolved).
-    resolved_after = _get_context_path()
-    if resolved_after and resolved_after.exists():
-        hook_log("info", hook_name, "HOOK_START", data=start_data,
-                 context_path=resolved_after, stderr=False)
-
-    # HOOK_END
-    duration_ms = round((time.monotonic() - start_time) * 1000, 1)
-    end_data: Dict[str, Any] = {
-        "lifecycle": "end", "status": status,
-        "duration_ms": duration_ms, "exit_code": exit_code,
-        "template": template,
-    }
-    end_event = _last_hook_event or event  # Re-read after main() populated it
-    end_tool = _last_tool_name or tool
-    end_data["event"] = end_event
-    if end_tool:
-        end_data["tool"] = end_tool
-    if error_info:
-        e, tb = error_info
-        end_data["error_type"] = type(e).__name__
-        log_hook_error(hook_name, e, traceback_str=tb)
-        log_error(hook_name, f"HOOK_END: {e}", data=end_data, traceback_str=tb)
-    elif status == "blocked":
-        log_warn(hook_name, "HOOK_END", data=end_data)
-    else:
-        log_info(hook_name, "HOOK_END", data=end_data)
-
-    raise SystemExit(exit_code)