techtree 0.1.0__py3-none-any.whl

techtree/engines/registry.py

@@ -0,0 +1,235 @@
+"""Which engines exist, where they live, and which one is active.
+
+Spec section 20.4.
+
+An engine is identified by the digest of its static bundle, and that digest is
+also where it lives: ``<techtree home>/engines/sha256-<hex>/``. Two consequences
+follow, and both are the point.
+
+Nothing here decides anything about *content*. The registry answers questions
+about the filesystem and about settings; whether the environment inside an
+engine actually works is the installer's question, asked by running the engine.
+
+An engine counts as installed only when its ``installed.json`` is present,
+parses, and names the directory it sits in. That file is written last, after
+verification, so a directory left behind by an interrupted install is reported
+as absent rather than as broken — and the next install replaces it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Final
+
+from techtree.canonical import validate_digest
+from techtree.engines.bundle import (
+    ENGINE_TOOLS,
+    INSTALLATION_FILENAME,
+    default_engine_digest,
+)
+from techtree.errors import EngineError, NotFoundError, ValidationError
+from techtree.fs import atomic_write_json
+from techtree.models.base import Digest
+from techtree.models.engine import EngineInstallation, EngineStatus
+from techtree.paths import TechtreePaths
+from techtree.settings import Settings, load_settings, save_settings
+
+__all__ = ["VENV_DIRECTORY", "EngineRegistry", "digest_from_directory_name"]
+
+#: uv's project environment, relative to the engine root.
+VENV_DIRECTORY: Final = ".venv"
+_BIN_DIRECTORY: Final = "bin"
+_TOOLS_DIRECTORY: Final = "tools"
+
+
+class EngineRegistry:
+    """Locates engines and records which one is active."""
+
+    def __init__(self, paths: TechtreePaths, settings: Settings) -> None:
+        self._paths = paths
+        self._settings = settings
+
+    # -- what exists ------------------------------------------------------
+
+    def known(self) -> list[Digest]:
+        """Return the packaged digest and every installed digest."""
+        digests = {default_engine_digest(), *self.installed()}
+        return sorted(digests)
+
+    def installed(self) -> list[Digest]:
+        """Return the digests of complete installations."""
+        if not self._paths.engines_dir.is_dir():
+            return []
+
+        found: list[Digest] = []
+        for directory in sorted(self._paths.engines_dir.iterdir()):
+            if not directory.is_dir():
+                continue
+            digest = digest_from_directory_name(directory.name)
+            if digest is None:
+                continue
+            if self.installation(digest) is not None:
+                found.append(digest)
+        return found
+
+    def installation(self, digest: Digest) -> EngineInstallation | None:
+        """Return the recorded installation, or None when there is not one.
+
+        A record that does not name this directory is not this engine's record,
+        so it is treated as absent rather than trusted.
+        """
+        marker = self.path(digest) / INSTALLATION_FILENAME
+        try:
+            raw = marker.read_bytes()
+        except (FileNotFoundError, NotADirectoryError):
+            return None
+
+        try:
+            installation = EngineInstallation.model_validate_json(raw)
+        except ValueError:
+            return None
+
+        if installation.digest != digest:
+            return None
+        return installation
+
+    def record(self, installation: EngineInstallation) -> None:
+        """Write the installation marker that completes an install."""
+        atomic_write_json(
+            self.path(installation.digest) / INSTALLATION_FILENAME, installation
+        )
+
+    # -- where things are -------------------------------------------------
+
+    def path(self, digest: Digest) -> Path:
+        """Return the installation directory for one engine."""
+        return self._paths.engine_dir(validate_digest(digest))
+
+    def python(self, digest: Digest) -> Path:
+        """Return the engine's managed interpreter."""
+        return self.path(digest) / VENV_DIRECTORY / _BIN_DIRECTORY / "python"
+
+    def executable(self, digest: Digest, name: str) -> Path:
+        """Return one console script inside the engine environment.
+
+        The pinned Verifiers build installs its scripts under generic names —
+        ``validate``, ``eval`` — so they are always addressed by absolute path
+        inside the engine and never resolved through ``PATH``
+        (``docs/verifiers-pin.md``, finding C3).
+        """
+        return self.path(digest) / VENV_DIRECTORY / _BIN_DIRECTORY / _plain(name)
+
+    def tool_path(self, digest: Digest, tool: str) -> Path:
+        """Return one engine helper shipped inside the bundle.
+
+        Decisions document 0003 A3. Only the helpers the bundle declares can be
+        addressed, so a caller cannot turn this into "run any file you like
+        with the engine interpreter".
+        """
+        if tool not in ENGINE_TOOLS:
+            raise NotFoundError(
+                f"the engine bundle ships no tool named {tool!r}",
+                code="engine_tool_unknown",
+                details={"tool": tool, "available": list(ENGINE_TOOLS)},
+            )
+        return self.path(digest) / _TOOLS_DIRECTORY / tool
+
+    # -- status and activation --------------------------------------------
+
+    def status(self, digest: Digest) -> EngineStatus:
+        """Return what is currently true about one engine."""
+        installation = self.installation(digest)
+        active = self.active_digest() == digest
+
+        if installation is None:
+            return EngineStatus(
+                digest=digest,
+                installed=False,
+                active=False,
+                verified=False,
+                path=str(self.path(digest)),
+                python_executable=None,
+                detail=_absent_detail(digest, active=active),
+            )
+
+        return EngineStatus(
+            digest=digest,
+            installed=True,
+            active=active,
+            verified=installation.verified,
+            path=str(self.path(digest)),
+            python_executable=installation.python_executable,
+            detail=_present_detail(installation.verified, active=active),
+        )
+
+    def active_digest(self) -> Digest | None:
+        """Return the digest of the active engine, if one is recorded."""
+        return self._settings.active_engine_digest
+
+    def set_active(self, digest: Digest) -> Settings:
+        """Record one verified engine as active.
+
+        Activation is a claim the CLI makes to every later command, so it is
+        refused unless the engine is installed and its installation was
+        verified. Verification itself belongs to the installer, which runs the
+        engine; this reads the result it recorded.
+        """
+        installation = self.installation(validate_digest(digest))
+        if installation is None:
+            raise EngineError(
+                f"engine {digest} is not installed, so it cannot be made active",
+                code="engine_not_installed",
+                details={"digest": digest, "path": str(self.path(digest))},
+            )
+        if not installation.verified:
+            raise EngineError(
+                f"engine {digest} was never verified, so it cannot be made active",
+                code="engine_not_verified",
+                details={"digest": digest},
+            )
+
+        # Settings are re-read rather than written from this object's copy, so
+        # concurrently changed preferences are not reverted by an activation.
+        settings = load_settings(self._paths).model_copy(
+            update={"active_engine_digest": digest}
+        )
+        save_settings(self._paths, settings)
+        self._settings = settings
+        return settings
+
+
+def _plain(name: str) -> str:
+    """Reject anything that is not a bare file name."""
+    if not name or "/" in name or name in {".", ".."}:
+        raise EngineError(
+            f"{name!r} is not an engine executable name",
+            code="engine_executable_invalid",
+            details={"name": name},
+        )
+    return name
+
+
+def digest_from_directory_name(name: str) -> Digest | None:
+    """Return the digest a directory name encodes, or None if it encodes none."""
+    algorithm, separator, hexadecimal = name.partition("-")
+    if separator != "-" or algorithm != "sha256":
+        return None
+    candidate = f"{algorithm}:{hexadecimal}"
+    try:
+        return validate_digest(candidate)
+    except ValidationError:
+        return None
+
+
+def _absent_detail(digest: Digest, *, active: bool) -> str:
+    if active:
+        return (
+            f"engine {digest} is recorded as active but is not installed; "
+            "install it again"
+        )
+    return "not installed"
+
+
+def _present_detail(verified: bool, *, active: bool) -> str:
+    state = "installed and verified" if verified else "installed but not verified"
+    return f"{state}, {'active' if active else 'not the active engine'}"

techtree/engines/runner.py

@@ -0,0 +1,170 @@
+"""Running one command inside the managed engine. Spec section 20.5.
+
+Two rules shape every invocation.
+
+*Absolute paths, never ``PATH``.* The pinned Verifiers build installs console
+scripts under names as generic as ``validate`` and ``eval``
+(``docs/verifiers-pin.md``, finding C3). Resolving those through the caller's
+``PATH`` would let anything on the machine answer for the engine, so the engine
+addresses its own executables by absolute path and the environment it runs them
+in carries a ``PATH`` for the operating system's benefit, not for lookup.
+
+*A minimal environment.* Model-free validation needs no provider credential,
+and a subprocess that never receives one cannot leak one. The child gets
+``PATH``, ``HOME``, and ``TMPDIR``, plus whatever the caller passes explicitly.
+Everything else in the parent environment — API keys, tokens, cloud
+credentials, the caller's Python configuration — is dropped.
+
+The result of a run is data, not a decision. ``validate`` exits ``0`` even when
+every task fails (``docs/verifiers-pin.md``, finding C2), so nothing here maps
+an exit code onto a verdict; callers read the summary the engine wrote.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from techtree.engines.registry import EngineRegistry
+from techtree.errors import EngineError
+from techtree.models.base import Digest
+
+__all__ = ["INHERITED_ENVIRONMENT", "EngineProcessResult", "EngineRunner"]
+
+#: The only variables an engine process inherits from its parent. ``PATH`` so
+#: the child can find ordinary system tools, ``HOME`` because caches and
+#: configuration hang off it, ``TMPDIR`` so scratch files land where the host
+#: expects them.
+INHERITED_ENVIRONMENT: Final[tuple[str, ...]] = ("PATH", "HOME", "TMPDIR")
+
+#: Prefix of the variables a caller may add. Anything else has to be passed
+#: deliberately by name, which keeps "just forward the environment" from being
+#: the easy option.
+_TECHTREE_PREFIX: Final = "TECHTREE_"
+
+
+@dataclass(frozen=True)
+class EngineProcessResult:
+    """What one engine command did."""
+
+    argv: tuple[str, ...]
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_seconds: float
+
+
+class EngineRunner:
+    """Runs commands inside one installed engine."""
+
+    def __init__(self, registry: EngineRegistry, digest: Digest) -> None:
+        self._registry = registry
+        self._digest = digest
+
+    def run(
+        self,
+        executable: str,
+        args: Sequence[str],
+        *,
+        timeout: float,
+        env: Mapping[str, str] | None = None,
+        cwd: Path | None = None,
+    ) -> EngineProcessResult:
+        """Run one console script from the engine environment."""
+        return self._execute(
+            [str(self._registry.executable(self._digest, executable)), *args],
+            timeout=timeout,
+            env=env,
+            cwd=cwd,
+        )
+
+    def run_python_script(
+        self,
+        script: Path,
+        args: Sequence[str],
+        *,
+        timeout: float,
+        env: Mapping[str, str] | None = None,
+    ) -> EngineProcessResult:
+        """Run one Python file with the engine's own interpreter."""
+        return self._execute(
+            [str(self._registry.python(self._digest)), str(script), *args],
+            timeout=timeout,
+            env=env,
+        )
+
+    def _execute(
+        self,
+        argv: Sequence[str],
+        *,
+        timeout: float,
+        env: Mapping[str, str] | None,
+        cwd: Path | None = None,
+    ) -> EngineProcessResult:
+        program = Path(argv[0])
+        if not program.is_file():
+            raise EngineError(
+                f"engine {self._digest} has no executable at {program}; "
+                "install the engine again",
+                code="engine_executable_missing",
+                details={"digest": self._digest, "path": str(program)},
+            )
+
+        started = time.monotonic()
+        try:
+            completed = subprocess.run(
+                list(argv),
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=timeout,
+                stdin=subprocess.DEVNULL,
+                env=engine_environment(env),
+                cwd=None if cwd is None else str(cwd),
+            )
+        except subprocess.TimeoutExpired as error:
+            raise EngineError(
+                f"engine command did not finish within {timeout:.0f}s: {program.name}",
+                code="engine_command_timeout",
+                details={"digest": self._digest, "timeout_seconds": timeout},
+                retryable=True,
+            ) from error
+        except OSError as error:
+            raise EngineError(
+                f"engine command could not be started: {error.strerror or error}",
+                code="engine_command_unusable",
+                details={"digest": self._digest, "path": str(program)},
+            ) from error
+
+        return EngineProcessResult(
+            argv=tuple(argv),
+            exit_code=completed.returncode,
+            stdout=completed.stdout,
+            stderr=completed.stderr,
+            duration_seconds=time.monotonic() - started,
+        )
+
+
+def engine_environment(extra: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Build the minimal environment an engine process runs in."""
+    environment = {
+        name: os.environ[name] for name in INHERITED_ENVIRONMENT if name in os.environ
+    }
+
+    for name, value in (extra or {}).items():
+        if not name.startswith(_TECHTREE_PREFIX) and name not in INHERITED_ENVIRONMENT:
+            raise EngineError(
+                f"{name} cannot be passed to an engine process; only "
+                f"{_TECHTREE_PREFIX}* variables and "
+                f"{', '.join(INHERITED_ENVIRONMENT)} are allowed",
+                code="engine_environment_rejected",
+                details={"variable": name},
+            )
+        environment[name] = value
+
+    return environment

techtree/errors.py

@@ -0,0 +1,262 @@
+"""Typed Techtree errors and the exit codes they map to. Spec section 10.5.
+
+Every failure a user can provoke is one of the classes below. Each class fixes
+a machine-stable ``code``, a documented process exit code, and whether retrying
+the same command could plausibly succeed. Call sites override those defaults
+only when they have something more specific to say.
+
+Two rules shape this module:
+
+* ``details`` is machine-facing and travels into JSON output, so it carries
+  identifiers, counts, and paths. Nothing filters it: decision 0036 removed
+  every secret-shaped-string detector from this project, so what a call site
+  puts in ``details`` is what a caller reads, including when the call site is
+  forwarding a subprocess's own words.
+* Human-facing text is actionable. Tracebacks are debugging aids for stderr,
+  not part of the contract, which is why
+  :func:`stable_exception_message` exists for the unexpected-exception path.
+
+An error can also carry the ``NextAction`` list the CLI should offer, so that
+the code which knows *why* something failed is the code that says what to do
+about it. The shapes those actions and the projected ``CliError`` are spelled
+in belong to :mod:`techtree.models.cli`. That module is imported only for
+typing, and inside :func:`error_to_cli_error`, because the model package
+imports this one: errors sit underneath models, and speaking a model's
+vocabulary must not invert that.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, ClassVar, Final
+
+if TYPE_CHECKING:
+    from techtree.models.base import JsonValue
+    from techtree.models.cli import CliError, NextAction
+
+__all__ = [
+    "AuthenticationError",
+    "CancellationError",
+    "ConflictError",
+    "EngineError",
+    "NotFoundError",
+    "PolicyError",
+    "PrerequisiteError",
+    "RunError",
+    "TechtreeError",
+    "UsageError",
+    "ValidationError",
+    "VerificationError",
+    "error_to_cli_error",
+    "exit_code_for",
+    "stable_exception_message",
+]
+
+
+# ---------------------------------------------------------------------------
+# Exit codes
+#
+# These are part of the CLI contract: a host agent branches on them without
+# parsing output. Values are append-only; never reuse a retired number.
+# ---------------------------------------------------------------------------
+
+EXIT_OK: Final = 0
+EXIT_ERROR: Final = 1
+EXIT_USAGE: Final = 2
+EXIT_VALIDATION: Final = 3
+EXIT_PREREQUISITE: Final = 4
+EXIT_NOT_FOUND: Final = 5
+EXIT_CONFLICT: Final = 6
+EXIT_AUTHENTICATION: Final = 7
+EXIT_POLICY: Final = 8
+EXIT_ENGINE: Final = 9
+EXIT_RUN: Final = 10
+EXIT_VERIFICATION: Final = 11
+#: The shell convention for "terminated by SIGINT", which is what a cancelled
+#: run is from the caller's point of view.
+EXIT_CANCELLED: Final = 130
+
+
+# ---------------------------------------------------------------------------
+# Hierarchy
+# ---------------------------------------------------------------------------
+
+
+class TechtreeError(Exception):
+    """Base class for every failure Techtree reports on purpose."""
+
+    default_code: ClassVar[str] = "techtree_error"
+    default_exit_code: ClassVar[int] = EXIT_ERROR
+    default_retryable: ClassVar[bool] = False
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        exit_code: int | None = None,
+        retryable: bool | None = None,
+        details: Mapping[str, JsonValue] | None = None,
+        next_actions: Sequence[NextAction] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = self.default_code if code is None else code
+        self.exit_code = self.default_exit_code if exit_code is None else exit_code
+        self.retryable = self.default_retryable if retryable is None else retryable
+        self.details: dict[str, JsonValue] = dict(details or {})
+        #: What the caller could do about this, in the CLI's own vocabulary.
+        #: Raising code fills this in when it knows; the CLI never invents it.
+        self.next_actions: list[NextAction] = list(next_actions or ())
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class UsageError(TechtreeError):
+    """The command, its options, or their combination is not valid."""
+
+    default_code: ClassVar[str] = "usage_error"
+    default_exit_code: ClassVar[int] = EXIT_USAGE
+
+
+class ValidationError(TechtreeError):
+    """Input data or a stored document failed protocol validation."""
+
+    default_code: ClassVar[str] = "validation_error"
+    default_exit_code: ClassVar[int] = EXIT_VALIDATION
+
+
+class PrerequisiteError(TechtreeError):
+    """Something that had to be done first has not been done."""
+
+    default_code: ClassVar[str] = "prerequisite_error"
+    default_exit_code: ClassVar[int] = EXIT_PREREQUISITE
+
+
+class NotFoundError(TechtreeError):
+    """A named object does not exist."""
+
+    default_code: ClassVar[str] = "not_found"
+    default_exit_code: ClassVar[int] = EXIT_NOT_FOUND
+
+
+class ConflictError(TechtreeError):
+    """The requested change collides with existing immutable state."""
+
+    default_code: ClassVar[str] = "conflict"
+    default_exit_code: ClassVar[int] = EXIT_CONFLICT
+
+
+class AuthenticationError(TechtreeError):
+    """A credential is missing, rejected, or expired."""
+
+    default_code: ClassVar[str] = "authentication_error"
+    default_exit_code: ClassVar[int] = EXIT_AUTHENTICATION
+
+
+class EngineError(TechtreeError):
+    """The managed engine could not be installed, resolved, or invoked."""
+
+    default_code: ClassVar[str] = "engine_error"
+    default_exit_code: ClassVar[int] = EXIT_ENGINE
+
+
+class RunError(TechtreeError):
+    """A run failed, or a run operation is illegal in the current phase."""
+
+    default_code: ClassVar[str] = "run_error"
+    default_exit_code: ClassVar[int] = EXIT_RUN
+
+
+class VerificationError(TechtreeError):
+    """A digest, signature, or membership commitment did not verify."""
+
+    default_code: ClassVar[str] = "verification_error"
+    default_exit_code: ClassVar[int] = EXIT_VERIFICATION
+
+
+class CancellationError(TechtreeError):
+    """Work stopped because it was cancelled."""
+
+    default_code: ClassVar[str] = "cancelled"
+    default_exit_code: ClassVar[int] = EXIT_CANCELLED
+
+
+class PolicyError(TechtreeError):
+    """A data-rights or publication policy forbids the request.
+
+    Data-policy contradictions raise this and nothing else, so a caller can
+    distinguish "your inputs disagree about rights" from "your inputs are
+    malformed".
+    """
+
+    default_code: ClassVar[str] = "policy_error"
+    default_exit_code: ClassVar[int] = EXIT_POLICY
+
+
+# ---------------------------------------------------------------------------
+# Message stability
+# ---------------------------------------------------------------------------
+
+#: A memory address as CPython writes one into a repr. It changes on every
+#: process, so an error quoting one would not compare equal to itself between
+#: runs. Normalising it is about stability, not about secrecy: decision 0036
+#: is explicit that this project detects no secret-shaped strings anywhere.
+_MEMORY_ADDRESS = re.compile(r"\b0x[0-9a-fA-F]{6,}\b")
+_WHITESPACE_RUN = re.compile(r"\s+")
+
+
+def stable_exception_message(error: Exception) -> str:
+    """Return one exception's message as a single stable line.
+
+    Line structure is flattened so a message reads as one line wherever it is
+    shown, and memory addresses are normalised so the same failure produces
+    the same words twice. Nothing else is altered: whatever the exception
+    said, including anything a subprocess said through it, is what comes out.
+    """
+    text = _WHITESPACE_RUN.sub(" ", str(error)).strip()
+    if not text:
+        return type(error).__name__
+    return _MEMORY_ADDRESS.sub("0x<address>", text)
+
+
+# ---------------------------------------------------------------------------
+# CLI projection
+# ---------------------------------------------------------------------------
+
+
+def error_to_cli_error(error: TechtreeError) -> CliError:
+    """Convert an internal typed error to CLI error data.
+
+    The message is flattened by :func:`stable_exception_message`; ``details``
+    travels exactly as the raising call site built it.
+
+    ``next_actions`` is not part of ``CliError``; it belongs to the envelope,
+    and the CLI reads it from the error directly.
+    """
+    from techtree.models.cli import CliError
+
+    return CliError(
+        code=error.code,
+        message=stable_exception_message(error),
+        retryable=error.retryable,
+        details=dict(error.details),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Exit codes
+# ---------------------------------------------------------------------------
+
+
+def exit_code_for(error: Exception) -> int:
+    """Return documented CLI exit code.
+
+    Anything that is not a typed Techtree error is an internal defect, and
+    every internal defect exits ``1``.
+    """
+    if isinstance(error, TechtreeError):
+        return error.exit_code
+    return EXIT_ERROR