#50 · stacks/uplink

Part of #6.

storage/framework/api/openapi.json, api-types.ts and client.ts are tracked, 2.9 MB, read by nothing, and describe an application that is not this one. They arrived with the scaffold and have never been generated here.

What is there today

All three have exactly one commit, 4442795, the initial "feat: Uplink" scaffold. git log -- storage/framework/api/openapi.json shows nothing since.
The committed spec documents 713 paths. The live router registers 246. 470 committed paths are not registered by this app at all: they are the auth, dashboard and dashboard-api bundles, which config/cloud.ts#L33 disables with STACKS_DEFAULT_ROUTES: 'none'.
It is also missing every route Uplink actually added. /api/license/check, /api/billing/portal and /api/billing/webhook appear in none of the three files, so the one document that claims to describe this API describes none of its business.
Nothing reads them. A repo-wide grep outside node_modules and the directory itself finds no import from app/, config/, routes/, resources/, tests/ or .github/.
Nothing in CI regenerates or diffs them (.github/workflows/ci.yml runs lint, test:types, migrate and the tests), so the drift is silent and always was.
The live spec does not come from the file. @stacksjs/router serves /__openapi.json from a handler, behind an authorization check that 404s when it is not enabled.
package.json carries docs:artifacts and docs:artifacts:check, both ./buddy docs:artifacts. That is not a command this app's buddy has: it does not appear in buddy list. The generated file's own header tells a reader to run it.
2.9 MB of it ships to the production box on every deploy.

Running ./buddy generate on a clean checkout rewrites all three: 16322 lines in api-types.ts, 6930 in client.ts, 57470 in openapi.json. The result is the more accurate document, but the delete-heavy diff reads like a mistake, so in practice nobody does.

Proposal

Stop tracking the three files, and gitignore storage/framework/api/. They are build output of a generator whose result depends on the environment it runs in, which is not a thing a repository can hold a correct copy of.
Drop docs:artifacts and docs:artifacts:check from package.json, or point them at a command that exists.
If a published spec is wanted, generate it in the release workflow from the app as configured for production, rather than keeping a copy that no process checks.

Requirements

Do not simply regenerate and commit. That replaces a wrong file with one that is right only for whoever ran it, and the next person to run it gets a different diff. The problem is that it is tracked, not that it is stale.
Nothing may start reading them as part of this. The point is to remove a thing that misleads, not to give it a job.
Check the deploy still works without them. config/cloud.ts ships the repository to the box, so confirm nothing in the serve path expects the directory to be present.

Acceptance

The three files are untracked, the directory is ignored, and git status stays clean after ./buddy generate.
bun run docs:artifacts either works or is gone.
A fresh clone builds, tests and deploys with the directory absent.