primarysource 0.1.0__py3-none-any.whl

primarysource/fetch.py

@@ -0,0 +1,360 @@
+"""The pinned fetch: polite, bounded, and checked before anything is parsed or kept.
+
+- https only, to named hosts, no credentials, the default port; a redirect is followed only to a URL that passes
+  the same check;
+- one request per `min_interval` seconds (one per second by default) per `Fetcher`;
+- a byte ceiling on every body; the pinned sha256 is checked (`verify`) before the bytes are parsed or written;
+- the collection's network settings (`primarysource.settings`) are honoured: offline or read-only refuses before a
+  request is made;
+- `Fetcher.download` brings a large file to disk as zimlore does: a `<name>.part` written under an `O_EXCL`
+  `<name>.part.lock`, resumed with a Range request, verified against the pinned size and sha256, and only then put
+  in place with `os.replace`. A failed or interrupted download leaves a `.part`, never a file that looks complete.
+
+Lifted from `primarysource/c2sp/_fetch.py` (bbf and ecma import it there, through a re-export) and zimlore's
+`catalog.py` (`_acquire_lock`, `_transfer`, `download_result`). Both transports are injectable, so every test runs
+with no network; the urllib ones are only the defaults.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import http.client
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from contextlib import AbstractContextManager
+from http.client import HTTPMessage
+from pathlib import Path
+from typing import IO, Any, Protocol
+
+from primarysource.errors import LibError
+from primarysource.fsutil import CHUNK, Lock, replace, sha256, sha256_file, write_lock
+from primarysource.settings import require_network
+
+__all__ = [
+    "MIN_INTERVAL",
+    "PART_LOCK_STALE_SECONDS",
+    "TIMEOUT",
+    "USER_AGENT",
+    "Fetcher",
+    "Response",
+    "StreamTransport",
+    "Transport",
+    "check_url",
+    "sha256",
+    "urllib_stream_transport",
+    "urllib_transport",
+    "verify",
+]
+
+Transport = Callable[[str, int], bytes]
+"""URL and byte ceiling in, the whole body out (at most the ceiling plus one byte)."""
+
+MIN_INTERVAL = 1.0
+TIMEOUT = 60.0
+USER_AGENT = "primarysource-importer (+https://github.com/b1tninja-labs/primarysource)"
+PART_LOCK_STALE_SECONDS = 3600.0
+"""A `.part.lock` is touched on every chunk, so one untouched this long belongs to a download that died."""
+
+_RETRY = "run the same command again: it resumes from the .part"
+
+
+class Response(Protocol):
+    """What a `StreamTransport` yields: a status, headers, and a body read in pieces."""
+
+    @property
+    def status(self) -> int: ...
+
+    def header(self, name: str) -> str | None: ...
+
+    def read(self, size: int) -> bytes: ...
+
+
+StreamTransport = Callable[[str, int], AbstractContextManager[Response]]
+"""URL and start offset in (0: the whole file; otherwise a `Range: bytes=<offset>-` request), a response out. A
+416 is a response with status 416, not an exception; any other failure raises `LibError` or `OSError`."""
+
+
+def check_url(url: str, hosts: Sequence[str]) -> None:
+    """Refuse anything but `https://<host>/...` with a host from `hosts`, no credentials and no odd port."""
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme != "https" or parts.hostname not in hosts or parts.username or parts.password:
+        raise LibError(f"refusing to fetch {url!r}", f"only https from {', '.join(hosts)} is allowed")
+    if parts.port not in (None, 443):
+        raise LibError(f"refusing to fetch {url!r}", "only the default https port is allowed")
+
+
+class _Guard(urllib.request.HTTPRedirectHandler):
+    """Follow a redirect only to a URL that passes `check_url`."""
+
+    def __init__(self, hosts: Sequence[str]) -> None:
+        self._hosts = hosts
+
+    def redirect_request(
+        self, req: urllib.request.Request, fp: IO[bytes], code: int, msg: str, headers: HTTPMessage, newurl: str
+    ) -> urllib.request.Request | None:
+        check_url(newurl, self._hosts)
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def urllib_transport(hosts: Sequence[str]) -> Transport:
+    """The real transport: urllib over https, redirects checked, the body read up to the ceiling plus one byte."""
+    opener = urllib.request.build_opener(_Guard(hosts))
+
+    def fetch(url: str, max_bytes: int) -> bytes:
+        check_url(url, hosts)
+        request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})  # noqa: S310 - checked above
+        try:
+            with opener.open(request, timeout=TIMEOUT) as response:
+                body: bytes = response.read(max_bytes + 1)
+        except urllib.error.HTTPError as exc:
+            raise LibError(f"{url}: HTTP {exc.code}", "retry later, or import the file by hand with --file") from exc
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise LibError(f"{url}: {exc}", "check the network, or import the file by hand with --file") from exc
+        return body
+
+    return fetch
+
+
+class _UrllibResponse:
+    def __init__(self, status: int, headers: Any, body: IO[bytes] | None) -> None:
+        self.status = status
+        self._headers = headers
+        self._body = body
+
+    def header(self, name: str) -> str | None:
+        return self._headers.get(name) if self._headers is not None else None
+
+    def read(self, size: int) -> bytes:
+        return self._body.read(size) if self._body is not None else b""
+
+
+def urllib_stream_transport(hosts: Sequence[str]) -> StreamTransport:
+    """The real streaming transport: urllib over https, redirects checked, a Range header when resuming."""
+    opener = urllib.request.build_opener(_Guard(hosts))
+
+    @contextlib.contextmanager
+    def stream(url: str, offset: int) -> Iterator[Response]:
+        check_url(url, hosts)
+        headers = {"User-Agent": USER_AGENT, "Accept-Encoding": "identity"}
+        if offset:
+            headers["Range"] = f"bytes={offset}-"
+        request = urllib.request.Request(url, headers=headers)  # noqa: S310 - checked above
+        try:
+            response = opener.open(request, timeout=TIMEOUT)
+        except urllib.error.HTTPError as exc:
+            if exc.code == 416:
+                yield _UrllibResponse(416, exc.headers, None)
+                return
+            raise LibError(f"{url}: HTTP {exc.code}", "retry later") from exc
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise LibError(f"{url}: {exc}", "check the network, then run the same command again") from exc
+        with response:
+            yield _UrllibResponse(getattr(response, "status", 200), response.headers, response)
+
+    return stream
+
+
+def _range_start(response: Response) -> int | None:
+    match = re.fullmatch(r"bytes (\d+)-\d+/(?:\d+|\*)", response.header("Content-Range") or "", re.ASCII)
+    return int(match.group(1)) if match else None
+
+
+def _content_length(response: Response) -> int | None:
+    announced = response.header("Content-Length")
+    return int(announced) if announced and announced.isascii() and announced.isdigit() else None
+
+
+class Fetcher:
+    """Fetches at most one URL per `min_interval` seconds, to `hosts` only, while the settings allow the network.
+
+    `collection` and `legacy_app` choose whose network settings apply (`primarysource.settings`); with neither,
+    only `PRIMARYSOURCE_NETWORK` and `PRIMARYSOURCE_READONLY` do. They are read at each request.
+    """
+
+    def __init__(
+        self,
+        hosts: Sequence[str],
+        transport: Transport | None = None,
+        *,
+        stream: StreamTransport | None = None,
+        min_interval: float = MIN_INTERVAL,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+        collection: str | None = None,
+        legacy_app: str | None = None,
+        environ: Mapping[str, str] | None = None,
+    ) -> None:
+        self._hosts = tuple(hosts)
+        self._transport = transport or urllib_transport(self._hosts)
+        self._stream = stream or urllib_stream_transport(self._hosts)
+        self._interval = min_interval
+        self._clock = clock
+        self._sleep = sleep
+        self._collection = collection
+        self._legacy_app = legacy_app
+        self._environ = environ
+        self._last: float | None = None
+        self.requests = 0
+
+    def _begin(self, url: str) -> None:
+        """Check the URL and the settings, then wait out the interval and count the request."""
+        check_url(url, self._hosts)
+        require_network(url, self._collection, self._legacy_app, self._environ)
+        if self._last is not None:
+            wait = self._last + self._interval - self._clock()
+            if wait > 0:
+                self._sleep(wait)
+        self._last = self._clock()
+        self.requests += 1
+
+    def get(self, url: str, max_bytes: int) -> bytes:
+        """The body of `url`, or a `LibError` if it is not allowed, fails, or is larger than `max_bytes`."""
+        self._begin(url)
+        body = self._transport(url, max_bytes)
+        if len(body) > max_bytes:
+            raise LibError(
+                f"{url} is larger than {max_bytes} bytes", "the pinned file is smaller; do not import this"
+            )
+        return body
+
+    def download(
+        self,
+        url: str,
+        dest: Path,
+        *,
+        sha256: str,
+        size: int,
+        progress: Callable[[int, int], None] | None = None,
+        stale_lock_seconds: float = PART_LOCK_STALE_SECONDS,
+    ) -> bool:
+        """Bring `dest` to the pinned `size` and `sha256`. True if a download put it there, False if it already was.
+
+        The bytes go to `<dest>.part` under the lock `<dest>.part.lock`; an existing `.part` is resumed. Only a
+        file of the pinned size and digest is moved to `dest`, with `os.replace`; a mismatch discards the `.part`
+        and raises. An existing `dest` that is not the pinned file is replaced only by a verified download.
+        """
+        check_url(url, self._hosts)
+        if dest.is_file() and dest.stat().st_size == size and sha256_file(dest) == sha256:
+            return False
+        require_network(url, self._collection, self._legacy_app, self._environ)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        part = dest.with_name(dest.name + ".part")
+        lock_path = part.with_name(part.name + ".lock")
+        with write_lock(lock_path, stale_after=stale_lock_seconds, what=str(part)) as lock:
+            done, digest = self._transfer(url, part, lock, size, progress)
+            if done != size or digest != sha256:
+                part.unlink(missing_ok=True)
+                raise LibError(
+                    f"{url}: downloaded {done} bytes with sha256 {digest}, expected {size} bytes with the pinned "
+                    f"{sha256}; the download was discarded",
+                    "retry; if it persists the publisher changed the file or the download was altered",
+                )
+            try:
+                replace(part, dest)
+            except OSError as exc:
+                raise LibError(
+                    f"the verified download of {url} could not be moved to {dest} ({exc})",
+                    f"it is kept as {part}; free {dest} and run the same command again (no re-download is needed)",
+                ) from exc
+        return True
+
+    def _transfer(
+        self, url: str, part: Path, lock: Lock, size: int, progress: Callable[[int, int], None] | None
+    ) -> tuple[int, str]:
+        """Bring `part` to `size` bytes and return (bytes, sha256 of the whole file).
+
+        An existing `.part` is re-hashed and resumed with a Range request. A server that refuses the range (200
+        instead of 206, a wrong Content-Range, 416) makes the download start over from byte zero, never splice.
+        Never more than `size` bytes reach the disk.
+        """
+        for _ in range(2):
+            digest = hashlib.sha256()
+            offset = part.stat().st_size if part.exists() else 0
+            if offset > size:  # longer than the file can be: not a prefix of it
+                part.unlink()
+                offset = 0
+            if offset:
+                with part.open("rb") as prefix:
+                    while chunk := prefix.read(CHUNK):
+                        digest.update(chunk)
+                        lock.touch()
+            if offset == size:
+                return offset, digest.hexdigest()  # a complete .part: the digest check decides
+            self._begin(url)
+            try:
+                with self._stream(url, offset) as response:
+                    status = response.status
+                    if status == 416:
+                        if not offset:
+                            raise LibError(f"{url}: HTTP 416 for the whole file", "retry later")
+                        part.unlink(missing_ok=True)  # the server's file is shorter than our part
+                        continue
+                    if status not in (200, 206):
+                        raise LibError(f"{url}: HTTP {status}", "retry later")
+                    if offset and not (status == 206 and _range_start(response) == offset):
+                        part.unlink(missing_ok=True)
+                        if status != 200:
+                            continue
+                        digest, offset = hashlib.sha256(), 0  # range refused: this 200 is the whole file
+                    elif not offset and status != 200:
+                        raise LibError(f"{url}: HTTP {status} for a request without a range", "retry later")
+                    return self._receive(url, response, part, lock, size, offset, digest, progress)
+            except (OSError, http.client.HTTPException, ValueError) as exc:
+                raise LibError(f"download of {url} failed ({exc})", _RETRY) from exc
+        raise LibError(f"the server for {url} kept refusing to serve the file", "retry later")
+
+    @staticmethod
+    def _receive(
+        url: str,
+        response: Response,
+        part: Path,
+        lock: Lock,
+        size: int,
+        offset: int,
+        digest: hashlib._Hash,
+        progress: Callable[[int, int], None] | None,
+    ) -> tuple[int, str]:
+        promised = _content_length(response)
+        if promised is not None and promised > size - offset:
+            part.unlink(missing_ok=True)
+            raise LibError(
+                f"{url}: the server announces {promised} bytes where the pin allows {size - offset}",
+                "the server is serving a different file; nothing was kept",
+            )
+        done = offset
+        try:
+            with part.open("ab" if offset else "wb") as out:
+                while chunk := response.read(min(CHUNK, size - done + 1)):
+                    if done + len(chunk) > size:
+                        out.close()
+                        part.unlink(missing_ok=True)
+                        raise LibError(
+                            f"{url}: the server sent more than the pinned {size} bytes; discarded",
+                            "the server is serving a different file",
+                        )
+                    out.write(chunk)
+                    digest.update(chunk)
+                    done += len(chunk)
+                    lock.touch()
+                    if progress:
+                        progress(done, size)
+        except (OSError, http.client.HTTPException, ValueError) as exc:
+            raise LibError(f"download of {url} was interrupted at {done} of {size} bytes ({exc})", _RETRY) from exc
+        if done < size:
+            raise LibError(f"download of {url} was cut off at {done} of {size} bytes", _RETRY)
+        return done, digest.hexdigest()
+
+
+def verify(data: bytes, expected: str, name: str) -> None:
+    """Raise unless `data` hashes to `expected`; the message names both digests."""
+    actual = sha256(data)
+    if actual != expected:
+        raise LibError(
+            f"{name}: sha256 {actual} does not match the pinned {expected}",
+            "the publisher changed the file or the download was altered; nothing was written",
+        )

primarysource/fsutil.py

@@ -0,0 +1,150 @@
+"""Filesystem helpers that behave the same on Windows, macOS and Linux: atomic write, sha256, a write lock.
+
+Lifted from rfclib's `fsutil.py` (`atomic_write_bytes`, `bulk_lock`) and zimlore's `catalog.py::_acquire_lock`.
+
+- `atomic_write`: a temp file in the destination directory, then `os.replace`, so a reader never sees half a file
+  and a crash leaves no torn one. On Windows `os.replace` fails while another process holds the target open
+  (antivirus, search indexers, a concurrent reader), so it retries briefly.
+- `write_lock`: an `O_EXCL` lock file, which works on every OS and on network filesystems. A lock whose last touch
+  is older than `stale_after` belonged to a process that died, and is taken over. A long holder calls
+  `Lock.touch()` as it works so it is never mistaken for a dead one.
+- `bulk_lock`: one long-running writer per library (`<home>/.write.lock`); short writes rely on SQLite's locking.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import os
+import tempfile
+import time
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+from primarysource.errors import LibError
+
+STALE_LOCK_SECONDS = 6 * 3600
+REPLACE_RETRIES = 10
+CHUNK = 1 << 20
+
+
+def replace(
+    source: Path, target: Path, retries: int = REPLACE_RETRIES, sleep: Callable[[float], None] = time.sleep
+) -> None:
+    """`os.replace(source, target)`, retried while Windows reports the target in use."""
+    for attempt in range(retries):
+        try:
+            os.replace(source, target)
+            return
+        except PermissionError:
+            if attempt == retries - 1:
+                raise
+            sleep(0.05 * (attempt + 1))
+
+
+def atomic_write(path: Path, data: bytes) -> None:
+    """Write `data` to `path` through a temp file in the same directory and `os.replace`.
+
+    A reader sees the old file or the new one, never a partial one. itulib's index rebuild unlinks first and a
+    concurrent reader then sees "no index"; this is the replacement for that.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handle, temp_name = tempfile.mkstemp(dir=path.parent, prefix=path.name + ".", suffix=".part")
+    try:
+        with os.fdopen(handle, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        replace(Path(temp_name), path)
+    except BaseException:
+        Path(temp_name).unlink(missing_ok=True)
+        raise
+
+
+def sha256(data: bytes) -> str:
+    """The lowercase hex sha256 of `data`."""
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_file(path: Path) -> str:
+    """The lowercase hex sha256 of the file at `path`, read in chunks."""
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        while chunk := stream.read(CHUNK):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+class LockHeld(LibError):
+    """Another live process holds the lock."""
+
+
+@dataclass(frozen=True)
+class Lock:
+    """A held lock. `touch()` marks the holder alive; a failed touch only risks the lock being called stale."""
+
+    path: Path
+
+    def touch(self) -> None:
+        with contextlib.suppress(OSError):
+            os.utime(self.path)
+
+
+def _create(lock: Path) -> int | None:
+    try:
+        return os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+    except FileExistsError:
+        return None
+
+
+@contextlib.contextmanager
+def write_lock(
+    lock: Path,
+    *,
+    stale_after: float = STALE_LOCK_SECONDS,
+    what: str = "this library",
+    clock: Callable[[], float] = time.time,
+) -> Iterator[Lock]:
+    """Hold the lock file `lock` (created with `O_EXCL`) for the body, and remove it after.
+
+    A lock untouched for more than `stale_after` seconds is taken over. A younger one raises `LockHeld`, naming
+    the holder the lock file records. Two processes that find the same stale lock at the same instant can both
+    take it over; after `stale_after` seconds of silence that window is accepted, as rfclib accepted it.
+    """
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    descriptor: int | None = None
+    for _ in range(3):
+        descriptor = _create(lock)
+        if descriptor is not None:
+            break
+        try:
+            age = clock() - lock.stat().st_mtime
+        except OSError:
+            continue  # removed between the create and the stat: try again
+        if age <= stale_after:
+            holder = ""
+            with contextlib.suppress(OSError):
+                holder = lock.read_text("utf-8").strip()
+            raise LockHeld(
+                f"another process is writing {what} ({holder or 'holder unknown'}; lock {lock})",
+                f"wait for it to finish; if none is running, delete {lock}",
+            )
+        with contextlib.suppress(OSError):
+            lock.unlink()  # stale: its holder died
+    if descriptor is None:
+        raise LockHeld(f"could not take {lock}", f"if no other process is running, delete {lock}")
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(f"pid {os.getpid()} since {time.strftime('%Y-%m-%d %H:%M:%S')}\n")
+        yield Lock(lock)
+    finally:
+        with contextlib.suppress(OSError):
+            lock.unlink()
+
+
+@contextlib.contextmanager
+def bulk_lock(home: Path, name: str = "write", *, stale_after: float = STALE_LOCK_SECONDS) -> Iterator[Lock]:
+    """One long-running writer per library (init, sync, index build): the lock `<home>/.<name>.lock`."""
+    with write_lock(home / f".{name}.lock", stale_after=stale_after, what=str(home)) as held:
+        yield held

primarysource/gitdocs/__init__.py

@@ -0,0 +1,15 @@
+"""`gitdocs`: git's Documentation/ tree, a pinned release, read as AsciiDoc and served under `gitdocs_`.
+
+Stdlib only. `mcp` is imported by `server.py` when a server is built; `primarysource gitdocs ...` runs `cli.py`.
+`docs/gitdocs.md` is the description; `catalogue.py` holds the pin, the licence and the build.
+"""
+
+from __future__ import annotations
+
+from primarysource.gitdocs.catalogue import SPEC
+from primarysource.pkgdocs.runtime import make_collection
+
+COLLECTION = make_collection(SPEC, "primarysource.gitdocs")
+"""Refs: `gitdocs:gitformat-pack@03b4152§pack-*.idx files have the following format`; see `pkgdocs.runtime`."""
+
+__all__ = ["COLLECTION", "SPEC"]

primarysource/gitdocs/catalogue.py

@@ -0,0 +1,116 @@
+"""The `gitdocs` collection: the `Documentation/` tree of git/git, read as AsciiDoc.
+
+Source, placement and pin (read from the repository on 2026-11-13, see `docs/gitdocs.md`):
+
+- the tree is `Documentation/` at the commit of the tag `v2.56.1`. It is fetched as a gitiles subtree archive from
+  kernel.googlesource.com (a few MB), because the whole-repository tarball from GitHub is two orders larger for
+  the same files; the GitHub tarball is the second source and must give the same manifest digest;
+- the licence is GPL-2.0-only, from `COPYING` at the repository root (it says "the only valid version of the GPL
+  as far as this project is concerned is _this_ particular version", i.e. v2). `COPYING` is not inside the
+  `Documentation/` subtree, so it is named as evidence rather than read by the importer;
+- placement is **layer**: the text may be baked into an image. GPL-2.0 asks that the licence and the source stay
+  available to the recipient, which a layer that carries `gitdocs status` and the pin satisfies.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from collections.abc import Mapping
+
+from primarysource.errors import LibError
+from primarysource.pkgdocs.fetch import Source
+from primarysource.pkgdocs.model import Doc
+from primarysource.pkgdocs.readers.asciidoc import read_asciidoc
+from primarysource.pkgdocs.runtime import Build, Licence, Pin, Spec, TreeSpec, matching
+
+COMMIT = "03b41523c576f26ad34085378717a0c1b287470f"
+
+PIN = Pin(
+    commit=COMMIT,
+    label="v2.56.1",
+    date="2026-10-23",
+    files_sha256="3a6d1e943dd8fe4aff27ffb5c4c0949a5a0f170b35a1413aecf4ae62e208a9bb",
+    sources=(
+        Source(
+            f"https://kernel.googlesource.com/pub/scm/git/git/+archive/{COMMIT}/Documentation.tar.gz",
+            strip=0,
+        ),
+        Source(
+            f"https://codeload.github.com/git/git/tar.gz/{COMMIT}",
+            strip=1,
+            hosts=("codeload.github.com",),
+            subdir="Documentation",
+        ),
+    ),
+)
+
+LICENCE = Licence(
+    spdx="GPL-2.0-only",
+    redistribute="layer",
+    attribution="Copyright the Git contributors",
+    evidence="COPYING at git/git " + COMMIT[:12],
+)
+
+_MAN_TITLE = re.compile(r"[\w.+-]+\(\d\)")
+
+
+def _manpage_title(doc: Doc) -> Doc:
+    """`git-tag(1)` plus its NAME line's description: `git-tag(1) - Create, list, delete or verify tags`."""
+    if not _MAN_TITLE.fullmatch(doc.title):
+        return doc
+    for section in doc.sections:
+        if section.anchor == "name" and section.units:
+            _, sep, description = section.units[0].partition(" - ")
+            if sep:
+                return Doc(
+                    doc.id,
+                    f"{doc.title} - {' '.join(description.split())}",
+                    doc.unit,
+                    doc.sections,
+                    doc.meta,
+                    doc.warnings,
+                )
+    return doc
+
+
+def build(files: Mapping[str, bytes], pin: Pin) -> Build:
+    docs: list[Doc] = []
+    skipped: Counter[str] = Counter()
+    for path in sorted(files):
+        try:
+            doc = read_asciidoc(files[path], path.removesuffix(".adoc"))
+        except LibError:
+            skipped["not UTF-8 text"] += 1
+            continue
+        docs.append(_manpage_title(doc).with_meta(path=f"Documentation/{path}"))
+    return Build(tuple(docs), {}, skipped)
+
+
+SPEC = Spec(
+    name="gitdocs",
+    title="git Documentation",
+    licence=LICENCE,
+    trees=(
+        TreeSpec(
+            name="documentation",
+            title="Documentation/ of git/git (AsciiDoc)",
+            pins=(PIN,),
+            include=matching(r"[A-Za-z0-9][A-Za-z0-9._+/-]*\.adoc"),
+            build=build,
+        ),
+    ),
+    instructions=(
+        "git's own Documentation/ (manual pages, gitformat-*, gitprotocol-*, technical/ notes, release notes) from "
+        "the user's imported copy at a pinned release. Loop: gitdocs_search('<words>') or gitdocs_docs('gitformat') "
+        "-> gitdocs_outline('<doc>') -> gitdocs_read('<ref>'). A document id is its path without .adoc "
+        "(gitformat-pack, technical/commit-graph, RelNotes/2.50.0). A section is an id (4.2), an anchor or a heading "
+        "or a unique part of one. include:: lines are not expanded; they read '[include] <path>' and the included "
+        "file is its own document. If nothing is imported the error says how."
+    ),
+    example_refs=(
+        "gitdocs:gitformat-pack§pack-*.idx files have the following format",
+        "gitdocs:gitformat-pack@03b4152§5.4¶2",
+        "gitdocs:technical/commit-graph§Chunk Format",
+    ),
+)

primarysource/gitdocs/cli.py

@@ -0,0 +1,12 @@
+"""`primarysource gitdocs import|status|docs|outline|read|search|cite`."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from primarysource.gitdocs.catalogue import SPEC
+from primarysource.pkgdocs.serving import run
+
+
+def main(argv: Sequence[str]) -> int:
+    return run(SPEC, argv)

primarysource/gitdocs/server.py

@@ -0,0 +1,8 @@
+"""The MCP server for `gitdocs` (`primarysource mcp --collection gitdocs`). Imports `mcp` when this module loads."""
+
+from __future__ import annotations
+
+from primarysource.gitdocs.catalogue import SPEC
+from primarysource.pkgdocs.serving import build_server
+
+server = build_server(SPEC)