Ebooks

Find every ebook on your machine, detect its bibliographic metadata, resolve authors and titles against Wikipedia + Wikidata, and render a browsable HTML page linking each file to its location on disk. WHAT IT DOES

Turns a filesystem full of ebooks into a catalogued, browsable library. It walks the tree for ebook files, derives author/title/ISBN/publish dates from the path, filename and file contents, then resolves each author and title against Wikipedia and Wikidata so the rendered pages show canonical names — and only links names actually classified as people. The scan is resumable: each run continues from where the last stopped and stops itself after a five-minute budget, so a million-file home directory is catalogued across several runs without ever re-walking ground already covered. It fetches nothing itself — all network I/O is delegated (transitively) to @svendowideit/web-cache, which paces and caches, so re-analysing an already-resolved name costs no network traffic.

It can also publish those pages over HTTP(S): when @svendowideit/caddy is installed, the workflow's final step declares a Caddy file_server route serving the render directory at ebooks.<host>.<domain>, reading the host and domain from the caddy model that already owns this machine. The route lives on a dedicated ebooks-caddy model that caddy merges with the models it already runs, and caddy derives the A record and certificate for the name — so nothing is hardcoded and nothing is duplicated. With caddy absent the step skips with a log and the pages remain on disk.

INSTALL

swamp extension pull @svendowideit/ebooks

DEPENDENCIES

@svendowideit/web-cache, @svendowideit/wikipedia, and @svendowideit/wikidata, declared in this manifest's dependencies: — the single swamp extension pull above installs them automatically. Nothing is installed on the host.

@svendowideit/caddy is an optional dependency, declared in this manifest's optionalDependencies:. It is not installed for you: pull it separately to enable the HTTP(S) serving step, which is skipped when it is absent.

RUN

# Scan, detect, resolve, and render — re-run to continue a long scan in
# five-minute increments; the HTML page regenerates each time.
swamp workflow run @svendowideit/ebook-scan

# Point the scan at a specific directory instead of $HOME.
swamp workflow run @svendowideit/ebook-scan --input root=/home/me/books

# Re-detect and re-render the already-found paths without re-walking the
# filesystem — use after changing metadata detection or rendering.
swamp workflow run @svendowideit/ebook-scan --input skipScan=true

# Raise the per-call origin-fetch cap to drain the resolution backlog
# faster (cached hits do not count).
swamp workflow run @svendowideit/ebook-scan --input maxFetches=50

# Read the discovered ebooks and their detected metadata as JSON.
swamp data get ebook-scan state --json

# (Re)declare the Caddy file_server route on its own — normally the last
# step of @svendowideit/ebook-scan does this for you. Needs
# @svendowideit/caddy and a caddy model that already owns this machine; it
# serves the render directory at ebooks.<host>.<domain>.
swamp model method run ebooks ensure-caddy-serve

CONFIGURE

All workflow inputs are optional:

root               Filesystem path to scan          (default ~)
outputPath         HTML listing output path          (default ~/.swamp/ebooks/ebooks.html)
authorsOutputPath  Author-index output path          (default ~/.swamp/ebooks/index.html)
title              Page title                        (default "Ebooks")
cacheDir           Shared web-cache directory        (default ~/.swamp/web-cache)
maxFetches         Origin fetches per get-many call  (default 20)
skipScan           Skip the directory scan           (default false)

The ebooks model also reads global arguments:

extensions           Ebook file extensions to match
excludePatterns      Directory names to skip
cacheDir             Shared web-cache directory
caddyModelName       @svendowideit/caddy model to read the ebooks host and
                     domain from, for ensure-caddy-serve
                     (default: auto-discover the model owning this machine)
caddyRouteHostname   Override the served hostname
                     (default: ebooks.<host>.<domain>)

See the README for values and defaults.

WHAT IT INSTALLS

Nothing on the host — no services, daemons, cron triggers, or webhooks. It reads the filesystem and the shared web-cache and writes swamp data plus the two HTML files named by outputPath and authorsOutputPath.

If @svendowideit/caddy is installed and a caddy model already owns this machine, the final ebook-scan step also declares a Caddy file_server route serving that directory at ebooks.<host>.<domain>, on a dedicated ebooks-caddy model that caddy merges with the models it already runs. Nothing new is installed by ebooks itself — no service, no daemon.