Skip to main content

/npm-publish-packages Command

System Prompt​

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

  1. IMMEDIATELY execute - no questions, no explanations first
  2. ALWAYS show full output from script/tool execution
  3. ALWAYS provide summary after execution completes

DO NOT:

  • Say "I don't need to take action" - you ALWAYS execute when invoked
  • Ask for confirmation unless requires_confirmation: true in frontmatter
  • Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

Purpose​

Publish CODITECT npm packages to the npm registry with comprehensive validation, authentication checks, and post-publish verification. Supports publishing binary packages and persona-specific packages with flexible targeting options.

Usage​

# Dry run - preview what would be published
/npm-publish-packages --dry-run

# Publish all packages to latest
/npm-publish-packages --all

# Publish with beta tag
/npm-publish-packages --all --tag beta

# Publish specific persona package
/npm-publish-packages --persona developer

# Publish specific platform binary
/npm-publish-packages --platform darwin-arm64

# Publish specific persona with tag
/npm-publish-packages --persona architect --tag next

# Publish multiple specific platforms
/npm-publish-packages --platform darwin-arm64,linux-x64 --tag latest

Action Policy​

Pre-Publish Validation (Step 1-6)​

Before publishing to npm:

  1. Verify npm authentication

    • Check ~/.npmrc for valid auth token
    • Verify user has publish permissions to @coditect scope
    • Confirm organization membership if required

  2. Version verification

    • Check package.json version is valid semver
    • Verify version doesn't already exist on npm registry
    • Confirm version matches git tag (if tagged)

  3. Package integrity checks

    • Validate package.json required fields (name, version, description, license)
    • Verify main/bin entry points exist
    • Check all dependencies are published and accessible

  4. Checksum verification

    • Verify SHA256 checksums for all binary artifacts
    • Validate checksums match manifest.json
    • Confirm no file corruption since build

  5. Platform binary checks (if publishing binaries)

    • Verify all platform binaries exist
    • Check file sizes are reasonable (>1MB, <100MB)
    • Validate executable permissions on Unix platforms

  6. Persona package checks (if publishing personas)

    • Verify persona configuration files exist
    • Check agent/command/skill references are valid
    • Validate activation status JSON integrity

Publish Workflow (Step 7-12)​

7. Package Preparation
   └─> Run npm pack (dry run)
   └─> Review package contents
   └─> Confirm no sensitive files included

8. Pre-Publish Hooks
   └─> Run prepublish scripts
   └─> Execute tests (if configured)
   └─> Build documentation

9. npm Publish
   └─> Binary Package: @coditect/cli
   └─> Persona Packages: @coditect/persona-{name}
   └─> Apply dist-tag (latest/beta/alpha/next)

10. Registry Verification
    └─> Confirm package appears in npm registry
    └─> Verify correct version published
    └─> Check dist-tags applied correctly

11. Installation Test
    └─> Test install in clean directory
    └─> Verify binary execution
    └─> Validate persona activation

12. Post-Publish Actions
    └─> Update GitHub Release notes
    └─> Notify team channels
    └─> Update documentation site

Agent Delegation​

This command delegates to:

binary-distribution-architect for:

  • Package manifest validation
  • Version compatibility checks
  • CDN sync coordination

npm-package-engineer for:

  • npm publishing workflow
  • Registry interaction
  • Package structure validation

Output​

Success Output​

╭─────────────────────────────────────────────╮
│        npm Publish Complete                 │
├─────────────────────────────────────────────┤
│ Packages Published:                         │
│   ✓ @coditect/cli@1.2.0                     │
│   ✓ @coditect/persona-developer@1.2.0       │
│   ✓ @coditect/persona-architect@1.2.0       │
│   ✓ @coditect/persona-qa-engineer@1.2.0     │
├─────────────────────────────────────────────┤
│ Dist Tag: latest                            │
│ Platform Binaries: 6/6                      │
├─────────────────────────────────────────────┤
│ npm URLs:                                   │
│   https://npmjs.com/package/@coditect/cli   │
├─────────────────────────────────────────────┤
│ Installation:                               │
│   npm install -g @coditect/cli              │
│   npm install -g @coditect/persona-developer│
├─────────────────────────────────────────────┤
│ Post-Publish Verification: PASSED           │
│   ✓ Registry check                          │
│   ✓ Installation test                       │
│   ✓ Binary execution                        │
╰─────────────────────────────────────────────╯

Dry Run Output​

╭─────────────────────────────────────────────╮
│     npm Publish Preview (DRY RUN)           │
├─────────────────────────────────────────────┤
│ Would publish:                              │
│   • @coditect/cli@1.2.0                     │
│   • @coditect/persona-developer@1.2.0       │
│   • @coditect/persona-architect@1.2.0       │
│   • @coditect/persona-qa-engineer@1.2.0     │
├─────────────────────────────────────────────┤
│ Dist Tag: latest                            │
├─────────────────────────────────────────────┤
│ Pre-Publish Checks:                         │
│   ✓ npm authentication valid                │
│   ✓ Version 1.2.0 available                 │
│   ✓ Package.json valid                      │
│   ✓ SHA256 checksums verified               │
│   ✓ Binary files present (6/6)              │
│   ✓ Persona configs valid (3/3)             │
├─────────────────────────────────────────────┤
│ No changes made (--dry-run enabled)         │
╰─────────────────────────────────────────────╯

Persona-Specific Output​

╭─────────────────────────────────────────────╮
│   Publish: @coditect/persona-developer      │
├─────────────────────────────────────────────┤
│ Version: 1.2.0                              │
│ Dist Tag: latest                            │
├─────────────────────────────────────────────┤
│ Included Components:                        │
│   • Agents: 12                              │
│   • Commands: 8                             │
│   • Skills: 15                              │
├─────────────────────────────────────────────┤
│ Status: ✓ Published successfully            │
│ URL: https://npmjs.com/package/...          │
╰─────────────────────────────────────────────╯

Error Handling​

Common Errors​

Not authenticated:

ERROR: npm authentication failed
FIX: Run 'npm login' or add auth token to ~/.npmrc
     Verify you have publish access to @coditect scope

Version already exists:

ERROR: @coditect/cli@1.2.0 already published
FIX: Bump version in package.json or use --tag for pre-release
     Cannot overwrite published versions (npm policy)

Checksum mismatch:

ERROR: SHA256 checksum mismatch for darwin-arm64 binary
FIX: Rebuild binary package or update checksums
     File may have been corrupted since build

Missing binary:

ERROR: Binary not found for platform linux-x64
FIX: Run /package-release first to build all platforms
     Or use --platform to exclude missing platforms

Registry timeout:

ERROR: npm registry request timed out
FIX: Check network connection and npm registry status
     Try again or use --tag to reduce load

Permission denied:

ERROR: Insufficient permissions to publish @coditect/cli
FIX: Contact org admin for publish permissions
     Verify you're a member of @coditect organization

Examples​

Standard Release (All Packages)​

User: /npm-publish-packages --all

Agent: Running pre-publish validation...
       ✓ npm authentication valid
       ✓ Version 1.2.0 available on registry
       ✓ SHA256 checksums verified for 6 binaries
       ✓ 3 persona packages validated

       Publishing packages...
       ✓ @coditect/cli@1.2.0 published
       ✓ @coditect/persona-developer@1.2.0 published
       ✓ @coditect/persona-architect@1.2.0 published
       ✓ @coditect/persona-qa-engineer@1.2.0 published

       Running post-publish verification...
       ✓ All packages accessible on registry
       ✓ Installation test passed
       ✓ Binary execution verified

       Success! 4 packages published to npm.

Beta Release​

User: /npm-publish-packages --all --tag beta

Agent: Publishing packages with 'beta' tag...

       This will publish:
       • @coditect/cli@1.3.0-beta.1 (tag: beta)
       • 3 persona packages (tag: beta)

       Users can install with:
       npm install -g @coditect/cli@beta

       Continue? [y/N]: y

       ✓ Published successfully with beta tag

Specific Persona (Developer Tools)​

User: /npm-publish-packages --persona developer

Agent: Publishing @coditect/persona-developer only...

       ✓ Package validated
       ✓ Published @coditect/persona-developer@1.2.0

       Install with:
       npm install -g @coditect/persona-developer

Dry Run Before Production Release​

User: /npm-publish-packages --all --dry-run

Agent: DRY RUN: Simulating publish workflow...

       Pre-publish checks:
       ✓ npm authentication valid
       ✓ All versions available (not published)
       ✓ SHA256 checksums verified
       ✓ All binaries present

       Would publish:
       • @coditect/cli@1.2.0 (latest)
       • @coditect/persona-developer@1.2.0 (latest)
       • @coditect/persona-architect@1.2.0 (latest)
       • @coditect/persona-qa-engineer@1.2.0 (latest)

       No changes made. Run without --dry-run to publish.

Platform-Specific Binary Update​

User: /npm-publish-packages --platform darwin-arm64

Agent: Publishing darwin-arm64 binary only...

       Note: This updates the binary within @coditect/cli package
       Version must be bumped first.

       ✓ Binary verified and published
       ✓ CDN manifest updated

Important Notes​

npm Registry Immutability​

  • Published versions cannot be unpublished after 24 hours
  • Always run --dry-run first for production releases
  • Use dist-tags (beta/alpha) for pre-release testing
  • Version numbers are permanent once published

Authentication Requirements​

# Login to npm (interactive)
npm login

# Or add auth token to ~/.npmrc
//registry.npmjs.org/:_authToken=YOUR_TOKEN

# Verify authentication
npm whoami
npm access ls-packages @coditect

Dist Tag Strategy​

  • latest - Stable production releases (default)
  • beta - Beta testing releases
  • alpha - Early alpha releases
  • next - Development/preview releases

Users install tagged versions:

npm install -g @coditect/cli@beta
npm install -g @coditect/cli@latest

Post-Publish Checklist​

After successful publish:

  1. Verify packages on npmjs.com
  2. Test installation in clean environment
  3. Update GitHub Release notes
  4. Notify team/community
  5. Update documentation website
  6. Monitor npm download stats
  7. Watch for user-reported issues

Package Size Considerations​

  • npm packages >10MB may have slower installs
  • Use .npmignore to exclude unnecessary files
  • Binary packages should be optimized
  • Consider CDN for large binaries, npm for metadata
  • /package-release - Build multi-platform binaries before publishing
  • /git-sync - Sync repository before release
  • /export-dedup - Create session checkpoint before publish

Security Considerations​

Before Publishing​

  1. Never include secrets in packages

    • No API keys, tokens, or credentials
    • Review .npmignore carefully
    • Check prepublish hook output

  2. Verify package contents

    npm pack --dry-run
    tar -tzf package.tgz  # Review contents

  3. Enable 2FA for npm account

    • Required for @coditect scope
    • Protects against unauthorized publishes

  4. Code signing

    • All binaries should be signed
    • Checksums in manifest.json
    • GPG signatures for verification

Troubleshooting​

Package Not Appearing After Publish​

Symptom: Package published but not visible on npm

Causes:

  • Registry propagation delay (wait 5-10 minutes)
  • Private package published to wrong registry
  • Network/CDN caching issues

Fix:

# Force registry cache clear
npm cache clean --force

# Check package directly
npm view @coditect/cli versions

# Verify registry URL
npm config get registry

Installation Fails After Publish​

Symptom: npm install -g @coditect/cli fails

Causes:

  • Binary missing for user's platform
  • Incorrect bin path in package.json
  • Permissions issues

Fix:

# Verify package structure
npm view @coditect/cli

# Check bin configuration
npm view @coditect/cli bin

# Test in clean environment
docker run -it node:18 npm install -g @coditect/cli

Version History​

  • 1.0.0 (2025-12-09) - Initial release with comprehensive npm publishing workflow

See Also​