tasq/node_modules/agentic-flow/docs/guides/NPM-PUBLISH.md

Publishing agent-flow to npm

Prerequisites

1. npm account with publish permissions
2. Verify package.json correctness
3. Complete build and testing
4. Update version number

Pre-Publish Checklist

# 1. Clean and rebuild
npm run build

# 2. Test locally
node dist/cli.js --help
node dist/cli.js --list

# 3. Test in Docker
docker build -t agent-flow:test .
docker run --rm -e ANTHROPIC_API_KEY=test agent-flow:test --help

# 4. Check package contents
npm pack --dry-run

# 5. Verify .npmignore excludes dev files
cat .npmignore

Version Update

# Update version (choose one)
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

# Or manually edit package.json version field

Publishing Steps

1. Login to npm

npm login
# Enter credentials when prompted

2. Dry Run (Test Publish)

npm publish --dry-run

Review the output to ensure correct files are included.

3. Publish to npm

# Public package (free)
npm publish --access public

# Or for scoped package
npm publish

4. Verify Publication

# Check on npmjs.com
open https://www.npmjs.com/package/agent-flow

# Test installation
npx agent-flow@latest --help

Post-Publish

1. Tag Release in Git

git tag v1.0.0
git push origin v1.0.0

2. Create GitHub Release

1. Go to https://github.com/ruvnet/agent-flow/releases
2. Click "Draft a new release"
3. Select tag v1.0.0
4. Title: "Agent Flow v1.0.0"
5. Describe changes from CHANGELOG.md
6. Attach binaries if applicable
7. Publish release

3. Update Documentation

• Update README with npm install instructions
• Update version badges
• Announce on social media

Unpublishing (Emergency Only)

# Unpublish within 72 hours
npm unpublish agent-flow@1.0.0

# Deprecate instead (preferred)
npm deprecate agent-flow@1.0.0 "Critical bug - use 1.0.1 instead"

Troubleshooting

Error: Package name already exists

# Check if name is taken
npm search agent-flow

# Use scoped package instead
# Update package.json: "name": "@your-org/agent-flow"

Error: 402 Payment Required

• Scoped packages require paid npm account or public access flag
• Use: npm publish --access public

Error: 403 Forbidden

• Not logged in: npm login
• No permissions: Contact package owner
• Email not verified: Check npm email

Beta/Alpha Releases

# Publish pre-release versions
npm version 1.1.0-alpha.1
npm publish --tag alpha

# Users install with:
npm install agent-flow@alpha

Package Maintenance

# View published versions
npm view agent-flow versions

# Add collaborators
npm owner add <username> agent-flow

# Check package health
npm doctor

# View download stats
npm info agent-flow

Files Included in Package

Based on .npmignore and package.json "files" field:

Included:

• dist/ - Compiled JavaScript
• docs/ - Documentation
• .claude/ - Agent definitions
• README.md - Package description
• LICENSE - MIT license
• package.json - Package manifest

Excluded:

• src/ - TypeScript source (after build)
• node_modules/ - Dependencies
• .env* - Environment files
• test-*.js - Test files
• validation/ - Validation scripts
• Docker files
• IDE config files

Continuous Deployment

For automated publishing via GitHub Actions:

# .github/workflows/publish.yml
name: Publish to npm

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm test
      - run: npm run build
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Support

• npm documentation: https://docs.npmjs.com/
• npm support: https://www.npmjs.com/support
• Package issues: https://github.com/ruvnet/agent-flow/issues