Skip to content

publishing.md

Latest commit

 

History

History
159 lines (110 loc) · 2.97 KB

publishing.md

File metadata and controls

159 lines (110 loc) · 2.97 KB

Publishing

npm publishing process for IntellyWeave CLI.

Prerequisites

Before publishing:

  • npm account with 2FA enabled
  • Publish access to intellyweave-cli package
  • Authenticator app for OTP codes
  • Clean working directory

Version Numbering

We follow Semantic Versioning:

Type When to Use Example
Patch Bug fixes, no breaking changes 2.5.1 → 2.5.2
Minor New features, backward compatible 1.0.0 → 2.6.0
Major Breaking changes 2.x.x → 3.0.0

Publishing Process

1. Ensure Clean Working Directory

git status  # Should show no uncommitted changes

2. Choose Version Bump

# For bug fixes (2.5.1 → 2.5.2)
npm run publish:patch

# For new features (1.0.0 → 2.6.0)
npm run publish:minor

# For breaking changes (2.x.x → 3.0.0)
npm run publish:major

3. What the Script Does

The publish script automatically:

  1. Runs linter and type checks (npm run check)
  2. Builds the project (npm run build)
  3. Sets executable permissions on dist/cli.js
  4. Bumps version in package.json
  5. Creates a git tag
  6. Builds the package
  7. Prompts for OTP

4. Enter OTP When Prompted

npm error This operation requires a one-time password from your authenticator.

Get your 6-digit code and run:

npm publish --otp=123456

5. Push to GitHub

Push commits and tags:

git push && git push --tags

Verification

After publishing, verify:

# Check npm registry
npm view intellyweave-cli

# Test installation
npx intellyweave-cli@latest --version

# Test in clean directory
cd /tmp
npx intellyweave-cli --help

prepublishOnly Hook

The prepublishOnly script in package.json runs automatically before publish:

{
  "prepublishOnly": "npm run check && npm run build && chmod +x dist/cli.js"
}

This ensures:

  • Code passes linting and type checks
  • Project is built
  • CLI is executable

Troubleshooting

"Missing OTP"

Enter OTP when prompted:

npm publish --otp=YOUR_6_DIGIT_CODE

"npm ERR! 403"

Check:

  • You have publish access to the intellyweave-cli package
  • 2FA is properly set up
  • You're logged in: npm whoami

Build Fails Before Publish

Fix the issue first:

npm run check   # Fix linting/type errors
npm run build   # Verify build works

Wrong Version Published

  1. Unpublish within 72 hours (if possible):

    npm unpublish intellyweave-cli@X.Y.Z

  2. Or publish a new patch version with fix

Release Checklist

  • All tests pass: npm run test
  • Linting passes: npm run check
  • Build succeeds: npm run build
  • Working directory is clean
  • Version number is correct
  • CHANGELOG updated (if applicable)
  • Documentation updated for new features
  • Git tag pushed
  • npm package verified

See Also