Skip to content

Commit 683fed9

Browse files
nonthclaude
andcommitted
docs(scripts): expand publish.sh comments and add workspace: guard
- Group the header into "why this script exists", "what this script does", and "output format" sections to make the rationale and the upstream issue (changesets/changesets#432) discoverable for future maintainers. - Annotate each step inline so the role of yarn pack vs npm publish vs the idempotency check is clear at a glance. - Add a pre-publish guard: after yarn pack, grep the tarball's embedded package.json for any leftover "workspace: protocol entries and abort with a clear error if found. Prevents another round of broken tarballs hitting the public registry if yarn pack ever stops substituting (regression, wrong yarn version, etc.). Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
1 parent c57414d commit 683fed9

1 file changed

Lines changed: 59 additions & 8 deletions

File tree

‎scripts/publish.sh‎

Lines changed: 59 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,44 @@
11
#!/usr/bin/env bash
2+
#
23
# Publish @inoxth/* packages to npm.
34
#
4-
# Uses `yarn pack` (substitutes the workspace:* protocol with concrete versions
5-
# at pack time) then `npm publish <tgz>` (auth via ~/.npmrc + WebAuthn locally,
6-
# OIDC + NODE_AUTH_TOKEN in CI). `npm publish` from a yarn 4 workspace alone
7-
# does not substitute workspace:* — see changesets/changesets#432.
5+
# WHY THIS SCRIPT EXISTS
6+
# ----------------------
7+
# Yarn 4 uses a `workspace:*` protocol to link sibling workspaces during
8+
# development. That protocol is yarn-specific — npm has no idea what it
9+
# means. If `npm publish` is invoked directly from a yarn 4 workspace dir
10+
# (the default behavior of `yarn changeset publish`), the published tarball
11+
# contains the literal string "workspace:*" in its dependencies, which
12+
# breaks every consumer downstream.
13+
#
14+
# Workaround: pack with `yarn pack` first (yarn substitutes workspace:*
15+
# with the concrete sibling version at pack time), then upload the
16+
# already-finalized tarball with `npm publish <tgz>`. See
17+
# https://github.com/changesets/changesets/issues/432.
18+
#
19+
# WHAT THIS SCRIPT DOES
20+
# ---------------------
21+
# For each package in the fixed-group from .changeset/config.json:
22+
# 1. yarn pack → tarball with workspace:* substituted
23+
# 2. assert → fail loudly if substitution didn't happen
24+
# 3. npm view → skip if this name@version is already on registry
25+
# 4. npm publish <tgz> → upload (auth: ~/.npmrc + WebAuthn locally,
26+
# NODE_AUTH_TOKEN or Trusted Publishing in CI)
827
#
9-
# Idempotent: skips versions already on the registry. Adds --provenance when
10-
# running in GitHub Actions with id-token: write (detected via OIDC env var).
28+
# OUTPUT FORMAT
29+
# -------------
30+
# Emits "🦋 success packages published successfully:" lines so
31+
# changesets/action@v1 can parse the output and auto-create GitHub releases.
1132

1233
set -euo pipefail
1334

35+
# Where packed tarballs go. Override with PACK_DIR=... for testing.
1436
PACK_DIR="${PACK_DIR:-/tmp/edot-publish}"
1537
mkdir -p "$PACK_DIR"
1638

39+
# Pull the list of publishable packages from changesets config. This keeps
40+
# the script in sync with the fixed-group declaration (single source of truth)
41+
# rather than hardcoding package names here.
1742
PACKAGES=()
1843
while IFS= read -r line; do
1944
PACKAGES+=("$line")
@@ -22,21 +47,45 @@ done < <(jq -r '.fixed[0][]' .changeset/config.json)
2247
PUBLISHED=()
2348

2449
for ws in "${PACKAGES[@]}"; do
50+
# Derive a flat filename from the scoped package name:
51+
# @inoxth/react-native-edot-shared → inoxth-react-native-edot-shared.tgz
2552
filename="$(printf '%s' "$ws" | sed 's|^@||; s|/|-|g').tgz"
2653
tarball="$PACK_DIR/$filename"
2754

55+
# Pack the workspace. `yarn pack` is the step that substitutes workspace:*
56+
# → concrete sibling version. The on-disk package.json is untouched; only
57+
# the tarball's embedded package.json gets the resolved versions.
2858
yarn workspace "$ws" pack --out "$tarball"
2959

60+
# Safety net: assert the tarball is free of any leftover workspace:
61+
# protocol references. If yarn pack ever stops substituting (regression,
62+
# config change, wrong yarn version, etc.), abort BEFORE uploading broken
63+
# tarballs to the public registry — unpublishing scoped packages requires
64+
# a 72h window and a 24h republish hold afterward.
65+
if tar -xzOf "$tarball" package/package.json | grep -q '"workspace:'; then
66+
echo "ERROR: $tarball still contains workspace: protocol references." >&2
67+
echo " yarn pack failed to substitute. Aborting before npm publish." >&2
68+
echo " Offending content:" >&2
69+
tar -xzOf "$tarball" package/package.json | grep '"workspace:' >&2
70+
exit 1
71+
fi
72+
73+
# Read the version straight from the packed tarball (post-substitution
74+
# truth) so the idempotency check matches what would actually be uploaded.
3075
version="$(tar -xzOf "$tarball" package/package.json | jq -r .version)"
3176

77+
# Idempotency: if this exact name@version is already on the registry, skip.
78+
# Lets the workflow re-run safely after partial failures (e.g. one
79+
# WebAuthn timeout out of four) without erroring on already-published
80+
# entries.
3281
if npm view "${ws}@${version}" version >/dev/null 2>&1; then
3382
echo "Skipping ${ws}@${version} — already published"
3483
continue
3584
fi
3685

3786
# Override publishConfig.provenance per environment:
38-
# - CI with id-token: write → OIDC available, generate attestation
39-
# - Local → no OIDC, skip attestation
87+
# - CI with id-token: write → OIDC available, generate Sigstore attestation
88+
# - Local → no OIDC, skip attestation so WebAuthn flow can complete
4089
provenance_flag="--no-provenance"
4190
if [ -n "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ]; then
4291
provenance_flag="--provenance"
@@ -48,6 +97,8 @@ for ws in "${PACKAGES[@]}"; do
4897
PUBLISHED+=("${ws}@${version}")
4998
done
5099

100+
# Output in the format changesets/action@v1 expects so it can auto-create
101+
# GitHub releases from a successful publish run.
51102
if [ ${#PUBLISHED[@]} -gt 0 ]; then
52103
echo ""
53104
echo "🦋 success packages published successfully:"

0 commit comments

Comments
 (0)