releases-cli AGENTS.md

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 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) that proxy to api.releases.sh. Mirrors the canonical tool names served by the hosted server at mcp.releases.sh. 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.
• 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. The Claude plugin references these folders directly through .claude-plugin/marketplace.json (the plugin's skills array lists ./skills/<name> paths, resolved against the repo root via source: "./"), so editing a skill is the whole change — nothing to re-sync. 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/ — Claude Code plugin. Bundles the hosted MCP connection + the skills referenced from skills/ via marketplace.json.
• npm/ — meta package (@buildinternet/releases) + five platform binary packages. CI writes the compiled binary into each platform package before publishing.