Cursor rule

1---
2description: "Package registry publishing for npm, crates.io, PyPI, and Homebrew. Verifies prerequisites, runs the publish command, confirms success, and surfaces actionable error hints on failure."
3alwaysApply: false
4---
5 
6# Publish Package
7 
8> **HARD GATE** — Do not attempt to publish without verifying prerequisites. Missing auth tokens, stale builds, or duplicate versions cause CI failures that are hard to debug post-push.
9>
10> **HARD GATE** — Always run `--dry-run` first. Package registries are append-only — a bad publish cannot be fully undone on most registries.
11 
12Publish packages to language-specific registries. Detects package type from manifest files, verifies publish prerequisites, runs the registry-specific publish command, and confirms the version appears on the registry.
13 
14## Process
15 
16### 1. Detect package type
17 
18Read the project root for manifest files to determine the package type:
19 
20| Manifest | Registry | Publish command |
21|----------|----------|----------------|
22| `package.json` | npm | `npm publish --access public` |
23| `Cargo.toml` | crates.io | `cargo publish` |
24| `setup.py` / `pyproject.toml` | PyPI | `twine upload dist/*` or `flit publish` |
25| `Formula/<name>.rb` | Homebrew | `brew bump-formula-pr` |
26| Multiple detected | Polyglot | Error: specify registry with `--registry <npm|crates.io|pypi|brew>` |
27 
28If no manifest is found, prompt the user to specify the type or pass `--type <npm|crates.io|pypi|brew>`.
29 
30### 2. Verify prerequisites
31 
32Before attempting any publish, run all applicable checks:
33 
34**npm (`package.json`):**
35See [REFERENCE.md](REFERENCE.md)
36 
37**crates.io (`Cargo.toml`):**
38See [REFERENCE.md](REFERENCE.md)
39 
40**PyPI (`setup.py` / `pyproject.toml`):**
41See [REFERENCE.md](REFERENCE.md)
42 
43### 3. Run publish
44 
45After all prerequisite checks pass, run the registry-specific command:
46 
47See [REFERENCE.md](REFERENCE.md)
48 
49### 4. Verify publish success
50 
51After publish, confirm the version appears on the registry:
52 
53See [REFERENCE.md](REFERENCE.md)
54 
55### 5. Error handling
56 
57On failure, surface actionable hints:
58 
59See [REFERENCE.md](REFERENCE.md)
60 
61### 6. Dry-run mode (`--dry-run`)
62 
63Run `--dry-run` to verify all prerequisites without actually publishing:
64 
65See [REFERENCE.md](REFERENCE.md)
66 
67### 7. Dry-run mode per registry
68 
69See [REFERENCE.md](REFERENCE.md)
70 
71## Verify
72 
73→ verify: `test -f skills/publish-package/SKILL.md && test -f package.json`
74→ verify: `grep -q publish-package SKILL-INDEX.md`
75 
76---
77 
78# Publish Package — Reference
79 
80## Navigation
81 
82| Lines | Section |
83|-------|---------|
84| 1 | Title |
85| 3–23 | Navigation |
86| 24–35 | Options |
87| 36–37 | Examples |
88| 38–51 | Publish an npm package |
89| 52–59 | Publish a Rust crate |
90| 60–69 | Missing token scenario |
91| 70–80 | Integration with release-branch |
92| 81–121 | Reference block 1 |
93| 122–143 | Reference block 2 |
94| 144–162 | Reference block 3 |
95| 163–180 | Reference block 4 |
96| 181–195 | Reference block 5 |
97| 196–230 | Reference block 6 |
98| 231–248 | Reference block 7 |
99| 249–260 | Reference block 8 |
100 
101## Options
102 
103| Flag | Description |
104|------|-------------|
105| `--dry-run` | Verify prerequisites and show publish command without executing |
106| `--registry <type>` | Force registry type (skip auto-detection) |
107| `--otp <code>` | One-time password for npm 2FA |
108| `--no-verify` | Skip prerequisite checks (use with caution) |
109 
110 
111---
112 
113## Examples
114 
115### Publish an npm package
116 
117```bash
118# Verify first
119publish-package --dry-run
120 
121# Publish
122publish-package
123 
124# Output:
125#   [npm] Publishing my-package v0.4.0...
126#   OK: npm publish confirmed (my-package@0.4.0 on registry)
127```
128 
129### Publish a Rust crate
130 
131```bash
132export CARGO_REGISTRY_TOKEN=&lt;token&gt;
133publish-package --dry-run
134publish-package
135```
136 
137### Missing token scenario
138 
139```bash
140$ publish-package
141FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=&lt;token&gt; or add to .npmrc
142```
143 
144 
145---
146 
147## Integration with release-branch
148 
149When wired into `release-branch`, add a step after git push:
150 
151```
1526a. Run publish-package to publish to package registries
153    → verify: publish-package --dry-run && publish-package
154```
155 
156---
157 
158## Reference block 1
159 
160```bash
161# Check auth token exists
162if [ -z &quot;${NPM_TOKEN:-}&quot; ]; then
163  if [ ! -f ~/.npmrc ] || ! grep -q &quot;_authToken&quot; ~/.npmrc; then
164    echo &quot;FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=&lt;token&gt; or add //registry.npmjs.org/:_authToken=&lt;token&gt; to .npmrc&quot;
165    exit 1
166  fi
167fi
168 
169# Check version not already published
170PACKAGE_NAME=$(node -p &quot;require('./package.json').name&quot;)
171CURRENT_VER=$(node -p &quot;require('./package.json').version&quot;)
172if npm view &quot;$PACKAGE_NAME@$CURRENT_VER&quot; version 2&gt;/dev/null; then
173  echo &quot;FAIL: Version $CURRENT_VER already published for $PACKAGE_NAME. Bump version first.&quot;
174  exit 1
175fi
176 
177# Check build artifacts are fresh
178if [ -d dist ] || [ -d lib ]; then
179  LATEST_BUILD=$(find dist lib 2&gt;/dev/null -name &quot;*.js&quot; -o -name &quot;*.cjs&quot; -o -name &quot;*.mjs&quot; | xargs ls -t 2&gt;/dev/null | head -1)
180  PACKAGE_MODIFIED=$(stat -f %m package.json 2&gt;/dev/null || stat -c %Y package.json 2&gt;/dev/null)
181  if [ -n &quot;$LATEST_BUILD&quot; ] && [ -n &quot;$PACKAGE_MODIFIED&quot; ]; then
182    BUILD_TIME=$(stat -f %m &quot;$LATEST_BUILD&quot; 2&gt;/dev/null || stat -c %Y &quot;$LATEST_BUILD&quot; 2&gt;/dev/null)
183    if [ &quot;$BUILD_TIME&quot; -lt &quot;$PACKAGE_MODIFIED&quot; ]; then
184      echo &quot;WARNING: Build artifacts may be stale (package.json modified after last build). Run npm run build first.&quot;
185    fi
186  fi
187fi
188 
189# Check CHANGELOG is updated
190if [ -f CHANGELOG.md ]; then
191  if ! grep -q &quot;$CURRENT_VER&quot; CHANGELOG.md 2&gt;/dev/null; then
192    echo &quot;WARNING: Version $CURRENT_VER not found in CHANGELOG.md. Update changelog before publish.&quot;
193  fi
194fi
195```
196 
197---
198 
199## Reference block 2
200 
201```bash
202# Check auth token exists
203if [ -z &quot;${CARGO_REGISTRY_TOKEN:-}&quot; ]; then
204  if [ ! -f ~/.cargo/config.toml ] || ! grep -q &quot;token&quot; ~/.cargo/config.toml; then
205    echo &quot;FAIL: CARGO_REGISTRY_TOKEN not set. Set via: export CARGO_REGISTRY_TOKEN=&lt;token&gt; or add to ~/.cargo/config.toml&quot;
206    exit 1
207  fi
208fi
209 
210# Check version not already published
211CRATE_NAME=$(grep '^name' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
212CURRENT_VER=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
213if cargo search &quot;$CRATE_NAME&quot; 2&gt;/dev/null | grep -q &quot;^${CRATE_NAME}.*\&quot;$CURRENT_VER\&quot;&quot;; then
214  echo &quot;FAIL: Version $CURRENT_VER already published for $CRATE_NAME. Bump version in Cargo.toml first.&quot;
215  exit 1
216fi
217```
218 
219---
220 
221## Reference block 3
222 
223```bash
224# Check auth token exists
225if [ -z &quot;${TWINE_PASSWORD:-}&quot; ] && [ -z &quot;${POETRY_PYPI_TOKEN_PYPI:-}&quot; ]; then
226  if [ ! -f ~/.pypirc ]; then
227    echo &quot;FAIL: PyPI token not configured. Set TWINE_PASSWORD or create ~/.pypirc&quot;
228    exit 1
229  fi
230fi
231 
232# Check for build artifacts
233if [ ! -d dist ] || [ -z &quot;$(ls dist/*.whl 2&gt;/dev/null)&quot; ]; then
234  echo &quot;WARNING: No .whl files found in dist/. Run: python -m build&quot;
235fi
236```
237 
238---
239 
240## Reference block 4
241 
242```bash
243# npm
244npm publish --access public
245 
246# crates.io
247cargo publish
248 
249# PyPI
250python -m twine upload dist/*  # or: poetry publish
251 
252# Homebrew (opens PR, does not publish directly)
253brew bump-formula-pr --url=&lt;tarball-url&gt; &lt;formula-name&gt;
254```
255 
256---
257 
258## Reference block 5
259 
260```bash
261# npm
262npm view &quot;$PACKAGE_NAME&quot; versions --json 2&gt;/dev/null | grep -q &quot;\&quot;$CURRENT_VER\&quot;&quot; && echo &quot;OK: npm publish confirmed&quot;
263 
264# crates.io
265cargo search &quot;$CRATE_NAME&quot; 2&gt;/dev/null | grep -q &quot;^${CRATE_NAME}.*\&quot;$CURRENT_VER\&quot;&quot; && echo &quot;OK: crates.io publish confirmed&quot;
266 
267# PyPI
268pip index versions &quot;$PACKAGE_NAME&quot; 2&gt;/dev/null | grep -q &quot;$CURRENT_VER&quot; && echo &quot;OK: PyPI publish confirmed&quot;
269```
270 
271---
272 
273## Reference block 6
274 
275```bash
276# Generic failure handler
277if [ $? -ne 0 ]; then
278  case &quot;$REGISTRY&quot; in
279    npm)
280      echo &quot;FAIL: npm publish failed.&quot;
281      echo &quot;  Common causes:&quot;
282      echo &quot;  - NPM_TOKEN not set in secrets: add to GitHub repo secrets&quot;
283      echo &quot;  - Version already published: bump version in package.json&quot;
284      echo &quot;  - Two-factor auth required: use --otp=&lt;code&gt; flag&quot;
285      echo &quot;  - Package scoped but not public: add --access public&quot;
286      ;;
287    crates.io)
288      echo &quot;FAIL: cargo publish failed.&quot;
289      echo &quot;  Common causes:&quot;
290      echo &quot;  - CARGO_REGISTRY_TOKEN not configured: see ~/.cargo/config.toml&quot;
291      echo &quot;  - Version already published: bump version in Cargo.toml&quot;
292      echo &quot;  - Local changes not committed: cargo publish requires clean working tree&quot;
293      ;;
294    pypi)
295      echo &quot;FAIL: PyPI publish failed.&quot;
296      echo &quot;  Common causes:&quot;
297      echo &quot;  - TWINE_PASSWORD not configured: set env var or ~/.pypirc&quot;
298      echo &quot;  - Build artifacts missing: run python -m build first&quot;
299      echo &quot;  - Version conflict: version already exists on PyPI&quot;
300      ;;
301  esac
302  exit 1
303fi
304```
305 
306---
307 
308## Reference block 7
309 
310```bash
311# Example output
312$ publish-package --dry-run
313 
314[DRY-RUN] Detected package type: npm
315[DRY-RUN] Package: my-package v0.4.0
316[DRY-RUN] Checking NPM_TOKEN... OK
317[DRY-RUN] Checking version 0.4.0 not already published... OK
318[DRY-RUN] Checking build artifacts... WARNING: package.json modified after build
319[DRY-RUN] Checking CHANGELOG... OK
320[DRY-RUN] Would run: npm publish --access public
321[DRY-RUN] Exiting without publishing.
322```
323 
324---
325 
326## Reference block 8
327 
328```bash
329# npm dry-run
330npm publish --access public --dry-run
331 
332# crates.io dry-run (cargo does not have a publish dry-run; use --dry-run flag for validation only)
333cargo package --list 2&gt;/dev/null
334 
335# PyPI dry-run
336python -m twine upload --repository testpypi dist/*  # test.pypi.org
337```
338