devclaw-gitea/PUBLISHING.md

Publishing DevClaw to npm

Package Details

• Name: @laurentenhoor/devclaw
• npm Profile: https://www.npmjs.com/settings/laurentenhoor/packages
• Package URL: https://www.npmjs.com/package/@laurentenhoor/devclaw

Prerequisites

1. NPM Access Token is configured as NPM_ACCESS_TOKEN secret in GitHub repository settings
2. npm account: laurentenhoor
3. Node.js 20+ installed locally for testing

Publishing Methods

Method 1: Automated (Recommended)

Publishing happens automatically via GitHub Actions when a release is created:

1. Create a new release on GitHub:

   # Tag format: v{version} (e.g., v0.1.0)
   git tag v0.1.0
   git push origin v0.1.0
   

2. Create GitHub Release:

   • Go to: https://github.com/laurentenhoor/devclaw/releases/new
   • Choose the tag you just pushed
   • Write release notes
   • Click "Publish release"

3. Monitor the workflow:

   • GitHub Actions will automatically build and publish to npm
   • Check: https://github.com/laurentenhoor/devclaw/actions

Method 2: Manual Workflow Trigger

Trigger the workflow manually from GitHub Actions:

1. Go to: https://github.com/laurentenhoor/devclaw/actions/workflows/npm-publish.yml
2. Click "Run workflow"
3. Enter the tag name (e.g., v0.1.0)
4. Click "Run workflow"

Method 3: Local Publishing (Not Recommended)

For testing or emergencies only:

1. Login to npm:

   npm login
   # Username: laurentenhoor
   # Password: <your-password>
   # Email: <your-email>
   

2. Test the package:

   npm install
   npm run build
   npm pack --dry-run
   

3. Publish:

   npm publish --provenance --access public
   

Testing Before Publishing

Dry Run Test

# Install dependencies
npm install

# Build the package
npm run build

# Check what will be included
npm pack --dry-run

# This will show:
# - Package size
# - Files that will be included
# - Tarball contents

Verify Package Contents

# Create a tarball locally
npm pack

# Extract and inspect
tar -xzf laurentenhoor-devclaw-0.1.0.tgz
ls -la package/

Expected Package Contents

The published package should include:

• dist/ - Compiled JavaScript files
• roles/ - Default role templates
• docs/ - Documentation files
• package.json - Package metadata
• README.md - Package documentation
• .npmignore - Publish exclusions

The package should NOT include:

• *.ts source files (except .d.ts)
• node_modules/
• .git/
• tsconfig.json
• Development files

Version Management

Bumping Version

Before creating a release, update the version in package.json:

# Patch release (0.1.0 -> 0.1.1)
npm version patch

# Minor release (0.1.0 -> 0.2.0)
npm version minor

# Major release (0.1.0 -> 1.0.0)
npm version major

This automatically:

• Updates package.json
• Creates a git commit
• Creates a git tag

Then push:

git push && git push --tags

Verifying Publication

After publishing, verify:

1. Package appears on npm:

   • https://www.npmjs.com/package/@laurentenhoor/devclaw

2. Test installation:

   # In a temporary directory
   mkdir test-install && cd test-install
   npm install @laurentenhoor/devclaw
   

3. Check package contents:

   ls -la node_modules/@laurentenhoor/devclaw/
   

Troubleshooting

Build Fails

# Clean and rebuild
rm -rf dist/ node_modules/
npm install
npm run build

Publish Fails - Already Published

If the version already exists on npm, you need to bump the version:

npm version patch  # or minor/major
git push && git push --tags

Publish Fails - Authentication

Check that NPM_ACCESS_TOKEN secret is correctly set in GitHub:

• Go to: https://github.com/laurentenhoor/devclaw/settings/secrets/actions
• Verify NPM_ACCESS_TOKEN exists and is valid

Generate a new token if needed:

• https://www.npmjs.com/settings/laurentenhoor/tokens
• Token type: "Automation" (for CI/CD)
• Copy token and update GitHub secret

Provenance Fails

If --provenance fails:

• Ensure id-token: write permission is set in workflow
• Check that GitHub Actions is enabled
• Verify repository settings allow provenance

Post-Publishing Checklist

• Verify package appears on npm
• Test installation in a fresh project
• Update CHANGELOG.md with release notes
• Announce release in project channels
• Close related issues/PRs
• Update documentation if needed

Support

For issues with publishing:

• Check GitHub Actions logs
• Review npm publish documentation
• Contact package maintainer: laurentenhoor