@emiliovt3/vibe-stack 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# @emiliovt3/vibe-stack
+
+Cross-platform npx CLI that installs and configures a curated vibe-coding tech stack.
+
+## Usage
+
+```bash
+npx @emiliovt3/vibe-stack
+
+# Skip gh auth login (do it manually later with `gh auth login`)
+npx @emiliovt3/vibe-stack --skip-gh-auth
+```
+
+## What Gets Installed
+
+| Tool | Type | Description |
+|------|------|-------------|
+| GitHub CLI (`gh`) | System | Git workflow automation |
+| Claude Code | npm global | AI coding assistant |
+| ClaudeKit | npm global | Claude workflow toolkit |
+| Context7 MCP | MCP server | Up-to-date library docs in context |
+| Sentry MCP | MCP server | Error monitoring integration |
+| Playwright MCP | MCP server | Browser automation |
+| Excalidraw MCP | MCP server | Diagram creation |
+| GitHub MCP | MCP server | GitHub API integration |
+
+## Prerequisites
+
+- Node.js >= 18.0.0
+- npm
+
+## How It Works
+
+1. Installs `gh` CLI via your OS package manager (winget/scoop/choco on Windows, brew on macOS, apt on Linux)
+2. Prompts `gh auth login` if not already authenticated
+3. Installs/updates Claude Code and ClaudeKit globally via npm
+4. Registers all MCP servers with `claude mcp add` (skips already-registered ones)
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Main entry point — orchestrates full vibe-stack installation in dependency order.
+// Order: node check → gh CLI → gh auth → npm tools → MCP servers → summary
+
+import semver from 'semver'
+import { tools } from '../src/registry.js'
+import { getInstalledVersion, getLatestVersion } from '../src/detector.js'
+import { installNpmTool, installGhCli, isGhAuthenticated, runGhAuthLogin } from '../src/installer.js'
+import { getRegisteredMcpNames, registerMcp } from '../src/mcp-registrar.js'
+import { printHeader, createSpinner, printSummary } from '../src/ui.js'
+
+const results = []
+const skipGhAuth = process.argv.includes('--skip-gh-auth')
+
+async function main() {
+  printHeader()
+
+  // 1. Node.js version gate — must be >= 18
+  const nodeVer = process.versions.node
+  if (semver.lt(nodeVer, '18.0.0')) {
+    console.error(`Node.js >= 18 required. Current: v${nodeVer}`)
+    process.exit(1)
+  }
+
+  // 2. gh CLI — required prerequisite, hard fail if install fails
+  const ghTool = tools.find(t => t.id === 'gh')
+  {
+    const sp = createSpinner('GitHub CLI')
+    sp.start()
+    try {
+      const installed = await getInstalledVersion(ghTool)
+      const latest = await getLatestVersion(ghTool)
+
+      if (!installed) {
+        sp.succeed('GitHub CLI — installing...')
+        await installGhCli()
+        results.push({ label: ghTool.label, status: 'installed' })
+      } else if (latest && semver.lt(installed, latest)) {
+        sp.succeed(`GitHub CLI — updating ${installed} → ${latest}`)
+        await installGhCli()
+        results.push({ label: ghTool.label, status: 'updated' })
+      } else {
+        sp.skip(`GitHub CLI — up to date (${installed})`)
+        results.push({ label: ghTool.label, status: 'skipped' })
+      }
+    } catch (err) {
+      sp.fail(`GitHub CLI — failed: ${err.message}`)
+      results.push({ label: ghTool.label, status: 'failed' })
+      process.exit(1) // gh is a hard prerequisite
+    }
+  }
+
+  // 3. gh auth — prompt login if not authenticated (skip with --skip-gh-auth)
+  const authenticated = await isGhAuthenticated()
+  if (!authenticated) {
+    if (skipGhAuth) {
+      console.log('  ℹ  GitHub CLI: auth skipped (run `gh auth login` manually)\n')
+    } else {
+      console.log('\n  GitHub CLI needs authentication. Launching browser login...\n')
+      await runGhAuthLogin()
+    }
+  }
+
+  // 4. npm global tools (claude-code, claudekit)
+  for (const tool of tools.filter(t => t.type === 'npm')) {
+    const sp = createSpinner(tool.label)
+    sp.start()
+    try {
+      const installed = await getInstalledVersion(tool)
+      const latest = await getLatestVersion(tool)
+
+      if (!installed) {
+        await installNpmTool(tool)
+        sp.succeed(`${tool.label} — installed`)
+        results.push({ label: tool.label, status: 'installed' })
+      } else if (latest && semver.lt(installed, latest)) {
+        await installNpmTool(tool)
+        sp.succeed(`${tool.label} — updated ${installed} → ${latest}`)
+        results.push({ label: tool.label, status: 'updated' })
+      } else {
+        sp.skip(`${tool.label} — up to date (${installed})`)
+        results.push({ label: tool.label, status: 'skipped' })
+      }
+    } catch (err) {
+      sp.fail(`${tool.label} — failed: ${err.message}`)
+      results.push({ label: tool.label, status: 'failed' })
+    }
+  }
+
+  // 5. MCP servers
+  const registeredNames = await getRegisteredMcpNames()
+  for (const tool of tools.filter(t => t.type === 'mcp')) {
+    const sp = createSpinner(tool.label)
+    sp.start()
+    try {
+      const status = await registerMcp(tool, registeredNames)
+      if (status === 'skipped') {
+        sp.skip(`${tool.label} — already registered`)
+      } else {
+        sp.succeed(`${tool.label} — registered`)
+      }
+      results.push({ label: tool.label, status })
+    } catch (err) {
+      sp.fail(`${tool.label} — failed: ${err.message}`)
+      results.push({ label: tool.label, status: 'failed' })
+    }
+  }
+
+  // 6. Print final summary
+  printSummary(results)
+}
+
+main().catch(err => {
+  console.error('\n  Error:', err.message)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@emiliovt3/vibe-stack",
+  "version": "1.0.0",
+  "description": "Cross-platform vibe-coding tech stack installer",
+  "type": "module",
+  "bin": {
+    "vibe-stack": "bin/install.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "execa": "^8.0.1",
+    "ora": "^8.1.1",
+    "semver": "^7.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/detector.js

@@ -0,0 +1,61 @@
+// Version detection for installed tools and latest available versions.
+// getInstalledVersion: runs the tool's checkCmd, parses output with its parseVersion fn.
+// getLatestVersion: fetches from npm registry or GitHub releases API.
+
+import { execa } from 'execa'
+
+/**
+ * Returns the currently installed version of a tool, or null if not installed.
+ * For npm-type tools, falls back to `npm list -g --json` if checkCmd fails.
+ */
+export async function getInstalledVersion(tool) {
+  // Try the tool's own version command first
+  try {
+    const [bin, args] = tool.checkCmd
+    const { stdout } = await execa(bin, args)
+    const version = tool.parseVersion?.(stdout) ?? stdout.trim()
+    return version || null
+  } catch {
+    // For npm tools, fall back to npm list
+    if (tool.type === 'npm' && tool.pkg) {
+      try {
+        const { stdout } = await execa('npm', ['list', '-g', '--json', '--depth=0'])
+        const json = JSON.parse(stdout)
+        return json.dependencies?.[tool.pkg]?.version ?? null
+      } catch {
+        return null
+      }
+    }
+    return null
+  }
+}
+
+/**
+ * Returns the latest available version of a tool, or null if not applicable.
+ * - npm type: queries https://registry.npmjs.org/<pkg>/latest
+ * - system type: queries tool.latestUrl (GitHub releases API), uses tool.parseLatest
+ * - mcp type: returns null (no version tracking needed for MCP servers)
+ */
+export async function getLatestVersion(tool) {
+  try {
+    if (tool.type === 'npm' && tool.pkg) {
+      const res = await fetch(`https://registry.npmjs.org/${tool.pkg}/latest`)
+      if (!res.ok) return null
+      const json = await res.json()
+      return json.version ?? null
+    }
+
+    if (tool.type === 'system' && tool.latestUrl) {
+      const res = await fetch(tool.latestUrl, {
+        headers: { 'User-Agent': 'vibe-stack-installer' },
+      })
+      if (!res.ok) return null
+      const json = await res.json()
+      return tool.parseLatest?.(json) ?? null
+    }
+
+    return null // mcp type — no version tracking
+  } catch {
+    return null
+  }
+}

package/src/installer.js

@@ -0,0 +1,48 @@
+// Install/update orchestration for npm global tools and gh CLI.
+// All commands passed as arrays to execa — no shell string interpolation (prevents injection).
+
+import { execa } from 'execa'
+import { getGhInstallCmd } from './platform.js'
+
+/**
+ * Installs or updates an npm global tool.
+ * Both install and update use the same `npm install -g <pkg>` command.
+ */
+export async function installNpmTool(tool) {
+  await execa('npm', ['install', '-g', tool.pkg], { stdio: 'pipe' })
+}
+
+/**
+ * Installs gh CLI using the OS-appropriate package manager.
+ * Hard-fails if no package manager is found — gh is a required prerequisite.
+ */
+export async function installGhCli() {
+  const cmd = await getGhInstallCmd()
+  if (!cmd) {
+    throw new Error(
+      'No package manager found for gh CLI. Install manually: https://cli.github.com/'
+    )
+  }
+  const [bin, args] = cmd
+  await execa(bin, args, { stdio: 'inherit' })
+}
+
+/**
+ * Returns true if gh is authenticated (`gh auth status` exits 0).
+ */
+export async function isGhAuthenticated() {
+  try {
+    await execa('gh', ['auth', 'status'])
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Launches interactive gh auth login — must run in a real TTY terminal.
+ * Uses stdio: 'inherit' so the user sees the browser OAuth prompt.
+ */
+export async function runGhAuthLogin() {
+  await execa('gh', ['auth', 'login'], { stdio: 'inherit' })
+}

package/src/mcp-registrar.js

@@ -0,0 +1,61 @@
+// MCP server registration via `claude mcp add`.
+// Checks for already-registered servers to avoid duplicate suffix bugs (e.g. context7_1).
+
+import { execa } from 'execa'
+
+/**
+ * Returns a Set of currently registered MCP server names.
+ * Parses `claude mcp list` output — each line starts with the server name.
+ */
+export async function getRegisteredMcpNames() {
+  try {
+    const { stdout } = await execa('claude', ['mcp', 'list'])
+    // Two output formats:
+    //   plugin:<scope>:<name>: <cmd> - <status>   (remote/plugin MCPs)
+    //   <name>: <cmd> - <status>                  (locally-added MCPs via `claude mcp add`)
+    // claude.ai lines are skipped — they use a different registration mechanism
+    const names = new Set()
+    for (const line of stdout.split('\n')) {
+      const trimmed = line.trim()
+      // Skip cloud-managed entries
+      if (trimmed.startsWith('claude.ai')) continue
+      // Format 1: plugin:<scope>:<name>:
+      const pluginMatch = trimmed.match(/^plugin:[^:]+:([^:]+):/)
+      if (pluginMatch) { names.add(pluginMatch[1]); continue }
+      // Format 2: <name>: (locally added)
+      const localMatch = trimmed.match(/^([A-Za-z0-9_-]+):/)
+      if (localMatch) names.add(localMatch[1])
+    }
+    return names
+  } catch {
+    return new Set()
+  }
+}
+
+/**
+ * Registers an MCP server with Claude Code via `claude mcp add`.
+ * Skips if already registered (avoids duplicate suffix bug).
+ * On Windows, wraps npx with `cmd /c` for correct PATH resolution.
+ *
+ * @returns 'registered' | 'skipped'
+ */
+export async function registerMcp(tool, registeredNames) {
+  if (registeredNames.has(tool.mcpName)) return 'skipped'
+
+  const isWin = process.platform === 'win32'
+  // Windows requires cmd /c to resolve npx correctly in non-interactive shells
+  const runnerArgs = isWin
+    ? ['cmd', '/c', 'npx', '-y', tool.mcpPkg]
+    : ['npx', '-y', tool.mcpPkg]
+
+  await execa('claude', [
+    'mcp', 'add',
+    '--transport', 'stdio',
+    '--scope', 'user',
+    tool.mcpName,
+    '--',
+    ...runnerArgs,
+  ])
+
+  return 'registered'
+}

package/src/platform.js

@@ -0,0 +1,42 @@
+// OS detection and package manager resolution for gh CLI installation.
+// Returns the first available package manager command on the current OS.
+
+import { execa } from 'execa'
+
+/** Returns the current OS platform string. */
+export const getOS = () => process.platform
+
+/**
+ * Detects available package manager and returns the gh install command.
+ * Windows: tries winget → scoop → choco in order.
+ * macOS: brew.
+ * Linux: apt.
+ * Returns null if no package manager found (manual install required).
+ */
+export async function getGhInstallCmd() {
+  if (process.platform === 'darwin') {
+    return ['brew', ['install', 'gh']]
+  }
+
+  if (process.platform === 'linux') {
+    return ['sudo', ['apt', 'install', '-y', 'gh']]
+  }
+
+  // Windows: probe for winget, scoop, choco in preference order
+  const candidates = [
+    ['winget', ['install', '--id', 'GitHub.cli', '-e']],
+    ['scoop',  ['install', 'gh']],
+    ['choco',  ['install', 'gh', '-y']],
+  ]
+
+  for (const [cmd, args] of candidates) {
+    try {
+      await execa(cmd, ['--version'])
+      return [cmd, args]
+    } catch {
+      // not available, try next
+    }
+  }
+
+  return null // no package manager found — user must install gh manually
+}

package/src/registry.js

@@ -0,0 +1,72 @@
+// Tool registry — single source of truth for all 8 tool descriptors.
+// All install/detect/register logic reads from this array; nothing is hardcoded elsewhere.
+
+export const tools = [
+  // --- System tools (installed via OS package manager) ---
+  {
+    id: 'gh',
+    label: 'GitHub CLI',
+    type: 'system',
+    checkCmd: ['gh', ['--version']],
+    parseVersion: (stdout) => stdout.match(/gh version (\S+)/)?.[1] ?? null,
+    latestUrl: 'https://api.github.com/repos/cli/cli/releases/latest',
+    parseLatest: (json) => json.tag_name.replace('v', ''),
+  },
+
+  // --- npm global tools ---
+  {
+    id: 'claude-code',
+    label: 'Claude Code',
+    type: 'npm',
+    pkg: '@anthropic-ai/claude-code',
+    checkCmd: ['claude', ['--version']],
+    // claude --version outputs "1.2.3 (Claude Code)" — extract semver part
+    parseVersion: (stdout) => stdout.match(/^(\d+\.\d+\.\d+)/)?.[1] ?? null,
+  },
+  {
+    id: 'claudekit',
+    label: 'ClaudeKit',
+    type: 'npm',
+    pkg: 'claudekit-cli',
+    checkCmd: ['ck', ['--version']],
+    // ck --version outputs "CLI Version: 1.2.3\n..." — extract semver part
+    parseVersion: (stdout) => stdout.match(/CLI Version:\s*(\d+\.\d+\.\d+)/)?.[1] ?? null,
+  },
+
+  // --- MCP servers (registered via `claude mcp add`) ---
+  {
+    id: 'context7',
+    label: 'Context7 MCP',
+    type: 'mcp',
+    mcpPkg: '@upstash/context7-mcp',
+    mcpName: 'context7',
+  },
+  {
+    id: 'sentry',
+    label: 'Sentry MCP',
+    type: 'mcp',
+    mcpPkg: '@sentry/mcp-server',
+    mcpName: 'sentry',
+  },
+  {
+    id: 'playwright',
+    label: 'Playwright MCP',
+    type: 'mcp',
+    mcpPkg: '@playwright/mcp',
+    mcpName: 'playwright',
+  },
+  {
+    id: 'excalidraw',
+    label: 'Excalidraw MCP',
+    type: 'mcp',
+    mcpPkg: 'excalidraw-mcp',
+    mcpName: 'excalidraw',
+  },
+  {
+    id: 'github-mcp',
+    label: 'GitHub MCP',
+    type: 'mcp',
+    mcpPkg: '@modelcontextprotocol/server-github',
+    mcpName: 'github',
+  },
+]

package/src/ui.js

@@ -0,0 +1,40 @@
+// ora spinners + chalk UI helpers: spinner factory, header banner, summary table.
+
+import ora from 'ora'
+import chalk from 'chalk'
+
+/**
+ * Creates a spinner wrapper with semantic methods.
+ * @param {string} label - Display text shown while spinner is active
+ */
+export function createSpinner(label) {
+  const spinner = ora(label)
+  return {
+    start:   ()    => spinner.start(),
+    succeed: (msg) => spinner.succeed(chalk.green(msg)),
+    skip:    (msg) => spinner.info(chalk.cyan(msg)),
+    fail:    (msg) => spinner.fail(chalk.red(msg)),
+  }
+}
+
+/** Prints the vibe-stack header banner. */
+export function printHeader() {
+  console.log(chalk.bold.blue('\n  vibe-stack installer'))
+  console.log(chalk.gray('  Cross-platform vibe-coding tech stack\n'))
+}
+
+/**
+ * Prints a summary table of all tool install results.
+ * @param {Array<{label: string, status: string}>} results
+ */
+export function printSummary(results) {
+  console.log(chalk.bold('\n  Summary:'))
+  for (const { label, status } of results) {
+    const icon =
+      status === 'failed'   ? chalk.red('✗') :
+      status === 'skipped'  ? chalk.cyan('→') :
+                              chalk.green('✓')
+    console.log(`  ${icon}  ${label.padEnd(20)} ${chalk.gray(status)}`)
+  }
+  console.log()
+}