The Netlify validation job imports site listings before generated static device JSON exists in a clean checkout, so keep the small device table in tracked source and use it as the route fallback.
Constraint: static/device-list.json is ignored generated output and is absent in GitHub-hosted clean runners
Rejected: Force-add static/device-list.json | keeps generated output under source control
Confidence: high
Scope-risk: narrow
Directive: Keep disabled device rows in the fallback source but filter them from routable listings
Tested: pnpm run with-env vitest ./test/prebuild/site-listings.test.js
Tested: pnpm netlify-build reached Astro build after passing prebuild tests
Not-tested: Full local netlify-build completion blocked by unrelated uncommitted scanner worker build failure
The first baseline committed the raw YouTube API dump, which fixed clean builds but carried unused API metadata. The route fallback only needs prebuilt listing objects, so this replaces the raw seed with slug-keyed listing fallbacks and adds a refresh script that fetches the latest source data before projecting it.
Constraint: helpers/site-listings.js must work in a fresh checkout before generated static/api output exists
Rejected: Commit the full raw YouTube JSON | unnecessarily large and mostly unused by the fallback path
Rejected: Drop descriptions only | smaller but would weaken app-link and tag matching semantics
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Refresh static/api/youtube-video-listings.json via scripts/update-youtube-video-listing-fallbacks.js, not by committing static/api/youtube-videos.json
Tested: pnpm run with-env vite-node scripts/update-youtube-video-listing-fallbacks.js
Tested: pnpm run with-env vitest test/prebuild/site-listings.test.js
Tested: pnpm run netlify-prebuild:test-prebuild-functions
Tested: pnpm run netlify-prebuild
Netlify prebuild tests import the YouTube listing JSON at module load time, so a fresh checkout needs a baseline copy of that data before any generated API step runs. The fetched JSON is committed and explicitly unignored while the broader static/api output remains generated.
Constraint: Netlify runs test-prebuild before Astro generation creates generated API files
Rejected: Move all API generation before tests | broader build-order change with more external dependencies
Confidence: high
Scope-risk: narrow
Directive: Keep static/api/youtube-videos.json tracked unless helpers/site-listings.js stops importing it at module load time
Tested: pnpm run with-env vite-node /tmp/fetch-youtube-videos.mjs
Tested: pnpm run with-env vitest test/prebuild/site-listings.test.js
Tested: pnpm run netlify-prebuild:test-prebuild-functions
Replace all in-scope axios callsites with a new helpers/http.js wrapper over native fetch, including JSON/text GET, JSON POST, HEAD checks, and transient 5xx retry behavior; update all browser, build, script, and proxy API clients to use it; add focused unit tests; and remove axios from package dependencies.
Constraint: Preserve API/build and deployment behavior while lowering transport surface area.
Rejected: inline fetch replacements at each callsite | rejected to avoid inconsistent error/retry semantics.
Confidence: high
Scope-risk: moderate
Directive: Keep helper in place as the transport boundary and update tests when changing request semantics.
Tested: pnpm run -s typecheck, pnpm -s run test-prebuild, pnpm -s run test, pnpm -s run test:browser, pnpm -s run netlify-build, smoke GETs on /apple-silicon-app-test and /apple-silicon-app-test/?version=2
Not-tested: branch/netlify deployment health in CI pipeline after merge
The previous route fallback fix worked locally but still failed on production because the Netlify SSR runtime did not have repo-local JSON files available at the paths the helper searched.
Switch the fallback helper to raw-import the generated app, game, device, and YouTube JSON inputs so the SSR bundle carries the data it needs at runtime, independent of function working directory or file packaging quirks.
Constraint: Netlify SSR bundling does not reliably expose repo-local generated files as runtime-readable filesystem paths
Rejected: Rely on Netlify included_files for SSR bundle data | the generated SSR function archive still omitted the fallback files
Rejected: Fetch large fallback JSON over HTTP on each request | unnecessary network dependency for a server-side fallback path
Confidence: medium
Scope-risk: narrow
Reversibility: clean
Directive: Prefer bundler-native inclusion for SSR-only fallback data when runtime file availability is uncertain on Netlify
Tested: vitest ./test/prebuild/config-node.test.js ./test/prebuild/site-listings.test.js; pnpm run netlify-build
Not-tested: live production after redeploy
Add a Bun health script that exercises top-level, dynamic, and representative video routes against one or more hosts so prod regressions are visible from a single command.
Device pages now fall back to the bundled device list when the external API misses a slug, and orphaned tv slugs redirect to /benchmarks instead of returning a 500. Video fallback logic reuses the existing YouTube-to-listing builder so route reconstruction stays aligned with the current build logic.
Constraint: The external API host can lag behind the frontend build and omit per-slug JSON files that public routes still expect
Rejected: Import the generated video list directly | static/video-list.json is too large for a safe SSR fallback
Rejected: Leave missing tv routes as 500s | a stale public URL should degrade to a useful redirect instead of breaking the request
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep route fallbacks tied to build-time artifacts from the same repo so frontend and fallback data stay in sync
Tested: bun scripts/health http://127.0.0.1:4322; vitest ./test/prebuild/config-node.test.js ./test/prebuild/site-listings.test.js; pnpm run netlify-build
Not-tested: live production deploy before push
Dynamic Astro routes were reading Netlify redirect config through a cwd-relative path, which is fragile inside a serverless runtime and was taking detail pages down with 500s before render.
Resolve netlify.toml by searching from the module directory and current working directory, and fail open in request-time redirect lookup so a config read problem does not block page rendering.
Constraint: Netlify serverless cwd is not guaranteed to be the repo root
Rejected: Inline redirects into route modules | would duplicate platform config and drift from source of truth
Rejected: Leave redirect lookup hard-failing | one config read failure should not take down unrelated pages
Confidence: medium
Scope-risk: narrow
Reversibility: clean
Directive: Keep redirect config lookup independent of process cwd anywhere server code reads deploy config files
Tested: vitest ./test/prebuild/config-node.test.js; pnpm run netlify-build
Not-tested: live Netlify production deploy before push
Madge treated the local plist parser module name as a circular dependency during the Netlify build lane after the TypeScript refactor. Rename the local module to plist-parser so the internal file no longer collides with the external plist package name, while keeping parser behavior unchanged.
Constraint: Must restore the deploy gate without changing parser semantics
Rejected: Disable the circular-dependency check | would hide a useful guard instead of fixing the naming conflict that triggered it
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Avoid naming local modules after direct external package imports when the repo relies on static dependency graph tooling
Tested: pnpm run typecheck; pnpm exec vitest run test/scanner/plist.test.ts test/scanner/file-api.test.ts test/scanner/client.test.ts test/prebuild/load-sitemap-endpoints.test.ts; pnpm run test-prebuild
Not-tested: Full production deploy completion before push
The TypeScript helper refactor exposed a separate production risk: builds can fail when the sitemap-endpoints API returns a transient 5xx during Pagefind index generation. Move that fetch into a small helper with retry logic and add a focused prebuild test so this failure mode is caught without waiting on a full deploy.
Constraint: Must keep Pagefind index generation behavior the same when the endpoint is healthy
Rejected: Ignore the failure as external-only | transient 5xx responses can still block deploys and CI repeatedly
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: When external build inputs can fail transiently, add a small retryable helper plus a direct test before relying on full deploy verification
Tested: pnpm exec vitest run test/prebuild/load-sitemap-endpoints.test.ts; pnpm run typecheck; pnpm run test-prebuild
Not-tested: Full production redeploy completion before push
Convert the scanner's plist parser and Node-style file shim to TypeScript and add small unit tests so common parser and file-reader failures are caught before we need to lean on Playwright or the higher-level scanner test.
Constraint: Must preserve current scanner behavior while tightening the lowest-level helper surface
Rejected: Jump straight to Mach-O parser conversion | harder to isolate regressions without first proving the smaller helper-test pattern
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Add small module-level regression tests for repeatable scanner breakage before expanding browser coverage
Tested: pnpm run typecheck; pnpm exec vitest run test/scanner/plist.test.ts test/scanner/file-api.test.ts test/scanner/client.test.ts; pnpm run test; pnpm run test:browser
Not-tested: Production deploy behavior prior to push
The Cloudflare worker deploy workflow was printing secret-derived config into CI logs and doing unnecessary root installs. Tighten the workflow to use read-only permissions, secure file writes, and per-worker dependency installs, then add a staged TypeScript migration plan so the repo-wide conversion has explicit CI-safe ordering.
Constraint: Must keep the current Cloudflare deploy path working while removing secret exposure from logs
Rejected: Leave the workflow as-is and document the risk | known secret leakage in CI is an immediate operational defect
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep worker deploy inputs secret-only and validate repo-wide TypeScript work in bounded slices, not one bulk migration
Tested: ruby YAML parse of .github/workflows/deploy-cloudflare-workers.yml; git diff --check; npm ci --prefix doesitarm-default --ignore-scripts --no-audit --no-fund; npm ci --prefix workers/analytics --ignore-scripts --no-audit --no-fund
Not-tested: Full GitHub Actions execution after commit
This adds a repo-local plan for the public discoverability and dataset work so
future implementation can proceed in small, reviewable stages. The rollout is
ordered by ease of implementation and each stage begins with a research pass to
re-check current crawler, schema, and search guidance before code changes land.
Constraint: User requested an ease-first rollout with research checkpoints at every stage
Rejected: Leverage-first ordering | larger evidence-page rewrite would delay smaller foundational wins
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Re-check external docs at the start of each stage before implementing because crawler and structured-data guidance can shift
Tested: git diff --cached --check; manual review of staged plan content
Not-tested: pnpm build; pnpm test (docs-only plan change)
The previous verbiage fallback loaded package.json via createRequire(), which broke Astro/Netlify prerender bundling because the relative package.json path is not available inside the generated chunk layout. Replace it with static fallback strings so the app-test text stays populated without depending on runtime file access.
Constraint: Must restore Netlify production builds immediately
Rejected: Revert the verbiage fix entirely | would reintroduce the blank app-test subtitle in production
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep public runtime fallbacks bundle-safe; do not require repo files from prerender/runtime chunks
Tested: pnpm run typecheck (workspace); GitHub Actions failure analysis for netlify-build
Not-tested: Full redeploy completion at commit time
Capture the next discovery, security, compatibility-data, and dual-deploy planning work, and ignore local Vercel/env state that should not be committed. This keeps the operational research with the repo while avoiding accidental local-config churn.
Constraint: Must not alter production runtime behavior
Rejected: Fold research notes into the runtime fix commit | obscures the user-facing app-test correction with planning-only material
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep .omx local state untracked even when committing broad workspace updates
Tested: Document review only
Not-tested: No runtime verification required for docs and ignore rules
The app-test page could render blank processor/mac verbiage when pnpm did not supply npm_package_config_verbiage_* in the runtime environment. Fall back to package.json config and the page-level computed value so the subtitle and description stay populated in builds and production.
Constraint: Must not change scanner behavior or app-test submission flow
Rejected: Patch only the Vue page text | leaves the public runtime config inconsistent for other consumers
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep publicRuntimeConfig resilient to missing npm_package_config_* env values until the config source is normalized repo-wide
Tested: pnpm run typecheck (workspace); node --input-type=module import of publicRuntimeConfig (workspace)
Not-tested: Full browser rerun for this exact commit beyond the already-green production smoke suite
Move the worker scanner surface into TypeScript, add a direct worker regression, and make the version=2 app-test path populate the same visible result data and final status as the legacy scanner. This keeps the refactor bounded while making the worker route safe to exercise.
Constraint: Must preserve the existing Apple Silicon app-test behavior while changing the worker internals
Rejected: Flip production to the worker path immediately | still needs the normal deploy path and broader production soak
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep the version=2 adapter using the shared finishFileScan path until the legacy scanner can be removed entirely
Tested: pnpm run typecheck; pnpm exec vitest run test/scanner/client.test.ts; pnpm run test:browser (original workspace); netlify build --context deploy-preview (original workspace)
Not-tested: Browser suite from the clean clone environment (local Astro dev server startup timed out there)
Add a typed Playwright harness for Pagefind and the Apple Silicon app-test flow so scanner work has browser-level protection. Keep the rollout plan in the same stack so the TypeScript conversion stays staged and reviewable.
Constraint: Must not change production runtime behavior in this commit
Rejected: Leave the old JS browser test and add a second harness | duplicates setup and leaves the targeted browser script broken
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep browser-only helpers under test/playwright/support until the runtime scanner surface is fully typed
Tested: pnpm run typecheck; pnpm run test:browser; pnpm run test:browser:pagefind
Not-tested: Live browser checks against doesitarm.com
Keep the Pagefind bootstrap path from rewriting the remote sitemap
payload locally when the static JSON file is absent. GitHub-hosted runs
only need the fetched data in memory, and stringifying the 385 MB payload
was exhausting Node during netlify-build.
Cover the Native Support filter with a Playwright-backed Vitest case
that can boot the local dev server or attach to a deployed URL so the
same regression can gate post-deploy verification.
Resolve the Pagefind browser loader in Vite dev and cap filter-only
result hydration so broad filters render promptly instead of stalling
behind thousands of fragment fetches.
Add Pagefind indexing and browser search adapters behind a provider switch.
This lets prebuild generate either Stork or Pagefind search artifacts and lets the existing search UI run against Pagefind while preserving scoped filters, excerpts, and result metadata.
Share filter parsing and provider mapping logic between Stork and upcoming search adapters.
This keeps the existing Stork API stable while adding Pagefind-oriented filter serialization under test.
Capture user-visible parity requirements for a future Pagefind migration.
This keeps the earlier viability memo focused on engine fit and documents the recommended adapter approach, carry-over patterns, and remaining prototype risks around ranking and title highlighting.
The generic
> doesitarm@1.0.0 test /Users/athena/Code/doesitarm
> vitest run
Running Astro Config File
RUN v4.1.0 /Users/athena/Code/doesitarm
Test Files 7 passed (7)
Tests 20 passed | 3 todo (23)
Start at 13:00:20
Duration 1.76s (transform 317ms, setup 138ms, import 1.23s, tests 2.55s, environment 2ms) entrypoint assumes artifacts that only exist after the repo's full Netlify-style build. Run the real end-to-end Netlify build in GitHub Actions instead so the hosted Node 24 check matches the supported build surface.
Install pnpm before enabling setup-node's pnpm cache in the Cloudflare deploy job, and make the Node 24 check workflow self-contained by providing the public build URLs directly.
These fixes address the first GitHub-hosted failures that surfaced after the Node 24 migration push without changing the application runtime.
Align local version markers and GitHub Actions with Node 24, switch the default test entrypoint to the maintained Vitest runner, and replace pnpm-incompatible npm helpers in repo scripts.
This also removes the obsolete AVA plus esm path and excludes disabled test fixtures from generic Vitest discovery so CI reflects the supported test surface.
Clean list-specific JSON endpoint directories before rewriting them so local and deploy-style API builds do not fail on leftover files from older runs.
Keep the count check, but count only generated JSON outputs so the verification reflects the actual endpoint set.
Switch Stork downloads to artifacts that match current runtimes and fix the runtime detection path that Node 22 changed.
This keeps the existing Stork pipeline working on Netlify's Noble image and on Apple Silicon development machines.
