@marcusrbrown/infra 0.4.9 → 0.4.11

package/src/commands/gateway/restore.ts

@@ -0,0 +1,297 @@
+import type {goke} from 'goke'
+
+import {z} from 'zod'
+
+import {validateGatewayHost} from './host'
+
+declare const process: {
+  env: Record<string, string | undefined>
+  exitCode?: number
+}
+
+const MITMPROXY_CERTS_VOLUME = 'mitmproxy-certs'
+const CA_CERT_FILE = 'mitmproxy-ca-cert.pem'
+const CA_KEY_FILE = 'mitmproxy-ca.pem'
+const COMPOSE_PROJECT_DIR = '/opt/gateway/deploy'
+const EXPECTED_ARCHIVE_FILES = new Set([CA_CERT_FILE, CA_KEY_FILE])
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type RestoreSpawnFn = (
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'pipe'; stderr: 'pipe'},
+) => {
+  stdout: ReadableStream<Uint8Array>
+  stderr: ReadableStream<Uint8Array>
+  exited: Promise<number>
+}
+
+export interface RestoreOpts {
+  host: string
+  input: string
+  includeCa: boolean
+}
+
+export type RestoreResult = {ok: true; confirmed: true} | {ok: false; error: string}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Returns the argv array for an SSH command to the given host. */
+function sshCommand(host: string, remote: string): string[] {
+  return ['ssh', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', `root@${host}`, remote]
+}
+
+async function spawnText(
+  spawn: RestoreSpawnFn,
+  cmd: string[],
+  env: Record<string, string>,
+): Promise<{stdout: string; stderr: string; exitCode: number}> {
+  const child = spawn(cmd, {env, stdout: 'pipe', stderr: 'pipe'})
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+  return {stdout, stderr, exitCode}
+}
+
+/**
+ * Validates that the local tarball contains exactly the two expected CA files
+ * and nothing else. Uses `tar -tf` to list contents without extracting.
+ * Returns an error string if invalid, or undefined if valid.
+ */
+export function validateBackupArchive(
+  inputPath: string,
+  spawn: RestoreSpawnFn,
+  env: Record<string, string>,
+): Promise<string | undefined> {
+  return spawnText(spawn, ['tar', '-tf', inputPath], env).then(result => {
+    if (result.exitCode !== 0) {
+      return `Cannot read archive (tar -tf exit ${result.exitCode}): ${result.stderr.trim() || 'unknown error'}`
+    }
+    const listed = result.stdout
+      .split('\n')
+      .map(f => f.trim())
+      .filter(Boolean)
+    const listedSet = new Set(listed)
+    const missing = [...EXPECTED_ARCHIVE_FILES].filter(f => !listedSet.has(f))
+    const extra = listed.filter(f => !EXPECTED_ARCHIVE_FILES.has(f))
+    if (missing.length > 0 || extra.length > 0) {
+      const parts: string[] = []
+      if (missing.length > 0) parts.push(`missing: ${missing.join(', ')}`)
+      if (extra.length > 0) parts.push(`unexpected: ${extra.join(', ')}`)
+      return `Backup archive is malformed — ${parts.join('; ')}`
+    }
+    return undefined
+  })
+}
+
+// ─── Core logic ───────────────────────────────────────────────────────────────
+
+function defaultSpawn(
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'pipe'; stderr: 'pipe'},
+): ReturnType<RestoreSpawnFn> {
+  return Bun.spawn(cmd, opts) as ReturnType<RestoreSpawnFn>
+}
+
+export async function restoreGatewayCa(
+  opts: RestoreOpts,
+  spawn: RestoreSpawnFn = defaultSpawn,
+): Promise<RestoreResult> {
+  if (!opts.includeCa) {
+    return {ok: false, error: 'Only CA restore is currently supported; --no-include-ca is not accepted'}
+  }
+
+  // Validate input file is non-empty before SSHing
+  const inputFile = Bun.file(opts.input)
+  const inputSize = inputFile.size
+
+  if (inputSize === 0) {
+    return {ok: false, error: `Input file is empty: ${opts.input}`}
+  }
+
+  // Validate host before any SSH invocation
+  validateGatewayHost(opts.host)
+
+  const env: Record<string, string> = {
+    PATH: process.env.PATH ?? '/usr/bin:/bin',
+    HOME: process.env.HOME ?? '/tmp',
+    ...(process.env.SSH_AUTH_SOCK ? {SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK} : {}),
+  }
+
+  // COR1: Validate archive contents before touching the remote — fail fast before SCP
+  const archiveError = await validateBackupArchive(opts.input, spawn, env)
+  if (archiveError !== undefined) {
+    return {ok: false, error: archiveError}
+  }
+
+  // SEC2: Generate an unguessable remote tmp path via mktemp on the droplet
+  const mktempResult = await spawnText(spawn, sshCommand(opts.host, 'mktemp -t gateway-ca-restore-XXXXXX.tar'), env)
+  if (mktempResult.exitCode !== 0) {
+    return {
+      ok: false,
+      error: `mktemp failed on remote (exit ${mktempResult.exitCode}): ${mktempResult.stderr.trim() || 'unknown error'}`,
+    }
+  }
+  const tmpRemote = mktempResult.stdout.trim()
+
+  // SCP the tarball to the unguessable remote path
+  const scpCmd = [
+    'scp',
+    '-o',
+    'BatchMode=yes',
+    '-o',
+    'StrictHostKeyChecking=yes',
+    opts.input,
+    `root@${opts.host}:${tmpRemote}`,
+  ]
+
+  let primaryError: RestoreResult | undefined
+
+  try {
+    const scpResult = await spawnText(spawn, scpCmd, env)
+    if (scpResult.exitCode !== 0) {
+      primaryError = {
+        ok: false,
+        error: `SCP failed (exit ${scpResult.exitCode}): ${scpResult.stderr.trim() || 'unknown error'}`,
+      }
+      return primaryError
+    }
+
+    // Defense-in-depth: chmod 600 the SCP'd file on the remote before docker run
+    const chmodResult = await spawnText(spawn, sshCommand(opts.host, `chmod 600 ${tmpRemote}`), env)
+    if (chmodResult.exitCode !== 0) {
+      primaryError = {
+        ok: false,
+        error: `chmod 600 on remote failed (exit ${chmodResult.exitCode}): ${chmodResult.stderr.trim() || 'unknown error'}`,
+      }
+      return primaryError
+    }
+
+    // Extract the tarball into the mitmproxy-certs volume
+    const extractResult = await spawnText(
+      spawn,
+      sshCommand(
+        opts.host,
+        `docker run --rm -v ${MITMPROXY_CERTS_VOLUME}:/dst -v ${tmpRemote}:/src.tar:ro alpine sh -c 'tar -xf /src.tar -C /dst'`,
+      ),
+      env,
+    )
+    if (extractResult.exitCode !== 0) {
+      primaryError = {
+        ok: false,
+        error: `docker run extract failed (exit ${extractResult.exitCode}): ${extractResult.stderr.trim() || 'unknown error'}`,
+      }
+      return primaryError
+    }
+
+    // Restart mitmproxy and gateway services
+    const restartResult = await spawnText(
+      spawn,
+      sshCommand(opts.host, `docker compose --project-directory ${COMPOSE_PROJECT_DIR} restart mitmproxy gateway`),
+      env,
+    )
+    if (restartResult.exitCode !== 0) {
+      primaryError = {
+        ok: false,
+        error: `docker compose restart failed (exit ${restartResult.exitCode}): ${restartResult.stderr.trim() || 'unknown error'}`,
+      }
+      return primaryError
+    }
+
+    // Byte-equal confirmation: read cert and key from inside the volume
+    const [certResult, keyResult] = await Promise.all([
+      spawnText(
+        spawn,
+        sshCommand(opts.host, `docker run --rm -v ${MITMPROXY_CERTS_VOLUME}:/src:ro alpine cat /src/${CA_CERT_FILE}`),
+        env,
+      ),
+      spawnText(
+        spawn,
+        sshCommand(opts.host, `docker run --rm -v ${MITMPROXY_CERTS_VOLUME}:/src:ro alpine cat /src/${CA_KEY_FILE}`),
+        env,
+      ),
+    ])
+
+    if (certResult.exitCode !== 0 || keyResult.exitCode !== 0) {
+      primaryError = {
+        ok: false,
+        error: `Confirmation read failed — cert exit ${certResult.exitCode}, key exit ${keyResult.exitCode}`,
+      }
+      return primaryError
+    }
+
+    // Extract cert and key from the local tarball for comparison
+    const localCertProc = Bun.spawnSync(['tar', '-xOf', opts.input, CA_CERT_FILE])
+    const localKeyProc = Bun.spawnSync(['tar', '-xOf', opts.input, CA_KEY_FILE])
+
+    const localCert = new TextDecoder().decode(localCertProc.stdout)
+    const localKey = new TextDecoder().decode(localKeyProc.stdout)
+
+    if (certResult.stdout !== localCert || keyResult.stdout !== localKey) {
+      primaryError = {
+        ok: false,
+        error: `Confirmation mismatch: restored CA content does not match input tarball. The volume may be in an inconsistent state.`,
+      }
+      return primaryError
+    }
+
+    return {ok: true, confirmed: true}
+  } finally {
+    // Always clean up the tmp file from the droplet; never let cleanup mask the primary failure
+    try {
+      await spawnText(spawn, sshCommand(opts.host, `rm -f ${tmpRemote}`), env)
+    } catch (error) {
+      console.error(`Cleanup also failed: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+}
+
+// ─── Command registration ─────────────────────────────────────────────────────
+
+export function registerGatewayRestore(cli: ReturnType<typeof goke>): void {
+  cli
+    .command(
+      'gateway restore',
+      'Restore the mitmproxy CA certificate and private key from a local tarball into the gateway Docker volume. Restarts mitmproxy and gateway services after restore and confirms byte-equal content before reporting success.',
+    )
+    .option(
+      '--input <file>',
+      z.string().describe('Path to the tarball produced by `gateway backup --include-ca`. Required.'),
+    )
+    .option(
+      '--include-ca',
+      z
+        .boolean()
+        .default(true)
+        .describe('Restore the mitmproxy CA certificate and private key. Currently the only supported restore target.'),
+    )
+    .example('# Restore CA from a backup tarball')
+    .example('infra gateway restore --input apps/gateway/.local/mitmproxy-ca.tar')
+    .example('# Restore CA from a custom path')
+    .example('infra gateway restore --input /secure/backup/mitmproxy-ca.tar --include-ca')
+    .action(async options => {
+      const hostEnvKey = 'GATEWAY_HOST'
+      const host = process.env[hostEnvKey]
+
+      if (!host) {
+        console.error(`Gateway host not set. Export ${hostEnvKey} before running restore.`)
+        process.exitCode = 1
+        return
+      }
+
+      const input = options.input
+      const includeCa = options.includeCa !== false
+
+      const result = await restoreGatewayCa({host, input, includeCa})
+
+      if (!result.ok) {
+        console.error(`Restore failed: ${result.error}`)
+        process.exitCode = 1
+        return
+      }
+
+      console.log('CA restore complete. Byte-equal confirmation passed.')
+    })
+}

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

@@ -0,0 +1,354 @@
+import {afterEach, beforeEach, describe, expect, it} from 'bun:test'
+
+import {parseComposePs, parseComposePsOutput, type ComposePsEntry, type ServiceRow} from './status'
+
+// ─── parseComposePs ──────────────────────────────────────────────────────────
+
+describe('parseComposePs', () => {
+  it('parses all 3 services running with gateway and mitmproxy healthy, workspace n-a', () => {
+    const raw: ComposePsEntry[] = [
+      {Name: 'gateway', State: 'running', Health: 'healthy'},
+      {Name: 'workspace', State: 'running', Health: ''},
+      {Name: 'mitmproxy', State: 'running', Health: 'healthy'},
+    ]
+
+    const rows = parseComposePs(raw)
+
+    expect(rows).toHaveLength(3)
+    expect(rows[0]).toEqual({service: 'gateway', state: 'running', health: 'healthy'} satisfies ServiceRow)
+    expect(rows[1]).toEqual({service: 'workspace', state: 'running', health: 'n-a'} satisfies ServiceRow)
+    expect(rows[2]).toEqual({service: 'mitmproxy', state: 'running', health: 'healthy'} satisfies ServiceRow)
+  })
+
+  it('shows exited state when a container has exited', () => {
+    const raw: ComposePsEntry[] = [
+      {Name: 'gateway', State: 'exited', Health: ''},
+      {Name: 'workspace', State: 'running', Health: ''},
+      {Name: 'mitmproxy', State: 'running', Health: 'healthy'},
+    ]
+
+    const rows = parseComposePs(raw)
+
+    expect(rows[0]).toEqual({service: 'gateway', state: 'exited', health: 'n-a'} satisfies ServiceRow)
+  })
+
+  it('maps unhealthy health status', () => {
+    const raw: ComposePsEntry[] = [{Name: 'gateway', State: 'running', Health: 'unhealthy'}]
+
+    const rows = parseComposePs(raw)
+
+    expect(rows[0]?.health).toBe('unhealthy')
+  })
+
+  it('maps starting health status', () => {
+    const raw: ComposePsEntry[] = [{Name: 'gateway', State: 'running', Health: 'starting'}]
+
+    const rows = parseComposePs(raw)
+
+    expect(rows[0]?.health).toBe('starting')
+  })
+
+  it('returns n-a for unknown health values', () => {
+    const raw: ComposePsEntry[] = [{Name: 'gateway', State: 'running', Health: 'something-weird'}]
+
+    const rows = parseComposePs(raw)
+
+    expect(rows[0]?.health).toBe('n-a')
+  })
+
+  it('returns empty array for empty input', () => {
+    expect(parseComposePs([])).toEqual([])
+  })
+})
+
+// ─── isAllRunning ─────────────────────────────────────────────────────────────
+
+describe('isAllRunning', () => {
+  it('returns true when all services are running', async () => {
+    const {isAllRunning} = await import('./status')
+    const rows: ServiceRow[] = [
+      {service: 'gateway', state: 'running', health: 'healthy'},
+      {service: 'workspace', state: 'running', health: 'n-a'},
+      {service: 'mitmproxy', state: 'running', health: 'healthy'},
+    ]
+
+    expect(isAllRunning(rows)).toBe(true)
+  })
+
+  it('returns false when any service is not running', async () => {
+    const {isAllRunning} = await import('./status')
+    const rows: ServiceRow[] = [
+      {service: 'gateway', state: 'exited', health: 'n-a'},
+      {service: 'workspace', state: 'running', health: 'n-a'},
+      {service: 'mitmproxy', state: 'running', health: 'healthy'},
+    ]
+
+    expect(isAllRunning(rows)).toBe(false)
+  })
+})
+
+// ─── getGatewayComposeStatus (SSH mocked) ────────────────────────────────────
+
+type SpawnFn = (
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'pipe'; stderr: 'pipe'},
+) => {
+  stdout: ReadableStream<Uint8Array>
+  stderr: ReadableStream<Uint8Array>
+  exited: Promise<number>
+}
+
+function makeSpawnOk(jsonOutput: string): SpawnFn {
+  return (_cmd, _opts) => {
+    const encoder = new TextEncoder()
+    return {
+      stdout: new ReadableStream({
+        start(controller) {
+          controller.enqueue(encoder.encode(jsonOutput))
+          controller.close()
+        },
+      }),
+      stderr: new ReadableStream({
+        start(controller) {
+          controller.close()
+        },
+      }),
+      exited: Promise.resolve(0),
+    }
+  }
+}
+
+function makeSpawnError(message: string): SpawnFn {
+  return (_cmd, _opts) => {
+    const encoder = new TextEncoder()
+    return {
+      stdout: new ReadableStream({
+        start(controller) {
+          controller.close()
+        },
+      }),
+      stderr: new ReadableStream({
+        start(controller) {
+          controller.enqueue(encoder.encode(message))
+          controller.close()
+        },
+      }),
+      exited: Promise.resolve(1),
+    }
+  }
+}
+
+describe('getGatewayComposeStatus — host validation (SEC1)', () => {
+  it('rejects a leading-hyphen host and does not invoke ssh', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+
+    const neverSpawn: SpawnFn = () => {
+      throw new Error('spawn must not be called for an invalid host')
+    }
+
+    await expect(getGatewayComposeStatus('-oProxyCommand=evil', neverSpawn)).rejects.toThrow('Invalid GATEWAY_HOST')
+  })
+
+  it('rejects a host with shell metacharacters and does not invoke ssh', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+
+    const neverSpawn: SpawnFn = () => {
+      throw new Error('spawn must not be called for an invalid host')
+    }
+
+    await expect(getGatewayComposeStatus('gateway.example.com;rm -rf', neverSpawn)).rejects.toThrow(
+      'Invalid GATEWAY_HOST',
+    )
+  })
+
+  it('rejects an empty host and does not invoke ssh', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+
+    const neverSpawn: SpawnFn = () => {
+      throw new Error('spawn must not be called for an invalid host')
+    }
+
+    await expect(getGatewayComposeStatus('', neverSpawn)).rejects.toThrow('Invalid GATEWAY_HOST')
+  })
+
+  it('accepts a valid FQDN and invokes ssh normally', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+
+    const psOutput = JSON.stringify([{Name: 'gateway', State: 'running', Health: 'healthy'}])
+    const result = await getGatewayComposeStatus('gateway.example.com', makeSpawnOk(psOutput))
+
+    expect(result.ok).toBe(true)
+  })
+
+  it('accepts localhost as a valid host', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+
+    const psOutput = JSON.stringify([{Name: 'gateway', State: 'running', Health: 'healthy'}])
+    const result = await getGatewayComposeStatus('localhost', makeSpawnOk(psOutput))
+
+    expect(result.ok).toBe(true)
+  })
+
+  it('accepts an IPv4 address as a valid host', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+
+    const psOutput = JSON.stringify([{Name: 'gateway', State: 'running', Health: 'healthy'}])
+    const result = await getGatewayComposeStatus('147.182.133.210', makeSpawnOk(psOutput))
+
+    expect(result.ok).toBe(true)
+  })
+})
+
+describe('getGatewayComposeStatus', () => {
+  let originalEnv: Record<string, string | undefined>
+
+  beforeEach(() => {
+    originalEnv = {GATEWAY_HOST: process.env.GATEWAY_HOST}
+    process.env.GATEWAY_HOST = 'gateway.example.com'
+  })
+
+  afterEach(() => {
+    if (originalEnv.GATEWAY_HOST === undefined) {
+      delete process.env.GATEWAY_HOST
+    } else {
+      process.env.GATEWAY_HOST = originalEnv.GATEWAY_HOST
+    }
+  })
+
+  it('returns ok=true with 3 service rows when all services are running', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+
+    const psOutput = JSON.stringify([
+      {Name: 'gateway', State: 'running', Health: 'healthy'},
+      {Name: 'workspace', State: 'running', Health: ''},
+      {Name: 'mitmproxy', State: 'running', Health: 'healthy'},
+    ])
+
+    const result = await getGatewayComposeStatus('gateway.example.com', makeSpawnOk(psOutput))
+
+    expect(result.ok).toBe(true)
+    expect(result.services).toHaveLength(3)
+    expect(result.services[0]).toEqual({service: 'gateway', state: 'running', health: 'healthy'})
+    expect(result.services[1]).toEqual({service: 'workspace', state: 'running', health: 'n-a'})
+    expect(result.services[2]).toEqual({service: 'mitmproxy', state: 'running', health: 'healthy'})
+  })
+
+  it('returns ok=false when gateway service is exited', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+
+    const psOutput = JSON.stringify([
+      {Name: 'gateway', State: 'exited', Health: ''},
+      {Name: 'workspace', State: 'running', Health: ''},
+      {Name: 'mitmproxy', State: 'running', Health: 'healthy'},
+    ])
+
+    const result = await getGatewayComposeStatus('gateway.example.com', makeSpawnOk(psOutput))
+
+    expect(result.ok).toBe(false)
+    expect(result.services[0]?.state).toBe('exited')
+  })
+
+  it('returns ok=false with error when SSH fails', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+
+    const result = await getGatewayComposeStatus('gateway.example.com', makeSpawnError('Connection refused'))
+
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain('SSH')
+  })
+})
+
+// ─── parseComposePsOutput ─────────────────────────────────────────────────────
+
+// Realistic fixture shape matching live droplet output
+const ndjsonFixture = [
+  String.raw`{"Command":"\"docker-entrypoint.sh\"","CreatedAt":"2026-05-20 08:20:18 +0000 UTC","ExitCode":0,"Health":"healthy","ID":"01e1a16f5752","Image":"fro-bot-gateway","Labels":"","LocalVolumes":"0","Mounts":"","Name":"fro-bot-gateway-1","Names":"fro-bot-gateway-1","Networks":"gateway_default","Ports":"","Project":"gateway","Publishers":null,"RunningFor":"2 hours ago","Service":"gateway","Size":"0B","State":"running","Status":"Up 2 hours (healthy)"}`,
+  String.raw`{"Command":"\"mitmproxy\"","CreatedAt":"2026-05-20 08:20:18 +0000 UTC","ExitCode":0,"Health":"healthy","ID":"02b2c27f6863","Image":"fro-bot-mitmproxy","Labels":"","LocalVolumes":"0","Mounts":"","Name":"fro-bot-mitmproxy-1","Names":"fro-bot-mitmproxy-1","Networks":"gateway_default","Ports":"","Project":"gateway","Publishers":null,"RunningFor":"2 hours ago","Service":"mitmproxy","Size":"0B","State":"running","Status":"Up 2 hours (healthy)"}`,
+  String.raw`{"Command":"\"sleep infinity\"","CreatedAt":"2026-05-20 08:20:18 +0000 UTC","ExitCode":0,"Health":"","ID":"03c3d38g7974","Image":"fro-bot-workspace","Labels":"","LocalVolumes":"0","Mounts":"","Name":"fro-bot-workspace-1","Names":"fro-bot-workspace-1","Networks":"gateway_default","Ports":"","Project":"gateway","Publishers":null,"RunningFor":"2 hours ago","Service":"workspace","Size":"0B","State":"running","Status":"Up 2 hours"}`,
+]
+
+describe('parseComposePsOutput', () => {
+  it('parses NDJSON with 3 lines into 3 entries with correct Name/State/Health', () => {
+    const raw = ndjsonFixture.join('\n')
+    const entries = parseComposePsOutput(raw)
+
+    expect(entries).toHaveLength(3)
+    expect(entries[0]?.Name).toBe('fro-bot-gateway-1')
+    expect(entries[0]?.State).toBe('running')
+    expect(entries[0]?.Health).toBe('healthy')
+    expect(entries[1]?.Name).toBe('fro-bot-mitmproxy-1')
+    expect(entries[1]?.State).toBe('running')
+    expect(entries[1]?.Health).toBe('healthy')
+    expect(entries[2]?.Name).toBe('fro-bot-workspace-1')
+    expect(entries[2]?.State).toBe('running')
+    expect(entries[2]?.Health).toBe('')
+  })
+
+  it('parses legacy single JSON array format', () => {
+    const raw = JSON.stringify([
+      {Name: 'fro-bot-gateway-1', State: 'running', Health: 'healthy'},
+      {Name: 'fro-bot-mitmproxy-1', State: 'running', Health: 'healthy'},
+    ])
+    const entries = parseComposePsOutput(raw)
+
+    expect(entries).toHaveLength(2)
+    expect(entries[0]?.Name).toBe('fro-bot-gateway-1')
+    expect(entries[1]?.Name).toBe('fro-bot-mitmproxy-1')
+  })
+
+  it('returns empty array for empty string', () => {
+    expect(parseComposePsOutput('')).toEqual([])
+  })
+
+  it('returns empty array for whitespace-only input', () => {
+    expect(parseComposePsOutput('   \n  \n  ')).toEqual([])
+  })
+
+  it('parses a single NDJSON line', () => {
+    const raw = ndjsonFixture.at(0) ?? ''
+    const entries = parseComposePsOutput(raw)
+
+    expect(entries).toHaveLength(1)
+    expect(entries[0]?.Name).toBe('fro-bot-gateway-1')
+  })
+
+  it('handles trailing newline correctly', () => {
+    const raw = `${ndjsonFixture.join('\n')}\n`
+    const entries = parseComposePsOutput(raw)
+
+    expect(entries).toHaveLength(3)
+  })
+
+  it('throws on a malformed NDJSON line', () => {
+    const raw = `${ndjsonFixture[0]}\nnot-valid-json\n${ndjsonFixture[2]}`
+
+    expect(() => parseComposePsOutput(raw)).toThrow()
+  })
+})
+
+// ─── getGatewayComposeStatus — NDJSON integration ────────────────────────────
+
+describe('getGatewayComposeStatus — NDJSON stdout', () => {
+  it('parses NDJSON docker compose ps output and returns correct services', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+
+    const ndjsonOutput = ndjsonFixture.join('\n')
+    const result = await getGatewayComposeStatus('gateway.example.com', makeSpawnOk(ndjsonOutput))
+
+    expect(result.ok).toBe(true)
+    expect(result.services).toHaveLength(3)
+    expect(result.services[0]).toEqual({service: 'fro-bot-gateway-1', state: 'running', health: 'healthy'})
+    expect(result.services[1]).toEqual({service: 'fro-bot-mitmproxy-1', state: 'running', health: 'healthy'})
+    expect(result.services[2]).toEqual({service: 'fro-bot-workspace-1', state: 'running', health: 'n-a'})
+  })
+
+  it('returns ok=false with error message when NDJSON contains a malformed line', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+
+    const badOutput = `${ndjsonFixture[0]}\nnot-valid-json`
+    const result = await getGatewayComposeStatus('gateway.example.com', makeSpawnOk(badOutput))
+
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain('Failed to parse docker compose ps output')
+  })
+})