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:

bash
npm whoami

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

3. Build

If package.json contains a build script:

bash
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"):

bash
npm test

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

5. Dry-Run Pack

bash
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

bash
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

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

Publish

Execute

Ask for explicit confirmation before running:

bash
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

bash
git tag v<version>

Push

bash
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:

bash
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

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

Verify the returned version matches what was just published.

Test Install

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

If the package has a bin entry:

bash
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