@marcusrbrown/infra 0.4.11 → 0.6.0

package/src/commands/gateway/status.ts

@@ -1,8 +1,11 @@
 import type {goke} from 'goke'
+import type {ActionCtx} from '../../lib/action-ctx'
 import type {StatusSummary} from '../status'
 
 import {z} from 'zod'
 
+// ─── Minimal ctx interface (subset of GokeExecutionContext used by this action) ─
+
 import {validateGatewayHost} from './host'
 
 declare const process: {
@@ -175,6 +178,52 @@ export async function getGatewayStatusSummary(host: string): Promise<StatusSumma
   }
 }
 
+// ─── Action (exported for direct testing) ────────────────────────────────────
+
+export async function gatewayStatusAction(
+  options: {key?: string | undefined},
+  ctx: ActionCtx,
+  spawn?: SpawnFn,
+): Promise<void> {
+  const hostEnvKey = options.key ?? 'GATEWAY_HOST'
+  const host = process.env[hostEnvKey]
+
+  if (!host) {
+    ctx.console.error(`Gateway host not set. Export ${hostEnvKey} or pass --key <env-name> pointing to a set variable.`)
+    ctx.process.exit(1)
+    return
+  }
+
+  ctx.console.log('Gateway status')
+  ctx.console.log('')
+
+  const result = await getGatewayComposeStatus(host, spawn)
+
+  if (!result.ok && result.services.length === 0) {
+    ctx.console.error(`Error: ${result.error ?? 'Unknown error'}`)
+    ctx.process.exit(1)
+    return
+  }
+
+  ctx.console.log('Service          State      Health')
+  ctx.console.log('─────────────────────────────────────')
+
+  for (const row of result.services) {
+    const svc = row.service.padEnd(16)
+    const state = row.state.padEnd(10)
+    ctx.console.log(`${svc} ${state} ${row.health}`)
+  }
+
+  ctx.console.log('')
+
+  if (result.ok) {
+    ctx.console.log('Status: OK')
+  } else {
+    ctx.console.log('Status: DEGRADED (one or more services not running)')
+    ctx.process.exit(1)
+  }
+}
+
 // ─── Command registration ─────────────────────────────────────────────────────
 
 export function registerGatewayStatus(cli: ReturnType<typeof goke>): void {
@@ -184,43 +233,5 @@ export function registerGatewayStatus(cli: ReturnType<typeof goke>): void {
       '--key [key]',
       z.string().describe('Environment variable name holding the SSH host. Falls back to GATEWAY_HOST when omitted.'),
     )
-    .action(async options => {
-      const hostEnvKey = options.key ?? 'GATEWAY_HOST'
-      const host = process.env[hostEnvKey]
-
-      if (!host) {
-        console.error(`Gateway host not set. Export ${hostEnvKey} or pass --key <env-name> pointing to a set variable.`)
-        process.exitCode = 1
-        return
-      }
-
-      console.log('Gateway status')
-      console.log('')
-
-      const result = await getGatewayComposeStatus(host)
-
-      if (!result.ok && result.services.length === 0) {
-        console.error(`Error: ${result.error ?? 'Unknown error'}`)
-        process.exitCode = 1
-        return
-      }
-
-      console.log('Service          State      Health')
-      console.log('─────────────────────────────────────')
-
-      for (const row of result.services) {
-        const svc = row.service.padEnd(16)
-        const state = row.state.padEnd(10)
-        console.log(`${svc} ${state} ${row.health}`)
-      }
-
-      console.log('')
-
-      if (result.ok) {
-        console.log('Status: OK')
-      } else {
-        console.log('Status: DEGRADED (one or more services not running)')
-        process.exitCode = 1
-      }
-    })
+    .action((options, ctx) => gatewayStatusAction(options, ctx))
 }

package/src/commands/keeweb/status.test.ts

@@ -1,5 +1,6 @@
 import {afterEach, beforeEach, describe, expect, it, mock, spyOn} from 'bun:test'
 
+import {createCapturedCtx, expectCapturedToInclude} from '../../__test__/mcp-ctx-fixture'
 import {
   checkContentHash,
   checkHttpReachability,
@@ -7,6 +8,7 @@ import {
   formatDate,
   formatDurationMs,
   hashSha256,
+  keewebStatusAction,
 } from './status'
 
 const originalFetch = globalThis.fetch
@@ -210,3 +212,147 @@ describe('keeweb status helpers', () => {
     })
   })
 })
+
+describe('keewebStatusAction (Tier-2 ctx capture)', () => {
+  let fetchMock: ReturnType<typeof mock<typeof fetch>>
+  let fileSpy: ReturnType<typeof spyOn<typeof Bun, 'file'>> | undefined
+  let spawnSpy: ReturnType<typeof spyOn<typeof Bun, 'spawn'>> | undefined
+
+  beforeEach(() => {
+    fetchMock = mock(
+      createFetchImplementation(async () => {
+        throw new Error('Unexpected fetch call')
+      }),
+    )
+    globalThis.fetch = Object.assign(fetchMock, {preconnect: originalFetch.preconnect})
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    fileSpy?.mockRestore()
+    fileSpy = undefined
+    spawnSpy?.mockRestore()
+    spawnSpy = undefined
+  })
+
+  it('writes "KeeWeb status" header to ctx.console.log (not global console)', async () => {
+    // Mock HTTP 200
+    fetchMock.mockImplementation(createFetchImplementation(async () => new Response('ok', {status: 200})))
+
+    // Mock gh CLI returning a successful run
+    spawnSpy = spyOn(Bun, 'spawn').mockImplementation(() =>
+      mockSpawnResult(0, JSON.stringify([{createdAt: '2026-01-15T10:30:00Z', url: 'https://example.com'}])),
+    )
+
+    // Mock local dist file as missing (avoids filesystem dependency)
+    fileSpy = spyOn(Bun, 'file').mockImplementation(
+      () =>
+        ({
+          exists: async () => false,
+        }) as ReturnType<typeof Bun.file>,
+    )
+
+    const {ctx, captured} = createCapturedCtx()
+
+    await keewebStatusAction({verbose: false}, ctx)
+
+    // 'KeeWeb status' is the header line in the formatted output — the contract
+    // marker confirming the action printed to ctx.console.log (captured) rather
+    // than the real global console (which would not appear in `captured`).
+    expect(expectCapturedToInclude(captured, 'KeeWeb status')).toBe(true)
+    // Summary footer is always emitted; pairing it with the header proves both
+    // ends of the formatted output flow through ctx capture.
+    expect(expectCapturedToInclude(captured, 'Summary:')).toBe(true)
+  })
+
+  it('writes HTTP check result to captured stdout', async () => {
+    fetchMock.mockImplementation(createFetchImplementation(async () => new Response('ok', {status: 200})))
+
+    spawnSpy = spyOn(Bun, 'spawn').mockImplementation(() =>
+      mockSpawnResult(0, JSON.stringify([{createdAt: '2026-01-15T10:30:00Z', url: 'https://example.com'}])),
+    )
+
+    fileSpy = spyOn(Bun, 'file').mockImplementation(
+      () =>
+        ({
+          exists: async () => false,
+        }) as ReturnType<typeof Bun.file>,
+    )
+
+    const {ctx, captured} = createCapturedCtx()
+
+    await keewebStatusAction({verbose: false}, ctx)
+
+    expect(expectCapturedToInclude(captured, 'HTTP reachability')).toBe(true)
+    expect(expectCapturedToInclude(captured, '[OK]')).toBe(true)
+  })
+
+  it('writes summary line to captured stdout', async () => {
+    fetchMock.mockImplementation(createFetchImplementation(async () => new Response('ok', {status: 200})))
+
+    spawnSpy = spyOn(Bun, 'spawn').mockImplementation(() =>
+      mockSpawnResult(0, JSON.stringify([{createdAt: '2026-01-15T10:30:00Z', url: 'https://example.com'}])),
+    )
+
+    fileSpy = spyOn(Bun, 'file').mockImplementation(
+      () =>
+        ({
+          exists: async () => false,
+        }) as ReturnType<typeof Bun.file>,
+    )
+
+    const {ctx, captured} = createCapturedCtx()
+
+    await keewebStatusAction({verbose: false}, ctx)
+
+    expect(expectCapturedToInclude(captured, 'Summary:')).toBe(true)
+    expect(expectCapturedToInclude(captured, '3 checks')).toBe(true)
+  })
+
+  it('calls ctx.process.exit(1) when there are errors', async () => {
+    // HTTP 500 → error level
+    fetchMock.mockImplementation(createFetchImplementation(async () => new Response('error', {status: 500})))
+
+    spawnSpy = spyOn(Bun, 'spawn').mockImplementation(() =>
+      mockSpawnResult(0, JSON.stringify([{createdAt: '2026-01-15T10:30:00Z', url: 'https://example.com'}])),
+    )
+
+    fileSpy = spyOn(Bun, 'file').mockImplementation(
+      () =>
+        ({
+          exists: async () => false,
+        }) as ReturnType<typeof Bun.file>,
+    )
+
+    const {ctx, captured} = createCapturedCtx()
+
+    // ctx.process.exit throws MockProcessExit — catch it
+    await expect(keewebStatusAction({verbose: false}, ctx)).rejects.toMatchObject({
+      name: 'MockProcessExit',
+      code: 1,
+    })
+
+    expect(captured.exit).toEqual({code: 1})
+  })
+
+  it('does not call ctx.process.exit when all checks pass', async () => {
+    fetchMock.mockImplementation(createFetchImplementation(async () => new Response('ok', {status: 200})))
+
+    spawnSpy = spyOn(Bun, 'spawn').mockImplementation(() =>
+      mockSpawnResult(0, JSON.stringify([{createdAt: '2026-01-15T10:30:00Z', url: 'https://example.com'}])),
+    )
+
+    fileSpy = spyOn(Bun, 'file').mockImplementation(
+      () =>
+        ({
+          exists: async () => false,
+        }) as ReturnType<typeof Bun.file>,
+    )
+
+    const {ctx, captured} = createCapturedCtx()
+
+    await keewebStatusAction({verbose: false}, ctx)
+
+    expect(captured.exit).toBeNull()
+  })
+})

package/src/commands/keeweb/status.ts

@@ -1,13 +1,11 @@
 import type {goke} from 'goke'
+
+import type {ActionCtx} from '../../lib/action-ctx'
 import type {StatusSummary} from '../status'
 
 import path from 'node:path'
 import {z} from 'zod'
 
-declare const process: {
-  exitCode?: number
-}
-
 const SITE_URL = 'https://kw.igg.ms/'
 const GH_REPO = 'marcusrbrown/infra'
 const HTTP_TIMEOUT_MS = 10_000
@@ -254,13 +252,13 @@ export async function checkContentHash(verbose: boolean): Promise<CheckResult> {
   }
 }
 
-function printCheckResult(result: CheckResult): void {
-  console.log(`[${levelLabel(result.level)}] ${result.title}`)
-  console.log(`  ${result.summary}`)
+function printCheckResult(result: CheckResult, ctx: ActionCtx): void {
+  ctx.console.log(`[${levelLabel(result.level)}] ${result.title}`)
+  ctx.console.log(`  ${result.summary}`)
 
   if (result.details && result.details.length > 0) {
     for (const detail of result.details) {
-      console.log(`  - ${detail}`)
+      ctx.console.log(`  - ${detail}`)
     }
   }
 }
@@ -286,34 +284,36 @@ export async function getKeewebStatusSummary(verbose: boolean): Promise<StatusSu
   }
 }
 
-export function registerKeewebStatus(cli: ReturnType<typeof goke>): void {
-  cli
-    .command('keeweb status', 'Show operational health of the KeeWeb deployment')
-    .option('--verbose', 'Enable verbose output for all commands')
-    .action(async options => {
-      const verbose = options.verbose === true
+export async function keewebStatusAction(options: {verbose?: boolean}, ctx: ActionCtx): Promise<void> {
+  const verbose = options.verbose === true
+
+  ctx.console.log('KeeWeb status')
+  ctx.console.log('')
 
-      console.log('KeeWeb status')
-      console.log('')
+  const results = await Promise.all([
+    checkHttpReachability(verbose),
+    checkLastDeploy(verbose),
+    checkContentHash(verbose),
+  ])
 
-      const results = await Promise.all([
-        checkHttpReachability(verbose),
-        checkLastDeploy(verbose),
-        checkContentHash(verbose),
-      ])
+  for (const result of results) {
+    printCheckResult(result, ctx)
+    ctx.console.log('')
+  }
 
-      for (const result of results) {
-        printCheckResult(result)
-        console.log('')
-      }
+  const errorCount = results.filter(result => result.level === 'error').length
+  const warningCount = results.filter(result => result.level === 'warning').length
 
-      const errorCount = results.filter(result => result.level === 'error').length
-      const warningCount = results.filter(result => result.level === 'warning').length
+  ctx.console.log(`Summary: ${results.length} checks, ${errorCount} errors, ${warningCount} warnings`)
 
-      console.log(`Summary: ${results.length} checks, ${errorCount} errors, ${warningCount} warnings`)
+  if (errorCount > 0) {
+    ctx.process.exit(1)
+  }
+}
 
-      if (errorCount > 0) {
-        process.exitCode = 1
-      }
-    })
+export function registerKeewebStatus(cli: ReturnType<typeof goke>): void {
+  cli
+    .command('keeweb status', 'Show operational health of the KeeWeb deployment')
+    .option('--verbose', 'Enable verbose output for all commands')
+    .action(keewebStatusAction)
 }

package/src/commands/mcp.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Tier-1 in-process MCP integration test.
+ *
+ * Uses @modelcontextprotocol/sdk's InMemoryTransport to spin up the MCP server
+ * in-process (no subprocess) and assert the tool list + call contracts.
+ *
+ * // FALLBACK: If InMemoryTransport proves incompatible with @goke/mcp@0.0.10's
+ * // transport injection in a future SDK version, switch to subprocess mode:
+ * //
+ * //   const proc = Bun.spawn(['bun', 'run', 'packages/cli/src/cli.ts', 'mcp'], {
+ * //     stdin: 'pipe',
+ * //     stdout: 'pipe',
+ * //     stderr: 'pipe',
+ * //   })
+ * //   const transport = new StdioClientTransport({
+ * //     readable: proc.stdout,
+ * //     writable: proc.stdin,
+ * //   })
+ * //   const client = new Client({name: 'test-client', version: '1.0.0'}, {capabilities: {}})
+ * //   await client.connect(transport)
+ * //   // ... same assertions below ...
+ * //   await client.close()
+ * //   proc.kill()
+ */
+
+import type {CallToolResult} from '@modelcontextprotocol/sdk/types.js'
+
+import {createMcpAction} from '@goke/mcp'
+import {Client} from '@modelcontextprotocol/sdk/client'
+import {InMemoryTransport} from '@modelcontextprotocol/sdk/inMemory.js'
+import {CallToolResultSchema} from '@modelcontextprotocol/sdk/types.js'
+import {afterAll, beforeAll, describe, expect, test} from 'bun:test'
+import {goke} from 'goke'
+
+import {registerCliproxyCommands} from './cliproxy'
+import {registerGatewayCommands} from './gateway'
+import {registerKeewebCommands} from './keeweb'
+import {MCP_ALLOWLIST, registerMcp} from './mcp'
+import {registerStatus} from './status'
+
+// ─── Tool name constants ──────────────────────────────────────────────────────
+
+/** Derived from the production MCP_ALLOWLIST — spaces replaced by underscores. */
+const EXPECTED_TOOLS = [...MCP_ALLOWLIST].map(name => name.replaceAll(' ', '_')).sort()
+
+/** The 9 CLI-only commands that must NOT appear in the MCP tool list. */
+const CLI_ONLY_TOOLS = [
+  'cliproxy_deploy',
+  'cliproxy_login',
+  'cliproxy_open',
+  'cliproxy_setup',
+  'gateway_deploy',
+  'gateway_logs',
+  'gateway_restore',
+  'keeweb_deploy',
+  'keeweb_open',
+].sort()
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildTestCli(): ReturnType<typeof goke> {
+  const cli = goke('infra')
+  cli.option('--verbose', 'Enable verbose output for all commands')
+  registerKeewebCommands(cli)
+  registerCliproxyCommands(cli)
+  registerGatewayCommands(cli)
+  registerStatus(cli)
+  registerMcp(cli)
+  return cli
+}
+
+// ─── Suite ────────────────────────────────────────────────────────────────────
+
+describe('mcp integration (Tier-1, in-process)', () => {
+  let client: Client
+
+  beforeAll(async () => {
+    const cli = buildTestCli()
+
+    // Simulate goke having matched the 'mcp' command so createMcpAction
+    // auto-excludes it from the tool list (it reads cli.matchedCommandName).
+    cli.matchedCommandName = 'mcp'
+
+    const [serverTransport, clientTransport] = InMemoryTransport.createLinkedPair()
+
+    // createMcpAction supports a custom createTransport factory (Option A).
+    // We inject the in-memory server transport so no stdio is involved.
+    const mcpAction = createMcpAction({
+      cli,
+      commandFilter: (name: string) => MCP_ALLOWLIST.has(name),
+      createTransport: () => serverTransport,
+    })
+
+    // Start the server (non-blocking — server.connect() resolves once the
+    // transport handshake completes, then the server listens for requests).
+    await mcpAction()
+
+    client = new Client({name: 'test-client', version: '1.0.0'}, {capabilities: {}})
+    await client.connect(clientTransport)
+  })
+
+  afterAll(async () => {
+    await client?.close()
+  })
+
+  // ── tools/list assertions ──────────────────────────────────────────────────
+
+  test('tools/list returns exactly the 10 allowlist tool names', async () => {
+    const result = await client.listTools()
+    const names = result.tools.map((t: {name: string}) => t.name).sort()
+    expect(names).toEqual(EXPECTED_TOOLS)
+  })
+
+  test('cli-only commands are absent from the tool list', async () => {
+    const result = await client.listTools()
+    const names = new Set(result.tools.map((t: {name: string}) => t.name))
+    for (const excluded of CLI_ONLY_TOOLS) {
+      expect(names.has(excluded)).toBe(false)
+    }
+  })
+
+  // ── Mode B contract: gateway_backup ───────────────────────────────────────
+  //
+  // gateway_backup tries to SSH to a real droplet, which is unreachable in CI.
+  // We assert the contract: the tool returns a non-empty CallToolResult.
+  // In CI the result will be an error CallToolResult (isError: true) because
+  // SSH fails — that's fine; the contract is that the MCP layer wraps the
+  // error and returns content rather than throwing.
+
+  test('gateway_backup returns a non-empty CallToolResult (Mode B contract)', async () => {
+    const rawResult = await client.callTool(
+      {
+        name: 'gateway_backup',
+        arguments: {},
+      },
+      CallToolResultSchema,
+    )
+    // Parse through the schema to get a properly typed result.
+    // The tool must return at least one content block (even on SSH failure).
+    const result: CallToolResult = CallToolResultSchema.parse(rawResult)
+    expect(result.content.length).toBeGreaterThan(0)
+  })
+
+  // ── Mode C contract: cliproxy_keys_list ───────────────────────────────────
+  //
+  // Mode C: when a command returns structured data AND prints to stdout,
+  // the CallToolResult must contain BOTH a stdout text block AND a
+  // stringified return-value text block.
+  //
+  // Re-enable after Unit 4 lands (cliproxy keys list refactor to return
+  // structured data alongside ctx-printed text).
+
+  // Re-enable after Unit 4 lands (cliproxy keys list refactor to return
+  // structured data alongside ctx-printed text).
+  test('cliproxy_keys_list returns BOTH stdout block AND structured return block (Mode C contract)', async () => {
+    const originalFetch = globalThis.fetch
+    const originalKey = process.env.CLIPROXY_MANAGEMENT_KEY
+
+    try {
+      process.env.CLIPROXY_MANAGEMENT_KEY = 'test-management-key'
+
+      globalThis.fetch = (async (_url: string | URL | Request, _init?: RequestInit): Promise<Response> => {
+        return new Response(JSON.stringify(['fro-bot-test1', 'fro-bot-test2']), {
+          status: 200,
+          headers: {'content-type': 'application/json'},
+        })
+      }) as typeof fetch
+
+      const rawResult = await client.callTool(
+        {
+          name: 'cliproxy_keys_list',
+          arguments: {},
+        },
+        CallToolResultSchema,
+      )
+
+      const result: CallToolResult = CallToolResultSchema.parse(rawResult)
+
+      // Mode C contract: at least 2 content blocks (stdout text + structured return)
+      expect(result.content.length).toBeGreaterThanOrEqual(2)
+
+      const allText = result.content
+        .filter((block): block is {type: 'text'; text: string} => block.type === 'text')
+        .map(block => block.text)
+        .join('\n')
+
+      // One block must contain the formatted stdout (key names printed by the action)
+      expect(allText).toContain('fro-bot-test1')
+
+      // One block must contain the stringified return value (JSON array of key names)
+      const hasStructuredReturn = result.content.some(block => {
+        if (block.type !== 'text') return false
+        try {
+          const parsed = JSON.parse(block.text) as unknown
+          return Array.isArray(parsed) && parsed.includes('fro-bot-test1') && parsed.includes('fro-bot-test2')
+        } catch {
+          return false
+        }
+      })
+      expect(hasStructuredReturn).toBe(true)
+    } finally {
+      globalThis.fetch = originalFetch
+      if (originalKey === undefined) {
+        delete process.env.CLIPROXY_MANAGEMENT_KEY
+      } else {
+        process.env.CLIPROXY_MANAGEMENT_KEY = originalKey
+      }
+    }
+  })
+})

package/src/commands/mcp.ts

@@ -1,8 +1,37 @@
 import type {goke} from 'goke'
 import {createMcpAction} from '@goke/mcp'
 
+/**
+ * Commands intentionally excluded from MCP exposure (not in MCP_ALLOWLIST):
+ *
+ * - `gateway deploy`   — subprocess streaming (Bun.spawn with stdout: 'inherit'), deferred to MCP v2 (#291)
+ * - `cliproxy deploy`  — subprocess streaming, deferred to MCP v2 (#291)
+ * - `keeweb deploy`    — subprocess streaming, deferred to MCP v2 (#291)
+ * - `gateway logs`     — subprocess streaming, deferred to MCP v2 (#291)
+ * - `cliproxy login`   — interactive (OAuth callback URL paste, requires TTY)
+ * - `cliproxy open`    — interactive (SSH TUI session, requires TTY)
+ * - `cliproxy setup`   — interactive (@clack/prompts wizard, requires TTY)
+ * - `gateway restore`  — destructive policy (replaces mitmproxy CA on live gateway, deferred to MCP v2 #292)
+ * - `keeweb open`      — host-machine side effect (spawns local browser, requires user intent)
+ */
+export const MCP_ALLOWLIST: ReadonlySet<string> = new Set([
+  'gateway status',
+  'gateway backup',
+  'cliproxy status',
+  'cliproxy keys list',
+  'cliproxy keys add',
+  'cliproxy keys remove',
+  'cliproxy config get',
+  'cliproxy config set',
+  'keeweb status',
+  'status',
+])
+
 export function registerMcp(cli: ReturnType<typeof goke>): void {
-  cli
-    .command('mcp', 'Start a stdio MCP server exposing all CLI commands as tools for coding agents')
-    .action(createMcpAction({cli}))
+  cli.command('mcp', 'Start a stdio MCP server exposing all CLI commands as tools for coding agents').action(
+    createMcpAction({
+      cli,
+      commandFilter: name => MCP_ALLOWLIST.has(name),
+    }),
+  )
 }