@marcusrbrown/infra 0.8.1 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcusrbrown/infra",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Infrastructure management CLI — deploy automation, health checks, and MCP bridge",
   "keywords": [
     "infra",

package/src/__snapshots__/cli.test.ts.snap

@@ -125,9 +125,27 @@ Commands:
     --include-ca                       Restore the mitmproxy CA certificate and private key. Currently the only supported restore target. (default: true)
 
 
+  umami status                         Show operational health of the Umami analytics deployment via docker compose ps.
+
+    --key [key]                        Environment variable name holding the SSH host. Falls back to UMAMI_DOMAIN when omitted.
+
+
+  umami deploy                         Deploy Umami analytics. Default mode triggers the GitHub Deploy Umami workflow, while --local runs apps/umami deploy directly with Bun.
+
+    --local                            Run local deployment with Bun using apps/umami instead of triggering GitHub Actions. (default: false)
+    --dry-run                          Validate deploy prerequisites and print planned actions without executing local deploy or dispatching workflow. (default: false)
+
+
+  umami logs [service]                 Stream logs from an Umami service via SSH and docker compose.
+
+    --tail [n]                         Number of log lines to tail from each service. (default: 100)
+    --allow-ci                         Allow log streaming in CI environments. Logs may contain sensitive credentials. (default: false)
+    --key [key]                        Environment variable name holding the SSH host. Falls back to UMAMI_DOMAIN when omitted.
+
+
   status                               Show status of all deployments
 
-    --json                             Output machine-readable JSON with keeweb, cliproxy, and gateway summary objects.
+    --json                             Output machine-readable JSON with keeweb, cliproxy, gateway, and umami summary objects.
     --verbose                          Include verbose per-app health check details when building the summary rows.
 
 

package/src/cli.ts

@@ -7,6 +7,7 @@ import {registerGatewayCommands} from './commands/gateway'
 import {registerKeewebCommands} from './commands/keeweb'
 import {registerMcp} from './commands/mcp'
 import {registerStatus} from './commands/status'
+import {registerUmamiCommands} from './commands/umami'
 
 declare const process: {
   argv: string[]
@@ -20,6 +21,7 @@ cli.option('--verbose', 'Enable verbose output for all commands')
 registerKeewebCommands(cli)
 registerCliproxyCommands(cli)
 registerGatewayCommands(cli)
+registerUmamiCommands(cli)
 registerStatus(cli)
 registerMcp(cli)
 

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)

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')
+  })
+})

package/src/commands/umami/deploy.ts

@@ -0,0 +1,132 @@
+import type {goke} from 'goke'
+
+import {z} from 'zod'
+
+declare const process: {
+  env: Record<string, string | undefined>
+  exitCode?: number
+}
+
+const REPO = 'marcusrbrown/infra'
+const WORKFLOW_NAME = 'Deploy Umami'
+const WORKFLOW_URL = 'https://github.com/marcusrbrown/infra/actions/workflows/deploy-umami.yaml'
+
+type CliInstance = ReturnType<typeof goke>
+
+// ─── Env helpers ─────────────────────────────────────────────────────────────
+
+export function getUmamiDeployEnv(): Record<string, string> {
+  const path = process.env.PATH
+  const home = process.env.HOME
+  const sshAuthSock = process.env.SSH_AUTH_SOCK
+  const sshKey = process.env.UMAMI_SSH_KEY
+
+  if (!path) {
+    throw new Error('PATH is required for local deploy')
+  }
+
+  if (!home) {
+    throw new Error('HOME is required for local deploy')
+  }
+
+  if (!sshAuthSock && !sshKey) {
+    throw new Error('Local deploy needs an SSH context: set SSH_AUTH_SOCK (ssh-agent) or UMAMI_SSH_KEY (key from env).')
+  }
+
+  return {
+    PATH: path,
+    HOME: home,
+    ...(sshAuthSock ? {SSH_AUTH_SOCK: sshAuthSock} : {}),
+    UMAMI_DOMAIN: process.env.UMAMI_DOMAIN ?? '',
+    UMAMI_APP_SECRET: process.env.UMAMI_APP_SECRET ?? '',
+    UMAMI_DB_PASSWORD: process.env.UMAMI_DB_PASSWORD ?? '',
+    UMAMI_ADMIN_PASSWORD: process.env.UMAMI_ADMIN_PASSWORD ?? '',
+    ...(sshKey ? {UMAMI_SSH_KEY: sshKey} : {}),
+  }
+}
+
+export function validateUmamiRemotePreconditions(): void {
+  if (!Bun.which('gh')) {
+    throw new Error('gh CLI is required for remote deploy. Install gh and run `gh auth login`.')
+  }
+}
+
+// ─── Command registration ─────────────────────────────────────────────────────
+
+export function registerUmamiDeploy(cli: CliInstance): void {
+  cli
+    .command(
+      'umami deploy',
+      'Deploy Umami analytics. Default mode triggers the GitHub Deploy Umami workflow, while --local runs apps/umami deploy directly with Bun.',
+    )
+    .option(
+      '--local',
+      z
+        .boolean()
+        .default(false)
+        .describe('Run local deployment with Bun using apps/umami instead of triggering GitHub Actions.'),
+    )
+    .option(
+      '--dry-run',
+      z
+        .boolean()
+        .default(false)
+        .describe(
+          'Validate deploy prerequisites and print planned actions without executing local deploy or dispatching workflow.',
+        ),
+    )
+    .example('# Trigger remote GitHub Actions deploy (default mode)')
+    .example('infra umami deploy')
+    .example('# Validate local deploy preconditions and planned command')
+    .example('infra umami deploy --local --dry-run')
+    .example('# Run local deploy with explicit SSH agent context')
+    .example('infra umami deploy --local')
+    .action(async options => {
+      if (options.local) {
+        const command = ['bun', 'run', '--cwd', 'apps/umami', 'deploy']
+
+        if (options.dryRun) {
+          console.log('Dry run: local umami deploy')
+          console.log(`- command: ${command.join(' ')}`)
+          return
+        }
+
+        const env = getUmamiDeployEnv()
+
+        const child = Bun.spawn(command, {
+          env,
+          stdout: 'inherit',
+          stderr: 'inherit',
+        })
+
+        const exitCode = await child.exited
+        if (exitCode !== 0) {
+          throw new Error(`Local deploy failed with exit code ${exitCode}`)
+        }
+
+        return
+      }
+
+      validateUmamiRemotePreconditions()
+
+      if (options.dryRun) {
+        console.log('Dry run: remote umami deploy')
+        console.log(`- command: gh workflow run "${WORKFLOW_NAME}" --repo ${REPO}`)
+        console.log(`- workflow URL: ${WORKFLOW_URL}`)
+        return
+      }
+
+      const child = Bun.spawn(['gh', 'workflow', 'run', WORKFLOW_NAME, '--repo', REPO], {
+        stdout: 'inherit',
+        stderr: 'inherit',
+      })
+
+      const exitCode = await child.exited
+      if (exitCode !== 0) {
+        throw new Error(`Failed to trigger "${WORKFLOW_NAME}" workflow (exit code ${exitCode})`)
+      }
+
+      console.log(`Workflow triggered: ${WORKFLOW_URL}`)
+      console.log('Approve the umami environment deployment in GitHub Actions to continue.')
+    })
+}

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

@@ -0,0 +1,62 @@
+import {describe, expect, it} from 'bun:test'
+
+import {validateUmamiHost} from './host'
+
+describe('validateUmamiHost', () => {
+  it('accepts a standard FQDN', () => {
+    expect(() => validateUmamiHost('metrics.fro.bot')).not.toThrow()
+    expect(validateUmamiHost('metrics.fro.bot')).toBe('metrics.fro.bot')
+  })
+
+  it('accepts localhost', () => {
+    expect(() => validateUmamiHost('localhost')).not.toThrow()
+  })
+
+  it('accepts an IPv4 address', () => {
+    expect(() => validateUmamiHost('147.182.133.210')).not.toThrow()
+  })
+
+  it('accepts a single-character hostname', () => {
+    expect(() => validateUmamiHost('a')).not.toThrow()
+  })
+
+  it('accepts a hostname with hyphens', () => {
+    expect(() => validateUmamiHost('my-metrics.prod.example.com')).not.toThrow()
+  })
+
+  it('rejects a leading-hyphen value (ProxyCommand injection vector)', () => {
+    expect(() => validateUmamiHost('-oProxyCommand=evil')).toThrow('Invalid UMAMI_DOMAIN')
+  })
+
+  it('rejects a value with shell metacharacters (semicolon)', () => {
+    expect(() => validateUmamiHost('metrics.fro.bot;rm -rf')).toThrow('Invalid UMAMI_DOMAIN')
+  })
+
+  it('rejects a value with shell metacharacters (backtick)', () => {
+    expect(() => validateUmamiHost('metrics.fro.bot`id`')).toThrow('Invalid UMAMI_DOMAIN')
+  })
+
+  it('rejects a value with spaces', () => {
+    expect(() => validateUmamiHost('metrics fro.bot')).toThrow('Invalid UMAMI_DOMAIN')
+  })
+
+  it('rejects a value with an at-sign', () => {
+    expect(() => validateUmamiHost('user@metrics.fro.bot')).toThrow('Invalid UMAMI_DOMAIN')
+  })
+
+  it('rejects an empty string', () => {
+    expect(() => validateUmamiHost('')).toThrow('Invalid UMAMI_DOMAIN')
+  })
+
+  it('truncates the invalid value in the error message to ~30 chars', () => {
+    const longMalicious = `-oProxyCommand=${'A'.repeat(100)}`
+    let message = ''
+    try {
+      validateUmamiHost(longMalicious)
+    } catch (error) {
+      message = error instanceof Error ? error.message : String(error)
+    }
+    expect(message).toContain('Invalid UMAMI_DOMAIN')
+    expect(message.length).toBeLessThan(longMalicious.length + 50)
+  })
+})

package/src/commands/umami/host.ts

@@ -0,0 +1,31 @@
+// ─── Umami host validation ────────────────────────────────────────────────────
+//
+// Validates UMAMI_DOMAIN values before they are passed as ssh argv arguments.
+// A value starting with `-` would be interpreted by ssh as an option flag,
+// enabling ProxyCommand injection and local code execution.
+
+const VALID_HOST_RE = /^[a-z\d][a-z\d.\-]*$/i
+
+/**
+ * Validates a candidate UMAMI_DOMAIN value against a strict hostname allowlist.
+ *
+ * Accepts: hostnames, FQDNs, IPv4 addresses, `localhost`.
+ * Rejects: empty strings, values starting with `-`, and anything containing
+ * characters outside `[A-Za-z0-9.-]`.
+ *
+ * @throws {Error} with a sanitized excerpt of the invalid value.
+ * @returns The validated host string (unchanged).
+ */
+export function validateUmamiHost(host: string): string {
+  if (!host) {
+    throw new Error('Invalid UMAMI_DOMAIN: value is empty')
+  }
+
+  if (!VALID_HOST_RE.test(host)) {
+    // Truncate to 30 chars and strip non-printable bytes before echoing back
+    const excerpt = host.slice(0, 30).replaceAll(/[^\u0020-\u007E]/g, '?')
+    throw new Error(`Invalid UMAMI_DOMAIN: "${excerpt}" — must match ${String.raw`[A-Za-z0-9][A-Za-z0-9.\-]*`}`)
+  }
+
+  return host
+}