homepage/.agents/PLAN.md

PLAN — Developer Homepage

Status: live static site · Last reviewed: 2026-09-18 (security & code-quality audit)

1. Project Identity

A single-page personal portfolio (Reese Wells — self-hosting & infrastructure) with an interactive fake terminal (easter-egg commands, vim simulator, achievement system). No backend, no user accounts, no PII beyond public contact details and GPG public keys.

2. Assumptions & Design Principles

1. Static first. The site is plain HTML/CSS/JS. No runtime dependencies, no CDNs, no build-time JS frameworks — the supply chain is the repo itself.
2. Boring deployment. build.sh → hashed dist/ → nginx:alpine on :8080 (plain HTTP) → TLS terminated by the external Caddy reverse proxy.
3. Test the artifact. E2E tests run against the built dist/, not src/, so what is tested is exactly what is deployed.
4. Security headers are a container property. All hardening headers are emitted by nginx (the only thing that serves the site in production).
5. Fun is safe. The fake terminal's easter eggs (page-wipe, login screen, vim) are DOM-only pranks — no real network or system effects. The only real network behavior (curl/wget fetch) is being removed — see Phase 02.

3. Architectural Anchors (LOCKED DECISIONS)

COMPONENT	DECISION	RATIONALE	STATUS
Frontend runtime	Vanilla HTML/CSS/JS, flat src/*.js files, defer load order	No toolchain, auditable, works with build.sh hashing	LOCKED (pre-existing)
Terminal modules	terminal-commands.js (canned data) · terminal-achievements.js · terminal-vim.js · terminal.js (core)	Flat modules keep build.sh's root-level hashing working; single source of truth for command data	LOCKED (2026-09-18 refactor)
Build	build.sh: md5 content-hash cache-busting + sed reference rewrites → dist/	md5 is a cache key, not a security hash — acceptable	LOCKED (pre-existing)
Serving	nginx:alpine, listen 8080, plain HTTP	TLS is added by the Caddy edge in front of the container	LOCKED (pre-existing)
Edge	Caddy reverse proxy (Route53 DNS-validated TLS) in front of the container	HSTS/TLS are edge responsibilities	LOCKED (assumed — verify per Phase 03)
E2E tests	@playwright/test pinned 1.62.0 (matches cached chromium-1234), serves dist/ via python3 -m http.server 8123, config playwright.config.js	Tests the deployed artifact; pinned to avoid browser re-downloads	LOCKED (2026-09-18, user-approved)
Deployment	Docker image → gitea.reeseapps.com/services/homepage via Gitea Actions (secrets-based registry login)	Self-hosted CI	LOCKED (pre-existing)
Persistence	localStorage only (achievements, key reese-terminal-achievements)	No backend by design	LOCKED (pre-existing)

4. High-Level Architecture

src/ (index.html, style.css, script.js, terminal*.js, assets)
  │  build.sh (hash + rewrite)
  ▼
dist/ (index.html + hashed assets)          ◄── playwright webServer (port 8123)
  │  Dockerfile (COPY → nginx html root)    ◄── tests/e2e/*.spec.js (44 tests)
  ▼
nginx:alpine :8080 (HTTP, security headers, cache policy)
  ▲
Caddy edge (TLS, HSTS) ← reeseapps.com

• src/terminal.js — terminal core: prompt loop, history, tab completion, dispatch, expand/collapse (expandTerminal/collapseTerminal, shared with script.js hero click).
• src/terminal-commands.js — TERMINAL_COMMANDS (canned outputs; values may be functions evaluated at dispatch), TERMINAL_COMMAND_LIST (tab completion), getCommandOutput().
• src/terminal-vim.js — launchVimSimulator({content, terminal, mobileInput, filename, setVimMode}).
• src/terminal-achievements.js — ACHIEVEMENTS, localStorage persistence, toasts, hidden-section reveal, initTerminalAchievements().
• src/script.js — nav menu, IntersectionObserver fades, server-rack background generation, hero-click terminal toggle.

5. Validation / Verification Workflow

1. ./build.sh — rebuild dist/.
2. npm test (Playwright) — 44 E2E tests against dist/ on port 8123. Every phase's final pass must leave the suite green.
3. .agents/validate.sh (installed by the phased-execution skill) — must run 1 + 2 and, for Phase 03, the header checks below.
4. Container header check (Phase 03): scripts/check-headers.sh — builds the image, runs it on a scratch port, asserts the four security headers on /, /index.html, and a hashed asset.

6. Data Model

No server-side data. Client-side state:

Key	Where	Shape
reese-terminal-achievements	localStorage	JSON array of achievement ids (e.g. ["time_flies","nice_try"])

Session-only state (no persistence): terminal history, isRoot, vim state, menu open/closed, terminal grown/collapsed.

7. Roadmap

Phase	Title	Source
01_fix_history_xss	Fix terminal history-recall XSS (M-1)	audit finding M-1
02_simulate_fetch_commands	Remove unvalidated client fetch from curl/wget (M-2)	audit finding M-2
03_nginx_security_headers	Security headers on every location (M-4) + server_tokens off (L-2)	audit findings M-4, L-2

Dismissed: audit finding M-3 (README 0.0.0.0:8080 binding) — false positive per project owner (2026-09-18); the host firewall already restricts access and the site is fronted by the Caddy edge.

Completed in-session (not phased): code-quality pass 2026-09-18 — module split (Q-1), dead-code removal (Q-2/3/4, scrollOffset), expand/collapse helpers (Q-5), rack-decoration CSS classes (Q-7), hidden-attribute reveal (Q-8), a11y label on terminal input (Q-9), dynamic date (Q-10), vim dd line-deletion fix, Playwright regression suite (44 tests). See .agents/remediation_plan.md.

Remaining low-priority audit items (not yet phased): L-1 (verify HSTS at the Caddy edge — folded into Phase 03 verification), L-3 (drop style-src 'unsafe-inline' after moving inline style="" attrs to classes), L-5 (label the displayed SSH key as fictitious or show fingerprint only), L-7 (pin CI action SHAs / image signing), L-8 (build.sh verification test in CI).