@opencow-ai/opencow-agent-sdk 0.4.0 → 0.4.2-beta.0

package/README.md

@@ -8,6 +8,7 @@ OpenCow Agent SDK is an open-source coding agent toolkit with two entrypoints:
 Use one workflow across OpenAI-compatible APIs, Gemini, GitHub Models, Codex, Ollama, Atomic Chat, and other supported backends, with tools, agents, MCP, and streaming responses.
 
 [![PR Checks](https://github.com/OpenCowAI/opencow-agent-sdk/actions/workflows/pr-checks.yml/badge.svg?branch=main)](https://github.com/OpenCowAI/opencow-agent-sdk/actions/workflows/pr-checks.yml)
+[![Publish to npm](https://github.com/OpenCowAI/opencow-agent-sdk/actions/workflows/release.yml/badge.svg)](https://github.com/OpenCowAI/opencow-agent-sdk/actions/workflows/release.yml)
 [![Release](https://img.shields.io/github/v/tag/OpenCowAI/opencow-agent-sdk?label=release&color=0ea5e9)](https://github.com/OpenCowAI/opencow-agent-sdk/tags)
 [![Discussions](https://img.shields.io/badge/discussions-open-7c3aed)](https://github.com/OpenCowAI/opencow-agent-sdk/discussions)
 [![Security Policy](https://img.shields.io/badge/security-policy-0f766e)](SECURITY.md)
@@ -27,6 +28,7 @@ Use one workflow across OpenAI-compatible APIs, Gemini, GitHub Models, Codex, Ol
 - [Setup Guides](#setup-guides)
 - [Build From Source](#build-from-source)
 - [Testing and Validation](#testing-and-validation)
+- [Release Process](#release-process)
 - [Repository Structure](#repository-structure)
 - [VS Code Extension](#vs-code-extension)
 - [Contributing](#contributing)
@@ -313,6 +315,76 @@ Additional checks:
 - `bun run security:pr-scan -- --base origin/main`
 - focused `bun test path/to/file.test.ts`
 
+## Release Process
+
+Releases are split between local preparation and a CI-driven publish step. Pushing a `v*` tag triggers `.github/workflows/release.yml`, which publishes to npm and creates a GitHub Release.
+
+### Cut a new version
+
+The interactive flow drafts user-facing release notes, writes them to `CHANGELOG.md`, then hands off to the local prepare script:
+
+```
+/yg.release patch          # 0.4.0 → 0.4.1 (also accepts: minor | major | <x.y.z>)
+```
+
+The slash command is defined at `.claude/commands/yg.release.md` and runs inside Claude Code. If you prefer to skip the notes-drafting step and bump directly, call the prepare script:
+
+```bash
+bun run release:patch       # or release:minor / release:major
+bun run release:dry         # full-pipeline preview, no file writes, no push
+bun run release -- --version 0.5.0-rc.1   # explicit version (prerelease → next dist-tag)
+```
+
+`bun run release` runs preflight checks, bumps `package.json`, renames `## [Unreleased]` in `CHANGELOG.md` to `## [X.Y.Z] — YYYY-MM-DD`, typechecks, builds, smoke-tests, commits, tags, and pushes. After the tag push, CI takes over:
+
+1. verifies the tag matches `package.json`
+2. installs, typechecks, builds, smoke-tests
+3. publishes the main package via `scripts/publish.ts`
+4. creates a GitHub Release with the matching `CHANGELOG.md` section as body
+
+The dist-tag is inferred from semver — versions containing `-` (e.g. `0.5.0-rc.1`) publish to `next`, everything else to `latest`.
+
+### Ripgrep subpackages
+
+The 8 platform-specific `@opencow-ai/ripgrep-*` packages are published independently and only when the underlying `rg` binary changes. Most main-package releases do not touch them — the main package's `optionalDependencies` keeps pointing at the last published ripgrep version, and CI skips the subpackage publish step automatically.
+
+When you do update the ripgrep binary across all 8 `packages/ripgrep-*` directories:
+
+```bash
+bun run release:ripgrep -- --bump patch
+```
+
+This runs locally (no CI), publishes all 8 subpackages, updates the main package's `optionalDependencies`, and commits — but does not create a tag. The next regular `/yg.release` will pick up the new ripgrep version automatically.
+
+### CI prerequisites
+
+The publish workflow uses [npm Trusted Publishers](https://docs.npmjs.com/trusted-publishers) (OIDC). No long-lived `NPM_TOKEN` is needed.
+
+Setup is per-package on npmjs.com. For each of the 9 packages below, open the package's npmjs.com page → **Settings → Trusted Publishers → Add → GitHub Actions** and fill in:
+
+- **Organization or user**: `OpenCowAI`
+- **Repository**: `opencow-agent-sdk`
+- **Workflow filename**: `release.yml`
+- **Environment name**: leave blank
+
+Packages to configure:
+
+```
+@opencow-ai/opencow-agent-sdk
+@opencow-ai/ripgrep-darwin-arm64
+@opencow-ai/ripgrep-darwin-x64
+@opencow-ai/ripgrep-linux-arm64
+@opencow-ai/ripgrep-linux-x64
+@opencow-ai/ripgrep-linux-arm
+@opencow-ai/ripgrep-win32-arm64
+@opencow-ai/ripgrep-win32-x64
+@opencow-ai/ripgrep-win32-ia32
+```
+
+npm does not validate Trusted Publisher config when saved — errors only surface at publish time. Test with a prerelease (`bun run release -- --version 0.x.y-rc.0`) before cutting a real release. The workflow already pins `permissions: id-token: write` and upgrades npm to the latest version (Trusted Publishers requires npm ≥ 11.5.1).
+
+Design and implementation notes live in `docs/superpowers/specs/2026-05-18-release-pipeline-design.md`.
+
 ## Repository Structure
 
 - `src/` - core CLI/runtime and SDK entrypoints