satchel-reader 0.1.0__tar.gz

satchel_reader-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritish Saini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

satchel_reader-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: satchel-reader
+Version: 0.1.0
+Summary: A local-first reading queue: saves the real article text, not just the link, and makes it genuinely offline-searchable.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/satchel
+Project-URL: Source, https://github.com/MaXiMo000/satchel
+Project-URL: Issues, https://github.com/MaXiMo000/satchel/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/satchel/releases
+Keywords: reading,offline,full-text-search,sqlite,local-first
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: trafilatura>=2.0
+Dynamic: license-file
+
+# satchel
+
+**A tiny local archive of the actual things you read.**
+
+[![ci](https://github.com/MaXiMo000/satchel/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/satchel/actions/workflows/ci.yml)
+
+Most "read later" tools save a URL. The link rots, the site adds a
+paywall, or you're offline — and the thing you saved is gone. `satchel`
+fetches the page once, extracts the actual article text (not the nav, not
+the related-links box, not the footer), and stores it in one local SQLite
+file with real full-text search. No server, no account, no network needed
+to search what you've already saved.
+
+```
+$ satchel add https://example.com/some-article
+saved #4: Why Local-First Software Is Worth the Extra Effort
+
+$ satchel search "FTS5"
+#4    Why Local-First Software Is Worth the Extra Effort  (https://example.com/some-article)
+
+$ satchel read 4
+Why Local-First Software Is Worth the Extra Effort
+by Jordan Rivers
+
+Most reading tools save a link and call it done...
+```
+
+Save with one click instead of a terminal: `satchel serve` runs a local
+listener and prints a bookmarklet — click it on any page and that page is
+saved through the exact same pipeline `add` uses. See "Capture" below.
+
+## How
+
+- `fetch.py` — plain `urllib` GET. Stdlib, no dependency for the easy
+  part. Always rejects non-http(s) schemes; a URL that didn't come from
+  the person running satchel (see "Capture") is additionally checked
+  against loopback/private/link-local address space before and after
+  every redirect hop, not just the first one.
+- `capture.py` — fetch → extract → store, in one place. Both `add` and the
+  capture listener call this; there is exactly one add pipeline.
+- `extract.py` — wraps [trafilatura](https://github.com/adbar/trafilatura)
+  to pull title/author/main-text out of real HTML, correctly skipping
+  navigation, ads, and related-links boilerplate. Boilerplate-stripping is
+  exactly the kind of thing that looks fine on a hand-rolled test page and
+  breaks on the next real site's markup — not worth reimplementing.
+- `db.py` — one SQLite file, an FTS5 virtual table kept in sync with the
+  real table via triggers (external-content FTS5: the searchable index
+  isn't a second copy of the truth that can drift from the first).
+- `serve.py` — the local capture listener (below).
+
+## Install
+
+```bash
+pip install satchel-reader        # the command it installs is `satchel`
+```
+
+Or from a checkout, for development:
+
+```bash
+pip install -e .
+```
+
+## Use
+
+```bash
+satchel add <url>          # fetch, extract, save
+satchel list                # everything saved
+satchel search <query>      # full-text search
+satchel read <id>           # print an article's full text
+satchel serve                # one-click capture -- see below
+```
+
+All commands take `--db path/to/file.db`. The default, if you don't pass
+one, is `~/.local/share/satchel/satchel.db` (respecting `XDG_DATA_HOME`) —
+one stable location regardless of which directory you happen to run the
+command from, not `./satchel.db` in the current directory. Run
+`satchel --help` to see the exact resolved path on your machine.
+
+Saving the same article twice — via a tracking link, a shortener, or a
+plain `http://` URL the site itself upgrades to `https://` — is one
+duplicate, not two. `add` normalizes the URL it's given, follows
+redirects, and normalizes the *actual* address the server served before
+checking for a duplicate: it defers to what the server says, rather than
+guessing at a scheme policy.
+
+## Capture
+
+```bash
+$ satchel serve
+satchel capture listening on http://127.0.0.1:8765  (db: ~/.local/share/satchel/satchel.db)
+
+Drag this to your bookmarks bar, then click it on any page to save it:
+
+  javascript:fetch('http://127.0.0.1:8765/add?token=...&url='+encodeURIComponent(location.href))...
+
+^C to stop.
+```
+
+Drag the printed link to your bookmarks bar. Click it on any page while
+`serve` is running, and that page goes through the same fetch/extract/save
+pipeline as `satchel add` — no terminal required for the thing you do most
+often.
+
+**This changes the threat model, and it's handled, not ignored.** While
+`serve` is running, any tab open in your browser can send it a request —
+a browser's same-origin policy stops a page from *reading* a
+cross-origin response it wasn't granted, but not from *sending* the
+request in the first place. Without a shared secret, that would be an
+open invitation for any open tab to make satchel fetch an arbitrary URL.
+So: the listener only binds to `127.0.0.1`, a fresh token is generated
+every time you run `serve` and only ever appears in the bookmarklet you
+just dragged, and every captured URL is checked against loopback,
+private (RFC1918), link-local (this is what closes off
+`169.254.169.254`-style cloud metadata endpoints), reserved, and
+multicast address space — before the first request, and again on every
+redirect hop, since checking only the first hop would let a URL redirect
+somewhere private after passing the initial check.
+
+What that guard does *not* claim: it validates a hostname's DNS answer at
+the moment it's checked, it doesn't pin the connection to that exact
+resolved address. A DNS-rebinding attacker with a fast-expiring record
+could in principle still slip a private address past the check and have
+the actual connection re-resolve to it. Closing that fully means
+connecting to a pinned IP rather than by hostname — real added complexity
+for a personal tool's local listener. This is a deliberate, documented
+partial mitigation, not a claim that it's unbreakable.
+
+Direct `satchel add <url>` from your own terminal is **not** restricted
+this way — typing your own local dev server's URL to save a draft you're
+writing is a legitimate thing to do, and you are not a threat to
+yourself.
+
+## Test
+
+```bash
+python tests/test_satchel.py
+```
+
+Extraction is tested against a fixture HTML file (`tests/fixtures/`), not
+the network — a real bug was caught this way during development: an
+ambiguous byline (`"By Jordan Rivers · September 2026"` in one text node)
+made trafilatura fold part of the date into the author field. Fixed by
+making the fixture look like well-structured real markup (byline and date
+as separate elements) rather than loosening the assertion.
+
+The capture listener is tested the same way it's actually used: a real
+`http.server.HTTPServer` runs in a background thread and gets real HTTP
+requests, including SSRF attempts against loopback and link-local
+addresses — checked with the *correct* token, since the interesting
+question is whether the guard holds once someone's past the door, not
+whether the door itself works.
+
+## What's deliberately not here yet
+
+No tagging, no folders, no read/unread state — a flat list plus full-text
+search covers the actual workflow (encounter → capture → search → read);
+add these when a flat list genuinely stops being enough, not before. No
+multi-device sync — one local file is the whole pitch, and sync is a
+separate, harder problem this project isn't trying to solve. No AI
+summarization, no embeddings, no recommendation engine: this is an
+archive of what you actually read, not a platform.
+
+MIT licensed.

satchel_reader-0.1.0/README.md

@@ -0,0 +1,163 @@
+# satchel
+
+**A tiny local archive of the actual things you read.**
+
+[![ci](https://github.com/MaXiMo000/satchel/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/satchel/actions/workflows/ci.yml)
+
+Most "read later" tools save a URL. The link rots, the site adds a
+paywall, or you're offline — and the thing you saved is gone. `satchel`
+fetches the page once, extracts the actual article text (not the nav, not
+the related-links box, not the footer), and stores it in one local SQLite
+file with real full-text search. No server, no account, no network needed
+to search what you've already saved.
+
+```
+$ satchel add https://example.com/some-article
+saved #4: Why Local-First Software Is Worth the Extra Effort
+
+$ satchel search "FTS5"
+#4    Why Local-First Software Is Worth the Extra Effort  (https://example.com/some-article)
+
+$ satchel read 4
+Why Local-First Software Is Worth the Extra Effort
+by Jordan Rivers
+
+Most reading tools save a link and call it done...
+```
+
+Save with one click instead of a terminal: `satchel serve` runs a local
+listener and prints a bookmarklet — click it on any page and that page is
+saved through the exact same pipeline `add` uses. See "Capture" below.
+
+## How
+
+- `fetch.py` — plain `urllib` GET. Stdlib, no dependency for the easy
+  part. Always rejects non-http(s) schemes; a URL that didn't come from
+  the person running satchel (see "Capture") is additionally checked
+  against loopback/private/link-local address space before and after
+  every redirect hop, not just the first one.
+- `capture.py` — fetch → extract → store, in one place. Both `add` and the
+  capture listener call this; there is exactly one add pipeline.
+- `extract.py` — wraps [trafilatura](https://github.com/adbar/trafilatura)
+  to pull title/author/main-text out of real HTML, correctly skipping
+  navigation, ads, and related-links boilerplate. Boilerplate-stripping is
+  exactly the kind of thing that looks fine on a hand-rolled test page and
+  breaks on the next real site's markup — not worth reimplementing.
+- `db.py` — one SQLite file, an FTS5 virtual table kept in sync with the
+  real table via triggers (external-content FTS5: the searchable index
+  isn't a second copy of the truth that can drift from the first).
+- `serve.py` — the local capture listener (below).
+
+## Install
+
+```bash
+pip install satchel-reader        # the command it installs is `satchel`
+```
+
+Or from a checkout, for development:
+
+```bash
+pip install -e .
+```
+
+## Use
+
+```bash
+satchel add <url>          # fetch, extract, save
+satchel list                # everything saved
+satchel search <query>      # full-text search
+satchel read <id>           # print an article's full text
+satchel serve                # one-click capture -- see below
+```
+
+All commands take `--db path/to/file.db`. The default, if you don't pass
+one, is `~/.local/share/satchel/satchel.db` (respecting `XDG_DATA_HOME`) —
+one stable location regardless of which directory you happen to run the
+command from, not `./satchel.db` in the current directory. Run
+`satchel --help` to see the exact resolved path on your machine.
+
+Saving the same article twice — via a tracking link, a shortener, or a
+plain `http://` URL the site itself upgrades to `https://` — is one
+duplicate, not two. `add` normalizes the URL it's given, follows
+redirects, and normalizes the *actual* address the server served before
+checking for a duplicate: it defers to what the server says, rather than
+guessing at a scheme policy.
+
+## Capture
+
+```bash
+$ satchel serve
+satchel capture listening on http://127.0.0.1:8765  (db: ~/.local/share/satchel/satchel.db)
+
+Drag this to your bookmarks bar, then click it on any page to save it:
+
+  javascript:fetch('http://127.0.0.1:8765/add?token=...&url='+encodeURIComponent(location.href))...
+
+^C to stop.
+```
+
+Drag the printed link to your bookmarks bar. Click it on any page while
+`serve` is running, and that page goes through the same fetch/extract/save
+pipeline as `satchel add` — no terminal required for the thing you do most
+often.
+
+**This changes the threat model, and it's handled, not ignored.** While
+`serve` is running, any tab open in your browser can send it a request —
+a browser's same-origin policy stops a page from *reading* a
+cross-origin response it wasn't granted, but not from *sending* the
+request in the first place. Without a shared secret, that would be an
+open invitation for any open tab to make satchel fetch an arbitrary URL.
+So: the listener only binds to `127.0.0.1`, a fresh token is generated
+every time you run `serve` and only ever appears in the bookmarklet you
+just dragged, and every captured URL is checked against loopback,
+private (RFC1918), link-local (this is what closes off
+`169.254.169.254`-style cloud metadata endpoints), reserved, and
+multicast address space — before the first request, and again on every
+redirect hop, since checking only the first hop would let a URL redirect
+somewhere private after passing the initial check.
+
+What that guard does *not* claim: it validates a hostname's DNS answer at
+the moment it's checked, it doesn't pin the connection to that exact
+resolved address. A DNS-rebinding attacker with a fast-expiring record
+could in principle still slip a private address past the check and have
+the actual connection re-resolve to it. Closing that fully means
+connecting to a pinned IP rather than by hostname — real added complexity
+for a personal tool's local listener. This is a deliberate, documented
+partial mitigation, not a claim that it's unbreakable.
+
+Direct `satchel add <url>` from your own terminal is **not** restricted
+this way — typing your own local dev server's URL to save a draft you're
+writing is a legitimate thing to do, and you are not a threat to
+yourself.
+
+## Test
+
+```bash
+python tests/test_satchel.py
+```
+
+Extraction is tested against a fixture HTML file (`tests/fixtures/`), not
+the network — a real bug was caught this way during development: an
+ambiguous byline (`"By Jordan Rivers · September 2026"` in one text node)
+made trafilatura fold part of the date into the author field. Fixed by
+making the fixture look like well-structured real markup (byline and date
+as separate elements) rather than loosening the assertion.
+
+The capture listener is tested the same way it's actually used: a real
+`http.server.HTTPServer` runs in a background thread and gets real HTTP
+requests, including SSRF attempts against loopback and link-local
+addresses — checked with the *correct* token, since the interesting
+question is whether the guard holds once someone's past the door, not
+whether the door itself works.
+
+## What's deliberately not here yet
+
+No tagging, no folders, no read/unread state — a flat list plus full-text
+search covers the actual workflow (encounter → capture → search → read);
+add these when a flat list genuinely stops being enough, not before. No
+multi-device sync — one local file is the whole pitch, and sync is a
+separate, harder problem this project isn't trying to solve. No AI
+summarization, no embeddings, no recommendation engine: this is an
+archive of what you actually read, not a platform.
+
+MIT licensed.

satchel_reader-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+# The command stays `satchel`; the distribution cannot -- that name is
+# already taken on PyPI by an unrelated, abandoned package (a single empty
+# "1.0" release from 2018, "Development Status :: 1 - Planning"). A
+# distribution name differing from the command it installs is ordinary
+# (python-dateutil installs `dateutil`).
+name = "satchel-reader"
+version = "0.1.0"
+description = "A local-first reading queue: saves the real article text, not just the link, and makes it genuinely offline-searchable."
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["reading", "offline", "full-text-search", "sqlite", "local-first"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing",
+]
+# trafilatura: boilerplate-stripping (nav/ads/footers) is exactly the kind
+# of thing that looks fine on one test page and breaks on the next real
+# site's markup -- not worth reimplementing. Fetching itself stays stdlib
+# (urllib) since a plain GET doesn't need a dependency.
+dependencies = ["trafilatura>=2.0"]
+
+urls.Homepage = "https://github.com/MaXiMo000/satchel"
+urls.Source = "https://github.com/MaXiMo000/satchel"
+urls.Issues = "https://github.com/MaXiMo000/satchel/issues"
+urls.Changelog = "https://github.com/MaXiMo000/satchel/releases"
+
+[project.scripts]
+satchel = "satchel.cli:main"
+
+[build-system]
+# 77 is the floor for PEP 639 (`license = "MIT"` as an SPDX expression). On
+# 68 a clean build environment can reject it -- learned the hard way in a
+# sibling project's own release workflow, fixed here before it bites this one.
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["satchel*"]

satchel_reader-0.1.0/satchel/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

satchel_reader-0.1.0/satchel/capture.py

@@ -0,0 +1,44 @@
+"""The one place "fetch, extract, store" happens -- used by both the CLI's
+`add` command and the local capture listener (`serve.py`), so there is
+exactly one add pipeline, not two that can drift apart.
+"""
+from __future__ import annotations
+
+import sqlite3
+
+from . import db
+from .extract import extract
+from .fetch import fetch, normalize_url
+
+
+def add_article(conn: sqlite3.Connection, raw_url: str, *, restrict_private_network: bool = False) -> dict:
+    """Fetch, extract, and store one article.
+
+    Returns {"ok": bool, "message": str, "id": int | None}.
+
+    restrict_private_network is False for direct CLI use (a human typing a
+    URL into their own terminal isn't a threat to themselves) and True for
+    the capture listener (see serve.py) -- there, the URL comes from
+    whatever page happened to be open in the browser, not from the person
+    running satchel, and that's exactly the boundary an SSRF guard exists
+    for.
+    """
+    url = normalize_url(raw_url)
+    try:
+        html, final_url = fetch(url, restrict_private_network=restrict_private_network)
+    except Exception as exc:  # noqa: BLE001 - a bad/unsafe fetch is a clear result, not a crash
+        return {"ok": False, "message": f"could not fetch {url}: {exc}", "id": None}
+    # Normalize again after following redirects -- the URL actually served
+    # (past a shortener, or an http->https upgrade) is the real dedup key.
+    url = normalize_url(final_url)
+
+    article = extract(html, url=url)
+    if article is None:
+        return {"ok": False, "message": f"could not extract article text from {url}", "id": None}
+
+    try:
+        article_id = db.add(conn, url, article["title"], article["author"], article["text"])
+    except sqlite3.IntegrityError:
+        return {"ok": False, "message": f"already saved: {url}", "id": None}
+
+    return {"ok": True, "message": f"saved #{article_id}: {article['title'] or url}", "id": article_id}

satchel_reader-0.1.0/satchel/cli.py

@@ -0,0 +1,99 @@
+"""satchel add <url> | search <query> | list | read <id> | serve"""
+from __future__ import annotations
+
+import argparse
+import sqlite3
+import sys
+
+from . import db
+from .capture import add_article
+from .serve import DEFAULT_PORT, serve
+
+
+def _do_add(args) -> int:
+    conn = db.connect(args.db)
+    result = add_article(conn, args.url)
+    print(result["message"], file=sys.stdout if result["ok"] else sys.stderr)
+    return 0 if result["ok"] else 1
+
+
+def _do_search(args) -> int:
+    conn = db.connect(args.db)
+    try:
+        rows = db.search(conn, args.query)
+    except sqlite3.OperationalError:
+        # FTS5's MATCH syntax (quotes, AND/OR/NOT, prefix *, column filters)
+        # is real query syntax a user can get wrong -- an unbalanced quote or
+        # a bare operator shouldn't surface as a Python traceback.
+        print(f"error: couldn't parse that search query: {args.query!r}", file=sys.stderr)
+        print("tip: quotes must be balanced; AND/OR/NOT/* are reserved words in FTS5 syntax", file=sys.stderr)
+        return 1
+    if not rows:
+        print("no matches")
+        return 0
+    for row in rows:
+        print(f"#{row['id']:<4} {row['title'] or row['url']}  ({row['url']})")
+    return 0
+
+
+def _do_list(args) -> int:
+    conn = db.connect(args.db)
+    rows = db.list_all(conn)
+    if not rows:
+        print(f"nothing saved yet — try: satchel add <url>  (db: {args.db})")
+        return 0
+    for row in rows:
+        print(f"#{row['id']:<4} {row['title'] or row['url']}  ({row['added_at']})")
+    return 0
+
+
+def _do_read(args) -> int:
+    conn = db.connect(args.db)
+    row = db.get(conn, args.id)
+    if row is None:
+        print(f"error: no article #{args.id}", file=sys.stderr)
+        return 1
+    print(row["title"] or row["url"])
+    if row["author"]:
+        print(f"by {row['author']}")
+    print()
+    print(row["text"])
+    return 0
+
+
+def _do_serve(args) -> int:
+    return serve(args.db, port=args.port)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="satchel")
+    parser.add_argument("--db", default=db.default_db_path(),
+                         help=f"path to the sqlite db (default: {db.default_db_path()})")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    add_p = sub.add_parser("add", help="fetch a URL, extract the article, save it")
+    add_p.add_argument("url")
+    add_p.set_defaults(func=_do_add)
+
+    search_p = sub.add_parser("search", help="full-text search saved articles")
+    search_p.add_argument("query")
+    search_p.set_defaults(func=_do_search)
+
+    list_p = sub.add_parser("list", help="list everything saved")
+    list_p.set_defaults(func=_do_list)
+
+    read_p = sub.add_parser("read", help="print a saved article's full text")
+    read_p.add_argument("id", type=int)
+    read_p.set_defaults(func=_do_read)
+
+    serve_p = sub.add_parser("serve", help="run a local listener + bookmarklet for one-click capture")
+    serve_p.add_argument("--port", type=int, default=DEFAULT_PORT,
+                          help=f"port to listen on (default: {DEFAULT_PORT})")
+    serve_p.set_defaults(func=_do_serve)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

satchel_reader-0.1.0/satchel/db.py

@@ -0,0 +1,101 @@
+"""SQLite storage with full-text search (FTS5), local-first: one file, no
+server, no network dependency to search what you've already saved.
+
+The FTS5 table is external-content (`content='articles'`): the searchable
+copy of the text isn't duplicated as the source of truth, and triggers keep
+it in sync on insert/update/delete so the two can't drift apart.
+"""
+from __future__ import annotations
+
+import os
+import pathlib
+import sqlite3
+import time
+
+
+def default_db_path() -> str:
+    """Where satchel.db lives if --db isn't given: one stable, per-user
+    location instead of "whatever directory you happened to run the
+    command from" -- the latter means `satchel add` from ~/Downloads and
+    `satchel list` from ~ silently look at two different, disconnected
+    databases, which is indistinguishable from data loss to a new user.
+    Respects XDG_DATA_HOME; falls back to the XDG default location.
+    """
+    data_home = os.environ.get("XDG_DATA_HOME") or str(pathlib.Path.home() / ".local" / "share")
+    return str(pathlib.Path(data_home) / "satchel" / "satchel.db")
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS articles (
+    id INTEGER PRIMARY KEY,
+    url TEXT UNIQUE NOT NULL,
+    title TEXT,
+    author TEXT,
+    text TEXT NOT NULL,
+    added_at TEXT NOT NULL
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS articles_fts USING fts5(
+    title, author, text, content='articles', content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS articles_ai AFTER INSERT ON articles BEGIN
+    INSERT INTO articles_fts(rowid, title, author, text)
+    VALUES (new.id, new.title, new.author, new.text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS articles_ad AFTER DELETE ON articles BEGIN
+    INSERT INTO articles_fts(articles_fts, rowid, title, author, text)
+    VALUES ('delete', old.id, old.title, old.author, old.text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS articles_au AFTER UPDATE ON articles BEGIN
+    INSERT INTO articles_fts(articles_fts, rowid, title, author, text)
+    VALUES ('delete', old.id, old.title, old.author, old.text);
+    INSERT INTO articles_fts(rowid, title, author, text)
+    VALUES (new.id, new.title, new.author, new.text);
+END;
+"""
+
+
+def connect(path: str) -> sqlite3.Connection:
+    parent = pathlib.Path(path).parent
+    if str(parent) not in ("", "."):
+        parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(path)
+    conn.row_factory = sqlite3.Row
+    conn.executescript(SCHEMA)
+    return conn
+
+
+def add(conn: sqlite3.Connection, url: str, title: str | None, author: str | None, text: str) -> int:
+    """Returns the article's id. Raises sqlite3.IntegrityError if the url
+    is already saved -- the caller decides what "already have this" means
+    to them (skip, re-fetch, update), this layer doesn't guess."""
+    cur = conn.execute(
+        "INSERT INTO articles (url, title, author, text, added_at) VALUES (?, ?, ?, ?, ?)",
+        (url, title, author, text, time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())),
+    )
+    conn.commit()
+    return cur.lastrowid
+
+
+def get(conn: sqlite3.Connection, article_id: int) -> sqlite3.Row | None:
+    return conn.execute("SELECT * FROM articles WHERE id = ?", (article_id,)).fetchone()
+
+
+def list_all(conn: sqlite3.Connection) -> list[sqlite3.Row]:
+    return conn.execute("SELECT id, url, title, author, added_at FROM articles ORDER BY added_at DESC").fetchall()
+
+
+def search(conn: sqlite3.Connection, query: str) -> list[sqlite3.Row]:
+    return conn.execute(
+        """
+        SELECT articles.id, articles.url, articles.title, articles.author, articles.added_at
+        FROM articles_fts
+        JOIN articles ON articles.id = articles_fts.rowid
+        WHERE articles_fts MATCH ?
+        ORDER BY rank
+        """,
+        (query,),
+    ).fetchall()