aiwcli 0.10.2 → 0.11.0

package/dist/templates/_shared/lib/context/plan_manager.py

@@ -1,204 +0,0 @@
-"""Plan lifecycle management — archival, lookup, and path extraction.
-
-Provides pure-data operations on plan files:
-- archive_plan: copy plan to context plans/ folder, compute hash + signature
-- find_latest_plan: locate the most relevant plan for a context
-- extract_plan_path_from_result: parse plan path from ExitPlanMode output
-
-This module does NOT modify mode or state.json.  The calling hook
-(e.g. archive_plan.py) is responsible for updating mode via
-context_store.update_mode() after archival succeeds.
-"""
-import hashlib
-import re
-import uuid
-from datetime import datetime
-from pathlib import Path
-from typing import List, Optional, Tuple
-
-from ..base.atomic_write import atomic_write
-from ..base.constants import get_context_dir, get_context_plans_dir
-from ..base.logger import log_debug, log_info, log_warn, log_error
-from ..base.utils import sanitize_title
-
-
-# ---------------------------------------------------------------------------
-# Plan archival
-# ---------------------------------------------------------------------------
-
-def archive_plan(
-    plan_path: str,
-    context_id: str,
-    project_root: Path = None,
-) -> Tuple[Optional[str], Optional[str], Optional[str]]:
-    """Archive a plan file to the context's plans/ folder.
-
-    Copies the plan content to:
-        _output/contexts/{context_id}/plans/{date}-{slug}.md
-
-    Computes a content hash and signature for change detection and
-    fallback matching after /clear.
-
-    Does NOT modify state.json or mode — the calling hook handles that
-    via context_store.update_mode().
-
-    Args:
-        plan_path: Path to the source plan file.
-        context_id: Target context identifier.
-        project_root: Project root directory (default: from env / cwd).
-
-    Returns:
-        (archived_path, plan_hash, plan_signature) on success.
-        (None, None, None) on any error.
-    """
-    plan_file = Path(plan_path)
-    if not plan_file.exists():
-        log_warn("plan_manager", f"Plan file not found: {plan_path}")
-        return None, None, None
-
-    # Read plan content
-    try:
-        content = plan_file.read_text(encoding="utf-8")
-    except Exception as e:
-        log_error("plan_manager", f"Failed to read plan: {e}")
-        return None, None, None
-
-    # Compute hash and signature
-    plan_hash = hashlib.sha256(content.encode("utf-8")).hexdigest()[:12]
-    plan_signature = content[:200]
-
-    # Ensure plans directory exists
-    plans_dir = get_context_plans_dir(context_id, project_root)
-    plans_dir.mkdir(parents=True, exist_ok=True)
-
-    # Generate archive filename: YYYY-MM-DD-<slug>.md
-    date_str = datetime.now().strftime("%Y-%m-%d")
-    slug = sanitize_title(plan_file.stem, max_len=30)
-    archive_name = f"{date_str}-{slug}.md"
-    archive_path = plans_dir / archive_name
-
-    # Handle filename collisions with counter suffix
-    counter = 2
-    while archive_path.exists():
-        archive_name = f"{date_str}-{slug}-{counter}.md"
-        archive_path = plans_dir / archive_name
-        counter += 1
-
-    # Write archived plan atomically
-    success, error = atomic_write(archive_path, content)
-    if not success:
-        log_error("plan_manager", f"Failed to write archive: {error}")
-        return None, None, None
-
-    log_info("plan_manager", f"Archived plan to: {archive_path}")
-    return str(archive_path), plan_hash, plan_signature
-
-
-# ---------------------------------------------------------------------------
-# Plan lookup
-# ---------------------------------------------------------------------------
-
-def find_latest_plan(
-    context_id: str,
-    project_root: Path = None,
-) -> Optional[str]:
-    """Find the most relevant plan file for a context.
-
-    Priority:
-    1. state.json plan_path — if the file still exists on disk.
-    2. Most recent .md in plans/ directory by modification time.
-    3. None if no plans found.
-
-    Args:
-        context_id: Context identifier.
-        project_root: Project root directory (default: from env / cwd).
-
-    Returns:
-        Absolute path string to the plan file, or None.
-    """
-    # 1. Check state.json plan_path first
-    try:
-        from .context_store import load_state
-        state = load_state(context_id, project_root)
-        if state and state.plan_path:
-            plan_path = Path(state.plan_path)
-            if plan_path.exists():
-                return str(plan_path)
-    except Exception as e:
-        log_warn("plan_manager", f"Failed to check state.json plan_path: {e}")
-
-    # 2. Fall back to most recent .md in plans/ dir by mtime
-    plans_dir = get_context_plans_dir(context_id, project_root)
-    if plans_dir.exists():
-        plans = sorted(
-            plans_dir.glob("*.md"),
-            key=lambda p: p.stat().st_mtime,
-            reverse=True,
-        )
-        if plans:
-            return str(plans[0])
-
-    # 3. No plan found
-    return None
-
-
-# ---------------------------------------------------------------------------
-# Plan identification and normalization
-# ---------------------------------------------------------------------------
-
-def generate_plan_id() -> str:
-    """Generate a short unique plan identifier (8 hex chars)."""
-    return uuid.uuid4().hex[:8]
-
-
-def normalize_plan_content(text: str) -> str:
-    """Aggressively normalize plan content for hashing.
-
-    Strips all XML/HTML tags and collapses whitespace so that
-    wrapper variations (e.g. <system-reminder>) don't affect the hash.
-    """
-    text = re.sub(r'<[^>]+>', '', text)
-    text = re.sub(r'\s+', ' ', text).strip()
-    return text
-
-
-def extract_plan_anchors(content: str, max_anchors: int = 5) -> List[str]:
-    """Extract structural anchors from plan content.
-
-    Returns markdown headings + first substantial paragraph as short strings.
-    Used for fuzzy matching when hash-based matching fails.
-    """
-    anchors = []
-    for line in content.splitlines():
-        line = line.strip()
-        if line.startswith('#') and len(line) > 3:
-            anchors.append(line[:80])
-        elif not anchors and len(line) > 20:
-            anchors.append(line[:80])
-        if len(anchors) >= max_anchors:
-            break
-    return anchors
-
-
-# ---------------------------------------------------------------------------
-# Path extraction from tool output
-# ---------------------------------------------------------------------------
-
-def extract_plan_path_from_result(tool_result: str) -> Optional[str]:
-    """Extract plan file path from ExitPlanMode tool result.
-
-    Parses the pattern: "Your plan has been saved to: <path>"
-    from the tool_result string returned by ExitPlanMode.
-
-    Args:
-        tool_result: Raw text output from the ExitPlanMode tool.
-
-    Returns:
-        Plan file path string (stripped), or None if not found.
-    """
-    if not tool_result:
-        return None
-    match = re.search(r"Your plan has been saved to:\s*(.+\.md)", tool_result)
-    if match:
-        return match.group(1).strip()
-    return None

package/dist/templates/_shared/lib/context/task_tracker.py

@@ -1,188 +0,0 @@
-"""Task tracker — direct state.json CRUD for tasks.
-
-Writes tasks directly to the tasks[] array in state.json,
-bypassing events.jsonl for faster, simpler task operations.
-
-All functions do their own I/O to avoid circular imports with
-context_store.py.
-"""
-import json
-import re
-from pathlib import Path
-from typing import Dict, List, Optional
-
-from ..base.atomic_write import atomic_write
-from ..base.constants import get_context_dir
-from ..base.logger import log_warn
-from ..base.utils import now_iso
-
-
-# ---------------------------------------------------------------------------
-# Internal I/O (avoids circular import with context_store)
-# ---------------------------------------------------------------------------
-
-def _state_path(context_id: str, project_root: Path = None) -> Path:
-    return get_context_dir(context_id, project_root) / "state.json"
-
-
-def _load_state(context_id: str, project_root: Path = None) -> Optional[dict]:
-    sp = _state_path(context_id, project_root)
-    if not sp.exists():
-        return None
-    try:
-        return json.loads(sp.read_text(encoding="utf-8"))
-    except Exception as e:
-        log_warn("task_tracker", f"Failed to read state.json: {e}")
-        return None
-
-
-def _save_state(context_id: str, state_data: dict, project_root: Path = None) -> bool:
-    sp = _state_path(context_id, project_root)
-    content = json.dumps(state_data, indent=2, ensure_ascii=False)
-    success, error = atomic_write(sp, content)
-    if not success:
-        log_warn("task_tracker", f"Failed to write state.json: {error}")
-    return success
-
-
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-def generate_next_task_id(context_id: str, project_root: Path = None) -> str:
-    """Scan tasks[] for highest aiw-N, return aiw-(N+1)."""
-    state = _load_state(context_id, project_root)
-    tasks = state.get("tasks", []) if state else []
-
-    max_num = 0
-    for t in tasks:
-        tid = t.get("id", "")
-        m = re.match(r"^aiw-(\d+)$", tid)
-        if m:
-            max_num = max(max_num, int(m.group(1)))
-
-    return f"aiw-{max_num + 1}"
-
-
-def add_task(
-    context_id: str,
-    subject: str,
-    description: str = "",
-    active_form: str = "",
-    session_id: str = "",
-    project_root: Path = None,
-) -> Optional[dict]:
-    """Add a new task to state.json tasks[] and return the task dict."""
-    state = _load_state(context_id, project_root)
-    if state is None:
-        return None
-
-    task_id = generate_next_task_id(context_id, project_root)
-    task = {
-        "id": task_id,
-        "subject": subject,
-        "description": description,
-        "active_form": active_form,
-        "status": "pending",
-        "created_at": now_iso(),
-        "completed_at": None,
-        "evidence": "",
-        "work_summary": "",
-        "files_changed": [],
-        "session_id": session_id,
-    }
-
-    state.setdefault("tasks", []).append(task)
-    state["last_active"] = now_iso()
-
-    if _save_state(context_id, state, project_root):
-        return task
-    return None
-
-
-def update_task(
-    context_id: str,
-    task_id: str,
-    status: str = None,
-    evidence: str = "",
-    work_summary: str = "",
-    files_changed: List[str] = None,
-    session_id: str = "",
-    project_root: Path = None,
-) -> bool:
-    """Find task by task_id in tasks[], update fields, return True on success."""
-    state = _load_state(context_id, project_root)
-    if state is None:
-        return False
-
-    for task in state.get("tasks", []):
-        if task.get("id") == task_id:
-            if status is not None:
-                task["status"] = status
-                if status == "completed":
-                    task["completed_at"] = now_iso()
-            if evidence:
-                task["evidence"] = evidence
-            if work_summary:
-                task["work_summary"] = work_summary
-            if files_changed is not None:
-                task["files_changed"] = files_changed
-            if session_id:
-                task["session_id"] = session_id
-            state["last_active"] = now_iso()
-            return _save_state(context_id, state, project_root)
-
-    log_warn("task_tracker", f"Task '{task_id}' not found in context '{context_id}'")
-    return False
-
-
-def delete_task(context_id: str, task_id: str, project_root: Path = None) -> bool:
-    """Remove task from tasks[] and return True on success."""
-    state = _load_state(context_id, project_root)
-    if state is None:
-        return False
-
-    tasks = state.get("tasks", [])
-    original_len = len(tasks)
-    state["tasks"] = [t for t in tasks if t.get("id") != task_id]
-
-    if len(state["tasks"]) == original_len:
-        log_warn("task_tracker", f"Task '{task_id}' not found in context '{context_id}'")
-        return False
-
-    state["last_active"] = now_iso()
-    return _save_state(context_id, state, project_root)
-
-
-def get_tasks(context_id: str, project_root: Path = None) -> List[dict]:
-    """Return tasks[] from state.json."""
-    state = _load_state(context_id, project_root)
-    if state is None:
-        return []
-    return state.get("tasks", [])
-
-
-def generate_task_summary(context_id: str, project_root: Path = None) -> str:
-    """Partition tasks and format as markdown checklist."""
-    tasks = get_tasks(context_id, project_root)
-    if not tasks:
-        return "No tasks in this context."
-
-    completed = [t for t in tasks if t.get("status") == "completed"]
-    in_progress = [t for t in tasks if t.get("status") == "in_progress"]
-    pending = [t for t in tasks if t.get("status") == "pending"]
-    blocked = [t for t in tasks if t.get("status") == "blocked"]
-
-    lines = [f"### Tasks ({len(tasks)} total)", ""]
-
-    for t in completed:
-        ws = f"\n  Work: {t['work_summary']}" if t.get("work_summary") else ""
-        lines.append(f"- [x] {t['id']}: {t['subject']}{ws}")
-    for t in in_progress:
-        lines.append(f"- [~] {t['id']}: {t['subject']}")
-    for t in pending:
-        lines.append(f"- [ ] {t['id']}: {t['subject']}")
-    for t in blocked:
-        lines.append(f"- [!] {t['id']}: {t['subject']}")
-
-    return "\n".join(lines)

package/dist/templates/_shared/lib/handoff/__init__.py

@@ -1,22 +0,0 @@
-"""Handoff utilities for context-aware session management.
-
-This module provides graceful context degradation when Claude's
-context window fills up. Instead of rushing or losing work,
-it creates a handoff document and facilitates clean session continuation.
-
-Components:
-- document_generator: Creates handoff documents with work state
-- context_monitor hook: Monitors context during tool use and triggers warnings
-"""
-
-from .document_generator import (
-    generate_handoff_document,
-    get_handoff_continuation_prompt,
-    HandoffDocument,
-)
-
-__all__ = [
-    "generate_handoff_document",
-    "get_handoff_continuation_prompt",
-    "HandoffDocument",
-]

package/dist/templates/_shared/lib/handoff/document_generator.py

@@ -1,278 +0,0 @@
-"""Handoff document generator for context-aware session management.
-
-Creates structured handoff documents when a session needs to transfer
-work to a new session (typically due to context window limits).
-
-Handoff documents capture:
-- Links to active plan and context folder
-- Current task state from events.jsonl
-- Work in progress summary
-- Next steps for continuation
-"""
-import json
-import uuid
-from dataclasses import dataclass, field
-from datetime import datetime
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-from ..base.atomic_write import atomic_write
-from ..base.constants import get_context_handoffs_dir, get_context_dir
-from ..base.logger import log_info, log_error
-from ..base.utils import now_iso
-from ..context.context_store import get_context as _get_context_state, save_state as _save_state
-from ..context.task_tracker import get_tasks
-from ..templates.formatters import render_task_list, format_continuation_header, format_reason
-
-
-@dataclass
-class HandoffDocument:
-    """Structured handoff document content."""
-    context_id: str
-    context_summary: str
-    session_id: str
-    reason: str  # e.g., "low_context", "user_requested", "error_recovery"
-    created_at: str
-
-    # Links
-    plan_path: Optional[str] = None
-    context_folder: str = ""
-    events_log_path: str = ""
-
-    # Task state
-    active_tasks: List[Dict[str, Any]] = field(default_factory=list)
-    completed_tasks_this_session: List[Dict[str, Any]] = field(default_factory=list)
-
-    # Context summary
-    work_summary: str = ""
-    next_steps: List[str] = field(default_factory=list)
-    important_notes: List[str] = field(default_factory=list)
-
-    # File path (set after saving)
-    file_path: Optional[str] = None
-
-
-def generate_handoff_document(
-    context_id: str,
-    reason: str = "low_context",
-    work_summary: str = "",
-    next_steps: Optional[List[str]] = None,
-    important_notes: Optional[List[str]] = None,
-    completed_this_session: Optional[List[str]] = None,
-    project_root: Path = None
-) -> Optional[HandoffDocument]:
-    """
-    Generate and save a handoff document for a context.
-
-    This creates a markdown document capturing current work state,
-    saves it to the context's handoffs folder, and records the event.
-
-    Args:
-        context_id: Context identifier
-        reason: Why handoff is happening (low_context, user_requested, etc.)
-        work_summary: Summary of current work in progress
-        next_steps: List of next steps for continuation
-        important_notes: Important decisions or context to preserve
-        completed_this_session: List of task subjects completed this session
-        project_root: Project root directory
-
-    Returns:
-        HandoffDocument with file_path set, or None on failure
-    """
-    context = _get_context_state(context_id, project_root)
-    if not context:
-        log_error("handoff", f"Context '{context_id}' not found")
-        return None
-
-    # Generate session ID
-    session_id = str(uuid.uuid4())[:8]
-
-    # Get pending tasks from state.json
-    all_tasks = get_tasks(context_id, project_root)
-    pending_tasks = [t for t in all_tasks if t.get("status") in ("pending", "in_progress", "blocked")]
-
-    # Build document
-    now = now_iso()
-    context_dir = get_context_dir(context_id, project_root)
-
-    doc = HandoffDocument(
-        context_id=context_id,
-        context_summary=context.summary,
-        session_id=session_id,
-        reason=reason,
-        created_at=now,
-        plan_path=context.plan_path,
-        context_folder=str(context_dir),
-        events_log_path=str(context_dir / "state.json"),
-        active_tasks=pending_tasks,
-        completed_tasks_this_session=[
-            {"subject": s} for s in (completed_this_session or [])
-        ],
-        work_summary=work_summary,
-        next_steps=next_steps or [],
-        important_notes=important_notes or [],
-    )
-
-    # Compute file path BEFORE rendering markdown
-    handoffs_dir = get_context_handoffs_dir(context_id, project_root)
-    handoffs_dir.mkdir(parents=True, exist_ok=True)
-
-    # Filename: YYYY-MM-DD-session-{session_id}.md
-    date_str = datetime.now().strftime("%Y-%m-%d")
-    filename = f"{date_str}-session-{session_id}.md"
-    file_path = handoffs_dir / filename
-
-    # Set file_path on doc BEFORE rendering markdown
-    doc.file_path = str(file_path)
-
-    # Generate markdown content
-    markdown = _render_handoff_markdown(doc)
-
-    # Save to handoffs folder
-
-    success, error = atomic_write(file_path, markdown)
-    if not success:
-        log_error("handoff", f"Failed to write handoff document: {error}")
-        return None
-
-    log_info("handoff", f"Created handoff document: {file_path}")
-    return doc
-
-
-def _render_handoff_markdown(doc: HandoffDocument) -> str:
-    """Render handoff document as markdown."""
-    lines = [
-        format_continuation_header("handoff", doc.context_id),
-        "",
-        f"**Created**: {doc.created_at}",
-        f"**Context ID**: {doc.context_id}",
-        f"**Session ID**: {doc.session_id}",
-        f"**Reason**: {format_reason(doc.reason)}",
-        "",
-        "## Links",
-        "",
-    ]
-
-    # Plan link
-    if doc.plan_path:
-        lines.append(f"- **Plan**: [{Path(doc.plan_path).name}]({doc.plan_path})")
-
-    lines.extend([
-        f"- **Context Folder**: `{doc.context_folder}`",
-        f"- **Events Log**: `{doc.events_log_path}`",
-        "",
-        "## Current State",
-        "",
-    ])
-
-    # Active tasks
-    lines.append(render_task_list(doc.active_tasks, header="Active Tasks", show_description=True).rstrip())
-    lines.append("")
-
-    # Completed this session
-    if doc.completed_tasks_this_session:
-        lines.append(render_task_list(
-            doc.completed_tasks_this_session,
-            header="Completed This Session",
-            show_description=False
-        ).rstrip())
-        lines.append("")
-
-    # Work summary
-    if doc.work_summary:
-        lines.extend([
-            "## Context Summary",
-            "",
-            doc.work_summary,
-            "",
-        ])
-
-    # Next steps
-    if doc.next_steps:
-        lines.extend([
-            "## Next Steps",
-            "",
-        ])
-        for i, step in enumerate(doc.next_steps, 1):
-            lines.append(f"{i}. {step}")
-        lines.append("")
-
-    # Important notes
-    if doc.important_notes:
-        lines.extend([
-            "## Important Notes",
-            "",
-        ])
-        for note in doc.important_notes:
-            lines.append(f"- {note}")
-        lines.append("")
-
-    # Continuation prompt
-    lines.extend([
-        "---",
-        "",
-        "**Continuation Prompt**:",
-        "```",
-        f'Continue working on context "{doc.context_id}".',
-        "",
-        f"Handoff document: {doc.file_path or 'See above'}",
-        "",
-        "Read the handoff document, restore tasks with TaskCreate, and continue implementation.",
-        "```",
-    ])
-
-    return "\n".join(lines)
-
-
-def get_handoff_continuation_prompt(doc: HandoffDocument) -> str:
-    """
-    Generate the prompt to paste into new session for continuation.
-
-    Args:
-        doc: HandoffDocument with file_path set
-
-    Returns:
-        Prompt string for continuing work
-    """
-    return f"""Continue working on context "{doc.context_id}".
-
-Handoff document: {doc.file_path}
-
-Read the handoff document, restore tasks with TaskCreate, and continue implementation."""
-
-
-def get_low_context_warning(context_remaining_percent: int, context_id: str) -> str:
-    """
-    Generate system reminder for low context warning.
-
-    This is injected by the UserPromptSubmit hook when context is low.
-
-    Args:
-        context_remaining_percent: Percentage of context remaining
-        context_id: Current context identifier
-
-    Returns:
-        System reminder markdown
-    """
-    return f"""<system-reminder>
-## LOW CONTEXT WARNING ({context_remaining_percent}% remaining)
-
-Your context window is running low. Please:
-
-1. **Finish current task** if 1-2 steps away, OR save current progress
-2. **Create handoff document** by calling:
-   ```python
-   from _shared.lib.handoff import generate_handoff_document
-   doc = generate_handoff_document(
-       context_id="{context_id}",
-       reason="low_context",
-       work_summary="<describe current work>",
-       next_steps=["<step 1>", "<step 2>"],
-       important_notes=["<key decision 1>"]
-   )
-   ```
-3. **Ask permission** to clear and paste continuation prompt
-
-After creating handoff, ask the user:
-"Context is low. I've created a handoff document. May I clear and continue in a new session?"
-</system-reminder>"""