bookfetch 0.3.0__tar.gz

bookfetch-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+
+# 内部规划文档，不上传（决策过程/商业意图属于本地留档）
+docs/PRD.md

bookfetch-0.3.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: bookfetch
+Version: 0.3.0
+Summary: Agent-friendly ebook finder CLI: routes book queries to working sources (Chinese classics first).
+Author-email: Helios Wei <helioswei1995@gmail.com>
+License: MIT
+Keywords: agent,chinese,classics,cli,ctext,ebook
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Provides-Extra: simp
+Requires-Dist: opencc>=1.4; extra == 'simp'
+Description-Content-Type: text/markdown
+
+# bookfetch
+
+给 Agent 用的电子书查找与下载 CLI：把书名丢给它，它自动把请求路由到**实际能下到书**的源。
+
+设计出发点（实测结论）：现成的 agent 找书技能几乎全部绑定 Z-Library / Libgen，而这两者对**中文古籍基本无效**（不收录 / 账号墙 / Cloudflare 墙）。中文古籍真正能用的源是 ctext.org（中国哲学书电子化计划：免费、带标点、国内直连）——没人把它做成 agent 工具，于是有了 bookfetch。
+
+```
+bookfetch search 渊海子平     # 跨源搜索，输出 JSON
+bookfetch get ctext 727782    # 下载整本书到当前目录
+```
+
+## 特性
+
+- 书源路由：按书种/语言分发到可用源，单个源故障不影响整体（errors 独立上报）
+- **EPUB / 章节感知**：`--format epub` 零依赖生成手机可读的 epub（含目录）；`--split`
+  在 txt 中插入章节分隔；古籍《》/卷/序跋类标题行自动识别为章节
+- JSON 优先输出：stdout 只吐结构化 JSON，agent 直接解析；`--human` 给人看
+- 礼貌抓取：内置限速 + 重试退避 + 编码回退（GBK/Big5→UTF-8）
+- **零运行时依赖**：纯 Python 标准库，任何环境装完即用（简体转换是可选扩展）
+- 离线可测：解析测试基于真实抓包样本（fixtures），不依赖线上
+
+## 安装
+
+需要 Python >= 3.10。
+
+```bash
+# 推荐：uv
+uv tool install git+https://github.com/Helioswei/bookfetch.git
+
+# 或 pip
+pip install git+https://github.com/Helioswei/bookfetch.git
+
+# 本地开发
+uv sync && uv run bookfetch search 论语
+```
+
+## 用法
+
+### 搜索
+
+```bash
+bookfetch search <书名>
+```
+
+输出（JSON，字段稳定，供 agent 消费）：
+
+```json
+{
+  "cmd": "search",
+  "query": "渊海子平",
+  "results": [
+    {
+      "source": "ctext",
+      "id": "727782",
+      "title": "淵海子平",
+      "url": "https://ctext.org/wiki.pl?if=gb&res=727782",
+      "subtitle": "維基文字版：開放共同編輯的資料。",
+      "format_hint": "txt",
+      "extra": { "author": "徐子平" }
+    }
+  ],
+  "count": 1,
+  "errors": {}
+}
+```
+
+`--source ctext` 限定源（可重复）；`--limit N` 限制条数；`--human` 输出人类可读列表。
+
+### 下载
+
+```bash
+bookfetch get ctext 727782 --out ./books            # 默认 txt（整本合并）
+bookfetch get ctext 727782 --format epub --out ./books   # 手机友好的 epub（自动分章+目录）
+bookfetch get ctext 727782 --split --out ./books    # txt 中插入 === 章节 === 分隔
+```
+
+把 id 对应的整本书下载为 UTF-8 纯文本（ctext 的书会自动按序抓取全部章节并拼接）。
+`epub` 与 `--split` 的章节来自源结构（ctext 分页）或《》/卷/序跋类标题行自动识别；
+正文一字不改，标题行仅在阅读视图去重。
+
+#### 繁转简（可选）
+
+默认保留古籍繁体原文；需要简体版时加 `--simplify`（需先装可选依赖）：
+
+```bash
+uv tool install bookfetch --extra simp     # 或 pip install 'bookfetch[simp]'
+bookfetch get ctext 727782 --out ./books --simplify
+```
+
+转换基于 OpenCC（t2s），文件与文件名会一并转为简体。古籍存在异体字/通假字，
+转换非 100% 保真，学术用途请以原文为准。
+
+## 已支持的书源
+
+| 源 | 覆盖 | 说明 |
+|---|---|---|
+| ctext | 中文古籍（免费全文、带标点） | 书目检索 + 多章节整本下载 |
+| github | 公版中文古籍文本仓库 | 精选仓库树索引（7 天缓存），raw 直连下载 |
+| wikisource | 中文/英文公版书（含现代公版：鲁迅等） | MediaWiki API + 渲染页解析，目录自动展开整本；大陆访问需代理 |
+| libgen | 英文现代书（原文件 epub/pdf） | 探活式镜像链（域名轮换频繁），当前镜像不可达时会明确报错；需代理 |
+
+> 网络提示：ctext/github 大陆直连可用；wikisource（Wikimedia）与 libgen 大陆直连不通，
+> 需能访问对应站点的网络环境（如代理），本工具遵循系统 http_proxy/https_proxy 环境变量。
+
+## 源与合规
+
+- bookfetch 是**路由与下载工具**，不存储、不重新分发任何书籍内容；下载物只落在使用者本地
+- 各源内容版权归原作者/整理者所有。公版内容可自由使用；**仍在版权期内的内容，请使用者自行确认下载与使用的合法性**
+- 抓取行为遵守各源访问条款：公开页面、内置限速、不做任何绕过（登录墙/验证码/反爬规避）
+- 测试 fixture 为各源页面/结构的极小样本，仅用于解析测试，来源记录见 tests/fixtures/README.md
+- 任何权利方认为本工具对某源的使用不妥，请提 issue，我们会调整或移除该源
+
+## 开发与测试
+
+```bash
+uv sync --group dev
+uv run pytest -q      # 离线测试，基于 tests/fixtures 真实抓包样本
+```
+
+## 路线图
+
+- [x] M1: ctext 源 + search/get CLI（2026-09-03 完成）
+- [x] M2: github 古籍源 + OpenCC 简繁转换 + 合规声明（2026-09-03 完成）
+- [x] M3: EPUB 转换 + 章节切分（2026-09-04 完成，零依赖手写 zip+xhtml）
+- [x] M4: wikisource 中/英公版源 + libgen 探活镜像链 + 白话注解 spike（2026-09-04 完成；白话注解判定放弃，见 PRD）
+- [ ] 规划中: SKILL.md agent 外壳 + PyPI 发布
+
+## 许可
+
+MIT。只面向公版/开放文本（ctext 收录均为公版古籍）。请遵守各源的访问条款。

bookfetch-0.3.0/README.md

@@ -0,0 +1,130 @@
+# bookfetch
+
+给 Agent 用的电子书查找与下载 CLI：把书名丢给它，它自动把请求路由到**实际能下到书**的源。
+
+设计出发点（实测结论）：现成的 agent 找书技能几乎全部绑定 Z-Library / Libgen，而这两者对**中文古籍基本无效**（不收录 / 账号墙 / Cloudflare 墙）。中文古籍真正能用的源是 ctext.org（中国哲学书电子化计划：免费、带标点、国内直连）——没人把它做成 agent 工具，于是有了 bookfetch。
+
+```
+bookfetch search 渊海子平     # 跨源搜索，输出 JSON
+bookfetch get ctext 727782    # 下载整本书到当前目录
+```
+
+## 特性
+
+- 书源路由：按书种/语言分发到可用源，单个源故障不影响整体（errors 独立上报）
+- **EPUB / 章节感知**：`--format epub` 零依赖生成手机可读的 epub（含目录）；`--split`
+  在 txt 中插入章节分隔；古籍《》/卷/序跋类标题行自动识别为章节
+- JSON 优先输出：stdout 只吐结构化 JSON，agent 直接解析；`--human` 给人看
+- 礼貌抓取：内置限速 + 重试退避 + 编码回退（GBK/Big5→UTF-8）
+- **零运行时依赖**：纯 Python 标准库，任何环境装完即用（简体转换是可选扩展）
+- 离线可测：解析测试基于真实抓包样本（fixtures），不依赖线上
+
+## 安装
+
+需要 Python >= 3.10。
+
+```bash
+# 推荐：uv
+uv tool install git+https://github.com/Helioswei/bookfetch.git
+
+# 或 pip
+pip install git+https://github.com/Helioswei/bookfetch.git
+
+# 本地开发
+uv sync && uv run bookfetch search 论语
+```
+
+## 用法
+
+### 搜索
+
+```bash
+bookfetch search <书名>
+```
+
+输出（JSON，字段稳定，供 agent 消费）：
+
+```json
+{
+  "cmd": "search",
+  "query": "渊海子平",
+  "results": [
+    {
+      "source": "ctext",
+      "id": "727782",
+      "title": "淵海子平",
+      "url": "https://ctext.org/wiki.pl?if=gb&res=727782",
+      "subtitle": "維基文字版：開放共同編輯的資料。",
+      "format_hint": "txt",
+      "extra": { "author": "徐子平" }
+    }
+  ],
+  "count": 1,
+  "errors": {}
+}
+```
+
+`--source ctext` 限定源（可重复）；`--limit N` 限制条数；`--human` 输出人类可读列表。
+
+### 下载
+
+```bash
+bookfetch get ctext 727782 --out ./books            # 默认 txt（整本合并）
+bookfetch get ctext 727782 --format epub --out ./books   # 手机友好的 epub（自动分章+目录）
+bookfetch get ctext 727782 --split --out ./books    # txt 中插入 === 章节 === 分隔
+```
+
+把 id 对应的整本书下载为 UTF-8 纯文本（ctext 的书会自动按序抓取全部章节并拼接）。
+`epub` 与 `--split` 的章节来自源结构（ctext 分页）或《》/卷/序跋类标题行自动识别；
+正文一字不改，标题行仅在阅读视图去重。
+
+#### 繁转简（可选）
+
+默认保留古籍繁体原文；需要简体版时加 `--simplify`（需先装可选依赖）：
+
+```bash
+uv tool install bookfetch --extra simp     # 或 pip install 'bookfetch[simp]'
+bookfetch get ctext 727782 --out ./books --simplify
+```
+
+转换基于 OpenCC（t2s），文件与文件名会一并转为简体。古籍存在异体字/通假字，
+转换非 100% 保真，学术用途请以原文为准。
+
+## 已支持的书源
+
+| 源 | 覆盖 | 说明 |
+|---|---|---|
+| ctext | 中文古籍（免费全文、带标点） | 书目检索 + 多章节整本下载 |
+| github | 公版中文古籍文本仓库 | 精选仓库树索引（7 天缓存），raw 直连下载 |
+| wikisource | 中文/英文公版书（含现代公版：鲁迅等） | MediaWiki API + 渲染页解析，目录自动展开整本；大陆访问需代理 |
+| libgen | 英文现代书（原文件 epub/pdf） | 探活式镜像链（域名轮换频繁），当前镜像不可达时会明确报错；需代理 |
+
+> 网络提示：ctext/github 大陆直连可用；wikisource（Wikimedia）与 libgen 大陆直连不通，
+> 需能访问对应站点的网络环境（如代理），本工具遵循系统 http_proxy/https_proxy 环境变量。
+
+## 源与合规
+
+- bookfetch 是**路由与下载工具**，不存储、不重新分发任何书籍内容；下载物只落在使用者本地
+- 各源内容版权归原作者/整理者所有。公版内容可自由使用；**仍在版权期内的内容，请使用者自行确认下载与使用的合法性**
+- 抓取行为遵守各源访问条款：公开页面、内置限速、不做任何绕过（登录墙/验证码/反爬规避）
+- 测试 fixture 为各源页面/结构的极小样本，仅用于解析测试，来源记录见 tests/fixtures/README.md
+- 任何权利方认为本工具对某源的使用不妥，请提 issue，我们会调整或移除该源
+
+## 开发与测试
+
+```bash
+uv sync --group dev
+uv run pytest -q      # 离线测试，基于 tests/fixtures 真实抓包样本
+```
+
+## 路线图
+
+- [x] M1: ctext 源 + search/get CLI（2026-09-03 完成）
+- [x] M2: github 古籍源 + OpenCC 简繁转换 + 合规声明（2026-09-03 完成）
+- [x] M3: EPUB 转换 + 章节切分（2026-09-04 完成，零依赖手写 zip+xhtml）
+- [x] M4: wikisource 中/英公版源 + libgen 探活镜像链 + 白话注解 spike（2026-09-04 完成；白话注解判定放弃，见 PRD）
+- [ ] 规划中: SKILL.md agent 外壳 + PyPI 发布
+
+## 许可
+
+MIT。只面向公版/开放文本（ctext 收录均为公版古籍）。请遵守各源的访问条款。

bookfetch-0.3.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "bookfetch"
+version = "0.3.0"
+description = "Agent-friendly ebook finder CLI: routes book queries to working sources (Chinese classics first)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Helios Wei", email = "helioswei1995@gmail.com" }]
+keywords = ["ebook", "chinese", "classics", "ctext", "cli", "agent"]
+classifiers = [
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.scripts]
+bookfetch = "bookfetch.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bookfetch"]
+
+[project.optional-dependencies]
+simp = ["opencc>=1.4"]
+
+[dependency-groups]
+dev = ["pytest>=8.0", "opencc>=1.4"]

bookfetch-0.3.0/src/bookfetch/__init__.py

@@ -0,0 +1,3 @@
+"""bookfetch — agent-friendly ebook finder CLI."""
+
+__version__ = "0.3.0"

bookfetch-0.3.0/src/bookfetch/cli.py

@@ -0,0 +1,169 @@
+"""bookfetch CLI — JSON-first output for agents, --human for people."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .model import Book, Chapter, FetchResult
+from .sources import get_source, search_all, source_names
+from .util import FetchError, sanitize_filename
+from .util.epub import build_epub
+from .util.simplify import to_simplified
+from .util.splitters import split_headings
+
+DESC = "Agent-friendly ebook finder: routes book queries to working sources."
+
+
+def _human_search(obj: dict) -> None:
+    for i, b in enumerate(obj["results"], 1):
+        extra = f" [{b['subtitle']}]" if b.get("subtitle") else ""
+        print(f"{i}. [{b['source']}] {b['title']} (id={b['id']}){extra}")
+    if obj.get("errors"):
+        for src, err in obj["errors"].items():
+            print(f"   ! {src}: {err}", file=sys.stderr)
+
+
+def _human_get(obj: dict) -> None:
+    r = obj["result"]
+    print(f"Saved: {r['out_path']}")
+    extra = f" | {len(r['chapters'])} chapters" if r.get("chapters") else ""
+    print(f"  {r['title']} | {r['lines']} paragraphs | {r['chars']} chars | {r['format']}{extra}")
+
+
+def _ensure_chapters(fr: FetchResult) -> list[Chapter]:
+    """Chapters from the source, or heading-split, or one whole-text chapter."""
+    if fr.chapters:
+        return list(fr.chapters)
+    chs = split_headings(fr.content.splitlines())
+    if chs:
+        return chs
+    return [Chapter(title=fr.title or fr.id, text=fr.content)]
+
+
+def _render_get(src, book: Book, args) -> FetchResult:
+    """Fetch -> optional simplify -> render txt/epub under --out.
+
+    Binary sources (libgen etc.) return FetchResult.raw and are saved
+    byte-for-byte; text-only flags (--simplify/--split/--format) reject them.
+    """
+    fr = src.fetch(book)
+
+    if fr.raw is not None:  # binary passthrough: save the original file
+        if args.simplify or args.split or args.format != "txt":
+            raise ValueError(f"源 {fr.source} 是二进制原文件（.{fr.format}），不支持 --simplify/--split/--format")
+        fname = sanitize_filename(fr.title) or fr.id
+        out_dir = Path(args.out)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        path = out_dir / f"{fname}.{fr.format}"
+        path.write_bytes(fr.raw)
+        fr.out_path = str(path)
+        return fr
+
+    chapters = _ensure_chapters(fr)
+
+    if args.simplify:
+        chapters = [Chapter(title=to_simplified(c.title), text=to_simplified(c.text)) for c in chapters]
+        fr.title = to_simplified(fr.title)
+
+    fname = sanitize_filename(fr.title) or fr.id
+    out_dir = Path(args.out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    if args.format == "epub":
+        path = build_epub(fr.title, chapters, out_dir / f"{fname}.epub")
+        text_chars = sum(len(c.text) for c in chapters)
+        n_lines = sum(len(c.text.splitlines()) for c in chapters)
+    else:  # txt
+        if args.split and len(chapters) > 1:
+            parts = []
+            for i, c in enumerate(chapters, 1):
+                head = c.title or f"第{i}部分"
+                parts.append(f"=== {head} ===\n{c.text}")
+            text = "\n\n".join(parts) + "\n"
+        elif args.simplify:
+            text = "\n".join(c.text for c in chapters) + "\n"
+        else:
+            text = fr.content  # byte-identical to the fetched text
+        path = out_dir / f"{fname}.txt"
+        path.write_text(text, encoding="utf-8")
+        text_chars = len(text)
+        n_lines = len(text.splitlines())
+
+    fr.out_path = str(path)
+    fr.format = args.format
+    fr.chars = text_chars
+    fr.lines = n_lines
+    return fr
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="bookfetch", description=DESC)
+    p.add_argument("--version", action="version", version=f"bookfetch {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sp = sub.add_parser("search", help="search sources for a book")
+    sp.add_argument("query", help="book title or keywords (Chinese OK)")
+    sp.add_argument("--source", action="append", default=None, help="only search this source (repeatable)")
+    sp.add_argument("--limit", type=int, default=20, help="max results (default 20)")
+    sp.add_argument("--human", action="store_true", help="human-readable output")
+
+    gp = sub.add_parser("get", help="download a book edition (id from search)")
+    gp.add_argument("source", help="source name, e.g. ctext")
+    gp.add_argument("id", help="edition id from search results")
+    gp.add_argument("--title", default="", help="optional title override for the output filename")
+    gp.add_argument("--out", default=".", help="output directory (default: current dir)")
+    gp.add_argument(
+        "--format",
+        choices=["txt", "epub"],
+        default="txt",
+        help="output format (default: txt; epub needs no extra deps)",
+    )
+    gp.add_argument(
+        "--split",
+        action="store_true",
+        help="insert '=== 章节 ===' separators into txt output (epub is always split)",
+    )
+    gp.add_argument(
+        "--simplify",
+        action="store_true",
+        help="convert Traditional Chinese to Simplified (requires the [simp] extra: OpenCC)",
+    )
+    gp.add_argument("--human", action="store_true", help="human-readable output")
+
+    args = p.parse_args(argv)
+    try:
+        if args.cmd == "search":
+            results, errors = search_all(args.query, args.source, args.limit)
+            obj = {
+                "cmd": "search",
+                "query": args.query,
+                "results": [b.to_dict() for b in results],
+                "count": len(results),
+                "errors": errors,
+            }
+        else:  # get
+            src = get_source(args.source)
+            if src is None:
+                raise ValueError(f"unknown source {args.source!r} (known: {', '.join(source_names())})")
+            book = Book(source=args.source, id=args.id, title=args.title)
+            fr = _render_get(src, book, args)
+            obj = {"cmd": "get", "result": fr.to_dict()}
+
+        if getattr(args, "human", False) and args.cmd == "search":
+            _human_search(obj)
+        elif getattr(args, "human", False) and args.cmd == "get":
+            _human_get(obj)
+        else:
+            print(json.dumps(obj, ensure_ascii=False))
+        return 0
+    except (ValueError, FetchError) as e:
+        print(json.dumps({"cmd": getattr(args, "cmd", None), "error": str(e)}, ensure_ascii=False))
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bookfetch-0.3.0/src/bookfetch/model.py

@@ -0,0 +1,64 @@
+"""Shared result models."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+
+@dataclass
+class Book:
+    """One downloadable edition found by a source."""
+
+    source: str
+    id: str
+    title: str
+    url: str = ""
+    subtitle: str = ""
+    format_hint: str = "txt"
+    extra: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class Chapter:
+    """A titled section of a fetched book (source pages, 《》 headings, ...)."""
+
+    title: str
+    text: str
+
+
+@dataclass
+class FetchResult:
+    """Parsed content of a downloaded Book.
+
+    Sources return content + optional chapter structure WITHOUT writing files;
+    the CLI renders the requested format (txt/epub) and sets ``out_path``.
+    ``content`` is the plain merged text: joining each chapter's ``text`` with
+    ``"\\n"`` reproduces it exactly (chapters are ordered slices of lines), so
+    format rendering never loses or reorders anything.
+    """
+
+    source: str
+    id: str
+    title: str
+    out_path: str = ""
+    chars: int = 0
+    lines: int = 0
+    format: str = "txt"
+    content: str = ""
+    chapters: list[Chapter] | None = None
+    raw: bytes | None = None  # binary sources (libgen): file bytes, no text pipeline
+
+    def to_dict(self) -> dict:
+        return {
+            "source": self.source,
+            "id": self.id,
+            "title": self.title,
+            "out_path": self.out_path,
+            "chars": self.chars,
+            "lines": self.lines,
+            "format": self.format,
+            "chapters": [c.title for c in self.chapters] if self.chapters else None,
+        }

bookfetch-0.3.0/src/bookfetch/sources/__init__.py

@@ -0,0 +1,49 @@
+"""Source registry."""
+
+from __future__ import annotations
+
+from ..model import Book
+from .base import Source
+from .ctext import Ctext
+from .github import GithubBooks
+from .libgen import Libgen
+from .wikisource import Wikisource
+
+_REGISTRY: dict[str, Source] = {}
+
+
+def _register(src: Source) -> Source:
+    _REGISTRY[src.name] = src
+    return src
+
+
+_register(Ctext())
+_register(GithubBooks())
+_register(Wikisource("zh"))
+_register(Wikisource("en"))
+_register(Libgen())
+
+
+def get_source(name: str) -> Source | None:
+    return _REGISTRY.get(name)
+
+
+def source_names() -> list[str]:
+    return list(_REGISTRY)
+
+
+def search_all(query: str, names: list[str] | None = None, limit: int = 20):
+    """Search across sources. Returns (results, errors_by_source)."""
+    names = names or source_names()
+    results: list[Book] = []
+    errors: dict[str, str] = {}
+    for n in names:
+        src = _REGISTRY.get(n)
+        if src is None:
+            errors[n] = f"unknown source (known: {', '.join(source_names())})"
+            continue
+        try:
+            results.extend(src.search(query))
+        except Exception as e:  # source failure must not kill the whole search
+            errors[n] = f"{type(e).__name__}: {e}"
+    return results[:limit], errors

bookfetch-0.3.0/src/bookfetch/sources/base.py

@@ -0,0 +1,24 @@
+"""Source adapter interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..model import Book, FetchResult
+
+
+class Source(ABC):
+    """One book source (ctext, github, ...). Implementations must be stateless
+    except for util's built-in rate limiting."""
+
+    name: str = "base"
+
+    @abstractmethod
+    def search(self, query: str) -> list[Book]:
+        """Return editions matching query. Never raises for network issues —
+        callers surface errors via the errors dict instead."""
+
+    @abstractmethod
+    def fetch(self, book: Book) -> FetchResult:
+        """Fetch and parse one edition into content + optional chapter
+        structure. Never writes files — the CLI renders txt/epub."""