@nikkory/vibe-engine 4.0.0

package/PUBLISH-GUIDE.md

@@ -0,0 +1,250 @@
+# 📦 NPM Publish Guide - @nikkory/vibe-engine v4.0.0
+
+## ✅ Pre-Publish Checklist
+
+- [x] **Build completed**: `pnpm build` ✅
+- [x] **Hybrid logic implemented**: MatrixResolver ✅
+- [x] **Tests passing**: All 12 plan tasks complete ✅
+- [x] **Package.json valid**: Fixed with `npm pkg fix` ✅
+- [x] **.npmignore created**: Excludes test files ✅
+- [x] **Dry-run tested**: Package size ~1.5MB ✅
+
+## 📋 Package Info
+
+```json
+{
+  "name": "@nikkory/vibe-engine",
+  "version": "4.0.0",
+  "description": "Zero-token UI/UX code generation with Matrix Algorithm",
+  "bin": {
+    "vibe": "./bin/vibe.js"
+  },
+  "access": "public"
+}
+```
+
+## 🚀 Publish Steps
+
+### Step 1: Login to npm
+
+```bash
+cd packages/engine
+npm login
+```
+
+**Enter your credentials:**
+- Username: `kemonra` (or your npm username)
+- Password: [your npm password]
+- Email: [your npm email]
+- One-time password (OTP): [from authenticator app if 2FA enabled]
+
+### Step 2: Verify Login
+
+```bash
+npm whoami
+# Should output: kemonra
+```
+
+### Step 3: Final Dry Run
+
+```bash
+npm publish --dry-run
+```
+
+**Verify:**
+- Package name: `@nikkory/vibe-engine@4.0.0`
+- Tarball size: ~1.5MB
+- Files included: dist/, bin/, README.md, package.json
+- Files excluded: src/, test files, coverage/, *.map
+
+### Step 4: Publish to npm
+
+```bash
+npm publish --access public
+```
+
+**Expected output:**
+```
++ @nikkory/vibe-engine@4.0.0
+```
+
+### Step 5: Verify Published Package
+
+```bash
+npm view @nikkory/vibe-engine
+npm view @nikkory/vibe-engine version
+```
+
+## 🧪 Test Installation (As End User)
+
+### Global Install
+
+```bash
+npm install -g @nikkory/vibe-engine
+```
+
+### Verify CLI
+
+```bash
+vibe --help
+vibe generate button material-design enterprise --factor-4=full
+```
+
+### Test Generation
+
+```bash
+# Create test directory
+mkdir ~/test-nikkory
+cd ~/test-nikkory
+
+# Generate enterprise button with override
+vibe generate button material-design enterprise --factor-4=full -o ./components
+
+# Verify generated files
+ls -la components/material-design/button/
+cat components/material-design/button/enterprise.tsx
+```
+
+**Expected output:**
+- ✅ Component file with `rounded-full` (override applied)
+- ✅ Types file with full TypeScript definitions
+- ✅ Test file with Vitest tests
+- ✅ All enterprise features (memo, forwardRef, analytics)
+
+## 📊 What Users Will Get
+
+### CLI Commands
+
+```bash
+# Generate single component
+vibe generate <component> <design-system> <tier> [options]
+
+# With factor overrides
+vibe generate button material-design enterprise --factor-4=full --factor-5=xl
+
+# Batch generation
+vibe batch -o ./output --ds material-design -t enterprise
+```
+
+### Generated Files Per Component
+
+1. **Component file** (`.tsx`):
+   - Enterprise tier: 150-300 LOC
+   - React.memo, forwardRef, useCallback
+   - Analytics tracking
+   - Full ARIA support
+
+2. **Types file** (`.types.ts`):
+   - Complete TypeScript definitions
+   - Variant and size types
+   - Event handler types
+
+3. **Test file** (`.test.tsx`):
+   - Vitest test suite
+   - Component rendering tests
+   - Props validation tests
+
+### Supported Features
+
+- **12 Design Systems**: Material, iOS, Glassmorphism, Neumorphism, Brutalism, Minimalism, etc.
+- **3 Quality Tiers**: Basic (30-50 LOC), Standard (50-150 LOC), Enterprise (150-300 LOC)
+- **40+ Component Types**: Button, Card, Input, Modal, Table, etc.
+- **24 Factors**: Color, Size, Variant, Shape, Shadow, Animation, etc.
+- **Hybrid Override System**: User values → ClassMapper, Defaults → Registry
+
+## 🔍 Package Stats
+
+**After .npmignore:**
+- **Total files**: ~150 files
+- **Size**: ~1.5MB (unpacked: ~4MB)
+- **Main exports**:
+  - `dist/index.js` (CJS): 577KB
+  - `dist/index.mjs` (ESM): 569KB
+  - `dist/browser.js`: 372KB (browser bundle)
+- **TypeScript definitions**: Full `.d.ts` files included
+
+## 📝 Post-Publish
+
+### Update README
+
+Add installation badge:
+
+```markdown
+[![npm version](https://img.shields.io/npm/v/@nikkory/vibe-engine.svg)](https://www.npmjs.com/package/@nikkory/vibe-engine)
+[![npm downloads](https://img.shields.io/npm/dm/@nikkory/vibe-engine.svg)](https://www.npmjs.com/package/@nikkory/vibe-engine)
+```
+
+### Create Release Notes
+
+GitHub release with:
+- Version: v4.0.0
+- Title: "Matrix Algorithm v4 - Hybrid Override System"
+- Changelog:
+  - ✅ Hybrid logic: ClassMapper + design-systems-registry
+  - ✅ CLI with factor overrides support
+  - ✅ 12 design systems × 3 tiers × 40+ components
+  - ✅ Enterprise-grade code generation
+
+### Social Media
+
+Twitter/LinkedIn post:
+```
+🚀 Just published @nikkory/vibe-engine v4.0.0!
+
+Zero-token UI component generation with Matrix Algorithm (M1×M2×M3×M4)
+
+✨ Features:
+- 12 design systems (Material, iOS, Glassmorphism, etc.)
+- 3 quality tiers (Basic → Enterprise)
+- 40+ component types
+- CLI with factor overrides
+- Enterprise-grade code
+
+npm i -g @nikkory/vibe-engine
+vibe generate button material-design enterprise
+
+Powered by Nikkory
+https://nikkory.com
+```
+
+## 🛟 Troubleshooting
+
+### Error: 401 Unauthorized
+
+```bash
+npm logout
+npm login
+npm publish --access public
+```
+
+### Error: Package already exists
+
+Version 4.0.0 already published? Update version:
+
+```bash
+npm version patch  # 4.0.1
+# or
+npm version minor  # 4.1.0
+```
+
+### Error: Missing bin file
+
+```bash
+chmod +x bin/vibe.js
+```
+
+## ✅ Success Criteria
+
+After publish, verify:
+
+- [ ] Package visible on npmjs.com: https://www.npmjs.com/package/@nikkory/vibe-engine
+- [ ] CLI installs globally: `npm i -g @nikkory/vibe-engine`
+- [ ] CLI works: `vibe --help`
+- [ ] Component generation works: `vibe generate button material-design enterprise`
+- [ ] Override works: `--factor-4=full` produces `rounded-full`
+- [ ] All files included: component + types + tests
+
+---
+
+**Powered by Nikkory**
+https://nikkory.com