@marcusrbrown/infra 0.11.4 → 0.12.1

package/package.json

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

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

@@ -150,6 +150,24 @@ Commands:
     --key [key]                        Environment variable name holding the SSH host. Falls back to UMAMI_DOMAIN when omitted.
 
 
+  dashboard status                     Show operational health of the dashboard deployment via docker compose ps.
+
+    --key [key]                        Environment variable name holding the SSH host. Falls back to DASHBOARD_DOMAIN when omitted.
+
+
+  dashboard deploy                     Deploy the dashboard. Default mode triggers the GitHub Deploy Dashboard workflow, while --local runs apps/dashboard deploy directly with Bun.
+
+    --local                            Run local deployment with Bun using apps/dashboard 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)
+
+
+  dashboard logs [service]             Stream logs from a dashboard 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 DASHBOARD_DOMAIN when omitted.
+
+
   vpn status                           Show operational health of the VPN box via SSH and wg show.
 
     --key [key]                        Environment variable name holding the SSH host. Falls back to VPN_HOST when omitted.
@@ -185,7 +203,7 @@ Commands:
 
   status                               Show status of all deployments
 
-    --json                             Output machine-readable JSON with keeweb, cliproxy, gateway, umami, and vpn summary objects.
+    --json                             Output machine-readable JSON with keeweb, cliproxy, gateway, umami, dashboard, and vpn summary objects.
     --verbose                          Include verbose per-app health check details when building the summary rows.
 
 

package/src/cli.ts

@@ -3,6 +3,7 @@
 import {goke} from 'goke'
 import pkg from '../package.json' with {type: 'json'}
 import {registerCliproxyCommands} from './commands/cliproxy'
+import {registerDashboardCommands} from './commands/dashboard'
 import {registerGatewayCommands} from './commands/gateway'
 import {registerKeewebCommands} from './commands/keeweb'
 import {registerMcp} from './commands/mcp'
@@ -23,6 +24,7 @@ registerKeewebCommands(cli)
 registerCliproxyCommands(cli)
 registerGatewayCommands(cli)
 registerUmamiCommands(cli)
+registerDashboardCommands(cli)
 registerVpnCommands(cli)
 registerStatus(cli)
 registerMcp(cli)

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

@@ -0,0 +1,218 @@
+import {resolve} from 'node:path'
+import {afterEach, beforeEach, describe, expect, it} from 'bun:test'
+
+import {getDashboardDeployEnv, validateDashboardRemotePreconditions} from './deploy'
+
+const repoRoot = resolve(import.meta.dir, '../../../../..')
+
+const envKeys = [
+  'HOME',
+  'PATH',
+  'SSH_AUTH_SOCK',
+  'DASHBOARD_DOMAIN',
+  'DASHBOARD_SSH_KEY',
+  'DASHBOARD_IMAGE_DIGEST',
+  'DASHBOARD_GITHUB_APP_ID',
+  'DASHBOARD_GITHUB_APP_KEY',
+  'DASHBOARD_OAUTH_CLIENT_ID',
+  'DASHBOARD_OAUTH_CLIENT_SECRET',
+  'DASHBOARD_OPERATOR_LOGIN',
+  'DASHBOARD_COOKIE_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()
+})
+
+// ─── getDashboardDeployEnv ────────────────────────────────────────────────────
+
+describe('getDashboardDeployEnv', () => {
+  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',
+      DASHBOARD_DOMAIN: 'dashboard.fro.bot',
+    })
+
+    const env = getDashboardDeployEnv()
+
+    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.DASHBOARD_DOMAIN).toBe('dashboard.fro.bot')
+  })
+
+  it('throws when PATH is missing', () => {
+    setManagedEnv({PATH: undefined, HOME: '/home/user', SSH_AUTH_SOCK: '/tmp/ssh-agent.sock'})
+
+    expect(() => getDashboardDeployEnv()).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(() => getDashboardDeployEnv()).toThrow('HOME is required')
+  })
+
+  it('throws when SSH_AUTH_SOCK is missing and no DASHBOARD_SSH_KEY either', () => {
+    setManagedEnv({
+      PATH: '/usr/bin:/bin',
+      HOME: '/home/user',
+      SSH_AUTH_SOCK: undefined,
+      DASHBOARD_SSH_KEY: undefined,
+    })
+
+    expect(() => getDashboardDeployEnv()).toThrow('Local deploy needs an SSH context')
+  })
+
+  it('succeeds with only SSH_AUTH_SOCK set (no DASHBOARD_SSH_KEY)', () => {
+    setManagedEnv({
+      PATH: '/usr/bin:/bin',
+      HOME: '/home/user',
+      SSH_AUTH_SOCK: '/tmp/ssh-agent.sock',
+      DASHBOARD_SSH_KEY: undefined,
+    })
+
+    const env = getDashboardDeployEnv()
+
+    expect(env.SSH_AUTH_SOCK).toBe('/tmp/ssh-agent.sock')
+    expect('DASHBOARD_SSH_KEY' in env).toBe(false)
+  })
+
+  it('succeeds with only DASHBOARD_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,
+      DASHBOARD_SSH_KEY: 'ssh-ed25519 AAAA...',
+    })
+
+    const env = getDashboardDeployEnv()
+
+    expect(env.DASHBOARD_SSH_KEY).toBe('ssh-ed25519 AAAA...')
+    expect('SSH_AUTH_SOCK' in env).toBe(false)
+    expect(env.DASHBOARD_SSH_KEY).toBe('ssh-ed25519 AAAA...')
+    expect('SSH_AUTH_SOCK' in env).toBe(false)
+  })
+
+  it('forwards all DASHBOARD_* vars from process.env (not a selective subset)', () => {
+    setManagedEnv({
+      PATH: '/usr/bin:/bin',
+      HOME: '/home/user',
+      SSH_AUTH_SOCK: '/tmp/ssh-agent.sock',
+      DASHBOARD_DOMAIN: 'dashboard.fro.bot',
+      DASHBOARD_IMAGE_DIGEST: `sha256:${'a'.repeat(64)}`,
+      DASHBOARD_GITHUB_APP_ID: '123456',
+      DASHBOARD_GITHUB_APP_KEY: '-----BEGIN RSA PRIVATE KEY-----\nfake\n-----END RSA PRIVATE KEY-----',
+      DASHBOARD_OAUTH_CLIENT_ID: 'Iv1.abc123',
+      DASHBOARD_OAUTH_CLIENT_SECRET: 'oauthsecret',
+      DASHBOARD_OPERATOR_LOGIN: 'marcusrbrown',
+      DASHBOARD_COOKIE_KEY: 'cookiekey',
+    })
+
+    const env = getDashboardDeployEnv()
+
+    // All DASHBOARD_* vars must be present in the returned env
+    expect(env.DASHBOARD_DOMAIN).toBe('dashboard.fro.bot')
+    expect(env.DASHBOARD_IMAGE_DIGEST).toBe(`sha256:${'a'.repeat(64)}`)
+    expect(env.DASHBOARD_GITHUB_APP_ID).toBe('123456')
+    expect(env.DASHBOARD_OAUTH_CLIENT_ID).toBe('Iv1.abc123')
+    expect(env.DASHBOARD_OAUTH_CLIENT_SECRET).toBe('oauthsecret')
+    expect(env.DASHBOARD_OPERATOR_LOGIN).toBe('marcusrbrown')
+    expect(env.DASHBOARD_COOKIE_KEY).toBe('cookiekey')
+  })
+})
+
+// ─── validateDashboardRemotePreconditions ─────────────────────────────────────
+
+describe('validateDashboardRemotePreconditions', () => {
+  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(() => validateDashboardRemotePreconditions()).not.toThrow()
+      return
+    }
+
+    expect(() => validateDashboardRemotePreconditions()).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', 'dashboard', '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 Dashboard')
+  })
+
+  it('dry-run local mode prints planned bun command without executing', async () => {
+    const proc = Bun.spawn(['bun', 'run', 'packages/cli/src/cli.ts', 'dashboard', '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/dashboard')
+  })
+})

package/src/commands/dashboard/deploy.ts

@@ -0,0 +1,135 @@
+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 Dashboard'
+const WORKFLOW_URL = 'https://github.com/marcusrbrown/infra/actions/workflows/deploy-dashboard.yaml'
+
+type CliInstance = ReturnType<typeof goke>
+
+// ─── Env helpers ─────────────────────────────────────────────────────────────
+
+export function getDashboardDeployEnv(): Record<string, string> {
+  const path = process.env.PATH
+  const home = process.env.HOME
+  const sshAuthSock = process.env.SSH_AUTH_SOCK
+  const sshKey = process.env.DASHBOARD_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 DASHBOARD_SSH_KEY (key from env).',
+    )
+  }
+
+  // Spread all of process.env so DASHBOARD_* vars (IMAGE_DIGEST, GITHUB_APP_ID, etc.)
+  // are forwarded to the spawned deploy.ts process. validateEnv in deploy.ts requires
+  // all DASHBOARD_* vars to be present — a selective subset would cause it to fail.
+  // Filter out undefined values (Record<string, string> does not allow undefined).
+  const fullEnv: Record<string, string> = {}
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v !== undefined) {
+      fullEnv[k] = v
+    }
+  }
+  return fullEnv
+}
+
+export function validateDashboardRemotePreconditions(): 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 registerDashboardDeploy(cli: CliInstance): void {
+  cli
+    .command(
+      'dashboard deploy',
+      'Deploy the dashboard. Default mode triggers the GitHub Deploy Dashboard workflow, while --local runs apps/dashboard deploy directly with Bun.',
+    )
+    .option(
+      '--local',
+      z
+        .boolean()
+        .default(false)
+        .describe('Run local deployment with Bun using apps/dashboard 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 dashboard deploy')
+    .example('# Validate local deploy preconditions and planned command')
+    .example('infra dashboard deploy --local --dry-run')
+    .example('# Run local deploy with explicit SSH agent context')
+    .example('infra dashboard deploy --local')
+    .action(async options => {
+      if (options.local) {
+        const command = ['bun', 'run', '--cwd', 'apps/dashboard', 'deploy']
+
+        if (options.dryRun) {
+          console.log('Dry run: local dashboard deploy')
+          console.log(`- command: ${command.join(' ')}`)
+          return
+        }
+
+        const env = getDashboardDeployEnv()
+
+        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
+      }
+
+      validateDashboardRemotePreconditions()
+
+      if (options.dryRun) {
+        console.log('Dry run: remote dashboard 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 dashboard environment deployment in GitHub Actions to continue.')
+    })
+}

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

@@ -0,0 +1,79 @@
+import {describe, expect, it} from 'bun:test'
+
+import {validateDashboardHost} from './host'
+
+describe('validateDashboardHost', () => {
+  it('accepts a standard FQDN', () => {
+    expect(() => validateDashboardHost('dashboard.fro.bot')).not.toThrow()
+    expect(validateDashboardHost('dashboard.fro.bot')).toBe('dashboard.fro.bot')
+  })
+
+  it('accepts localhost', () => {
+    expect(() => validateDashboardHost('localhost')).not.toThrow()
+  })
+
+  it('accepts an IPv4 address', () => {
+    expect(() => validateDashboardHost('147.182.133.210')).not.toThrow()
+  })
+
+  it('accepts a single-character hostname', () => {
+    expect(() => validateDashboardHost('a')).not.toThrow()
+  })
+
+  it('accepts a hostname with hyphens', () => {
+    expect(() => validateDashboardHost('my-dashboard.prod.example.com')).not.toThrow()
+  })
+
+  it('rejects a leading-hyphen value (ProxyCommand injection vector)', () => {
+    expect(() => validateDashboardHost('-oProxyCommand=evil')).toThrow('Invalid DASHBOARD_DOMAIN')
+  })
+
+  it('rejects a value with shell metacharacters (semicolon)', () => {
+    expect(() => validateDashboardHost('dashboard.fro.bot;rm -rf')).toThrow('Invalid DASHBOARD_DOMAIN')
+  })
+
+  it('rejects a value with shell metacharacters (backtick)', () => {
+    expect(() => validateDashboardHost('dashboard.fro.bot`id`')).toThrow('Invalid DASHBOARD_DOMAIN')
+  })
+
+  it('rejects a value with spaces', () => {
+    expect(() => validateDashboardHost('dashboard fro.bot')).toThrow('Invalid DASHBOARD_DOMAIN')
+  })
+
+  it('rejects a value with an at-sign', () => {
+    expect(() => validateDashboardHost('user@dashboard.fro.bot')).toThrow('Invalid DASHBOARD_DOMAIN')
+  })
+
+  it('rejects an empty string', () => {
+    expect(() => validateDashboardHost('')).toThrow('Invalid DASHBOARD_DOMAIN')
+  })
+
+  it('omits the rejected value entirely from the error message', () => {
+    const longMalicious = `-oProxyCommand=${'A'.repeat(100)}`
+    let message = ''
+    try {
+      validateDashboardHost(longMalicious)
+    } catch (error) {
+      message = error instanceof Error ? error.message : String(error)
+    }
+    // The value is never echoed (it may be a misdirected secret) — only the constraint is shown.
+    expect(message).toContain('Invalid DASHBOARD_DOMAIN')
+    expect(message).not.toContain('ProxyCommand')
+    expect(message).not.toContain('AAAA')
+  })
+
+  // ── Secret value redaction ───────────────────────────────────────────────────
+
+  it('does not echo the rejected value in the error message', () => {
+    const secretValue = 'AWS_SECRET_KEY=AKIA1234567890EXAMPLE'
+    let message = ''
+    try {
+      validateDashboardHost(secretValue)
+    } catch (error) {
+      message = error instanceof Error ? error.message : String(error)
+    }
+    expect(message).toContain('Invalid DASHBOARD_DOMAIN')
+    expect(message).not.toContain('AKIA1234567890EXAMPLE')
+    expect(message).not.toContain('AWS_SECRET_KEY')
+  })
+})

package/src/commands/dashboard/host.ts

@@ -0,0 +1,33 @@
+// ─── Dashboard host validation ────────────────────────────────────────────────
+//
+// Validates DASHBOARD_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 DASHBOARD_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} when empty or not a valid hostname. The rejected value is
+ *   never included in the message (it may be a misdirected secret).
+ * @returns The validated host string (unchanged).
+ */
+export function validateDashboardHost(host: string): string {
+  if (!host) {
+    throw new Error('Invalid DASHBOARD_DOMAIN: value is empty')
+  }
+
+  if (!VALID_HOST_RE.test(host)) {
+    // Do NOT echo the value — it may be a secret that was redirected via --key
+    throw new Error(
+      `Invalid DASHBOARD_DOMAIN: value is not a valid hostname (must match ${String.raw`[A-Za-z0-9][A-Za-z0-9.\-]*`})`,
+    )
+  }
+
+  return host
+}

package/src/commands/dashboard/index.ts

@@ -0,0 +1,13 @@
+import type {goke} from 'goke'
+
+import {registerDashboardDeploy} from './deploy'
+import {registerDashboardLogs} from './logs'
+import {registerDashboardStatus} from './status'
+
+export {getDashboardStatusSummary} from './status'
+
+export function registerDashboardCommands(cli: ReturnType<typeof goke>): void {
+  registerDashboardStatus(cli)
+  registerDashboardDeploy(cli)
+  registerDashboardLogs(cli)
+}