docs(bun): port bun-publish OIDC skill to pleaseai/bun + fix broken `bun pm pack` capture snippet

[amondnet]

Summary

The new pleaseai/bun plugin (currently 1.3.0) has no npm publishing guidance, and the publishing skill that shipped in the now-deprecated passionfactory/bun plugin (bun-publish, v2.1.0) contains a broken shell snippet. Since users are being actively migrated from passionfactory/bun → pleaseai/bun (via the SessionStart migration notice), the publishing know-how is being lost in the move.

This issue asks to (1) port the bun-publish skill into plugins/bun, and (2) fix the verified gotchas below before/while porting.

Context

• plugins/bun/skills/use-bun/references/package-manager.md only lists bun pm pack / bun publish as one-liners. It does not cover the OIDC provenance gap, the npm publish tarball workaround, or npm trusted publishers.
• The passionfactory/bun@2.1.0 bun-publish skill covers all of that — but it never made it into pleaseai/bun.

All findings below were verified empirically on Bun 1.3.14.

Gotcha 1 — bun publish has no OIDC provenance (keep the two-step workaround)

bun publish cannot attach OIDC provenance attestations (tracking: oven-sh/bun#15601), and npm publish cannot resolve Bun's workspace:* / catalog: protocols. The working pattern is:

bun pm pack ...          # resolves workspace:*/catalog:, produces a plain npm .tgz
npm publish <tarball> --provenance --access public   # OIDC + provenance

This is the core value of the skill and should be preserved when porting.

Gotcha 2 — the pack-capture snippet is broken without --quiet 🐛

The current bun-publish skill captures the tarball path like this:

TARBALL=$(bun pm pack --destination ./dist 2>&1 | tail -1)
npm publish "$TARBALL" --provenance --access public

This is broken. Without --quiet, bun pm pack prints human-readable stats to stdout, so tail -1 captures the wrong line:

Total files: 7
Shasum: 9029e444...
Integrity: sha512-...
Unpacked size: 38.76KB
Packed size: 8.96KB      <-- tail -1 grabs THIS

→ TARBALL="Packed size: 8.96KB" → npm publish fails with a "no such file" error.

Fix: add --quiet. With --quiet, stdout is the tarball path itself (an absolute path when --destination is used):

TARBALL="$(bun pm pack --quiet --destination ./dist)"
npm publish "$TARBALL" --provenance --access public

Gotcha 3 — --filename / --destination exclusivity & workspace-root write

• --filename and --destination are mutually exclusive — passing both errors:
  error: cannot use both filename and destination at the same time with tarball
• With bare --filename <name> (no --destination), the tarball is written to the workspace root, not the current package directory — surprising in a monorepo when running from packages/<x>/.
• Recommendation for monorepos: prefer --quiet --destination <dir> and consume the printed absolute path, rather than --filename + a hand-computed relative path.

Suggested action

1. Port bun-publish skill from passionfactory/bun@2.1.0 into plugins/bun/skills/.
2. Apply the Gotcha 2 fix (--quiet) to every snippet, including the Multi-Package Publishing and release-please Integration examples.
3. Add a short note covering Gotcha 3.

Reference: real-world working workflow

A live monorepo (pleaseai/code-style) using this exact pattern with release-please + trusted publishing:

permissions:
  contents: read
  id-token: write   # required for OIDC trusted publishing + provenance

steps:
  # ...setup-bun, setup-node (>=22.14), npm i -g npm@latest (>=11.5.1)...
  - name: Publish @pleaseai/eslint-config
    if: ${{ needs.release-please.outputs.eslint-config-released == 'true' }}
    working-directory: packages/eslint-config
    run: |
      bun pm pack --quiet --filename eslint-config.tgz
      npm publish ../../eslint-config.tgz --access public --provenance

(Note: this workflow uses --filename and references ../../<name>.tgz precisely because of Gotcha 3 — the tarball lands at the workspace root. A --quiet --destination variant would be cleaner and is what the skill should recommend.)

References

• npm Trusted Publishers — requires npm ≥ 11.5.1, Node ≥ 22.14.0, id-token: write
• oven-sh/bun#15601 — OIDC provenance tracking issue