@vibe-db/cli 1.0.0

package/PUBLISHING.md

@@ -0,0 +1,558 @@
+# Publishing VibeDB CLI to npm
+
+**Status:** Ready to Publish  
+**Package Name:** `vibedb` (check availability on npm)  
+**Current Version:** 1.0.0  
+
+---
+
+## 📋 Pre-Publishing Checklist
+
+### 1. Test the CLI Locally
+
+```bash
+cd /vibedb/cli
+
+# Install dependencies
+npm install
+
+# Test all commands
+node bin/vibedb.js --help
+node bin/vibedb.js signup
+node bin/vibedb.js login
+node bin/vibedb.js list
+node bin/vibedb.js billing info
+```
+
+### 2. Update package.json
+
+Current package.json should have:
+
+```json
+{
+  "name": "vibedb",
+  "version": "1.0.0",
+  "description": "Instant database provisioning for AI-powered development",
+  "main": "src/api.js",
+  "bin": {
+    "vibedb": "./bin/vibedb.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "database",
+    "postgres",
+    "mysql",
+    "redis",
+    "ai",
+    "claude",
+    "gpt",
+    "development",
+    "devtools",
+    "provisioning"
+  ],
+  "author": "VibeDB",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/vibedb-cli.git"
+  },
+  "homepage": "https://vibedb.dev",
+  "bugs": {
+    "url": "https://github.com/yourusername/vibedb-cli/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.3",
+    "commander": "^11.1.0",
+    "inquirer": "^8.2.5"
+  }
+}
+```
+
+**Important fields to verify:**
+- ✅ `name`: Must be unique on npm
+- ✅ `version`: Start with 1.0.0
+- ✅ `bin`: Points to executable
+- ✅ `repository`: Your GitHub repo
+- ✅ `homepage`: Your website
+- ✅ `keywords`: For discoverability
+
+### 3. Create/Update README.md
+
+The CLI already has a README.md at `/vibedb/cli/README.md`. Make sure it includes:
+
+- [ ] Installation instructions
+- [ ] Quick start guide
+- [ ] Command reference
+- [ ] Authentication setup
+- [ ] Examples
+- [ ] Links to docs
+
+### 4. Add LICENSE File
+
+```bash
+cd /vibedb/cli
+cat > LICENSE << 'EOF'
+MIT License
+
+Copyright (c) 2026 VibeDB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+EOF
+```
+
+### 5. Create .npmignore
+
+```bash
+cd /vibedb/cli
+cat > .npmignore << 'EOF'
+# Development files
+node_modules/
+.git/
+.gitignore
+.DS_Store
+
+# Documentation
+*.md
+!README.md
+
+# Test files
+test/
+tests/
+*.test.js
+*.spec.js
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+.travis.yml
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+
+# Misc
+.env
+.env.*
+EOF
+```
+
+---
+
+## 🚀 Publishing Steps
+
+### Step 1: Create npm Account
+
+If you don't have one:
+
+1. Go to https://www.npmjs.com/signup
+2. Create account
+3. Verify email
+
+### Step 2: Login to npm CLI
+
+```bash
+npm login
+```
+
+Enter:
+- Username
+- Password
+- Email
+- OTP (if 2FA enabled)
+
+Verify login:
+```bash
+npm whoami
+```
+
+### Step 3: Check Package Name Availability
+
+```bash
+npm view vibedb
+```
+
+If it shows "npm ERR! 404" - the name is available!
+
+If it's taken, you'll need to choose a different name:
+- `@your-username/vibedb` (scoped package)
+- `vibedb-cli`
+- `vibedb-tool`
+- `vibe-db`
+
+Update package.json with the available name.
+
+### Step 4: Dry Run
+
+Test what will be published:
+
+```bash
+cd /vibedb/cli
+npm pack --dry-run
+```
+
+This shows what files will be included.
+
+### Step 5: Test Installation Locally
+
+```bash
+# Create a tarball
+npm pack
+
+# Install globally from tarball
+npm install -g vibedb-1.0.0.tgz
+
+# Test it works
+vibedb --help
+
+# Uninstall test version
+npm uninstall -g vibedb
+```
+
+### Step 6: Publish to npm
+
+```bash
+cd /vibedb/cli
+
+# First time publishing (public package)
+npm publish --access public
+
+# Or if using scoped package
+npm publish --access public
+```
+
+**You'll see output like:**
+```
++ vibedb@1.0.0
+```
+
+### Step 7: Verify Publication
+
+```bash
+# Check it's live
+npm view vibedb
+
+# Install from npm
+npm install -g vibedb
+
+# Test
+vibedb --help
+```
+
+---
+
+## 📦 Future Updates
+
+### Semantic Versioning
+
+Use semantic versioning (semver):
+- **Major** (1.0.0 → 2.0.0): Breaking changes
+- **Minor** (1.0.0 → 1.1.0): New features, backward compatible
+- **Patch** (1.0.0 → 1.0.1): Bug fixes
+
+### Publishing Updates
+
+```bash
+cd /vibedb/cli
+
+# 1. Make your changes
+# 2. Update version in package.json
+
+# Option A: Manual version bump
+# Edit package.json, change "version": "1.0.0" to "1.0.1"
+
+# Option B: Use npm version command
+npm version patch  # 1.0.0 → 1.0.1
+npm version minor  # 1.0.0 → 1.1.0
+npm version major  # 1.0.0 → 2.0.0
+
+# 3. Test locally
+npm install
+node bin/vibedb.js --help
+
+# 4. Publish
+npm publish
+
+# 5. Tag in git (if using version control)
+git add .
+git commit -m "Release v1.0.1"
+git tag v1.0.1
+git push && git push --tags
+```
+
+---
+
+## 🏷️ npm Tags
+
+### Publishing Beta/Alpha Versions
+
+```bash
+# For pre-release versions
+npm version prerelease --preid=beta
+# Creates: 1.0.1-beta.0
+
+npm publish --tag beta
+```
+
+Users can install with:
+```bash
+npm install -g vibedb@beta
+```
+
+### Setting Latest Tag
+
+```bash
+# Make a specific version the "latest"
+npm dist-tag add vibedb@1.0.0 latest
+```
+
+---
+
+## 📊 Package Analytics
+
+After publishing, you can track usage:
+
+1. **npm stats:** https://npmjs.com/package/vibedb
+   - Downloads per day/week/month
+   - Version distribution
+
+2. **npm trends:** https://npmtrends.com/vibedb
+   - Compare with other packages
+   - Historical download data
+
+---
+
+## 🔧 Troubleshooting
+
+### Error: Package name already taken
+
+**Solution:** Use a scoped package or different name
+
+```json
+{
+  "name": "@your-org/vibedb",
+  // or
+  "name": "vibedb-cli"
+}
+```
+
+### Error: 402 Payment Required
+
+**Solution:** You need to publish as public
+
+```bash
+npm publish --access public
+```
+
+### Error: You need to authorize this machine
+
+**Solution:** Login again with 2FA
+
+```bash
+npm login
+# Enter OTP from authenticator app
+```
+
+### Error: ENEEDAUTH
+
+**Solution:** Login expired
+
+```bash
+npm logout
+npm login
+```
+
+### Version already published
+
+**Solution:** Can't republish same version, bump it
+
+```bash
+npm version patch
+npm publish
+```
+
+---
+
+## ✅ Post-Publishing Checklist
+
+After publishing:
+
+- [ ] Test installation: `npm install -g vibedb`
+- [ ] Update website with install instructions
+- [ ] Update documentation
+- [ ] Announce on social media/blog
+- [ ] Add npm badge to README
+- [ ] Set up GitHub Actions for auto-publishing (optional)
+- [ ] Monitor for issues/feedback
+
+### Add npm Badge to README
+
+```markdown
+[![npm version](https://badge.fury.io/js/vibedb.svg)](https://www.npmjs.com/package/vibedb)
+[![npm downloads](https://img.shields.io/npm/dm/vibedb.svg)](https://www.npmjs.com/package/vibedb)
+```
+
+---
+
+## 🤖 Automated Publishing (Optional)
+
+### Set up GitHub Actions
+
+Create `.github/workflows/publish.yml`:
+
+```yaml
+name: Publish to npm
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org'
+      
+      - run: cd cli && npm install
+      
+      - run: cd cli && npm test
+        if: steps.test.outcome == 'success'
+      
+      - run: cd cli && npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+**Setup:**
+1. Get npm token: https://www.npmjs.com/settings/YOUR_USERNAME/tokens
+2. Add as GitHub secret: Settings → Secrets → NPM_TOKEN
+3. Create GitHub release → Auto publishes to npm
+
+---
+
+## 📝 Quick Reference
+
+### Essential Commands
+
+```bash
+# Login
+npm login
+
+# Check what's logged in
+npm whoami
+
+# Check package name availability
+npm view PACKAGE_NAME
+
+# Test publish (dry run)
+npm pack --dry-run
+
+# Publish
+npm publish --access public
+
+# Update version
+npm version patch|minor|major
+
+# Check published package
+npm view vibedb
+
+# Unpublish (within 72 hours)
+npm unpublish vibedb@1.0.0
+```
+
+### Useful Links
+
+- npm Dashboard: https://www.npmjs.com/~YOUR_USERNAME
+- Package Page: https://www.npmjs.com/package/vibedb
+- Downloads Stats: https://npm-stat.com/charts.html?package=vibedb
+- Search Rankings: https://www.npmjs.com/search?q=vibedb
+
+---
+
+## 🎯 Launch Checklist
+
+Before first publish:
+
+- [ ] Package name is available
+- [ ] README.md is complete and clear
+- [ ] LICENSE file exists
+- [ ] .npmignore excludes dev files
+- [ ] package.json has correct metadata
+- [ ] All commands tested locally
+- [ ] Version is 1.0.0
+- [ ] bin executable has shebang: `#!/usr/bin/env node`
+- [ ] bin file has execute permissions: `chmod +x bin/vibedb.js`
+
+After publish:
+
+- [ ] Package installs correctly: `npm install -g vibedb`
+- [ ] All commands work: `vibedb --help`
+- [ ] Documentation updated
+- [ ] Announcement prepared
+- [ ] Support channels ready (email, GitHub issues)
+
+---
+
+## 🚀 You're Ready!
+
+Once published, users can install with:
+
+```bash
+npm install -g vibedb
+```
+
+And use immediately:
+
+```bash
+vibedb signup
+vibedb login
+vibedb list
+vibedb billing info
+```
+
+**Next steps after publishing:**
+1. Update landing page with npm install command
+2. Add to website: https://vibedb.dev
+3. Submit to:
+   - Product Hunt
+   - Hacker News (Show HN)
+   - Reddit /r/SideProject
+   - Dev.to
+4. Monitor npm stats and GitHub issues
+5. Iterate based on feedback
+
+Good luck with the launch! 🎉