78 lines
4.4 KiB
Markdown
78 lines
4.4 KiB
Markdown
# Publish Legacy PDFs Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Publish all 332 permission-cleared legacy PDFs through a searchable Starlight archive without changing their bytes.
|
|
|
|
**Architecture:** Public files retain their DokuWiki-derived hierarchy under `public/media/legacy-dokuwiki/`. A generated Markdown catalog and explicit supplemental-content registry make the collection discoverable while keeping the original 29-page migration manifest unchanged.
|
|
|
|
**Tech Stack:** Astro 7, Starlight 0.41, Node.js 22, Markdown, Node test runner, Poppler `pdfinfo`.
|
|
|
|
## Global Constraints
|
|
|
|
- Publish exactly the 332 records in `docs/pdf-inventory.tsv`.
|
|
- Preserve PDF bytes, relative namespace paths, sizes, and SHA-256 checksums.
|
|
- Record the maintainer's 2026-08-03 permission confirmation.
|
|
- Preserve unrelated working-tree changes.
|
|
- Do not deploy or push.
|
|
|
|
---
|
|
|
|
### Task 1: Define the supplemental publication contract
|
|
|
|
**Files:**
|
|
- Create: `docs/supplemental-content.json`
|
|
- Modify: `scripts/audit-content.mjs`
|
|
- Modify: `tests/content-audit.test.mjs`
|
|
|
|
**Interfaces:**
|
|
- Consumes: original destinations from `docs/migration-manifest.json`
|
|
- Produces: an allowlist of `{ destination, source, category }` records loaded by `auditContent`
|
|
|
|
- [ ] **Step 1: Write failing audit tests** proving a declared supplemental page is accepted, an undeclared page is rejected, and a registry destination missing from disk is rejected.
|
|
- [ ] **Step 2: Run `node --test tests/content-audit.test.mjs`** and confirm the declared supplemental-page test fails.
|
|
- [ ] **Step 3: Add `docs/supplemental-content.json`** with the PDF archive destination and implement strict registry loading and validation in `scripts/audit-content.mjs`.
|
|
- [ ] **Step 4: Run `node --test tests/content-audit.test.mjs`** and confirm all content-audit tests pass.
|
|
|
|
### Task 2: Publish and verify the recovered files
|
|
|
|
**Files:**
|
|
- Move: `to-be-studied/legacy-pdfs/study/**` to `public/media/legacy-dokuwiki/study/**`
|
|
- Modify: `docs/pdf-inventory.tsv`
|
|
- Modify: `docs/pdf-publication-review.tsv`
|
|
- Modify: `docs/pdf-publication-review.md`
|
|
- Modify: `docs/pdf-archive.md`
|
|
- Modify: `to-be-studied/README.md`
|
|
- Create: `scripts/verify-pdf-archive.mjs`
|
|
- Create: `tests/pdf-archive.test.mjs`
|
|
|
|
**Interfaces:**
|
|
- Consumes: current inventory rows and staged PDFs
|
|
- Produces: byte-identical public files plus a verifier that returns counts and throws on missing files, size mismatches, checksum mismatches, duplicate public paths, or malformed PDF signatures
|
|
|
|
- [ ] **Step 1: Write failing verifier tests** using temporary valid-signature fixtures for success, missing-file, byte-count, and checksum cases.
|
|
- [ ] **Step 2: Run `node --test tests/pdf-archive.test.mjs`** and confirm failure because the verifier does not exist.
|
|
- [ ] **Step 3: Implement the verifier** and update inventory/review documentation to public URLs and permission-confirmed status.
|
|
- [ ] **Step 4: Move each inventoried file with an explicit source/destination mapping**, leaving no recovered PDF in the non-public staging directory.
|
|
- [ ] **Step 5: Run the verifier and `pdfinfo` over all public PDFs**; expect exactly 332 successes and matching hashes.
|
|
|
|
### Task 3: Add the searchable archive page
|
|
|
|
**Files:**
|
|
- Create: `src/content/docs/previous-exams-and-documents.md`
|
|
- Modify: `src/config/sidebar.mjs`
|
|
- Modify: `src/content/docs/bachelor/index.md`
|
|
- Modify: `src/content/docs/master-ai/index.md`
|
|
- Modify: `src/content/docs/master-dsdm/index.md`
|
|
- Modify: `tests/content-audit.test.mjs`
|
|
|
|
**Interfaces:**
|
|
- Consumes: the normalized `docs/pdf-inventory.tsv`
|
|
- Produces: `/previous-exams-and-documents/` with exactly one working link per inventory record
|
|
|
|
- [ ] **Step 1: Write failing tests** for archive frontmatter, sidebar registration, programme links, link count, and one-to-one inventory URL coverage.
|
|
- [ ] **Step 2: Run the focused tests** and confirm they fail before the page exists.
|
|
- [ ] **Step 3: Generate the archive Markdown** grouped by programme/course namespace with human-readable labels and original filenames.
|
|
- [ ] **Step 4: Add sidebar and programme links** and replace wording that still calls the recovered archive non-public.
|
|
- [ ] **Step 5: Run `npm run verify`** and confirm the full site, rendered output, and internal links pass with all 332 PDFs present in `dist/`.
|
|
|