docs(skill): first-publish bootstrap + preflight registry probe#53
Open
jadb wants to merge 6 commits into
Open
docs(skill): first-publish bootstrap + preflight registry probe#53jadb wants to merge 6 commits into
jadb wants to merge 6 commits into
Conversation
new section covering npm/PyPI/crates.io first-publish constraints — scoped tokens grant updates not creation. local bootstrap path per registry. publish-py.yml comment cross-link.
ERR_PNPM_OTP_NON_INTERACTIVE root-caused to 'Auth and writes' 2FA mode (CI cannot supply OTP). expired-token returns HTTP 404 not 401/403 — misreads as scope/permission issue.
local-run helper for first publish of new npm/PyPI/cargo packages. verifies auth, probes registry for prior existence, dispatches the right build + publish. handoff to publish-on-tag.yml after first release lands.
new parallel job 'first-publish-risk'. probes npm/PyPI/crates.io/ Packagist for each component in release-please-config.json. emits ::warning:: with bootstrap command when name is unclaimed. annotation-only — fail-on policy stays in preflight job.
…try-probe accuracy + dirty-tree guard - preflight first-publish-risk: set -euo pipefail (fail-fast on real errors) - preflight first-publish-risk: timeout-minutes 5 + curl --max-time 10 on 4 probes - bootstrap cargo: gate "no published versions" message inside HTTP 200; explicit 404 + inconclusive branches - bootstrap npm: drop --no-git-checks (restore dirty-tree guard)
- references/troubleshooting/ts.md: first-publish, ERR_PNPM_OTP_NON_INTERACTIVE, 404-on-expired-token cross-links to SKILL.md. - references/troubleshooting/py.md: first-publish PyPI cross-link (token scoping + OIDC pre-registration). - references/troubleshooting/rs.md: first-publish crates.io cross-link (unrestricted-token rationale + local cargo publish). - scripts/README.md: new — bootstrap-first-publish.sh subcommand table, dirty-tree note, pointer to SKILL.md companion section.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
per-registry constraints: scoped npm/PyPI/crates.io tokens grant version
updates but not name creation. Documents the local bootstrap path
(
npm login+pnpm publish --access public;uv build+uv run twine uploadwith an account-scoped token;cargo loginwith anunrestricted token) and the handoff to CI for subsequent versions.
covering two confusing symptoms:
ERR_PNPM_OTP_NON_INTERACTIVEcaused by npm 2FA in "Auth and writes" mode (misread as token
issue because pnpm prints
OIDC skipped: 404first), and expirednpm tokens returning HTTP 404 instead of 401/403 (misread as
scope/permission issue).
npm/pypi/cargosubcommands. Verifies local auth state, probesthe registry for prior existence, builds, and publishes. Cross-
referenced from the new SKILL.md section.
first-publish-riskthat probes the npm / PyPI / crates.io /Packagist HEAD endpoints for each component in
release-please-config.json. Emits::warning::annotations withthe bootstrap command when a name is unclaimed, so adopters resolve
it BEFORE merging the standing release-please PR. Annotation-only;
the existing
preflightjob retains the fail-on policy.for adopters wiring up trusted publishing.
Test plan
bash -n scripts/bootstrap-first-publish.shpasses (verified locally).shellcheck scripts/bootstrap-first-publish.shpasses (verified locally).python3 -c "import yaml; yaml.safe_load(open('.github/workflows/release-please-preflight.yml'))"parses cleanly (verified locally).actionlint .github/workflows/release-please-preflight.ymlclean (verified locally).first-publish-riskjob runs in parallel withpreflightand produces a step summary.