219 lines
4.0 KiB
Markdown
219 lines
4.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
npm login
|
|
# Enter credentials when prompted
|
|
```
|
|
|
|
### 2. Dry Run (Test Publish)
|
|
|
|
```bash
|
|
npm publish --dry-run
|
|
```
|
|
|
|
Review the output to ensure correct files are included.
|
|
|
|
### 3. Publish to npm
|
|
|
|
```bash
|
|
# Public package (free)
|
|
npm publish --access public
|
|
|
|
# Or for scoped package
|
|
npm publish
|
|
```
|
|
|
|
### 4. Verify Publication
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```yaml
|
|
# .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
|