agentbundle 0.2.0__py3-none-any.whl

agentbundle/build/projections/kiro_ide_hook.py

@@ -0,0 +1,256 @@
+"""``kiro-ide-hook`` projection — direct-file copy + ``then.command``
+placeholder expansion (RFC-0005, v0.4).
+
+The projection mode is ``direct-file`` byte-for-byte for askAgent-shaped
+hooks (no scan surface) and parse-modify-emit for runCommand-shaped
+hooks that contain ``${hook-body:<name>}`` placeholders in
+``then.command``. RFC-0005 § Substitution rules pins the placeholder
+mechanics:
+
+  1. Scan surface — ``then.command`` only. Every other field in the
+     ``.kiro.hook`` JSON (``then.prompt``, ``when.patterns``, ``name``,
+     ``description``, …) passes through verbatim.
+  2. Verbatim substitution — no shell quoting; pack authors quote
+     placeholders themselves.
+  3. Multiple placeholders allowed; single-pass resolution. Resolved
+     text is NOT re-scanned.
+  4. Placeholder grammar — strict regex ``\\$\\{hook-body:[a-zA-Z0-9_-]+\\}``.
+     Validated upstream at ``validate`` time (T-C2's
+     ``check_kiro_ide_hook`` rail in ``scope_rails.py``); a malformed
+     placeholder reaching the projector is a defense-in-depth refusal.
+  5. Unresolvable references refuse — same defense-in-depth.
+
+The output path's ``<pack>`` placeholder resolves to the source
+pack's directory name; the ``<name>`` placeholder resolves to the
+``.kiro.hook`` file's bare name (extension stripped). Both are
+substituted into the contract-declared ``target.repo`` template.
+
+This module is stdlib-only — ``json`` + ``re`` + ``shutil`` +
+``pathlib``.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from pathlib import Path
+
+
+class KiroIdeHookRefusal(Exception):
+    """Raised when projection refuses to write.
+
+    All reachable paths are defense-in-depth (the validate rail
+    refuses these cases upstream); the exception only fires when
+    a caller skipped validate or supplied a malformed pack
+    directly to the projector.
+    """
+
+
+# Strict placeholder grammar — same regex as the validate rail.
+# Kept inline rather than imported so this module's contract is
+# self-evident from its source; the rail's regex carries the same
+# grammar.
+_HOOK_BODY_PLACEHOLDER_RE = re.compile(r"\$\{hook-body:([a-zA-Z0-9_-]+)\}")
+
+# Loose `${...}` matcher; an offender that matches this but not the
+# strict regex above is a malformed placeholder.
+_ANY_PLACEHOLDER_RE = re.compile(r"\$\{[^}]*\}")
+
+# `.kiro.hook` is a compound extension; pathlib treats ``.hook`` as
+# the suffix and ``.kiro`` as the prior segment. Endswith-check on
+# the literal extension is more readable than juggling ``suffixes``.
+_KIRO_HOOK_EXTENSION = ".kiro.hook"
+
+
+def project(
+    pack_path: Path,
+    output_root: Path,
+    target_template: str,
+    hook_body_target_dir: str,
+) -> None:
+    """Project every ``.apm/kiro-ide-hooks/<name>.kiro.hook`` under
+    *pack_path* into *output_root* per the *target_template* shape.
+
+    Arguments:
+      pack_path: pack source root.
+      output_root: where to write projected files (the per-pack base
+        the caller passes in — typically ``<dist>/<pack>/`` or the
+        repo root for ``make build --self``).
+      target_template: contract-declared
+        ``[adapter.kiro.projections.kiro-ide-hook].target.repo``,
+        e.g. ``".kiro/hooks/<pack>/<name>.kiro.hook"``. The
+        ``<pack>`` and ``<name>`` placeholders resolve at projection
+        time. The pre-bump v0.3 contract carries no such field
+        (the v0.4 declaration is probe-gated, T-CONTRACT); callers
+        targeting v0.3 contracts simply don't invoke this projector.
+      hook_body_target_dir: the projected hook-body directory for
+        same-pack ``${hook-body:<name>}`` references — e.g.
+        ``"tools/hooks"`` at repo scope (the Kiro adapter's legacy
+        ``[[adapter.kiro.projection]] primitive = "hook-body"``
+        target). Resolved placeholders emit
+        ``./{hook_body_target_dir}/<actual-filename>``.
+
+    Raises:
+      KiroIdeHookRefusal: on JSON parse failure, on a malformed
+        placeholder reaching projection, or on an unresolvable
+        placeholder. All three are validate-rail-covered cases;
+        the projector refuses defensively rather than emitting a
+        silently-wrong artifact.
+    """
+    source_dir = pack_path / ".apm" / "kiro-ide-hooks"
+    if not source_dir.exists():
+        return
+    pack_name = pack_path.name
+    hook_body_files = _collect_hook_body_files(pack_path)
+
+    for entry in sorted(source_dir.iterdir()):
+        if not entry.name.endswith(_KIRO_HOOK_EXTENSION):
+            continue
+        if not entry.is_file() or entry.is_symlink():
+            continue
+
+        bare_name = entry.name[: -len(_KIRO_HOOK_EXTENSION)]
+        if not bare_name:
+            # A file named exactly `.kiro.hook` would land as a dotfile
+            # at `.kiro/hooks/<pack>/.kiro.hook` and collide with any
+            # other dotfile in the directory. Defense-in-depth refusal —
+            # the validate rail catches this upstream too.
+            raise KiroIdeHookRefusal(
+                f"pack {pack_name}'s kiro-ide-hook entry has an "
+                f"empty bare name; expected <name>.kiro.hook with "
+                f"<name> non-empty"
+            )
+        resolved_target = (
+            target_template
+            .replace("<pack>", pack_name)
+            .replace("<name>", bare_name)
+        )
+        target_path = output_root / resolved_target.lstrip("/")
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+
+        raw_bytes = entry.read_bytes()
+
+        # askAgent byte-copy shortcut. RFC's placeholder grammar uses
+        # `${` as the unambiguous prefix; if the raw file carries no
+        # such substring AND the parsed JSON's then.type is askAgent,
+        # the file has no expansion work to do and a byte copy
+        # preserves the source's key order, whitespace, and trailing
+        # newline.
+        if b"${" not in raw_bytes:
+            try:
+                parsed = json.loads(raw_bytes.decode("utf-8"))
+            except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+                raise KiroIdeHookRefusal(
+                    f"pack {pack_name}'s kiro-ide-hook {entry.name} "
+                    f"failed to parse: {exc}"
+                )
+            if (
+                isinstance(parsed, dict)
+                and isinstance(parsed.get("then"), dict)
+                and parsed["then"].get("type") == "askAgent"
+            ):
+                shutil.copy2(entry, target_path, follow_symlinks=False)
+                continue
+            # Non-askAgent without placeholders — also byte-copy. No
+            # scan surface; nothing to rewrite.
+            shutil.copy2(entry, target_path, follow_symlinks=False)
+            continue
+
+        # Otherwise: parse, expand, re-emit. The parse step also
+        # catches malformed JSON the validate rail would already have
+        # refused.
+        try:
+            body = json.loads(raw_bytes.decode("utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            raise KiroIdeHookRefusal(
+                f"pack {pack_name}'s kiro-ide-hook {entry.name} "
+                f"failed to parse: {exc}"
+            )
+        if not isinstance(body, dict):
+            raise KiroIdeHookRefusal(
+                f"pack {pack_name}'s kiro-ide-hook {entry.name} "
+                f"is not a JSON object"
+            )
+
+        then = body.get("then")
+        command = then.get("command") if isinstance(then, dict) else None
+        if isinstance(command, str):
+            new_command = _expand_placeholders(
+                command,
+                pack_name=pack_name,
+                file_name=entry.name,
+                hook_body_files=hook_body_files,
+                hook_body_target_dir=hook_body_target_dir.rstrip("/"),
+            )
+            then["command"] = new_command
+
+        # Emit with stable formatting — `indent=2` matches the
+        # fixtures' shape and the RFC's example, `sort_keys=False`
+        # preserves source ordering best-effort, trailing newline for
+        # POSIX-friendliness.
+        target_path.write_text(
+            json.dumps(body, indent=2, sort_keys=False) + "\n",
+            encoding="utf-8",
+        )
+
+
+def _collect_hook_body_files(pack_path: Path) -> dict[str, str]:
+    """Return basename → filename for every hook-body the pack ships.
+
+    e.g. ``{"lint": "lint.py", "format": "format.sh"}``. Used by
+    placeholder resolution to emit the actual extension. Symlinks
+    silently skipped (Rail B is the gate for symlinked hook-bodies
+    at user scope; at repo scope the safer default is to ignore).
+    """
+    out: dict[str, str] = {}
+    hook_body_dir = pack_path / ".apm" / "hooks"
+    if not hook_body_dir.exists():
+        return out
+    for entry in sorted(hook_body_dir.iterdir()):
+        if entry.is_symlink():
+            continue
+        if entry.is_file():
+            out[entry.stem] = entry.name
+    return out
+
+
+def _expand_placeholders(
+    command: str,
+    *,
+    pack_name: str,
+    file_name: str,
+    hook_body_files: dict[str, str],
+    hook_body_target_dir: str,
+) -> str:
+    """Single-pass placeholder expansion against ``then.command``.
+
+    Refuses (defense-in-depth) on malformed or unresolvable
+    placeholders even though the validate rail covered these
+    upstream. Resolved text is NOT re-scanned (RFC § Substitution
+    rules clause 3) — single pass via ``re.sub``.
+    """
+    # Defense-in-depth check 1 — malformed placeholder.
+    for match in _ANY_PLACEHOLDER_RE.finditer(command):
+        literal = match.group(0)
+        if not _HOOK_BODY_PLACEHOLDER_RE.fullmatch(literal):
+            raise KiroIdeHookRefusal(
+                f"pack {pack_name}'s kiro-ide-hook {file_name} "
+                f"contains malformed placeholder '{literal}'; "
+                f"expected ${{hook-body:<name>}} with name "
+                f"matching [a-zA-Z0-9_-]+"
+            )
+
+    def _resolve(match: re.Match[str]) -> str:
+        name = match.group(1)
+        filename = hook_body_files.get(name)
+        if filename is None:
+            raise KiroIdeHookRefusal(
+                f"pack {pack_name}'s kiro-ide-hook {file_name} "
+                f"references unknown hook-body "
+                f"'${{hook-body:{name}}}'; no such hook-body "
+                f"in pack"
+            )
+        return f"./{hook_body_target_dir}/{filename}"
+
+    return _HOOK_BODY_PLACEHOLDER_RE.sub(_resolve, command)

agentbundle/build/projections/merge_into_agent_json.py

@@ -0,0 +1,264 @@
+"""``merge-into-agent-json`` projection mode — Kiro at both scopes.
+
+Merges a pack's ``.apm/hook-wiring/*.toml`` content into a **pack-owned**
+agent JSON at ``<scope-root>/.kiro/agents/<attach-to-agent>.json`` under
+the ``hooks`` key. The mode reuses ``user-merge-json``'s
+array-append-with-id discipline, with structural differences from the
+Claude-Code-user-scope shape:
+
+1. **Target is pack-owned, not adopter-shared.** Adopter hand-edits to
+   the agent JSON are squatting on a managed surface — the next upgrade
+   replaces the file via the agent primitive's ``direct-file``
+   projection. No collision detection, no ``--force-merge`` flag.
+2. **Agent file must exist before merge runs.** RFC-0005 establishes
+   the build-pipeline ordering invariant — agents project before any
+   wiring merges run. The absent-file case is a refuse-with-internal-
+   error path, exercised only via test instrumentation.
+3. **Per-agent target, scope-conditional.** Each wiring TOML targets
+   a single agent named by its ``attach-to-agent`` field. The caller
+   (T8b) is responsible for resolving the target file path; this
+   module operates on the resolved path.
+
+This module is stdlib-only — ``json`` + ``pathlib`` + ``tempfile``.
+
+T8b will own the install/uninstall CLI threading; T7 enforces the
+pipeline ordering in the iterator. T6 (this module) ships the merge
+engine plus the per-adapter event-vocabulary rail used by
+``commands/validate.py``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from agentbundle.build.projections.hook_id import synthesize_id
+
+
+class AgentJsonRefusal(Exception):
+    """Raised when ``project`` / ``unproject`` refuses to write.
+
+    The exception's string is the refuse-and-explain text RFC-0005
+    specifies. CLI callers (T8b) catch and print to stderr without
+    paraphrasing.
+    """
+
+
+def project(
+    target_path: Path,
+    pack_name: str,
+    wiring_tomls: dict[str, dict],
+) -> list[tuple[str, str]]:
+    """Merge *wiring_tomls* into the agent JSON at *target_path*.
+
+    Arguments:
+      target_path: resolved path to the agent JSON. **Must exist** —
+        the build pipeline (T7) projects agents before wiring runs.
+        Absent → refuse with the ``internal:`` text.
+      pack_name: the pack's ``[pack].name``. Substituted into id tags.
+      wiring_tomls: map of wiring TOML basename (no ``.toml``) → parsed
+        TOML body (typically ``{"attach-to-agent": "<name>", "hooks":
+        {"<Event>": [entries]}}``). The ``attach-to-agent`` field is
+        not consumed here — the caller has already resolved
+        *target_path* using it.
+
+    Returns:
+      List of ``(event, id)`` tuples reflecting every owned entry
+      written. T8b records these in the state file's
+      ``hook-wiring-owned`` table so ``unproject`` can be precise.
+
+    Raises:
+      AgentJsonRefusal: missing agent file (pipeline-ordering
+        violation), unparseable JSON, wrong-shape ``hooks`` or
+        ``hooks.<event>``.
+    """
+    if not target_path.exists():
+        # The text below extends RFC-0005's bare `internal: <agent-file>
+        # missing` shape with diagnostic context. This is intentional —
+        # the message is a CLI-internal-error string, not an
+        # adopter-facing contract, so we trade brevity for the breadcrumb
+        # "agent must project before wiring" that points at the
+        # pipeline-ordering invariant. Tests assert the substrings
+        # `internal:` / `missing` / `agent must project before wiring`
+        # to keep T8b's CLI handler portable across text refinements.
+        raise AgentJsonRefusal(
+            f"internal: {target_path} missing at hook-wiring merge time; "
+            f"agent must project before wiring"
+        )
+
+    data = _load_agent_json(target_path)
+    _shape_check_hooks(target_path, data)
+
+    owned: list[tuple[str, str]] = []
+    for basename, body in wiring_tomls.items():
+        entry_id = synthesize_id(pack_name, basename)
+        hooks_in_wiring = body.get("hooks", {}) if isinstance(body, dict) else {}
+        if not isinstance(hooks_in_wiring, dict):
+            continue
+        for event, incoming_entries in hooks_in_wiring.items():
+            if not isinstance(incoming_entries, list):
+                continue
+            data.setdefault("hooks", {})
+            data["hooks"].setdefault(event, [])
+            event_array = data["hooks"][event]
+            _shape_check_event_array(target_path, event, event_array)
+            for incoming in incoming_entries:
+                if not isinstance(incoming, dict):
+                    continue
+                tagged = dict(incoming)
+                tagged["id"] = entry_id
+                _merge_one_entry(event_array, tagged)
+                owned.append((event, entry_id))
+
+    _atomic_write(target_path, data)
+    # Deduplicate (event, id) tuples — see T5's note in user_merge_json.
+    seen: set[tuple[str, str]] = set()
+    result: list[tuple[str, str]] = []
+    for item in owned:
+        if item not in seen:
+            seen.add(item)
+            result.append(item)
+    return result
+
+
+def unproject(target_path: Path, owned: list[tuple[str, str]]) -> None:
+    """Remove every ``(event, id)`` pair in *owned* from *target_path*.
+
+    Empty ``hooks.<event>`` arrays are removed. The agent file itself
+    is **never** removed by this function — that's the agent
+    primitive's ``direct-file`` uninstall's responsibility (RFC-0005
+    § Conflict, idempotency, uninstall).
+
+    If the target file is absent, ``unproject`` is a no-op — same
+    rationale as T5's ``user_merge_json.unproject``: a state row
+    pointing at a now-absent file is an orphan-in-state condition that
+    T9's reconcile surfaces. Refusing here would block uninstall of
+    unrelated packs whose own target files happen to be absent.
+    """
+    if not target_path.exists():
+        return
+
+    data = _load_agent_json(target_path)
+    _shape_check_hooks(target_path, data)
+
+    hooks = data.get("hooks")
+    if not isinstance(hooks, dict):
+        return
+
+    owned_by_event: dict[str, set[str]] = {}
+    for event, entry_id in owned:
+        owned_by_event.setdefault(event, set()).add(entry_id)
+
+    for event, ids_to_remove in owned_by_event.items():
+        if event not in hooks:
+            continue
+        event_array = hooks[event]
+        if not isinstance(event_array, list):
+            continue
+        hooks[event] = [
+            e for e in event_array
+            if not (isinstance(e, dict) and e.get("id") in ids_to_remove)
+        ]
+        if not hooks[event]:
+            del hooks[event]
+
+    _atomic_write(target_path, data)
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+
+def _load_agent_json(target_path: Path) -> dict:
+    """Read the agent JSON. Raises ``AgentJsonRefusal`` on
+    unparseable content (matches T5's `user_merge_json` shape)."""
+    try:
+        text = target_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise AgentJsonRefusal(
+            f"cannot parse {target_path}: {exc}; fix or back up the file and retry"
+        ) from exc
+    if not text.strip():
+        # An empty agent JSON file is a Kiro-side artifact (an agent
+        # body with no fields yet) — treat as `{}` for merge.
+        return {}
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise AgentJsonRefusal(
+            f"cannot parse {target_path}: {exc}; fix or back up the file and retry"
+        ) from exc
+    if not isinstance(data, dict):
+        raise AgentJsonRefusal(
+            f"cannot parse {target_path}: top-level value is "
+            f"{type(data).__name__}, expected object; fix or back up "
+            f"the file and retry"
+        )
+    return data
+
+
+def _shape_check_hooks(target_path: Path, data: dict) -> None:
+    if "hooks" in data and not isinstance(data["hooks"], dict):
+        raise AgentJsonRefusal(
+            f"{target_path}: hooks has unexpected shape {type(data['hooks']).__name__}; "
+            f"expected object"
+        )
+
+
+def _shape_check_event_array(target_path: Path, event: str, value: object) -> None:
+    if not isinstance(value, list):
+        raise AgentJsonRefusal(
+            f"{target_path}: hooks.{event} has unexpected shape {type(value).__name__}; "
+            f"expected array"
+        )
+
+
+def _merge_one_entry(event_array: list, tagged_entry: dict) -> None:
+    """Append or replace-in-place by id.
+
+    No adopter-collision branch: the agent JSON is pack-owned (RFC-0005
+    § What this section does NOT add — no ``--force-merge`` for Kiro).
+    Adopter hand-edits to the agent file are squatting on a managed
+    surface; the next upgrade replaces the file via the agent
+    primitive's ``direct-file`` projection.
+    """
+    incoming_id = tagged_entry["id"]
+    for index, existing in enumerate(event_array):
+        if isinstance(existing, dict) and existing.get("id") == incoming_id:
+            event_array[index] = tagged_entry
+            return
+    event_array.append(tagged_entry)
+
+
+def _atomic_write(target_path: Path, data: dict) -> None:
+    """Write *data* to *target_path* via temp + rename + dir-fsync.
+
+    Same shape as T5's ``user_merge_json._atomic_write`` — see there
+    for the directory-fsync rationale.
+    """
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    serialised = json.dumps(data, indent=2, sort_keys=False) + "\n"
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        encoding="utf-8",
+        dir=str(target_path.parent),
+        prefix=target_path.name + ".",
+        suffix=".tmp",
+        delete=False,
+    ) as tmp:
+        tmp.write(serialised)
+        tmp.flush()
+        os.fsync(tmp.fileno())
+        tmp_path = Path(tmp.name)
+    tmp_path.replace(target_path)
+    try:
+        dir_fd = os.open(str(target_path.parent), os.O_RDONLY)
+        try:
+            os.fsync(dir_fd)
+        finally:
+            os.close(dir_fd)
+    except OSError:
+        pass

agentbundle/build/projections/merge_json.py

@@ -0,0 +1,58 @@
+"""Shared `merge-json` projection — claude-code's settings.local.json
+and codex's hooks.json share this implementation.
+
+Both adapters' hook-wiring lands in a JSON file with the same
+``{ "<managed-key>": { "<event>": [...handlers...] } }`` shape; the
+build-pipeline dispatcher in each adapter calls this function for any
+projection rule with ``mode == "merge-json"``.
+
+Originally private to ``adapters/claude_code.py`` as
+``_project_merge_json``; lifted to this sibling module by
+docs/specs/dropped-primitives-coverage (T2) so codex.py can reuse the
+exact same code path without re-implementing.
+"""
+
+from __future__ import annotations
+
+import json
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def project_merge_json(source_dir: Path, output_root: Path, rule: dict) -> None:
+    """Merge TOML hook-wiring source files into a JSON target file.
+
+    Reads every ``*.toml`` under ``source_dir`` (sorted), pulls the
+    payload at ``rule["managed-key"]`` (default ``"hooks"``), and
+    merges into ``output_root / rule["target-path"]``'s managed key.
+    Existing non-managed keys in the JSON target are preserved.
+
+    Output is serialised with ``indent=2, sort_keys=True`` and a
+    trailing newline — idempotent across re-runs.
+    """
+    target_path = output_root / rule["target-path"].lstrip("/")
+    managed_key = rule.get("managed-key", "hooks")
+
+    incoming: dict[str, Any] = {}
+    for entry in sorted(source_dir.iterdir()):
+        if entry.is_file() and entry.suffix == ".toml":
+            payload = tomllib.loads(entry.read_text(encoding="utf-8"))
+            for key, value in payload.get(managed_key, {}).items():
+                incoming[key] = value
+    if not incoming:
+        return
+
+    existing: dict[str, Any] = {}
+    if target_path.exists():
+        existing = json.loads(target_path.read_text(encoding="utf-8"))
+
+    merged = dict(existing.get(managed_key, {}))
+    merged.update(incoming)
+    existing[managed_key] = merged
+
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    target_path.write_text(
+        json.dumps(existing, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )