---
name: publish-cli
description: >-
  Publish a new version of @rootplatform/cli to npm. Use when the user asks to
  publish, deploy, or release a new CLI version, or mentions bumping the
  version, creating a release, or pushing to npm.
---

# Publish @rootplatform/cli

## Overview

Publishing happens through GitHub Releases. A GitHub Action (`publish.yml`)
automatically builds, tests, and publishes to npm when a release is created.
Never run `npm publish` directly.

## Pre-flight checks

Before starting, verify:

1. You are on a **feature branch** (not `main`).
2. The working tree is clean (`git status`).
3. Build succeeds: `npm run build`
4. Tests pass: `npm test`
5. No sensitive files leak into the tarball: `npm pack --dry-run`

If any check fails, fix it before proceeding.

## Step 1 — Bump version

Ask the user which semver bump to apply using AskQuestion:

| Bump  | When to use                                         |
|-------|-----------------------------------------------------|
| patch | Bug fixes, small tweaks, documentation updates      |
| minor | New features, non-breaking changes                  |
| major | Breaking changes to CLI commands or public API      |

Then update the `version` field in `package.json` using StrReplace.
Do **not** use `npm version` (it auto-commits and auto-tags).

Show the user the old and new version for confirmation.

## Step 2 — Draft release notes

1. Find the latest release tag:
   ```bash
   git describe --tags --abbrev=0
   ```
2. Gather commits since that tag:
   ```bash
   git log <tag>..HEAD --oneline
   ```
3. Draft a concise release title and markdown description summarising the
   changes. The title and description are **publicly visible** on GitHub and
   represent content published on behalf of Root.
4. Present the draft to the user for approval.

## Step 3 — Commit, push, and update PR

1. Commit only the version bump:
   ```bash
   git add package.json
   git commit -m "chore: bump version to <new-version>"
   ```
2. Push the branch:
   ```bash
   git push origin HEAD
   ```
3. If a PR exists for this branch, update its description to include the
   approved release title and notes (so reviewers can approve the release
   copy):
   ```bash
   gh pr edit --body "..."
   ```

**Stop here.** The PR must be reviewed and merged before continuing.

## Step 4 — Create GitHub release (post-merge only)

Only proceed once the PR is merged into `main`.

1. Confirm you are on `main` and up to date:
   ```bash
   git checkout main && git pull origin main
   ```
2. Create the release. The tag must match the version prefixed with `v`:
   ```bash
   gh release create v<version> \
     --target main \
     --title "<release-title>" \
     --notes "<release-notes-markdown>"
   ```
   **Critical**: publish as a release, NOT a draft. Drafts do not trigger the
   GitHub Action.

## Step 5 — Verify publish

Poll the npm registry until the new version appears (may take 1–3 minutes):

```bash
curl -s https://registry.npmjs.org/@rootplatform/cli | jq '.["dist-tags"].latest'
```

Report the result to the user.

## Step 6 — Post-publish reminders

Flag these to the user (the AI cannot do them):

1. **#changelog Slack channel** — Post a message adapted from the release notes.
2. **Update the guides** — If new features were added, update the relevant
   documentation per https://root-platform.slite.com/app/docs/Whwdl4CDAQl7EH

## Safety rules

- NEVER run `npm publish` directly.
- NEVER create a draft release (the Action won't trigger).
- NEVER skip local tests before pushing.
- ALWAYS confirm the version bump type with the user.
- ALWAYS show release notes to the user for approval before creating the release.