@marcusrbrown/infra 0.8.1 → 0.9.1

package/src/commands/cliproxy/status.ts

@@ -94,8 +94,34 @@ export async function checkHttpReachability(url: string, verbose: boolean): Prom
   }
 }
 
+/** Count records in a usage-queue array that look like errors/failures. Defensive: only counts when a recognizable field exists. */
+function countQueueErrors(records: unknown[]): number {
+  let count = 0
+  for (const record of records) {
+    if (record === null || typeof record !== 'object') {
+      continue
+    }
+
+    const rec = record as Record<string, unknown>
+
+    // Status field >= 400 indicates an HTTP-level error
+    const status = toNumber(rec.status)
+    if (status !== null && status >= 400) {
+      count++
+      continue
+    }
+
+    // Explicit error/failure markers
+    if (rec.error !== undefined || rec.failed === true || rec.failure === true) {
+      count++
+    }
+  }
+
+  return count
+}
+
 export async function checkUsageStats(baseUrl: string, key: string): Promise<CheckResult> {
-  const endpoint = `${baseUrl}/v0/management/usage`
+  const endpoint = `${baseUrl}/v0/management/usage-queue?count=50`
 
   try {
     const response = await fetch(endpoint, {
@@ -115,31 +141,35 @@ export async function checkUsageStats(baseUrl: string, key: string): Promise<Che
       return {
         title: 'Usage stats',
         level: 'error',
-        summary: `GET /v0/management/usage failed with HTTP ${response.status}`,
+        summary: `GET /v0/management/usage-queue failed with HTTP ${response.status}`,
       }
     }
 
     const payload = await parseJsonResponse(response)
-    const top = payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : {}
-    const usage = top.usage && typeof top.usage === 'object' ? (top.usage as Record<string, unknown>) : top
-    const totalRequests = toNumber(usage.total_requests)
-    const failureCount = toNumber(usage.failure_count)
 
-    if (totalRequests === null || failureCount === null) {
+    if (!Array.isArray(payload)) {
       return {
         title: 'Usage stats',
         level: 'warning',
-        summary: 'Management usage payload is missing expected numeric fields.',
+        summary: 'Usage-queue response was not an array — cannot parse recent activity.',
+      }
+    }
+
+    const total = payload.length
+    const errors = countQueueErrors(payload)
+
+    if (total === 0) {
+      return {
+        title: 'Usage stats',
+        level: 'ok',
+        summary: 'recent: 0 (idle)',
       }
     }
 
     return {
       title: 'Usage stats',
-      level: failureCount > 0 ? 'warning' : 'ok',
-      summary:
-        failureCount > 0
-          ? `total_requests=${totalRequests}, failure_count=${failureCount} (token refresh likely needed)`
-          : `total_requests=${totalRequests}, failure_count=${failureCount}`,
+      level: errors > 0 ? 'warning' : 'ok',
+      summary: errors > 0 ? `recent: ${total}, errors: ${errors}` : `recent: ${total}`,
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
@@ -196,6 +226,95 @@ export async function checkVersion(baseUrl: string, key: string): Promise<CheckR
   }
 }
 
+/**
+ * Probe the management API with a cheap auth check before issuing parallel calls.
+ * Returns null on success, or a CheckResult describing the auth failure.
+ * Never throws.
+ */
+async function probeManagementAuth(baseUrl: string, key: string): Promise<CheckResult | null> {
+  const endpoint = `${baseUrl}/v0/management/config`
+
+  try {
+    const response = await fetch(endpoint, {
+      headers: managementHeaders(key),
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    })
+
+    if (response.ok) {
+      return null
+    }
+
+    if (response.status === 403) {
+      // Could be an IP ban — inspect body for ban-ish markers
+      const payload = await parseJsonResponse(response)
+      const isBanBody =
+        payload !== null &&
+        typeof payload === 'object' &&
+        Object.values(payload as Record<string, unknown>).some(
+          v => typeof v === 'string' && /\b(?:ip[- ]?)?bann?ed\b/i.test(v),
+        )
+
+      if (isBanBody) {
+        return {
+          title: 'Management access',
+          level: 'error',
+          summary: 'IP banned — stop retrying for ~30 min. Management checks skipped.',
+        }
+      }
+
+      return {
+        title: 'Management access',
+        level: 'error',
+        summary: 'Management API returned HTTP 403. Management checks skipped.',
+      }
+    }
+
+    if (response.status === 401) {
+      return {
+        title: 'Management access',
+        level: 'error',
+        summary: 'Management API returned HTTP 401 (invalid key). Management checks skipped.',
+      }
+    }
+
+    return {
+      title: 'Management access',
+      level: 'warning',
+      summary: `Management auth probe returned HTTP ${response.status}. Management checks skipped.`,
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      title: 'Management access',
+      level: 'error',
+      summary: `Management auth probe failed: ${message}`,
+    }
+  }
+}
+
+type ManagementChecks =
+  | {kind: 'no-key'}
+  | {kind: 'auth-failure'; result: CheckResult}
+  | {kind: 'checks'; usage: CheckResult; version: CheckResult}
+
+/**
+ * Run management checks with single probe + parallel data fetches.
+ * Returns a discriminated union so callers handle no-key, auth-failure, and success distinctly.
+ */
+async function runManagementChecks(baseUrl: string, key: string | undefined): Promise<ManagementChecks> {
+  if (!key) {
+    return {kind: 'no-key'}
+  }
+
+  const authFailure = await probeManagementAuth(baseUrl, key)
+  if (authFailure !== null) {
+    return {kind: 'auth-failure', result: authFailure}
+  }
+
+  const [usage, version] = await Promise.all([checkUsageStats(baseUrl, key), checkVersion(baseUrl, key)])
+  return {kind: 'checks', usage, version}
+}
+
 function printCheckResult(result: CheckResult, ctx: ActionCtx): void {
   ctx.console.log(`[${levelLabel(result.level)}] ${result.title}`)
   ctx.console.log(`  ${result.summary}`)
@@ -212,37 +331,46 @@ function formatCheckSummary(result: CheckResult): string {
 }
 
 export function formatUsageSummaryLine(result: CheckResult): string | null {
-  const totalMatch = /total_requests=(\d+)/.exec(result.summary)
-  const failureMatch = /failure_count=(\d+)/.exec(result.summary)
-
-  if (!totalMatch || !failureMatch) {
+  // v7 recent-window format: "recent: N" or "recent: N, errors: M"
+  const recentMatch = /recent:\s*(\d+)/.exec(result.summary)
+  if (!recentMatch) {
     return null
   }
-
-  const total = Number(totalMatch[1])
-  const failed = Number(failureMatch[1])
-  const failureRate = total === 0 ? 0 : (failed / total) * 100
-
-  return `Requests: ${total} total, ${failed} failed (${failureRate.toFixed(1)}% failure rate)`
+  const total = Number(recentMatch[1])
+  const errorMatch = /errors:\s*(\d+)/.exec(result.summary)
+  const errors = errorMatch ? Number(errorMatch[1]) : 0
+  return `Recent requests: ${total}${errors > 0 ? `, ${errors} errors` : ''}`
 }
 
 export async function getCliproxyStatusSummary(baseUrl: string, key: string, verbose: boolean): Promise<StatusSummary> {
   const normalizedBaseUrl = stripTrailingSlash(baseUrl)
-  const httpPromise = checkHttpReachability(normalizedBaseUrl, verbose)
-  const managementResultsPromise = key
-    ? Promise.all([checkUsageStats(normalizedBaseUrl, key), checkVersion(normalizedBaseUrl, key)])
-    : Promise.resolve(null)
-
-  const [httpResult, managementResults] = await Promise.all([httpPromise, managementResultsPromise])
-  const [usageResult, versionResult] = managementResults ?? [null, null]
+  const [httpResult, mgmt] = await Promise.all([
+    checkHttpReachability(`${normalizedBaseUrl}/healthz`, verbose),
+    runManagementChecks(normalizedBaseUrl, key || undefined),
+  ])
+
+  let version: string
+  let usageStats: string
+
+  if (mgmt.kind === 'no-key') {
+    version = '— (no key)'
+    usageStats = '— (no key)'
+  } else if (mgmt.kind === 'auth-failure') {
+    const authSummary = formatCheckSummary(mgmt.result)
+    version = authSummary
+    usageStats = authSummary
+  } else {
+    version = formatCheckSummary(mgmt.version)
+    usageStats = formatCheckSummary(mgmt.usage)
+  }
 
   return {
     app: 'cliproxy',
     http: formatCheckSummary(httpResult),
     lastDeploy: '—',
-    version: versionResult ? formatCheckSummary(versionResult) : '— (no key)',
+    version,
     contentHash: '—',
-    usageStats: usageResult ? formatCheckSummary(usageResult) : '— (no key)',
+    usageStats,
   }
 }
 
@@ -262,25 +390,24 @@ export async function cliproxyStatusAction(options: StatusOptions, ctx: ActionCt
     ctx.console.log('CLIProxyAPI status')
     ctx.console.log('')
 
-    const results: CheckResult[] = [await checkHttpReachability(baseUrl, verbose)]
+    const results: CheckResult[] = [await checkHttpReachability(`${baseUrl}/healthz`, verbose)]
 
     let capturedUsageResult: CheckResult | undefined
 
-    if (managementKey) {
-      const [usageResult, versionResult] = await Promise.all([
-        checkUsageStats(baseUrl, managementKey),
-        checkVersion(baseUrl, managementKey),
-      ])
+    const mgmt = await runManagementChecks(baseUrl, managementKey)
 
-      capturedUsageResult = usageResult
-      results.push(usageResult, versionResult)
-    } else {
+    if (mgmt.kind === 'no-key') {
       results.push({
         title: 'Management checks',
         level: 'warning',
         summary:
           'CLIPROXY_MANAGEMENT_KEY is not set. Skipping usage stats and version checks. Provide --key or set env var.',
       })
+    } else if (mgmt.kind === 'auth-failure') {
+      results.push(mgmt.result)
+    } else {
+      capturedUsageResult = mgmt.usage
+      results.push(mgmt.usage, mgmt.version)
     }
 
     for (const result of results) {

package/src/commands/mcp.test.ts

@@ -37,6 +37,7 @@ import {registerGatewayCommands} from './gateway'
 import {registerKeewebCommands} from './keeweb'
 import {MCP_ALLOWLIST, registerMcp} from './mcp'
 import {registerStatus} from './status'
+import {registerUmamiCommands} from './umami'
 
 // ─── Tool name constants ──────────────────────────────────────────────────────
 
@@ -54,6 +55,8 @@ const CLI_ONLY_TOOLS = [
   'gateway_restore',
   'keeweb_deploy',
   'keeweb_open',
+  'umami_deploy',
+  'umami_logs',
 ].sort()
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -64,6 +67,7 @@ function buildTestCli(): ReturnType<typeof goke> {
   registerKeewebCommands(cli)
   registerCliproxyCommands(cli)
   registerGatewayCommands(cli)
+  registerUmamiCommands(cli)
   registerStatus(cli)
   registerMcp(cli)
   return cli
@@ -105,7 +109,7 @@ describe('mcp integration (Tier-1, in-process)', () => {
 
   // ── tools/list assertions ──────────────────────────────────────────────────
 
-  test('tools/list returns exactly the 10 allowlist tool names', async () => {
+  test('tools/list returns exactly the 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)
@@ -146,12 +150,6 @@ describe('mcp integration (Tier-1, in-process)', () => {
   // 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

package/src/commands/mcp.ts

@@ -13,6 +13,8 @@ import {createMcpAction} from '@goke/mcp'
  * - `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)
+ * - `umami deploy`     — intentionally CLI-only: mutates live deployment and requires environment approval
+ * - `umami logs`       — intentionally CLI-only: streams logs that may emit sensitive data (DB passwords, app secrets)
  */
 export const MCP_ALLOWLIST: ReadonlySet<string> = new Set([
   'gateway status',
@@ -24,6 +26,7 @@ export const MCP_ALLOWLIST: ReadonlySet<string> = new Set([
   'cliproxy config get',
   'cliproxy config set',
   'keeweb status',
+  'umami status',
   'status',
 ])
 

package/src/commands/status.test.ts

@@ -31,11 +31,21 @@ const healthyGateway: StatusSummary = {
   usageStats: '—',
 }
 
+const healthyUmami: StatusSummary = {
+  app: 'umami',
+  http: 'OK: umami:running/healthy',
+  lastDeploy: '—',
+  version: '—',
+  contentHash: '—',
+  usageStats: '—',
+}
+
 function makeDeps(overrides?: Partial<Parameters<typeof registerStatus>[1]>): Parameters<typeof registerStatus>[1] {
   return {
     getKeewebStatusSummary: async () => healthyKeeweb,
     getCliproxyStatusSummary: async () => healthyCliproxy,
     getGatewayStatusSummary: async () => healthyGateway,
+    getUmamiStatusSummary: async () => healthyUmami,
     ...overrides,
   }
 }
@@ -52,6 +62,30 @@ describe('top-level status command (Tier-2 ctx capture)', () => {
     expect(expectCapturedToInclude(captured, '| keeweb | OK | 2026-04-12 10:00 | — | match | — |')).toBe(true)
     expect(expectCapturedToInclude(captured, '| cliproxy | OK | — | v1.2.3 | — | 12 req / 0 fail |')).toBe(true)
     expect(expectCapturedToInclude(captured, '| gateway | OK: gateway:running/healthy | — | — | — | — |')).toBe(true)
+    expect(expectCapturedToInclude(captured, '| umami | OK: umami:running/healthy | — | — | — | — |')).toBe(true)
+  })
+
+  it('shows an error row when umami is unreachable and keeps the other results', async () => {
+    const {ctx, captured} = createCapturedCtx()
+
+    await unifiedStatusAction(
+      {},
+      ctx,
+      makeDeps({
+        getUmamiStatusSummary: async () => {
+          throw new Error('UMAMI_DOMAIN not set')
+        },
+      }),
+    )
+
+    expect(
+      expectCapturedToInclude(
+        captured,
+        '| umami | ❌ UMAMI_DOMAIN not set | ❌ UMAMI_DOMAIN not set | ❌ UMAMI_DOMAIN not set | ❌ UMAMI_DOMAIN not set | ❌ UMAMI_DOMAIN not set |',
+      ),
+    ).toBe(true)
+    expect(expectCapturedToInclude(captured, '| gateway | OK: gateway:running/healthy | — | — | — | — |')).toBe(true)
+    expect(captured.stderr.join('')).toContain('umami status check failed: UMAMI_DOMAIN not set')
   })
 
   it('shows an error row when one app fails and keeps the other results', async () => {
@@ -92,11 +126,13 @@ describe('top-level status command (Tier-2 ctx capture)', () => {
       keeweb: {http: string}
       cliproxy: {version: string}
       gateway: {http: string}
+      umami: {http: string}
     }
 
     expect(parsed.keeweb.http).toBe('OK')
     expect(parsed.cliproxy.version).toBe('v1.2.3')
     expect(parsed.gateway.http).toBe('OK: gateway:running/healthy')
+    expect(parsed.umami.http).toBe('OK: umami:running/healthy')
   })
 
   it('does not write to global console (output is captured via ctx)', async () => {

package/src/commands/status.ts

@@ -7,13 +7,14 @@ import {z} from 'zod'
 import {getCliproxyStatusSummary} from './cliproxy/status'
 import {getGatewayStatusSummary} from './gateway'
 import {getKeewebStatusSummary} from './keeweb/status'
+import {getUmamiStatusSummary} from './umami'
 
 declare const process: {
   env: Record<string, string | undefined>
 }
 
 export interface StatusSummary {
-  app: 'keeweb' | 'cliproxy' | 'gateway'
+  app: 'keeweb' | 'cliproxy' | 'gateway' | 'umami'
   http: string
   lastDeploy: string
   version: string
@@ -27,6 +28,7 @@ interface StatusDependencies {
   getKeewebStatusSummary: (verbose: boolean) => Promise<StatusSummary>
   getCliproxyStatusSummary: (baseUrl: string, key: string, verbose: boolean) => Promise<StatusSummary>
   getGatewayStatusSummary: (host: string) => Promise<StatusSummary>
+  getUmamiStatusSummary: (host: string) => Promise<StatusSummary>
 }
 
 const DEFAULT_CLIPROXY_URL = 'https://cliproxy.fro.bot'
@@ -63,6 +65,7 @@ function toJsonPayload(rows: StatusSummary[]): Record<AppName, StatusSummary> {
     keeweb: rows.find(row => row.app === 'keeweb') ?? errorSummary('keeweb', 'missing result'),
     cliproxy: rows.find(row => row.app === 'cliproxy') ?? errorSummary('cliproxy', 'missing result'),
     gateway: rows.find(row => row.app === 'gateway') ?? errorSummary('gateway', 'missing result'),
+    umami: rows.find(row => row.app === 'umami') ?? errorSummary('umami', 'missing result'),
   }
 }
 
@@ -78,20 +81,23 @@ export async function unifiedStatusAction(
     getKeewebStatusSummary,
     getCliproxyStatusSummary,
     getGatewayStatusSummary,
+    getUmamiStatusSummary,
   },
 ): Promise<void> {
   const verbose = options.verbose === true
   const cliproxyBaseUrl = stripTrailingSlash(process.env.CLIPROXY_URL ?? DEFAULT_CLIPROXY_URL)
   const cliproxyKey = process.env.CLIPROXY_MANAGEMENT_KEY ?? ''
   const gatewayHost = process.env.GATEWAY_HOST ?? ''
+  const umamiHost = process.env.UMAMI_DOMAIN ?? ''
 
   const results = await Promise.allSettled([
     dependencies.getKeewebStatusSummary(verbose),
     dependencies.getCliproxyStatusSummary(cliproxyBaseUrl, cliproxyKey, verbose),
     dependencies.getGatewayStatusSummary(gatewayHost),
+    dependencies.getUmamiStatusSummary(umamiHost),
   ])
 
-  const appNames: AppName[] = ['keeweb', 'cliproxy', 'gateway']
+  const appNames: AppName[] = ['keeweb', 'cliproxy', 'gateway', 'umami']
   const rows: StatusSummary[] = results.map((result, index) => {
     const app = appNames[index] ?? 'keeweb'
     if (result.status === 'fulfilled') {
@@ -120,13 +126,14 @@ export function registerStatus(
     getKeewebStatusSummary,
     getCliproxyStatusSummary,
     getGatewayStatusSummary,
+    getUmamiStatusSummary,
   },
 ): void {
   cli
     .command('status', 'Show status of all deployments')
     .option(
       '--json',
-      z.boolean().describe('Output machine-readable JSON with keeweb, cliproxy, and gateway summary objects.'),
+      z.boolean().describe('Output machine-readable JSON with keeweb, cliproxy, gateway, and umami summary objects.'),
     )
     .option(
       '--verbose',

package/src/commands/umami/deploy.test.ts

@@ -0,0 +1,202 @@
+import {resolve} from 'node:path'
+import {afterEach, beforeEach, describe, expect, it} from 'bun:test'
+
+import {getUmamiDeployEnv, validateUmamiRemotePreconditions} from './deploy'
+
+const repoRoot = resolve(import.meta.dir, '../../../../..')
+
+const envKeys = [
+  'HOME',
+  'PATH',
+  'SSH_AUTH_SOCK',
+  'UMAMI_DOMAIN',
+  'UMAMI_APP_SECRET',
+  'UMAMI_DB_PASSWORD',
+  'UMAMI_ADMIN_PASSWORD',
+  'UMAMI_SSH_KEY',
+] as const
+
+type ManagedEnvKey = (typeof envKeys)[number]
+
+let originalEnv: Partial<Record<ManagedEnvKey, string | undefined>>
+
+function restoreManagedEnv(): void {
+  for (const key of envKeys) {
+    const value = originalEnv[key]
+    if (value === undefined) {
+      delete process.env[key]
+    } else {
+      process.env[key] = value
+    }
+  }
+}
+
+function setManagedEnv(overrides: Partial<Record<ManagedEnvKey, string | undefined>>): void {
+  restoreManagedEnv()
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) {
+      delete process.env[key as ManagedEnvKey]
+    } else {
+      process.env[key as ManagedEnvKey] = value
+    }
+  }
+}
+
+beforeEach(() => {
+  originalEnv = {}
+  for (const key of envKeys) {
+    originalEnv[key] = process.env[key]
+  }
+})
+
+afterEach(() => {
+  restoreManagedEnv()
+})
+
+// ─── getUmamiDeployEnv ────────────────────────────────────────────────────────
+
+describe('getUmamiDeployEnv', () => {
+  it('returns env object with required keys when all are set', () => {
+    setManagedEnv({
+      PATH: '/usr/bin:/bin',
+      HOME: '/home/user',
+      SSH_AUTH_SOCK: '/tmp/ssh-agent.sock',
+      UMAMI_DOMAIN: 'metrics.fro.bot',
+    })
+
+    const env = getUmamiDeployEnv()
+
+    expect(env.PATH).toBe('/usr/bin:/bin')
+    expect(env.HOME).toBe('/home/user')
+    expect(env.SSH_AUTH_SOCK).toBe('/tmp/ssh-agent.sock')
+    expect(env.UMAMI_DOMAIN).toBe('metrics.fro.bot')
+  })
+
+  it('throws when PATH is missing', () => {
+    setManagedEnv({PATH: undefined, HOME: '/home/user', SSH_AUTH_SOCK: '/tmp/ssh-agent.sock'})
+
+    expect(() => getUmamiDeployEnv()).toThrow('PATH is required')
+  })
+
+  it('throws when HOME is missing', () => {
+    setManagedEnv({PATH: '/usr/bin:/bin', HOME: undefined, SSH_AUTH_SOCK: '/tmp/ssh-agent.sock'})
+
+    expect(() => getUmamiDeployEnv()).toThrow('HOME is required')
+  })
+
+  it('throws when SSH_AUTH_SOCK is missing and no UMAMI_SSH_KEY either', () => {
+    setManagedEnv({
+      PATH: '/usr/bin:/bin',
+      HOME: '/home/user',
+      SSH_AUTH_SOCK: undefined,
+      UMAMI_SSH_KEY: undefined,
+    })
+
+    expect(() => getUmamiDeployEnv()).toThrow('Local deploy needs an SSH context')
+  })
+
+  it('succeeds with only SSH_AUTH_SOCK set (no UMAMI_SSH_KEY)', () => {
+    setManagedEnv({
+      PATH: '/usr/bin:/bin',
+      HOME: '/home/user',
+      SSH_AUTH_SOCK: '/tmp/ssh-agent.sock',
+      UMAMI_SSH_KEY: undefined,
+    })
+
+    const env = getUmamiDeployEnv()
+
+    expect(env.SSH_AUTH_SOCK).toBe('/tmp/ssh-agent.sock')
+    expect('UMAMI_SSH_KEY' in env).toBe(false)
+  })
+
+  it('succeeds with only UMAMI_SSH_KEY set (no SSH_AUTH_SOCK) and includes the key in env', () => {
+    setManagedEnv({
+      PATH: '/usr/bin:/bin',
+      HOME: '/home/user',
+      SSH_AUTH_SOCK: undefined,
+      UMAMI_SSH_KEY: 'ssh-ed25519 AAAA...',
+    })
+
+    const env = getUmamiDeployEnv()
+
+    expect(env.UMAMI_SSH_KEY).toBe('ssh-ed25519 AAAA...')
+    expect('SSH_AUTH_SOCK' in env).toBe(false)
+  })
+
+  it('includes optional umami env vars when set', () => {
+    setManagedEnv({
+      PATH: '/usr/bin:/bin',
+      HOME: '/home/user',
+      SSH_AUTH_SOCK: '/tmp/ssh-agent.sock',
+      UMAMI_APP_SECRET: 'secret123',
+      UMAMI_DB_PASSWORD: 'dbpass',
+      UMAMI_ADMIN_PASSWORD: 'adminpass',
+    })
+
+    const env = getUmamiDeployEnv()
+
+    expect(env.UMAMI_APP_SECRET).toBe('secret123')
+    expect(env.UMAMI_DB_PASSWORD).toBe('dbpass')
+    expect(env.UMAMI_ADMIN_PASSWORD).toBe('adminpass')
+  })
+})
+
+// ─── validateUmamiRemotePreconditions ─────────────────────────────────────────
+
+describe('validateUmamiRemotePreconditions', () => {
+  it('throws a clear error when gh is not available', () => {
+    // We cannot reliably mock Bun.which, so we test the function contract:
+    // if gh is not installed, it should throw with a helpful message.
+    // This test verifies the error message shape by calling with a known-missing binary.
+    // In CI where gh IS installed, we skip this test.
+    if (Bun.which('gh')) {
+      // gh is available — just verify the function does not throw
+      expect(() => validateUmamiRemotePreconditions()).not.toThrow()
+      return
+    }
+
+    expect(() => validateUmamiRemotePreconditions()).toThrow('gh CLI is required')
+  })
+})
+
+// ─── deploy command (subprocess integration via CLI) ─────────────────────────
+
+describe('deploy command', () => {
+  it('dry-run remote mode prints planned gh workflow run command without executing', async () => {
+    const proc = Bun.spawn(['bun', 'run', 'packages/cli/src/cli.ts', 'umami', 'deploy', '--dry-run'], {
+      cwd: repoRoot,
+      env: {...process.env, NO_COLOR: '1'},
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+
+    const [stdout, _stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+
+    expect(exitCode).toBe(0)
+    expect(stdout).toContain('Dry run')
+    expect(stdout).toContain('Deploy Umami')
+  })
+
+  it('dry-run local mode prints planned bun command without executing', async () => {
+    const proc = Bun.spawn(['bun', 'run', 'packages/cli/src/cli.ts', 'umami', 'deploy', '--local', '--dry-run'], {
+      cwd: repoRoot,
+      env: {...process.env, NO_COLOR: '1'},
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+
+    const [stdout, _stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+
+    expect(exitCode).toBe(0)
+    expect(stdout).toContain('Dry run')
+    expect(stdout).toContain('apps/umami')
+  })
+})