PyPI - xrefkit - Versions diffs - 0.3.0__py3-none-any.whl - Mend

xrefkit 0.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (65) hide show

xrefkit/__init__.py +5 -0
xrefkit/__main__.py +5 -0
xrefkit/catalog_cli.py +57 -0
xrefkit/cli.py +71 -0
xrefkit/contracts.py +297 -0
xrefkit/ctx.py +160 -0
xrefkit/dashboard.py +1220 -0
xrefkit/discovery.py +85 -0
xrefkit/gate.py +428 -0
xrefkit/goalstate.py +555 -0
xrefkit/hashing.py +18 -0
xrefkit/import_skill.py +469 -0
xrefkit/instance.py +133 -0
xrefkit/loaders.py +77 -0
xrefkit/mcp/__init__.py +26 -0
xrefkit/mcp/audit.py +168 -0
xrefkit/mcp/bootstrap.py +337 -0
xrefkit/mcp/catalog.py +2638 -0
xrefkit/mcp/cli.py +173 -0
xrefkit/mcp/client_cache.py +356 -0
xrefkit/mcp/context_registry.py +277 -0
xrefkit/mcp/contracts.py +243 -0
xrefkit/mcp/dist.py +234 -0
xrefkit/mcp/ownership.py +246 -0
xrefkit/mcp/repository.py +217 -0
xrefkit/mcp/schemas.py +349 -0
xrefkit/mcp/server.py +773 -0
xrefkit/mcp/startup_contract_pack.py +154 -0
xrefkit/mcp_tools.py +47 -0
xrefkit/models/__init__.py +41 -0
xrefkit/models/common.py +185 -0
xrefkit/models/effective_bundle.py +131 -0
xrefkit/models/local_manifest.py +217 -0
xrefkit/models/package_manifest.py +126 -0
xrefkit/models/run_log.py +276 -0
xrefkit/models/server_config.py +160 -0
xrefkit/models/skill_definition.py +131 -0
xrefkit/operations_cli.py +670 -0
xrefkit/ownership.py +276 -0
xrefkit/packmeta.py +289 -0
xrefkit/registry.py +334 -0
xrefkit/resolver.py +252 -0
xrefkit/resource_provider.py +187 -0
xrefkit/resources/base/contracts.json +178 -0
xrefkit/resources/base/current.json +6 -0
xrefkit/resources/base/generations/7a682a5272907354/contracts.json +178 -0
xrefkit/resources/base/generations/7a682a5272907354/model_body.md +22 -0
xrefkit/resources/base/generations/9929294385ccb7b0/contracts.json +178 -0
xrefkit/resources/base/generations/9929294385ccb7b0/model_body.md +22 -0
xrefkit/resources/base/model_body.md +22 -0
xrefkit/runlog.py +45 -0
xrefkit/skillmeta.py +1034 -0
xrefkit/skillrun.py +2381 -0
xrefkit/structure_catalog.py +199 -0
xrefkit/tools/__init__.py +119 -0
xrefkit/tools/__main__.py +4 -0
xrefkit/v2_cli.py +130 -0
xrefkit/workspace.py +117 -0
xrefkit/xref.py +1048 -0
xrefkit-0.3.0.dist-info/METADATA +203 -0
xrefkit-0.3.0.dist-info/RECORD +65 -0
xrefkit-0.3.0.dist-info/WHEEL +5 -0
xrefkit-0.3.0.dist-info/entry_points.txt +2 -0
xrefkit-0.3.0.dist-info/licenses/LICENSE +21 -0
xrefkit-0.3.0.dist-info/top_level.txt +1 -0

xrefkit/mcp/dist.py ADDED Viewed

@@ -0,0 +1,234 @@
+"""Plain-HTTP artifact distribution routes served next to the MCP endpoint.
+The MCP channel stays a context-distribution channel (small governance
+text); executable artifacts (the xrefkit runtime package, client tools package,
+optional third-party wheels, and the stdlib-only bootstrap script) are
+served as ordinary HTTP downloads under ``/dist`` on the same server, so
+package bytes never have to travel through an MCP tool result and therefore
+never enter an AI client's model context.
+Routes:
+- ``GET /dist``            pip ``--find-links`` compatible HTML index
+- ``GET /dist/index.json`` machine-readable manifest with sha256 hashes
+- ``GET /dist/<filename>`` one artifact
+"""
+from __future__ import annotations
+import base64
+from dataclasses import dataclass
+from pathlib import Path
+from .catalog import XRefCatalog
+DIST_ROUTE_PATH = "/dist"
+BOOTSTRAP_FILENAME = "bootstrap.py"
+@dataclass(frozen=True)
+class DistArtifact:
+    filename: str
+    kind: str  # "pip_package" | "bootstrap_script" | "wheel" | "extra_file"
+    content: bytes
+    sha256: str
+    size_bytes: int
+    package_id: str | None = None
+    version: str | None = None
+    install_command: str | None = None
+    def manifest_entry(self, base_url: str) -> dict[str, object]:
+        return {
+            "filename": self.filename,
+            "url": f"{base_url.rstrip('/')}{DIST_ROUTE_PATH}/{self.filename}",
+            "kind": self.kind,
+            "sha256": self.sha256,
+            "size_bytes": self.size_bytes,
+            "package_id": self.package_id,
+            "version": self.version,
+            "install_command": self.install_command,
+        }
+class ArtifactDistribution:
+    """Builds the artifact set live from the catalog's repository state."""
+    def __init__(self, catalog: XRefCatalog, extra_dir: Path | None = None) -> None:
+        self._catalog = catalog
+        self._extra_dir = extra_dir
+        self._bootstrap_source = (
+            Path(__file__).parent / BOOTSTRAP_FILENAME
+        ).read_text(encoding="utf-8")
+    def artifacts(self) -> list[DistArtifact]:
+        # Package artifacts are rebuilt from the live repository on each
+        # request; the fixed zip timestamps in the catalog builders keep the
+        # bytes (and therefore the sha256) stable for unchanged inputs.
+        artifacts = [
+            _package_artifact(self._catalog.get_xrefkit_runtime_pip_package()),
+            _package_artifact(self._catalog.get_client_tool_pip_package()),
+            _bootstrap_artifact(self._bootstrap_source),
+        ]
+        artifacts.extend(_extra_artifacts(self._extra_dir))
+        return artifacts
+    def get(self, filename: str) -> DistArtifact | None:
+        for artifact in self.artifacts():
+            if artifact.filename == filename:
+                return artifact
+        return None
+    def index_manifest(self, base_url: str) -> dict[str, object]:
+        return {
+            "server": "xrefkit-mcp",
+            "transport": "plain_http",
+            "hash_algorithm": "sha256",
+            "find_links_url": f"{base_url.rstrip('/')}{DIST_ROUTE_PATH}/",
+            "bootstrap_url": (
+                f"{base_url.rstrip('/')}{DIST_ROUTE_PATH}/{BOOTSTRAP_FILENAME}"
+            ),
+            "artifacts": [
+                artifact.manifest_entry(base_url) for artifact in self.artifacts()
+            ],
+        }
+    def index_html(self) -> str:
+        # pip --find-links page: bare anchors with a sha256 fragment.
+        links = "\n".join(
+            f'<a href="{artifact.filename}#sha256={artifact.sha256}">{artifact.filename}</a><br/>'
+            for artifact in self.artifacts()
+        )
+        return (
+            "<!DOCTYPE html>\n<html><head><title>xrefkit-mcp dist</title></head>"
+            f"<body>\n{links}\n</body></html>\n"
+        )
+    def describe_for_mcp(self, base_url: str) -> dict[str, object]:
+        """The artifact_distribution block attached to get_startup_context."""
+        base = base_url.rstrip("/")
+        return {
+            "transport": "plain_http",
+            "base_url": base,
+            "index_json_url": f"{base}{DIST_ROUTE_PATH}/index.json",
+            "find_links_url": f"{base}{DIST_ROUTE_PATH}/",
+            "bootstrap_url": f"{base}{DIST_ROUTE_PATH}/{BOOTSTRAP_FILENAME}",
+            "bootstrap_run": (
+                f"python {BOOTSTRAP_FILENAME} --base-url {base} --target ."
+            ),
+            "pip_install_example": (
+                "python -m pip install --no-index --no-build-isolation "
+                f"--find-links {base}{DIST_ROUTE_PATH}/ xrefkit"
+            ),
+            "artifacts": [
+                {
+                    key: value
+                    for key, value in artifact.manifest_entry(base).items()
+                }
+                for artifact in self.artifacts()
+            ],
+            "instructions": [
+                "Fetch artifacts out-of-band with plain HTTP GET (bootstrap "
+                "script, curl, or pip --find-links), never through the "
+                "get_*_bundle or get_*_pip_package MCP tools, so package "
+                "bytes do not enter the model context.",
+                "Verify each downloaded artifact against the sha256 in "
+                "index.json before materializing or installing it.",
+                f"First download {BOOTSTRAP_FILENAME} from bootstrap_url and "
+                "run bootstrap_run in the client-side target repository; it "
+                "verifies hashes and materializes xrefkit/ and tools/.",
+                "These HTTP routes are outside MCP session ordering; the "
+                "startup-context-first obligation still applies to the AI "
+                "session driving the download.",
+            ],
+        }
+def _package_artifact(package: dict[str, object]) -> DistArtifact:
+    content = base64.b64decode(str(package["content_base64"]))
+    return DistArtifact(
+        filename=str(package["filename"]),
+        kind="pip_package",
+        content=content,
+        sha256=str(package["content_hash"]),
+        size_bytes=len(content),
+        package_id=str(package["package_id"]),
+        version=str(package["version"]),
+        install_command=str(package["install_command"]),
+    )
+def _bootstrap_artifact(source: str) -> DistArtifact:
+    from .repository import stable_hash
+    content = source.encode("utf-8")
+    return DistArtifact(
+        filename=BOOTSTRAP_FILENAME,
+        kind="bootstrap_script",
+        content=content,
+        sha256=stable_hash(source),
+        size_bytes=len(content),
+        install_command=f"python {BOOTSTRAP_FILENAME} --base-url <base-url> --target .",
+    )
+def _extra_artifacts(extra_dir: Path | None) -> list[DistArtifact]:
+    """Operator-provided files (for example PyYAML wheels) mirrored as-is."""
+    if extra_dir is None or not extra_dir.is_dir():
+        return []
+    from .catalog import hashlib_sha256_bytes
+    artifacts: list[DistArtifact] = []
+    for path in sorted(extra_dir.iterdir()):
+        if not path.is_file():
+            continue
+        content = path.read_bytes()
+        kind = "wheel" if path.suffix == ".whl" else "extra_file"
+        artifacts.append(
+            DistArtifact(
+                filename=path.name,
+                kind=kind,
+                content=content,
+                sha256=hashlib_sha256_bytes(content),
+                size_bytes=len(content),
+                install_command=(
+                    f"python -m pip install --no-index {path.name}"
+                    if kind == "wheel"
+                    else None
+                ),
+            )
+        )
+    return artifacts
+def add_dist_routes(starlette_app: object, dist: ArtifactDistribution, base_url: str) -> None:
+    from starlette.responses import HTMLResponse, JSONResponse, Response
+    from starlette.routing import Route
+    async def index_html(_request: object) -> HTMLResponse:
+        return HTMLResponse(dist.index_html())
+    async def artifact_or_index(request: object) -> Response:
+        filename = request.path_params["filename"]
+        if filename == "index.json":
+            return JSONResponse(dist.index_manifest(base_url))
+        artifact = dist.get(filename)
+        if artifact is None:
+            return JSONResponse({"error": f"unknown artifact: {filename}"}, status_code=404)
+        media_type = (
+            "text/x-python" if artifact.filename.endswith(".py") else "application/zip"
+        )
+        return Response(
+            artifact.content,
+            media_type=media_type,
+            headers={
+                "X-Content-SHA256": artifact.sha256,
+                "Content-Disposition": f'attachment; filename="{artifact.filename}"',
+            },
+        )
+    routes = getattr(getattr(starlette_app, "router"), "routes")
+    routes.append(Route(f"{DIST_ROUTE_PATH}", index_html, methods=["GET"]))
+    routes.append(Route(f"{DIST_ROUTE_PATH}/", index_html, methods=["GET"]))
+    routes.append(
+        Route(f"{DIST_ROUTE_PATH}/{{filename}}", artifact_or_index, methods=["GET"])
+    )

xrefkit/mcp/ownership.py ADDED Viewed

@@ -0,0 +1,246 @@
+from __future__ import annotations
+import fnmatch
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any
+from .repository import stable_hash
+class OwnershipError(ValueError):
+    pass
+@dataclass(frozen=True)
+class Zone:
+    id: str
+    owner: str
+    paths: tuple[str, ...]
+    catalog: bool
+    distribution: bool
+    base_sync: bool
+    shadowing: bool
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["paths"] = list(self.paths)
+        return data
+@dataclass(frozen=True)
+class Ownership:
+    zones: tuple[Zone, ...]
+    @property
+    def content_hash(self) -> str:
+        return stable_hash(json.dumps(self.to_dict(), sort_keys=True, separators=(",", ":")))
+    def zone_for(self, rel_path: str) -> Zone | None:
+        normalized = _normalize_rel_path(rel_path)
+        for zone in self.zones:
+            if any(_matches(pattern, normalized) for pattern in zone.paths):
+                return zone
+        return None
+    def catalog_enabled(self, rel_path: str) -> bool:
+        zone = self.zone_for(rel_path)
+        return True if zone is None else zone.catalog
+    def distribution_enabled(self, rel_path: str) -> bool:
+        zone = self.zone_for(rel_path)
+        return True if zone is None else zone.distribution
+    def metadata_for(self, rel_path: str) -> dict[str, Any]:
+        zone = self.zone_for(rel_path)
+        if zone is None:
+            return {
+                "zone": None,
+                "owner": None,
+                "pack_id": _pack_id(rel_path),
+                "local_only": False,
+                "catalog": True,
+                "distribution": True,
+                "shadowing": False,
+            }
+        return {
+            "zone": zone.id,
+            "owner": zone.owner,
+            "pack_id": _pack_id(rel_path),
+            "local_only": zone.owner == "local" or zone.id == "local-packs",
+            "catalog": zone.catalog,
+            "distribution": zone.distribution,
+            "shadowing": zone.shadowing,
+        }
+    def to_dict(self) -> dict[str, Any]:
+        return {"zones": [zone.to_dict() for zone in self.zones]}
+def load_ownership(root: str | Path, filename: str = "ownership.yaml") -> Ownership | None:
+    path = Path(root) / filename
+    if not path.exists():
+        return None
+    parsed = _parse_simple_yaml(path.read_text(encoding="utf-8"))
+    zones = parsed.get("zones")
+    if not isinstance(zones, list):
+        raise OwnershipError("ownership.yaml must contain a zones list")
+    result: list[Zone] = []
+    seen: set[str] = set()
+    for index, raw in enumerate(zones):
+        if not isinstance(raw, dict):
+            raise OwnershipError(f"zone {index} must be a mapping")
+        zone = _zone_from_mapping(raw, index)
+        if zone.id in seen:
+            raise OwnershipError(f"duplicate zone id: {zone.id}")
+        seen.add(zone.id)
+        result.append(zone)
+    return Ownership(tuple(result))
+def validate_ownership(root: str | Path, ownership: Ownership) -> list[str]:
+    errors: list[str] = []
+    repo = Path(root).resolve()
+    for zone in ownership.zones:
+        for pattern in zone.paths:
+            if not pattern or pattern.startswith("/") or "\\" in pattern:
+                errors.append(f"{zone.id}: invalid path pattern `{pattern}`")
+                continue
+            literal_prefix = pattern.split("*", 1)[0]
+            target = (repo / literal_prefix).resolve()
+            try:
+                target.relative_to(repo)
+            except ValueError:
+                errors.append(f"{zone.id}: path escapes repository `{pattern}`")
+    return errors
+def _zone_from_mapping(raw: dict[str, Any], index: int) -> Zone:
+    required = ("id", "owner", "paths", "catalog", "distribution", "base_sync", "shadowing")
+    missing = [key for key in required if key not in raw]
+    if missing:
+        raise OwnershipError(f"zone {index} missing fields: {', '.join(missing)}")
+    paths = raw["paths"]
+    if not isinstance(paths, list) or not all(isinstance(item, str) for item in paths):
+        raise OwnershipError(f"zone {raw.get('id', index)} paths must be a list of strings")
+    return Zone(
+        id=_as_str(raw["id"], "id"),
+        owner=_as_str(raw["owner"], "owner"),
+        paths=tuple(_normalize_pattern(path) for path in paths),
+        catalog=_as_bool(raw["catalog"], "catalog"),
+        distribution=_as_bool(raw["distribution"], "distribution"),
+        base_sync=_as_bool(raw["base_sync"], "base_sync"),
+        shadowing=_as_bool(raw["shadowing"], "shadowing"),
+    )
+def _parse_simple_yaml(text: str) -> dict[str, Any]:
+    root: dict[str, Any] = {}
+    current_list_name: str | None = None
+    current_item: dict[str, Any] | None = None
+    current_item_list_name: str | None = None
+    for line_number, raw_line in enumerate(text.splitlines(), start=1):
+        line = raw_line.split("#", 1)[0].rstrip()
+        if not line.strip():
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        stripped = line.strip()
+        if indent == 0:
+            if not stripped.endswith(":"):
+                raise OwnershipError(f"line {line_number}: top-level value must be a mapping key")
+            current_list_name = stripped[:-1]
+            root[current_list_name] = []
+            current_item = None
+            current_item_list_name = None
+            continue
+        if current_list_name is None:
+            raise OwnershipError(f"line {line_number}: nested value before top-level key")
+        if indent == 2 and stripped.startswith("- "):
+            key, raw_value = _split_key_value(stripped[2:], line_number)
+            current_item = {key: _parse_scalar(raw_value)}
+            root[current_list_name].append(current_item)
+            current_item_list_name = None
+            continue
+        if indent == 4:
+            if current_item is None:
+                raise OwnershipError(f"line {line_number}: mapping value before list item")
+            key, raw_value = _split_key_value(stripped, line_number)
+            if raw_value == "":
+                current_item[key] = []
+                current_item_list_name = key
+            else:
+                current_item[key] = _parse_scalar(raw_value)
+                current_item_list_name = None
+            continue
+        if indent == 6 and stripped.startswith("- "):
+            if current_item is None or current_item_list_name is None:
+                raise OwnershipError(f"line {line_number}: list value without parent key")
+            current_item[current_item_list_name].append(_parse_scalar(stripped[2:]))
+            continue
+        raise OwnershipError(f"line {line_number}: unsupported indentation or syntax")
+    return root
+def _split_key_value(value: str, line_number: int) -> tuple[str, str]:
+    if ":" not in value:
+        raise OwnershipError(f"line {line_number}: expected key: value")
+    key, raw = value.split(":", 1)
+    key = key.strip()
+    if not key:
+        raise OwnershipError(f"line {line_number}: empty key")
+    return key, raw.strip()
+def _parse_scalar(value: str) -> str | bool:
+    if value == "true":
+        return True
+    if value == "false":
+        return False
+    return value.strip("'\"")
+def _as_str(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise OwnershipError(f"{field} must be a non-empty string")
+    return value
+def _as_bool(value: Any, field: str) -> bool:
+    if not isinstance(value, bool):
+        raise OwnershipError(f"{field} must be true or false")
+    return value
+def _normalize_pattern(pattern: str) -> str:
+    normalized = pattern.replace("\\", "/")
+    if normalized.startswith("./"):
+        normalized = normalized[2:]
+    if normalized and not normalized.endswith("/"):
+        normalized += "/"
+    return normalized
+def _normalize_rel_path(path: str) -> str:
+    normalized = path.replace("\\", "/")
+    if normalized.startswith("./"):
+        normalized = normalized[2:]
+    parts = PurePosixPath(normalized).parts
+    if any(part == ".." for part in parts):
+        return normalized
+    return normalized
+def _matches(pattern: str, rel_path: str) -> bool:
+    if "*" not in pattern:
+        return rel_path == pattern.rstrip("/") or rel_path.startswith(pattern)
+    return fnmatch.fnmatch(rel_path, pattern + "*")
+def _pack_id(rel_path: str) -> str | None:
+    parts = PurePosixPath(rel_path.replace("\\", "/")).parts
+    if len(parts) >= 2 and parts[0] == "packs":
+        if parts[1] == "local" and len(parts) >= 3:
+            return f"local/{parts[2]}"
+        return parts[1]
+    return None

xrefkit/mcp/repository.py ADDED Viewed

@@ -0,0 +1,217 @@
+from __future__ import annotations
+import hashlib
+import re
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+OWN_XID_RE = re.compile(
+    r"""
+    ^\s*
+    (?:
+        <!--\s*xid\s*:\s*(?P<html>[A-Za-z0-9_-]+)\s*-->
+      | (?:\#|//|--|')\s*xid\s*:\s*(?P<comment>[A-Za-z0-9_-]+)\s*$
+      | xid\s*:\s*(?P<yaml>[A-Za-z0-9_-]+)\s*$
+      | <a\s+[^>]*id=["']xid-(?P<anchor>[A-Za-z0-9_-]+)["'][^>]*>\s*</a>
+    )
+    """,
+    re.IGNORECASE | re.MULTILINE | re.VERBOSE,
+)
+HEADING_RE = re.compile(r"^#\s+(.+?)\s*$", re.MULTILINE)
+MD_LINK_RE = re.compile(r"\]\((?P<target>[^)]+#xid-(?P<xid>[A-Za-z0-9]+))\)")
+XID_TARGET_RE = re.compile(r"(?P<path>[A-Za-z0-9_.\-/]+\.md)#xid-(?P<xid>[A-Za-z0-9]+)")
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+def stable_hash(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+def repository_identity(repo_root: Path) -> tuple[str, str]:
+    """Return (fingerprint, basis) identifying the repository's content lineage.
+    Basis preference:
+    1. ``git_root_commits`` — the root commit(s) of HEAD's history. Every
+       full clone of the same repository shares them regardless of path,
+       host, or branch, so caches keyed by this fingerprint are shared
+       across machines and survive checkout moves. Multiple roots (merged
+       histories) are sorted and joined for determinism.
+    2. ``resolved_repository_root`` — path fallback for non-git
+       directories, repositories without commits, and shallow clones
+       (whose grafted history would misreport the true root commit).
+    """
+    root_commits = _git_root_commits(repo_root)
+    if root_commits:
+        seed = "git-root-commits:" + ",".join(root_commits)
+        return stable_hash(seed)[:32], "git_root_commits"
+    normalized_root = repo_root.resolve().as_posix().casefold()
+    seed = f"resolved-repository-root:{normalized_root}"
+    return stable_hash(seed)[:32], "resolved_repository_root"
+def repository_fingerprint(repo_root: Path) -> str:
+    return repository_identity(repo_root)[0]
+def _git_root_commits(repo_root: Path) -> list[str]:
+    if _git_is_shallow(repo_root):
+        return []
+    output = _git_stdout(repo_root, ["rev-list", "--max-parents=0", "HEAD"])
+    if output is None:
+        return []
+    return sorted(line.strip() for line in output.splitlines() if line.strip())
+def _git_is_shallow(repo_root: Path) -> bool:
+    output = _git_stdout(repo_root, ["rev-parse", "--is-shallow-repository"])
+    return output is not None and output.strip() == "true"
+def _git_stdout(repo_root: Path, arguments: list[str]) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", *arguments],
+            cwd=repo_root,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout
+def first_xid(text: str) -> str | None:
+    for match in OWN_XID_RE.finditer(text):
+        return (
+            match.group("html")
+            or match.group("comment")
+            or match.group("yaml")
+            or match.group("anchor")
+        )
+    return None
+def first_heading(text: str, fallback: str) -> str:
+    match = HEADING_RE.search(text)
+    return match.group(1).strip() if match else fallback
+def first_paragraph(text: str) -> str:
+    lines: list[str] = []
+    in_heading = False
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("<!--") or line.startswith("<a "):
+            continue
+        if line.startswith("#"):
+            in_heading = True
+            continue
+        if in_heading and not line.startswith(("-", "|", "```")):
+            lines.append(line)
+            if len(" ".join(lines)) > 220:
+                break
+        elif lines:
+            break
+    return " ".join(lines)[:500]
+def markdown_xid_links(text: str) -> list[str]:
+    return list(dict.fromkeys(match.group("xid") for match in MD_LINK_RE.finditer(text)))
+def markdown_xid_link_targets(text: str) -> list[dict[str, str]]:
+    links: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for match in MD_LINK_RE.finditer(text):
+        xid = match.group("xid")
+        if xid in seen:
+            continue
+        seen.add(xid)
+        links.append(
+            {
+                "xid": xid,
+                "resolver_tool": "get_document_by_xid",
+                "resolver_argument": "xid",
+            }
+        )
+    return links
+def markdown_xid_only_text(text: str) -> str:
+    return XID_TARGET_RE.sub(lambda match: f"#xid-{match.group('xid')}", text)
+def relative_to_repo(path: Path, repo_root: Path) -> str:
+    return path.resolve().relative_to(repo_root.resolve()).as_posix()
+def file_last_modified(path: Path) -> str | None:
+    """UTC ISO timestamp of the file's last modification on this checkout.
+    Derived from the filesystem, not from git history: catalog entries are
+    rebuilt from the live repository inside MCP request handlers, and
+    spawning a git subprocess there hangs the stdio transport on Windows
+    (the tool result is computed but the response never reaches the
+    client). revised_at is advisory metadata, so the checkout's mtime is an
+    acceptable and subprocess-free source.
+    """
+    try:
+        stat = path.stat()
+    except OSError:
+        return None
+    return (
+        datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc)
+        .isoformat(timespec="seconds")
+    )
+def parse_meta_bullets(text: str) -> dict[str, object]:
+    result: dict[str, object] = {}
+    current_key: str | None = None
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        top = re.match(r"^- ([A-Za-z0-9_\-]+):\s*(.*)$", line)
+        if top:
+            current_key = top.group(1)
+            value = _clean_scalar(top.group(2))
+            result[current_key] = value if value else []
+            continue
+        child = re.match(r"^\s+-\s+(.+)$", line)
+        if child and current_key:
+            existing = result.setdefault(current_key, [])
+            if not isinstance(existing, list):
+                existing = [existing]
+                result[current_key] = existing
+            existing.append(_clean_scalar(child.group(1)))
+    return result
+def _clean_scalar(value: str) -> str:
+    value = value.strip()
+    if value.startswith("`") and value.endswith("`"):
+        value = value[1:-1]
+    return value
+def scalar_list(meta: dict[str, object], key: str) -> list[str]:
+    value = meta.get(key)
+    if isinstance(value, list):
+        return [piece for item in value for piece in _split_scalar(str(item))]
+    if isinstance(value, str) and value:
+        return _split_scalar(value)
+    return []
+def _split_scalar(value: str) -> list[str]:
+    if "," not in value:
+        return [value] if value else []
+    return [_clean_scalar(piece) for piece in value.split(",") if _clean_scalar(piece)]