From df8b4f4eb21f9f2b19fef7b0c5a460df8a6015e2 Mon Sep 17 00:00:00 2001 From: LeOu Date: Mon, 3 Aug 2026 15:59:31 -0400 Subject: [PATCH] Polish README and remove unused scaffolding --- .github/workflows/pages.yml | 4 +- README.md | 50 ++----------------- package.json | 2 +- scripts/README.md | 4 +- ...xtures.mjs => check-protected-sources.mjs} | 11 ++-- tests/fixtures/published-copy/README.md | 32 ------------ tests/rendered-html.test.mjs | 26 ++++------ types/README.md | 6 --- .../02-repository-structure.md | 2 +- website-maintenance/04-release-checklist.md | 3 +- .../05-architecture-decisions.md | 5 +- website-maintenance/README.md | 5 +- 12 files changed, 32 insertions(+), 118 deletions(-) rename scripts/{check-published-copy-fixtures.mjs => check-protected-sources.mjs} (84%) delete mode 100644 tests/fixtures/published-copy/README.md delete mode 100644 types/README.md diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 39ef6ee..062932c 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -29,12 +29,12 @@ jobs: with: node-version: 24 cache: npm - - name: Guard protected sources and published snapshots + - name: Guard protected sources env: BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }} FORCED_PUSH: ${{ github.event.forced }} AUTHORIZED_ROOT_RESET_SHA: ${{ vars.AUTHORIZED_ROOT_RESET_SHA }} - run: npm run check:published-copy + run: npm run check:protected-sources - name: Install dependencies run: npm ci --ignore-scripts - name: Validate and build diff --git a/README.md b/README.md index 1d217ac..b6b6bed 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,7 @@ -# Theodore Ouyang - -This repository contains the source for [theodoreoy.com](https://www.theodoreoy.com/), -a selective personal archive built around four public sections: - -- **Home** — a particle-first opening stage followed by Theodore's profile, - biography, and contact coordinates. -- **Education** — Theodore's academic record and selected coursework. -- **Past Experience** — a five-domain archive generated from a validated source - record. -- **Current Chapter** — a concise account of Theodore's exploration of practical - AI use cases in everyday life. - -The Home page gives visual priority to an interactive Three.js particle field. -A same-shape particle fallback makes the first visible frame a stable word; -the canvas then takes over without flashing solid text. The complete identity -and biographical content remains available as static HTML below it. - -## Architecture and publishing - -The site uses the Next.js App Router, React, and TypeScript, and ships as a -Next.js static export. There is no application server, database, or request-time -API: GitHub Pages serves the generated HTML, CSS, JavaScript, fonts, and images. -Pull requests validate the complete export; pushes to `main` deploy it. +[![Theodore Ouyang — Exploring practical AI use cases](public/assets/brand/og-1774.jpg)](https://www.theodoreoy.com/) -## Development and validation - -```sh -npm ci --ignore-scripts -npm run check -npm audit --omit=dev -npm run preview:static -``` - -`npm run check` runs linting, TypeScript, a production build, and final-artifact -tests. Generated `.next/` and `out/` directories are intentionally not committed. -See [`website-maintenance/`](website-maintenance/) for the source map, design -boundaries, particle-system notes, and release checklist. - -## Rollback - -Publish changes through a pull request and keep `main` history intact. To undo a -release, create a new `codex/` branch from the current `main`, revert the relevant -merge commit, run the full validation suite, and merge that rollback through a -new pull request. Do not rewrite the published branch. +# Theodore Ouyang -[Visit the website →](https://www.theodoreoy.com/) +[theodoreoy.com](https://www.theodoreoy.com/) is a living archive of the +questions Theodore pursues, the work he chooses to preserve, and the ways his +thinking changes over time. It is selective and honest. diff --git a/package.json b/package.json index cf4c164..ae91b2c 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ "scripts": { "dev": "next dev", "build": "next build", - "check:published-copy": "node scripts/check-published-copy-fixtures.mjs", + "check:protected-sources": "node scripts/check-protected-sources.mjs", "preview:static": "node scripts/preview-static.mjs", "typecheck": "tsc --noEmit", "test": "npm run build && npm run test:artifact", diff --git a/scripts/README.md b/scripts/README.md index 12c5f16..90890df 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -7,5 +7,5 @@ - `optimize-images.mjs` creates reproducible web derivatives while preserving the original image files. -Whenever a public route is added, update the content registry and add its -append-only published-copy snapshot before release. +Whenever a public route is added, update the route registry, sitemap +expectations, and final-artifact tests in the same change. diff --git a/scripts/check-published-copy-fixtures.mjs b/scripts/check-protected-sources.mjs similarity index 84% rename from scripts/check-published-copy-fixtures.mjs rename to scripts/check-protected-sources.mjs index 0951494..a3feea1 100644 --- a/scripts/check-published-copy-fixtures.mjs +++ b/scripts/check-protected-sources.mjs @@ -2,7 +2,7 @@ import { execFileSync, spawnSync } from "node:child_process"; const baseSha = process.env.BASE_SHA; if (!baseSha) { - throw new Error("BASE_SHA is required to verify append-only published copy fixtures."); + throw new Error("BASE_SHA is required to verify protected sources."); } const forcedPush = process.env.FORCED_PUSH === "true"; @@ -25,7 +25,6 @@ const protectedPathspecs = [ ":(literal)app/past-experience/components/ExperienceDomainPage.tsx", ":(literal)app/lib/content/experience.ts", ":(literal)content/past-experience/archive-through-2026-06-30.md", - ":(glob)tests/fixtures/published-copy/*.json", ]; const mergeBaseCheck = spawnSync( @@ -46,12 +45,12 @@ let comparisonMessage; if (mergeBaseCheck.status === 0) { revisions = [`${baseSha}...HEAD`]; comparisonMessage = - "Protected Education, Past Experience, and Current Chapter sources are unchanged; published-copy snapshots contain additions only."; + "Protected Education, Past Experience, and Current Chapter sources are unchanged."; } else if (isAuthorizedRootReset) { if (mergeBaseCheck.status === 1) { revisions = [baseSha, "HEAD"]; comparisonMessage = - "Authorized root reset detected; direct tree comparison confirms protected Education, Past Experience, and Current Chapter sources are unchanged and published-copy snapshots contain additions only."; + "Authorized root reset detected; direct tree comparison confirms protected Education, Past Experience, and Current Chapter sources are unchanged."; } else { const emptyTreeSha = execFileSync( "git", @@ -60,7 +59,7 @@ if (mergeBaseCheck.status === 0) { ).trim(); revisions = [emptyTreeSha, "HEAD"]; comparisonMessage = - "Authorized root reset detected without the previous object; protected Education, Past Experience, and Current Chapter sources and preservation snapshots are introduced as additions."; + "Authorized root reset detected without the previous object; protected Education, Past Experience, and Current Chapter sources are introduced as additions."; } } else { throw new Error( @@ -89,7 +88,7 @@ const forbidden = changes if (forbidden.length > 0) { throw new Error( - "Protected Education, Past Experience, and Current Chapter sources are immutable, and published-copy snapshots are append-only; modification, deletion, and rename are forbidden:\n" + + "Protected Education, Past Experience, and Current Chapter sources are immutable; modification, deletion, and rename are forbidden:\n" + forbidden.join("\n"), ); } diff --git a/tests/fixtures/published-copy/README.md b/tests/fixtures/published-copy/README.md deleted file mode 100644 index 78f214c..0000000 --- a/tests/fixtures/published-copy/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# Append-only published copy - -Add one JSON file when a new route is first published. Existing JSON files must -never be modified, deleted, or renamed; CI enforces additions-only changes -against the pull request base commit. - -Each snapshot records the route, normalized visible `
` text, title, -description, headings, links, images, IDs, times, and `aria-label` / -`aria-labelledby` attributes. The artifact test can require recorded content -and structure to remain an ordered subsequence of future exports. - -Use this shape: - -```json -{ - "schemaVersion": 1, - "route": "/future-route/", - "mainText": "Complete normalized visible main text", - "title": "Page title", - "description": "Meta description", - "headings": [], - "links": [], - "images": [], - "ids": [], - "times": [], - "ariaAttributes": [] -} -``` - -Build first, derive the snapshot from the reviewed `out//index.html`, -and inspect the new plaintext fixture in the same pull request. Education and -Past Experience source files remain independently protected by CI and hashes. diff --git a/tests/rendered-html.test.mjs b/tests/rendered-html.test.mjs index 3fff271..3325002 100644 --- a/tests/rendered-html.test.mjs +++ b/tests/rendered-html.test.mjs @@ -477,23 +477,19 @@ test("Education retains all 31 selected courses", async () => { ); }); -test("README mirrors the current four-page site and its operating model", async () => { +test("README stays a concise public introduction", async () => { const readme = await readFile(path.join(ROOT, "README.md"), "utf8"); assert.match(readme, /^# Theodore Ouyang$/mu); - for (const page of ["Home", "Education", "Past Experience", "Current Chapter"]) { - assert.match(readme, new RegExp(`\\b${page}\\b`, "u"), `README is missing ${page}`); - } - assert.match(readme, /particle[- ]first/iu); - assert.match(readme, /(?:same-shape|matching)\s+(?:particle\s+)?fallback/iu); - assert.match(readme, /Next(?:\.js)?\s+static export/iu); - assert.match(readme, /GitHub Pages/u); - assert.match(readme, /npm run check/u); - assert.match(readme, /npm run preview:static/u); assert.match( readme, - /\[Visit (?:the )?website[^\]]*\]\(https:\/\/www\.theodoreoy\.com\/\)/iu, + /\[!\[Theodore Ouyang[^\]]*\]\(public\/assets\/brand\/og-1774\.jpg\)\]\(https:\/\/www\.theodoreoy\.com\/\)/u, + ); + assert.match(readme, /\[theodoreoy\.com\]\(https:\/\/www\.theodoreoy\.com\/\) is a living archive/u); + assert.match(readme, /It is selective and honest\./u); + assert.doesNotMatch( + readme, + /^##\s|