Add Project Gutenberg integration package

[sabraman]

Summary

Adds a Project Gutenberg integration package. The package exposes a static OPDS provider descriptor, so compatible firmware can show Project Gutenberg as a book catalog after the package is installed and enabled.

The provider uses Gutenberg's OPDS search endpoint and leaves book downloads to the existing OPDS browser flow.

The examples workflow now validates manifests against firmware 1.3.0 so packages can declare the compatibility floor needed for this integration host.

Validation

• python3 ../marginalia-sdk/tools/validate_manifest.py --profile publish --firmware-version 1.3.0 */manifest.json
• python3 ../marginalia-sdk/tools/build_package.py project-gutenberg-integration --profile publish --output dist --json

Summary by CodeRabbit

• New Features

  • Project Gutenberg integration available as an OPDS catalog provider — browse, search, and download public-domain EPUBs; appears in the OPDS picker and is descriptor-driven and read-only/sandboxed.

• Documentation

  • Added detailed docs describing behavior, installation, and expected runtime interactions for the Gutenberg provider.

• Chores

  • CI manifest validation now specifies a firmware version during checks.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: de582792-2864-48ab-bf7c-16ef871ad86b

📥 Commits

Reviewing files that changed from the base of the PR and between 9c21b75 and a3a1cfd.

📒 Files selected for processing (1)

• project-gutenberg-integration/README.md

✅ Files skipped from review due to trivial changes (1)

• project-gutenberg-integration/README.md

---

📝 Walkthrough

Walkthrough

This PR introduces a new Project Gutenberg OPDS integration package to the marginalia-examples repository. The integration provides a descriptor-driven catalog provider for Project Gutenberg books, defined through manifest metadata, entrypoint configuration, and OPDS catalog data. Documentation and CI validation are updated accordingly.

Changes

Project Gutenberg Integration Package

Layer / File(s)	Summary
Integration manifest and entrypoint contracts project-gutenberg-integration/manifest.json, project-gutenberg-integration/src/entrypoints.json	Manifest defines schema, Project Gutenberg metadata (v0.1.0), target device/firmware requirements (minimum 1.3.0), network permission, and entrypoint mappings. Entrypoints declare catalogProvider to expose static OPDS providers and shutdown to clean up on uninstall.
OPDS catalog configuration project-gutenberg-integration/src/opds.json	OPDS schema version 1 with a single Project Gutenberg provider entry specifying base URL and search URL template with {searchTerms} substitution.
Integration and project documentation project-gutenberg-integration/README.md, README.md	Package README documents installation, OPDS browser integration, search capability, and read-only catalog preset design. Main README adds the integration to the examples list with descriptor-driven description.
CI validation firmware version .github/workflows/ci.yml	Manifest validation step now explicitly passes --firmware-version 1.3.0 to validate against the integration's minimum firmware requirement.

---

🎯 2 (Simple) | ⏱️ ~12 minutes

---

🐰 A bunny hops through files with care,
Adding OPDS catalogs everywhere,
Project Gutenberg reads on the screen,
Static descriptors keep it clean,
No fuzzy execution here! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add Project Gutenberg integration package' directly and accurately summarizes the main change: introducing a new integration package for Project Gutenberg as an OPDS provider.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch project-gutenberg-opds

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

project-gutenberg-integration/README.md (1)

5-15: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add explicit “expected future runtime behavior” to complement the current behavior section.

This README only documents what works today; please add a short future-runtime section so the example clearly distinguishes current vs planned host/runtime capabilities.

As per coding guidelines, **/README.md: Example READMEs should state what works today versus expected future runtime behavior.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@project-gutenberg-integration/README.md` around lines 5 - 15, Add a new
"Expected future runtime behavior" section to the README to complement the
"Current behavior" list: clearly state planned host/runtime capabilities (e.g.,
future support for dynamic catalog updates, background metadata synchronization,
enhanced search/query routing, and any runtime permissions or sandbox
guarantees) and explicitly contrast them with today’s static behavior (the
package reads the static src/opds.json and remains a read-only catalog preset
with no arbitrary code execution); reference the OPDS browser picker and
existing OPDS download flow so readers can see which features are current vs
planned.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@project-gutenberg-integration/README.md`:
- Around line 5-15: Add a new "Expected future runtime behavior" section to the
README to complement the "Current behavior" list: clearly state planned
host/runtime capabilities (e.g., future support for dynamic catalog updates,
background metadata synchronization, enhanced search/query routing, and any
runtime permissions or sandbox guarantees) and explicitly contrast them with
today’s static behavior (the package reads the static src/opds.json and remains
a read-only catalog preset with no arbitrary code execution); reference the OPDS
browser picker and existing OPDS download flow so readers can see which features
are current vs planned.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f40bb1f0-3855-4b2f-abe2-23c260f38865

📥 Commits

Reviewing files that changed from the base of the PR and between 8016d2d and 9c21b75.

📒 Files selected for processing (6)

• .github/workflows/ci.yml
• README.md
• project-gutenberg-integration/README.md
• project-gutenberg-integration/manifest.json
• project-gutenberg-integration/src/entrypoints.json
• project-gutenberg-integration/src/opds.json

[sabraman]

Superseded by #9, which uses the generic catalog provider contribution contract.