primarysource 0.1.0__py3-none-any.whl

primarysource/rpmdocs/__init__.py

@@ -0,0 +1,15 @@
+"""`rpmdocs`: rpm's manual and manual pages, a pinned release, read as Markdown and scdoc. Served under `rpmdocs_`.
+
+Stdlib only. `mcp` is imported by `server.py` when a server is built; `primarysource rpmdocs ...` runs `cli.py`.
+`docs/rpmdocs.md` is the description; `catalogue.py` holds the pin, the licence and the build.
+"""
+
+from __future__ import annotations
+
+from primarysource.pkgdocs.runtime import make_collection
+from primarysource.rpmdocs.catalogue import SPEC
+
+COLLECTION = make_collection(SPEC, "primarysource.rpmdocs")
+"""Refs: `rpmdocs:format_v6§Header`; see `pkgdocs.runtime`."""
+
+__all__ = ["COLLECTION", "SPEC"]

primarysource/rpmdocs/catalogue.py

@@ -0,0 +1,117 @@
+"""The `rpmdocs` collection: rpm's manual (Markdown) and manual pages (scdoc) from rpm-software-management/rpm.
+
+Source, placement and pin (read from the repository on 2026-11-13, see `docs/rpmdocs.md`):
+
+- the tree is `docs/` at the commit of the tag `rpm-6.1.0-release`: `docs/manual/*.md` (the format documents
+  `format_v4`, `format_v6`, `tags`, `spec`, `macros`, `dependencies`, ...) and `docs/man/*.scd` (rpm(8),
+  rpm-macros(7), rpm-queryformat(7), ...), fetched as a GitHub tarball (1.2 MB);
+- the licence is GPL-2.0-or-later: `COPYING` at the repository root says "In SPDX terms, the entire code base is
+  licensed GPL-2.0-or-later", with LGPL-2.0-or-later as an alternative for `lib/` and `rpmio/` only, which are
+  not the documentation. The files under `docs/` carry no licence of their own;
+- placement is **layer**.
+
+Ids: a manual page is `<name>.<section>` (`rpm-macros.7`, `rpm.8`; `rpm-macros` alone also works), a manual
+document is its file name without `.md` (`format_v6`, `tags`).
+"""
+
+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.markdown import read_markdown
+from primarysource.pkgdocs.readers.scdoc import read_scdoc
+from primarysource.pkgdocs.runtime import Build, Licence, Pin, Spec, TreeSpec, matching
+
+COMMIT = "f832c7e69945248dd5bcfcacfd10c176ee300fa2"
+
+PIN = Pin(
+    commit=COMMIT,
+    label="rpm-6.1.0-release",
+    date="2026-08-20",
+    files_sha256="610c31cafa342d40c7dd3e507749c1fc90fa32c3550d6b8a3e440f45b4a037b7",
+    sources=(
+        Source(f"https://codeload.github.com/rpm-software-management/rpm/tar.gz/{COMMIT}", strip=1, subdir="docs"),
+        Source(
+            f"https://github.com/rpm-software-management/rpm/archive/{COMMIT}.tar.gz",
+            strip=1,
+            hosts=("codeload.github.com",),
+            subdir="docs",
+        ),
+    ),
+)
+
+LICENCE = Licence(
+    spdx="GPL-2.0-or-later",
+    redistribute="layer",
+    attribution="RPM Package Manager contributors",
+    evidence="COPYING at rpm-software-management/rpm " + COMMIT[:12] + ' ("In SPDX terms ... GPL-2.0-or-later")',
+)
+
+_MAN = re.compile(r"man/([a-z0-9._+-]+\.\d)\.scd")
+_MANUAL = re.compile(r"manual/([A-Za-z0-9_.+-]+)\.md")
+
+
+def build(files: Mapping[str, bytes], pin: Pin) -> Build:
+    docs: list[Doc] = []
+    aliases: dict[str, str] = {}
+    skipped: Counter[str] = Counter()
+    for path in sorted(files):
+        man = _MAN.fullmatch(path)
+        manual = _MANUAL.fullmatch(path)
+        try:
+            if man:
+                page = man.group(1)
+                doc = read_scdoc(files[path], page)
+                aliases[page.rsplit(".", 1)[0]] = page
+                name, section = page.rsplit(".", 1)
+                body_title = _name_line(doc)
+                title = f"{name}({section})" + (f" - {body_title}" if body_title else "")
+                doc = Doc(doc.id, title, doc.unit, doc.sections, doc.meta, doc.warnings)
+            elif manual:
+                doc = read_markdown(files[path], manual.group(1))
+            else:
+                skipped["not a manual or man page source"] += 1
+                continue
+        except LibError:
+            skipped["not UTF-8 text"] += 1
+            continue
+        docs.append(doc.with_meta(path=f"docs/{path}", licence="GPL-2.0-or-later (COPYING, no file tag)"))
+    return Build(tuple(docs), aliases, skipped)
+
+
+def _name_line(doc: Doc) -> str:
+    """The description in the NAME section's `*name* - description` line."""
+    for section in doc.sections:
+        if section.anchor == "name" and section.units:
+            _, sep, description = section.units[0].partition(" - ")
+            return " ".join(description.split()) if sep else ""
+    return ""
+
+
+SPEC = Spec(
+    name="rpmdocs",
+    title="RPM documentation",
+    licence=LICENCE,
+    trees=(
+        TreeSpec(
+            name="docs",
+            title="docs/ of rpm-software-management/rpm (Markdown, scdoc)",
+            pins=(PIN,),
+            include=matching(r"manual/[A-Za-z0-9_.+-]+\.md|man/[a-z0-9._+-]+\.\d\.scd"),
+            build=build,
+        ),
+    ),
+    instructions=(
+        "rpm's manual (file formats format_v4/format_v6, tags, spec, macros, dependencies, ...) and manual pages "
+        "(rpm.8, rpm-macros.7, rpm-queryformat.7, ...) from the user's imported copy at a pinned release. Loop: "
+        "rpmdocs_search('<words>') -> rpmdocs_outline('format_v6') -> rpmdocs_read('<ref>'). A manual document's id "
+        "is its file name without .md; a man page's id is name.section ('rpm-macros.7', or just 'rpm-macros'). A "
+        "section is an id, an anchor, a heading or a unique part of one."
+    ),
+    example_refs=("rpmdocs:format_v6§Header", "rpmdocs:tags§Tag types", "rpmdocs:rpm-macros.7§DESCRIPTION"),
+)

primarysource/rpmdocs/cli.py

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

primarysource/rpmdocs/server.py

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

primarysource/scaffold.py

@@ -0,0 +1,223 @@
+"""The MCP scaffold: how a collection's tools are registered, and how `primarysource mcp` serves collections.
+
+Three rules from PLAN.md §5, enforced here so no collection has to remember them:
+
+- **Errors** (§5.10). `guard` turns a `LibError` into the SDK's `ToolError`, which reaches the client as an
+  `isError` result. Its text is the `error:`, `hint:` and `action:` lines of `LibError.as_text`. The SDK puts
+  `Error executing tool <name>:` in front of every tool error's text, so the lines start after a newline: each
+  field is then at the start of its own line, where a reader or a regex finds it.
+- **Text only** (§5.9). Every tool is registered with `structured_output=False`, so a result is never sent twice
+  (as text and again as `structuredContent`) and no tool advertises an output schema.
+- **Prefixed names** (§5.12). `compose` builds the server `primarysource mcp` runs, from one or more collections'
+  own servers, naming every tool and prompt `<collection>_<name>` (a name that already carries the prefix keeps
+  it). `bare=True` keeps each collection's own names, for the old single-collection commands. A name, resource
+  URI or HTTP route that two collections both want is refused at startup, never silently shadowed.
+
+This module imports only the standard library and the core at import time; `mcp` is imported when a server is
+built, so the core and every collection import without the `[mcp]` extra (§5.13).
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Awaitable, Callable, Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any, cast
+
+from primarysource.errors import LibError
+
+
+def tool_error(exc: LibError) -> Exception:
+    """The SDK `ToolError` for `exc`: the fixed error lines, each at the start of a line of the result text."""
+    from mcp.server.mcpserver.exceptions import ToolError
+
+    error: Exception = ToolError("\n" + exc.as_text())
+    return error
+
+
+def guard[F: Callable[..., Any]](fn: F) -> F:
+    """Wrap a tool so a `LibError` becomes `tool_error(exc)`. Sync and async tools both keep their signature,
+    which the SDK reads to build the input schema."""
+    if getattr(fn, "__primarysource_guarded__", False):
+        return fn
+    if inspect.iscoroutinefunction(fn):
+        async_fn = cast(Callable[..., Awaitable[Any]], fn)
+
+        @functools.wraps(fn)
+        async def guarded_async(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return await async_fn(*args, **kwargs)
+            except LibError as exc:
+                raise tool_error(exc) from None
+
+        wrapped: Any = guarded_async
+    else:
+
+        @functools.wraps(fn)
+        def guarded(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return fn(*args, **kwargs)
+            except LibError as exc:
+                raise tool_error(exc) from None
+
+        wrapped = guarded
+    wrapped.__primarysource_guarded__ = True
+    return cast(F, wrapped)
+
+
+def add_tools(server: Any, tools: Iterable[Callable[..., Any]], *, prefix: str = "", annotations: Any = None) -> None:
+    """Register `tools` on an `MCPServer` the way every collection must: guarded, text only, and named
+    `prefix + fn.__name__` unless the function's name already starts with `prefix`."""
+    for fn in tools:
+        name = fn.__name__ if fn.__name__.startswith(prefix) else prefix + fn.__name__
+        server.add_tool(guard(fn), name=name, annotations=annotations, structured_output=False)
+
+
+@dataclass(frozen=True, slots=True)
+class Served:
+    """One collection to serve: its registry name and title, and the `MCPServer` its own module built."""
+
+    name: str
+    title: str
+    server: Any
+
+
+def public_name(collection: str, name: str, *, bare: bool = False) -> str:
+    """The name `primarysource mcp` gives a collection's tool or prompt: `<collection>_<name>`, or `name` as it
+    is when it already starts with that prefix or when `bare` keeps the collection's own names."""
+    prefix = f"{collection}_"
+    return name if bare or name.startswith(prefix) else prefix + name
+
+
+def _clash(kind: str, key: str, first: str, second: str, bare: bool) -> LibError:
+    if first == second:
+        return LibError(f"collection {first!r} defines the {kind} {key!r} twice", "")
+    if bare:
+        hint = "drop --bare-names, which suits one collection only, or serve them from separate processes"
+    else:
+        hint = "serve them from separate processes, or rename one of them in its collection"
+    return LibError(f"the {kind} {key!r} is wanted by both {first!r} and {second!r}", hint)
+
+
+def _instructions(served: Sequence[Served], bare: bool) -> str:
+    if bare and len(served) == 1:
+        return str(served[0].server.instructions or "")
+    parts = []
+    for item in served:
+        text = str(item.server.instructions or "").strip()
+        head = f"[{item.name}] {item.title}." + ("" if bare else f" Tools are named {item.name}_<tool>.")
+        parts.append(f"{head} {text}" if text else head)
+    return "\n\n".join(parts)
+
+
+def compose(served: Sequence[Served], *, bare: bool = False) -> Any:
+    """One `MCPServer` serving every tool, prompt, resource and HTTP route of `served`, renamed by `public_name`.
+
+    Each tool is rebuilt from its function with `structured_output=False` and behind `guard`, so the contract
+    holds whatever the collection registered. Each collection keeps its own state (database, home directory,
+    loaded corpus): its functions are reused, not copied. A collection's completion handler is carried over: a
+    request for a renamed prompt reaches it under the prompt's own name, and one for a resource template reaches
+    the collection that owns the template. A clash raises `LibError` before anything runs.
+    """
+    if not served:
+        raise LibError("no collection to serve", "primarysource mcp --collection <name>")
+    from mcp.server.mcpserver import MCPServer
+    from mcp.server.mcpserver.tools import Tool
+
+    tools: dict[str, tuple[str, Any]] = {}
+    prompts: dict[str, tuple[str, Any]] = {}
+    prompt_names: dict[str, str] = {}  # public prompt name -> the name its collection gave it
+    completers: dict[str, Any] = {}  # collection -> its own `completion/complete` handler
+    resources: dict[str, tuple[str, Any]] = {}
+    templates: dict[str, tuple[str, Any]] = {}
+    routes: dict[str, tuple[str, Any]] = {}
+
+    def claim(table: dict[str, tuple[str, Any]], kind: str, key: str, owner: str, value: Any) -> None:
+        if key in table:
+            raise _clash(kind, key, table[key][0], owner, bare)
+        table[key] = (owner, value)
+
+    for item in served:
+        source = item.server
+        for tool in source._tool_manager.list_tools():
+            name = public_name(item.name, tool.name, bare=bare)
+            rebuilt = Tool.from_function(
+                guard(tool.fn),
+                name=name,
+                title=tool.title,
+                description=tool.description,
+                annotations=tool.annotations,
+                icons=tool.icons,
+                meta=tool.meta,
+                structured_output=False,
+            )
+            claim(tools, "tool", name, item.name, rebuilt)
+        for prompt in source._prompt_manager.list_prompts():
+            name = public_name(item.name, prompt.name, bare=bare)
+            claim(prompts, "prompt", name, item.name, prompt.model_copy(update={"name": name}))
+            prompt_names[name] = prompt.name
+        for resource in source._resource_manager.list_resources():
+            claim(resources, "resource", str(resource.uri), item.name, resource)
+        for template in source._resource_manager.list_templates():
+            claim(templates, "resource template", template.uri_template, item.name, template)
+        for route in source._custom_starlette_routes:
+            claim(routes, "HTTP route", f"{route.path} {sorted(route.methods or ())}", item.name, route)
+        entry = source._lowlevel_server.get_request_handler("completion/complete")
+        if entry is not None:
+            completers[item.name] = entry.handler
+
+    name = served[0].server.name if len(served) == 1 else "primarysource"
+    server = MCPServer(
+        name,
+        version=str(served[0].server.version or "") if len(served) == 1 else _version(),
+        instructions=_instructions(served, bare),
+        tools=[tool for _, tool in tools.values()],
+    )
+    for _, prompt in prompts.values():
+        server.add_prompt(prompt)
+    for _, resource in resources.values():
+        server.add_resource(resource)
+    for _, template in templates.values():
+        server._resource_manager._templates[template.uri_template] = template
+    server._custom_starlette_routes.extend(route for _, route in routes.values())
+    if completers:
+        _carry_completions(server, completers, prompts, prompt_names, templates)
+    return server
+
+
+def _carry_completions(
+    server: Any,
+    completers: dict[str, Any],
+    prompts: dict[str, tuple[str, Any]],
+    prompt_names: dict[str, str],
+    templates: dict[str, tuple[str, Any]],
+) -> None:
+    """Register one `completion/complete` handler on `server` that hands each request to the collection owning
+    the prompt or resource template it names, with the prompt's public name turned back into the collection's.
+    A request for something no collection completes gets no values, as the SDK answers when a handler returns
+    nothing."""
+    from mcp.types import CompleteRequestParams, CompleteResult, Completion, PromptReference
+
+    async def complete(ctx: Any, params: CompleteRequestParams) -> CompleteResult:
+        ref = params.ref
+        if isinstance(ref, PromptReference):
+            owner = prompts.get(ref.name, ("", None))[0]
+            if owner in completers:
+                original = ref.model_copy(update={"name": prompt_names[ref.name]})
+                params = params.model_copy(update={"ref": original})
+        else:
+            owner = templates.get(ref.uri, ("", None))[0]
+        handler = completers.get(owner)
+        if handler is None:
+            return CompleteResult(completion=Completion(values=[]))
+        result: CompleteResult = await handler(ctx, params)
+        return result
+
+    server._lowlevel_server.add_request_handler("completion/complete", CompleteRequestParams, complete)
+
+
+def _version() -> str:
+    from primarysource import __version__
+
+    return __version__

primarysource/serve.py

@@ -0,0 +1,75 @@
+"""Run an MCP server on stdio or as one shared HTTP server: the transport switch every collection uses.
+
+Lifted from rfclib's `rfclib mcp` (rfclib PR #1). stdio starts one server per client. http starts one long-lived
+server that every client reaches by URL (MCP streamable HTTP at `/mcp`), stateless and with JSON responses, so a
+restart loses no session. There is no authentication: the default bind is loopback, where the SDK checks the
+Host header itself. A non-loopback bind gets the same check only when allowed hosts are named; without them it
+warns, because anyone who can reach the port can use the server.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+from primarysource.errors import LibError
+
+MCP_HTTP_PORT = 8765
+LOOPBACK = ("127.0.0.1", "localhost", "::1")
+TRANSPORTS = {"stdio": "stdio", "http": "http", "streamable-http": "http", "streamable_http": "http"}
+
+
+def normalise_transport(transport: str) -> str:
+    """`stdio` or `http`; the SDK's own spellings of streamable HTTP are accepted."""
+    found = TRANSPORTS.get(transport.strip().lower())
+    if found is None:
+        raise LibError(f"unknown transport {transport!r}", "use --transport stdio or --transport http")
+    return found
+
+
+def transport_security(host: str, allowed_hosts: Sequence[str]) -> Any:
+    """The DNS-rebinding settings for a bind address: None on loopback (the SDK enables its own check there),
+    an allow-list when hosts are named, else None with a warning on stderr."""
+    if host in LOOPBACK:
+        return None
+    if not allowed_hosts:
+        print(
+            f"warning: listening on {host} with no authentication and no Host check; anyone who can reach the "
+            "port can use this server. Keep it behind a firewall or an authenticating reverse proxy.",
+            file=sys.stderr,
+        )
+        return None
+    from mcp.server.transport_security import TransportSecuritySettings
+
+    return TransportSecuritySettings(
+        enable_dns_rebinding_protection=True,
+        allowed_hosts=list(allowed_hosts),
+        allowed_origins=[f"{scheme}://{h}" for h in allowed_hosts for scheme in ("http", "https")],
+    )
+
+
+def run(
+    server: Any,
+    transport: str = "stdio",
+    host: str = "127.0.0.1",
+    port: int = MCP_HTTP_PORT,
+    allowed_hosts: Sequence[str] = (),
+) -> None:
+    """Serve `server` (an `mcp.server.mcpserver.MCPServer`) until interrupted."""
+    kind = normalise_transport(transport)
+    # stdout is the JSON-RPC channel on stdio; per-request client logs would flood stderr either way
+    for name in ("httpx", "httpcore", "huggingface_hub"):
+        logging.getLogger(name).setLevel(logging.WARNING)
+    if kind == "stdio":
+        server.run(transport="stdio")
+        return
+    server.run(
+        transport="streamable-http",
+        host=host,
+        port=port,
+        stateless_http=True,
+        json_response=True,
+        transport_security=transport_security(host, allowed_hosts),
+    )

primarysource/settings.py

@@ -0,0 +1,152 @@
+"""Per-collection settings read from the environment: the network mode and the read-only switch.
+
+Generalised from rfclib's `config.py` (`RFCLIB_NETWORK`, `RFCLIB_READONLY`, `require_network`). One process may
+serve several collections (PLAN.md §5.8), so each setting is looked up per collection, most specific first, the
+same way `home.collection_home` finds the home:
+
+1. `<LEGACY_APP>_<KEY>`, e.g. `RFCLIB_NETWORK`: a setting from before the move keeps working;
+2. `PRIMARYSOURCE_<COLLECTION>_<KEY>`, e.g. `PRIMARYSOURCE_NIST_NETWORK`: one collection of a shared process;
+3. `PRIMARYSOURCE_<KEY>`: every collection.
+
+The first variable that is set and not blank decides; a more specific `0` overrides a general `1`. A value that is
+not understood is an error naming the variable, never a silent fallback: `RFCLIB_NETWORK=ofline` must not fetch.
+
+Network modes:
+
+- `auto` (the default): fetch what is asked for, and refresh catalogues when they are stale;
+- `on-demand`: fetch only when a document is asked for;
+- `offline`: never touch the network; answer from what is stored.
+
+A read-only process (`<PREFIX>_READONLY=1`) must not write its library, so it is always offline: a fetch would
+have to be stored.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from primarysource.errors import LibError
+from primarysource.home import collection_home
+
+NETWORK_MODES = ("auto", "on-demand", "offline")
+DEFAULT_NETWORK = "auto"
+_TRUE = ("1", "true", "yes", "on")
+_FALSE = ("0", "false", "no", "off")
+
+
+class NetworkDisabled(LibError):
+    """A fetch was needed and the settings forbid it (offline, or read-only)."""
+
+
+def prefixes(collection: str | None = None, legacy_app: str | None = None) -> tuple[str, ...]:
+    """The variable prefixes consulted for `collection`, most specific first."""
+    found: list[str] = []
+    if legacy_app:
+        found.append(legacy_app.upper())
+    if collection:
+        found.append(f"PRIMARYSOURCE_{collection.upper()}")
+    found.append("PRIMARYSOURCE")
+    return tuple(found)
+
+
+def _lookup(key: str, names: tuple[str, ...], env: Mapping[str, str]) -> tuple[str, str] | None:
+    """(variable, value) of the first `<prefix>_<key>` that is set and not blank, or None."""
+    for prefix in names:
+        variable = f"{prefix}_{key}"
+        value = (env.get(variable) or "").strip()
+        if value:
+            return variable, value
+    return None
+
+
+@dataclass(frozen=True)
+class Settings:
+    """One collection's settings, read once from the environment by `settings()`."""
+
+    collection: str | None
+    home: Path | None
+    network: str
+    read_only: bool
+    network_variable: str
+    """The variable that set `network` (or forced it, for a read-only process), for messages."""
+    read_only_variable: str
+
+    def require_network(self, what: str) -> None:
+        """Return if `what` may be fetched now; raise `NetworkDisabled` naming the variable that forbids it."""
+        if self.read_only:
+            raise NetworkDisabled(
+                f"{what} is not stored here and this process is read-only ({self.read_only_variable})",
+                "ask the shared server that writes this library, or run the import without "
+                f"{self.read_only_variable}",
+            )
+        if self.network == "offline":
+            raise NetworkDisabled(
+                f"{what} is not stored here and {self.network_variable}=offline forbids fetching it",
+                f"run the import while online, or unset {self.network_variable}",
+            )
+
+
+def settings(
+    collection: str | None = None,
+    legacy_app: str | None = None,
+    environ: Mapping[str, str] | None = None,
+    platform: str | None = None,
+) -> Settings:
+    """Read `collection`'s settings. With no collection only the `PRIMARYSOURCE_*` variables apply and `home` is
+    None. Raises `LibError` for a value it does not understand."""
+    env = os.environ if environ is None else environ
+    names = prefixes(collection, legacy_app)
+
+    read_only, read_only_variable = False, f"{names[0]}_READONLY"
+    found = _lookup("READONLY", names, env)
+    if found:
+        read_only_variable, value = found
+        if value.lower() in _TRUE:
+            read_only = True
+        elif value.lower() not in _FALSE:
+            raise LibError(
+                f"{read_only_variable}={value!r} is not a yes or a no", f"set {read_only_variable} to 1 or 0"
+            )
+
+    network, network_variable = DEFAULT_NETWORK, f"{names[0]}_NETWORK"
+    found = _lookup("NETWORK", names, env)
+    if found:
+        network_variable, value = found
+        network = value.lower()
+        if network not in NETWORK_MODES:
+            raise LibError(
+                f"{network_variable}={value!r} is not a network mode",
+                f"set {network_variable} to one of {', '.join(NETWORK_MODES)}",
+            )
+    if read_only:
+        network, network_variable = "offline", read_only_variable
+
+    home = collection_home(collection, legacy_app, env, platform) if collection else None
+    return Settings(collection, home, network, read_only, network_variable, read_only_variable)
+
+
+def network_mode(
+    collection: str | None = None, legacy_app: str | None = None, environ: Mapping[str, str] | None = None
+) -> str:
+    """`auto`, `on-demand` or `offline` for `collection`; always `offline` when it is read-only."""
+    return settings(collection, legacy_app, environ).network
+
+
+def read_only(
+    collection: str | None = None, legacy_app: str | None = None, environ: Mapping[str, str] | None = None
+) -> bool:
+    """True when `collection` must not write its library."""
+    return settings(collection, legacy_app, environ).read_only
+
+
+def require_network(
+    what: str,
+    collection: str | None = None,
+    legacy_app: str | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> None:
+    """Raise `NetworkDisabled` unless `collection` may fetch `what` now. Read at each call, not cached."""
+    settings(collection, legacy_app, environ).require_network(what)

primarysource/usb/__init__.py

@@ -0,0 +1,5 @@
+"""USB-IF specifications: corpus index, search, and citation."""
+
+from primarysource.usb.models import Document, Section
+
+__all__ = ["Document", "Section"]

primarysource/usb/collection.py

@@ -0,0 +1,37 @@
+"""USB-IF specifications as a primarysource collection. Importing this needs nothing beyond the core."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from primarysource.model import Unit
+from primarysource.pdfcorpus.tools import GRAMMAR
+from primarysource.registry import Collection
+
+# The server registers the bare names (search, read, outline, info, cite); `primarysource mcp` serves them as
+# usb_search, ... and `--bare-names` keeps usblib's names. Refs: `<doc_id>§<section>` and `<doc_id>:<first>-<last>`.
+COLLECTION = Collection(
+    name="usb",
+    title="USB-IF specifications (CCID and others), fetched by the user",
+    prefix="usb_",
+    unit=Unit.BLOCK,
+    grammar=GRAMMAR,
+    server="primarysource.usb.server.mcp:mcp",
+    cli="primarysource.usb.collection:main",
+)
+
+
+def main(argv: Sequence[str]) -> int:
+    """`primarysource usb fetch ...` (download, extract and index the specifications in sources.toml) and
+    `primarysource usb index` (rebuild the search index from the fetched corpus)."""
+    if argv and argv[0] == "index":
+        from primarysource.pdfcorpus import fts
+        from primarysource.usb.spec import SPEC
+
+        return fts.main(SPEC, argv[1:])
+    if not argv or argv[0] != "fetch":
+        print("usage: primarysource usb {fetch,index} [args]", flush=True)
+        return 2
+    from primarysource.usb.ingest import fetch
+
+    return int(fetch.main(list(argv[1:])))