primarysource 0.1.0__py3-none-any.whl

primarysource/rfc/packs/builder.py

@@ -0,0 +1,228 @@
+"""Build .rfcpack zips from collections.
+
+Pack format v1 (mirrors caionline's .caipack: one root folder, one marker
+file, verified manifest):
+
+    <pack-id>/
+      pack.json        manifest: metadata, per-doc files w/ sha256+size
+      search.sqlite    optional: docs + chunks + FTS5 index over txt bodies
+      docs/RFC9000.txt document files, one per fmt registered in pack.json
+
+The Android reader verifies every file against sha256 on install and refuses
+tampered/corrupt packs; catalog.json (see serve.py) carries pack-level sha256
+for download verification. Everything is stdlib (zipfile, sqlite3, hashlib).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..index.chunker import split_sections
+from ..sync.state import file_path
+from .collections import Collection, resolve, sort_key
+
+PACK_MARKER = "pack.json"
+PACK_SUFFIX = ".rfcpack"
+FORMAT_VERSION = 1
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for blk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(blk)
+    return h.hexdigest()
+
+
+class MissingFiles(Exception):
+    def __init__(self, missing: list[str]):
+        self.missing = missing
+        head = ", ".join(missing[:10])
+        super().__init__(
+            f"{len(missing)} docs have no local file "
+            f"(run `rfclib sync` first): {head}"
+            + (" ..." if len(missing) > 10 else ""))
+
+
+def resolve_files(conn, doc_ids: list[str],
+                  formats: list[str]) -> dict[str, dict[str, Path]]:
+    """{doc_id: {fmt: local path}}; raises MissingFiles listing gaps."""
+    out: dict[str, dict[str, Path]] = {}
+    missing: list[str] = []
+    for doc_id in doc_ids:
+        per: dict[str, Path] = {}
+        for fmt in formats:
+            row = conn.execute(
+                "SELECT path FROM files WHERE doc_id=? AND fmt=?",
+                (doc_id, fmt)).fetchone()
+            path = file_path(conn, row[0]) if row else None
+            if path is None or not path.is_file():
+                missing.append(f"{doc_id}.{fmt}")
+            else:
+                per[fmt] = path
+        if per:
+            out[doc_id] = per
+    if missing:
+        raise MissingFiles(missing)
+    return out
+
+
+def _docs_meta(conn, doc_ids: list[str],
+               files: dict[str, dict[str, Path]]) -> list[dict]:
+    docs = []
+    for doc_id in doc_ids:
+        row = conn.execute(
+            """SELECT doc_id, series, title, status, pub_date, is_current,
+                      stream, wg FROM docs WHERE doc_id=?""", (doc_id,)).fetchone()
+        if row is None:
+            continue
+        docs.append({
+            "doc_id": row["doc_id"], "series": row["series"],
+            "title": row["title"] or "", "status": row["status"] or "",
+            "pub_date": row["pub_date"] or "", "current": bool(row["is_current"]),
+            "stream": row["stream"] or "", "wg": row["wg"] or "",
+            "formats": sorted(files[doc_id]),
+        })
+    return docs
+
+
+SEARCH_SCHEMA = """
+CREATE TABLE docs(
+  doc_id TEXT PRIMARY KEY, series TEXT, title TEXT, status TEXT,
+  pub_date TEXT, is_current INTEGER, stream TEXT, wg TEXT);
+CREATE TABLE chunks(
+  id INTEGER PRIMARY KEY, doc_id TEXT NOT NULL,
+  sec_num TEXT NOT NULL, sec_title TEXT NOT NULL,
+  start_line INTEGER NOT NULL, end_line INT NOT NULL, body TEXT NOT NULL,
+  sec TEXT GENERATED ALWAYS AS (trim(sec_num || ' ' || sec_title)) STORED);
+CREATE INDEX idx_chunks_doc ON chunks(doc_id);
+CREATE VIRTUAL TABLE chunks_fts USING fts5(
+  sec, body, content='chunks', content_rowid='id',
+  tokenize='porter unicode61 remove_diacritics 2');
+"""
+
+
+def build_search_db(doc_ids: list[str], txt_files: dict[str, Path],
+                    out_path: Path) -> int:
+    """Offline FTS5 index the app can open with android.database.sqlite."""
+    if out_path.exists():
+        out_path.unlink()
+    conn = sqlite3.connect(out_path)
+    try:
+        conn.executescript(SEARCH_SCHEMA)
+        n_chunks = 0
+        for doc_id in doc_ids:
+            path = txt_files.get(doc_id)
+            if path is None:
+                continue
+            text = path.read_text("utf-8", errors="replace")
+            for sec in split_sections(text):
+                conn.execute(
+                    "INSERT INTO chunks(doc_id, sec_num, sec_title,"
+                    " start_line, end_line, body) VALUES(?,?,?,?,?,?)",
+                    (doc_id, sec.sec_num, sec.sec_title,
+                     sec.start_line, sec.end_line, sec.text))
+                n_chunks += 1
+        conn.commit()
+        conn.execute("INSERT INTO chunks_fts(chunks_fts) VALUES('rebuild')")
+        conn.commit()
+        conn.isolation_level = None  # VACUUM cannot run inside a transaction
+        conn.execute("VACUUM")
+        return n_chunks
+    finally:
+        conn.close()
+
+
+def _fill_search_docs(search_db: Path, conn, doc_ids: list[str]) -> None:
+    sc = sqlite3.connect(search_db)
+    try:
+        for doc_id in doc_ids:
+            row = conn.execute(
+                """SELECT doc_id, series, COALESCE(title,''),
+                          COALESCE(status,''), COALESCE(pub_date,''),
+                          is_current, COALESCE(stream,''), COALESCE(wg,'')
+                   FROM docs WHERE doc_id=?""", (doc_id,)).fetchone()
+            if row:
+                sc.execute("INSERT OR REPLACE INTO docs VALUES(?,?,?,?,?,?,?,?)",
+                           tuple(row))
+        sc.commit()
+    finally:
+        sc.close()
+
+
+def build_pack(conn, coll: Collection, out_dir: Path,
+               formats: list[str] = ("txt",), search: bool = True,
+               progress=None) -> dict:
+    """Build <out_dir>/<coll.id>.rfcpack; returns a summary dict."""
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    doc_ids = resolve(conn, coll)
+    if not doc_ids:
+        raise LookupError(f"collection '{coll.id}' resolves to 0 docs")
+    # Alias-series docs (STD/BCP/FYI) are pointers, not content; drop any
+    # that carry no member files instead of failing the whole pack.
+    doc_ids = [d for d in doc_ids if d.startswith("RFC") or conn.execute(
+        "SELECT 1 FROM files WHERE doc_id=? LIMIT 1", (d,)).fetchone()]
+    files = resolve_files(conn, doc_ids, list(formats))
+    doc_ids = [d for d in doc_ids if d in files]
+
+    root = coll.id
+    tmp = out_dir / (coll.id + PACK_SUFFIX + ".part")
+    search_db = out_dir / f".search-{coll.id}.sqlite.tmp"
+    n_chunks = 0
+    try:
+        if search and "txt" in files[doc_ids[0]]:
+            txt = {d: files[d]["txt"] for d in doc_ids if "txt" in files[d]}
+            if progress:
+                progress(f"indexing {len(txt)} docs for offline search ...")
+            n_chunks = build_search_db(doc_ids, txt, search_db)
+            _fill_search_docs(search_db, conn, doc_ids)
+
+        file_entries, hashes = [], []
+        with zipfile.ZipFile(tmp, "w", zipfile.ZIP_DEFLATED,
+                             compresslevel=9) as zf:
+            for doc_id in sorted(doc_ids, key=sort_key):
+                for fmt, path in sorted(files[doc_id].items()):
+                    arc = f"{root}/docs/{doc_id}.{fmt}"
+                    sha = _sha256(path)
+                    hashes.append(sha)
+                    file_entries.append({
+                        "path": arc, "doc_id": doc_id, "fmt": fmt,
+                        "sha256": sha, "size": path.stat().st_size})
+                    zf.write(path, arc)
+            if search_db.is_file():
+                zf.write(search_db, f"{root}/search.sqlite")
+            manifest = {
+                "format": FORMAT_VERSION,
+                "id": coll.id, "name": coll.name,
+                "description": coll.description,
+                "generated_at": _now(),
+                "formats": sorted(formats),
+                "version": hashlib.sha256(
+                    "".join(hashes).encode()).hexdigest()[:16],
+                "doc_count": len(doc_ids), "chunk_count": n_chunks,
+                "docs": _docs_meta(conn, doc_ids, files),
+                "files": file_entries,
+            }
+            zf.writestr(f"{root}/{PACK_MARKER}",
+                        json.dumps(manifest, ensure_ascii=False, indent=1))
+        final = out_dir / (coll.id + PACK_SUFFIX)
+        tmp.replace(final)
+        return {"id": coll.id, "path": str(final), "docs": len(doc_ids),
+                "files": len(file_entries), "chunks": n_chunks,
+                "bytes": final.stat().st_size,
+                "version": manifest["version"]}
+    finally:
+        if search_db.exists():
+            search_db.unlink()
+        if tmp.exists():
+            tmp.unlink()

primarysource/rfc/packs/collections/all-current-txt.json

@@ -0,0 +1,10 @@
+{
+ "id": "all-current-txt",
+ "name": "Full RFC Archive (current)",
+ "description": "Every non-obsolete document in the local mirror. Large (~1 GB uncompressed txt); build with --no-search unless you want the multi-hundred-MB FTS index too.",
+ "docs": [],
+ "selectors": [
+  {"current": true}
+ ],
+ "history": false
+}

primarysource/rfc/packs/collections/essentials.json

@@ -0,0 +1,19 @@
+{
+ "id": "essentials",
+ "name": "Internet Essentials",
+ "description": "Hand-picked core protocols every RFC reader should have offline: keyword norms, IPv4/IPv6, TCP/UDP, DNS(+SEC), DHCP, email, HTTP/1.1+2+3, TLS 1.3, QUIC, and the RFC process documents. All current (non-obsolete) IDs; set \"history\": true in a copy to pull in the obsoleted lineage.",
+ "docs": [
+  "RFC2119", "RFC8174", "RFC2026", "RFC9920", "RFC7841",
+  "RFC9293", "RFC792", "RFC1112", "RFC2236", "RFC1071", "RFC1122", "RFC1123",
+  "RFC768", "RFC8200", "RFC4291", "RFC4443", "RFC1918", "RFC6890",
+  "RFC2131", "RFC2132", "RFC9915",
+  "RFC1034", "RFC1035", "RFC7766", "RFC6891", "RFC9331", "RFC9903", "RFC8078",
+  "RFC5321", "RFC5322", "RFC6409", "RFC6532", "RFC2045", "RFC2049",
+  "RFC1939", "RFC9051", "RFC9458",
+  "RFC3986", "RFC9110", "RFC9112", "RFC9113", "RFC9536", "RFC9114", "RFC9115",
+  "RFC9846", "RFC8447", "RFC8448", "RFC5280",
+  "RFC9000", "RFC9001", "RFC9002", "RFC9369"
+ ],
+ "selectors": [],
+ "history": false
+}

primarysource/rfc/packs/collections/fyi-current.json

@@ -0,0 +1,10 @@
+{
+ "id": "fyi-current",
+ "name": "FYI Notes",
+ "description": "Current FYI (For Your Information) notes — the RFC Series' informational essays (e.g. RFC 1918, the KISS principle, privacy considerations).",
+ "docs": [],
+ "selectors": [
+  {"series": ["FYI"], "current": true, "members": true}
+ ],
+ "history": false
+}

primarysource/rfc/packs/collections/standards-current.json

@@ -0,0 +1,10 @@
+{
+ "id": "standards-current",
+ "name": "Official Standards & BCPs",
+ "description": "Every RFC that is a member of a current STD (Internet Standard) or BCP (Best Current Practice), resolved from the alias series in rfc-index.xml. This is the closest thing the RFC Series has to an official 'essential' list.",
+ "docs": [],
+ "selectors": [
+  {"series": ["STD", "BCP"], "current": true, "members": true}
+ ],
+ "history": false
+}

primarysource/rfc/packs/collections/year-2025.json

@@ -0,0 +1,10 @@
+{
+ "id": "year-2025",
+ "name": "RFCs Published in 2025",
+ "description": "Everything published in 2025 — an example of the year selector for keeping up with releases without watching the RSS feed daily.",
+ "docs": [],
+ "selectors": [
+  {"year": "2025", "current": false}
+ ],
+ "history": false
+}

primarysource/rfc/packs/collections/year-2026.json

@@ -0,0 +1,10 @@
+{
+ "id": "year-2026",
+ "name": "RFCs Published in 2026",
+ "description": "Everything published in 2026 so far — rebuild this pack any time after `rfclib sync` to pick up the month's releases.",
+ "docs": [],
+ "selectors": [
+  {"year": "2026", "current": false}
+ ],
+ "history": false
+}

primarysource/rfc/packs/collections.py

@@ -0,0 +1,163 @@
+"""Collection manifests: named, editable bundles of RFCs resolved from the DB.
+
+A collection is a small JSON file (stdlib-parseable — the Android reader
+reads the same format) that names documents explicitly and/or selects them
+by DB attributes (series/stream/area/wg/year). Publication is rolling
+(~5-25 RFCs/month, no official batches), so the useful groupings are the
+official ones: STD/BCP/FYI alias series, streams, IETF areas, working
+groups, publication year — plus hand-curated sets like `essentials`.
+
+Selector semantics (all keys optional, AND-combined):
+  series / stream / area / wg : list of exact values to include
+  year                        : pub_date year, e.g. "2025"
+  current                     : true (default) keeps only non-obsolete docs
+  members                     : true expands STD/BCP/FYI picks to their
+                                content-bearing RFC members (alias edges)
+
+Collection-level "history": also pull in the docs that the selected docs
+obsolete (transitive), so a reader sees the lineage, not just the tip.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+BUILTIN_DIR = Path(__file__).parent / "collections"
+
+_SERIES_ORDER = {"RFC": 0, "BCP": 1, "STD": 2, "FYI": 3, "IEN": 4}
+
+
+def sort_key(doc_id: str) -> tuple[int, int]:
+    m = re.fullmatch(r"(RFC|BCP|STD|FYI|IEN)(\d+)", doc_id)
+    if not m:
+        return (9, 0)
+    return (_SERIES_ORDER.get(m.group(1), 9), int(m.group(2)))
+
+
+@dataclass
+class Collection:
+    id: str
+    name: str
+    description: str
+    docs: list[str] = field(default_factory=list)
+    selectors: list[dict] = field(default_factory=list)
+    history: bool = False
+
+    @classmethod
+    def from_json(cls, raw: dict, fallback_id: str = "") -> "Collection":
+        cid = raw.get("id") or fallback_id
+        if not cid or not re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,40}", cid):
+            raise ValueError(f"invalid collection id: {cid!r}")
+        return cls(
+            id=cid,
+            name=raw.get("name", cid),
+            description=raw.get("description", ""),
+            docs=[str(d) for d in raw.get("docs", [])],
+            selectors=[dict(s) for s in raw.get("selectors", [])],
+            history=bool(raw.get("history", False)),
+        )
+
+
+def builtin_collections() -> list[Path]:
+    return sorted(BUILTIN_DIR.glob("*.json"))
+
+
+def find_collection(name: str, extra_dirs: list[Path] | None = None) -> Path:
+    """Locate `<name>.json` in the extra dirs (user dirs win) or builtins."""
+    for d in (extra_dirs or []):
+        p = Path(d) / f"{name}.json"
+        if p.is_file():
+            return p
+    p = BUILTIN_DIR / f"{name}.json"
+    if p.is_file():
+        return p
+    raise LookupError(f"no collection '{name}' (checked user dirs and builtins)")
+
+
+def list_collections(extra_dirs: list[Path] | None = None) -> list[Collection]:
+    """Builtins plus user overrides — a user file with the same id wins."""
+    by_id: dict[str, Path] = {}
+    for p in builtin_collections():
+        by_id[p.stem] = p
+    for d in (extra_dirs or []):
+        for p in sorted(Path(d).glob("*.json")):
+            by_id[p.stem] = p
+    return [Collection.from_json(json.loads(path.read_text("utf-8")),
+                                 fallback_id=cid)
+            for cid, path in sorted(by_id.items())]
+
+
+def _selector_sql(sel: dict) -> tuple[str, list]:
+    where, args = ["1=1"], []
+    for key in ("series", "stream", "area", "wg"):
+        vals = sel.get(key)
+        if vals:
+            where.append(f"COALESCE({key},'') IN ({','.join('?' * len(vals))})")
+            args += [str(v) for v in vals]
+    year = sel.get("year")
+    if year:
+        where.append("pub_date LIKE ?")
+        args.append(f"{int(year)}-%")
+    if sel.get("current", True):
+        where.append("is_current = 1")
+    return " AND ".join(where), args
+
+
+def _expand_members(conn, ids: set[str]) -> set[str]:
+    """Replace STD/BCP/FYI alias docs by their content-bearing RFC members;
+    aliases without any member edge are kept as-is."""
+    if not ids:
+        return ids
+    ph = ",".join("?" * len(ids))
+    nonrfc = {r[0] for r in conn.execute(
+        f"SELECT doc_id FROM docs WHERE doc_id IN ({ph}) AND series != 'RFC'",
+        sorted(ids))}
+    if not nonrfc:
+        return ids
+    ph = ",".join("?" * len(nonrfc))
+    members = {r[0] for r in conn.execute(
+        f"SELECT dst FROM doc_relations WHERE kind='alias' AND src IN ({ph})",
+        sorted(nonrfc))}
+    by_alias: dict[str, list[str]] = {}
+    for src, dst in conn.execute(
+            f"SELECT src, dst FROM doc_relations "
+            f"WHERE kind='alias' AND src IN ({ph})", sorted(nonrfc)):
+        by_alias.setdefault(src, []).append(dst)
+    out = set(ids)
+    for alias in nonrfc:
+        if by_alias.get(alias):
+            out.discard(alias)
+    return out | members
+
+
+def resolve(conn, coll: Collection) -> list[str]:
+    """Resolve a collection to a sorted list of doc_ids (no file checks)."""
+    picked: set[str] = set()
+    for doc in coll.docs:
+        m = re.fullmatch(r"(RFC|BCP|STD|FYI|IEN)\s*(\d+)", doc.strip(), re.I)
+        if not m:
+            raise ValueError(f"{coll.id}: bad doc id {doc!r}")
+        picked.add(m.group(1).upper() + m.group(2))
+    for sel in coll.selectors:
+        where, args = _selector_sql(sel)
+        ids = {r[0] for r in conn.execute(
+            f"SELECT doc_id FROM docs WHERE {where}", args)}
+        if sel.get("members"):
+            ids = _expand_members(conn, ids)
+        picked |= ids
+
+    if coll.history:
+        # Add the docs the picked docs obsolete, transitively (lineage).
+        frontier = set(picked)
+        while frontier:
+            ph = ",".join("?" * len(frontier))
+            rows = conn.execute(
+                f"""SELECT dst FROM doc_relations
+                    WHERE kind='obsoletes' AND src IN ({ph})""",
+                sorted(frontier)).fetchall()
+            frontier = {r[0] for r in rows} - picked
+            picked |= frontier
+    return sorted(picked, key=sort_key)

primarysource/rfc/packs/docsetexport.py

@@ -0,0 +1,163 @@
+"""Dash docset export: one collection -> one <id>.docset bundle (+ .tgz).
+
+Canonical docset layout (Dash / Xcode / Zeal all read it):
+
+  <id>.docset/Contents/
+    Info.plist                    bundle identity, Dash/Xcode keys
+    Resources/
+      icon.png                    32x32 catalogue icon (generated, stdlib)
+      docSet.dsidx                SQLite searchIndex(word, type, url)
+      Documents/                  index.html + style.css + RFCxxxx.html
+
+Pages come from the shared export.py render layer — identical to the
+EPUB/HTML/ZIM exports — laid out flat in Documents/. The dsidx gives
+Dash its headline feature: type-ahead lookup of documents ("RFC9110…")
+and top-level sections ("RFC9110: 4.2. HTTP Messaging") that deep-link
+straight into the section anchor. No new dependencies: plistlib,
+sqlite3 and tarfile are stdlib.
+"""
+from __future__ import annotations
+
+import html as htmllib
+import plistlib
+import shutil
+import sqlite3
+import tarfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable, Optional
+
+from .collections import Collection
+from .export import ExportDoc, STYLE_CSS, make_resolver, render_doc_page
+from .zimexport import _png_illustration  # stdlib PNG generator, no libzim
+
+# Section headings at or above this level (smaller = shallower) become
+# index entries; level 2 is what the renderer gives top-level numbered
+# sections and appendices, so this is "one entry per section".
+MAX_INDEX_LEVEL = 2
+
+
+def _index_page(coll: Collection, docs: list[ExportDoc], now: str) -> str:
+    rows = "".join(
+        "<tr>"
+        f'<td class="num"><a href="{htmllib.escape(d.doc_id)}.html">'
+        f"{htmllib.escape(d.doc_id)}</a></td>"
+        f"<td>{htmllib.escape(d.title)}</td>"
+        f"<td>{htmllib.escape(d.status)}</td>"
+        f'<td class="num">{htmllib.escape(d.pub_date)}</td>'
+        f"{'current' if d.current else 'obsolete'}"
+        "</tr>" for d in docs)
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>{htmllib.escape(coll.name)} — rfclib docset</title>
+<link rel="stylesheet" type="text/css" href="style.css"/>
+</head>
+<body>
+<h1>{htmllib.escape(coll.name)}</h1>
+<p class="meta">{len(docs)} documents · generated {now} · Dash docset
+(lookup via Dash; anchors link into sections)</p>
+<p>{htmllib.escape(coll.description)}</p>
+<table class="index">
+<tr><th>Doc</th><th>Title</th><th>Status</th><th>Published</th><th></th></tr>
+{rows}
+</table>
+</body>
+</html>
+"""
+
+
+def _info_plist(coll: Collection, now: str) -> dict:
+    return {
+        "CFBundleIdentifier": f"org.rfclib.{coll.id}",
+        "CFBundleName": coll.name,
+        "CFBundleDevelopmentRegion": "en",
+        "CFBundleIconFile": "icon.png",
+        # Xcode reads docset_platform; Dash ignores unknown keys.
+        "docset_platform": {
+            "platform_family": "Common",
+            "docset_name": coll.id,
+            "dashboard_name": coll.name,
+            "docset_article_path": "Documents",
+        },
+        # Dash-specific markers.
+        "isDashDocset": True,
+        "dashDocsetCompat": ["Common"],
+        "docset_icon": "icon.png",
+        "docset_taxonomy": "guides;reference;standards",
+        "dash_docset_date": now,
+    }
+
+
+def _build_dsidx(db_path: Path, docs: list[ExportDoc],
+                 toc: dict[str, list[tuple[int, str, str]]]) -> int:
+    """Write the searchIndex table; returns the number of index rows."""
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(db_path))
+    try:
+        conn.executescript(
+            "DROP TABLE IF EXISTS searchIndex;"
+            "CREATE TABLE searchIndex(id INTEGER PRIMARY KEY,"
+            " word TEXT, type TEXT, url TEXT);"
+            "CREATE INDEX word ON searchIndex (word);")
+        rows: list[tuple[str, str, str]] = []
+        for doc in docs:
+            fname = f"{doc.doc_id}.html"
+            rows.append((f"{doc.doc_id}: {doc.title}", "Guide", fname))
+            for level, hid, text in toc.get(doc.doc_id, []):
+                if level > MAX_INDEX_LEVEL or hid.startswith("toc"):
+                    continue
+                rows.append((f"{doc.doc_id}: {text}", "Section",
+                             f"{fname}#{hid}"))
+        conn.executemany(
+            "INSERT INTO searchIndex(word, type, url) VALUES (?,?,?)", rows)
+        conn.commit()
+    finally:
+        conn.close()
+    return len(rows)
+
+
+def build_docset(coll: Collection, docs: list[ExportDoc], out_dir: Path,
+                 link_refs: str = "internal",
+                 progress: Optional[Callable[[str], None]] = None) -> dict:
+    """Write <out_dir>/<coll.id>.docset (+ .tgz); summary dict like build_html."""
+    root = Path(out_dir) / f"{coll.id}.docset"
+    res_dir = root / "Contents" / "Resources"
+    docs_dir = res_dir / "Documents"
+    # Stale files must not survive a rebuild — Dash would keep dead entries.
+    if root.exists():
+        shutil.rmtree(root)
+    docs_dir.mkdir(parents=True, exist_ok=True)
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    known = {d.doc_id: f"{d.doc_id}.html" for d in docs}
+    resolver = make_resolver(known, link_refs)
+
+    (root / "Contents" / "Info.plist").write_bytes(
+        plistlib.dumps(_info_plist(coll, now)))
+    (res_dir / "icon.png").write_bytes(_png_illustration(32))
+    (docs_dir / "style.css").write_text(STYLE_CSS, "utf-8")
+    idx = _index_page(coll, docs, now)
+    (docs_dir / "index.html").write_text(idx, "utf-8")
+
+    nbytes = len(idx.encode("utf-8")) + len(STYLE_CSS)
+    toc: dict[str, list[tuple[int, str, str]]] = {}
+    for n, doc in enumerate(docs, 1):
+        page, headings = render_doc_page(doc, resolver, css_href="style.css",
+                                         back_href="index.html")
+        (docs_dir / f"{doc.doc_id}.html").write_text(page, "utf-8")
+        toc[doc.doc_id] = headings
+        nbytes += len(page.encode("utf-8"))
+        if progress:
+            progress(f"docset {n}/{len(docs)} {doc.doc_id}")
+
+    n_entries = _build_dsidx(res_dir / "docSet.dsidx", docs, toc)
+
+    tgz = Path(out_dir) / f"{coll.id}.docset.tgz"
+    with tarfile.open(tgz, "w:gz") as tar:
+        tar.add(root, arcname=f"{coll.id}.docset")
+    return {"id": coll.id, "format": "docset", "path": str(root),
+            "docs": len(docs), "bytes": tgz.stat().st_size,
+            "entries": n_entries}