Windsurf rules

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