@blxzer/pactile 0.5.0

package/dist/templates/pactile/scripts/common/task_utils.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""
+Task utility functions.
+
+Provides:
+    is_safe_task_path   - Validate task path is safe to operate on
+    find_task_by_name   - Find task directory by name
+    resolve_task_dir    - Resolve task directory from name, relative, or absolute path
+    archive_task_dir    - Archive task to monthly directory
+    run_task_hooks      - Run lifecycle hooks for task events
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .paths import get_repo_root, get_tasks_dir
+
+
+# =============================================================================
+# Path Safety
+# =============================================================================
+
+def is_safe_task_path(task_path: str, repo_root: Path | None = None) -> bool:
+    """Check if a relative task path is safe to operate on.
+
+    Args:
+        task_path: Task path (relative to repo_root).
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True if safe, False if dangerous.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    normalized = task_path.replace("\\", "/")
+
+    # Check empty or null
+    if not normalized or normalized == "null":
+        print("Error: empty or null task path", file=sys.stderr)
+        return False
+
+    # Reject absolute paths
+    if Path(task_path).is_absolute():
+        print(f"Error: absolute path not allowed: {task_path}", file=sys.stderr)
+        return False
+
+    # Reject ".", "..", paths starting with "./" or "../", or containing ".."
+    if normalized in (".", "..") or normalized.startswith("./") or normalized.startswith("../") or ".." in normalized:
+        print(f"Error: path traversal not allowed: {task_path}", file=sys.stderr)
+        return False
+
+    # Final check: ensure resolved path is not the repo root
+    abs_path = repo_root / Path(normalized)
+    if abs_path.exists():
+        try:
+            resolved = abs_path.resolve()
+            root_resolved = repo_root.resolve()
+            if resolved == root_resolved:
+                print(f"Error: path resolves to repo root: {task_path}", file=sys.stderr)
+                return False
+        except (OSError, IOError):
+            pass
+
+    return True
+
+
+# =============================================================================
+# Task Lookup
+# =============================================================================
+
+def find_task_by_name(task_name: str, tasks_dir: Path) -> Path | None:
+    """Find task directory by name (exact or suffix match).
+
+    Args:
+        task_name: Task name to find.
+        tasks_dir: Tasks directory path.
+
+    Returns:
+        Absolute path to task directory, or None if not found.
+    """
+    if not task_name or not tasks_dir or not tasks_dir.is_dir():
+        return None
+
+    # Try exact match first
+    exact_match = tasks_dir / task_name
+    if exact_match.is_dir():
+        return exact_match
+
+    # Try suffix match (e.g., "my-task" matches "01-21-my-task")
+    for d in tasks_dir.iterdir():
+        if d.is_dir() and d.name.endswith(f"-{task_name}"):
+            return d
+
+    return None
+
+
+# =============================================================================
+# Archive Operations
+# =============================================================================
+
+def archive_task_dir(task_dir_abs: Path, repo_root: Path | None = None) -> Path | None:
+    """Archive a task directory to archive/{YYYY-MM}/.
+
+    Args:
+        task_dir_abs: Absolute path to task directory.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to archived directory, or None on error.
+    """
+    if not task_dir_abs.is_dir():
+        print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
+        return None
+
+    # Get tasks directory (parent of the task)
+    tasks_dir = task_dir_abs.parent
+    archive_dir = tasks_dir / "archive"
+    year_month = datetime.now().strftime("%Y-%m")
+    month_dir = archive_dir / year_month
+
+    # Create archive directory
+    try:
+        month_dir.mkdir(parents=True, exist_ok=True)
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create archive directory: {e}", file=sys.stderr)
+        return None
+
+    # Move task to archive
+    task_name = task_dir_abs.name
+    dest = month_dir / task_name
+
+    try:
+        shutil.move(str(task_dir_abs), str(dest))
+    except (OSError, IOError, shutil.Error) as e:
+        print(f"Error: Failed to move task to archive: {e}", file=sys.stderr)
+        return None
+
+    return dest
+
+
+def archive_task_complete(
+    task_dir_abs: Path,
+    repo_root: Path | None = None
+) -> dict[str, str]:
+    """Complete archive workflow: archive directory.
+
+    Args:
+        task_dir_abs: Absolute path to task directory.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Dict with archive result info.
+    """
+    if not task_dir_abs.is_dir():
+        print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
+        return {}
+
+    archive_dest = archive_task_dir(task_dir_abs, repo_root)
+    if archive_dest:
+        return {"archived_to": str(archive_dest)}
+
+    return {}
+
+
+# =============================================================================
+# Task Directory Resolution
+# =============================================================================
+
+def resolve_task_dir(target_dir: str, repo_root: Path) -> Path:
+    """Resolve task directory to absolute path.
+
+    Supports:
+    - Absolute path: /path/to/task
+    - Relative path: .pactile/tasks/01-31-my-task
+    - Task name: my-task (uses find_task_by_name for lookup)
+
+    Args:
+        target_dir: Task directory specification.
+        repo_root: Repository root path.
+
+    Returns:
+        Resolved absolute path.
+    """
+    if not target_dir:
+        return Path()
+
+    normalized = target_dir.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    # Absolute path
+    if Path(target_dir).is_absolute():
+        return Path(target_dir)
+
+    # Relative path (contains path separator or starts with .pactile)
+    if "/" in normalized or normalized.startswith(".pactile"):
+        return repo_root / Path(normalized)
+
+    # Task name - try to find in tasks directory
+    tasks_dir = get_tasks_dir(repo_root)
+    found = find_task_by_name(target_dir, tasks_dir)
+    if found:
+        return found
+
+    # Fallback to treating as relative path
+    return repo_root / Path(normalized)
+
+
+# =============================================================================
+# Lifecycle Hooks
+# =============================================================================
+
+def run_task_hooks(event: str, task_json_path: Path, repo_root: Path) -> None:
+    """Run lifecycle hooks for a task event.
+
+    Args:
+        event: Event name (e.g. "after_create").
+        task_json_path: Absolute path to the task's task.json.
+        repo_root: Repository root for cwd and config lookup.
+    """
+    import os
+    import subprocess
+
+    from .config import get_hooks
+    from .log import Colors, colored
+
+    commands = get_hooks(event, repo_root)
+    if not commands:
+        return
+
+    env = {**os.environ, "TASK_JSON_PATH": str(task_json_path)}
+
+    for cmd in commands:
+        try:
+            result = subprocess.run(
+                cmd,
+                shell=True,
+                cwd=repo_root,
+                env=env,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            if result.returncode != 0:
+                print(
+                    colored(f"[WARN] Hook failed ({event}): {cmd}", Colors.YELLOW),
+                    file=sys.stderr,
+                )
+                if result.stderr.strip():
+                    print(f"  {result.stderr.strip()}", file=sys.stderr)
+        except Exception as e:
+            print(
+                colored(f"[WARN] Hook error ({event}): {cmd} — {e}", Colors.YELLOW),
+                file=sys.stderr,
+            )
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    repo = get_repo_root()
+    tasks = get_tasks_dir(repo)
+
+    print(f"Tasks dir: {tasks}")
+    print(f"is_safe_task_path('.pactile/tasks/test'): {is_safe_task_path('.pactile/tasks/test', repo)}")
+    print(f"is_safe_task_path('../test'): {is_safe_task_path('../test', repo)}")

package/dist/templates/pactile/scripts/common/tasks.py

@@ -0,0 +1,231 @@
+"""
+Task data access layer.
+
+Single source of truth for loading and iterating task directories.
+Replaces scattered task.json parsing across 9+ files.
+
+Provides:
+    load_task          — Load a single task by directory path
+    iter_active_tasks  — Iterate all non-archived tasks (sorted)
+    get_all_statuses   — Get {dir_name: status} map for children progress
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+
+from .io import read_json
+from .paths import FILE_TASK_JSON
+from .task_map import PARENT_TERMINAL_STATES, get_child_state, load_task_map
+from .types import TaskInfo
+
+
+def load_task(task_dir: Path) -> TaskInfo | None:
+    """Load task from a directory containing task.json.
+
+    Args:
+        task_dir: Absolute path to the task directory.
+
+    Returns:
+        TaskInfo if task.json exists and is valid, None otherwise.
+    """
+    task_json = task_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        return None
+
+    data = read_json(task_json)
+    if not data:
+        return None
+
+    return TaskInfo(
+        dir_name=task_dir.name,
+        directory=task_dir,
+        title=data.get("title") or data.get("name") or "unknown",
+        status=data.get("status", "unknown"),
+        assignee=data.get("assignee", ""),
+        priority=data.get("priority", "P2"),
+        children=tuple(data.get("children", [])),
+        parent=data.get("parent"),
+        package=data.get("package"),
+        raw=data,
+    )
+
+
+def iter_active_tasks(tasks_dir: Path) -> Iterator[TaskInfo]:
+    """Iterate all active (non-archived) tasks, sorted by directory name.
+
+    Skips the "archive" directory and directories without valid task.json.
+
+    Args:
+        tasks_dir: Path to the tasks directory.
+
+    Yields:
+        TaskInfo for each valid task.
+    """
+    if not tasks_dir.is_dir():
+        return
+
+    for d in sorted(tasks_dir.iterdir()):
+        if not d.is_dir() or d.name == "archive":
+            continue
+        info = load_task(d)
+        if info is not None:
+            yield info
+
+
+def get_all_statuses(tasks_dir: Path) -> dict[str, str]:
+    """Get a {dir_name: status} mapping for all active tasks.
+
+    Useful for computing children progress without loading full TaskInfo.
+
+    Args:
+        tasks_dir: Path to the tasks directory.
+
+    Returns:
+        Dict mapping directory names to status strings.
+    """
+    return {t.dir_name: t.status for t in iter_active_tasks(tasks_dir)}
+
+
+def load_parent_child_integration_states(
+    parent_dir: Path,
+    children: tuple[str, ...] | list[str],
+) -> dict[str, str]:
+    """Map structural child ids to parent task-map integration states."""
+    if not children:
+        return {}
+    data, _ = load_task_map(parent_dir)
+    if not data:
+        return {}
+    states: dict[str, str] = {}
+    for child_name in children:
+        state = get_child_state(parent_dir, child_name)
+        if state:
+            states[child_name] = state
+    return states
+
+
+def _child_counts_as_done_for_progress(
+    child_name: str,
+    all_statuses: dict[str, str],
+    integration_states: dict[str, str] | None,
+) -> bool:
+    """Whether a structural child counts toward parent [n/m done]."""
+    if child_name not in all_statuses:
+        return True
+    dir_status = all_statuses.get(child_name)
+    if dir_status in ("completed", "done"):
+        return True
+    if integration_states:
+        integration = integration_states.get(child_name)
+        if integration in PARENT_TERMINAL_STATES:
+            return True
+    return False
+
+
+def children_progress(
+    children: tuple[str, ...] | list[str],
+    all_statuses: dict[str, str],
+    integration_states: dict[str, str] | None = None,
+) -> str:
+    """Format children progress like " [2/3 done]" or integration summary.
+
+    Directory lifecycle (task.json status) and parent task-map integration
+    are separate planes. A child integrated by the parent counts as done even
+    when its directory status is still planning or in_progress.
+
+    Args:
+        children: List of child directory names.
+        all_statuses: Status map from get_all_statuses().
+        integration_states: Optional map from load_parent_child_integration_states().
+
+    Returns:
+        Formatted string, or "" if no children.
+    """
+    if not children:
+        return ""
+
+    done = sum(
+        1
+        for c in children
+        if _child_counts_as_done_for_progress(c, all_statuses, integration_states)
+    )
+    total = len(children)
+
+    if integration_states:
+        integrated = sum(
+            1 for c in children if integration_states.get(c) == "integrated"
+        )
+        cancelled = sum(
+            1 for c in children if integration_states.get(c) == "cancelled"
+        )
+        terminal = integrated + cancelled
+        if terminal == total and done == total:
+            parts: list[str] = []
+            if integrated:
+                parts.append(f"{integrated} integrated")
+            if cancelled:
+                parts.append(f"{cancelled} cancelled")
+            summary = ", ".join(parts) if parts else f"{done}/{total} done"
+            return f" [{summary}]"
+
+        in_flight = total - terminal
+        if in_flight or terminal:
+            detail = f"{done}/{total} done"
+            if integrated or cancelled or in_flight:
+                bits: list[str] = []
+                if integrated:
+                    bits.append(f"{integrated} integrated")
+                if cancelled:
+                    bits.append(f"{cancelled} cancelled")
+                active = total - terminal
+                if active:
+                    bits.append(f"{active} active")
+                detail = f"{detail}; {', '.join(bits)}"
+            return f" [{detail}]"
+
+    return f" [{done}/{total} done]"
+
+
+def format_child_task_display(
+    dir_status: str,
+    integration_state: str | None,
+) -> str:
+    """Format task list/dashboard status for a child with optional integration."""
+    if integration_state:
+        return f"{dir_status}; integration:{integration_state}"
+    return dir_status
+
+
+def parent_archive_child_followup_hint(
+    parent_dir: Path,
+    child_names: list[str],
+    tasks_dir: Path,
+) -> str | None:
+    """Return a hint when integrated children remain active after parent archive."""
+    if not child_names:
+        return None
+    data, _ = load_task_map(parent_dir)
+    if data is None:
+        return None
+
+    pending: list[str] = []
+    for child_name in child_names:
+        state = get_child_state(parent_dir, child_name)
+        if state != "integrated":
+            continue
+        child_path = tasks_dir / child_name
+        if child_path.is_dir():
+            pending.append(child_name)
+
+    if not pending:
+        return None
+
+    names = ", ".join(pending)
+    return (
+        f"Integrated child task dirs still active: {names}. "
+        "Archive each child when ready: "
+        f"python ./.pactile/scripts/task.py archive <child> "
+        "(or parent archive with --archive-integrated-children after archive --check passes for each)."
+    )

package/dist/templates/pactile/scripts/common/test_adapter_middleware.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Stage 6 Event Bridge / Middleware Python projection."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from common.adapter_middleware import (
+    EXTERNAL_KNOWLEDGE_CAPABILITY,
+    RETRIEVAL_INTENTS,
+    SHIPPED_MIDDLEWARE_PROVIDERS,
+    SHIPPED_PROVIDER_PROBE,
+    AdapterMiddlewareError,
+    apply_middleware_probes,
+    assert_external_knowledge,
+    classify_transport_probe,
+    default_event_bridge,
+    default_middleware_providers,
+    dispatch_hook_event,
+    event_bridge_for_dispatch,
+    mcp_server_ids_from_config,
+    normalize_capability_router,
+    probe_smart_search_readiness,
+    resolve_provider_v1,
+    select_registered_mcp_servers,
+    sync_event_bridge_subscriptions,
+)
+
+
+def test_dispatch_skips_unsubscribed_modules() -> None:
+    last = dispatch_hook_event(
+        {
+            "subscriptions": [
+                {"event": "sessionStart", "module": "observability-local"},
+                {"event": "stop", "module": "retrieval-extended"},
+            ]
+        },
+        "sessionStart",
+        source="cursor-hooks",
+    )
+    assert last["delivered"] == ["observability-local"]
+    assert last["skipped"] == ["retrieval-extended"]
+
+
+def test_empty_subscriptions_do_not_crash_dispatch() -> None:
+    last = dispatch_hook_event(default_event_bridge(), "sessionStart")
+    assert last["delivered"] == []
+    assert last["skipped"] == []
+    extras: dict = {
+        "ondemand_modules": {"active": ["worker-orchestration"]},
+        "baseline_modules": {"active": ["context-progressive"]},
+    }
+    sync_event_bridge_subscriptions(extras)
+    hooks = {item.get("hook") for item in extras["event_bridge"]["subscriptions"]}
+    assert "inject-subagent-context.py" in hooks
+    assert "session-start.py" in hooks
+    extras["ondemand_modules"]["active"] = []
+    extras["baseline_modules"]["active"] = []
+    sync_event_bridge_subscriptions(extras)
+    assert extras["event_bridge"]["subscriptions"] == []
+    last = dispatch_hook_event(extras["event_bridge"], "preToolUse")
+    assert last["delivered"] == []
+
+
+def test_event_bridge_for_dispatch_defaults_baseline_then_honors_empty() -> None:
+    bridge = event_bridge_for_dispatch({})
+    modules = {item.get("module") for item in bridge["subscriptions"]}
+    assert "context-progressive" in modules
+    last = dispatch_hook_event(bridge, "sessionStart", source="cursor-hooks")
+    assert "context-progressive" in last["delivered"]
+    empty = event_bridge_for_dispatch({"baseline_modules": {"active": []}})
+    assert empty["subscriptions"] == []
+
+
+def test_missing_smart_search_is_not_ready() -> None:
+    readiness = probe_smart_search_readiness(available=False)
+    assert readiness["status"] == "missing"
+    assert readiness["capability"] == EXTERNAL_KNOWLEDGE_CAPABILITY
+    extras: dict[str, Any] = {
+        "required_capabilities": [EXTERNAL_KNOWLEDGE_CAPABILITY]
+    }
+    with pytest.raises(AdapterMiddlewareError, match="no ready authorized Provider"):
+        assert_external_knowledge(extras, readiness, phase="start")
+    extras["external_knowledge_policy"] = "degrade"
+    assert_external_knowledge(extras, readiness, phase="start")
+    assert extras["profile_health"] == "degraded"
+    assert_external_knowledge({}, readiness, phase="archive")
+
+
+def test_capability_router_rejects_optional_tool_names() -> None:
+    router = normalize_capability_router(None)
+    assert tuple(key for key in RETRIEVAL_INTENTS if router.get(key)) == RETRIEVAL_INTENTS
+    with pytest.raises(AdapterMiddlewareError, match="retrieval intent keys"):
+        normalize_capability_router({"codegraph": True})
+
+
+def test_default_catalog_is_empty_and_does_not_claim_a_concrete_provider() -> None:
+    providers = default_middleware_providers()
+    assert providers["registered"] == list(SHIPPED_MIDDLEWARE_PROVIDERS)
+    assert providers["registered"] == []
+    assert providers["required"] == []
+    assert set(SHIPPED_PROVIDER_PROBE) == set(SHIPPED_MIDDLEWARE_PROVIDERS)
+    assert set(SHIPPED_PROVIDER_PROBE.values()) <= {"cli", "mcp", "host"}
+
+
+def test_optional_mcp_missing_does_not_block_unrelated_assert() -> None:
+    providers = apply_middleware_probes(
+        {
+            **default_middleware_providers(),
+            "registered": ["provider.alpha"],
+        },
+        {
+            "provider.alpha": {
+                "present": False,
+                "capability": EXTERNAL_KNOWLEDGE_CAPABILITY,
+            },
+            "random-extra-mcp": {"present": True},
+        },
+    )
+    assert providers["readiness"]["provider.alpha"]["status"] == "missing"
+    assert "random-extra-mcp" not in providers["readiness"]
+    extras: dict = {}
+    assert_external_knowledge(
+        extras,
+        providers["readiness"]["provider.alpha"],
+        phase="archive",
+    )
+    configured = mcp_server_ids_from_config(
+        {"mcpServers": {"codegraph": {}, "random-extra-mcp": {}, "playwright": {}}},
+    )
+    assert select_registered_mcp_servers(configured) == []
+    assert select_registered_mcp_servers(
+        configured,
+        registered=["random-extra-mcp"],
+    ) == ["random-extra-mcp"]
+
+
+def test_probe_evidence_is_logical_and_secret_safe() -> None:
+    safe = "evidence://probe/provider.alpha/1"
+    assert classify_transport_probe(present=True, evidence=safe)["evidence"] == safe
+    canary = "TOKEN=do-not-print"
+    result = classify_transport_probe(present=True, evidence=canary)
+    assert result["evidence"] is None
+    assert canary not in str(result)
+
+
+def test_resolver_rejects_non_plain_mapping_containers_without_reading_them() -> None:
+    canary = "TOKEN=hostile-mapping-canary"
+
+    class ThrowingDict(dict[str, Any]):
+        def get(self, key: str, default: Any = None) -> Any:
+            raise RuntimeError(canary)
+
+    keys = {
+        "schemaVersion",
+        "intent",
+        "capabilityId",
+        "minimumAssurance",
+        "requestedPolicy",
+        "authorizedProviderIds",
+        "activeProviderIds",
+        "standbyProviderIds",
+        "fallbackAllowed",
+        "manifests",
+        "bindings",
+        "runtimeFacts",
+        "now",
+    }
+    top_level = ThrowingDict({key: None for key in keys})
+    nested: dict[str, Any] = {key: None for key in keys}
+    nested["schemaVersion"] = 1
+    nested["requestedPolicy"] = ThrowingDict()
+
+    expected = {
+        "schemaVersion": 1,
+        "status": "invalid",
+        "resolution": None,
+        "fingerprint": None,
+        "explain": {
+            "schemaVersion": 1,
+            "decision": "invalid",
+            "reasonCode": "provider-input-invalid",
+            "selectedProviderId": None,
+            "fallbackFromProviderId": None,
+            "effectivePolicy": None,
+            "evidenceRefs": [],
+            "candidates": [],
+        },
+    }
+    for value in (top_level, nested):
+        result = resolve_provider_v1(value)
+        assert result == expected
+        assert canary not in str(result)