oc-ls-stats/AGENTS.md

oc-ls-stats

OpenCode TUI plugin that displays live prefill (PP) and generation (TG) rates from a llama.cpp llama-server. Polls /slots, classifies slot activity, renders into the session status bar.

Test / release gate

• All tests live in test-backoff.ts (node:test, run via tsx): npx tsx test-backoff.ts
• prepack runs this suite automatically on every npm pack / npm publish. A failing suite blocks publishing.
• No separate lint/typecheck scripts exist; the test suite is the gate.

Conventions

• Commits: lowercase conventional style — fix: …, feat: …, docs: …, and release bumps as chore: vX.Y.Z — <summary>.
• Tags: lightweight, named vX.Y.Z.
• Version bump lands in the same release commit chain as the changes it ships.

Registries

Two registries are used:

Target	Scope mapping in ~/.npmrc
Local Gitea	@troed:registry=https://git.sync.wtf/api/packages/troed/npm/
Public npmjs	@troed:registry=https://registry.npmjs.org/

Gotchas learned the hard way:

• The Gitea mapping MUST include the full API path (/api/packages/troed/npm/). Mapping the bare host breaks both npm publish auth (ENEEDAUTH) and plugin installation/loading.
• A --registry CLI flag does NOT override @scope:registry config. Scoped operations always use the scope registry — to query a different registry for a scoped package, use its HTTP API directly (e.g. curl https://registry.npmjs.org/@troed%2foc-ls-stats).
• Auth tokens are per path in ~/.npmrc: //git.sync.wtf/api/packages/troed/npm/:_authToken=… and //registry.npmjs.org/:_authToken=….

Publish to local Gitea registry

# ensure @troed:registry points at https://git.sync.wtf/api/packages/troed/npm/
npm publish

Publish to public npmjs

1. Back up the config: cp ~/.npmrc ~/.npmrc.bak-$(date +%Y%m%d-%H%M%S)
2. Point the scope at npmjs: set @troed:registry=https://registry.npmjs.org/ in ~/.npmrc
3. Authenticate (browser flow): npm login --scope=@troed — open the printed URL, then npm whoami should print troed
4. Publish: npm publish
   • npmjs additionally requires a fresh publish-time web authentication (separate from login). Headless, npm masks that URL with ***; run under a pseudo-TTY to get the real link and let it poll until you finish in the browser:

     script -qec "npm publish --browser=/bin/echo" /dev/null
     

5. Verify: curl -s https://registry.npmjs.org/@troed%2foc-ls-stats | jq '.dist-tags'
6. Restore the backup (cp ~/.npmrc.bak-<timestamp> ~/.npmrc) before the next local-registry publish.