# NPM Package Deployment Checklist

**Version:** 1.0.0  
**Pre-Publish Validation**

---

## ✅ AUTOMATED PRE-FLIGHT

Run these commands before `npm publish`:

```bash
cd "D:/KERNL/kernl-mcp"

# 1. Clean build
npm run clean
npm run build

# 2. Run tests
npm test

# 3. Validate package
npm run validate

# 4. Check TypeScript
npx tsc --noEmit

# 5. Preview what WILL be published
npm pack --dry-run

# 6. Check package size
npm pack
ls -lh kernl-mcp-1.0.0.tgz
```

**Expected package size:** ~2-3MB (NOT 300MB!)

---

## 📦 WHAT GETS PUBLISHED

### ✅ Included Files
```
kernl-mcp/
├── dist/                   # Compiled JavaScript
├── docs/                   # User documentation
│   ├── CONFIG_TEMPLATE.md
│   ├── CONVERSATION_EXPORT.md
│   ├── INSTALLATION.md
│   ├── INTEGRATION.md
│   ├── PACKAGE_DISTRIBUTION.md
│   ├── QUICK_START.md
│   ├── TOOL_REFERENCE.md
│   └── VIDEO_TUTORIALS.md
├── scripts/                # Installation helpers
│   ├── install.ts
│   ├── validate.ts
│   ├── fix-schema.cjs
│   ├── generate-icons.js
│   └── generate-branded.js
├── assets/                 # Branding (icons, logos)
├── README.md               # Main documentation
├── LICENSE                 # MIT license
└── package.json            # Package manifest
```

### ❌ Excluded Files (Development Only)
```
# Source TypeScript (already compiled to dist/)
src/
tests/

# Development docs
BACKLOG_OVERVIEW.md
CONTINUATION_PROMPT_NEXT_SESSION.md
SESSION_SUMMARY.md
INSTALLATION.md (root - duplicate)
manifest.json

# Packaging scripts
create-mcpb*.ps1
create-mcpb.bat
package-mcpb.js

# Runtime data
data/
*.db
models/
*.mcpb

# Build config
tsconfig.json
vitest.config.ts
node_modules/
package-lock.json
```

---

## 🔒 SECURITY CHECK

### Sensitive Data Verification
```bash
# Check for API keys, tokens, secrets
grep -r "api_key\|secret\|password\|token" dist/ docs/ README.md

# Check for hardcoded paths
grep -r "D:\\\\" dist/ docs/ README.md
grep -r "/Users/" dist/ docs/ README.md

# Check for development URLs
grep -r "localhost\|127.0.0.1" dist/ docs/ README.md
```

**Expected:** No matches (all good)

---

## 📝 PACKAGE.JSON VALIDATION

### Required Fields
- [x] `name`: "kernl-mcp"
- [x] `version`: "1.0.0"
- [x] `description`: Present
- [x] `main`: "dist/index.js"
- [x] `license`: "MIT"
- [ ] `author`: **UPDATE EMAIL** (currently placeholder)
- [ ] `repository`: **UPDATE GITHUB URL** (currently placeholder)
- [x] `keywords`: 9 relevant keywords
- [x] `engines`: Node.js >=18.0.0

### Update Before Publishing
```bash
# Update author email
# Update repository URL
# Update bugs URL
# Update homepage URL
```

---

## 🧪 TEST INSTALLATION

### Local Test
```bash
# Create test package
npm pack

# Test install in separate directory
mkdir test-install
cd test-install
npm install ../kernl-mcp-1.0.0.tgz

# Verify files
ls -la node_modules/kernl-mcp/

# Run validation
cd node_modules/kernl-mcp
node scripts/validate.js
```

### Expected Results
- ✅ Package installs successfully
- ✅ All docs present
- ✅ Scripts executable
- ✅ No error messages

---

## 🚀 PUBLISHING STEPS

### First-Time Setup
```bash
# Login to NPM
npm login

# Verify logged in
npm whoami
```

### Publish
```bash
# Dry run (test without publishing)
npm publish --dry-run

# Publish to NPM
npm publish

# Add tags if needed
npm dist-tag add kernl-mcp@1.0.0 latest
```

### Post-Publish Verification
```bash
# View on NPM
npm view kernl-mcp

# Test global install
npm install -g kernl-mcp
```

---

## 📊 QUALITY METRICS

### File Count Validation
```bash
# Count files that will be published
npm pack --dry-run | grep "npm notice" | wc -l
```

**Expected:** 40-60 files

### Size Validation
```bash
npm pack
ls -lh kernl-mcp-1.0.0.tgz
```

**Expected:** 2-3 MB

### Dependency Audit
```bash
npm audit
npm audit fix
```

**Expected:** 0 vulnerabilities

---

## 🐛 COMMON ISSUES

### Issue: Package too large
**Cause:** `.npmignore` not working
**Fix:** Check `.npmignore` patterns, verify with `npm pack --dry-run`

### Issue: Missing files
**Cause:** Overly aggressive `.npmignore`
**Fix:** Use `!pattern` to include specific files

### Issue: Installation fails
**Cause:** Missing dependencies or build step
**Fix:** Add `prepare` script: `"prepare": "npm run build"`

---

## ✅ FINAL CHECKLIST

Before running `npm publish`:

- [ ] All tests pass (`npm test`)
- [ ] Build succeeds (`npm run build`)
- [ ] Zero TypeScript errors (`npx tsc --noEmit`)
- [ ] Package size reasonable (`npm pack`)
- [ ] No sensitive data (`grep` checks)
- [ ] package.json updated (author, repo URLs)
- [ ] LICENSE file present
- [ ] README.md complete
- [ ] CHANGELOG.md updated
- [ ] Git committed and tagged
- [ ] Local install test passed

---

**When all checks pass:** `npm publish` 🚀