From fc7cf7b055ed78448bbbd833efe723b80b3bd54b Mon Sep 17 00:00:00 2001
From: AJ ONeal <aj@therootcompany.com>
Date: Wed, 11 Mar 2026 02:02:34 -0600
Subject: [PATCH] docs: update PROD_NOTES.md after dead code removal

---
 PROD_NOTES.md | 53 +++++++++++++++++++++++++++++++--------------------
 1 file changed, 32 insertions(+), 21 deletions(-)

diff --git a/PROD_NOTES.md b/PROD_NOTES.md
index ac8c7f2..933a6fa 100644
--- a/PROD_NOTES.md
+++ b/PROD_NOTES.md
@@ -4,20 +4,24 @@
 
 The Node.js server no longer fetches from upstream APIs. It reads only from
 `_cache/YYYY-MM/{pkg}.json` files generated by the Go `webicached` daemon.
+All per-package `releases.js` files and `_common/` fetcher libraries have been
+deleted — they are no longer needed.
 
-### Completed
+### Changes Made
 
 - **builds.js**: Removed `freshenRandomPackage()` calls and background refresh
 - **builds-cacher.js**: Removed `getLatestBuilds()`, stale re-fetch, and
   `freshenRandomPackage()`. Missing cache files return empty metadata.
 - **builds-cacher.js `getProjectTypeByEntry()`**: Replaced `require(releases.js)`
   with cache file existence check. Packages are `valid` if they have a cache
-  file, `selfhosted` if they don't. This means packages like vim-airline that
-  now have Go-generated cache are correctly served.
+  file, `selfhosted` if they don't.
 - **transform-releases.js**: Legacy release API now reads from cache files
   instead of fetching upstream. Pre-classified fields are cleared before
   `normalize()` so the output matches the legacy format (e.g. `darwin` → `macos`,
   versions without `v` prefix).
+- **classify-one.js**: Updated to read from cache instead of `releases.js`.
+  Fixed hardcoded triplet key.
+- **Deleted 94 `{pkg}/releases.js` files** and **8 `_common/*.js` files**
 
 ### Data Format Note
 
@@ -32,25 +36,37 @@ pre-classified fields and re-normalize from filenames to match production output
 For the installer endpoint (`builds-cacher.js` + `serve-installer.js`), the Go
 naming is used directly — the build-classifier handles its own mappings.
 
-### Remaining Work
+### Known Pre-existing Issues
 
-- **`{pkg}/releases.js` files**: No longer `require()`d at runtime. They are
-  now dead code (not loaded by builds-cacher, transform-releases, or any
-  runtime path). Still useful as documentation of upstream sources. The files
-  in `_common/` (github.js, gitea.js, etc.) are also unused at runtime.
-- **`classify-one.js`**: CLI utility that still `require()`s releases.js
-  directly. This is a dev tool, not a production path.
 - **`transform-releases.js` self-test**: The `if (require.main === module)`
-  block calls `module.exports({...})` but the module exports an object. This
-  is a pre-existing bug (not caused by our changes).
+  block calls `module.exports({...})` but the module exports an object.
+- **armhf classification warnings**: `arm-unknown-linux-gnueabihf` triggers
+  "wrong arch" warnings in the build-classifier (armhf vs armv6).
+- **Go illumos/solaris warnings**: Go's illumos and solaris builds trigger
+  "wrong os" warnings (expected `sunos`).
+
+## Testing
+
+All paths verified locally:
+
+```sh
+# builds-cacher: load packages from cache
+node -e "let B = require('./_webi/builds.js'); B.init().then(...);"
+
+# transform-releases: legacy API from cache
+node -e "let R = require('./_webi/transform-releases.js'); R.getReleases({pkg:'bat', ...});"
+
+# serve-installer: full end-to-end resolution
+node -e "let I = require('./_webi/serve-installer.js'); I.helper({unameAgent:'aarch64/unknown Darwin/24.2.0 libc', ...});"
+
+# classify-one: dev tool reads cache
+node _webi/classify-one.js bat
+```
 
 ## Public API Endpoints (live at webinstall.dev)
 
-Tested against production 2026-03-11:
-
 - `GET /api/releases/{pkg}.json` — Returns JSON with `oses`, `arches`, `libcs`,
-  `formats`, and `releases` array. Each release has: name, version, lts,
-  channel, date, os, arch, ext, download, libc. Uses `macos` not `darwin`.
+  `formats`, and `releases` array. Uses `macos` not `darwin`.
 - `GET /api/releases/{pkg}.tab` — Tab-separated release data
 - `GET /{pkg}@{tag}` — Returns installer script (bash or ps1 based on UA)
 
@@ -69,11 +85,6 @@ modules (`Releases.getReleases()` and `InstallerServer.serveInstaller()`).
 | `hidden` | System dirs, `_*`, `.*` etc | naming convention |
 | `invalid` | No README.md | file check |
 
-**`serve-installer.js` behavior by type:**
-- `valid` → loads cache, resolves version/triplet, renders installer
-- `selfhosted` → returns error package immediately (no cache lookup)
-- Others → throws ENOENT
-
 ## Package Counts
 
 - **99 packages** detected as `valid` (have cache files)