[PR #1598] [MERGED] refactor(staffml): retire prod static-fallback; opt-in dev-only #9210

New Issue

GiteaMirror · 2026-05-03T01:28:34-05:00

GiteaMirror commented

2026-05-03 01:28:34 -05:00

📋 Pull Request Information

Original PR: https://github.com/harvard-edge/cs249r_book/pull/1598
Author: @profvjreddi
Created: 4/28/2026
Status: ✅ Merged
Merged: 4/28/2026
Merged by: @profvjreddi

Base: dev ← Head: cleanup/retire-static-fallback

📝 Commits (1)

fd873ec refactor(staffml): retire prod static-fallback; opt-in dev-only

📊 Changes

18 files changed (+177 additions, -1778 deletions)

View changed files

📝 .github/workflows/staffml-publish-live.yml (+12 -14)
📝 interviews/staffml/.env.example (+12 -5)
➖ interviews/staffml/scripts/DEPRECATED.md (+0 -36)
📝 interviews/staffml/scripts/validate-vault.py (+21 -220)
📝 interviews/staffml/src/app/plans/page.tsx (+7 -1)
📝 interviews/staffml/src/app/practice/page.tsx (+10 -1)
📝 interviews/staffml/src/lib/corpus-provider.tsx (+11 -8)
➖ interviews/staffml/src/lib/corpus-source.ts (+0 -56)
➖ interviews/staffml/src/lib/corpus-vault.ts (+0 -161)
📝 interviews/staffml/src/lib/corpus.ts (+54 -49)
📝 interviews/staffml/src/lib/hooks/useFullQuestion.ts (+49 -27)
➖ interviews/staffml/src/lib/hooks/useVaultQuestion.ts (+0 -49)
📝 interviews/staffml/src/lib/taxonomy.ts (+1 -1)
➖ interviews/staffml/src/lib/vault-fallback.ts (+0 -22)
➖ interviews/vault-cli/docs/CUTOVER_QA.md (+0 -210)
➖ interviews/vault/docs/RESUME_PLAN_2026-04-25.md (+0 -331)
➖ interviews/vault/docs/RESUME_PLAN_PHASE_D.md (+0 -273)
➖ interviews/vault/docs/RESUME_PLAN_RELEASE.md (+0 -314)

📄 Description

Summary

Retires the bundled corpus.json static-fallback path as a production safety net. The Cloudflare Worker is now the only data source for full question details in prod; on Worker error, the UI shows a "details unavailable" banner.
Keeps the static path as an OPT-IN local-dev affordance: set NEXT_PUBLIC_VAULT_FALLBACK=static and run vault build --legacy-json to materialize corpus.json on disk for offline work.
Cuts ~1,600 lines of dead cutover scaffolding (corpus-source.ts, corpus-vault.ts, useVaultQuestion.ts, vault-fallback.ts) and 5 stale planning docs.

Why

Post-cutover the Worker has been serving prod for ~1 week. The static fallback wasn't actually a usable safety net — corpus.json is a generated artifact whose prose details (common_mistake, realistic_solution, napkin_math) are blank in corpus-summary.json, so a Worker outage that triggered the fallback would silently degrade content rather than preserve it. Better to make the failure visible.

Changes

Behavior:

staffml-publish-live.yml no longer runs vault build --legacy-json; smoke tests rewritten against corpus-summary.json.
corpus.ts:getQuestionFullDetail no longer falls back to static on Worker error — throws so useFullQuestion can surface the error state.
shouldUseStaticDetails() no longer auto-triggers on localhost — explicit env var only.
useFullQuestion signature changed: Question | undefined → { question, status: 'loading' | 'ready' | 'error' }. Practice and plans pages updated to render an amber banner when status === 'error'.
taxonomy.ts now imports corpus-summary.json (was corpus.json).
validate-vault.py collapsed to sparse-only (per-question validation lives in vault check --strict).

Deletions (code, dead post-cutover):

interviews/staffml/src/lib/vault-fallback.ts
interviews/staffml/src/lib/corpus-source.ts
interviews/staffml/src/lib/corpus-vault.ts
interviews/staffml/src/lib/hooks/useVaultQuestion.ts

Deletions (stale docs):

interviews/staffml/scripts/DEPRECATED.md
interviews/vault-cli/docs/CUTOVER_QA.md
interviews/vault/docs/RESUME_PLAN_2026-04-25.md
interviews/vault/docs/RESUME_PLAN_PHASE_D.md
interviews/vault/docs/RESUME_PLAN_RELEASE.md

Test plan

npx tsc --noEmit clean
npm test — 37/37 passing
npm run build — all 15 static routes generated
CI: validate-dev workflow green
CI: validate-vault workflow green
Manual: dev preview shows the "details unavailable" banner when the Worker is unreachable (e.g. block the host in browser devtools)
Manual: setting NEXT_PUBLIC_VAULT_FALLBACK=static + running vault build --legacy-json still produces a working offline dev build

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/harvard-edge/cs249r_book/pull/1598 **Author:** [@profvjreddi](https://github.com/profvjreddi) **Created:** 4/28/2026 **Status:** ✅ Merged **Merged:** 4/28/2026 **Merged by:** [@profvjreddi](https://github.com/profvjreddi) **Base:** `dev` ← **Head:** `cleanup/retire-static-fallback` --- ### 📝 Commits (1) - [`fd873ec`](https://github.com/harvard-edge/cs249r_book/commit/fd873ecf211116acd69d939ce6dc0430685320da) refactor(staffml): retire prod static-fallback; opt-in dev-only ### 📊 Changes **18 files changed** (+177 additions, -1778 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/staffml-publish-live.yml` (+12 -14) 📝 `interviews/staffml/.env.example` (+12 -5) ➖ `interviews/staffml/scripts/DEPRECATED.md` (+0 -36) 📝 `interviews/staffml/scripts/validate-vault.py` (+21 -220) 📝 `interviews/staffml/src/app/plans/page.tsx` (+7 -1) 📝 `interviews/staffml/src/app/practice/page.tsx` (+10 -1) 📝 `interviews/staffml/src/lib/corpus-provider.tsx` (+11 -8) ➖ `interviews/staffml/src/lib/corpus-source.ts` (+0 -56) ➖ `interviews/staffml/src/lib/corpus-vault.ts` (+0 -161) 📝 `interviews/staffml/src/lib/corpus.ts` (+54 -49) 📝 `interviews/staffml/src/lib/hooks/useFullQuestion.ts` (+49 -27) ➖ `interviews/staffml/src/lib/hooks/useVaultQuestion.ts` (+0 -49) 📝 `interviews/staffml/src/lib/taxonomy.ts` (+1 -1) ➖ `interviews/staffml/src/lib/vault-fallback.ts` (+0 -22) ➖ `interviews/vault-cli/docs/CUTOVER_QA.md` (+0 -210) ➖ `interviews/vault/docs/RESUME_PLAN_2026-04-25.md` (+0 -331) ➖ `interviews/vault/docs/RESUME_PLAN_PHASE_D.md` (+0 -273) ➖ `interviews/vault/docs/RESUME_PLAN_RELEASE.md` (+0 -314) </details> ### 📄 Description ## Summary - Retires the bundled `corpus.json` static-fallback path as a production safety net. The Cloudflare Worker is now the only data source for full question details in prod; on Worker error, the UI shows a "details unavailable" banner. - Keeps the static path as an OPT-IN local-dev affordance: set `NEXT_PUBLIC_VAULT_FALLBACK=static` and run `vault build --legacy-json` to materialize `corpus.json` on disk for offline work. - Cuts ~1,600 lines of dead cutover scaffolding (`corpus-source.ts`, `corpus-vault.ts`, `useVaultQuestion.ts`, `vault-fallback.ts`) and 5 stale planning docs. ## Why Post-cutover the Worker has been serving prod for ~1 week. The static fallback wasn't actually a usable safety net — `corpus.json` is a generated artifact whose prose `details` (`common_mistake`, `realistic_solution`, `napkin_math`) are blank in `corpus-summary.json`, so a Worker outage that triggered the fallback would silently degrade content rather than preserve it. Better to make the failure visible. ## Changes **Behavior:** - `staffml-publish-live.yml` no longer runs `vault build --legacy-json`; smoke tests rewritten against `corpus-summary.json`. - `corpus.ts:getQuestionFullDetail` no longer falls back to static on Worker error — throws so `useFullQuestion` can surface the error state. - `shouldUseStaticDetails()` no longer auto-triggers on `localhost` — explicit env var only. - `useFullQuestion` signature changed: `Question | undefined` → `{ question, status: 'loading' | 'ready' | 'error' }`. Practice and plans pages updated to render an amber banner when `status === 'error'`. - `taxonomy.ts` now imports `corpus-summary.json` (was `corpus.json`). - `validate-vault.py` collapsed to sparse-only (per-question validation lives in `vault check --strict`). **Deletions (code, dead post-cutover):** - `interviews/staffml/src/lib/vault-fallback.ts` - `interviews/staffml/src/lib/corpus-source.ts` - `interviews/staffml/src/lib/corpus-vault.ts` - `interviews/staffml/src/lib/hooks/useVaultQuestion.ts` **Deletions (stale docs):** - `interviews/staffml/scripts/DEPRECATED.md` - `interviews/vault-cli/docs/CUTOVER_QA.md` - `interviews/vault/docs/RESUME_PLAN_2026-04-25.md` - `interviews/vault/docs/RESUME_PLAN_PHASE_D.md` - `interviews/vault/docs/RESUME_PLAN_RELEASE.md` ## Test plan - [x] `npx tsc --noEmit` clean - [x] `npm test` — 37/37 passing - [x] `npm run build` — all 15 static routes generated - [ ] CI: validate-dev workflow green - [ ] CI: validate-vault workflow green - [ ] Manual: dev preview shows the "details unavailable" banner when the Worker is unreachable (e.g. block the host in browser devtools) - [ ] Manual: setting `NEXT_PUBLIC_VAULT_FALLBACK=static` + running `vault build --legacy-json` still produces a working offline dev build 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

GiteaMirror added the pull-request label 2026-05-03 01:28:34 -05:00

GiteaMirror closed this issue

2026-05-03 01:28:38 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/cs249r_book#9210