alysis-code 0.13.0__py3-none-any.whl

alysis_code/git_worktrees.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .git_ops import (
+    GitOpsError,
+    branch_exists,
+    ensure_git_available,
+    ensure_git_repo,
+    ensure_runtime_artifact_excludes,
+    status_porcelain,
+)
+from .git_safe import build_git_cmd
+
+
+@dataclass(frozen=True)
+class WorktreeInfo:
+    path: Path
+    branch: str
+    base_branch: str
+    created_branch: bool
+    reused_existing_worktree: bool
+
+
+def _run_git_checked(
+    root: Path,
+    args: list[str],
+    *,
+    error_message: str,
+) -> subprocess.CompletedProcess[str]:
+    try:
+        cp = subprocess.run(
+            build_git_cmd(root, args),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except OSError as e:
+        raise GitOpsError("failed to run git") from e
+    if cp.returncode != 0:
+        detail = (cp.stderr or cp.stdout).strip()
+        raise GitOpsError(f"{error_message}: {detail or 'unknown error'}")
+    return cp
+
+
+def _is_valid_existing_worktree(
+    *,
+    worktree_repo_path: Path,
+    expected_branch: str,
+) -> tuple[bool, str]:
+    try:
+        inside = subprocess.run(
+            build_git_cmd(worktree_repo_path, ["rev-parse", "--is-inside-work-tree"]),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except OSError as e:
+        raise GitOpsError("failed to run git") from e
+    if inside.returncode != 0 or inside.stdout.strip().lower() != "true":
+        return False, "path exists but is not a valid git worktree"
+
+    try:
+        branch_cp = subprocess.run(
+            build_git_cmd(worktree_repo_path, ["rev-parse", "--abbrev-ref", "HEAD"]),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except OSError as e:
+        raise GitOpsError("failed to run git") from e
+    if branch_cp.returncode != 0:
+        return False, "failed to resolve worktree branch"
+    current = branch_cp.stdout.strip()
+    if current != expected_branch:
+        return (
+            False,
+            f"worktree branch mismatch (expected {expected_branch}, got {current or '(empty)'})",
+        )
+    ensure_runtime_artifact_excludes(worktree_repo_path)
+    status_lines = status_porcelain(worktree_repo_path)
+    if status_lines:
+        preview = ", ".join(status_lines[:5])
+        if len(status_lines) > 5:
+            preview += ", ..."
+        return False, f"worktree has stale filesystem state ({preview})"
+    return True, ""
+
+
+def _cleanup_existing_worktree_path(*, root: Path, worktree_repo_path: Path) -> None:
+    remove_cp = subprocess.run(
+        build_git_cmd(root, ["worktree", "remove", str(worktree_repo_path), "--force"]),
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    # Best-effort cleanup via git first; path cleanup below handles leftovers.
+    _ = remove_cp
+    if worktree_repo_path.exists():
+        if worktree_repo_path.is_dir():
+            shutil.rmtree(worktree_repo_path, ignore_errors=True)
+        else:
+            try:
+                worktree_repo_path.unlink()
+            except OSError:
+                pass
+    if worktree_repo_path.exists():
+        raise GitOpsError(f"failed to cleanup existing worktree path {worktree_repo_path}")
+
+
+def ensure_task_worktree(
+    *,
+    root: Path,
+    worktree_repo_path: Path,
+    branch: str,
+    base_branch: str,
+) -> WorktreeInfo:
+    ensure_git_available()
+    ensure_git_repo(root)
+    worktree_repo_path = worktree_repo_path.resolve()
+    worktree_repo_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if worktree_repo_path.exists():
+        valid, _reason = _is_valid_existing_worktree(
+            worktree_repo_path=worktree_repo_path,
+            expected_branch=branch,
+        )
+        if valid:
+            return WorktreeInfo(
+                path=worktree_repo_path,
+                branch=branch,
+                base_branch=base_branch,
+                created_branch=False,
+                reused_existing_worktree=True,
+            )
+        _cleanup_existing_worktree_path(root=root, worktree_repo_path=worktree_repo_path)
+
+    if branch_exists(root, branch):
+        _run_git_checked(
+            root,
+            ["worktree", "add", str(worktree_repo_path), branch],
+            error_message=f"failed to add worktree for branch {branch}",
+        )
+        return WorktreeInfo(
+            path=worktree_repo_path,
+            branch=branch,
+            base_branch=base_branch,
+            created_branch=False,
+            reused_existing_worktree=False,
+        )
+
+    _run_git_checked(
+        root,
+        ["worktree", "add", "-b", branch, str(worktree_repo_path), base_branch],
+        error_message=f"failed to create worktree branch {branch} from {base_branch}",
+    )
+    return WorktreeInfo(
+        path=worktree_repo_path,
+        branch=branch,
+        base_branch=base_branch,
+        created_branch=True,
+        reused_existing_worktree=False,
+    )
+
+
+def remove_task_worktree(
+    *,
+    root: Path,
+    worktree_repo_path: Path,
+    force: bool = True,
+) -> None:
+    args = ["worktree", "remove", str(worktree_repo_path)]
+    if force:
+        args.append("--force")
+    _run_git_checked(
+        root,
+        args,
+        error_message=f"failed to remove worktree {worktree_repo_path}",
+    )
+
+
+def prune_worktrees(root: Path) -> None:
+    _run_git_checked(
+        root,
+        ["worktree", "prune"],
+        error_message="failed to prune worktrees",
+    )

alysis_code/hooks/README.md

@@ -0,0 +1,33 @@
+# Lifecycle Hooks
+
+This package implements command-based lifecycle hooks around sessions, prompts,
+and tool calls.
+
+## Contents
+
+- `config.py` loads user, project, and local hook configuration.
+- `models.py` defines hook specs and event payloads.
+- `dispatcher.py` executes hooks and interprets decisions.
+- `trust.py` records trust for project hook configuration.
+- `audit.py` writes hook audit artifacts.
+
+## Scope
+
+Project hook configuration is executable policy and is not trusted by default.
+Edits to that configuration require a new trust decision.
+
+Blocking events can stop prompts or tool calls. Non-blocking events record hook
+output but continue execution. Keep that distinction explicit in code and docs.
+
+Hooks receive a filtered environment by default; avoid broadening environment
+inheritance unless the security impact is clear.
+
+## Development
+
+When changing event payloads or dispatcher behavior, update the hook protocol
+tests and public hook documentation together.
+
+## See Also
+
+- [Lifecycle hooks](../../../docs/hooks.md)
+- [Security model](../../../docs/security_model.md)

alysis_code/hooks/__init__.py

@@ -0,0 +1,67 @@
+from .audit import (
+    HOOK_AUDIT_ARTIFACT_PARTS,
+    HookAuditLogger,
+    build_hook_audit_event,
+    hook_audit_artifact_path,
+    hook_audit_log_path,
+    read_hook_audit_events,
+)
+from .config import (
+    ResolvedHookConfig,
+    ResolvedHookMatcherGroup,
+    load_hook_config_file,
+    load_resolved_hooks_config,
+    project_hooks_config_path,
+    project_local_hooks_config_path,
+    user_hooks_config_path,
+)
+from .dispatcher import HookDispatcher
+from .models import (
+    CanonicalHookEventName,
+    HookConfigFile,
+    HookDispatchResult,
+    HookEventName,
+    canonicalize_hook_event_name,
+)
+from .trust import (
+    ProjectHooksTrustKey,
+    ProjectHooksTrustState,
+    is_project_hooks_config_trusted,
+    load_trust_state,
+    project_hooks_trust_key,
+    save_trust_state,
+    trust_project_hooks_config,
+    trust_state_path,
+    untrust_project_hooks_config,
+)
+
+__all__ = [
+    "CanonicalHookEventName",
+    "HOOK_AUDIT_ARTIFACT_PARTS",
+    "HookAuditLogger",
+    "HookConfigFile",
+    "HookDispatchResult",
+    "HookDispatcher",
+    "HookEventName",
+    "ProjectHooksTrustKey",
+    "ProjectHooksTrustState",
+    "ResolvedHookConfig",
+    "ResolvedHookMatcherGroup",
+    "build_hook_audit_event",
+    "canonicalize_hook_event_name",
+    "hook_audit_artifact_path",
+    "hook_audit_log_path",
+    "is_project_hooks_config_trusted",
+    "load_hook_config_file",
+    "load_resolved_hooks_config",
+    "load_trust_state",
+    "project_hooks_config_path",
+    "project_hooks_trust_key",
+    "project_local_hooks_config_path",
+    "read_hook_audit_events",
+    "save_trust_state",
+    "trust_project_hooks_config",
+    "trust_state_path",
+    "untrust_project_hooks_config",
+    "user_hooks_config_path",
+]

alysis_code/hooks/audit.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from ..error_text import sanitize_error_summary
+from ..session_store import sanitize_session_id
+from .models import HookInvocationContext
+
+HOOK_AUDIT_ARTIFACT_PARTS: tuple[str, str] = ("hooks", "hook_runs.jsonl")
+_MAX_WARNING_PREVIEW_ITEMS = 3
+_MAX_WARNING_PREVIEW_CHARS = 160
+
+
+def _now_ts() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _truncate_preview(text: str, *, max_chars: int = _MAX_WARNING_PREVIEW_CHARS) -> str:
+    return sanitize_error_summary(str(text or ""), max_chars=max_chars)
+
+
+def hook_audit_log_path(*, sessions_dir: Path, session_id: str) -> Path:
+    return (
+        sessions_dir
+        / sanitize_session_id(session_id)
+        / HOOK_AUDIT_ARTIFACT_PARTS[0]
+        / HOOK_AUDIT_ARTIFACT_PARTS[1]
+    )
+
+
+def hook_audit_artifact_path(*, sessions_dir: Path, session_id: str) -> Path:
+    return hook_audit_log_path(sessions_dir=sessions_dir, session_id=session_id)
+
+
+def _redacted_hook_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    warning_items = payload.get("warnings")
+    warning_list = [str(item) for item in warning_items] if isinstance(warning_items, list) else []
+    return {
+        "event_name": str(payload.get("event_name") or ""),
+        "source_path": str(payload.get("source_path") or ""),
+        "source_scope": str(payload.get("source_scope") or ""),
+        "matcher": str(payload.get("matcher") or ""),
+        "hook_id": str(payload.get("hook_id") or ""),
+        "priority": int(payload.get("priority") or 0),
+        "failure_policy": str(payload.get("failure_policy") or ""),
+        "command_preview": _truncate_preview(
+            str(payload.get("command") or ""),
+            max_chars=180,
+        ),
+        "timeout_s": float(payload.get("timeout_s") or 0.0),
+        "trusted": bool(payload.get("trusted")),
+        "returncode": payload.get("returncode"),
+        "blocked": bool(payload.get("blocked")),
+        "modified_input": bool(payload.get("modified_input")),
+        "modified_input_fields": [
+            str(item)
+            for item in (payload.get("modified_input_fields") or [])
+            if str(item or "").strip()
+        ],
+        "modified_prompt": bool(payload.get("modified_prompt")),
+        "modified_prompt_chars": int(payload.get("modified_prompt_chars") or 0),
+        "additional_system_message_count": int(payload.get("additional_system_message_count") or 0),
+        "additional_user_message_count": int(payload.get("additional_user_message_count") or 0),
+        "system_notices_count": int(payload.get("system_notices_count") or 0),
+        "halt_requested": bool(payload.get("halt_requested")),
+        "allow_short_circuited": bool(payload.get("allow_short_circuited")),
+        "suppress_output": bool(payload.get("suppress_output")),
+        "permission_decision": str(payload.get("permission_decision") or ""),
+        "stop_reason_preview": _truncate_preview(
+            str(payload.get("stop_reason") or ""),
+            max_chars=180,
+        ),
+        "stdout_chars": int(payload.get("stdout_chars") or 0),
+        "stderr_chars": int(payload.get("stderr_chars") or 0),
+        "duration_ms": int(payload.get("duration_ms") or 0),
+        "status": str(payload.get("status") or ""),
+        "warning_count": len(warning_list),
+        "warnings_preview": [
+            _truncate_preview(item) for item in warning_list[:_MAX_WARNING_PREVIEW_ITEMS]
+        ],
+        "payload_truncated": bool(payload.get("payload_truncated")),
+        "payload_bytes": int(payload.get("payload_bytes") or 0),
+    }
+
+
+class HookAuditLogger:
+    def __init__(self, *, path: Path, session_id: str) -> None:
+        self.path = path
+        self.session_id = session_id
+
+    def append(self, event: dict[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event, ensure_ascii=True) + "\n")
+
+    def close(self) -> None:
+        return None
+
+
+def read_hook_audit_events(path: Path) -> Iterable[dict[str, Any]]:
+    if not path.exists():
+        return
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(obj, dict):
+            yield obj
+
+
+def build_hook_audit_event(
+    *,
+    session_id: str,
+    context: HookInvocationContext,
+) -> dict[str, Any]:
+    payload = {
+        "event_name": context.event_name,
+        "source_path": context.source_path,
+        "source_scope": context.source_scope,
+        "matcher": context.matcher,
+        "hook_id": context.hook_id,
+        "priority": context.priority,
+        "failure_policy": context.failure_policy,
+        "command": context.command,
+        "timeout_s": context.timeout_s,
+        "trusted": context.trusted,
+        "returncode": context.returncode,
+        "blocked": context.blocked,
+        "modified_input": context.modified_input,
+        "modified_input_fields": list(context.modified_input_fields),
+        "modified_prompt": context.modified_prompt,
+        "modified_prompt_chars": context.modified_prompt_chars,
+        "additional_system_message_count": context.additional_system_message_count,
+        "additional_user_message_count": context.additional_user_message_count,
+        "system_notices_count": context.system_notices_count,
+        "halt_requested": context.halt_requested,
+        "allow_short_circuited": context.allow_short_circuited,
+        "suppress_output": context.suppress_output,
+        "permission_decision": context.permission_decision,
+        "stop_reason": context.stop_reason,
+        "stdout_chars": context.stdout_chars,
+        "stderr_chars": context.stderr_chars,
+        "duration_ms": context.duration_ms,
+        "status": context.status,
+        "warnings": list(context.warnings),
+        "payload_truncated": context.payload_truncated,
+        "payload_bytes": context.payload_bytes,
+    }
+    redacted = _redacted_hook_payload(payload)
+    redacted["type"] = "hook_command"
+    redacted["ts"] = _now_ts()
+    redacted["session_id"] = session_id
+    return redacted
+
+
+__all__ = [
+    "HOOK_AUDIT_ARTIFACT_PARTS",
+    "HookAuditLogger",
+    "build_hook_audit_event",
+    "hook_audit_artifact_path",
+    "hook_audit_log_path",
+    "read_hook_audit_events",
+]

alysis_code/hooks/config.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from ..branding import canonical_user_config_dir, env_get
+from ..config import ConfigError
+from .models import (
+    CanonicalHookEventName,
+    CommandHookSpec,
+    HookConfigFile,
+    HookEventName,
+    canonicalize_hook_event_name,
+)
+from .trust import is_project_hooks_config_trusted, load_trust_state
+
+
+def _hooks_config_dir() -> Path:
+    override = env_get("ALYSIS_CONFIG_DIR")
+    if override:
+        return Path(override)
+    return canonical_user_config_dir()
+
+
+def user_hooks_config_path() -> Path:
+    return _hooks_config_dir() / "hooks.json"
+
+
+def project_hooks_config_path(workspace_root: Path) -> Path:
+    return workspace_root.resolve() / ".alysis" / "hooks.json"
+
+
+def project_local_hooks_config_path(workspace_root: Path) -> Path:
+    return workspace_root.resolve() / ".alysis" / "hooks.local.json"
+
+
+def _read_json_object(path: Path) -> dict[str, Any]:
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise ConfigError(f"Failed to read hooks config: {path}") from exc
+    if not isinstance(raw, dict):
+        raise ConfigError(f"Invalid hooks config format (expected JSON object): {path}")
+    return raw
+
+
+def _format_validation_error(path: Path, exc: ValidationError) -> ConfigError:
+    details: list[str] = []
+    for err in exc.errors(include_url=False):
+        loc = ".".join(str(part) for part in err.get("loc", ()))
+        msg = str(err.get("msg") or "invalid value")
+        detail = f"{path}: {msg}" if not loc else f"{path}: {loc}: {msg}"
+        details.append(detail)
+    joined = "\n".join(details) if details else f"{path}: invalid hooks config"
+    return ConfigError(f"Invalid hooks config:\n{joined}")
+
+
+def _load_hook_config_file(path: Path) -> HookConfigFile:
+    raw = _read_json_object(path)
+    try:
+        return HookConfigFile.model_validate(raw)
+    except ValidationError as exc:
+        raise _format_validation_error(path, exc) from exc
+
+
+def load_hook_config_file(path: Path) -> HookConfigFile:
+    return _load_hook_config_file(path)
+
+
+@dataclass(frozen=True)
+class ResolvedHookMatcherGroup:
+    event_name: CanonicalHookEventName
+    matcher: str
+    hooks: tuple[CommandHookSpec, ...]
+    source_path: Path
+    source_scope: str
+    trusted: bool = True
+
+
+@dataclass(frozen=True)
+class ResolvedHookConfig:
+    groups_by_event: dict[str, tuple[ResolvedHookMatcherGroup, ...]] = field(default_factory=dict)
+    loaded_paths: tuple[Path, ...] = ()
+    untrusted_project_paths: tuple[Path, ...] = ()
+
+    @property
+    def has_any_hooks(self) -> bool:
+        return any(groups for groups in self.groups_by_event.values())
+
+    def groups_for_event(self, event_name: HookEventName) -> tuple[ResolvedHookMatcherGroup, ...]:
+        return self.groups_by_event.get(canonicalize_hook_event_name(event_name), ())
+
+
+def _resolve_groups_for_file(
+    *,
+    config_file: HookConfigFile,
+    source_path: Path,
+    source_scope: str,
+    trusted: bool,
+) -> dict[str, list[ResolvedHookMatcherGroup]]:
+    resolved: dict[str, list[ResolvedHookMatcherGroup]] = {}
+    for event_name, groups in config_file.hooks.items():
+        event_groups: list[ResolvedHookMatcherGroup] = []
+        for group in groups:
+            if not group.enabled:
+                continue
+            enabled_hooks = tuple(
+                sorted(
+                    (hook for hook in group.hooks if hook.enabled),
+                    key=lambda hook: (-hook.priority, hook.id or "", hook.command),
+                )
+            )
+            if not enabled_hooks:
+                continue
+            event_groups.append(
+                ResolvedHookMatcherGroup(
+                    event_name=event_name,
+                    matcher=str(group.matcher or ""),
+                    hooks=enabled_hooks,
+                    source_path=source_path,
+                    source_scope=source_scope,
+                    trusted=trusted,
+                )
+            )
+        if event_groups:
+            resolved[event_name] = event_groups
+    return resolved
+
+
+def _drop_overridden_hooks(
+    groups: list[ResolvedHookMatcherGroup],
+    *,
+    overridden_ids: set[str],
+) -> list[ResolvedHookMatcherGroup]:
+    if not overridden_ids:
+        return groups
+    retained: list[ResolvedHookMatcherGroup] = []
+    for group in groups:
+        remaining_hooks = tuple(hook for hook in group.hooks if hook.id not in overridden_ids)
+        if not remaining_hooks:
+            continue
+        if remaining_hooks == group.hooks:
+            retained.append(group)
+            continue
+        retained.append(
+            ResolvedHookMatcherGroup(
+                event_name=group.event_name,
+                matcher=group.matcher,
+                hooks=remaining_hooks,
+                source_path=group.source_path,
+                source_scope=group.source_scope,
+                trusted=group.trusted,
+            )
+        )
+    return retained
+
+
+def _merge_event_groups(
+    *,
+    existing: list[ResolvedHookMatcherGroup],
+    incoming: list[ResolvedHookMatcherGroup],
+) -> list[ResolvedHookMatcherGroup]:
+    override_ids = {hook.id for group in incoming for hook in group.hooks if hook.id is not None}
+    merged = _drop_overridden_hooks(existing, overridden_ids=override_ids)
+    merged.extend(incoming)
+    return merged
+
+
+def load_resolved_hooks_config(workspace_root: Path) -> ResolvedHookConfig:
+    workspace_root = workspace_root.resolve()
+    candidate_paths = (
+        (user_hooks_config_path(), "user"),
+        (project_hooks_config_path(workspace_root), "project"),
+        (project_local_hooks_config_path(workspace_root), "project_local"),
+    )
+    trust_state = load_trust_state()
+    merged: dict[str, list[ResolvedHookMatcherGroup]] = {}
+    loaded_paths: list[Path] = []
+    untrusted_project_paths: list[Path] = []
+    for path, source_scope in candidate_paths:
+        if not path.exists():
+            continue
+        trusted = source_scope != "project" or is_project_hooks_config_trusted(
+            workspace_root=workspace_root,
+            config_path=path,
+            state=trust_state,
+        )
+        loaded_paths.append(path)
+        if not trusted:
+            untrusted_project_paths.append(path)
+            continue
+        config_file = _load_hook_config_file(path)
+        resolved = _resolve_groups_for_file(
+            config_file=config_file,
+            source_path=path,
+            source_scope=source_scope,
+            trusted=trusted,
+        )
+        if not resolved:
+            continue
+        for event_name, groups in resolved.items():
+            merged[event_name] = _merge_event_groups(
+                existing=merged.get(event_name, []),
+                incoming=groups,
+            )
+    return ResolvedHookConfig(
+        groups_by_event={event_name: tuple(groups) for event_name, groups in merged.items()},
+        loaded_paths=tuple(loaded_paths),
+        untrusted_project_paths=tuple(untrusted_project_paths),
+    )
+
+
+__all__ = [
+    "ResolvedHookConfig",
+    "ResolvedHookMatcherGroup",
+    "load_hook_config_file",
+    "load_resolved_hooks_config",
+    "project_hooks_config_path",
+    "project_local_hooks_config_path",
+    "user_hooks_config_path",
+]