Repository navigation
chore: remove the Blume spike and spent build inputs - #366
Merged
Merged
Conversation
apps/site-blume-spike was a two-week evaluation of Blume as a replacement static-site generator for the public site. It was never wired into the build and nothing imports it, but it sat in the pnpm workspace, so its Astro toolchain and a 1.9 MB vendored tarball were carried in the lockfile. The framework question it existed to answer was settled by what shipped. The public site was restructured in place a day after the spike's last commit (#313), and the spike has not been touched in the three weeks since. Its one durable output already left the repository: the heading-ID incompatibility it found was fixed upstream in Blume (haydenbleasel/blume#215, merged 2026-08-28), which is also what made the vendored tarball redundant, since that tarball existed only to carry the unmerged patch. The spike also kept its own copies of the specification content under content/specification. Those copies were outside spec-check's parity gate, so nothing would have reported them drifting from the canonical root specs. Keep the design note, which holds the findings, and record the outcome there along with a pointer to the commit the implementation can be read from. Two of its deferred findings are unrelated to the framework choice and stay open: the sandbox still lives inside apps/site, and the Agent Skills endpoint still publishes from the site app while docs/agent-skills owns the content. Assisted-by: AI Signed-off-by: Tim Nunamaker <tnunamak@gmail.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
tnunamak
changed the title
Three tracked files outlived what they were for. design_handoff_pdpp_site/ was the input brief for the site rebuild: a Claude Design export, an HTML prototype, and the prompt naming them as the sources of truth for appearance and copy. That rebuild shipped in #313, so the brief is a spent build input, and it is 226 KB of HTML that no longer describes the site. index.md is a VitePress homepage. Nothing in the repository uses VitePress, and it still advertises a live reference implementation that no longer lives here. STACK-0902.md says in its own first paragraph that it exists so an integration branch would have a commit of its own. That branch is long merged. The rest closes gaps that let junk accumulate in the first place: .gitignore did not cover .turbo, .worktrees, .codex-reports, devspecs or ai, all of which appear in a working tree during normal use, so a `git add -A` in one could commit build output or local notes to a public repository. biome.jsonc did not exclude .worktrees. A git worktree of this repository checked out inside it carries its own biome.jsonc, and Biome refuses to run at all when it finds a nested root configuration, so `biome check` failed for files that were themselves clean. sync-spec-docs.mjs now clears a stale content/docs/spec-*.md before writing the .mdx of the same name. An earlier revision emitted .md; a leftover from one of those runs is not overwritten, fumadocs globs both, and the two collide on slug and fail the build with "Duplicated slugs", an error that names nothing the author touched. The script runs from predev and prebuild, so it clears the file before anyone can build or commit with it present. Assisted-by: AI Signed-off-by: Tim Nunamaker <tnunamak@gmail.com>
apps/site/.source holds four files written by fumadocs-mdx. They were tracked, while the dev-mode equivalent .source-*/ was already ignored, so the same generated artifact was committed in one mode and ignored in the other. The cost was noise in every working tree: any run of `types:check` rewrites these files, so they appear as unstaged modifications that have to be discarded before committing unrelated work, and they turn up in the diff of anyone who builds before staging. Verified they are not an input: deleting the directory entirely and running `pnpm run build` regenerates all four and compiles successfully, so nothing depends on the committed copies. `reuse lint` still passes. Assisted-by: AI Signed-off-by: Tim Nunamaker <tnunamak@gmail.com>
tnunamak
force-pushed
the
chore/remove-blume-spike
branch
from
September 21, 2026 20:49
7aa556e to
3709f65
Compare
tnunamak
marked this pull request as ready for review
September 21, 2026 21:55
tnunamak
added a commit
that referenced
this pull request
Sep 23, 2026
Two independent bugs, both hidden because neither ran as a required PR gate. apps/site's tsconfig.json maps `@generated-docs/*` to a single hardcoded `./.source/*`. `types:check`/`verify` set `PDPP_SITE_SOURCE_DIR` to `.source-verify` (and `dev` to `.source-dev`), so fumadocs-mdx writes each mode's output to its own directory instead. #340 isolated these directories, and kept matching webpack/turbopack aliases in `next.config.ts` in sync, so dev and verify runs stop clobbering each other's generated files. `tsc` has no way to read that env var, so it always resolved `.source`, which `verify` never populates: `tsc --noEmit` failed with `TS2307: Cannot find module '@generated-docs/dynamic.ts'`. `next build` never hit this, because Next's own bundler uses the parameterized alias, not tsconfig's `paths`, so the bug was invisible to any build/deploy path and to every CI job, none of which invoke `apps/site`'s `verify` or `types:check` at all. List all three mode directories in `paths` as fallbacks; tsc resolves whichever one the run populated. `apps/site/scripts/sync-spec-docs.mjs` is a generated artifact compiled from `sync-spec-docs.mts` (`scripts/check-generated-artifacts.ts` asserts they're byte-identical). #366 added stale-`.md` cleanup logic by editing the compiled `.mjs` directly and never touched the `.mts` source, so the two diverged. Port the same logic into `.mts` and regenerate `.mjs` from it. `generated-artifacts:check` only runs in semantic-release.yml, gated on a version actually publishing, so it's absent from the PR-required checks and this went uncaught since #366 merged. Root/site spec drift (spec-check.yml) stayed green throughout because it only runs `spec:check`, which diffs generated markdown against the root specs and never invokes tsc or generated-artifacts:check. Verified: `pnpm --dir apps/site run verify` now gets past types:check, test (247/247), and build. `pnpm generated-artifacts:check` reports 7 byte-identical artifacts. `ultracite check` still fails on an unrelated, pre-existing `playwright` import in `apps/site/scripts/style-differ.mjs`, present unmodified on main and out of scope here. Assisted-by: AI Signed-off-by: Tim Nunamaker <tnunamak@gmail.com>
tnunamak
added a commit
that referenced
this pull request
Sep 23, 2026
…372) * fix(site): fix tsconfig and sync-spec-docs.mts drift breaking verify Two independent bugs, both hidden because neither ran as a required PR gate. apps/site's tsconfig.json maps `@generated-docs/*` to a single hardcoded `./.source/*`. `types:check`/`verify` set `PDPP_SITE_SOURCE_DIR` to `.source-verify` (and `dev` to `.source-dev`), so fumadocs-mdx writes each mode's output to its own directory instead. #340 isolated these directories, and kept matching webpack/turbopack aliases in `next.config.ts` in sync, so dev and verify runs stop clobbering each other's generated files. `tsc` has no way to read that env var, so it always resolved `.source`, which `verify` never populates: `tsc --noEmit` failed with `TS2307: Cannot find module '@generated-docs/dynamic.ts'`. `next build` never hit this, because Next's own bundler uses the parameterized alias, not tsconfig's `paths`, so the bug was invisible to any build/deploy path and to every CI job, none of which invoke `apps/site`'s `verify` or `types:check` at all. List all three mode directories in `paths` as fallbacks; tsc resolves whichever one the run populated. `apps/site/scripts/sync-spec-docs.mjs` is a generated artifact compiled from `sync-spec-docs.mts` (`scripts/check-generated-artifacts.ts` asserts they're byte-identical). #366 added stale-`.md` cleanup logic by editing the compiled `.mjs` directly and never touched the `.mts` source, so the two diverged. Port the same logic into `.mts` and regenerate `.mjs` from it. `generated-artifacts:check` only runs in semantic-release.yml, gated on a version actually publishing, so it's absent from the PR-required checks and this went uncaught since #366 merged. Root/site spec drift (spec-check.yml) stayed green throughout because it only runs `spec:check`, which diffs generated markdown against the root specs and never invokes tsc or generated-artifacts:check. Verified: `pnpm --dir apps/site run verify` now gets past types:check, test (247/247), and build. `pnpm generated-artifacts:check` reports 7 byte-identical artifacts. `ultracite check` still fails on an unrelated, pre-existing `playwright` import in `apps/site/scripts/style-differ.mjs`, present unmodified on main and out of scope here. Assisted-by: AI Signed-off-by: Tim Nunamaker <tnunamak@gmail.com> * fix(site): isolate verify's tsc pass per mode, add generated-docs PR gate The previous commit's tsconfig fix listed `.source`, `.source-verify`, and `.source-dev` as fallback `paths` for `@generated-docs/*`, so `tsc` would resolve whichever directory exists. That is unsound: `tsc` picks the first entry that exists, not the one the current run generated, so a `.source` left behind by an unrelated `next build`/`next dev` run masks a real type error in `verify`'s own `.source-verify` output. Reproduced: with a valid `.source` present and a `docs-source.ts` import renamed to break against a freshly-regenerated `.source-verify` (the same shape a real fumadocs-mdx or source-config change could produce), `tsc --noEmit` against the fallback list still exited 0. Fix: give `verify` a dedicated `tsconfig.verify.json` that resolves `@generated-docs/*` against `.source-verify` only, selected by a new `PDPP_SITE_TSCONFIG` env var alongside the existing `PDPP_SITE_SOURCE_DIR`. `next build` has its own internal type-check pass that reads `tsconfig.json` directly, separate from the webpack/turbopack aliases its bundler uses, so it needs the same fix: `next.config.mjs` now sets `typescript.tsconfigPath` from the same env var. The base `tsconfig.json` goes back to a single `.source` path, for the editor and a plain `types:check`. Re-ran the same masking repro against the fix: with the same stale, valid `.source` present, `tsc -p tsconfig.verify.json --noEmit` correctly fails on the broken `.source-verify`. `ultracite check` (the linter step inside `apps/site`'s `check`/`verify`) failed on `scripts/style-differ.mjs`'s `import { chromium } from "playwright"`, flagged as an unresolved import. `playwright` is a real dependency (`apps/site/package.json`); the import resolves under TypeScript and at runtime. The failure is Biome's documented resolver gap with re-exports (`export * from 'playwright-core'` in `playwright`'s `index.d.ts`): `playwright-core` is only an indirect dependency here, so pnpm's isolated `node_modules` gives Biome's resolver nothing to follow. `apps/site/biome.jsonc` already carries a scoped waiver for this exact upstream gap (biomejs/biome#9143, #6464) for `src/**`; `style-differ.mjs` sits outside `src/`, so it wasn't covered. Added a second, narrowly scoped override for this one file with its own rationale, rather than widening the `src/**` waiver's stated scope. `style-differ.mjs` itself is unmodified: it is a real, actively-referenced visual-regression diagnostic (used to prove CSS-migration behavior preservation, per its own header comment), not dead code. Both original bugs (the tsconfig path drift and the hand-edited `sync-spec-docs.mjs` generated-artifact drift) reached `main` because no PR check ran `apps/site`'s `types:check`/`verify` or the root `generated-artifacts:check`; the latter only runs post-merge in `semantic-release.yml`, gated on an actual version publish. Added `.github/workflows/site-generated-docs-check.yml`, path-scoped to `apps/site/**` the same way `react-doctor.yml` (this repo's existing apps/site-only PR check, a React-health regression scan) is, running `types:check` (in verify mode, via the same `PDPP_SITE_SOURCE_DIR`/ `PDPP_SITE_TSCONFIG` pair `verify` sets) and `generated-artifacts:check`. Deliberately not the full `verify` script: `verify` also runs the test suite and a production `next build`, real coverage but not what closes this gap, and roughly doubles wall time for no additional defect coverage here. Verified: `pnpm --dir apps/site run verify` passes end to end (exit 0): types:check, 250/250 tests, `ultracite check` (0 errors, 4 pre-existing unrelated warnings), `generated-artifacts:check` (7 byte-identical artifacts), and `next build` (log shows `Using tsconfig file: tsconfig.verify.json`). The new workflow's two steps (`PDPP_SITE_SOURCE_DIR=.source-verify PDPP_SITE_TSCONFIG=tsconfig.verify.json pnpm --dir apps/site run types:check` and `pnpm generated-artifacts:check`) both pass when run standalone from the repo root, matching how the workflow invokes them. Assisted-by: AI Signed-off-by: Tim Nunamaker <tnunamak@gmail.com> * docs(site): correct and shorten the per-mode tsconfig comments tsconfig.verify.json still described a fallback list in the base config that the previous commit removed. Assisted-by: AI Signed-off-by: Tim Nunamaker <tnunamak@gmail.com> --------- Signed-off-by: Tim Nunamaker <tnunamak@gmail.com>
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Deletes four things that outlived their purpose, and closes the gaps that let them sit unnoticed.
apps/site-blume-spikeevaluated Blume as a replacement site generator. Nothing imports it, but it sat in the pnpm workspace, so its Astro toolchain and a 1.9 MB vendored tarball resolved on every install. The question it asked was answered by what shipped: the site was restructured in place a day later (#313), untouched since. Its one durable output went upstream (blume#215, merged 2026-08-28), which also makes the vendored tarball redundant. The design note stays and records this.design_handoff_pdpp_site/was the input brief for the rebuild that shipped in #313.index.mdis a VitePress homepage for a generator this repo does not use.STACK-0902.mdsays in its first paragraph that it exists so a branch would have a commit of its own.The gaps:
.gitignoremissed.turbo,.worktrees,.codex-reports,devspecs,ai, sogit add -Ain a normal tree could commit build output to a public repo.biome.jsoncmissed.worktrees. A worktree carries its ownbiome.jsonc, and Biome refuses to run under a nested root config, failingbiome checkon clean files.apps/site/.sourcewas tracked while its dev twin.source-*/was ignored, leaving it dirty after everytypes:check.sync-spec-docs.mjsnow clears a stalespec-*.mdbefore writing the.mdx. An earlier revision emitted.md; fumadocs globs both and they collide on slug.Verification
With the stale files restored,
pnpm run buildfails on "Duplicated slugs"; after the sync script clears them, it succeeds. Deletingapps/site/.sourceand building regenerates all four files, so nothing depended on the committed copies.spec:checkreports the same 9 pairs and 3 extensions asmain, andpnpm install --frozen-lockfileresolves 9 workspace projects with only the spike removed. Site tests,tsc --noEmitandreuse lintpass.public-tree:hygiene-checkfails here and onmainalike, on an operator home path inscripts/hero-load-measure.mjsand a private hostname inscripts/connector-reachability.mjs. Pre-existing.Draft: deleting the spike removes someone else's work on circumstantial grounds. It was never formally closed, so the case is #313 shipping on Next.js the next day and silence since.
Assisted-by: AI