releases-cli: Instructions file for Codex

Agents guide — releases-cli

This repo is the public, client-only CLI for the Releases registry. It talks to api.releases.sh over HTTP. Ingest, database access, and AI pipelines live in a separate open-source backend monorepo, buildinternet/releases.

Stack

• Runtime: Bun (required for bun --compile)
• Language: TypeScript (strict mode)
• CLI: Commander
• MCP: @modelcontextprotocol/sdk on stdio
• HTTP client: src/api/client.ts is the only data-access layer. No Drizzle, no SQLite, no local DB.

Commands

bun src/index.ts <command>    # run from source
bun run build                 # compile binary to dist/releases
bun run check                 # oxlint (lint + type-check) + oxfmt check — CI gate
bun run lint                  # oxlint only (`typecheck` is an alias)
bun test                      # bun test (not part of check)

Architecture

• src/index.ts — entry point. Validates config, sets up telemetry, rewrites legacy aliases, hands off to Commander.
• src/cli/program.ts — Commander program wiring. Public reader commands at the top level; operator workflows under admin.
• src/cli/commands/ — one file per command. Every command goes through src/api/client.ts for data access.
• src/api/client.ts — single HTTP boundary. apiFetch() auto-attaches Authorization: Bearer ${RELEASES_API_KEY} when admin mode is active, and (via src/lib/mutation-log.ts) records mutating requests when RELEASES_RUN_DIR is set.
• src/lib/mode.ts — getApiUrl() / getApiKey() / isAdminMode() / validateConfig(). Always remote.
• src/lib/mutation-log.ts — admin-mutation audit log for the ~/.releases/work/ maintenance workspace. When RELEASES_RUN_DIR is set, each non-GET request (minus telemetry/heartbeat plumbing) appends a {timestamp, command, target, result} JSONL line to $RELEASES_RUN_DIR/mutations.jsonl. Unset → no-op; fully fail-open.
• src/lib/trace.ts — managed-session traces. Writes <dir>/<id>/{trace.json,summary.md} for terminal sessions/workflows; dir precedence is explicit flag > RELEASES_RUN_DIR > ~/.releases/work/runs. Used by --trace-dir (onboard, source fetch --wait, overview batch --wait) and task get --save. summary.md mirrors the monorepo's docs/architecture/maintenance-workspace.md run-summary template.
• src/lib/telemetry.ts — anonymous usage pings to api.releases.sh/v1/telemetry. First-run notice shown once. Opt out via RELEASES_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1.
• src/lib/update-check.ts — npm-registry poll for newer CLI versions (24h cache in ~/.releases/update-check.json). Prints a one-line stderr nag after command output when stale. src/lib/skills-update-check.ts mirrors it for the bundled skills: GitHub git/trees/main poll for the plugins/claude/releases/skills/ subtree SHA, cached in ~/.releases/skills-check.json. Baseline is written on successful releases skills install; the nag fires only if a baseline exists and diverges. Defense in depth: when the skills CLI's lock file ($XDG_STATE_HOME/skills/.skill-lock.json or ~/.agents/.skill-lock.json) is present and parses cleanly with zero buildinternet/releases-cli entries, the nag is suppressed (user uninstalled via skills). A missing/unreadable lock file falls through to the baseline check so manual installers aren't penalized. Opt out via RELEASES_DISABLE_SKILL_UPDATE_CHECK=1. Both checks skip non-TTY callers and --help/--version.
• src/mcp/server.ts — local stdio MCP bridge. Exposes read-only tools (search, get_latest_releases, list_catalog, get_catalog_entry, get_source, list_organizations, get_organization, changelog) that proxy to api.releases.sh. Mirrors the canonical tool names served by the hosted server at mcp.releases.sh, plus changelog for recent releases.sh product updates (same as releases changelog: optional limit 1–50, default 5; JSON { url, feed, entries }; GET-only, no writes). get_catalog_entry inlines a CHANGELOG slice for source entries via include_changelog / changelog_path / changelog_offset / changelog_limit / changelog_tokens (products have none — degrades with a clear message). The former get_source_changelog tool was removed in 0.72.0 — use get_catalog_entry with the changelog_* params instead.
• @buildinternet/releases-core — runtime-neutral helpers (schema, categories, slicing, IDs, slugs, tokens, CLI contracts). Published from the private buildinternet/releases monorepo (canonical source in packages/core/), consumed here as a regular npm dependency. Bump the pin in package.json when adopting a new schema.
• packages/lib/ (@buildinternet/releases-lib) — logger, errors, trimmed config.
• plugins/claude/releases/skills/ — single source of truth for the three user-facing agent skills (releases-mcp, releases-cli, analyzing-releases); there is no generated copy and no npm wrapper (@buildinternet/releases-skills is retired/deprecated). Operator skills live in the backend monorepo's .claude/skills/ tree — do not re-add copies here. They live inside the Claude plugin folder because the plugin directory screens everything under a plugin's source, and a plugin can't reference files outside its own folder — so the plugin is self-contained and .claude-plugin/marketplace.json only points source at ./plugins/claude/releases (no inline skills/commands/mcpServers; those are discovered from the plugin's own .claude-plugin/plugin.json and folder layout). npx skills add resolves the same folder through the marketplace source, so editing a skill is the whole change — nothing to re-sync. Don't move them back to the repo root: that makes the whole repo the plugin again. Cross-agent install runs through releases skills install, which shells out to npx skills add buildinternet/releases-cli (the vercel-labs/skills ecosystem). Wiring is in src/cli/commands/skills.ts; pure argv construction in src/cli/skills/build-args.ts.
• plugins/claude/releases/ — agent plugin in the common plugin layout (listed in the Claude Code marketplace; submitted to the xAI plugin marketplace as release-notes-index, pending review; add further marketplaces as install subsections in its README without rewording the intro), self-contained: .claude-plugin/plugin.json (+ icon.svg, copied from the web app's apps/web/src/app/icon.svg in the monorepo), .mcp.json (hosted MCP, wrapped in mcpServers — the flat form loads in Claude Code but xAI's catalog scanner ignores it), commands/, skills/. Validate with claude plugin validate . from the repo root. Keep the folder path: the Claude directory listing pins plugins/claude/releases, and the xAI catalog entry will pin the same path.
• npm/ — meta package (@buildinternet/releases) + five platform binary packages. CI writes the compiled binary into each platform package before publishing.