agentbundle 0.2.0__py3-none-any.whl

agentbundle/commands/_drop_warning.py

@@ -0,0 +1,329 @@
+"""Shared drop-warning helpers for the install and validate commands.
+
+Owns the per-file hook-wiring enumerator and the unified formatter that
+produces both the install-time ``warning:`` line and the validate-time
+``info:`` line.
+
+docs/specs/incompatible-hook-event-drop AC6 / AC6b / AC6c / AC7.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Literal
+
+
+# ---------------------------------------------------------------------------
+# Pinned ordering for <reason-summary> in the formatter.
+# Any future category is appended after these three in stable-sorted order.
+# ---------------------------------------------------------------------------
+_REASON_ORDER: tuple[str, ...] = (
+    "event not in adapter vocabulary",
+    "kiro requires 'attach-to-agent'",
+    "hook-wiring TOML failed to parse",
+)
+
+
+def _adapter_agent_event_vocabulary(
+    contract: dict,
+    adapter: str,
+) -> list[str] | None:
+    """Return the ``agent-event-vocabulary`` list for *adapter*'s
+    hook-wiring projections, or ``None`` if the adapter doesn't declare
+    one.
+
+    Reads ``[adapter.<name>.projections.hook-wiring].agent-event-vocabulary``
+    from the contract dict.
+    """
+    projections = (
+        contract.get("adapter", {})
+        .get(adapter, {})
+        .get("projections", {})
+        .get("hook-wiring", {})
+    )
+    vocab = projections.get("agent-event-vocabulary")
+    if isinstance(vocab, list):
+        return vocab
+    return None
+
+
+def _is_primitive_type_dropped(
+    contract: dict,
+    adapter: str,
+    primitive: str,
+) -> bool:
+    """Return ``True`` when the adapter projects *primitive* with
+    ``mode = "dropped"`` at the type level.
+
+    Walks ``[[adapter.<name>.projection]]`` entries — the legacy array
+    that carries the coarse-grained per-type mode (used by the
+    ``_enumerate_dropped_primitives`` rail in install.py). Returns
+    ``False`` for any adapter that has no entry for the primitive or
+    whose entry uses a non-dropped mode.
+    """
+    adapter_entries = (
+        contract.get("adapter", {}).get(adapter, {}).get("projection", [])
+    )
+    for entry in adapter_entries:
+        if entry.get("primitive") == primitive and entry.get("mode") == "dropped":
+            return True
+    return False
+
+
+def enumerate_event_dropped_wirings(
+    pack_dir: Path,
+    adapter: str,
+    contract: dict,
+) -> list[tuple[str, str]]:
+    """Return per-file hook-wiring drops as ``(relpath, reason_category)`` pairs.
+
+    AC6 / AC6b / AC6c of spec incompatible-hook-event-drop.
+
+    Walk semantics:
+      Step 1 (type-level gate): if hook-wiring is ``mode = "dropped"``
+        for the adapter at the type level, return ``[]`` early — the
+        coarse-grained rail already covers it; no double-warning.
+      Step 2: walk ``<pack_dir>/.apm/hook-wiring/*.toml`` (sorted by
+        basename):
+        2a (vocab check): if the adapter declares ``agent-event-vocabulary``
+          and any ``[[hooks.<EventName>]]`` event-name isn't in the vocab,
+          append one drop entry per file (break after first — one entry per
+          file per reason category, AC6 dedup).
+        2b (attach-to-agent, kiro-only): if ``attach-to-agent`` is omitted
+          or empty (truthy check), append ``(relpath,
+          "kiro requires 'attach-to-agent'")``.
+        Parse-fail (AC6c): on ``tomllib.TOMLDecodeError`` or ``OSError``,
+          append ``(relpath, "hook-wiring TOML failed to parse")``.
+    """
+    # Step 1: gate on non-dropped type.
+    if _is_primitive_type_dropped(contract, adapter, "hook-wiring"):
+        return []
+
+    drops: list[tuple[str, str]] = []
+    hook_wiring_dir = pack_dir / ".apm" / "hook-wiring"
+    if not hook_wiring_dir.exists():
+        return []
+
+    vocab = _adapter_agent_event_vocabulary(contract, adapter)
+
+    for toml_path in sorted(hook_wiring_dir.glob("*.toml")):
+        relpath = f"hook-wiring/{toml_path.name}"
+        # Split read + parse so OSError (unreadable file: permission,
+        # truncation, race after glob) doesn't masquerade as a parse
+        # failure in the warning. Unreadable files are skipped silently
+        # — they'll surface elsewhere (project_pack's read attempt) and
+        # the warning rail is for compatibility issues, not I/O.
+        try:
+            text = toml_path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        try:
+            data = tomllib.loads(text)
+        except tomllib.TOMLDecodeError:
+            # AC6c: install-time emits a parse-fail drop entry;
+            # validate-time refuses earlier (separate code path).
+            drops.append((relpath, "hook-wiring TOML failed to parse"))
+            continue
+
+        # Step 2a: vocab check.
+        if vocab is not None:
+            events = data.get("hooks", {})
+            if isinstance(events, dict):
+                for event_name in sorted(events.keys()):
+                    if event_name not in vocab:
+                        drops.append((relpath, "event not in adapter vocabulary"))
+                        break  # one entry per file per reason category (AC6 dedup)
+
+        # Step 2b: attach-to-agent check (kiro-only, presence-only).
+        # AC4b carve-out: non-empty unknown-agent references remain
+        # validate-time refusals; omitted-or-empty both flow here as
+        # install-side drops. The validate side refuses on attach = ""
+        # per the test pin, but install-side enumerator treats
+        # omitted-or-empty as "effectively missing" for warning purposes.
+        if adapter == "kiro":
+            attach = data.get("attach-to-agent")
+            if not isinstance(attach, str) or not attach:
+                drops.append((relpath, "kiro requires 'attach-to-agent'"))
+
+    return drops
+
+
+def _join_serial_comma(items: list[str]) -> str:
+    """Project's list-formatting convention: serial comma + 'and'.
+
+    Examples:
+      - ``[]`` → ``""``
+      - ``["a"]`` → ``"a"``
+      - ``["a", "b"]`` → ``"a and b"``
+      - ``["a", "b", "c"]`` → ``"a, b, and c"``
+    """
+    if not items:
+        return ""
+    if len(items) == 1:
+        return items[0]
+    if len(items) == 2:
+        return f"{items[0]} and {items[1]}"
+    return ", ".join(items[:-1]) + ", and " + items[-1]
+
+
+def _build_reason_summary(reason_categories: list[str]) -> str:
+    """Build the ``<reason-summary>`` string: deduplicated reason
+    categories in pinned order, joined with `` + ``.
+
+    Pinned order: vocabulary first, then attach-to-agent, then
+    parse-fail. Any future category appears after in stable-sorted
+    order.
+    """
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for cat in _REASON_ORDER:
+        if cat in reason_categories and cat not in seen:
+            ordered.append(cat)
+            seen.add(cat)
+    # Defensive: any future category not in _REASON_ORDER.
+    for cat in sorted(set(reason_categories)):
+        if cat not in seen:
+            ordered.append(cat)
+    return " + ".join(ordered)
+
+
+def _join_serial_comma_files(items: list[str]) -> str:
+    """File-list variant: always uses serial comma (Oxford comma) before
+    ``and``, including for two-item lists.
+
+    AC2 pins the two-file form as ``"a, and b"`` (comma before "and")
+    — differs from the compatible-list formatter which uses ``"a and b"``
+    for two items. Isolating the file-list join prevents the two
+    contracts from drifting if either is changed independently.
+
+    Examples:
+      - ``[]`` → ``""``
+      - ``["a"]`` → ``"a"``
+      - ``["a", "b"]`` → ``"a, and b"``
+      - ``["a", "b", "c"]`` → ``"a, b, and c"``
+    """
+    if not items:
+        return ""
+    if len(items) == 1:
+        return items[0]
+    return ", ".join(items[:-1]) + ", and " + items[-1]
+
+
+def _build_file_list(file_relpath_pairs: list[tuple[str, str]]) -> str:
+    """Build the ``<file-list>`` string: deduplicated file paths,
+    lexicographically sorted, joined with serial-comma-plus-``and``.
+    """
+    files = sorted(set(f for f, _ in file_relpath_pairs))
+    return _join_serial_comma_files(files)
+
+
+def _pluralize_primitive_name(name: str) -> str:
+    """Plural form of a primitive-type name."""
+    if name == "hook-body":
+        return "hook-bodies"
+    return name + "s"
+
+
+def format_drop_message(
+    *,
+    pack_name: str,
+    adapter: str,
+    dropped_counts: dict[str, int],
+    compatible_types: list[str],
+    event_drops: list[tuple[str, str]] | None = None,
+    mode: Literal["install_warning", "validate_info"] = "install_warning",
+) -> str:
+    """Build the drop warning / info message.
+
+    ``install_warning`` mode composes the three-clause grammar per
+    spec AC7 + AC10's "Pinned wording":
+      - Primitive-type clause (when ``dropped_counts`` non-empty).
+      - Event-level clause (when ``event_drops`` non-empty), prefixed
+        ``Additionally, `` when primitive clause also present.
+      - Closing clause (when either prior fired).
+
+    ``validate_info`` mode (AC2):
+      - Ignores ``dropped_counts`` and ``compatible_types``.
+      - Raises ``ValueError`` if ``dropped_counts`` is non-empty.
+      - Raises ``ValueError`` if ``event_drops`` is empty.
+      - Output: ``info: pack <name>: the following hook-wiring file(s)
+        will not project to <adapter> (<reason-summary>): <file-list>.``
+
+    Raises:
+        ValueError: in ``install_warning`` mode when both
+          ``dropped_counts`` and ``event_drops`` are empty.
+        ValueError: in ``validate_info`` mode when ``event_drops`` is
+          empty or when ``dropped_counts`` is non-empty.
+    """
+    effective_event_drops: list[tuple[str, str]] = event_drops or []
+
+    if mode == "validate_info":
+        if dropped_counts:
+            raise ValueError(
+                "format_drop_message: validate_info mode does not accept "
+                "dropped_counts; validate-side rail is event-only"
+            )
+        if not effective_event_drops:
+            raise ValueError(
+                "format_drop_message: validate_info mode requires non-empty event_drops"
+            )
+        reason_cats = [reason for _, reason in effective_event_drops]
+        reason_summary = _build_reason_summary(reason_cats)
+        file_list = _build_file_list(effective_event_drops)
+        return (
+            f"info: pack {pack_name}: the following hook-wiring file(s) "
+            f"will not project to {adapter} ({reason_summary}): {file_list}."
+        )
+
+    # install_warning mode
+    # Determine non-zero dropped counts.
+    nonzero_dropped = {
+        ptype: count for ptype, count in dropped_counts.items() if count > 0
+    }
+    has_prim = bool(nonzero_dropped)
+    has_event = bool(effective_event_drops)
+
+    if not has_prim and not has_event:
+        raise ValueError(
+            "format_drop_message: install_warning mode has nothing to format; "
+            "both dropped_counts and event_drops are empty"
+        )
+
+    clauses: list[str] = []
+
+    # Primitive-type clause.
+    if has_prim:
+        count_parts: list[str] = []
+        for ptype, count in sorted(nonzero_dropped.items()):
+            if count == 1:
+                count_parts.append(f"1 {ptype}")
+            else:
+                count_parts.append(f"{count} {_pluralize_primitive_name(ptype)}")
+        count_list = _join_serial_comma(count_parts)
+        clauses.append(
+            f"pack {pack_name} ships {count_list} that {adapter} "
+            f"projects as 'dropped'; these primitives will not be installed."
+        )
+
+    # Event-level clause.
+    if has_event:
+        reason_cats = [reason for _, reason in effective_event_drops]
+        reason_summary = _build_reason_summary(reason_cats)
+        file_list = _build_file_list(effective_event_drops)
+        event_clause = (
+            f"the following hook-wiring file(s) will be skipped "
+            f"({reason_summary}): {file_list}."
+        )
+        if has_prim:
+            event_clause = "Additionally, " + event_clause
+        clauses.append(event_clause)
+
+    # Closing clause.
+    compatible_parts = [
+        _pluralize_primitive_name(ptype) for ptype in sorted(compatible_types)
+    ]
+    compatible_list = _join_serial_comma(compatible_parts)
+    clauses.append(f"The compatible primitives ({compatible_list}) will proceed.")
+
+    return "warning: " + " ".join(clauses)

agentbundle/commands/adapt.py

@@ -0,0 +1,343 @@
+"""``agentbundle adapt`` — marker resolution and pending-companion report.
+
+RFC-0004 turned this into a **dual-state-file** walk:
+
+  - Read both ``<repo>/.agentbundle-state.toml`` and
+    ``~/.agentbundle/state.toml``. Either may be absent (a fresh repo,
+    or no user-scope installs yet).
+  - Read marker values from both ``<repo>/.adapt-discovery.toml`` and
+    ``~/.agentbundle/.adapt-discovery.toml`` (user-scope discovery
+    lives inside the namespaced dot-directory, not as a bare dotfile).
+    ``--values-from`` still wins as an explicit override.
+  - Walk for ``.upstream.<ext>`` companions per scope; write per-scope
+    ``.adapt-pending.md`` reports at the same per-scope locations.
+  - ``adapt --ci`` exits non-zero when *either* scope's pending file
+    would be non-empty (or any companion is on disk).
+
+Findings are routed by the scope of the state file that recorded them —
+a squatter under ``~/.claude/`` is a user-scope finding, a
+``.upstream.<ext>`` companion in ``<repo>/`` is a repo-scope finding.
+
+Spec rail: ``.adapt-discovery.toml`` is **never written** here. The
+``adapt-to-project`` LLM skill owns the write side.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import argparse
+
+# Marker regex (AC14): canonical lowercase-hyphen identifiers. The CLI
+# narrows from the prior UPPER_SNAKE-only regex to the canonical form
+# that the adapt-to-project skill writes. UPPER_SNAKE markers still
+# appearing in adopter trees are left in place with a one-shot warning
+# (``_LEGACY_UPPER_RE``); they're not substituted.
+_MARKER_RE = re.compile(r"<adapt:([a-z][a-z0-9-]*)>")
+_LEGACY_UPPER_RE = re.compile(r"<adapt:([A-Z_][A-Z0-9_]*)>")
+
+
+@dataclass
+class _Scope:
+    """Per-scope artifact paths the adapt verb operates on."""
+
+    name: str
+    root: Path
+    state_path: Path
+    discovery_path: Path
+    pending_path: Path
+    # User-scope writes must pass the adapter's `allowed-prefixes.user`
+    # list through to `safety.write_jailed` so the path-jail rail
+    # fires. Repo-scope leaves this as None (the repo-jail is the
+    # repo root; no additional prefix gate).
+    allowed_prefixes: list[str] | None = None
+
+
+def _find_upstream_companions(root: Path, projected_paths: set[str] | None = None) -> list[Path]:
+    """Return ``.upstream.<ext>`` companions of paths recorded in state.
+
+    When *projected_paths* is provided, only companions that sit next to
+    a path in the install's projection count — this prevents a stray
+    ``vendor/upstream.tar.gz`` or documentation artifact from making
+    ``adapt --ci`` exit non-zero. When *projected_paths* is ``None``
+    (e.g. no state file present), fall back to the tree walk so the
+    command still does something useful.
+    """
+    from agentbundle.safety import companion_path
+
+    companions: list[Path] = []
+    if projected_paths is not None:
+        for relpath in sorted(projected_paths):
+            comp = root / companion_path(Path(relpath))
+            if comp.is_file():
+                companions.append(comp)
+        return companions
+
+    for p in sorted(root.rglob("*")):
+        if not p.is_file():
+            continue
+        name = p.name
+        parts = name.split(".")
+        if len(parts) >= 2 and "upstream" in parts:
+            idx = parts.index("upstream")
+            if idx > 0:
+                companions.append(p)
+    return companions
+
+
+def _diff_summary(original: Path, companion: Path) -> str:
+    """Return a one-line diff summary: line-count delta and first divergent line."""
+    try:
+        orig_lines = original.read_text(encoding="utf-8", errors="replace").splitlines()
+        comp_lines = companion.read_text(encoding="utf-8", errors="replace").splitlines()
+    except Exception:
+        return "binary or unreadable"
+
+    delta = len(comp_lines) - len(orig_lines)
+    sign = "+" if delta >= 0 else ""
+    first_diff_line: str | None = None
+    for i, (ol, cl) in enumerate(zip(orig_lines, comp_lines)):
+        if ol != cl:
+            first_diff_line = f"line {i + 1}: original={ol[:60]!r} upstream={cl[:60]!r}"
+            break
+    if first_diff_line is None and len(orig_lines) != len(comp_lines):
+        first_diff_line = f"line {min(len(orig_lines), len(comp_lines)) + 1}: (line count differs)"
+
+    parts = [f"lines {sign}{delta}"]
+    if first_diff_line:
+        parts.append(first_diff_line)
+    return "; ".join(parts)
+
+
+def _apply_markers(text: str, values: dict[str, str], *, src_label: str) -> str:
+    """Replace ``<adapt:NAME>`` in *text* using *values*.
+
+    Unknown markers are left in place; a warning is printed to stderr.
+    Legacy UPPER_SNAKE markers (per AC14) are left in place with a single
+    warning per file.
+    """
+    if _LEGACY_UPPER_RE.search(text):
+        print(
+            f"adapt: warning: legacy UPPER_SNAKE marker(s) in {src_label}; "
+            f"left in place (canonical form is <adapt:[a-z][a-z0-9-]*>)",
+            file=sys.stderr,
+        )
+
+    def _replace(m: re.Match) -> str:
+        name = m.group(1)
+        if name in values:
+            return values[name]
+        print(
+            f"adapt: warning: no value for marker <adapt:{name}> in {src_label}; leaving in place",
+            file=sys.stderr,
+        )
+        return m.group(0)
+
+    return _MARKER_RE.sub(_replace, text)
+
+
+def _resolve_scopes(args: "argparse.Namespace") -> list[_Scope]:
+    """Return the per-scope artifact descriptions adapt walks.
+
+    The repo scope is always present (rooted at ``args.root``). The
+    user scope is only added if ``~`` can be resolved — when
+    ``$HOME=/`` or otherwise unresolvable, the user scope is silently
+    skipped (a repo-only fixture should not refuse on a malformed
+    user-scope environment).
+    """
+    from agentbundle import scope as scope_mod
+
+    repo_root = Path(args.root).resolve()
+    scopes: list[_Scope] = [
+        _Scope(
+            name="repo",
+            root=repo_root,
+            state_path=repo_root / ".agentbundle-state.toml",
+            discovery_path=repo_root / ".adapt-discovery.toml",
+            pending_path=repo_root / ".adapt-pending.md",
+        ),
+    ]
+    try:
+        user_root = scope_mod.resolve_user_root()
+    except scope_mod.UserScopeUnresolvable:
+        return scopes
+    # User-scope dot-directory: `<user_root>/.agentbundle/`. We don't
+    # *create* it here; we only operate on it if it already exists
+    # (i.e. some prior user-scope install set it up).
+    user_dir = user_root / ".agentbundle"
+    if user_dir.is_dir():
+        from agentbundle.commands.install import _claude_code_allowed_prefixes_user
+
+        scopes.append(
+            _Scope(
+                name="user",
+                root=user_root,
+                state_path=user_dir / "state.toml",
+                discovery_path=user_dir / ".adapt-discovery.toml",
+                pending_path=user_dir / ".adapt-pending.md",
+                allowed_prefixes=_claude_code_allowed_prefixes_user(),
+            )
+        )
+    return scopes
+
+
+def run(args: "argparse.Namespace") -> int:
+    """Entry point for ``agentbundle adapt``.
+
+    Returns 0 on success; 1 on ``--ci`` with pending companions or
+    path-jail refusal at write time.
+    """
+    from agentbundle.config import ConfigError, load_adapt_discovery_typed, load_state, load_values_from
+    from agentbundle import safety
+
+    scopes = _resolve_scopes(args)
+
+    # ── --ci mode ─────────────────────────────────────────────────────────────
+    if args.ci:
+        any_pending = False
+        for s in scopes:
+            try:
+                state = load_state(s.state_path) if s.state_path.exists() else None
+            except ConfigError as exc:
+                print(f"adapt: {exc}", file=sys.stderr)
+                return 1
+            projected = state.projected_paths() if state else None
+            companions = _find_upstream_companions(s.root, projected)
+            if companions:
+                if not any_pending:
+                    print(
+                        "adapt --ci: pending .upstream.* companions found:",
+                        file=sys.stderr,
+                    )
+                    any_pending = True
+                for cp in companions:
+                    try:
+                        rel = cp.relative_to(s.root)
+                    except ValueError:
+                        rel = cp
+                    print(f"  [{s.name}] {rel}", file=sys.stderr)
+        return 1 if any_pending else 0
+
+    # ── Default mode ──────────────────────────────────────────────────────────
+    # Build marker values from the **repo-scope** discovery file's
+    # [markers] table. Markers are repo-only per RFC-0004 — the user-
+    # scope discovery file is still read (to surface legacy-shape errors
+    # symmetrically and to honour the dual-scope walk contract) but
+    # carries no [markers] table by rail. --values-from (when supplied)
+    # wins as the explicit override.
+    values: dict[str, str] = {}
+    for s in scopes:
+        try:
+            discovery = load_adapt_discovery_typed(s.discovery_path, scope=s.name)  # type: ignore[arg-type]
+        except ConfigError as exc:
+            print(f"adapt: {exc}", file=sys.stderr)
+            return 1
+        if s.name == "repo":
+            for k, v in discovery.markers.items():
+                values[k] = v
+
+    if getattr(args, "values_from", None):
+        try:
+            explicit = load_values_from(Path(args.values_from))
+        except ConfigError as exc:
+            print(f"adapt: {exc}", file=sys.stderr)
+            return 1
+        values.update(explicit)
+
+    # ── Per-scope walk: substitute markers + emit pending report ─────────────
+    for s in scopes:
+        try:
+            state = load_state(s.state_path) if s.state_path.exists() else None
+        except ConfigError as exc:
+            print(f"adapt: {exc}", file=sys.stderr)
+            return 1
+        projected = state.projected_paths() if state else set()
+
+        # Substitute markers only when --values-from was given (preserve
+        # the read-only-without-values-from contract).
+        if getattr(args, "values_from", None) and values and projected:
+            for relpath in sorted(projected):
+                target = s.root / relpath
+                if not target.exists() or not target.is_file():
+                    continue
+                try:
+                    text = target.read_bytes().decode("utf-8")
+                except (UnicodeDecodeError, ValueError):
+                    print(f"adapt: skipping binary file: [{s.name}] {relpath}", file=sys.stderr)
+                    continue
+                substituted = _apply_markers(text, values, src_label=f"[{s.name}] {relpath}")
+                if substituted != text:
+                    try:
+                        safety.write_jailed(
+                            s.root, relpath, substituted,
+                            scope=s.name,
+                            allowed_prefixes=s.allowed_prefixes,
+                        )
+                    except safety.PathJailError as exc:
+                        print(f"adapt: {exc}", file=sys.stderr)
+                        return 1
+
+        # Build the per-scope pending report.
+        companions = _find_upstream_companions(s.root, projected)
+        report_lines: list[str] = [
+            f"# Adapt Pending Report ({s.name} scope)",
+            "",
+            "Companions awaiting human merge:",
+            "",
+        ]
+        if companions:
+            for cp in sorted(companions):
+                try:
+                    rel_companion = cp.relative_to(s.root)
+                except ValueError:
+                    rel_companion = cp
+                original = _original_from_companion(cp)
+                if original.exists():
+                    summary = _diff_summary(original, cp)
+                else:
+                    summary = "original file not found"
+                report_lines.append(f"- `{rel_companion}`: {summary}")
+        else:
+            report_lines.append("_No pending companions._")
+        report_lines.append("")
+        report_content = "\n".join(report_lines)
+
+        # Write the pending report through the per-scope path-jail. At
+        # user scope this routes through `allowed-prefixes.user` —
+        # `.adapt-pending.md` lives at `.agentbundle/.adapt-pending.md`
+        # under the user root, which the `.agentbundle/` prefix admits.
+        report_relpath = s.pending_path.relative_to(s.root).as_posix()
+        try:
+            safety.write_jailed(
+                s.root, report_relpath, report_content,
+                scope=s.name,
+                allowed_prefixes=s.allowed_prefixes,
+            )
+        except safety.PathJailError as exc:
+            print(f"adapt: {exc}", file=sys.stderr)
+            return 1
+
+    return 0
+
+
+def _original_from_companion(companion: Path) -> Path:
+    """Derive the original file path from a companion path.
+
+    Inverse of ``safety.companion_path``:
+      - ``AGENTS.upstream.md``  → ``AGENTS.md``
+      - ``Makefile.upstream``   → ``Makefile``
+      - ``foo.upstream.md``     → ``foo.md``
+    """
+    name = companion.name
+    parts = name.split(".")
+    if "upstream" in parts:
+        idx = parts.index("upstream")
+        new_parts = parts[:idx] + parts[idx + 1:]
+        new_name = ".".join(new_parts)
+        return companion.parent / new_name
+    return companion