feat(api): library read endpoints — GET /libraries, GET /libraries/:id/specs

[thewrz]

Why

The examples/web_ui_demo board cannot bootstrap on main: creating its default project requires a source library id (POST /projects mandates sourceLibraryIds ≥1 by design, #94), and seeded library UUIDs are only discoverable by listing them. The DB layer already had listLibraries(); these were just never exposed over REST. First of the roadmap-first backend gaps that unblock the demo (spec: docs/superpowers/specs/2026-06-19-demo-backend-conformance.md).

What

Two read endpoints, mirroring the existing GET /conventions list pattern and ADR-015 D1 (libraries are first-class):

• GET /libraries → ApiResponse<Library[]>, ordered by tier then name (reuses listLibraries()).
• GET /libraries/:id/specs → ApiResponse<LibrarySpec[]> with each spec's paragraph nodeCount; 404 on unknown library, 400 on malformed id. New listLibrarySpecs query.

openapi.yaml documents both with Library/LibrarySpec schemas; the contract gate response-covers them.

Testing

• Unit/integration: src/api/libraries.integration.test.ts (list returns seeded built-ins ordered; specs list returns nodeCount; 404 + 400) — 5/5 pass
• Contract gate green (route↔spec coverage + response-schema validation)
• pnpm lint clean (eslint + tsc + prettier)
• CI green

⚠️ Note: src/parser/docx/cpi.integration.test.ts fails on origin/main independently of this PR (CPI source-inference regression) — not introduced here.

🤖 Co-authored by Claude Opus 4.8. Closes #226.

Summary by CodeRabbit

New Features

• Added endpoints to list all available libraries, organized by tier and name
• New ability to retrieve all specs within a library, including section, title, and node count information
• Improved error handling for invalid library identifiers and missing resources

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds GET /libraries and GET /libraries/{id}/specs REST endpoints. A new listLibrarySpecs DB query joins specs to paragraphs to compute nodeCount. Two Express handlers with UUID validation and 400/404/500 error handling are wired into the router. OpenAPI schemas and endpoint definitions are added, and integration tests cover ordering, nodeCount, and error cases.

Changes

Library Read Endpoints

Layer / File(s)	Summary
LibrarySpec type and listLibrarySpecs query src/db/queries/libraries.ts, src/db/index.ts	Adds the LibrarySpec interface and listLibrarySpecs function that joins specs to paragraphs, computes nodeCount via COUNT, orders by section, and re-exports both from the DB index.
Express handlers and router wiring src/api/libraries.ts, src/api/router.ts	Adds parseLibraryId (zod UUID validation), listLibrariesHandler, and listLibrarySpecsHandler with 400/404/500 error handling. Registers /libraries and /libraries/:id/specs GET routes.
OpenAPI contract openapi.yaml	Documents both GET operations with SuccessResponse envelopes and error responses. Adds Library and LibrarySpec component schemas including nullable owner/parentLibraryId and nodeCount.
Integration tests src/api/libraries.integration.test.ts, src/api/contract.integration.test.ts	New test suite covers GET /libraries (tier presence, sort order) and GET /libraries/:id/specs (nodeCount, empty case, 404, 400). Contract test's response-covered set and schema-validation tests are extended for both endpoints.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• wrzonance/SpecR#212: Introduced the contract/route↔spec gate infrastructure in src/api/contract.integration.test.ts that this PR extends by registering the new /libraries and /libraries/{id}/specs operations as response-covered endpoints.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 62.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding two new library read endpoints (GET /libraries and GET /libraries/:id/specs) to the API.
Linked Issues check	✅ Passed	The PR fully implements all coding requirements from issue #226: both endpoints are added with correct signatures, responses are documented in openapi.yaml, integration tests verify listed libraries and node counts, and no linting violations are introduced.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the stated objectives: API endpoints, database queries, OpenAPI schemas, integration tests, and router registration are all necessary for implementing the two library read operations.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/api-library-read

---

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