# Releasing

The repo is a pnpm monorepo. Each package is versioned independently; the
aggregate package and root bundle pin exact versions of every plugin.

## Preconditions

- npm scope/account exists for `@icedrop-ai`.
- GitHub Actions secret `NPM_TOKEN` is optional. Without it, the release
  workflow still builds and attaches tarballs to the GitHub Release but skips
  npm publishing. With it, packages are published to npm.

## One-time setup

1. Create the npm scope `@icedrop-ai` (or change every `@icedrop-ai/*`
   package name and dependency to a scope you own).
2. Optional: add `NPM_TOKEN` under GitHub repository secrets. Use an npm
   granular token with **Read and write** package permission and 2FA bypass for
   CI. A future migration to npm Trusted Publishing only needs the
   `id-token: write` permission already present in the workflow.
3. Add topic `dsh-plugin` in the GitHub repository settings.

## Bump and release

```sh
git switch main && git pull

# 1. bump each changed package's version in packages/<name>/package.json
# 2. regenerate the aggregate patches and exact dependency pins
pnpm aggregate

# 3. verify locally
pnpm check
pnpm vendor

# 4. commit, push, and tag the aggregate version
git add .
git commit -m "release: v0.1.1"
git push origin main
git tag "v$(node -p "require('./packages/all/package.json').version")"
git push origin --tags
```

The `release` workflow verifies the tag matches `@icedrop-ai/dsh-all`, runs
`pnpm check`, builds `vendor/*.tgz` + `plugins.lock.json`, publishes changed
packages to npm when `NPM_TOKEN` is configured, and creates/edits the GitHub
Release with the tarballs attached.

## Rules

- Never commit `workspace:` dependency specs. `pnpm check` fails on them; Git
  subpath installs would fail with `ERR_PNPM_WORKSPACE_PKG_NOT_FOUND`.
- Prefer exact versions in aggregate dependencies. Consumers get a reproducible
  bundle.
- Ship built `lib/` inside each package. GitHub installs must not depend on
  install-time `prepare` scripts and pnpm's `allowBuilds` approval.
- Keep official `@deepseek-ai/*` packages in `peerDependencies`.
- Tag names use the aggregate version (`vX.Y.Z`). If per-plugin releases become
  necessary later, add `pkg-vX.Y.Z` tags and split the workflow.