Make directory libraries reachable through the REST API

[koppor]

Related issues and pull requests

Phase 8 of the "directory as library" plan (PLAN.md), stacked on #744 (base branch directory-convert). No issue is closed by this PR.

PR Description

🤖 jabsrv (JabRef's REST API) identified every open library by its .bib path. A directory library has no .bib path — only a root directory — so it was invisible to the entire HTTP API: missing from GET /libraries, missing from the libraries:query existence check, and un-addressable for reading (GET /libraries/{id}/entries…) or adding (POST /libraries/{id}/entries) entries.

The whole gap was one root cause in ServerUtils, whose three id helpers (openLibraryIds, getLibraryPath, getBibDatabaseContext) all keyed off getDatabasePath() and dropped/rejected empty-path contexts. They now derive a library's id from getDatabasePath().or(getDirectoryLibraryRoot()) — the same identity the GUI session store already uses — so listing, the existence-check query, entry reads, and appends all resolve a directory library by its root. The GUI-side append matcher (selectLibraryTab) gains the same fallback, so an append targets the open directory-library tab by its root; the entries then flow through the existing write-back into sidecars and the .bib mirror (imports fire EntriesEventSource.LOCAL, which write-back already handles). No new module dependency — getDirectoryLibraryRoot() is on the model's BibDatabaseContext.

Scope note: this fixes GUI mode (JabMap and the browser extension talk to the running JabRef GUI, where directory-library tabs are open databases). Standalone jabsrv-cli still serves only the .bib files given on its command line — serving a bare directory there is separate future work, and adds require the GUI regardless.

jabref-contrib-policy:4.2:reviewed​:ok

Analogies

Like honey the label finally lists, the directory library was always in the pantry but unnamed on the jar; now the index reads it out. Like a chocolate assortment where one praline had no map coordinate, every piece can now be pointed to and picked. And like the moon answering to a name in the almanac, the library was always orbiting — it just needed an entry in the tables to be found and hailed.

Steps to test

1. Start JabRef with the HTTP server enabled and open a folder as library (so a directory-library tab is open).
2. GET http://localhost:23119/libraries — the directory library now appears in the list (id = <folder-name>-<hash>).
3. POST http://localhost:23119/libraries:query with {"queries": ["doi = \"…\""]} — matches in the directory library are returned (the browser-extension / JabMap existence check).
4. POST http://localhost:23119/libraries/<that-id>/entries with a BibTeX body — the entry lands in the directory library, and a Markdown sidecar plus the .bib mirror update on disk.

(No user-visible UI change, so no screenshot — the behaviour is exercised by ServerUtilsTest and the steps above.)

Live verification (running JabRef + HTTP server)

Enabled the HTTP server, opened a folder as library (demo-library), and drove the real API:

• GET /libraries → the directory library now appears: "demo-library-275b20a6" (a .bib-only listing before this PR).
• POST /libraries:query {"queries":["title = \"ZygOS: Achieving Low Tail Latency\""]} → {"libraryId":"demo-library-275b20a6","entryId":"zygos"} (existence check hits the directory library); a non-matching query returns [].
• GET /libraries/demo-library-275b20a6/entries/sidecar2026 → entry preview resolves.
• POST /libraries/demo-library-275b20a6/entries with a BibTeX body → 204; the entry lands in the directory library, and write-back creates the Markdown sidecar Rest2026 - Added Over the REST API.md (filename pattern applied) and updates the .bib mirror. A follow-up libraries:query then finds the freshly added Rest2026 — the full loop closes.

Known cosmetic follow-up (not fixed here): the interactive import dialog's "Library to import into" selector shows untitled for a directory library (it derives the name from the .bib path); the import still targets the correct directory-library context.

AI usage

Claude Code (model claude-opus-4-8).

AI CHECKLIST.md walkthrough

• No == null / != null checks.
• No Objects.requireNonNull(...).
• [/] New classes annotated with @NullMarked — no new production classes (methods added to existing ServerUtils).
• Optional consumed with map / or / flatMap / orElse(false) — no isPresent() + get() (in fact this PR removes a getDatabasePath().get() block).
• [/] StringUtil.isBlank(...) — no blank checks added.
• No catch (Exception e).
• No throw new RuntimeException(...).
• [/] Logged exceptions last — no new logging.
• [/] Withers for new BibEntry — none built.
• Modern Java (Optional.or, streams).
• [/] Precompiled regex — none.
• [/] No new Thread() — none.
• No commented-out code, no trivial comments, no AI-disclosure comments.
• Markdown Javadoc (///) with Markdown syntax.
• [/] Localized user-facing text — none added (id strings, not shown to users).
• Security: the existing HtmlEscapers on the 404 id message is preserved.
• Behavior change in jabsrv covered by ServerUtilsTest (listing, path resolution, context resolution, unknown id).
• Tests assert with assertEquals/assertSame, plain JUnit, no @DisplayName, no caught exceptions, @TempDir.
• ./gradlew :jabsrv:test green locally (full suite, no regressions); :jabsrv:compileJava + :jabgui:compileJava green.
• ./gradlew checkstyleMain checkstyleTest green for touched modules.
• ./gradlew modernizer green.
• ./gradlew :rewriteRun applied (no diff).
• ./gradlew traceRequirements green (req~directory-library.rest-api~1 covered impl + utest).
• npx markdownlint-cli2 green on the changed Markdown.
• [/] Docker IntelliJ formatter — not available; CI format job is the backstop.

Checklist

• I own the copyright of the code submitted and I license it under the MIT license
• If AI tools were used, I disclosed them in the "AI usage" section and reviewed, understood, and take full ownership of all AI-generated code
• I manually tested my changes in running JabRef (see "Live verification" above: enabled the HTTP server, listed/queried/read/added against an open directory library, and confirmed the sidecar + mirror were written on disk)
• I added JUnit tests for changes (if applicable)
• [/] I added screenshots in the PR description (if change is visible to the user) — no UI change
• [/] I added a screenshot in the PR description showing a library with a single entry with me as author and as title the issue number
• [/] I described the change in CHANGELOG.md — the directory-library feature is unreleased, so no user-visible change against any released version
• I checked the user documentation — the docs PR is the pending phase-5 step covering the whole feature

🤖 Generated with Claude Code