agentbundle 0.2.0__py3-none-any.whl

agentbundle/build/adapter_root_bins.py

@@ -0,0 +1,336 @@
+"""T6: adapter-root-bins/ build-pipeline primitive class.
+
+Source rule: ``packs/<pack>/.apm/adapter-root-bins/*.py``.
+Target rule (self-host, repo scope): project each
+``adapter-root-bins/*.py`` file byte-identically to
+``<working_tree>/.agentbundle/bin/<basename>.py`` with POSIX mode
+``0o755`` (Windows inherits the parent DACL — no explicit chmod).
+At user-scope install time the install command projects the same
+files to ``$HOME/.agentbundle/bin/<basename>.py``; that surface is
+the install command's responsibility, not this module's.
+
+This module owns both halves of the build-pipeline contract for the
+new primitive class:
+
+- ``apply_projection(working_tree, packs_dir)`` — write the files.
+  Called by ``make build-self``.
+- ``check_drift(working_tree, packs_dir)`` — read-only gate. Returns
+  a list of drift descriptions (empty list == clean). Three outcomes
+  per RFC-0013 § 4d / spec AC22-AC23:
+    * **modified** — projected file exists but bytes diverge from source
+    * **missing** — source exists but projected file absent
+    * **orphaned** — projected file present but source has been removed
+
+Inter-pack basename collision is a hard error at ``collect_sources``
+time. v1 ships exactly one source (``sso-broker.py`` in
+``credential-brokers``); the rail guards against a future collision.
+
+Path-jail compliance: the target (``.agentbundle/``) is fenced by the
+v0.7 contract's ``allowed-prefixes.repo`` for the three user-scope
+adapters (``claude-code``, ``kiro``, ``codex``). The projection writes
+under that prefix and never anywhere else; no PATH manipulation, no
+shell-config edits.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import shared_libs
+
+# Pin the source path so a downstream consumer that wants to enumerate
+# sources doesn't hardcode the literal repeatedly.
+SOURCE_SUBDIR = ".apm/adapter-root-bins"
+
+# Target subtree under the per-scope artifact root. Mirrors the
+# `~/.agentbundle/bin/` path at user scope (install-time surface).
+TARGET_SUBDIR = Path(".agentbundle") / "bin"
+
+# POSIX mode bits applied after copy. AC22 pins 0o755; Windows
+# inherits the DACL from %USERPROFILE% (no explicit chmod call).
+EXECUTABLE_MODE = 0o755
+
+# AC22b: shim-companion projection. When a pack ships both
+# adapter-root-bins/ and shared-libs/credentials_shim.py, the shim is
+# projected as a sibling under `bin/` so that per-platform Tier-2
+# backend modules under adapter-root-bins/ (e.g. _sso_keychain_macos.py)
+# can resolve `from .credentials_shim import Tier2HardFailError`.
+SHIM_COMPANION_BASENAME = "credentials_shim.py"
+
+# AC22b content-grep trigger. Any *.py under adapter-root-bins/ whose
+# bytes contain this literal substring is considered shim-dependent;
+# the pack must then ship .apm/shared-libs/credentials_shim.py or the
+# build hard-errors. Literal-substring match has a documented
+# false-positive surface (a docstring quoting the line); accepted for
+# v1 because the failure mode is benign (the shim is projected
+# unnecessarily — no functional or security regression). AST-walk is
+# the documented tightening path.
+SHIM_IMPORT_GREP = b"from .credentials_shim import"
+
+
+@dataclass(frozen=True)
+class AdapterRootBinProjection:
+    """One concrete projection: copy ``source`` to ``target``."""
+
+    source: Path
+    target: Path
+
+
+def collect_sources(packs_dir: Path) -> dict[str, Path]:
+    """Return ``{basename → source_path}`` for every
+    ``.apm/adapter-root-bins/*.py`` file across every pack.
+
+    Raises ``ValueError`` on inter-pack basename collision — two
+    packs shipping the same basename produces non-deterministic
+    projection order and silent overwrites; refuse hard at
+    enumeration time.
+    """
+    sources: dict[str, Path] = {}
+    for pack in sorted(packs_dir.iterdir()):
+        if not pack.is_dir() or not (pack / "pack.toml").exists():
+            continue
+        bins = pack / SOURCE_SUBDIR
+        if not bins.is_dir():
+            continue
+        for src in sorted(bins.glob("*.py")):
+            if src.name in sources:
+                raise ValueError(
+                    f"adapter-root-bins collision: '{src.name}' shipped by both "
+                    f"{sources[src.name]} and {src}"
+                )
+            sources[src.name] = src
+    return sources
+
+
+def _packs_with_adapter_root_bins(packs_dir: Path) -> list[Path]:
+    """Return every pack directory whose ``.apm/adapter-root-bins/``
+    contains at least one ``*.py`` source. Sorted for determinism.
+
+    Used by the AC22b shim-companion enumeration and by the
+    content-grep hard-error rail — both predicate on "the pack ships
+    adapter-root-bins/", not on what's inside it.
+    """
+    out: list[Path] = []
+    for pack in sorted(packs_dir.iterdir()):
+        if not pack.is_dir() or not (pack / "pack.toml").exists():
+            continue
+        bins = pack / SOURCE_SUBDIR
+        if not bins.is_dir():
+            continue
+        if any(bins.glob("*.py")):
+            out.append(pack)
+    return out
+
+
+def _assert_shim_companion_present(packs_dir: Path) -> None:
+    """AC22b hard-error rail (content-based, generalises past _sso_*).
+
+    For each pack that ships any ``.apm/adapter-root-bins/*.py``,
+    content-grep its sources for the literal substring
+    ``from .credentials_shim import``; if any match AND the pack does
+    not ship ``.apm/shared-libs/credentials_shim.py``, raise
+    ``ValueError`` with the broker-agnostic pinned message. Generalises
+    so a future ``_oauth_macos.py`` or any other adapter-root-bins
+    module with the same dependency is auto-covered.
+    """
+    for pack in _packs_with_adapter_root_bins(packs_dir):
+        shim_source = pack / shared_libs.SOURCE_SUBDIR / SHIM_COMPANION_BASENAME
+        if shim_source.is_file():
+            continue  # pack ships the companion — no need to grep.
+        bins_dir = pack / SOURCE_SUBDIR
+        offenders: list[str] = []
+        for src in sorted(bins_dir.glob("*.py")):
+            try:
+                body = src.read_bytes()
+            except OSError:
+                continue
+            if SHIM_IMPORT_GREP in body:
+                offenders.append(src.name)
+        if offenders:
+            offender_list = ", ".join(offenders)
+            raise ValueError(
+                f"adapter-root-bins/{{{offender_list}}} imports "
+                f".credentials_shim but .apm/shared-libs/credentials_shim.py "
+                f"is missing in pack {pack.name!r} — the importing module's "
+                f"Tier-2 dispatch would degrade silently on macOS/Windows"
+            )
+
+
+def collect_companion_shim(packs_dir: Path) -> dict[str, Path]:
+    """AC22b companion projection enumeration.
+
+    Returns ``{basename → source_path}`` for the shim companion when
+    at least one pack ships BOTH ``.apm/adapter-root-bins/`` AND
+    ``.apm/shared-libs/credentials_shim.py``. Cross-pack basename
+    collision on the shim is detected by ``shared_libs.collect_sources``
+    (single source of truth — one error shape, one ownership boundary).
+    The companion's target is always
+    ``<working_tree>/.agentbundle/bin/credentials_shim.py``; callers
+    compose ``working_tree`` themselves.
+    """
+    shim_sources = shared_libs.collect_sources(packs_dir)
+    shim_source = shim_sources.get(SHIM_COMPANION_BASENAME)
+    if shim_source is None:
+        return {}
+    for pack in _packs_with_adapter_root_bins(packs_dir):
+        pack_shim = pack / shared_libs.SOURCE_SUBDIR / SHIM_COMPANION_BASENAME
+        if pack_shim.is_file():
+            # At least one pack ships both adapter-root-bins/ and
+            # shared-libs/credentials_shim.py. Project the canonical
+            # shim source as the companion. Opt-in by ship-both: packs
+            # that ship adapter-root-bins/ alone do not get the shim
+            # — the AC22b hard-error rail catches the case where they
+            # *need* it but don't ship it.
+            return {SHIM_COMPANION_BASENAME: shim_source}
+    return {}
+
+
+def compute_projections(
+    working_tree: Path, packs_dir: Path
+) -> list[AdapterRootBinProjection]:
+    """Return the full list of ``(source → target)`` pairs.
+
+    Deterministic order — drift gates depend on it. Includes the AC22b
+    shim companion when applicable (opt-in by ship-both).
+    """
+    sources = collect_sources(packs_dir)
+    target_dir = working_tree / TARGET_SUBDIR
+    projections: list[AdapterRootBinProjection] = [
+        AdapterRootBinProjection(source=sources[name], target=target_dir / name)
+        for name in sorted(sources)
+    ]
+    companion = collect_companion_shim(packs_dir)
+    for basename in sorted(companion):
+        projections.append(
+            AdapterRootBinProjection(
+                source=companion[basename],
+                target=target_dir / basename,
+            )
+        )
+    return projections
+
+
+def _is_companion_projection(proj: AdapterRootBinProjection) -> bool:
+    """True iff ``proj`` is the AC22b shim-companion (source rooted in
+    ``shared-libs/``), not a primary adapter-root-bins target.
+
+    Drives the ``[adapter-root-bins:shim-companion]`` diagnostic
+    prefix in ``check_drift`` so the source-side reference reads
+    coherently next to its diagnostic class. Derives the comparison
+    leaf-name from ``shared_libs.SOURCE_SUBDIR`` so a future rename of
+    that constant propagates here automatically.
+    """
+    shared_libs_leaf = Path(shared_libs.SOURCE_SUBDIR).name
+    return proj.source.parent.name == shared_libs_leaf
+
+
+def apply_projection(working_tree: Path, packs_dir: Path) -> None:
+    """Write every projection target and remove orphans.
+
+    Called by ``make build-self``. Idempotent — running twice produces
+    the same on-disk state. POSIX mode bits set to ``0o755`` after
+    copy. Windows inherits the parent DACL (no explicit chmod).
+
+    Three drift outcomes resolved here:
+      * **missing** → file written from source
+      * **modified** → file overwritten from source
+      * **orphaned** → file removed (source basename no longer
+        shipped by any pack)
+
+    AC22b: also projects the shim companion when a pack ships both
+    ``.apm/adapter-root-bins/`` and ``.apm/shared-libs/credentials_shim.py``.
+    AC22b hard-error rail fires before any writes if a pack imports
+    the shim but doesn't ship the source.
+    """
+    _assert_shim_companion_present(packs_dir)
+    projections = compute_projections(working_tree, packs_dir)
+    expected_targets = {p.target for p in projections}
+    for proj in projections:
+        proj.target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(proj.source, proj.target)
+        if os.name == "posix":
+            os.chmod(proj.target, EXECUTABLE_MODE)
+    # Orphan removal: any *.py file under <working_tree>/.agentbundle/bin/
+    # not claimed by an expected target.
+    target_dir = working_tree / TARGET_SUBDIR
+    if target_dir.is_dir():
+        for existing in sorted(target_dir.glob("*.py")):
+            if existing not in expected_targets:
+                try:
+                    existing.unlink()
+                except FileNotFoundError:  # pragma: no cover — race-only
+                    pass
+
+
+def check_drift(working_tree: Path, packs_dir: Path) -> list[str]:
+    """Return drift descriptions for ``make build-check``.
+
+    Three outcomes per RFC-0013 § 4d / spec AC22-AC23:
+        * **modified** — projected bytes diverge from source
+        * **missing** — source exists but projected file absent
+        * **orphaned** — projected file present, no source claiming it
+
+    Each description ends with the regeneration command.
+    """
+    drifts: list[str] = []
+    try:
+        sources = collect_sources(packs_dir)
+    except ValueError as exc:
+        drifts.append(f"[adapter-root-bins] {exc}; run: make build-self")
+        return drifts
+    try:
+        _assert_shim_companion_present(packs_dir)
+    except ValueError as exc:
+        drifts.append(f"[adapter-root-bins:shim-companion] {exc}; run: make build-self")
+        return drifts
+
+    target_dir = working_tree / TARGET_SUBDIR
+    expected_targets: set[Path] = set()
+
+    for proj in compute_projections(working_tree, packs_dir):
+        expected_targets.add(proj.target)
+        prefix = (
+            "[adapter-root-bins:shim-companion]"
+            if _is_companion_projection(proj)
+            else "[adapter-root-bins]"
+        )
+        try:
+            source_bytes = proj.source.read_bytes()
+        except OSError as exc:  # pragma: no cover — defensive
+            drifts.append(f"{prefix} source unreadable: {exc}")
+            continue
+        if not proj.target.exists():
+            drifts.append(
+                f"{prefix} missing: "
+                f"{proj.target.relative_to(working_tree).as_posix()} "
+                f"(source: "
+                f"{proj.source.relative_to(packs_dir.parent).as_posix()}); "
+                f"run: make build-self FORCE=1"
+            )
+            continue
+        if proj.target.read_bytes() != source_bytes:
+            drifts.append(
+                f"{prefix} modified: "
+                f"{proj.target.relative_to(working_tree).as_posix()} "
+                f"diverges from "
+                f"{proj.source.relative_to(packs_dir.parent).as_posix()}; "
+                f"run: make build-self FORCE=1"
+            )
+
+    # Orphan check.
+    if target_dir.is_dir():
+        for existing in sorted(target_dir.glob("*.py")):
+            if existing not in expected_targets:
+                drifts.append(
+                    f"[adapter-root-bins] orphaned: "
+                    f"{existing.relative_to(working_tree).as_posix()} "
+                    f"present but no pack ships "
+                    f"adapter-root-bins/{existing.name}; "
+                    f"run: make build-self FORCE=1"
+                )
+
+    return drifts

agentbundle/build/adapters/__init__.py

@@ -0,0 +1,46 @@
+"""Adapter registry — keyed by contract adapter name."""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from types import ModuleType
+from typing import Callable, Dict, Mapping
+
+from agentbundle.build.adapters import claude_code, codex, copilot, kiro, kiro_cli, kiro_ide
+
+
+def _kiro_alias_project(pack_path: Path, contract: dict, output_root: Path) -> None:
+    """Deprecated alias: `kiro` → `kiro-ide`. Emits a build-time warning."""
+    warnings.warn(
+        "kiro: deprecated alias for kiro-ide; update allowed-adapters in pack.toml",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    kiro_ide.project(pack_path, contract, output_root)
+
+
+# Original callable registry (hyphenated contract names) — preserved for
+# F-build's recipe runner which keys recipes by contract names.
+ADAPTERS: Dict[str, Callable] = {
+    "claude-code": claude_code.project,
+    "kiro-ide": kiro_ide.project,
+    "kiro-cli": kiro_cli.project,
+    "kiro": _kiro_alias_project,  # deprecated alias → kiro-ide (RFC-0022 D1)
+    "copilot": copilot.project,
+    "codex": codex.project,
+}
+
+# Module-keyed registry — the surface RFC-0003 F-cli AC requires.
+# Keys are the Python module names (`claude_code`, etc.) which is what the
+# CLI's `list-targets` and the AC's test reference. Values are the adapter
+# modules themselves so callers can introspect any future per-adapter
+# attribute the sibling spec pins onto `AdapterModule`.
+registry: Mapping[str, ModuleType] = {
+    "claude_code": claude_code,
+    "kiro_ide": kiro_ide,
+    "kiro_cli": kiro_cli,
+    "kiro": kiro,  # legacy module; use kiro_ide for new code
+    "copilot": copilot,
+    "codex": codex,
+}

agentbundle/build/adapters/claude_code.py

@@ -0,0 +1,142 @@
+"""Claude Code adapter — projects every primitive per the contract.
+
+Projection modes used (read from contract["adapter"]["claude-code"]):
+  - skill       → direct-directory → .claude/skills/<name>/
+  - agent       → direct-file       → .claude/agents/<name>.md
+  - hook-body   → direct-file       → tools/hooks/<name>.{sh,py}
+  - hook-wiring → merge-json        → .claude/settings.local.json (hooks key)
+  - command     → direct-file       → .claude/commands/<name>.md
+
+The merge-json projection is idempotent because we re-serialise with
+`sort_keys=True` and re-read the existing file's `hooks` key before
+deep-merging the incoming TOML payload.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Iterator
+
+
+# Phase order from RFC-0005 § Build-pipeline ordering invariant.
+# Uniform across all reference adapters even though Claude Code's
+# wiring lands in a settings file (not in agents) — the uniformity
+# keeps the phases predictable, which the spec calls for.
+from agentbundle.build.phase_order import PHASE_ORDER as _PHASE_ORDER
+from agentbundle.build.projections.direct_directory import sweep_orphans
+from agentbundle.build.projections.merge_json import project_merge_json
+
+
+def _iter_primitives(contract: dict) -> Iterator[str]:
+    """Yield Claude Code's projected primitive names in phase order."""
+    adapter_block = contract["adapter"]["claude-code"]
+    array_form = {entry["primitive"]: entry for entry in adapter_block.get("projection", [])}
+    for primitive_name in _PHASE_ORDER:
+        if primitive_name in array_form and array_form[primitive_name].get("mode") != "dropped":
+            yield primitive_name
+
+
+def project(pack_path: Path, contract: dict, output_root: Path) -> None:
+    """Single-pack convenience wrapper. Delegates to `project_packs`."""
+    project_packs([pack_path], contract, output_root)
+
+
+def project_packs(pack_paths: list[Path], contract: dict, output_root: Path) -> None:
+    """Project every pack in `pack_paths` in order, then run the
+    shared orphan-sweep post-pass on the `skill` target directory.
+
+    Same-name collision rule: pack source order as supplied here; the
+    last pack's `<name>` overwrites earlier packs' (`_project_direct_directory`
+    `rmtree`s the destination before `copytree`). The orphan sweep
+    observes the union of source skill names across the call's pack
+    list (not per-pack) so a pack shipping a subset can co-exist with
+    another that ships the union complement.
+    """
+    for pack_path in pack_paths:
+        _project_single(pack_path, contract, output_root)
+    _sweep_skill_orphans(pack_paths, contract, output_root)
+
+
+# Mirror of kiro.py:_skill_direct_directory_target — keep in sync.
+# A shared helper is barred by the spec's `Never do` boundary (no
+# expansion of projections/direct_directory.py beyond `sweep_orphans`).
+def _skill_direct_directory_target(contract: dict, output_root: Path) -> Path | None:
+    adapter_block = contract["adapter"]["claude-code"]
+    for entry in adapter_block.get("projection", []):
+        if entry.get("primitive") == "skill" and entry.get("mode") == "direct-directory":
+            return output_root / entry["target-path"].rstrip("/")
+    return None
+
+
+def _sweep_skill_orphans(pack_paths: list[Path], contract: dict, output_root: Path) -> None:
+    target_dir = _skill_direct_directory_target(contract, output_root)
+    if target_dir is None:
+        return
+    skill_source_path = contract["primitive"]["skill"]["source-path"].rstrip("/")
+    expected_names: set[str] = set()
+    for pack_path in pack_paths:
+        source_dir = pack_path / skill_source_path
+        if not source_dir.exists():
+            continue
+        for entry in source_dir.iterdir():
+            if entry.is_dir():
+                expected_names.add(entry.name)
+    sweep_orphans(target_dir, expected_names)
+
+
+def _project_single(pack_path: Path, contract: dict, output_root: Path) -> None:
+    adapter_block = contract["adapter"]["claude-code"]
+    rules_by_primitive = {entry["primitive"]: entry for entry in adapter_block.get("projection", [])}
+
+    for primitive_name in _iter_primitives(contract):
+        rule = rules_by_primitive[primitive_name]
+        mode = rule["mode"]
+        primitive = contract["primitive"][primitive_name]
+        source_dir = pack_path / primitive["source-path"].rstrip("/")
+        if not source_dir.exists():
+            continue
+
+        if mode == "direct-directory":
+            _project_direct_directory(source_dir, output_root / rule["target-path"].rstrip("/"))
+        elif mode == "direct-file":
+            _project_direct_file(source_dir, output_root, rule["target-path"])
+        elif mode == "merge-json":
+            project_merge_json(source_dir, output_root, rule)
+        else:
+            raise ValueError(f"claude-code: unhandled mode {mode!r} for {primitive_name}")
+
+
+def _project_direct_directory(source_dir: Path, target_dir: Path) -> None:
+    for entry in sorted(source_dir.iterdir()):
+        # Defense-in-depth — `lint-packs` rejects packs that ship
+        # symlinks, but a direct `project_packs` caller bypasses
+        # that gate. A symlink at the skill-root level would be
+        # dereferenced by `copytree`.
+        if entry.is_symlink():
+            continue
+        if entry.is_dir():
+            destination = target_dir / entry.name
+            # Spec § Never do — `shutil.rmtree` is barred against
+            # any entry whose `is_symlink()` is true. If a previous
+            # run left a symlink at the destination path, unlink it
+            # (removes the link, not the target).
+            if destination.is_symlink():
+                destination.unlink()
+            elif destination.exists():
+                shutil.rmtree(destination)
+            # symlinks=True preserves symlinks rather than dereferencing
+            # them — a malicious pack with a symlink to /etc/passwd
+            # cannot exfiltrate the target into the projection.
+            shutil.copytree(entry, destination, symlinks=True)
+
+
+def _project_direct_file(source_dir: Path, output_root: Path, target_prefix: str) -> None:
+    target_dir = output_root / target_prefix.rstrip("/")
+    target_dir.mkdir(parents=True, exist_ok=True)
+    for entry in sorted(source_dir.iterdir()):
+        if entry.is_file():
+            destination = target_dir / entry.name
+            shutil.copy2(entry, destination, follow_symlinks=False)
+
+