primarysource 0.1.0__py3-none-any.whl

primarysource/cve/views.py

@@ -0,0 +1,304 @@
+"""Text views of `service`'s answers: what a tool or a command prints (PLAN.md §5.9).
+
+`service` returns plain dicts, which is what `--json` prints. These functions turn the same dicts into `render()`
+text: the answer as lines, then the fixed footer. What a dict carries as a field either stays a line of the body
+(`kev:`, `epss:`, the verdict) or becomes a footer line:
+
+- `cite:` the sources that supplied the answer, as `service` names them;
+- `unit:` is `block` when the lines are the numbered items of a list section (a reference, an affected entry, a
+  kernel range): each carries its own ref, `CVE-Y-N§references¶9`, and `¶n` on a read means "from item n on";
+- `next:` a ref string for a read (`CVE-Y-N§references¶9`, what `cve_read` takes back as `ref`), `start=<n>` for a
+  list (`render.next_start`);
+- `relaxed:` the search matched only some of its terms;
+- `partial:` every source that is missing, failed or stale, because an absence means less when one is (a CVE
+  "not in KEV" is a different fact from a KEV catalog that was never synced);
+- `warning:` a hedge the reader must not drop: a truncated description, a version string with a distribution
+  suffix.
+
+Record text (titles, descriptions, references, KEV notes) is data from other people. It is printed as it came and
+never interpreted; the server instructions say so.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from primarysource.render import next_start, render
+
+PARTIAL_JOIN = " | "
+
+
+def _footer(payload: Mapping[str, Any], **fixed: str) -> dict[str, str]:
+    """The footer lines `payload` implies, plus `fixed` ones. A multi-line value is cut to one line."""
+    footer = {key: " ".join(str(value).split()) for key, value in fixed.items() if value}
+    gaps = payload.get("partial")
+    if gaps:
+        footer["partial"] = PARTIAL_JOIN.join(" ".join(str(gap).split()) for gap in gaps)
+    return footer
+
+
+def _next(payload: Mapping[str, Any]) -> str:
+    """A read's `next` is already a ref; a list's is `{"start": n}`."""
+    value = payload.get("next")
+    if isinstance(value, Mapping):
+        return next_start(int(value["start"]))
+    return str(value) if value else ""
+
+
+def _score(metric: Mapping[str, Any] | None) -> str:
+    if not metric:
+        return "none"
+    severity = f" {metric['severity']}" if metric.get("severity") else ""
+    return f"{metric['score']}{severity} (CVSS {metric['version']}, {metric['label']})"
+
+
+def _json_line(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def _kev_line(kev: Mapping[str, Any]) -> str:
+    if kev["status"] == "listed":
+        return (
+            f"listed, added {kev['date_added']}, due {kev['due_date']}, ransomware use {kev['ransomware']}; "
+            f"action: {kev['action']}"
+        )
+    if kev["status"] == "not_listed":
+        return f"not listed ({kev['source']})"
+    return f"unknown: {kev.get('why', 'not consulted')}"
+
+
+def _epss_line(epss: Mapping[str, Any]) -> str:
+    return f"{epss['score']} (percentile {epss['percentile']}) {epss['source']}"
+
+
+def _fixed_in(fixed: Mapping[str, str]) -> str:
+    return ", ".join(f"{branch} -> {fix}" for branch, fix in fixed.items()) or "none recorded"
+
+
+# --- info ----------------------------------------------------------------------------------------------------
+
+
+def info(payload: Mapping[str, Any]) -> str:
+    if payload.get("status") == "not_synced":
+        body = f"home: {payload['home']}\nindex: not synced yet"
+        return render(body, {"warning": f"{payload['error']}; {payload['hint']}; run: {payload['action']}"})
+    if "counts" not in payload:
+        lines = [f"{payload['ref']}  {payload['state']}  {payload['title']}"]
+        lines.append(f"cvss: {_score(payload['cvss'])}")
+        lines.append(f"kev: {payload['kev']}")
+        if payload.get("epss"):
+            lines.append(f"epss: {_epss_line(payload['epss'])}")
+        lines.append(f"kernel CNA data: {'yes' if payload['kernel_cna'] else 'no'}")
+        return render("\n".join(lines), _footer(payload, next=str(payload["next"])))
+    lines = [f"home: {payload['home']}", f"index: {payload['index']} ({payload['index_mb']} MB)"]
+    lines += [f"{name}: {count}" for name, count in payload["counts"].items()]
+    lines.append("sources:")
+    for name, row in payload["sources"].items():
+        lines.append(
+            f"  {name}  {row['state']}  version {row['version'] or '-'}  upstream {row['upstream_date'] or '-'}  "
+            f"synced {row['synced_at'] or '-'}  records {row['records'] if row['records'] is not None else '-'}"
+            + (f"  detail: {row['detail']}" if row["detail"] else "")
+        )
+    return render("\n".join(lines), _footer(payload))
+
+
+# --- search --------------------------------------------------------------------------------------------------
+
+
+def search(payload: Mapping[str, Any]) -> str:
+    lines: list[str] = []
+    for hit in payload["hits"]:
+        flags = "".join(
+            [
+                f" cvss={hit['cvss']}" if "cvss" in hit else "",
+                " KEV" if hit.get("kev") else "",
+                f" epss={hit['epss']:.3f}" if "epss" in hit else "",
+            ]
+        )
+        lines.append(f"{hit['ref']}  [{hit['source']}]{flags}  {hit['title']}")
+        if hit.get("snippet"):
+            lines.append(f"    {' '.join(str(hit['snippet']).split())}")
+    body = "\n".join(lines) or f"no CVE record matches {payload['query']!r}"
+    relaxed = "no record holds every term; these hold some of them" if payload.get("relaxed") and lines else ""
+    return render(body, _footer(payload, next=_next(payload), relaxed=relaxed))
+
+
+# --- read ----------------------------------------------------------------------------------------------------
+
+
+def _items(payload: Mapping[str, Any], label: str, lines: list[str]) -> list[str]:
+    """The numbered items of a list section, each with its own ref so it can be cited."""
+    section = str(payload["ref"])
+    head = f"{section}: items {payload['start']}-{payload['start'] + len(payload['items']) - 1} of {payload['total']}"
+    if not payload["items"]:
+        head = f"{section}: no {label}"
+    numbered = [f"{section}¶{payload['start'] + offset}  {item}" for offset, item in enumerate(payload["items"])]
+    return [head, *lines, *numbered]
+
+
+def _affected_line(entry: Any) -> str:
+    if not isinstance(entry, Mapping):
+        return str(entry)
+    head = f"{entry.get('vendor', '')} {entry.get('product', '')}".strip()
+    ranges: list[str] = []
+    for version in entry.get("versions") or []:
+        if not isinstance(version, Mapping):
+            continue
+        bits = [str(version.get("status", "")), str(version.get("version", ""))]
+        bits += [f"{key} {version[key]}" for key in ("lessThan", "lessThanOrEqual") if version.get(key)]
+        ranges.append(" ".join(bit for bit in bits if bit))
+    if ranges:
+        return f"{head}: {'; '.join(ranges)}"
+    return head or _json_line(entry)
+
+
+def read(payload: Mapping[str, Any]) -> str:
+    ref = str(payload["ref"])
+    if payload.get("state") == "UNKNOWN_TO_CVE_SOURCES":
+        lines = [f"{ref}  {payload['note']}", f"kev: {_kev_line(payload['kev'])}"]
+        if payload.get("epss"):
+            lines.append(f"epss: {_epss_line(payload['epss'])}")
+        return render("\n".join(lines), _footer(payload))
+    cite = str(payload.get("cite", ""))
+    if "§" in ref:
+        section = ref.split("§", 1)[1]
+        if section == "references":
+            body = "\n".join(_items(payload, "references", []))
+            return render(body, _footer(payload, cite=cite, unit="block", next=_next(payload)))
+        if section == "affected":
+            lines = _items(
+                {**payload, "items": [_affected_line(i) for i in payload["items"]]}, "affected entries", []
+            )
+            return render("\n".join(lines), _footer(payload, cite=cite, unit="block", next=_next(payload)))
+        if section == "cvss":
+            lines = [f"{ref}  preferred: {_score(payload['preferred'])}"]
+            for metric in payload["items"]:
+                lines.append(f"{metric['label']}  {metric['version']}  {_score(metric)}  {metric['vector']}")
+            if not payload["items"]:
+                lines.append("no CVSS score in any synced source")
+            return render("\n".join(lines), _footer(payload, cite=cite))
+        if section == "kernel":
+            if "items" not in payload:
+                return render(f"{ref}  {payload['note']}", _footer(payload, cite=cite))
+            lines = [
+                f"fixed in: {_fixed_in(payload['fixed_in'])}",
+                f"unfixed on start: {', '.join(payload['unfixed_on_start']) or 'none'}",
+                f"source: {payload['source']}",
+            ]
+            body = "\n".join(_items(payload, "kernel ranges", lines))
+            return render(body, _footer(payload, cite=cite, unit="block", next=_next(payload)))
+        lines = [f"{ref}"]
+        for name, row in payload["sources"].items():
+            lines.append(
+                f"{name}  {row['state']}  version {row['version'] or '-'}  upstream {row['upstream_date'] or '-'}  "
+                f"synced {row['synced_at'] or '-'}"
+            )
+        return render("\n".join(lines), _footer(payload, cite=cite))
+    return _summary(payload)
+
+
+def _summary(payload: Mapping[str, Any]) -> str:
+    lines = [f"{payload['ref']}  {payload['state']}"]
+    if payload["title"]:
+        lines.append(f"title: {payload['title']}")
+    lines.append(
+        f"assigner: {payload['assigner'] or '-'}  published: {payload['published']}  updated: {payload['updated']}"
+    )
+    lines.append(f"cwe: {', '.join(payload['cwe']) or '-'}")
+    lines.append(
+        f"cvss: {_score(payload['cvss']['preferred'])}; {payload['cvss']['count']} score(s) in {payload['ref']}§cvss"
+    )
+    lines.append(f"kev: {_kev_line(payload['kev'])}")
+    if payload.get("epss"):
+        lines.append(f"epss: {_epss_line(payload['epss'])}")
+    if payload.get("ssvc"):
+        lines.append("ssvc: " + ", ".join(f"{key}={value}" for key, value in payload["ssvc"].items()))
+    kernel = payload.get("kernel")
+    if kernel:
+        lines.append(f"kernel: {kernel['source']}; fixed in {_fixed_in(kernel['fixed_in'])}")
+        if kernel["unfixed_on_start"]:
+            lines.append(f"kernel unfixed on start: {', '.join(kernel['unfixed_on_start'])}")
+        if kernel["files"]:
+            more = kernel["files_total"] - len(kernel["files"])
+            lines.append(f"kernel files: {' '.join(kernel['files'])}" + (f" (+{more} more)" if more > 0 else ""))
+        lines.append(f"kernel question: cve_kernel('{payload['ref']}', '<version>')")
+    lines.append(f"description ({payload['description_source']}):")
+    lines.append(str(payload["description"]))
+    lines.append(f"references ({len(payload['references'])} of {payload['references_total']}):")
+    lines += [f"  {url}" for url in payload["references"]]
+    lines.append("sections: " + ", ".join(payload["sections"]))
+    warning = "description and references cut to fit max_tokens; raise max_tokens" if payload.get("truncated") else ""
+    return render("\n".join(lines), _footer(payload, cite=str(payload["cite"]), next=_next(payload), warning=warning))
+
+
+# --- kev -----------------------------------------------------------------------------------------------------
+
+
+def kev(payload: Mapping[str, Any]) -> str:
+    if "status" in payload:
+        if payload["status"] == "not_listed":
+            body = f"{payload['ref']} is not in the CISA KEV catalog"
+            return render(body, _footer(payload, cite=str(payload["source"])))
+        lines = [
+            f"{payload['ref']}  listed in CISA KEV",
+            f"vendor: {payload['vendor']}  product: {payload['product']}",
+            f"name: {payload['name']}",
+            f"added: {payload['date_added']}  due: {payload['due_date']}  ransomware use: {payload['ransomware']}",
+            f"action: {payload['action']}",
+            f"description: {payload['description']}",
+        ]
+        if payload.get("notes"):
+            lines.append(f"notes: {payload['notes']}")
+        if payload.get("cwes"):
+            lines.append(f"cwe: {', '.join(payload['cwes'])}")
+        if payload.get("forensic_triage"):
+            lines.append(f"forensic triage: {payload['forensic_triage']}")
+        return render("\n".join(lines), _footer(payload, cite=str(payload["source"])))
+    lines = [f"{payload['total']} KEV entries, newest first"]
+    lines += [
+        f"{row['cve']}  added {row['date_added']}  due {row['due_date']}  {row['vendor']}/{row['product']}  "
+        f"{row['name']}" + (f"  ransomware: {row['ransomware']}" if row["ransomware"] else "")
+        for row in payload["items"]
+    ]
+    return render("\n".join(lines), _footer(payload, cite=str(payload["source"]), next=_next(payload)))
+
+
+# --- kernel --------------------------------------------------------------------------------------------------
+
+
+def _caveats(payload: Mapping[str, Any]) -> str:
+    return PARTIAL_JOIN.join(payload.get("caveats", []))
+
+
+def kernel_check(payload: Mapping[str, Any]) -> str:
+    confidence = f"  (confidence: {payload['confidence']})" if payload.get("confidence") else ""
+    lines = [f"{payload['ref']} on kernel {payload['version']}: {payload['verdict']}{confidence}"]
+    if payload.get("reason"):
+        lines.append(f"reason: {payload['reason']}")
+    if payload.get("detail"):
+        lines.append(f"detail: {payload['detail']}")
+    lines += [f"evidence: {item}" for item in payload.get("evidence", [])]
+    if payload.get("fixed_in"):
+        lines.append(f"fixed in: {_fixed_in(payload['fixed_in'])}")
+    if payload.get("note"):
+        lines.append(f"note: {payload['note']}")
+    return render("\n".join(lines), _footer(payload, cite=str(payload.get("source", "")), warning=_caveats(payload)))
+
+
+def kernel_list(payload: Mapping[str, Any]) -> str:
+    lines = [f"{payload['version']}: {payload['affected_total']} of {payload['assessed']} kernel CNA CVEs affect it"]
+    for item in payload["items"]:
+        marks = "".join([" KEV" if item.get("kev") else "", f" epss={item['epss']:.3f}" if "epss" in item else ""])
+        files = f"  files: {' '.join(item['files'])}" if item.get("files") else ""
+        lines.append(f"{item['ref']}{marks}  {item['title']}  ({item['why']}){files}")
+    lines.append(f"note: {payload['note']}")
+    return render(
+        "\n".join(lines),
+        _footer(payload, cite=str(payload["source"]), next=_next(payload), warning=_caveats(payload)),
+    )
+
+
+def path(home: str, index: str) -> str:
+    return render(f"home: {home}\nindex: {index}\nsetting: CVELIB_HOME or PRIMARYSOURCE_CVE_HOME", {})

primarysource/debpolicy/__init__.py

@@ -0,0 +1,16 @@
+"""`debpolicy`: Debian Policy and the dpkg manual pages, pinned releases, read as reStructuredText and POD.
+Served under `debpolicy_`.
+
+Stdlib only. `mcp` is imported by `server.py` when a server is built; `primarysource debpolicy ...` runs `cli.py`.
+`docs/debpolicy.md` is the description; `catalogue.py` holds the pin, the licence and the build.
+"""
+
+from __future__ import annotations
+
+from primarysource.debpolicy.catalogue import SPEC
+from primarysource.pkgdocs.runtime import make_collection
+
+COLLECTION = make_collection(SPEC, "primarysource.debpolicy")
+"""Refs: `debpolicy:5.6.1`; see `pkgdocs.runtime`."""
+
+__all__ = ["COLLECTION", "SPEC"]

primarysource/debpolicy/catalogue.py

@@ -0,0 +1,263 @@
+"""The `debpolicy` collection: Debian Policy (reStructuredText) and the dpkg manual pages (POD).
+
+Two pinned trees, so two editions that move independently:
+
+- `policy`: dbnpolicy/policy on salsa.debian.org at the commit of the tag `debian/4.7.4.1`. The documents are
+  `policy/*.rst` (chapters `ch-*`, appendices `ap-*`, `upgrading-checklist`, `index`) and `autopkgtest.md`;
+- `dpkg`: dpkg-team/dpkg at the tag `1.23.12`. The documents are the 63 `man/*.pod` pages, with their manual
+  section taken from `man/Makefile.am` (`man_MANS`). In 1.23.12 the pages are POD, not roff; roff appears only
+  after `pod2man`.
+
+Licence (read from the repositories on 2026-11-13, see `docs/debpolicy.md`): the policy tree's `debian/copyright`
+(DEP-5) gives `Files: *` as GPL-2+ and names the exceptions (`copyright-format*.xml`, `debconf*`, `fhs-3.0*` and
+some diagrams), none of which is imported; the build reads that file and puts the matching `License:` of each
+imported document in its meta. Each dpkg page carries its own header, "either version 2 of the License, or (at
+your option) any later version", which the POD build reads the same way. Placement is **layer**.
+
+Numbering: a chapter's number is its place in the first `toctree` of `index.rst`, so `ch-controlfields` is
+chapter 5 and its subsections are `5.1`, `5.6.1`. `debpolicy:5.6.1` works without a document id for that
+reason. Appendices are numbered locally inside their own document (the build does not claim Sphinx's appendix
+numbering, which was not checked).
+"""
+
+from __future__ import annotations
+
+import fnmatch
+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._common import decode
+from primarysource.pkgdocs.readers.markdown import read_markdown
+from primarysource.pkgdocs.readers.pod import read_pod
+from primarysource.pkgdocs.readers.rst import read_rst
+from primarysource.pkgdocs.runtime import Build, Licence, Pin, Spec, TreeSpec, matching
+
+POLICY_COMMIT = "aceb1daf7305adc0b336ee2ebbdf0bc0340d3b68"
+DPKG_COMMIT = "f78cedcdcbbf25b27f3104b99ac3d2832e19d0cc"
+
+POLICY_PIN = Pin(
+    commit=POLICY_COMMIT,
+    label="4.7.4.1",
+    date="2026-03-31",
+    files_sha256="bcf7ce3c75512efe7274fedf88a8c615483e50872c9fd644c678a816f8b3319b",
+    sources=(
+        Source(
+            f"https://salsa.debian.org/dbnpolicy/policy/-/archive/{POLICY_COMMIT}/policy-{POLICY_COMMIT}.tar.gz",
+            strip=1,
+        ),
+    ),
+)
+DPKG_PIN = Pin(
+    commit=DPKG_COMMIT,
+    label="1.23.12",
+    date="2026-11-13",
+    files_sha256="22d4c9ed26c64e136510ae6d7f002b7afb309613223bc88ef025413b8b47e610",
+    sources=(
+        Source(f"https://salsa.debian.org/dpkg-team/dpkg/-/archive/{DPKG_COMMIT}/dpkg-{DPKG_COMMIT}.tar.gz", strip=1),
+        Source(
+            f"https://github.com/guillemj/dpkg/archive/{DPKG_COMMIT}.tar.gz",
+            strip=1,
+            hosts=("codeload.github.com",),
+        ),
+    ),
+)
+
+LICENCE = Licence(
+    spdx="GPL-2.0-or-later",
+    redistribute="layer",
+    attribution="Debian Policy: Ian Jackson, Christian Schwarz and many other Debian contributors; "
+    "dpkg: Guillem Jover and others",
+    evidence="debian/copyright (`Files: *`, License: GPL-2+) in the policy tree; the header of each dpkg .pod",
+)
+
+_GPL2_PLUS = "GPL-2.0-or-later"
+_MAN_MANS = re.compile(r"man_MANS\s*\+?=\s*((?:[^\n]*\\\n)*[^\n]*)")
+_PAGE = re.compile(r"([\w.+-]+)\.(\d)")
+
+
+def _copyright_stanzas(text: str) -> list[tuple[list[str], str]]:
+    """(file patterns, licence short name) for each DEP-5 `Files:` stanza of a `debian/copyright`."""
+    stanzas: list[tuple[list[str], str]] = []
+    for block in re.split(r"\n\s*\n", text):
+        files: list[str] = []
+        licence = ""
+        in_files = False
+        for line in block.split("\n"):
+            if line.startswith("Files:"):
+                in_files = True
+                files.extend(line[len("Files:") :].split())
+            elif in_files and line[:1] in (" ", "\t"):
+                files.extend(line.split())
+            else:
+                in_files = False
+                if line.startswith("License:"):
+                    licence = line[len("License:") :].strip()
+        if files and licence:
+            stanzas.append((files, licence))
+    return stanzas
+
+
+def licence_of(path: str, stanzas: list[tuple[list[str], str]]) -> str:
+    """The licence DEP-5 gives `path`: the last `Files:` stanza that matches it (`*` also matches `/`)."""
+    found = ""
+    for patterns, licence in stanzas:
+        if any(fnmatch.fnmatchcase(path, pattern) for pattern in patterns):
+            found = licence
+    return found
+
+
+def _chapter_order(index: bytes | None) -> list[str]:
+    """Document stems in the first `toctree` of `index.rst`, in order."""
+    if index is None:
+        return []
+    stems: list[str] = []
+    in_tree = False
+    for line in decode(index, "policy/index.rst").split("\n"):
+        if line.startswith(".. toctree::"):
+            if stems:
+                break
+            in_tree = True
+        elif in_tree and line.strip() and line.startswith(("   ", "\t")) and not line.strip().startswith(":"):
+            stems.append(line.strip())
+        elif in_tree and line.strip() and not line.startswith((" ", "\t")):
+            break
+    return stems
+
+
+def build_policy(files: Mapping[str, bytes], pin: Pin) -> Build:
+    stanzas = (
+        _copyright_stanzas(decode(files["debian/copyright"], "debian/copyright"))
+        if "debian/copyright" in files
+        else []
+    )
+    order = _chapter_order(files.get("policy/index.rst"))
+    docs: list[Doc] = []
+    aliases: dict[str, str] = {}
+    skipped: Counter[str] = Counter()
+    if not stanzas:
+        skipped["debian/copyright not found or has no Files stanza: licences unchecked"] += 1
+    for path in sorted(files):
+        if path == "debian/copyright":
+            continue
+        stem = path.rsplit("/", 1)[-1].rsplit(".", 1)[0]
+        try:
+            if path.startswith("policy/") and path.endswith(".rst"):
+                number = str(order.index(stem) + 1) if stem.startswith("ch-") and stem in order else ""
+                doc = read_rst(files[path], stem, base=number)
+                if number:
+                    aliases[number] = stem
+                    doc = Doc(
+                        doc.id,
+                        f"Debian Policy {pin.label} chapter {number}: {doc.title}",
+                        doc.unit,
+                        doc.sections,
+                        doc.meta,
+                        doc.warnings,
+                    )
+                elif stem != "index":
+                    doc = Doc(
+                        doc.id,
+                        f"Debian Policy {pin.label}: {doc.title}",
+                        doc.unit,
+                        doc.sections,
+                        doc.meta,
+                        doc.warnings,
+                    )
+            elif path.endswith(".md"):
+                doc = read_markdown(files[path], stem)
+            else:
+                skipped["not a policy document"] += 1
+                continue
+        except LibError:
+            skipped["not UTF-8 text"] += 1
+            continue
+        found = licence_of(path, stanzas)
+        docs.append(doc.with_meta(path=path, licence=_GPL2_PLUS if found == "GPL-2+" else (found or "unchecked")))
+    return Build(tuple(docs), aliases, skipped)
+
+
+def man_sections(makefile: bytes | None) -> dict[str, str]:
+    """`{page: section}` from the `man_MANS` lists of `man/Makefile.am` (`deb-control.5` -> `deb-control: 5`)."""
+    if makefile is None:
+        return {}
+    sections: dict[str, str] = {}
+    for match in _MAN_MANS.finditer(decode(makefile, "man/Makefile.am")):
+        for token in match.group(1).replace("\\\n", " ").split():
+            found = _PAGE.fullmatch(token)
+            if found:
+                sections[found.group(1)] = found.group(2)
+    return sections
+
+
+def build_dpkg(files: Mapping[str, bytes], pin: Pin) -> Build:
+    sections = man_sections(files.get("man/Makefile.am"))
+    docs: list[Doc] = []
+    aliases: dict[str, str] = {}
+    skipped: Counter[str] = Counter()
+    for path in sorted(files):
+        if not (path.startswith("man/") and path.endswith(".pod")):
+            continue
+        page = path[len("man/") : -len(".pod")]
+        try:
+            doc = read_pod(files[path], page)
+        except LibError:
+            skipped["not UTF-8 text"] += 1
+            continue
+        number = sections.get(page, "")
+        if not number:
+            skipped["page not listed in man_MANS: no manual section"] += 1
+        _, _, description = doc.title.partition(" - ")
+        title = f"{page}({number})" + (f" - {description}" if description else "") if number else doc.title
+        text = decode(files[path], path)
+        licence = (
+            _GPL2_PLUS
+            if "either version 2 of the License, or" in text and "any later version" in text
+            else "see file"
+        )
+        doc = Doc(doc.id, title, doc.unit, doc.sections, doc.meta, doc.warnings)
+        docs.append(doc.with_meta(path=path, licence=licence, man_section=number))
+        if number:
+            aliases[f"{page}.{number}"] = page
+    return Build(tuple(docs), aliases, skipped)
+
+
+SPEC = Spec(
+    name="debpolicy",
+    title="Debian Policy and the dpkg manual pages",
+    licence=LICENCE,
+    trees=(
+        TreeSpec(
+            name="policy",
+            title="Debian Policy Manual (policy/*.rst, autopkgtest.md)",
+            pins=(POLICY_PIN,),
+            include=matching(r"policy/[a-z0-9-]+\.rst|autopkgtest\.md|debian/copyright"),
+            build=build_policy,
+        ),
+        TreeSpec(
+            name="dpkg",
+            title="dpkg manual pages (man/*.pod)",
+            pins=(DPKG_PIN,),
+            include=matching(r"man/[A-Za-z0-9.+-]+\.pod|man/Makefile\.am"),
+            build=build_dpkg,
+        ),
+    ),
+    instructions=(
+        "Debian Policy (chapters 1-12 and the appendices) and the dpkg manual pages (deb(5), deb-control(5), "
+        "dpkg-deb(1), ...) from the user's imported copies at pinned releases. Loop: debpolicy_search('<words>') -> "
+        "debpolicy_outline('<doc>') -> debpolicy_read('<ref>'). Policy section numbers work as refs: '5.6.1' is "
+        "the Source field of chapter 5 (ch-controlfields); chapters are the documents ch-* and appendices ap-*. "
+        "A dpkg page's document id is its name ('deb-control'); 'deb-control.5' works too. A section is an id, an "
+        "anchor (Policy's s-f-Source), a heading or a unique part of one. If nothing is imported the error says "
+        "how."
+    ),
+    example_refs=(
+        "debpolicy:5.6.1",
+        "debpolicy:ch-controlfields§s-f-Source",
+        "debpolicy:deb-control§DESCRIPTION",
+        "debpolicy:5.6.1@aceb1daf¶2",
+    ),
+)

primarysource/debpolicy/cli.py

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

primarysource/debpolicy/server.py

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

primarysource/draft/__init__.py

@@ -0,0 +1,11 @@
+"""IETF Internet-Drafts as a primarysource collection: `primarysource mcp --collection draft`.
+
+The portfolio tracks documents that exist only as drafts (RTR version 2 and the ASPA PDU, ASPA verification,
+LibrePGP, the TURN REST API), which the RFC library cannot cite. This collection imports named drafts from the
+IETF's own servers into `$PRIMARYSOURCE_HOME/draft/` and serves them like the `rfc` collection does, with one
+difference that matters: a draft has revisions and a life cycle, so every result says which revision it read and
+whether that draft is still alive.
+
+`docs/draft.md` is the user-facing description. Nothing here needs a dependency beyond the standard library;
+serving needs the `[mcp]` extra. `primarysource draft ...` runs `cli.py`.
+"""