@event4u/agent-config 6.0.0 → 7.0.0

package/src/scripts/_lib/json_pointers.py

@@ -1,260 +0,0 @@
-"""JSON-pointer helpers for the v2 ``merged_keys[]`` manifest field.
-
-P1.5 of road-to-multi-package-coexistence (Anthropic constraint
-2026-05-12). When a tool merges into a shared JSON file, the manifest
-records which JSON pointers it owns so uninstall can subtract them
-cleanly without touching foreign keys. Two invariants:
-
-1. **No array indices.** Pointers MUST target named object keys only.
-   ``/hooks/PostToolUse`` is valid; ``/hooks/PostToolUse/0`` is not.
-   Array indices shift when another tool inserts or removes entries
-   at the same array, so an index-based pointer corrupts other
-   packages' ownership records on neighbour-tool uninstall.
-2. **Arrays carry a ``value_hash`` discriminator.** A pointer that
-   targets a parent whose value is a list records the SHA-256 of the
-   JSON-serialised list contents the install wrote, so uninstall can
-   identify the owned elements by content rather than position.
-
-This module is dependency-free (stdlib only) so it can be imported in
-both the installer (``scripts/install.py``) and the manifest layer
-(``scripts/_lib/installed_tools.py``).
-"""
-from __future__ import annotations
-
-import hashlib
-import json
-from typing import Any, Optional
-
-
-class ArrayIndexPointerError(ValueError):
-    """Raised when a JSON pointer segment is an array index."""
-
-    def __init__(self, pointer: str, segment: str):
-        super().__init__(
-            f"json_pointer {pointer!r} targets array index {segment!r}; "
-            "pointers MUST target named object keys only "
-            "(see road-to-multi-package-coexistence.md § P1.5)"
-        )
-        self.pointer = pointer
-        self.segment = segment
-
-
-def _escape_segment(key: str) -> str:
-    """Escape a JSON pointer segment per RFC 6901 § 4."""
-    return key.replace("~", "~0").replace("/", "~1")
-
-
-def validate_pointer(pointer: str) -> None:
-    """Raise :class:`ArrayIndexPointerError` if any segment is an integer.
-
-    The empty pointer (``""``) is valid (targets the document root).
-    Otherwise the pointer must start with ``/`` and split into
-    segments; each segment that parses cleanly as a non-negative
-    integer is rejected (RFC 6901 array-index syntax).
-    """
-    if pointer == "":
-        return
-    if not pointer.startswith("/"):
-        raise ValueError(
-            f"json_pointer {pointer!r} must start with '/' (RFC 6901)"
-        )
-    # Skip the leading empty segment from the leading slash.
-    segments = pointer.split("/")[1:]
-    for seg in segments:
-        # RFC 6901 § 4 — array index = unsigned integer, no leading zero
-        # except for "0" itself.
-        if seg.isdigit() and (seg == "0" or not seg.startswith("0")):
-            raise ArrayIndexPointerError(pointer, seg)
-
-
-def value_hash(value: Any) -> str:
-    """Return a stable SHA-256 hex digest of ``value`` (JSON-serialised).
-
-    Uses canonical JSON (sorted keys, no whitespace) so the hash is
-    insertion-order independent. Used to discriminate tool-owned
-    entries in a shared array on uninstall.
-    """
-    payload = json.dumps(value, sort_keys=True, separators=(",", ":"))
-    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
-
-
-def collect_pointers(
-    overlay: dict,
-    *,
-    prefix: str = "",
-    include_arrays: bool = True,
-) -> list[dict[str, Any]]:
-    """Walk an overlay dict and return one entry per object-key pointer.
-
-    Each entry: ``{"json_pointer": str, "value_hash": Optional[str]}``.
-    ``value_hash`` is set when the targeted value is a list (arrays
-    need content-hash discrimination on uninstall); for nested dicts
-    we recurse and emit a pointer for each inner key. Scalars get a
-    pointer with ``value_hash=None`` (the key/value pair fully
-    identifies the merge).
-
-    The collector NEVER emits array-index pointers — list contents
-    are owned wholesale at the parent key.
-    """
-    entries: list[dict[str, Any]] = []
-    for key, value in overlay.items():
-        pointer = f"{prefix}/{_escape_segment(str(key))}"
-        if isinstance(value, dict):
-            # Recurse so the manifest captures the leaf object keys,
-            # not just the root container. Empty dicts get a single
-            # entry at the key so an uninstall can still remove them.
-            if not value:
-                entries.append({"json_pointer": pointer, "value_hash": None})
-            else:
-                entries.extend(
-                    collect_pointers(
-                        value, prefix=pointer, include_arrays=include_arrays,
-                    )
-                )
-        elif isinstance(value, list):
-            entries.append(
-                {
-                    "json_pointer": pointer,
-                    "value_hash": value_hash(value) if include_arrays else None,
-                }
-            )
-        else:
-            entries.append({"json_pointer": pointer, "value_hash": None})
-    # Validate every emitted pointer once at the end — cheap and
-    # guarantees the invariant even if a future caller hand-crafts
-    # entries.
-    for entry in entries:
-        validate_pointer(entry["json_pointer"])
-    return entries
-
-
-def build_merge_entries(
-    file_label: str,
-    overlay: dict,
-) -> list[dict[str, Any]]:
-    """Return v2 ``merged_keys[]`` entries for a single JSON merge.
-
-    ``file_label`` is the manifest-relative file path the merge
-    touched (e.g. ``.cursor/hooks.json``). The overlay is the dict the
-    installer wrote into the file; only its top-level object keys
-    become pointers (recursing through nested objects, halting at
-    lists / scalars).
-    """
-    pointers = collect_pointers(overlay)
-    return [
-        {
-            "file": file_label,
-            "json_pointer": entry["json_pointer"],
-            "value_hash": entry["value_hash"],
-        }
-        for entry in pointers
-    ]
-
-
-# ---------------------------------------------------------------------------
-# Subtraction (P2.2 — uninstall round-trip)
-# ---------------------------------------------------------------------------
-
-
-def _split_segments(pointer: str) -> list[str]:
-    """Split a non-empty pointer into unescaped segments."""
-    if pointer == "":
-        return []
-    # RFC 6901: leading '/' separates segments; unescape ~1 → '/' and ~0 → '~'.
-    parts = pointer.split("/")[1:]
-    return [p.replace("~1", "/").replace("~0", "~") for p in parts]
-
-
-def _navigate(doc: Any, segments: list[str]) -> tuple[Any, str] | None:
-    """Walk ``doc`` down ``segments`` and return ``(parent_dict, leaf_key)``.
-
-    Returns ``None`` when any intermediate segment is missing or not a
-    dict (we never descend into lists by index, see :func:`validate_pointer`).
-    """
-    if not segments:
-        return None
-    cursor = doc
-    for seg in segments[:-1]:
-        if not isinstance(cursor, dict) or seg not in cursor:
-            return None
-        cursor = cursor[seg]
-    if not isinstance(cursor, dict):
-        return None
-    leaf = segments[-1]
-    if leaf not in cursor:
-        return None
-    return cursor, leaf
-
-
-def subtract_pointers(
-    doc: dict,
-    entries: list[dict[str, Any]],
-) -> tuple[dict, list[dict[str, Any]]]:
-    """Remove the pointers in ``entries`` from ``doc``; trim empty ancestors.
-
-    ``entries`` is a list of ``{"json_pointer": str, "value_hash":
-    Optional[str]}`` records (the per-file slice of a tool's
-    ``merged_keys[]``). For each entry:
-
-    * ``value_hash is None`` → delete the key at the pointer.
-    * ``value_hash is set`` → the target is a list owned wholesale by
-      the tool. Delete only when the current value's hash still
-      matches; otherwise treat as **drift** (a neighbour package or
-      the user edited the array) and skip, surfacing a warning.
-
-    After every leaf removal we walk up the ancestor chain and drop
-    any empty dict the removal left behind — but only empty ones. A
-    neighbour tool's remaining keys keep the container alive, so its
-    contributions are never touched.
-
-    Returns ``(updated_doc, warnings)`` where ``warnings`` is a list of
-    ``{"pointer": str, "reason": "missing" | "drift", "expected_hash":
-    Optional[str], "actual_hash": Optional[str]}`` entries describing
-    pointers that could not be subtracted cleanly.
-    """
-    warnings: list[dict[str, Any]] = []
-    # Sort longest-first so leaves are removed before their ancestors —
-    # otherwise ancestor cleanup races leaf removal in deep trees.
-    ordered = sorted(
-        entries,
-        key=lambda e: len(_split_segments(e["json_pointer"])),
-        reverse=True,
-    )
-    for entry in ordered:
-        pointer = entry["json_pointer"]
-        expected = entry.get("value_hash")
-        segments = _split_segments(pointer)
-        nav = _navigate(doc, segments)
-        if nav is None:
-            warnings.append({
-                "pointer": pointer,
-                "reason": "missing",
-                "expected_hash": expected,
-                "actual_hash": None,
-            })
-            continue
-        parent, leaf = nav
-        if expected is not None:
-            actual = value_hash(parent[leaf])
-            if actual != expected:
-                warnings.append({
-                    "pointer": pointer,
-                    "reason": "drift",
-                    "expected_hash": expected,
-                    "actual_hash": actual,
-                })
-                continue
-        del parent[leaf]
-        # Trim empty-ancestor chain — never remove a container that
-        # still holds foreign keys.
-        for depth in range(len(segments) - 1, 0, -1):
-            ancestor_segments = segments[:depth]
-            anc_nav = _navigate(doc, ancestor_segments)
-            if anc_nav is None:
-                break
-            anc_parent, anc_leaf = anc_nav
-            if isinstance(anc_parent[anc_leaf], dict) and not anc_parent[anc_leaf]:
-                del anc_parent[anc_leaf]
-                continue
-            break
-    return doc, warnings

package/src/scripts/_lib/linked_projects.py

@@ -1,238 +0,0 @@
-"""Detect IDE-attached sibling projects (linked-projects scope, Option A).
-
-Pure, dependency-free detector. Reads on-disk IDE config the developer already
-created by attaching a sibling repo, and returns the sibling project roots that
-sit *outside* the current project. Config-driven only — never guesses from
-arbitrary adjacent directories.
-
-Sources:
-  * PhpStorm / IntelliJ  — ``.idea/modules.xml`` (``<module fileurl>``) and
-    ``.idea/vcs.xml`` (``<mapping directory>``).
-  * VS Code              — ``*.code-workspace`` (``folders[].path``).
-
-Guardrails (per the linked-projects council, Option A):
-  * a candidate must resolve OUTSIDE the project root, exist, and contain a
-    ``.git/`` directory;
-  * a candidate whose file count exceeds ``max_files`` (default 20000) is
-    **flagged** ``large: true`` — NOT excluded. Under Option A the agent only
-    carries a passive awareness note and never bulk-includes sibling files, so
-    repo size is cost-irrelevant to detection; a real frontend repo routinely
-    exceeds 20000 files (excluding node_modules) and must still be surfaced.
-    The flag lets the awareness note say "large repo — check targeted impact,
-    do not scan the whole tree";
-  * the bloat directories ``node_modules``/``.git``/``dist``/``build``/
-    ``.venv``/``target`` are never descended into while counting.
-
-The detector returns awareness candidates; it does NOT include any sibling
-files in context and does NOT persist anything. Opt-in + persistence is the
-caller's job.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import re
-import xml.etree.ElementTree as ET
-from pathlib import Path
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-#: File-count ceiling above which a sibling is skipped (token-blowup guard).
-DEFAULT_MAX_FILES = 20000
-
-#: Directories never descended into while counting a sibling's size.
-SKIP_DIRS: frozenset[str] = frozenset(
-    {"node_modules", ".git", "dist", "build", ".venv", "target", ".idea"}
-)
-
-
-def detect_linked_projects(
-    project_root: Path | str,
-    *,
-    max_files: int = DEFAULT_MAX_FILES,
-) -> list[dict[str, Any]]:
-    """Return IDE-attached sibling projects outside ``project_root``.
-
-    Each entry is ``{"path": <absolute str>, "detected_via": <source>,
-    "large": <bool>}`` where source is one of ``phpstorm_modules`` /
-    ``phpstorm_vcs`` / ``vscode_workspace`` and ``large`` is true when the
-    sibling's file count (excluding bloat dirs) exceeds ``max_files``. Results
-    are de-duplicated by resolved path (first source wins) and sorted by path.
-    Size never excludes — see the module docstring.
-    """
-    root = Path(project_root).resolve()
-    if not root.is_dir():
-        logger.info("linked_projects: project_root %s is not a directory", root)
-        return []
-
-    candidates: list[tuple[Path, str]] = []
-    candidates.extend((p, "phpstorm_modules") for p in _phpstorm_modules(root))
-    candidates.extend((p, "phpstorm_vcs") for p in _phpstorm_vcs(root))
-    candidates.extend((p, "vscode_workspace") for p in _vscode_workspace(root))
-
-    seen: set[Path] = set()
-    out: list[dict[str, Any]] = []
-    for path, source in candidates:
-        try:
-            resolved = path.resolve()
-        except OSError:
-            logger.info("linked_projects: cannot resolve %s", path)
-            continue
-        if resolved in seen:
-            continue
-        if not _is_valid_sibling(resolved, root):
-            continue
-        large = _exceeds_size(resolved, max_files)
-        if large:
-            logger.info(
-                "linked_projects: %s exceeds %d files — flagged large (awareness only)",
-                resolved,
-                max_files,
-            )
-        seen.add(resolved)
-        out.append(
-            {"path": str(resolved), "detected_via": source, "large": large}
-        )
-
-    out.sort(key=lambda e: e["path"])
-    return out
-
-
-def _is_valid_sibling(candidate: Path, root: Path) -> bool:
-    """A sibling must be outside the project root, exist, and be a git repo."""
-    try:
-        if candidate == root or root in candidate.parents:
-            return False  # inside the project — that's the module system's job
-        if candidate in root.parents:
-            return False  # an ancestor of the project, not a sibling
-        if not candidate.is_dir():
-            logger.info("linked_projects: candidate missing/not-a-dir %s", candidate)
-            return False
-        if not (candidate / ".git").exists():
-            logger.info("linked_projects: candidate not a git repo %s", candidate)
-            return False
-    except OSError:
-        logger.info("linked_projects: unreadable candidate %s", candidate)
-        return False
-    return True
-
-
-def _exceeds_size(candidate: Path, max_files: int) -> bool:
-    """True if the tree (minus SKIP_DIRS) holds more than ``max_files`` files."""
-    import os
-
-    count = 0
-    for dirpath, dirnames, filenames in os.walk(candidate):
-        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
-        count += len(filenames)
-        if count > max_files:
-            return True
-    return False
-
-
-def _phpstorm_modules(root: Path) -> list[Path]:
-    """Sibling roots from ``.idea/modules.xml`` ``<module fileurl>`` entries."""
-    path = root / ".idea" / "modules.xml"
-    elems = _iter_xml_attrs(path, "module", ("fileurl", "filepath"))
-    out: list[Path] = []
-    for attrs in elems:
-        raw = attrs.get("fileurl") or attrs.get("filepath")
-        if not raw:
-            continue
-        resolved = _resolve_idea_url(raw, root)
-        if resolved is None:
-            continue
-        # raw points at <sibling>/.idea/<name>.iml → sibling is .idea's parent.
-        if resolved.parent.name == ".idea":
-            out.append(resolved.parent.parent)
-        else:
-            out.append(resolved)
-    return out
-
-
-def _phpstorm_vcs(root: Path) -> list[Path]:
-    """Sibling roots from ``.idea/vcs.xml`` ``<mapping directory>`` entries."""
-    path = root / ".idea" / "vcs.xml"
-    out: list[Path] = []
-    for attrs in _iter_xml_attrs(path, "mapping", ("directory",)):
-        raw = attrs.get("directory")
-        if not raw:
-            continue
-        resolved = _resolve_idea_url(raw, root)
-        if resolved is not None:
-            out.append(resolved)
-    return out
-
-
-def _vscode_workspace(root: Path) -> list[Path]:
-    """Sibling roots from ``*.code-workspace`` ``folders[].path`` entries."""
-    out: list[Path] = []
-    try:
-        workspaces = sorted(root.glob("*.code-workspace"))
-    except OSError:
-        return out
-    for ws in workspaces:
-        data = _read_jsonc(ws)
-        if not isinstance(data, dict):
-            continue
-        folders = data.get("folders")
-        if not isinstance(folders, list):
-            continue
-        for folder in folders:
-            if not isinstance(folder, dict):
-                continue
-            rel = folder.get("path")
-            if not isinstance(rel, str) or not rel.strip():
-                continue
-            out.append((root / rel).resolve())
-    return out
-
-
-def _resolve_idea_url(raw: str, root: Path) -> Path | None:
-    """Resolve a PhpStorm path token to an absolute Path, or None."""
-    value = raw.strip()
-    if value.startswith("file://"):
-        value = value[len("file://") :]
-    value = value.replace("$PROJECT_DIR$", str(root))
-    if not value:
-        return None
-    try:
-        return (Path(value) if Path(value).is_absolute() else root / value).resolve()
-    except OSError:
-        return None
-
-
-def _iter_xml_attrs(
-    path: Path, tag: str, _attrs: tuple[str, ...]
-) -> list[dict[str, str]]:
-    """Return the attribute dicts of every ``<tag>`` in ``path`` (tolerant)."""
-    if not path.is_file():
-        return []
-    try:
-        tree = ET.parse(path)
-    except (ET.ParseError, OSError) as exc:
-        logger.info("linked_projects: malformed/unreadable %s (%s)", path, exc)
-        return []
-    return [dict(el.attrib) for el in tree.iter(tag)]
-
-
-def _read_jsonc(path: Path) -> Any:
-    """Parse JSON that may carry ``//`` comments and trailing commas (VS Code)."""
-    try:
-        text = path.read_text(encoding="utf-8")
-    except OSError:
-        return None
-    try:
-        return json.loads(text)
-    except json.JSONDecodeError:
-        pass
-    # tolerant fallback: strip line comments + trailing commas, retry once.
-    stripped = re.sub(r"^\s*//.*$", "", text, flags=re.MULTILINE)
-    stripped = re.sub(r",(\s*[}\]])", r"\1", stripped)
-    try:
-        return json.loads(stripped)
-    except json.JSONDecodeError as exc:
-        logger.info("linked_projects: malformed workspace JSON %s (%s)", path, exc)
-        return None

package/src/scripts/_lib/model_tier.py

@@ -1,52 +0,0 @@
-"""Shared `model_tier` → native Claude `model:` mapping (ADR-034 / ADR-035).
-
-Single source of truth for the tier→model rewrite, used by **both** render
-paths so they can never drift:
-
-- the repo generator (`condense.py generate_claude_skills`), which builds the
-  package's own `.claude/skills/` tree, and
-- the consumer install finalizer (`install.py finalize_claude_model_tiers`),
-  which rewrites the installed `.claude/skills/` tree so Claude Code performs
-  the per-turn model switch on a consumer with `model.auto_switch: auto`.
-
-Only `auto` triggers the rewrite — `suggest` / `off` keep skills as pure
-symlinks so the package never silently overrides a user's explicit `/model`
-choice. A skill with `model_tier: inherit` (or no `model_tier`) is never
-rewritten.
-"""
-from __future__ import annotations
-
-import re
-from pathlib import Path
-from typing import Optional
-
-# Tier → Claude model. The ONLY per-vendor mapping the package maintains
-# (ADR-035 § 3); other agents resolve the tier band to their own line-up.
-TIER_TO_CLAUDE_MODEL = {"high": "opus", "medium": "sonnet", "lite": "haiku"}
-
-# Matches a `model_tier: <tier>` frontmatter line (quoted or bare).
-MODEL_TIER_RE = re.compile(r'^model_tier:\s*"?([a-z]+)"?\s*$', re.MULTILINE)
-
-
-def read_model_tier(skill_md: Path) -> Optional[str]:
-    """Return the `model_tier` frontmatter value, or None if absent/unparsable."""
-    if not skill_md.exists():
-        return None
-    text = skill_md.read_text(encoding="utf-8", errors="replace")
-    if not text.startswith("---\n"):
-        return None
-    end = text.find("\n---\n", 4)
-    if end == -1:
-        return None
-    m = MODEL_TIER_RE.search(text[4:end])
-    return m.group(1) if m else None
-
-
-def render_native_model_md(text: str, tier: str) -> str:
-    """Rewrite the first `model_tier: <tier>` line to native `model: <mapped>`.
-
-    The rest of the SKILL.md stays byte-identical. `tier` must be a key of
-    :data:`TIER_TO_CLAUDE_MODEL` (callers gate on that).
-    """
-    model = TIER_TO_CLAUDE_MODEL[tier]
-    return MODEL_TIER_RE.sub(f"model: {model}", text, count=1)