Npm publish

npm-publish

Ship a package to the npm registry with full pre-flight checks, version management, and post-publish verification.

---

When to Trigger

Activate this skill when the user:

• Asks to publish an npm package or ship to npm
• Wants to release a new version or cut a release
• Says "bump version and publish" or "push to registry"
• Needs to prepare a package for distribution

---

Pre-Flight Checks

Run every check before attempting to publish. Fail fast on any blocker.

1. Validate package.json

Verify the following fields exist and are non-empty:

Field	Required	Notes
name	Yes	Must be scoped: @0xjitsu/<package>
version	Yes	Must follow semver
description	Yes	One-line summary for npm search
license	Yes	Should be AGPL-3.0-or-later unless overridden
files	Yes	Whitelist of published files (e.g., ["dist", "bin"])
bin	If CLI	Entry point for CLI packages
main/exports	Yes	Package entry point
repository	Recommended	Links npm page to GitHub
keywords	Recommended	Improves discoverability

If any required field is missing, report it and stop.

2. Verify .npmrc Scope

Check that .npmrc (project root or ~/.npmrc) contains:

@0xjitsu:registry=https://registry.npmjs.org/

If missing, offer to create it. Verify npm auth:

npm whoami

If not authenticated, instruct the user to run npm login.

3. Build

If package.json contains a build script:

npm run build

Fail the pipeline if the build exits non-zero. Verify the output directory (dist/, build/, etc.) exists and is non-empty.

4. Test

If package.json contains a test script (and it is not the default echo "Error: no test specified"):

npm test

Hard rule: Never publish if tests fail. No exceptions.

5. Dry-Run Pack

npm pack --dry-run 2>&1

Review the file list. Flag and halt if any of these appear:

• .env, .env.* (secrets)
• node_modules/ (bloat)
• .git/ (repository internals)
• *.pem, *.key (certificates/keys)
• credentials.json, serviceAccountKey.json (auth files)
• Any file larger than 1 MB (warn, don't halt)

Report the total packed size. Warn if over 5 MB.

---

Version Bump Workflow

Ask the User

Present the current version and ask:

Current version: X.Y.Z What type of release?

• patch (X.Y.Z+1) -- bug fixes, no new features
• minor (X.Y+1.0) -- new features, backward compatible
• major (X+1.0.0) -- breaking changes

Bump

npm version <patch|minor|major> --no-git-tag-version

Using --no-git-tag-version because we create the tag manually after publish succeeds.

Update CHANGELOG

Invoke the changelog-gen skill if available. If not available, prompt the user to write a changelog entry manually. The entry must exist before publishing.

Commit the Version Bump

git add package.json package-lock.json CHANGELOG.md
git commit -m "release: v<new-version>"

---

Publish

Execute

Ask for explicit confirmation before running:

npm publish --access public

• --access public is required for scoped packages to be publicly visible.
• Never use --force. If publish fails, diagnose and fix the root cause.
• If the version already exists on the registry, bump again -- do not force overwrite.

Create Git Tag

git tag v<version>

Push

git push origin <current-branch>
git push origin v<version>

Create GitHub Release

Write the changelog entry for this version to a temp file, then:

gh release create v<version> \
  --title "v<version>" \
  --notes-file /tmp/CHANGELOG_ENTRY.md

Clean up the temp file after.

---

Post-Publish Verification

Confirm on Registry

npm view @0xjitsu/<package>@latest version

Verify the returned version matches what was just published.

Test Install

TMPDIR=$(mktemp -d)
cd "$TMPDIR"
npm init -y --silent
npm install @0xjitsu/<package>@<version>

If the package has a bin entry:

npx @0xjitsu/<package> --help

Verify it runs without error. Clean up the temp directory.

Report

Print a summary:

Published: @0xjitsu/<package>@<version>
Registry:  https://www.npmjs.com/package/@0xjitsu/<package>
Git tag:   v<version>
Release:   https://github.com/0xjitsu/<repo>/releases/tag/v<version>

---

Safety Rules

Rule	Rationale
Never use npm publish --force	Can overwrite existing versions, breaking downstream consumers
Always dry-run first	Catches accidentally included secrets or bloat
Never publish if tests fail	Broken packages erode trust
Ask confirmation before npm publish	Publishing is irreversible (npm unpublish has a 72h window)
Never publish .env or credentials	Security violation -- halt immediately if detected in pack
Create tag only after successful publish	Prevents tags pointing to unpublished versions
Use --access public for scoped packages	Scoped packages default to restricted on npm

---

Rollback

If something goes wrong after publish:

1. npm unpublish @0xjitsu/<package>@<version> (only within 72 hours)
2. git tag -d v<version> and git push origin :refs/tags/v<version>
3. Delete the GitHub release: gh release delete v<version> --yes
4. Revert the version bump commit if needed