magicciv/.project/history/20260417_guide_web_deploy_audit.md

p2-09 guide-web-deploy audit — 2026-04-17

Scope: verify the four acceptance bullets for the guide web app deploy pipeline. Work was done from the EDIT host; the guide build was run on the apricot RUN host per CLAUDE.md Two-Host Workflow (pnpm + node + wasm-pack live on apricot). No compiled WASM .wasm or pkg/ artifacts were rsync'd EDIT→RUN.

What already existed

• public/games/age-of-dwarves/guide/ — React + Vite + TypeScript app, pnpm workspace member @magic-civilization/guide-age-of-dwarves.
• src/packages/guide/ — shared component library @magic-civ/guide-engine.
• src/simulator/build-wasm.sh — produces src/simulator/pkg/ for the guide's @magic-civ/physics-rs alias.
• vite.config.ts — path aliases, WASM plugin, port 5800 dev server.
• tsconfig.json — mirrored path aliases, strict mode.

Gaps fixed this pass

1. Broken import @/game.json flagged by prior teammate reports. Root cause: @ alias resolves to src/, but game.json lives at public/games/age-of-dwarves/game.json — one directory above the guide's src/. Fix: changed to relative path '../../../game.json' in public/games/age-of-dwarves/guide/src/app/guide-data.ts. Verified the file resolves correctly from disk.

2. Five missing Toc re-exports in @magic-civ/guide-engine. Consumers in public/games/age-of-dwarves/guide/src/components/nav/ import TableOfContents, TocEntry, SimulationArrow, TocLink, TocIcon from the package barrel — none were listed in src/packages/guide/src/index.ts. Added re-exports for all five plus the NavItem / NavGroup / NavEpisodeHeader types consumed by the same component tree.

3. tools/deploy-guide.sh (new, 87 LOC) — four modes: build # pnpm --filter … build → dist/ serve [port] # local python http.server preview (default 5801) apricot [ver] # rsync dist/ → apricot:~/public/guide// zip [ver] # archive dist/ into .local/build/guide/guide-…zip External hosting target is unresolved (no GitHub Pages / S3 / Cloudflare Pages decision committed); the zip mode produces an artifact that can be handed to whichever public host wins, and apricot mode gives the team a LAN-reachable preview today. A TODO-line in the script header flags the external-host gap.

Blocker found (out of devops scope)

@magic-civ/guide-engine has drifted systematically from its consumer. After applying the fixes above, the build still fails; pnpm typecheck reports 32 TS errors across 32 files. Missing barrel exports include:

GuideLayout, PreferencesProvider, RaceThemeProvider, EpisodeProvider,
usePreferences, usePreferencesReroll, resolveGender, resolveRace,
ResolvedPreferences, ThemePreview, PageHeading, PageSubtitle, DataTable,
TechTreeGraph, Highlight, QualityTierDef, Lens, LensCategory, LensUnlock,
SPECIES_LIBRARY, applyObservationLens, SpeciesObservationLens,
ObservedSpecies, EpisodeDwarvesPage, EpisodeKzzkytPage, EpisodeElvesPage,
TheHivePlanetPage, SilvandelPage, SpellsPage, MagicSchoolsPage,
ArchonsPage, DisciplinesPage, LeyLinesPage

Plus two type incompatibilities in src/data/game.ts where Unit[] / Building[] are being assigned to ResourceWithEncyclopedia[] — structural type drift, not a missing export.

This is craft work for the guide-web agent (per .claude/agents/ registry: "Player guide web app: React pages, components, climate sim, Vitest"), not devops infrastructure. Deployment tooling cannot be verified against a broken build; the deploy script ships ready, and the build-pass verification defers to the drift fix.

Empirical verification on apricot

ssh lilith@apricot.local 'cd ~/Code/@projects/@magic-civilization/src/simulator && bash build-wasm.sh'
# → wasm-pack finished in ~50s, 8 warnings (all missing-docs), no errors.
# → pkg/magic_civ_physics{.js,.d.ts,_bg.wasm,_bg.wasm.d.ts,_bg.js} emitted.

ssh lilith@apricot.local 'cd ~/Code/@projects/@magic-civilization && \
    pnpm --filter @magic-civilization/guide-age-of-dwarves build'
# → 3430 modules transformed, then Build failed on missing @magic-civ/guide-engine
#   exports. Transform phase proved guide-data.ts fix works; rollup phase revealed
#   the drift.

ssh lilith@apricot.local 'cd ~/Code/@projects/@magic-civilization && \
    pnpm --filter @magic-civilization/guide-age-of-dwarves typecheck'
# → 32 errors across 32 files. Cited above.

Status call

Moving partial → partial (no status change). The Objective Status Integrity rule forbids done when the first acceptance bullet ("zero TypeScript errors") is measurably false at 32 errors. Fix is scoped to guide-web, not devops-engineer. Dashboard citation for this pass shows the deploy script + one-level-deep import fix + partial re-exports; full done unblocks after guide-web closes the drift.

---

Footer — 2026-04-17 (tourguide, path relocation)

References above to src/simulator/pkg/ are historical as of this date. The wasm-pack output was relocated to .local/build/wasm/ per objective p1-11 (build-output-src-purge) as part of enforcing the project-wide "build output never under src/" rule. See .claude/instructions/build-output-locations.md for the canonical rule and ./run verify step 16 (_verify_no_build_in_src) for the mechanical enforcement. Existing entries above are preserved verbatim as a record of the pre-relocation audit and are not rewritten.