# NPM Publishing Guide - Hyly E2E Plugin

Complete guide to publish the Hyly E2E Plugin to NPM registry.

## Prerequisites

### 1. NPM Account
- Create account at https://www.npmjs.com/signup
- Verify your email address
- Enable 2FA (recommended for security)

### 2. NPM CLI
```bash
# Check if npm is installed
npm --version

# Should show version 8.0.0 or higher
```

### 3. Login to NPM
```bash
# Login to your NPM account
npm login

# Follow prompts:
# - Username: your_npm_username
# - Password: your_npm_password
# - Email: your_email@example.com
# - OTP: (if 2FA enabled)

# Verify login
npm whoami
# Should show your username
```

## Pre-Publishing Checklist

### ✅ Step 1: Check Package Name Availability

```bash
# Check if name is available
npm view hyly-e2e-plugin

# If package doesn't exist (404 error), name is available ✅
# If package exists, you need to:
#   - Choose different name, OR
#   - Use scoped package: @hyly/e2e-plugin
```

**Option A: Use Different Name**
If `hyly-e2e-plugin` is taken, try:
- `@hyly/e2e-plugin` (scoped to your organization)
- `hyly-e2e-test-automation`
- `hyly-playwright-pipeline`

**Option B: Use Scoped Package (Recommended)**
Update `package.json`:
```json
{
  "name": "@hyly/e2e-plugin",
  ...
}
```

### ✅ Step 2: Verify package.json

Ensure these fields are correct:
- `name` - Unique package name
- `version` - Semantic version (1.0.0)
- `description` - Clear description
- `keywords` - Search terms
- `author` - Your name/organization
- `license` - MIT
- `repository` - GitHub URL
- `homepage` - Documentation URL

### ✅ Step 3: Test Package Locally

```bash
# Navigate to plugin directory
cd hyly-e2e-plugin

# Create tarball to see what will be published
npm pack

# This creates: hyly-e2e-plugin-1.0.0.tgz
# Extract and inspect:
tar -xzf hyly-e2e-plugin-1.0.0.tgz
ls package/

# Verify all necessary files are included
# Clean up
rm -rf package hyly-e2e-plugin-1.0.0.tgz
```

### ✅ Step 4: Install Dependencies

```bash
# Install production dependencies
npm install --production

# Or if you want all dependencies
npm install
```

### ✅ Step 5: Run Verification

```bash
# Run the index.js to verify
node index.js

# Should display installation message and verify files
```

## Publishing Steps

### Option A: Public Package (Free)

```bash
# Navigate to plugin directory
cd hyly-e2e-plugin

# Publish to NPM
npm publish

# You'll see:
# + hyly-e2e-plugin@1.0.0
```

### Option B: Scoped Package (Organization)

**For Public Scoped Package (Free):**
```bash
# Update package.json name to @hyly/e2e-plugin

# Publish with public access
npm publish --access public
```

**For Private Scoped Package (Requires paid NPM plan):**
```bash
# Publish as private
npm publish --access restricted
```

### Option C: Dry Run (Test Without Publishing)

```bash
# Test the publishing process without actually publishing
npm publish --dry-run

# This shows what would be published without doing it
```

## Post-Publishing Steps

### 1. Verify Publication

```bash
# Check package on NPM
npm view hyly-e2e-plugin

# Should show your package information
```

### 2. Test Installation

```bash
# In a different directory, test installation
cd /tmp/test
npm install hyly-e2e-plugin

# Or with scoped package
npm install @hyly/e2e-plugin

# Verify it works
node
> const plugin = require('hyly-e2e-plugin')
> plugin.verify()
```

### 3. Update README Badges

Add NPM badges to your README.md:

```markdown
[![npm version](https://badge.fury.io/js/hyly-e2e-plugin.svg)](https://www.npmjs.com/package/hyly-e2e-plugin)
[![npm downloads](https://img.shields.io/npm/dm/hyly-e2e-plugin.svg)](https://www.npmjs.com/package/hyly-e2e-plugin)
[![license](https://img.shields.io/npm/l/hyly-e2e-plugin.svg)](https://github.com/hyly-ai/hyly-e2e-plugin/blob/main/LICENSE)
```

### 4. Tag Git Release

```bash
# Tag the release
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# Or create release on GitHub
# Go to: https://github.com/hyly-ai/hyly-e2e-plugin/releases/new
```

## Usage After Publishing

Once published, users can install:

### Global Installation
```bash
# Install globally
npm install -g hyly-e2e-plugin

# Then use in Claude Code
/plugin install hyly-e2e-plugin
```

### Local Installation
```bash
# In their project
npm install hyly-e2e-plugin

# Use in Claude Code
/plugin install ./node_modules/hyly-e2e-plugin
```

### Direct from NPM
```bash
# Claude Code can install directly
/plugin install npm:hyly-e2e-plugin
```

## Updating the Package

### Publishing New Version

```bash
# 1. Update code/documentation

# 2. Update version (choose one):
npm version patch  # 1.0.0 -> 1.0.1 (bug fixes)
npm version minor  # 1.0.0 -> 1.1.0 (new features)
npm version major  # 1.0.0 -> 2.0.0 (breaking changes)

# 3. This automatically:
#    - Updates package.json version
#    - Creates git commit
#    - Creates git tag

# 4. Push to GitHub
git push origin main --tags

# 5. Publish to NPM
npm publish

# 6. Users can update:
npm update hyly-e2e-plugin
```

## Deprecating a Version

If you need to deprecate an old version:

```bash
# Deprecate specific version
npm deprecate hyly-e2e-plugin@1.0.0 "Please upgrade to 1.1.0"

# Deprecate all versions (careful!)
npm deprecate hyly-e2e-plugin "Package moved to @hyly/e2e-plugin"
```

## Unpublishing (Use with Caution)

⚠️ **Warning**: Unpublishing is discouraged and has restrictions.

```bash
# Unpublish within 72 hours of publish
npm unpublish hyly-e2e-plugin@1.0.0

# Unpublish entire package (only within 72 hours)
npm unpublish hyly-e2e-plugin --force
```

**NPM Unpublish Policy:**
- Can only unpublish within 72 hours
- Cannot unpublish if other packages depend on it
- Cannot reuse package name for 24 hours after unpublish

## Organization Setup (For @hyly scope)

### Create NPM Organization

1. **Create Organization:**
   - Go to https://www.npmjs.com/org/create
   - Enter organization name: `hyly`
   - Choose plan (free for public packages)

2. **Add Team Members:**
   - Go to https://www.npmjs.com/settings/hyly/teams
   - Invite team members
   - Set permissions

3. **Publish Scoped Packages:**
   ```bash
   # Update package.json
   {
     "name": "@hyly/e2e-plugin"
   }

   # Publish
   npm publish --access public
   ```

## Best Practices

### Semantic Versioning

Follow semver (https://semver.org/):
- **Major** (X.0.0): Breaking changes
- **Minor** (1.X.0): New features, backwards compatible
- **Patch** (1.0.X): Bug fixes, backwards compatible

### Version History

Maintain `CHANGELOG.md`:
```markdown
# Changelog

## [1.1.0] - 2025-01-10
### Added
- New feature X

### Fixed
- Bug fix Y

## [1.0.0] - 2025-01-03
- Initial release
```

### Pre-Release Versions

For beta/alpha releases:
```bash
# Beta release
npm version 1.1.0-beta.0
npm publish --tag beta

# Users install with:
npm install hyly-e2e-plugin@beta

# Alpha release
npm version 1.1.0-alpha.0
npm publish --tag alpha
```

### Security

1. **Enable 2FA:**
   ```bash
   npm profile enable-2fa auth-and-writes
   ```

2. **Use `.npmignore`:**
   - Exclude sensitive files
   - Exclude development files
   - Keep package small

3. **Check Package Contents:**
   ```bash
   npm pack --dry-run
   ```

## Monitoring

### NPM Stats

View package statistics:
- https://www.npmjs.com/package/hyly-e2e-plugin
- Downloads, dependents, versions

### NPM Email Notifications

Enable email notifications:
- Package updates
- Security vulnerabilities
- Download milestones

## Troubleshooting

### Error: Package Already Exists

**Solution 1:** Use scoped package
```bash
# Change to @hyly/e2e-plugin
npm publish --access public
```

**Solution 2:** Choose different name
```json
{
  "name": "hyly-playwright-e2e-automation"
}
```

### Error: Must be Logged In

```bash
# Login again
npm logout
npm login
```

### Error: 403 Forbidden

Check:
- Package name is available
- You have publish permissions
- 2FA code is correct (if enabled)

### Error: File Size Too Large

```bash
# Check package size
npm pack
ls -lh *.tgz

# If > 10MB, optimize:
# - Remove large files
# - Add to .npmignore
# - Split into multiple packages
```

## Complete Publishing Script

Create `scripts/publish.sh`:

```bash
#!/bin/bash

# Hyly E2E Plugin - Publishing Script

set -e  # Exit on error

echo "🚀 Publishing Hyly E2E Plugin to NPM"

# 1. Verify we're on main branch
current_branch=$(git branch --show-current)
if [ "$current_branch" != "main" ]; then
    echo "❌ Must be on main branch to publish"
    exit 1
fi

# 2. Verify no uncommitted changes
if ! git diff-index --quiet HEAD --; then
    echo "❌ You have uncommitted changes"
    exit 1
fi

# 3. Run tests (if you have them)
# npm test

# 4. Verify package
echo "📦 Verifying package..."
node index.js

# 5. Check what will be published
echo "📋 Checking package contents..."
npm pack --dry-run

# 6. Ask for confirmation
read -p "Ready to publish? (y/n) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
    echo "❌ Publishing cancelled"
    exit 1
fi

# 7. Publish
echo "📤 Publishing to NPM..."
npm publish

# 8. Get version
version=$(node -p "require('./package.json').version")

# 9. Tag and push
echo "🏷️  Tagging release..."
git tag -a "v$version" -m "Release version $version"
git push origin "v$version"

echo "✅ Successfully published version $version!"
echo "📦 https://www.npmjs.com/package/hyly-e2e-plugin"
```

Make it executable:
```bash
chmod +x scripts/publish.sh
```

## Summary: Quick Publishing Checklist

- [ ] NPM account created
- [ ] Logged in via `npm login`
- [ ] Package name available
- [ ] `package.json` updated
- [ ] `index.js` entry point created
- [ ] `.npmignore` configured
- [ ] Tested locally with `npm pack`
- [ ] Dependencies installed
- [ ] Ready to publish:

```bash
cd hyly-e2e-plugin
npm publish
```

**After publishing:**
- [ ] Verify on npmjs.com
- [ ] Test installation
- [ ] Tag git release
- [ ] Update documentation
- [ ] Announce release

---

**Questions?**
- NPM Docs: https://docs.npmjs.com/
- NPM Support: https://www.npmjs.com/support
- GitHub: https://github.com/hyly-ai/hyly-e2e-plugin/issues

**Ready to publish?** Run: `npm publish`