M1 slice 4: amicode service — paper library (GET/POST /amicode/library)

[aarontrowbridge]

Part of #451 (M1 slice 4; not closing).

What's here

Two more fork routes ported (15 of 31 total): GET/POST /amicode/library — the user's uploaded-paper library. Ported verbatim (pure Node): listing ordered by added_ms, upload with PDF-only filename sanitization, 30 MB cap, %PDF- magic check, and the refreshed-listing return so the client renders in one round-trip.

Parity proof

Golden fixtures grow 35 → 40 entries (seeded listing newest-first, valid upload + refreshed listing, bad_filetype refusal, missing-data_b64 refusal, post-upload state). Seeded papers get pinned mtime epochs; a route-**written** paper's added_ms is wall-clock by nature (the upload happens mid-arc), so the replay normalizes post-seed timestamps to <NOW> on both sides — the recorder stamps meta.seededAt for exactly this rule, mirroring the existing <ELAPSED> discipline.

Verification

Contract suite 43/43; typecheck clean.

Summary by CodeRabbit

• New Features

  • Added a library for storing and browsing uploaded PDF papers.
  • Added endpoints for listing library papers and uploading new files.
  • Library entries are ordered by most recent update.
  • Uploaded files receive sanitized filenames and refreshed listings after successful uploads.

• Bug Fixes

  • Added validation for PDF file type, missing upload data, and files exceeding 30 MB.
  • Invalid uploads now return clear JSON-formatted errors.

[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: f325000d-f623-48a1-a8f0-966001707fee

📥 Commits

Reviewing files that changed from the base of the PR and between b75a4d3 and ad3a971.

📒 Files selected for processing (6)

• packages/extension/scripts/amicode_fixture_seed.mjs
• packages/extension/scripts/record_amicode_fixtures.mjs
• packages/extension/src/amicode_service/index.ts
• packages/extension/src/amicode_service/library.ts
• packages/extension/test/amicode_service_contract.test.ts
• packages/extension/test/fixtures/amicode/golden.json

Included review availability: Your plan provides up to 10 included reviews per hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

The extension adds PDF library listing and upload routes. It validates filenames and PDF data, limits uploads to 30 MB, seeds deterministic library fixtures, and normalizes replay timestamps.

Changes

PDF library service

Layer / File(s)	Summary
Deterministic library fixture setup packages/extension/scripts/amicode_fixture_seed.mjs, packages/extension/scripts/record_amicode_fixtures.mjs	The sandbox seeds two timestamped PDF files, exposes AMICODE_LIBRARY_DIR, and records seededAt. Fixture recording covers listing, valid uploads, invalid file types, missing data, and post-upload state.
Library storage and route handling packages/extension/src/amicode_service/library.ts, packages/extension/src/amicode_service/index.ts	The service lists PDFs by modification time and validates base64 PDF uploads. It sanitizes filenames, enforces a 30 MB limit, writes files, and registers GET and POST /amicode/library routes.
Contract replay and golden responses packages/extension/test/amicode_service_contract.test.ts, packages/extension/test/fixtures/amicode/golden.json	Contract replay captures seed timestamps and normalizes newly created paper timestamps. Golden responses include library scenarios and updated sandbox-dependent values.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to ad3a9

The library routes are a localized change with clean contract and typecheck results; no actionable merge-blocking risk remains beyond normal checks.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant AmicodeService
  participant LibraryService
  participant LibraryFilesystem
  Client->>AmicodeService: GET or POST /amicode/library
  AmicodeService->>LibraryService: listLibrary or saveLibraryFile
  LibraryService->>LibraryFilesystem: read, validate, or write PDF data
  LibraryFilesystem-->>LibraryService: files or write result
  LibraryService-->>AmicodeService: JSON listing or error
  AmicodeService-->>Client: HTTP response

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 5 files. (1 skipped: 1 unsupported.)	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the paper library feature and the added GET/POST /amicode/library routes.
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.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 451-m1-slice-4-library

---

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