@gokiteam/goki-dev 0.2.0

package/src/mcp/tools/services.js

@@ -0,0 +1,169 @@
+export function registerServicesTools (server, apiClient) {
+  server.tool(
+    'services_list',
+    'List all dev-tools platform services and their status',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/services/list')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to list services: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'services_status',
+    'Get detailed status of all services',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/services/status')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to get services status: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'services_restart',
+    'Restart dev-tools services',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/services/restart')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to restart services: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'scheduler_start',
+    'Start the one-minute scheduler tick publisher',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/scheduler/tick/start')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to start scheduler: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'scheduler_stop',
+    'Stop the scheduler tick',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/scheduler/tick/stop')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to stop scheduler: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'scheduler_status',
+    'Get scheduler tick status (running/stopped, interval)',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/scheduler/tick/status')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to get scheduler status: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'scheduler_trigger',
+    'Manually trigger a scheduler tick (useful for testing)',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/scheduler/tick/trigger')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to trigger scheduler tick: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'gateway_start',
+    'Start the app gateway service',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/gateway/start')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to start gateway: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'gateway_stop',
+    'Stop the app gateway service',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/gateway/stop')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to stop gateway: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'gateway_status',
+    'Get the app gateway status',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/gateway/status')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to get gateway status: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'gateway_trigger_scan',
+    'Trigger a gateway scan for connected services',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/gateway/triggerScan')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to trigger gateway scan: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'gateway_health_check',
+    'Run health checks on all gateway endpoints',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/gateway/healthCheck')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to run gateway health check: ${error.message}` }], isError: true }
+      }
+    }
+  )
+}

package/src/mcp/tools/snapshots.js

@@ -0,0 +1,88 @@
+import { z } from 'zod'
+
+export function registerSnapshotTools (server, apiClient) {
+  server.tool(
+    'snapshots_create',
+    'Create a snapshot of development environment (PostgreSQL, Firestore, and SQLite metadata). This saves the current state before running tests.',
+    {
+      services: z.array(z.enum(['postgres', 'firestore', 'sqlite'])).optional().describe('Services to snapshot. Defaults to all configured services.')
+    },
+    async ({ services }) => {
+      try {
+        const body = {}
+        if (services !== undefined) body.services = services
+        const data = await apiClient.post('/v1/snapshots/create', body)
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'snapshots_restore',
+    'Restore development environment from a snapshot. This will stop microservices, restore data, and restart them.',
+    {
+      snapshotId: z.string().describe('Snapshot ID to restore from (e.g., "e2e_2026-02-26_10-30-45")'),
+      restartServices: z.boolean().optional().describe('Whether to restart microservices after restore (default: true)')
+    },
+    async ({ snapshotId, restartServices }) => {
+      try {
+        const body = { snapshotId }
+        if (restartServices !== undefined) body.restartServices = restartServices
+        const data = await apiClient.post('/v1/snapshots/restore', body)
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'snapshots_list',
+    'List all available snapshots with their metadata',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/snapshots/list', {})
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'snapshots_details',
+    'Get detailed information about a specific snapshot',
+    {
+      snapshotId: z.string().describe('Snapshot ID to get details for')
+    },
+    async ({ snapshotId }) => {
+      try {
+        const data = await apiClient.post('/v1/snapshots/details', { snapshotId })
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'snapshots_delete',
+    'Delete a snapshot and its files',
+    {
+      snapshotId: z.string().optional().describe('Snapshot ID to delete. If omitted, deletes all snapshots.')
+    },
+    async ({ snapshotId }) => {
+      try {
+        const body = {}
+        if (snapshotId !== undefined) body.snapshotId = snapshotId
+        const data = await apiClient.post('/v1/snapshots/delete', body)
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+      }
+    }
+  )
+}

package/src/mcp/tools/webhooks.js

@@ -0,0 +1,115 @@
+import { z } from 'zod'
+
+export function registerWebhooksTools (server, apiClient) {
+  server.tool(
+    'webhooks_register',
+    'Register a webhook endpoint for forwarding requests',
+    {
+      prefix: z.string().describe('URL prefix to match incoming requests against'),
+      target: z.string().describe('Target URL to forward matching requests to'),
+      pathRewrite: z.string().optional().describe('Optional path rewrite pattern for the forwarded request'),
+      description: z.string().optional().describe('Optional human-readable description of the webhook')
+    },
+    async ({ prefix, target, pathRewrite, description }) => {
+      try {
+        const body = { prefix, target }
+        if (pathRewrite !== undefined) body.pathRewrite = pathRewrite
+        if (description !== undefined) body.description = description
+        const data = await apiClient.post('/v1/webhooks/register', body)
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to register webhook: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'webhooks_list',
+    'List all registered webhooks',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/webhooks/list')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to list webhooks: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'webhooks_remove',
+    'Remove a registered webhook by its prefix',
+    {
+      prefix: z.string().describe('URL prefix of the webhook to remove')
+    },
+    async ({ prefix }) => {
+      try {
+        const data = await apiClient.post('/v1/webhooks/remove', { prefix })
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to remove webhook: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'webhooks_test',
+    'Send a test request to a webhook endpoint',
+    {
+      prefix: z.string().describe('URL prefix of the webhook to test')
+    },
+    async ({ prefix }) => {
+      try {
+        const data = await apiClient.post('/v1/webhooks/test', { prefix })
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to test webhook: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'webhooks_tunnel_status',
+    'Get ngrok tunnel status (connected/disconnected, public URL)',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/webhooks/tunnel/status')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to get tunnel status: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'webhooks_settings_get',
+    'Get current webhook/ngrok settings',
+    {},
+    async () => {
+      try {
+        const data = await apiClient.post('/v1/webhooks/settings/get')
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to get webhook settings: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'webhooks_settings_update',
+    'Update webhook/ngrok settings',
+    {
+      settings: z.record(z.any()).describe('Settings object with key-value pairs to update')
+    },
+    async ({ settings }) => {
+      try {
+        const data = await apiClient.post('/v1/webhooks/settings/update', { settings })
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Failed to update webhook settings: ${error.message}` }], isError: true }
+      }
+    }
+  )
+}

package/src/middleware/DevProxy.js

@@ -0,0 +1,67 @@
+import httpProxy from 'http-proxy'
+import { Logger } from '../singletons/Logger.js'
+
+/**
+ * Development proxy middleware
+ * Forwards requests to the React dev server running on port 3000
+ * Only used in development mode
+ */
+export const DevProxy = (targetUrl = 'http://localhost:3000') => {
+  const proxy = httpProxy.createProxyServer({
+    target: targetUrl,
+    changeOrigin: true,
+    ws: true, // Support WebSocket (for React Hot Reload)
+    logLevel: 'warn'
+  })
+
+  // Handle proxy errors
+  proxy.on('error', (err, req, res) => {
+    Logger.log({
+      level: 'error',
+      message: 'Proxy error',
+      data: {
+        error: err.message,
+        url: req.url,
+        method: req.method
+      }
+    })
+
+    // Send error response
+    if (!res.headersSent) {
+      res.writeHead(502, { 'Content-Type': 'text/plain' })
+    }
+    res.end('Proxy Error: Unable to connect to React dev server. Make sure it\'s running on port 3000.')
+  })
+
+  // Koa middleware
+  return async (ctx, next) => {
+    // Skip proxy for API routes
+    if (ctx.path.startsWith('/v1') || ctx.path.startsWith('/v2')) {
+      return next()
+    }
+
+    // Log proxy request
+    Logger.log({
+      level: 'debug',
+      message: 'Proxying request to React dev server',
+      data: {
+        method: ctx.method,
+        path: ctx.path,
+        target: targetUrl
+      }
+    })
+
+    // Proxy the request
+    ctx.respond = false // Bypass Koa's response handling
+
+    return new Promise((resolve, reject) => {
+      proxy.web(ctx.req, ctx.res, {}, (err) => {
+        if (err) {
+          reject(err)
+        } else {
+          resolve()
+        }
+      })
+    })
+  }
+}

package/src/middleware/ErrorCatcher.js

@@ -0,0 +1,35 @@
+import { Logger } from '../singletons/Logger.js'
+
+export const ErrorCatcher = () => {
+  return async (ctx, next) => {
+    try {
+      await next()
+    } catch (error) {
+      const isOops = error.isOops
+      const status = isOops ? error.data.status : 500
+      const errorReason = isOops ? error.data.reason : 'unknownError'
+      const message = error.message || 'An unexpected error occurred'
+      const traceId = ctx.state.traceId || ctx.request.body?.traceId
+      Logger.log({
+        level: 'error',
+        message: 'Request error',
+        data: {
+          error: isOops ? error.data : { message: error.message, stack: error.stack },
+          traceId,
+          path: ctx.path,
+          method: ctx.method
+        }
+      })
+      ctx.status = status
+      ctx.body = {
+        success: false,
+        status,
+        errorReason,
+        message,
+        data: {
+          traceId
+        }
+      }
+    }
+  }
+}

package/src/middleware/HttpProxy.js

@@ -0,0 +1,215 @@
+import { Readable } from 'stream'
+import zlib from 'zlib'
+import { HttpProxy } from '../singletons/HttpProxy.js'
+import { Logger } from '../singletons/Logger.js'
+
+function bufferRequestBody (req) {
+  return new Promise((resolve) => {
+    const chunks = []
+    let size = 0
+    req.on('data', (chunk) => {
+      chunks.push(chunk)
+      size += chunk.length
+    })
+    req.on('end', () => {
+      try {
+        resolve(Buffer.concat(chunks))
+      } catch {
+        resolve(null)
+      }
+    })
+    req.on('error', () => {
+      resolve(null)
+    })
+    if (req.readableEnded || req.complete) {
+      resolve(null)
+    }
+  })
+}
+
+function decompressBuffer (buffer, encoding) {
+  if (!encoding) return buffer
+  try {
+    if (encoding === 'gzip' || encoding === 'x-gzip') {
+      return zlib.gunzipSync(buffer)
+    }
+    if (encoding === 'deflate') {
+      return zlib.inflateSync(buffer)
+    }
+    if (encoding === 'br') {
+      return zlib.brotliDecompressSync(buffer)
+    }
+  } catch {
+    return buffer
+  }
+  return buffer
+}
+
+function collectStreamBody (stream, contentEncoding) {
+  return new Promise((resolve) => {
+    const chunks = []
+    stream.on('data', (chunk) => {
+      chunks.push(chunk)
+    })
+    stream.on('end', () => {
+      try {
+        const raw = decompressBuffer(Buffer.concat(chunks), contentEncoding).toString('utf-8')
+        resolve({ raw })
+      } catch {
+        resolve({ raw: null })
+      }
+    })
+    stream.on('error', () => {
+      resolve({ raw: null })
+    })
+  })
+}
+
+function parseCookies (cookieHeader) {
+  if (!cookieHeader) return null
+  const cookies = {}
+  cookieHeader.split(';').forEach(part => {
+    const [key, ...rest] = part.trim().split('=')
+    if (key) cookies[key.trim()] = rest.join('=').trim()
+  })
+  return Object.keys(cookies).length > 0 ? cookies : null
+}
+
+export const HttpProxyMiddleware = () => {
+  return async (ctx, next) => {
+    if (!ctx.path.startsWith('/proxy/')) {
+      return next()
+    }
+    // Reconstruct full URL including query string (Koa strips it from ctx.path)
+    const fullProxyPath = ctx.querystring
+      ? ctx.path + '?' + ctx.querystring
+      : ctx.path
+    const resolved = HttpProxy.parseTargetUrl(fullProxyPath)
+    if (!resolved) {
+      ctx.status = 400
+      ctx.body = {
+        success: false,
+        status: 400,
+        message: 'Invalid proxy target URL',
+        data: { path: ctx.path }
+      }
+      return
+    }
+    const startTime = Date.now()
+    const startedAt = new Date().toISOString()
+    const traceId = ctx.get('X-Trace-Id') || ctx.state?.traceId || null
+    const rawBodyBuffer = await bufferRequestBody(ctx.req)
+    const requestBodyStr = rawBodyBuffer ? rawBodyBuffer.toString('utf-8') : null
+    const requestHeaders = { ...ctx.req.headers }
+    const cookies = parseCookies(requestHeaders.cookie)
+    const contentType = requestHeaders['content-type'] || null
+    const targetUrl = new URL(resolved.fullUrl)
+    const queryParams = targetUrl.search
+      ? Object.fromEntries(targetUrl.searchParams)
+      : null
+    Logger.log({
+      level: 'info',
+      message: `HTTP Proxy IN: ${ctx.method} ${resolved.fullUrl}`,
+      data: {
+        method: ctx.method,
+        target: resolved.fullUrl,
+        service: resolved.serviceName
+      }
+    })
+    ctx.respond = false
+    // resolved.path already includes the query string from the target URL
+    ctx.req.url = resolved.path
+    const bodyStream = rawBodyBuffer
+      ? Readable.from(rawBodyBuffer)
+      : Readable.from(Buffer.alloc(0))
+    return new Promise((resolve) => {
+      HttpProxy.proxy.web(ctx.req, ctx.res, {
+        target: resolved.origin,
+        buffer: bodyStream
+      }, (err) => {
+        const elapsed = Date.now() - startTime
+        if (err) {
+          Logger.log({
+            level: 'error',
+            message: `HTTP Proxy ERR: ${ctx.method} ${resolved.fullUrl} → 502 (${elapsed}ms) ${err.message}`,
+            data: {
+              method: ctx.method,
+              target: resolved.fullUrl,
+              error: err.message,
+              responseTimeMs: elapsed
+            }
+          })
+          HttpProxy.logTraffic({
+            method: ctx.method,
+            targetUrl: resolved.fullUrl,
+            targetHost: resolved.host,
+            targetPath: resolved.path,
+            queryParams,
+            requestHeaders,
+            requestBody: requestBodyStr,
+            requestCookies: cookies,
+            contentType,
+            statusCode: 502,
+            responseHeaders: null,
+            responseBody: null,
+            responseContentType: null,
+            responseTimeMs: elapsed,
+            startedAt,
+            completedAt: new Date().toISOString(),
+            sourceService: resolved.serviceName,
+            error: err.message,
+            traceId
+          })
+          if (!ctx.res.headersSent) {
+            ctx.res.writeHead(502, { 'Content-Type': 'application/json' })
+          }
+          ctx.res.end(JSON.stringify({
+            success: false,
+            message: `HTTP proxy error: ${err.message}`,
+            target: resolved.fullUrl
+          }))
+        }
+        resolve()
+      })
+      HttpProxy.proxy.once('proxyRes', async (proxyRes) => {
+        const elapsed = Date.now() - startTime
+        const contentEncoding = (proxyRes.headers['content-encoding'] || '').trim().toLowerCase()
+        const { raw: responseBody } = await collectStreamBody(proxyRes, contentEncoding || null)
+        const responseHeaders = { ...proxyRes.headers }
+        const responseContentType = responseHeaders['content-type'] || null
+        Logger.log({
+          level: proxyRes.statusCode >= 400 ? 'warn' : 'info',
+          message: `HTTP Proxy OUT: ${ctx.method} ${resolved.fullUrl} → ${proxyRes.statusCode} (${elapsed}ms)`,
+          data: {
+            method: ctx.method,
+            target: resolved.fullUrl,
+            statusCode: proxyRes.statusCode,
+            responseTimeMs: elapsed,
+            service: resolved.serviceName
+          }
+        })
+        HttpProxy.logTraffic({
+          method: ctx.method,
+          targetUrl: resolved.fullUrl,
+          targetHost: resolved.host,
+          targetPath: resolved.path,
+          queryParams,
+          requestHeaders,
+          requestBody: requestBodyStr,
+          requestCookies: cookies,
+          contentType,
+          statusCode: proxyRes.statusCode,
+          responseHeaders,
+          responseBody,
+          responseContentType,
+          responseTimeMs: elapsed,
+          startedAt,
+          completedAt: new Date().toISOString(),
+          sourceService: resolved.serviceName,
+          error: null,
+          traceId
+        })
+      })
+    })
+  }
+}