@gokiteam/goki-dev 0.2.0

package/cli/HttpProxyRewriter.js

@@ -0,0 +1,91 @@
+import path from 'path'
+import { collectAllEnvVars } from './ComposeParser.js'
+
+const DEV_TOOLS_PROXY_BASE = 'http://goki-dev-tools-backend:9000/proxy'
+
+// Env var names that should be checked for proxy rewriting
+const URL_SUFFIXES = ['_URL', '_BASE_URL']
+
+// Infrastructure hostnames to skip (not HTTP API services)
+const INFRA_SKIP_LIST = [
+  'redis', 'goki-redis', 'goki-redis-logs',
+  'postgres', 'goki-postgres',
+  'goki-pubsub-emulator', 'pubsub-emulator',
+  'goki-firestore-emulator', 'firestore-emulator',
+  'goki-elasticsearch', 'elasticsearch',
+  'goki-kibana', 'kibana',
+  'goki-dev-tools-backend', 'goki-dev-tools-frontend',
+  'localhost', '127.0.0.1'
+]
+
+/**
+ * Check if an env var name is a URL variable that should be proxied
+ */
+function isUrlEnvVar (name) {
+  return URL_SUFFIXES.some(suffix => name.endsWith(suffix))
+}
+
+/**
+ * Check if a hostname matches a filter pattern (substring match)
+ */
+function hostnameMatchesPattern (hostname, pattern) {
+  return hostname === pattern || hostname.includes(pattern)
+}
+
+/**
+ * Check if a URL value should be proxied through dev-tools for monitoring
+ */
+function isProxiableUrl (value, proxyConfig = {}) {
+  if (!value.startsWith('http://') && !value.startsWith('https://')) return false
+  try {
+    const url = new URL(value)
+    const hostname = url.hostname
+    if (INFRA_SKIP_LIST.includes(hostname)) return false
+    if (proxyConfig.include?.length > 0) {
+      return proxyConfig.include.some(p => hostnameMatchesPattern(hostname, p))
+    }
+    if (proxyConfig.exclude?.length > 0) {
+      if (proxyConfig.exclude.some(p => hostnameMatchesPattern(hostname, p))) {
+        return false
+      }
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Compute HTTP proxy URL rewrites as pure data (no file writing)
+ *
+ * @param {object} config - The config object with httpProxy settings
+ * @param {string} projectDir - Absolute path to project root
+ * @returns {{ rewrites: Array<{key, original, proxied}>, skipped: Array<{key, original, hostname}>, serviceName: string }} or null
+ */
+export function computeProxyRewrites (config, projectDir) {
+  const docker = config.docker || {}
+  const proxyConfig = config.httpProxy || {}
+  const composeFile = docker.composeFile || 'docker-compose.yaml'
+  const envFilePath = path.join(projectDir, 'config.development')
+  const composePath = path.join(projectDir, composeFile)
+  const { allVars, serviceName } = collectAllEnvVars(envFilePath, composePath)
+  if (!serviceName) return null
+  const rewrites = []
+  const skipped = []
+  for (const [key, value] of Object.entries(allVars)) {
+    if (!isUrlEnvVar(key)) continue
+    if (isProxiableUrl(value, proxyConfig)) {
+      const proxiedUrl = `${DEV_TOOLS_PROXY_BASE}/${value}`
+      rewrites.push({ key, original: value, proxied: proxiedUrl })
+    } else if (value.startsWith('http://') || value.startsWith('https://')) {
+      try {
+        const hostname = new URL(value).hostname
+        if (!INFRA_SKIP_LIST.includes(hostname)) {
+          skipped.push({ key, original: value, hostname })
+        }
+      } catch {}
+    }
+  }
+  if (rewrites.length === 0) return null
+  return { rewrites, skipped, serviceName }
+}

package/cli/Logger.js

@@ -0,0 +1,10 @@
+import chalk from 'chalk'
+import ora from 'ora'
+
+export const Logger = {
+  info: (msg) => console.log(chalk.blue('ℹ'), msg),
+  success: (msg) => console.log(chalk.green('✓'), msg),
+  error: (msg) => console.log(chalk.red('✗'), msg),
+  warn: (msg) => console.log(chalk.yellow('⚠'), msg),
+  spinner: (text) => ora(text).start()
+}

package/cli/McpConfigManager.js

@@ -0,0 +1,123 @@
+import fs from 'fs'
+import path from 'path'
+import { ensureGitignore } from './DevToolsDir.js'
+
+const MCP_SERVER_NAME = 'goki-dev-tools'
+const MCP_COMMAND = 'goki-dev-mcp'
+
+function buildServerEntry () {
+  return {
+    command: MCP_COMMAND,
+    env: {
+      DEV_TOOLS_URL: 'http://localhost:9000'
+    }
+  }
+}
+
+function isEntryUpToDate (current, expected) {
+  if (!current) return false
+  if (current.command !== expected.command) return false
+  if (current.env?.DEV_TOOLS_URL !== expected.env.DEV_TOOLS_URL) return false
+  return true
+}
+
+/**
+ * Ensures the target project's .mcp.json includes the goki-dev-tools MCP server.
+ * Creates the file if missing, or merges/fixes the entry if it exists.
+ * Uses the globally-linked `goki-dev-mcp` command (no absolute paths).
+ * Also ensures .dev-tools/ and .mcp.json are in .gitignore.
+ *
+ * Returns { created, updated, skipped, path }
+ */
+export function ensureMcpConfig () {
+  const projectDir = process.cwd()
+  const mcpPath = path.join(projectDir, '.mcp.json')
+  const serverEntry = buildServerEntry()
+  let existing = {}
+  let fileExists = false
+  if (fs.existsSync(mcpPath)) {
+    fileExists = true
+    try {
+      existing = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'))
+    } catch {
+      existing = {}
+    }
+  }
+  if (!existing.mcpServers) {
+    existing.mcpServers = {}
+  }
+  const current = existing.mcpServers[MCP_SERVER_NAME]
+  if (isEntryUpToDate(current, serverEntry)) {
+    ensureGitignore(projectDir)
+    return { created: false, updated: false, skipped: true, path: mcpPath }
+  }
+  const wasUpdate = !!current
+  existing.mcpServers[MCP_SERVER_NAME] = serverEntry
+  fs.writeFileSync(mcpPath, JSON.stringify(existing, null, 2) + '\n')
+  ensureGitignore(projectDir)
+  return {
+    created: !fileExists,
+    updated: wasUpdate,
+    skipped: false,
+    path: mcpPath
+  }
+}
+
+const MCP_ALLOW_PATTERN = `mcp__${MCP_SERVER_NAME}__*`
+
+/**
+ * Checks if Claude Code permissions already allow all dev-tools MCP tools.
+ */
+export function checkClaudePermissions () {
+  const projectDir = process.cwd()
+  const settingsPath = path.join(projectDir, '.claude', 'settings.local.json')
+  if (!fs.existsSync(settingsPath)) {
+    return { allowed: false, path: settingsPath }
+  }
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'))
+    const allowList = settings?.permissions?.allow || []
+    const allowed = allowList.includes(MCP_ALLOW_PATTERN)
+    return { allowed, path: settingsPath }
+  } catch {
+    return { allowed: false, path: settingsPath }
+  }
+}
+
+/**
+ * Adds the MCP wildcard allow pattern to .claude/settings.local.json.
+ */
+export function addClaudePermissions () {
+  const projectDir = process.cwd()
+  const claudeDir = path.join(projectDir, '.claude')
+  const settingsPath = path.join(claudeDir, 'settings.local.json')
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true })
+  }
+  let settings = {}
+  let fileExists = false
+  if (fs.existsSync(settingsPath)) {
+    fileExists = true
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'))
+    } catch {
+      settings = {}
+    }
+  }
+  if (!settings.permissions) {
+    settings.permissions = {}
+  }
+  if (!Array.isArray(settings.permissions.allow)) {
+    settings.permissions.allow = []
+  }
+  if (settings.permissions.allow.includes(MCP_ALLOW_PATTERN)) {
+    return { created: false, updated: false, path: settingsPath }
+  }
+  settings.permissions.allow.push(MCP_ALLOW_PATTERN)
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n')
+  return {
+    created: !fileExists,
+    updated: fileExists,
+    path: settingsPath
+  }
+}

package/cli/NgrokManager.js

@@ -0,0 +1,431 @@
+import { execa } from 'execa'
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { Logger } from './Logger.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const DEV_TOOLS_API = 'http://localhost:9000'
+const NGROK_API = 'http://localhost:4040'
+const DATA_DIR = path.resolve(__dirname, '..', 'data')
+const PID_FILE = path.join(DATA_DIR, 'ngrok.pid')
+const STATE_FILE = path.join(DATA_DIR, 'ngrok.json')
+
+export class NgrokManager {
+  // --- PID File Management ---
+
+  static ensureDataDir () {
+    if (!fs.existsSync(DATA_DIR)) {
+      fs.mkdirSync(DATA_DIR, { recursive: true })
+    }
+  }
+
+  static writePid (pid) {
+    this.ensureDataDir()
+    fs.writeFileSync(PID_FILE, String(pid), 'utf8')
+  }
+
+  static readPid () {
+    try {
+      const content = fs.readFileSync(PID_FILE, 'utf8').trim()
+      const pid = parseInt(content, 10)
+      return isNaN(pid) ? null : pid
+    } catch {
+      return null
+    }
+  }
+
+  static writeState ({ pid, domain, port, startedAt, startedBy }) {
+    this.ensureDataDir()
+    fs.writeFileSync(STATE_FILE, JSON.stringify({ pid, domain, port, startedAt, startedBy }, null, 2), 'utf8')
+  }
+
+  static readState () {
+    try {
+      const content = fs.readFileSync(STATE_FILE, 'utf8')
+      return JSON.parse(content)
+    } catch {
+      return null
+    }
+  }
+
+  static cleanStateFiles () {
+    try { fs.unlinkSync(PID_FILE) } catch { /* ignore */ }
+    try { fs.unlinkSync(STATE_FILE) } catch { /* ignore */ }
+  }
+
+  // --- Process Validation ---
+
+  static isProcessAlive (pid) {
+    try {
+      process.kill(pid, 0)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  static async isInstalled () {
+    try {
+      await execa('ngrok', ['version'], { stdio: 'pipe' })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  static async isRunning () {
+    try {
+      const response = await fetch(`${NGROK_API}/api/tunnels`, {
+        signal: AbortSignal.timeout(2000)
+      })
+      return response.ok
+    } catch {
+      return false
+    }
+  }
+
+  static async getTunnelUrl () {
+    try {
+      const response = await fetch(`${NGROK_API}/api/tunnels`, {
+        signal: AbortSignal.timeout(2000)
+      })
+      if (!response.ok) return null
+      const data = await response.json()
+      const tunnel = data.tunnels?.[0]
+      return tunnel?.public_url || null
+    } catch {
+      return null
+    }
+  }
+
+  static async getTunnelInfo () {
+    try {
+      const response = await fetch(`${NGROK_API}/api/tunnels`, {
+        signal: AbortSignal.timeout(2000)
+      })
+      if (!response.ok) return null
+      const data = await response.json()
+      const tunnel = data.tunnels?.[0]
+      if (!tunnel) return null
+      return {
+        url: tunnel.public_url,
+        addr: tunnel.config?.addr,
+        proto: tunnel.proto
+      }
+    } catch {
+      return null
+    }
+  }
+
+  static async verifyTunnel (expectedDomain, expectedPort) {
+    const info = await this.getTunnelInfo()
+    if (!info) return { valid: false, reason: 'No tunnel found' }
+    if (expectedDomain && !info.url?.includes(expectedDomain)) {
+      return { valid: false, url: info.url, reason: `Domain mismatch: running ${info.url}, expected ${expectedDomain}` }
+    }
+    if (expectedPort && info.addr && !info.addr.includes(String(expectedPort))) {
+      return { valid: false, url: info.url, reason: `Port mismatch: forwarding to ${info.addr}, expected ${expectedPort}` }
+    }
+    return { valid: true, url: info.url }
+  }
+
+  // --- Lifecycle ---
+
+  static async start (domain, port = 9000, projectName = null) {
+    // Check if ngrok is already running via its API
+    if (await this.isRunning()) {
+      const verification = await this.verifyTunnel(domain, port)
+      if (verification.valid) {
+        return { alreadyRunning: true, url: verification.url, pid: this.readPid() }
+      }
+      // Tunnel exists but domain/port mismatch — restart
+      Logger.info(`Restarting ngrok — ${verification.reason}`)
+      await this.stop()
+    }
+    // Clean up stale PID file if process is dead
+    const existingPid = this.readPid()
+    if (existingPid) {
+      if (this.isProcessAlive(existingPid)) {
+        // Process alive but API not responding — kill it
+        Logger.info('Cleaning up unresponsive ngrok process')
+        try { process.kill(existingPid, 'SIGKILL') } catch { /* ignore */ }
+        await new Promise(resolve => setTimeout(resolve, 500))
+      }
+      this.cleanStateFiles()
+    }
+    // Build ngrok args
+    const ngrokArgs = ['http', '--log', 'stderr']
+    if (domain) {
+      ngrokArgs.push('--url', domain)
+    }
+    ngrokArgs.push(String(port))
+    // Start ngrok with nohup to survive terminal close
+    // Note: Both stdout and stderr go to /dev/null to prevent blocking the CLI process
+    // Verification happens via ngrok's API and health check requests
+    const child = execa('nohup', ['ngrok', ...ngrokArgs], {
+      stdio: ['ignore', fs.openSync('/dev/null', 'w'), fs.openSync('/dev/null', 'w')],
+      detached: true,
+      cleanup: false
+    })
+    child.unref()
+    const pid = child.pid
+    // Write PID and state files
+    this.writePid(pid)
+    this.writeState({
+      pid,
+      domain,
+      port,
+      startedAt: new Date().toISOString(),
+      startedBy: projectName
+    })
+    // Wait for tunnel to be ready and verify it works
+    try {
+      const url = await this.waitForReady()
+      return { alreadyRunning: false, url, pid }
+    } catch (error) {
+      // Tunnel failed to start - clean up and provide helpful error
+      this.cleanStateFiles()
+      if (this.isProcessAlive(pid)) {
+        // Process is alive but tunnel didn't come up - likely auth/config issue
+        try { process.kill(pid, 'SIGKILL') } catch { /* ignore */ }
+        throw new Error('ngrok process started but tunnel failed to initialize. Check your ngrok auth token and domain configuration.')
+      } else {
+        // Process died - likely ngrok not found or crashed
+        throw new Error('ngrok process failed to start. Verify ngrok is installed and accessible.')
+      }
+    }
+  }
+
+  static async waitForReady (timeout = 15000) {
+    const startTime = Date.now()
+    while (Date.now() - startTime < timeout) {
+      const url = await this.getTunnelUrl()
+      if (url) {
+        // Verify tunnel actually works by making a test request
+        const tunnelWorks = await this.verifyTunnelWorks(url)
+        if (tunnelWorks) {
+          return url
+        }
+        // URL exists but tunnel doesn't work yet - keep waiting
+      }
+      await new Promise(resolve => setTimeout(resolve, 500))
+    }
+    throw new Error('ngrok did not become ready within timeout')
+  }
+
+  static async verifyTunnelWorks (tunnelUrl) {
+    try {
+      // Make a health check request through the tunnel
+      const response = await fetch(`${tunnelUrl}/health`, {
+        method: 'GET',
+        signal: AbortSignal.timeout(3000),
+        headers: {
+          'User-Agent': 'goki-dev-cli-verification'
+        }
+      })
+      // Any response (even 404) means tunnel is working
+      // We just need to verify the request reaches the backend
+      return response.status !== undefined
+    } catch (error) {
+      // Network errors mean tunnel isn't working yet
+      return false
+    }
+  }
+
+  static async stop () {
+    const pid = this.readPid()
+    if (pid && this.isProcessAlive(pid)) {
+      // Graceful shutdown
+      try { process.kill(pid, 'SIGTERM') } catch { /* ignore */ }
+      // Wait up to 3 seconds for process to exit
+      const deadline = Date.now() + 3000
+      while (Date.now() < deadline && this.isProcessAlive(pid)) {
+        await new Promise(resolve => setTimeout(resolve, 200))
+      }
+      // Force kill if still alive
+      if (this.isProcessAlive(pid)) {
+        try { process.kill(pid, 'SIGKILL') } catch { /* ignore */ }
+      }
+      this.cleanStateFiles()
+      return { stopped: true, pid }
+    }
+    this.cleanStateFiles()
+    // No PID file but ngrok might still be running — try targeted pgrep
+    if (await this.isRunning()) {
+      try {
+        const { stdout } = await execa('pgrep', ['-f', 'ngrok http'], { stdio: 'pipe' })
+        const pids = stdout.trim().split('\n').filter(Boolean)
+        for (const p of pids) {
+          try { process.kill(parseInt(p, 10), 'SIGTERM') } catch { /* ignore */ }
+        }
+        return { stopped: true, pid: pids[0] ? parseInt(pids[0], 10) : null }
+      } catch {
+        // pgrep found nothing
+      }
+    }
+    return { stopped: false, pid: null }
+  }
+
+  // --- Status ---
+
+  static async getStatus () {
+    const state = this.readState()
+    const pid = this.readPid()
+    const apiRunning = await this.isRunning()
+    const processAlive = pid ? this.isProcessAlive(pid) : false
+    const running = apiRunning && (processAlive || !pid)
+    if (!running) {
+      // Clean up stale files if process is dead
+      if (pid && !processAlive) this.cleanStateFiles()
+      return { running: false, pid: null, url: null, domain: null, port: null, uptime: null, startedBy: null }
+    }
+    const url = await this.getTunnelUrl()
+    let uptime = null
+    if (state?.startedAt) {
+      const ms = Date.now() - new Date(state.startedAt).getTime()
+      const hours = Math.floor(ms / 3600000)
+      const minutes = Math.floor((ms % 3600000) / 60000)
+      uptime = hours > 0 ? `${hours}h ${minutes}m` : `${minutes}m`
+    }
+    return {
+      running: true,
+      pid: pid || null,
+      url,
+      domain: state?.domain || null,
+      port: state?.port || null,
+      uptime,
+      startedBy: state?.startedBy || null
+    }
+  }
+
+  // --- Domain Management ---
+
+  static async loadDomain () {
+    try {
+      const response = await fetch(`${DEV_TOOLS_API}/v1/webhooks/settings/get`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({}),
+        signal: AbortSignal.timeout(3000)
+      })
+      if (response.ok) {
+        const result = await response.json()
+        const domain = result.data?.settings?.ngrok_domain
+        if (domain) return domain
+      }
+    } catch {
+      // API failed, fall through to local file fallback
+    }
+    // Fallback: read from local state file
+    const state = this.readState()
+    return state?.domain || null
+  }
+
+  static async saveDomain (domain) {
+    try {
+      await fetch(`${DEV_TOOLS_API}/v1/webhooks/settings/update`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          settings: { ngrok_domain: domain }
+        }),
+        signal: AbortSignal.timeout(3000)
+      })
+    } catch (error) {
+      Logger.warn(`Failed to save ngrok domain: ${error.message}`)
+    }
+  }
+
+  static async promptForDomain (defaultDomain = null) {
+    const inquirer = await import('inquirer')
+    console.log('\n🌐 Webhook tunneling requires an ngrok static domain.')
+    console.log('   Get your free domain at: https://dashboard.ngrok.com/domains\n')
+    const promptConfig = {
+      type: 'input',
+      name: 'domain',
+      message: defaultDomain
+        ? 'Confirm or update your ngrok static domain:'
+        : 'Enter your ngrok static domain (e.g., your-name.ngrok-free.app):',
+      validate: (input) => {
+        if (!input || !input.includes('.')) {
+          return 'Please enter a valid domain (e.g., your-name.ngrok-free.app)'
+        }
+        return true
+      }
+    }
+    if (defaultDomain) {
+      promptConfig.default = defaultDomain
+    }
+    const { domain } = await inquirer.default.prompt([promptConfig])
+    return domain.trim()
+  }
+
+  // --- Webhook Routes ---
+
+  static async registerWebhookRoutes (webhooks) {
+    const registered = []
+    for (const [prefix, config] of Object.entries(webhooks)) {
+      try {
+        await fetch(`${DEV_TOOLS_API}/v1/webhooks/register`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            prefix,
+            target: config.target,
+            pathRewrite: config.pathRewrite,
+            description: config.description || `${prefix} webhooks`
+          }),
+          signal: AbortSignal.timeout(3000)
+        })
+        registered.push(prefix)
+      } catch (error) {
+        Logger.warn(`Failed to register webhook route '${prefix}': ${error.message}`)
+      }
+    }
+    return registered
+  }
+
+  // --- Orchestration ---
+
+  /**
+   * Full webhook setup: register routes, ensure ngrok domain, start tunnel
+   * @param {Object} webhooks - Webhook configuration from cli.config.js
+   * @param {Object} spinner - ora spinner instance
+   * @param {string} projectName - Name of the project starting the tunnel
+   * @returns {Object} { tunnelUrl, domain, routes, pid }
+   */
+  static async setup (webhooks, spinner, projectName = null) {
+    // Step 1: Register webhook routes
+    if (spinner) spinner.text = 'Registering webhook routes...'
+    const registeredRoutes = await this.registerWebhookRoutes(webhooks)
+    // Step 2: Check for ngrok
+    const installed = await this.isInstalled()
+    if (!installed) {
+      if (spinner) spinner.warn('ngrok not installed — webhook routes registered but no tunnel started')
+      console.log('   Install ngrok: https://ngrok.com/download')
+      console.log('   Then run "goki-dev start" again to auto-start the tunnel\n')
+      return { tunnelUrl: null, domain: null, routes: registeredRoutes, pid: null }
+    }
+    // Step 3: Get or prompt for domain
+    let domain = await this.loadDomain()
+    if (!domain) {
+      if (spinner) spinner.stop()
+      domain = await this.promptForDomain()
+      await this.saveDomain(domain)
+      if (spinner) spinner.start()
+    }
+    // Step 4: Start ngrok tunnel
+    if (spinner) spinner.text = `Starting ngrok tunnel (${domain})...`
+    try {
+      const { url, alreadyRunning, pid } = await this.start(domain, 9000, projectName)
+      if (alreadyRunning) {
+        if (spinner) spinner.text = `ngrok tunnel already running (PID: ${pid || 'unknown'})`
+      }
+      return { tunnelUrl: url, domain, routes: registeredRoutes, pid }
+    } catch (error) {
+      if (spinner) spinner.warn(`Failed to start ngrok: ${error.message}`)
+      return { tunnelUrl: null, domain, routes: registeredRoutes, pid: null }
+    }
+  }
+}