alysis-code 0.13.0__py3-none-any.whl

alysis_code/build_identity.py

@@ -0,0 +1,465 @@
+"""Non-fakeable build identity: which commit is actually running.
+
+Three behaviourally different builds once all reported themselves as version
+``0.9.8``, and one benchmark campaign turned out to have run against an
+unpinned "latest main". Every score those runs produced is therefore
+unattributable: there is no way, now, to say which source tree earned which
+number. A version string is a promise the developer makes; a commit hash
+recorded at build time is a fact about the artifact.
+
+This module owns three things:
+
+*The generated fact.* ``scripts/generate_build_info.py`` writes
+``_build_info.py`` next to this file, stamping the commit, an ISO-8601 UTC
+build timestamp, and whether the working tree carried uncommitted changes. The
+copy committed to the repository is a deliberate *dev default* -- no commit,
+marked dirty -- so that an artifact built without running the generator is
+correctly reported as unidentifiable rather than quietly inheriting a stale
+hash.
+
+*The reading.* :func:`load_build_info` tolerates the file being absent,
+truncated or hand-edited, because the failure mode that matters is a build
+that cannot prove its identity, and that must surface as a clear refusal
+rather than an import error.
+
+*The refusal.* :func:`decide_clean_build` is the policy behind
+``--require-clean-build`` / ``ALYSIS_REQUIRE_CLEAN_BUILD``. Benchmark
+harnesses set it so a campaign cannot start against a build whose provenance
+is unknown -- the precise mistake that cost the earlier campaign its meaning.
+
+Stdlib only, no package imports: the generator script runs this in a bare
+interpreter before the package is installable, and the tests load it straight
+from this file path.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import re
+import subprocess
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+BUILD_INFO_FILENAME = "_build_info.py"
+BUILD_INFO_SCHEMA_VERSION = 1
+
+REQUIRE_CLEAN_BUILD_ENV = "ALYSIS_REQUIRE_CLEAN_BUILD"
+
+#: Written into the committed dev default. Any artifact still reporting this
+#: source was built without the release generator.
+DEV_DEFAULT_SOURCE = "dev-default"
+GENERATED_SOURCE = "git"
+
+#: The generator rewrites this file immediately before the wheel is built, so
+#: git necessarily sees it as modified. Counting that self-inflicted edit as a
+#: dirty tree would make every release build report itself dirty, so the one
+#: path the generator writes is excluded from the dirty computation.
+DIRTY_CHECK_EXCLUDED_PATHS = ("src/alysis_code/" + BUILD_INFO_FILENAME,)
+
+_TRUTHY = frozenset({"1", "true", "yes", "on", "enabled", "require"})
+_COMMIT_RE = re.compile(r"\A[0-9a-f]{7,64}\Z")
+_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+_BUILD_INFO_ATTRIBUTES = (
+    "BUILD_COMMIT",
+    "BUILD_TIMESTAMP",
+    "BUILD_DIRTY",
+    "BUILD_SOURCE",
+    "BUILD_INFO_SCHEMA_VERSION",
+)
+
+UNKNOWN = "unknown"
+
+
+# ---------------------------------------------------------------------------
+# The record
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BuildInfo:
+    """What the artifact can prove about its own provenance."""
+
+    commit: str = ""
+    timestamp: str = ""
+    dirty: bool = True
+    source: str = DEV_DEFAULT_SOURCE
+    schema_version: int = BUILD_INFO_SCHEMA_VERSION
+
+    @property
+    def commit_short(self) -> str:
+        return self.commit[:12] if self.commit else ""
+
+    @property
+    def is_identifiable(self) -> bool:
+        """True when the recorded commit is a plausible git object name.
+
+        Shape is checked rather than trusted: a hand-edited ``_build_info.py``
+        containing ``BUILD_COMMIT = "probably main"`` must not pass for
+        provenance.
+        """
+        return bool(_COMMIT_RE.fullmatch(self.commit.strip().casefold()))
+
+    @property
+    def is_clean(self) -> bool:
+        return self.is_identifiable and not self.dirty
+
+    def describe(self) -> str:
+        """One-line human summary, as printed by ``alysis --version``."""
+        return (
+            f"commit: {self.commit_short or UNKNOWN}, "
+            f"built: {self.timestamp or UNKNOWN}, "
+            f"dirty: {'yes' if self.dirty else 'no'}, "
+            f"source: {self.source or UNKNOWN}"
+        )
+
+    def telemetry_payload(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "commit": self.commit,
+            "commit_short": self.commit_short,
+            "timestamp": self.timestamp,
+            "dirty": self.dirty,
+            "source": self.source,
+            "identifiable": self.is_identifiable,
+            "clean": self.is_clean,
+        }
+
+
+DEV_DEFAULT_BUILD_INFO = BuildInfo()
+
+
+def version_line(version: str, info: BuildInfo | None = None) -> str:
+    """Render the ``--version`` line.
+
+    The bare version stays the leading token and the whole thing stays on one
+    line: the VS Code extension, the managed-CLI smoke test and the release
+    distribution validator all read this output, and they read it by prefix,
+    substring and non-emptiness respectively.
+    """
+    resolved = load_build_info() if info is None else info
+    return f"{str(version).strip()} ({resolved.describe()})"
+
+
+# ---------------------------------------------------------------------------
+# Reading the generated file
+# ---------------------------------------------------------------------------
+
+
+def _coerce_build_info(namespace: Mapping[str, Any]) -> BuildInfo:
+    commit = str(namespace.get("BUILD_COMMIT") or "").strip()
+    timestamp = str(namespace.get("BUILD_TIMESTAMP") or "").strip()
+    source = str(namespace.get("BUILD_SOURCE") or "").strip() or DEV_DEFAULT_SOURCE
+    raw_dirty = namespace.get("BUILD_DIRTY", True)
+    # Anything unparseable resolves to dirty. Provenance failures must fail
+    # closed: a build that cannot say whether it was clean is not clean.
+    if isinstance(raw_dirty, bool):
+        dirty = raw_dirty
+    elif isinstance(raw_dirty, (int, float)):
+        dirty = bool(raw_dirty)
+    elif isinstance(raw_dirty, str):
+        dirty = raw_dirty.strip().casefold() not in {"false", "0", "no", "off"}
+    else:
+        dirty = True
+    try:
+        schema_version = int(namespace.get("BUILD_INFO_SCHEMA_VERSION", BUILD_INFO_SCHEMA_VERSION))
+    except (TypeError, ValueError):
+        schema_version = BUILD_INFO_SCHEMA_VERSION
+    return BuildInfo(
+        commit=commit,
+        timestamp=timestamp,
+        dirty=dirty,
+        source=source,
+        schema_version=schema_version,
+    )
+
+
+def _namespace_from_path(path: Path) -> dict[str, Any] | None:
+    try:
+        if not path.is_file():
+            return None
+        spec = importlib.util.spec_from_file_location("_alysis_build_info", path)
+        if spec is None or spec.loader is None:
+            return None
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+    except Exception:  # noqa: BLE001 - a corrupt stamp must not break startup
+        return None
+    return {name: getattr(module, name) for name in _BUILD_INFO_ATTRIBUTES if hasattr(module, name)}
+
+
+def default_build_info_path() -> Path:
+    return Path(__file__).resolve().parent / BUILD_INFO_FILENAME
+
+
+def read_build_info(path: str | os.PathLike[str] | None = None) -> BuildInfo:
+    """Read build info from disk, uncached.
+
+    Prefers the installed package module so a frozen or zipped distribution
+    resolves the same way the rest of the package does, and falls back to
+    loading the sibling file by path -- which is also what makes this readable
+    from a bare interpreter that has never imported the package.
+    """
+    if path is None:
+        try:
+            from . import _build_info as module  # noqa: PLC0415
+        except ImportError:
+            module = None
+        except Exception:  # noqa: BLE001 - corrupt stamp, fall through to path load
+            module = None
+        if module is not None:
+            namespace = {
+                name: getattr(module, name)
+                for name in _BUILD_INFO_ATTRIBUTES
+                if hasattr(module, name)
+            }
+            if namespace:
+                return _coerce_build_info(namespace)
+        path = default_build_info_path()
+    namespace = _namespace_from_path(Path(path))
+    if namespace is None:
+        return DEV_DEFAULT_BUILD_INFO
+    return _coerce_build_info(namespace)
+
+
+_CACHED_BUILD_INFO: BuildInfo | None = None
+
+
+def load_build_info() -> BuildInfo:
+    """Read build info once per process."""
+    global _CACHED_BUILD_INFO
+    if _CACHED_BUILD_INFO is None:
+        _CACHED_BUILD_INFO = read_build_info()
+    return _CACHED_BUILD_INFO
+
+
+def reset_build_info_cache_for_tests() -> None:
+    global _CACHED_BUILD_INFO
+    _CACHED_BUILD_INFO = None
+
+
+# ---------------------------------------------------------------------------
+# Generating the file
+# ---------------------------------------------------------------------------
+
+GitRunner = Callable[[Sequence[str]], "tuple[int, str]"]
+
+
+def _run_git(args: Sequence[str], *, cwd: Path) -> tuple[int, str]:
+    try:
+        completed = subprocess.run(  # noqa: S603 - fixed argv, no shell
+            ["git", *args],
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return 1, ""
+    return completed.returncode, completed.stdout
+
+
+def build_timestamp(
+    now: datetime | None = None,
+    *,
+    environ: Mapping[str, str] | None = None,
+) -> str:
+    """ISO-8601 UTC build timestamp, honouring ``SOURCE_DATE_EPOCH``.
+
+    The reproducible-builds variable is respected so that a deliberately
+    reproducible release does not become irreproducible because of this stamp.
+    """
+    source: Mapping[str, str] = os.environ if environ is None else environ
+    raw_epoch = str(source.get("SOURCE_DATE_EPOCH") or "").strip()
+    if raw_epoch:
+        try:
+            return datetime.fromtimestamp(int(raw_epoch), tz=timezone.utc).strftime(
+                _TIMESTAMP_FORMAT
+            )
+        except (TypeError, ValueError, OSError, OverflowError):
+            pass
+    moment = datetime.now(timezone.utc) if now is None else now
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=timezone.utc)
+    return moment.astimezone(timezone.utc).strftime(_TIMESTAMP_FORMAT)
+
+
+def parse_dirty_status(porcelain_output: str) -> bool:
+    """Decide dirtiness from ``git status --porcelain`` output.
+
+    The generator's own output file is excluded (see
+    :data:`DIRTY_CHECK_EXCLUDED_PATHS`); everything else that git reports --
+    modified, staged, or untracked-and-not-ignored -- counts, because any of
+    them can change what the built artifact actually executes.
+    """
+    for line in str(porcelain_output or "").splitlines():
+        entry = line.strip()
+        if not entry:
+            continue
+        # Porcelain v1: two status characters, a space, then the path. A rename
+        # reads "R  old -> new"; the destination is what ships.
+        path = entry[2:].strip() if len(entry) > 2 else ""
+        if "->" in path:
+            path = path.split("->")[-1].strip()
+        path = path.strip('"')
+        if path and path not in DIRTY_CHECK_EXCLUDED_PATHS:
+            return True
+    return False
+
+
+def generate_build_info(
+    *,
+    repo_root: str | os.PathLike[str],
+    now: datetime | None = None,
+    git_runner: GitRunner | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> BuildInfo:
+    """Interrogate git and return the build stamp for the current tree.
+
+    A tree with no git available, or no repository, yields the dev default:
+    unidentifiable and dirty. That is the honest answer, and it is the answer
+    ``--require-clean-build`` is designed to reject.
+    """
+    root = Path(repo_root)
+    runner: GitRunner = git_runner if git_runner is not None else (lambda a: _run_git(a, cwd=root))
+
+    code, out = runner(["rev-parse", "HEAD"])
+    commit = out.strip().splitlines()[0].strip().casefold() if code == 0 and out.strip() else ""
+    if not _COMMIT_RE.fullmatch(commit):
+        return BuildInfo(
+            commit="",
+            timestamp=build_timestamp(now, environ=environ),
+            dirty=True,
+            source=DEV_DEFAULT_SOURCE,
+        )
+
+    status_code, status_out = runner(["status", "--porcelain"])
+    # A failed status probe is treated as dirty for the same fail-closed reason
+    # as an unparseable stamp: not knowing is not the same as being clean.
+    dirty = True if status_code != 0 else parse_dirty_status(status_out)
+    return BuildInfo(
+        commit=commit,
+        timestamp=build_timestamp(now, environ=environ),
+        dirty=dirty,
+        source=GENERATED_SOURCE,
+    )
+
+
+def render_build_info_module(info: BuildInfo) -> str:
+    """Render the generated ``_build_info.py`` source text.
+
+    String literals are emitted via ``json.dumps`` rather than ``repr`` so the
+    generated file is double-quoted and survives the repository's
+    ``ruff format`` check unchanged.
+    """
+    return (
+        '"""Generated build identity. Do not edit by hand.\n'
+        "\n"
+        "Regenerate with ``python3 scripts/generate_build_info.py``. The copy\n"
+        "committed to the repository is the dev default and deliberately reports an\n"
+        "unidentifiable build, so that an artifact built without running the\n"
+        "generator is refused by ``--require-clean-build`` instead of inheriting a\n"
+        "stale commit hash.\n"
+        '"""\n'
+        "\n"
+        f"BUILD_COMMIT = {json.dumps(info.commit)}\n"
+        f"BUILD_TIMESTAMP = {json.dumps(info.timestamp)}\n"
+        f"BUILD_DIRTY = {bool(info.dirty)!r}\n"
+        f"BUILD_SOURCE = {json.dumps(info.source)}\n"
+        f"BUILD_INFO_SCHEMA_VERSION = {int(info.schema_version)!r}\n"
+    )
+
+
+def write_build_info(info: BuildInfo, path: str | os.PathLike[str]) -> Path:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(render_build_info_module(info), encoding="utf-8", newline="\n")
+    return target
+
+
+# ---------------------------------------------------------------------------
+# The refusal
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CleanBuildDecision:
+    """Whether startup may proceed under ``--require-clean-build``."""
+
+    required: bool
+    allowed: bool
+    reason: str
+    message: str = ""
+
+    def payload(self) -> dict[str, Any]:
+        return {
+            "required": self.required,
+            "allowed": self.allowed,
+            "reason": self.reason,
+        }
+
+
+def require_clean_build_requested(
+    *,
+    environ: Mapping[str, str] | None = None,
+    flag: bool | None = None,
+) -> bool:
+    """True when this run must refuse an unidentifiable build.
+
+    An explicit ``--require-clean-build`` wins over the environment; otherwise
+    the harness-set variable decides. An unrecognised value means "not
+    requested" rather than an error, so a typo cannot silently *enable* a
+    refusal that then looks like a build problem.
+    """
+    if flag:
+        return True
+    source: Mapping[str, str] = os.environ if environ is None else environ
+    raw = str(source.get(REQUIRE_CLEAN_BUILD_ENV) or "").strip().casefold()
+    return raw in _TRUTHY
+
+
+def decide_clean_build(
+    *,
+    info: BuildInfo | None = None,
+    environ: Mapping[str, str] | None = None,
+    flag: bool | None = None,
+) -> CleanBuildDecision:
+    """Decide whether a run may start, and say why not in words an operator can act on."""
+    resolved = load_build_info() if info is None else info
+    required = require_clean_build_requested(environ=environ, flag=flag)
+    if not required:
+        return CleanBuildDecision(required=False, allowed=True, reason="not_required")
+    if not resolved.is_identifiable:
+        return CleanBuildDecision(
+            required=True,
+            allowed=False,
+            reason="missing_commit",
+            message=(
+                "This build cannot identify itself: no commit hash was recorded at "
+                f"build time (source: {resolved.source or UNKNOWN}). "
+                f"{REQUIRE_CLEAN_BUILD_ENV} is set, so the run is refused rather than "
+                "producing results that cannot be attributed to a source tree. "
+                "Rebuild after running scripts/generate_build_info.py, or unset "
+                f"{REQUIRE_CLEAN_BUILD_ENV} to proceed with an unidentifiable build."
+            ),
+        )
+    if resolved.dirty:
+        return CleanBuildDecision(
+            required=True,
+            allowed=False,
+            reason="dirty_tree",
+            message=(
+                f"This build was made from a dirty working tree at commit "
+                f"{resolved.commit_short} (built {resolved.timestamp or UNKNOWN}). "
+                f"{REQUIRE_CLEAN_BUILD_ENV} is set, so the run is refused: the commit "
+                "alone does not describe the code that would run. Commit or stash the "
+                f"changes and rebuild, or unset {REQUIRE_CLEAN_BUILD_ENV}."
+            ),
+        )
+    return CleanBuildDecision(required=True, allowed=True, reason="clean")

alysis_code/builtin_hooks/__init__.py

@@ -0,0 +1,7 @@
+"""Built-in hook handlers shipped with alysis-code.
+
+Users can reference these modules from hooks.json with commands like
+`python -m alysis_code.builtin_hooks.<name>`.
+"""
+
+from __future__ import annotations

alysis_code/builtin_hooks/notify_done_windows.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Windows-native lifecycle notification hook using winsound.
+
+Built-in handler shipped with alysis-code; no path discovery needed.
+Handles TurnComplete and Notification events.
+TurnComplete with exit_code 0 plays MB_ICONASTERISK.
+TurnComplete with any other exit_code plays MB_ICONHAND.
+Notification with cause "pre_tool_use_blocked" plays MB_ICONEXCLAMATION.
+Other Notification causes play MB_ICONQUESTION.
+Other hook events exit silently.
+Example .alysis/hooks.json:
+    {"hooks": {"TurnComplete": [{"hooks": [{"type": "command",
+      "command": "python -m alysis_code.builtin_hooks.notify_done_windows"}]}],
+      "Notification": [{"hooks": [{"type": "command",
+      "command": "python -m alysis_code.builtin_hooks.notify_done_windows"}]}]}}
+The hook never writes stdout, so dispatcher JSON parsing stays clean.
+On non-Windows or unavailable audio devices it exits 0 silently.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+try:
+    import winsound
+except ImportError:
+    winsound = None
+
+
+def _read_payload() -> dict:
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _beep(sound: int) -> None:
+    if winsound is None:
+        return
+    try:
+        winsound.MessageBeep(sound)
+    except Exception:  # noqa: BLE001 - notification hooks must never break a turn.
+        pass
+
+
+def main() -> int:
+    if winsound is None:
+        return 0
+    payload = _read_payload()
+    event_name = payload.get("hook_event_name")
+    if event_name == "TurnComplete":
+        sound = winsound.MB_ICONASTERISK if payload.get("exit_code") == 0 else winsound.MB_ICONHAND
+        _beep(sound)
+    elif event_name == "Notification":
+        if payload.get("cause") == "pre_tool_use_blocked":
+            _beep(winsound.MB_ICONEXCLAMATION)
+        else:
+            _beep(winsound.MB_ICONQUESTION)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

alysis_code/bwrap_etc.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+_VALID_NETWORK = {"off", "on"}
+
+
+def _write_if_changed(path: Path, content: str) -> None:
+    if path.exists():
+        try:
+            if path.read_text(encoding="utf-8") == content:
+                return
+        except OSError:
+            pass
+    path.write_text(content, encoding="utf-8")
+
+
+def _resolve_uid_gid() -> tuple[int, int]:
+    uid = 0
+    gid = 0
+    if hasattr(os, "getuid"):
+        try:
+            uid = int(os.getuid())
+        except OSError:
+            uid = 0
+    if hasattr(os, "getgid"):
+        try:
+            gid = int(os.getgid())
+        except OSError:
+            gid = 0
+    return uid, gid
+
+
+def ensure_minimal_etc_dir(*, network: str) -> Path:
+    mode = str(network).strip().lower()
+    if mode not in _VALID_NETWORK:
+        raise ValueError(f"Invalid network mode for minimal /etc: {network!r}")
+
+    root = Path(tempfile.gettempdir()) / "alysis-code" / "bwrap-etc" / mode
+    root.mkdir(parents=True, exist_ok=True)
+
+    uid, gid = _resolve_uid_gid()
+    passwd_lines = ["root:x:0:0:root:/tmp/home:/bin/sh"]
+    if uid != 0:
+        passwd_lines.append(f"user:x:{uid}:{gid}:user:/tmp/home:/bin/sh")
+    _write_if_changed(root / "passwd", "\n".join(passwd_lines) + "\n")
+
+    group_lines = ["root:x:0:"]
+    if gid != 0:
+        group_lines.append(f"user:x:{gid}:")
+    _write_if_changed(root / "group", "\n".join(group_lines) + "\n")
+
+    _write_if_changed(
+        root / "nsswitch.conf",
+        "passwd: files\ngroup: files\nhosts: files dns\n",
+    )
+    _write_if_changed(root / "hosts", "127.0.0.1 localhost\n::1 localhost\n")
+
+    resolv_path = root / "resolv.conf"
+    if mode == "on":
+        host_resolv = Path("/etc/resolv.conf")
+        try:
+            if host_resolv.exists():
+                _write_if_changed(resolv_path, host_resolv.read_text(encoding="utf-8"))
+            else:
+                _write_if_changed(resolv_path, "")
+        except OSError:
+            _write_if_changed(resolv_path, "")
+    else:
+        _write_if_changed(resolv_path, "")
+
+    (root / "ssl").mkdir(parents=True, exist_ok=True)
+    (root / "ssl" / "certs").mkdir(parents=True, exist_ok=True)
+    return root

alysis_code/cancellation.py

@@ -0,0 +1,41 @@
+"""Shared cooperative-cancellation primitives.
+
+One token discipline for every long-running execution surface (IDE bridge
+jobs, Forge swarm workers): a ``threading.Event`` is the single cancel
+signal, a token wraps it for duck-typed checkpoints, and cancellation
+surfaces as a dedicated exception type so callers can distinguish a
+cooperative stop from a failure.
+
+The agent turn engine (``agent/turn/core.py``) duck-types tokens: it calls
+``throw_if_cancelled()`` when available, otherwise checks ``is_cancelled``.
+Both behaviors are provided here.
+"""
+
+from __future__ import annotations
+
+import threading
+
+
+class CooperativeCancellationError(Exception):
+    """Raised at a cooperative checkpoint after cancellation was requested."""
+
+    def __init__(self, reason: str = "cancelled_by_user") -> None:
+        super().__init__(reason)
+        self.reason = str(reason or "cancelled_by_user")
+
+
+class EventCancellationToken:
+    """Duck-typed cancellation token backed by a ``threading.Event``."""
+
+    error_class: type[CooperativeCancellationError] = CooperativeCancellationError
+
+    def __init__(self, event: threading.Event) -> None:
+        self._event = event
+
+    @property
+    def is_cancelled(self) -> bool:
+        return self._event.is_set()
+
+    def throw_if_cancelled(self, reason: str = "cancelled_by_user") -> None:
+        if self.is_cancelled:
+            raise self.error_class(reason)