@ahmed-g-gad/apothem 0.1.1

package/src/apothem/lib/propagation.py

@@ -0,0 +1,220 @@
+# SPDX-License-Identifier: MIT
+
+"""Propagation-manifest loader for harness adapters.
+
+The manifest at ``src/apothem/lib/propagation-manifest.yaml`` declares
+per-harness install rules — ordered ``(source, target, mode)`` tuples,
+exclude globs, stale-sweep entries, and per-directory filename filters.
+This module loads the manifest and exposes typed accessors so adapter
+modules consume the manifest declaratively instead of hardcoding the
+rules as Python constants.
+
+Status: manifest-driven. The canonical claude-code adapter at
+``src/apothem/harnesses/claude_code/install.py`` consumes its
+propagation rules from this loader via ``load_manifest`` — the manifest
+IS the contract; the adapter holds no hardcoded install-layout
+constants. The regression test at
+``tests/unit/test_propagation_manifest.py`` verifies the manifest and
+the adapter agree on the install layout.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from functools import lru_cache
+from importlib.resources import as_file, files
+from pathlib import Path
+from string import Template
+from typing import Final
+
+import yaml
+
+# The five preserve-first ownership classes. Class assignment is by
+# authorship origin and durability — who authored the bytes at the target
+# path, and what the propagation driver may do to them:
+#
+# - apothem-owned   — bytes Apothem authors and exclusively manages.
+# - operator-owned  — bytes the operator owns; Apothem merges, never
+#                     silently overwrites (backup + diff + authorization).
+# - vendor-reserved — bytes the harness vendor manages; never a write target.
+# - generated       — Apothem's reproducible derived output; regenerate freely.
+# - immutable       — append-only records; in-place rewrite is refused.
+OWNERSHIP_CLASSES: Final[frozenset[str]] = frozenset(
+    {
+        "apothem-owned",
+        "operator-owned",
+        "vendor-reserved",
+        "generated",
+        "immutable",
+    }
+)
+
+_DEFAULT_OWNERSHIP_CLASS: Final[str] = "apothem-owned"
+
+
+@dataclass(frozen=True)
+class InstallEntry:
+    """One propagation operation declared in the manifest."""
+
+    source: str
+    target: str
+    mode: str  # write_text, tree mode, or harness-specific conversion mode
+    ownership_class: str = _DEFAULT_OWNERSHIP_CLASS
+
+
+@dataclass(frozen=True)
+class HarnessRules:
+    """Per-harness propagation rules loaded from the manifest."""
+
+    install: list[InstallEntry]
+    exclude: list[str]
+    stale_sweep: list[str]
+    per_directory_filters: dict[str, list[str]] = field(default_factory=dict)
+
+
+_MANIFEST_FILENAME: Final[str] = "propagation-manifest.yaml"
+
+
+def _manifest_path() -> Path:
+    """Return the on-disk path to the propagation manifest.
+
+    Resolves via ``importlib.resources`` so the manifest is locatable
+    regardless of where the apothem package is installed (editable
+    development tree, pip-installed wheel, or zipfile distribution).
+    """
+    traversable = files("apothem.lib") / _MANIFEST_FILENAME
+    with as_file(traversable) as concrete:
+        return Path(concrete)
+
+
+def load_manifest() -> dict[str, HarnessRules]:
+    """Load the propagation manifest and return per-harness rules.
+
+    The parse is memoized per process and keyed by the manifest's path and
+    modification time, so a batch command (install-all / update-all) that
+    resolves rules once per harness parses the 27 KB manifest only once. A
+    manifest edited in place (different mtime) invalidates the cache on the
+    next call.
+
+    Returns:
+        Mapping from harness name (e.g. ``"claude_code"``) to its
+        ``HarnessRules`` record. Harnesses absent from the manifest are
+        omitted from the returned mapping.
+
+    Raises:
+        FileNotFoundError: When the manifest file is missing from the
+            package resources.
+        ValueError: When the manifest is malformed (missing top-level
+            ``harnesses`` key, unparseable YAML, or per-harness entries
+            failing the schema).
+    """
+    path = _manifest_path()
+    if not path.is_file():
+        raise FileNotFoundError(f"propagation manifest not found at {path}")
+    return _load_manifest_cached(str(path), path.stat().st_mtime_ns)
+
+
+@lru_cache(maxsize=1)
+def _load_manifest_cached(path_str: str, mtime_ns: int) -> dict[str, HarnessRules]:
+    """Read and parse the manifest at ``path_str``; memoized by (path, mtime).
+
+    Reading and YAML-parsing happen here so the bytes are read exactly once
+    per (path, mtime). ``lru_cache`` does not memoize exceptions, so a
+    malformed manifest re-parses (and re-raises ``ValueError``) on every call.
+    """
+    text = Path(path_str).read_text(encoding="utf-8")
+    return _parse_manifest_text(text)
+
+
+def _parse_manifest_text(text: str) -> dict[str, HarnessRules]:
+    """Parse the manifest YAML text into per-harness rules (schema-validated)."""
+    raw = yaml.safe_load(text)
+    if not isinstance(raw, dict) or "harnesses" not in raw:
+        raise ValueError(
+            "propagation manifest is missing the top-level 'harnesses' key"
+        )
+    harnesses_raw = raw["harnesses"] or {}
+    if not isinstance(harnesses_raw, dict):
+        raise ValueError("'harnesses' must be a mapping of harness-name to rules")
+
+    rules: dict[str, HarnessRules] = {}
+    for name, body in harnesses_raw.items():
+        if body is None:
+            continue
+        if not isinstance(body, dict):
+            raise ValueError(f"harness '{name}' entry must be a mapping")
+        install_raw = body.get("install") or []
+        install: list[InstallEntry] = []
+        for entry in install_raw:
+            if not isinstance(entry, dict):
+                raise ValueError(f"harness '{name}' install entry must be a mapping")
+            ownership_class = str(
+                entry.get("ownership_class", _DEFAULT_OWNERSHIP_CLASS)
+            )
+            if ownership_class not in OWNERSHIP_CLASSES:
+                raise ValueError(
+                    f"harness '{name}' install entry declares unknown "
+                    f"ownership_class '{ownership_class}'"
+                )
+            install.append(
+                InstallEntry(
+                    source=str(entry["source"]),
+                    target=str(entry["target"]),
+                    mode=str(entry.get("mode", "replace_tree")),
+                    ownership_class=ownership_class,
+                )
+            )
+        rules[name] = HarnessRules(
+            install=install,
+            exclude=list(body.get("exclude") or []),
+            stale_sweep=list(body.get("stale-sweep") or []),
+            per_directory_filters={
+                k: list(v or [])
+                for k, v in (body.get("per-directory-filters") or {}).items()
+            },
+        )
+    return rules
+
+
+def resolve_target(
+    template: str,
+    *,
+    harness_root: Path | None = None,
+    project_root: Path | None = None,
+) -> Path:
+    """Substitute ``${HARNESS_ROOT}`` and ``${PROJECT_ROOT}`` into a path.
+
+    Shared substitution helper consumed by every adapter that resolves
+    manifest target paths into concrete filesystem locations. Supports
+    two placeholders:
+
+    - ``${HARNESS_ROOT}`` — the harness's user-scope configuration root
+      (e.g., ``~/.claude`` for the Claude Code harness, ``~/.gemini`` for
+      antigravity / gemini_cli).
+    - ``${PROJECT_ROOT}`` — the operator-supplied project root, required
+      by project-scope harnesses (e.g., ``<project>/.cursor/rules/`` for
+      the cursor harness; analogous targets for github_copilot and
+      gemini_cli project-scope entries).
+
+    Either placeholder may be absent from the template — substitution is
+    a no-op for the absent placeholder. When a template references a
+    placeholder whose corresponding root argument is ``None``, the
+    substitution leaves the literal placeholder in place; the caller is
+    responsible for surfacing the missing-root condition as an operator
+    inquiry before the resulting path is written to.
+    """
+    mapping: dict[str, str] = {}
+    if harness_root is not None:
+        mapping["HARNESS_ROOT"] = str(harness_root)
+    if project_root is not None:
+        mapping["PROJECT_ROOT"] = str(project_root)
+    return Path(Template(template).safe_substitute(mapping))
+
+
+__all__ = [
+    "OWNERSHIP_CLASSES",
+    "HarnessRules",
+    "InstallEntry",
+    "load_manifest",
+    "resolve_target",
+]

package/src/apothem/lib/python_resolver.py

@@ -0,0 +1,189 @@
+# SPDX-License-Identifier: MIT
+
+"""Resolve a real CPython interpreter for install-time hook-command wiring.
+
+The Claude Code ``settings.json`` hook entries must invoke a concrete
+interpreter, never a bare ``python`` name that a host's ``PATH`` can resolve to
+a Microsoft Store ``WindowsApps`` launcher stub (a zero-content shim that opens
+the Store instead of running the script). This module supplies the absolute
+interpreter path that the adapter substitutes for the template's
+``${PYTHON_BIN}`` placeholder at install time.
+
+Resolution order:
+
+1. ``sys.executable`` — the interpreter running the install. apothem declares
+   ``requires-python = ">=3.10"``, so a WindowsApps stub (which cannot import or
+   run apothem at all) can never be the running interpreter; ``sys.executable``
+   is therefore guaranteed a real CPython that satisfies the floor whenever it
+   is populated and points at a real file.
+2. A ``PATH`` walk mirroring ``hooks/lib/find-python.sh`` — every candidate name
+   probed in ``PATH`` order, ``WindowsApps`` shims and sub-1024-byte stubs
+   rejected, each survivor version-probed against the floor. This is the
+   fallback for the (rare) embedded / frozen case where ``sys.executable`` is
+   unusable.
+
+The PATH-walk fallback is the Python sibling of the shipped shell locators
+(``find-python.sh`` / ``find-python.ps1``); it does not replace them — the
+bootstrap stubs still consume the shell locators on the no-substitution path.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Final
+
+# Minimum interpreter the hooks require, mirroring ``requires-python`` in
+# ``pyproject.toml`` and the floor in ``hooks/lib/find-python.sh``.
+MIN_MAJOR: Final[int] = 3
+MIN_MINOR: Final[int] = 10
+
+# Candidate executable names probed in ``PATH``, most-specific last so the
+# bare names win when they already satisfy the floor (mirrors find-python.sh).
+_CANDIDATE_NAMES: Final[tuple[str, ...]] = (
+    "python",
+    "python3",
+    "python3.14",
+    "python3.13",
+    "python3.12",
+    "python3.11",
+    "python3.10",
+)
+
+# Minimum byte size for a real interpreter; WindowsApps launcher shims are
+# near-empty reparse stubs well under this floor (mirrors find-python.sh).
+_MIN_INTERPRETER_BYTES: Final[int] = 1024
+
+# Probe program: print ``"<major> <minor>"`` for the running interpreter.
+_VERSION_PROBE: Final[str] = (
+    "import sys; "
+    "sys.stdout.write(str(sys.version_info.major) + chr(32) "
+    "+ str(sys.version_info.minor))"
+)
+
+
+def _is_windowsapps_stub(path: Path) -> bool:
+    """Return True when *path* is a Microsoft Store launcher shim.
+
+    Store shims live under ``...\\Microsoft\\WindowsApps\\`` and are near-empty
+    reparse stubs; either signal alone is conclusive, so both are rejected.
+    """
+    if "WindowsApps" in path.parts:
+        return True
+    try:
+        return path.stat().st_size < _MIN_INTERPRETER_BYTES
+    except OSError:
+        return True
+
+
+def _probe_version(executable: Path) -> tuple[int, int] | None:
+    """Return ``(major, minor)`` for *executable*, or None when unprobeable.
+
+    Runs the candidate with a literal probe program (no shell, no untrusted
+    input). Any failure — non-zero exit, unparseable output, OSError — yields
+    None so the caller skips the candidate rather than aborting the walk.
+    """
+    try:
+        completed = subprocess.run(  # noqa: S603 — literal argv, trusted probe program, no shell
+            [str(executable), "-c", _VERSION_PROBE],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if completed.returncode != 0:
+        return None
+    parts = completed.stdout.strip().split()
+    if len(parts) < 2:
+        return None
+    try:
+        return int(parts[0]), int(parts[1])
+    except ValueError:
+        return None
+
+
+def _satisfies_floor(major: int, minor: int) -> bool:
+    """Return True when ``(major, minor)`` meets the ``>= 3.10`` floor."""
+    return major > MIN_MAJOR or (major == MIN_MAJOR and minor >= MIN_MINOR)
+
+
+def _path_candidates(name: str) -> list[Path]:
+    """Return every executable named *name* found across ``PATH``, in order.
+
+    The Python stand-in for ``find-python.sh``'s PATH walk: it lists *all*
+    matches rather than only the first, so a WindowsApps shim early on ``PATH``
+    does not mask a real interpreter found later. Empty ``PATH`` segments are
+    skipped, not resolved to the current directory — a cwd-resident interpreter
+    must never be discovered, version-probed (executed), and wired into the
+    hook command (defense-in-depth, mirroring ``find-python.sh``).
+    """
+    found: list[Path] = []
+    raw_path = os.environ.get("PATH", "")
+    suffixes = [""]
+    if os.name == "nt":
+        pathext = os.environ.get("PATHEXT", ".EXE")
+        suffixes = [""] + [ext.lower() for ext in pathext.split(os.pathsep) if ext]
+    for directory in raw_path.split(os.pathsep):
+        # Skip an empty PATH segment (a doubled separator, or a leading /
+        # trailing one) rather than mapping it to cwd. POSIX resolves an empty
+        # segment to the current directory, but this resolver's result is
+        # version-probed (executed) and substituted for ``${PYTHON_BIN}`` in the
+        # hook command that runs on every tool use; trusting a cwd interpreter
+        # there is the footgun this guard closes. An explicit "." entry is
+        # non-empty and still honored below.
+        if not directory:
+            continue
+        for suffix in suffixes:
+            candidate = Path(directory) / (name + suffix)
+            if candidate.is_file() and os.access(candidate, os.X_OK):
+                found.append(candidate)
+    return found
+
+
+def _resolve_from_path() -> Path | None:
+    """Walk ``PATH`` for a real CPython satisfying the floor, or None.
+
+    Mirrors ``find-python.sh``: probe each candidate name in priority order,
+    reject WindowsApps shims and sub-1024-byte stubs, and return the first
+    interpreter whose probed version meets the floor.
+    """
+    for name in _CANDIDATE_NAMES:
+        for candidate in _path_candidates(name):
+            if _is_windowsapps_stub(candidate):
+                continue
+            version = _probe_version(candidate)
+            if version is None:
+                continue
+            if _satisfies_floor(*version):
+                return candidate.resolve()
+    return None
+
+
+def resolve_python_bin() -> Path:
+    """Return the absolute path to a real CPython >= 3.10 for hook wiring.
+
+    Prefers ``sys.executable`` (guaranteed a real, floor-satisfying interpreter
+    whenever it is populated and points at a real file, because apothem cannot
+    run under a WindowsApps stub). Falls back to a ``PATH`` walk that rejects
+    Store shims. Raises :class:`RuntimeError` when no real interpreter can be
+    found — the adapter surfaces that as an install-time failure rather than
+    wiring a bare ``python`` that could resolve to a stub at hook-run time.
+    """
+    running = sys.executable
+    if running:
+        running_path = Path(running)
+        if running_path.is_file() and not _is_windowsapps_stub(running_path):
+            return running_path.resolve()
+
+    resolved = _resolve_from_path()
+    if resolved is not None:
+        return resolved
+
+    raise RuntimeError(
+        "no real CPython >= 3.10 interpreter found for hook wiring; "
+        "sys.executable is unusable and no PATH candidate satisfies the floor"
+    )

package/src/apothem/lib/reporter.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: MIT
+
+"""Structured pass/fail/warn reporting for validation tools."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from typing import Final, TextIO
+
+_PASS: Final[str] = "[PASS]"
+_FAIL: Final[str] = "[FAIL]"
+_WARN: Final[str] = "[WARN]"
+_INFO: Final[str] = "[INFO]"
+
+
+@dataclass
+class Reporter:
+    """Accumulates validation outcomes with running counts."""
+
+    stream: TextIO = field(default_factory=lambda: sys.stdout)
+    passed: int = 0
+    failed: int = 0
+    warned: int = 0
+    errors: list[str] = field(default_factory=list)
+
+    def ok(self, message: str) -> None:
+        """Write a ``[PASS]`` line and increment the passed count."""
+        self.stream.write(f"{_PASS} {message}\n")
+        self.passed += 1
+
+    def fail(self, message: str) -> None:
+        """Write a ``[FAIL]`` line, increment the failed count, and record
+        the message in :attr:`errors`."""
+        self.stream.write(f"{_FAIL} {message}\n")
+        self.failed += 1
+        self.errors.append(message)
+
+    def warn(self, message: str) -> None:
+        """Write a ``[WARN]`` line and increment the warned count."""
+        self.stream.write(f"{_WARN} {message}\n")
+        self.warned += 1
+
+    def info(self, message: str) -> None:
+        """Write an ``[INFO]`` line; carries no pass/fail/warn weight."""
+        self.stream.write(f"{_INFO} {message}\n")
+
+    def section(self, title: str) -> None:
+        """Write a section header to group the subsequent lines."""
+        self.stream.write(f"\n=== {title} ===\n")
+
+    def summary(self) -> None:
+        """Write the final summary block with the passed/failed/warned counts."""
+        self.stream.write("\n=== Summary ===\n")
+        self.stream.write(f"{_INFO} Passed: {self.passed}\n")
+        self.stream.write(f"{_INFO} Failed: {self.failed}\n")
+        self.stream.write(f"{_INFO} Warnings: {self.warned}\n")
+
+    @property
+    def exit_code(self) -> int:
+        """Process exit code: ``0`` when no check failed, else ``1``."""
+        return 0 if self.failed == 0 else 1