---
name: 0xjitsu/npm-publish
source: https://app.decimal.ai/s/0xjitsu-npm-publish@1/SKILL.md
source_sha256: 3f5da6298073
---

# 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