@marcusrbrown/infra 0.8.1 → 0.9.1

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

package/src/commands/umami/index.ts

@@ -0,0 +1,13 @@
+import type {goke} from 'goke'
+
+import {registerUmamiDeploy} from './deploy'
+import {registerUmamiLogs} from './logs'
+import {registerUmamiStatus} from './status'
+
+export {getUmamiStatusSummary} from './status'
+
+export function registerUmamiCommands(cli: ReturnType<typeof goke>): void {
+  registerUmamiStatus(cli)
+  registerUmamiDeploy(cli)
+  registerUmamiLogs(cli)
+}

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

@@ -0,0 +1,154 @@
+import {afterEach, beforeEach, describe, expect, it} from 'bun:test'
+
+import {streamUmamiLogs, type LogsSpawnFn, type StreamLogsOpts} from './logs'
+
+// ─── streamUmamiLogs ─────────────────────────────────────────────────────────
+
+function makeLogsSpawn(exitCode = 0): LogsSpawnFn {
+  return (_cmd, _opts) => ({exited: Promise.resolve(exitCode)})
+}
+
+describe('logs command', () => {
+  let originalCI: string | undefined
+  let originalUmamiDomain: string | undefined
+
+  beforeEach(() => {
+    originalCI = process.env.CI
+    originalUmamiDomain = process.env.UMAMI_DOMAIN
+  })
+
+  afterEach(() => {
+    if (originalCI === undefined) {
+      delete process.env.CI
+    } else {
+      process.env.CI = originalCI
+    }
+
+    if (originalUmamiDomain === undefined) {
+      delete process.env.UMAMI_DOMAIN
+    } else {
+      process.env.UMAMI_DOMAIN = originalUmamiDomain
+    }
+  })
+
+  it('refuses to stream logs in CI without --allow-ci', async () => {
+    process.env.CI = 'true'
+
+    const opts: StreamLogsOpts = {
+      host: 'metrics.fro.bot',
+      service: 'umami',
+      tail: 100,
+      allowCi: false,
+    }
+
+    const messages: string[] = []
+    const result = await streamUmamiLogs(opts, makeLogsSpawn(), msg => messages.push(msg))
+
+    expect(result.refused).toBe(true)
+    expect(messages.join('')).toContain('Refusing to stream logs in CI')
+  })
+
+  it('proceeds in CI when --allow-ci is set', async () => {
+    process.env.CI = 'true'
+
+    const opts: StreamLogsOpts = {
+      host: 'metrics.fro.bot',
+      service: 'umami',
+      tail: 100,
+      allowCi: true,
+    }
+
+    const warnings: string[] = []
+    const result = await streamUmamiLogs(opts, makeLogsSpawn(), undefined, msg => warnings.push(msg))
+
+    expect(result.refused).toBe(false)
+    expect(result.exitCode).toBe(0)
+  })
+
+  it('always emits a sensitive-data warning to stderr', async () => {
+    delete process.env.CI
+
+    const opts: StreamLogsOpts = {
+      host: 'metrics.fro.bot',
+      service: 'umami',
+      tail: 100,
+      allowCi: false,
+    }
+
+    const warnings: string[] = []
+    await streamUmamiLogs(opts, makeLogsSpawn(), undefined, msg => warnings.push(msg))
+
+    expect(warnings.join('')).toContain('sensitive')
+  })
+
+  it('rejects invalid host before spawning SSH', async () => {
+    delete process.env.CI
+
+    const opts: StreamLogsOpts = {
+      host: '-oProxyCommand=evil',
+      service: 'umami',
+      tail: 100,
+      allowCi: false,
+    }
+
+    let spawnCalled = false
+    const spy: LogsSpawnFn = (_cmd, _opts) => {
+      spawnCalled = true
+      return {exited: Promise.resolve(0)}
+    }
+
+    await expect(streamUmamiLogs(opts, spy)).rejects.toThrow('Invalid UMAMI_DOMAIN')
+    expect(spawnCalled).toBe(false)
+  })
+
+  it('returns exitCode from the SSH subprocess', async () => {
+    delete process.env.CI
+
+    const opts: StreamLogsOpts = {
+      host: 'metrics.fro.bot',
+      service: 'umami',
+      tail: 50,
+      allowCi: false,
+    }
+
+    const result = await streamUmamiLogs(opts, makeLogsSpawn(42))
+
+    expect(result.refused).toBe(false)
+    expect(result.exitCode).toBe(42)
+  })
+
+  it('accepts caddy as a valid service', async () => {
+    delete process.env.CI
+
+    const opts: StreamLogsOpts = {
+      host: 'metrics.fro.bot',
+      service: 'caddy',
+      tail: 100,
+      allowCi: false,
+    }
+
+    const result = await streamUmamiLogs(opts, makeLogsSpawn(0))
+    expect(result.refused).toBe(false)
+    expect(result.exitCode).toBe(0)
+  })
+
+  it('rejects an unknown service when called directly (bypassing the CLI action)', async () => {
+    delete process.env.CI
+
+    const opts: StreamLogsOpts = {
+      host: 'metrics.fro.bot',
+      service: 'notaservice',
+      tail: 100,
+      allowCi: false,
+    }
+
+    let spawnCalled = false
+    const spy: LogsSpawnFn = (_cmd, _opts) => {
+      spawnCalled = true
+      return {exited: Promise.resolve(0)}
+    }
+
+    await expect(streamUmamiLogs(opts, spy)).rejects.toThrow(/Invalid service/)
+    expect(spawnCalled).toBe(false)
+  })
+})

package/src/commands/umami/logs.ts

@@ -0,0 +1,161 @@
+import type {goke} from 'goke'
+
+import {z} from 'zod'
+
+import {validateUmamiHost} from './host'
+
+declare const process: {
+  env: Record<string, string | undefined>
+  exitCode?: number
+  stderr: {write: (msg: string) => void}
+}
+
+const COMPOSE_PROJECT_DIR = '/opt/umami'
+const SENSITIVE_WARNING =
+  'Warning: Logs may contain database passwords, app secrets, or user data. Treat output as sensitive; do not capture in shared logs or chat.'
+
+export const VALID_SERVICES = ['umami', 'db', 'caddy'] as const
+
+export type ValidService = (typeof VALID_SERVICES)[number]
+
+// ─── Pure helpers ─────────────────────────────────────────────────────────────
+
+export function validateService(service: string): asserts service is ValidService {
+  if (!VALID_SERVICES.includes(service as ValidService)) {
+    throw new Error(`Invalid service "${service}". Valid services: ${VALID_SERVICES.join(', ')}`)
+  }
+}
+
+// ─── Injectable spawn type ────────────────────────────────────────────────────
+
+export type LogsSpawnFn = (
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'inherit'; stderr: 'inherit'},
+) => {
+  exited: Promise<number>
+}
+
+export interface StreamLogsOpts {
+  host: string
+  service: string
+  tail: number
+  allowCi: boolean
+}
+
+export interface StreamLogsResult {
+  refused: boolean
+  exitCode?: number
+}
+
+function defaultLogsSpawn(
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'inherit'; stderr: 'inherit'},
+): {exited: Promise<number>} {
+  return Bun.spawn(cmd, opts)
+}
+
+export async function streamUmamiLogs(
+  opts: StreamLogsOpts,
+  spawn: LogsSpawnFn = defaultLogsSpawn,
+  printOut?: (msg: string) => void,
+  printErr?: (msg: string) => void,
+): Promise<StreamLogsResult> {
+  // Validate service at the top so direct callers cannot bypass the guard.
+  validateService(opts.service)
+
+  const isCI = process.env.CI === 'true'
+
+  if (isCI && !opts.allowCi) {
+    const msg = 'Refusing to stream logs in CI without --allow-ci. Logs may contain sensitive credentials or user data.'
+    if (printOut) {
+      printOut(msg)
+    } else {
+      console.log(msg)
+    }
+
+    return {refused: true}
+  }
+
+  // Warn on every run — logs are sensitive regardless of context
+  if (printErr) {
+    printErr(SENSITIVE_WARNING)
+  } else {
+    console.error(SENSITIVE_WARNING)
+  }
+
+  validateUmamiHost(opts.host)
+
+  const sshCmd = [
+    'ssh',
+    '-o',
+    'BatchMode=yes',
+    '-o',
+    'StrictHostKeyChecking=yes',
+    `root@${opts.host}`,
+    `docker compose --project-directory ${COMPOSE_PROJECT_DIR} logs --no-color --tail=${opts.tail} ${opts.service}`,
+  ]
+
+  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} : {}),
+  }
+
+  const child = spawn(sshCmd, {env, stdout: 'inherit', stderr: 'inherit'})
+  const exitCode = await child.exited
+
+  return {refused: false, exitCode}
+}
+
+// ─── Command registration ─────────────────────────────────────────────────────
+
+export function registerUmamiLogs(cli: ReturnType<typeof goke>): void {
+  cli
+    .command('umami logs [service]', 'Stream logs from an Umami service via SSH and docker compose.')
+    .option('--tail [n]', z.number().default(100).describe('Number of log lines to tail from each service.'))
+    .option(
+      '--allow-ci',
+      z
+        .boolean()
+        .default(false)
+        .describe('Allow log streaming in CI environments. Logs may contain sensitive credentials.'),
+    )
+    .option(
+      '--key [key]',
+      z.string().describe('Environment variable name holding the SSH host. Falls back to UMAMI_DOMAIN when omitted.'),
+    )
+    .action(async (service, options) => {
+      const targetService = (service as string | undefined) ?? 'umami'
+
+      try {
+        validateService(targetService)
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error))
+        process.exitCode = 1
+        return
+      }
+
+      const hostEnvKey = options.key ?? 'UMAMI_DOMAIN'
+      const host = process.env[hostEnvKey]
+
+      if (!host) {
+        console.error('Umami host not set. Export UMAMI_DOMAIN or pass --key <env-name> pointing to a set variable.')
+        process.exitCode = 1
+        return
+      }
+
+      const tail = typeof options.tail === 'number' ? options.tail : 100
+      const allowCi = options.allowCi === true
+
+      const result = await streamUmamiLogs({host, service: targetService, tail, allowCi})
+
+      if (result.refused) {
+        process.exitCode = 1
+        return
+      }
+
+      if (result.exitCode !== 0) {
+        process.exitCode = result.exitCode ?? 1
+      }
+    })
+}