# Releasing on GitHub

This project is distributed from GitHub tags, not the npm registry. `package.json` is marked `private` and its `prepublishOnly` hook intentionally fails so an accidental `npm publish` stops before upload.

Only release from a clean, reviewed `main` branch. The connector relies on a private-by-convention `PiAiAdapter.current()` seam, so dependency upgrades require deliberate compatibility testing rather than an automatic range bump.

## Prerequisites

- Node.js `>=22.19.0` and npm `>=10`
- The canonical `zhangxiubo/dsh-llm-chatgpt-oauth` GitHub remote configured as `origin`
- Permission to push tags and create releases in the GitHub repository
- A dedicated test OAuth grant for the optional live check

## Release checklist

1. Update `version` in `package.json` and `package-lock.json` without creating a tag:

   ```bash
   npm version <patch|minor|major> --no-git-tag-version
   ```

   Skip this step when preparing the initial `v0.1.0` release and the files already contain `0.1.0`.

2. Move release notes into the matching dated section of `CHANGELOG.md`.
3. Install exactly what the lockfile declares and run the offline suite:

   ```bash
   npm ci
   npm audit --omit=dev
   npm run verify
   ```

4. When Harness, pi-ai, authentication, or streaming behavior changed, run the credentialed live test:

   ```bash
   RUN_LIVE_CODEX=1 npm run test:live
   ```

5. Inspect the repository's distributable package payload:

   ```bash
   npm pack --dry-run
   npm pack --json
   ```

   Confirm that no credential, local path, test fixture, or environment file is present. The generated tarball is only a local inspection artifact and need not be attached to the GitHub release. Git installs use the committed JavaScript source directly; this package deliberately has no `prepare` build or install-time code execution.

6. Commit the release, create an annotated tag, and push both:

   ```bash
   version=$(node -p "require('./package.json').version")
   git add -A
   git commit -m "Release v$version"
   git tag -a "v$version" -m "v$version"
   git push origin main --follow-tags
   ```

7. Create a GitHub release and put the immutable release commit in its notes:

   ```bash
   version=$(node -p "require('./package.json').version")
   release_commit=$(git rev-list -n 1 "v$version")
   install="dsh plugin --profile web add 'github:zhangxiubo/dsh-llm-chatgpt-oauth#$release_commit'"
   notes=$(printf 'Release commit: `%s`\n\nInstall: `%s`' "$release_commit" "$install")
   gh release create "v$version" --title "v$version" --generate-notes --notes "$notes"
   ```

8. Verify a fresh immutable DSH install:

   ```bash
   version=$(node -p "require('./package.json').version")
   release_commit=$(git rev-list -n 1 "v$version")
   dsh plugin --profile web add "github:zhangxiubo/dsh-llm-chatgpt-oauth#$release_commit"
   ```

Never run the live test in public CI or upload OAuth files as release assets.