@marcusrbrown/infra 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcusrbrown/infra",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Infrastructure management CLI — deploy automation, health checks, and MCP bridge",
   "keywords": [
     "infra",
@@ -25,7 +25,8 @@
     "src/"
   ],
   "scripts": {
-    "cli": "bun run src/cli.ts"
+    "cli": "bun run src/cli.ts",
+    "test": "bun test"
   },
   "dependencies": {
     "@goke/mcp": "^0.0.9",

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

@@ -0,0 +1,30 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`infra CLI shows root help with registered top-level commands 1`] = `
+"infra/x.x.x
+
+
+Usage:
+  $ infra <command> [options]
+
+
+Commands:
+  keeweb status  Show operational health of the KeeWeb deployment
+
+
+  keeweb deploy  Trigger KeeWeb deployment. Default mode dispatches the GitHub Deploy workflow. Use --local to run apps/keeweb/deploy.sh directly from this repo.
+
+    --local      Run local deployment using apps/keeweb/deploy.sh instead of triggering GitHub Actions. (default: false)
+    --nginx      Include nginx config deployment. Valid only with --local and passed through to deploy.sh as --nginx. (default: false)
+    --dry-run    Print planned actions without validating preconditions, executing deploy.sh, or triggering GitHub Actions. (default: false)
+
+
+  mcp            Start a stdio MCP server exposing all CLI commands as tools for coding agents
+
+
+Options:
+  --verbose      Enable verbose output for all commands
+  -h, --help     Display this message
+  -v, --version  Display version number
+"
+`;

package/src/cli.test.ts

@@ -0,0 +1,61 @@
+import {resolve} from 'node:path'
+import {describe, expect, it} from 'bun:test'
+
+const cliDir = resolve(import.meta.dir, '..')
+
+async function runCli(...args: string[]) {
+  const proc = Bun.spawn(['bun', 'src/cli.ts', ...args], {
+    cwd: cliDir,
+    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,
+  ])
+
+  return {stdout, stderr, exitCode}
+}
+
+describe('infra CLI', () => {
+  it('shows root help with registered top-level commands', async () => {
+    const {stdout, stderr, exitCode} = await runCli('--help')
+
+    expect(exitCode).toBe(0)
+    expect(stderr).toBe('')
+    expect(stdout).toContain('keeweb')
+    expect(stdout).toContain('mcp')
+    // Normalize version so snapshot survives changeset bumps
+    const stableOutput = stdout.replace(/infra\/\d+\.\d+\.\d+/, 'infra/x.x.x')
+    expect(stableOutput).toMatchSnapshot()
+  })
+
+  it('shows keeweb deploy help with expected flags', async () => {
+    const {stdout, stderr, exitCode} = await runCli('keeweb', 'deploy', '--help')
+
+    expect(exitCode).toBe(0)
+    expect(stderr).toBe('')
+    expect(stdout).toContain('--local')
+    expect(stdout).toContain('--nginx')
+    expect(stdout).toContain('--dry-run')
+  })
+
+  it('falls back to root help for an unknown command', async () => {
+    const {stdout, stderr, exitCode} = await runCli('nonexistent')
+
+    expect(exitCode).toBe(0)
+    expect(stderr).toBe('')
+    expect(stdout).toContain('Usage:')
+  })
+
+  it('exits non-zero and prints an error for an invalid option', async () => {
+    const {stdout, stderr, exitCode} = await runCli('keeweb', 'deploy', '--bogus')
+
+    expect(exitCode).not.toBe(0)
+    expect(stdout).toBe('')
+    expect(stderr).toContain('--bogus')
+  })
+})

package/src/commands/keeweb-deploy.test.ts

@@ -0,0 +1,182 @@
+import {resolve} from 'node:path'
+import {afterEach, beforeEach, describe, expect, it, spyOn} from 'bun:test'
+
+import {
+  getLocalDeployEnv,
+  resolveDeployScriptPath,
+  resolveDistIndexPath,
+  validateRemotePreconditions,
+} from './keeweb-deploy'
+
+const cliDir = resolve(import.meta.dir, '../..')
+
+const envKeys = ['HOST', 'HOME', 'PATH', 'REMOTE_USER', 'SITE_DIR', 'SSH_AUTH_SOCK'] 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]
+      continue
+    }
+
+    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]
+      continue
+    }
+
+    process.env[key] = value
+  }
+}
+
+async function runDeployCommand(
+  args: string[],
+  envOverrides: Partial<Record<ManagedEnvKey, string | undefined>> = {},
+): Promise<{stdout: string; stderr: string; exitCode: number}> {
+  const env = {...process.env}
+
+  for (const [key, value] of Object.entries(envOverrides)) {
+    if (value === undefined) {
+      delete env[key]
+      continue
+    }
+
+    env[key] = value
+  }
+
+  const proc = Bun.spawn(['bun', 'src/cli.ts', 'keeweb', 'deploy', ...args], {
+    cwd: cliDir,
+    env: {
+      ...env,
+      NO_COLOR: '1',
+      SSH_AUTH_SOCK: env.SSH_AUTH_SOCK ?? '/tmp/test-sock',
+    },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+
+  return {stdout, stderr, exitCode}
+}
+
+describe('keeweb deploy', () => {
+  beforeEach(() => {
+    originalEnv = Object.fromEntries(envKeys.map(key => [key, process.env[key]]))
+  })
+
+  afterEach(() => {
+    restoreManagedEnv()
+  })
+
+  describe('resolveDeployScriptPath', () => {
+    it('returns a string path containing deploy.sh', () => {
+      const deployScriptPath = resolveDeployScriptPath()
+
+      expect(typeof deployScriptPath).toBe('string')
+      expect(deployScriptPath).toContain('deploy.sh')
+    })
+  })
+
+  describe('resolveDistIndexPath', () => {
+    it('returns a string path ending with dist/index.html', () => {
+      const distIndexPath = resolveDistIndexPath()
+
+      expect(typeof distIndexPath).toBe('string')
+      expect(distIndexPath).toEndWith('dist/index.html')
+    })
+  })
+
+  describe('getLocalDeployEnv', () => {
+    it('returns the expected deploy environment when required variables are present', () => {
+      setManagedEnv({
+        HOME: '/tmp/test-home',
+        PATH: '/usr/bin:/bin',
+        SSH_AUTH_SOCK: '/tmp/test-sock',
+      })
+
+      expect(getLocalDeployEnv()).toEqual({
+        HOME: '/tmp/test-home',
+        HOST: 'box.heatvision.co',
+        PATH: '/usr/bin:/bin',
+        REMOTE_USER: 'deploy-kw',
+        SITE_DIR: '/home/user-data/www/kw.igg.ms',
+        SSH_AUTH_SOCK: '/tmp/test-sock',
+      })
+    })
+
+    it('throws when SSH_AUTH_SOCK is missing', () => {
+      setManagedEnv({
+        HOME: '/tmp/test-home',
+        PATH: '/usr/bin:/bin',
+        SSH_AUTH_SOCK: undefined,
+      })
+
+      expect(() => getLocalDeployEnv()).toThrow(/SSH_AUTH_SOCK/)
+    })
+
+    it('throws when PATH is missing', () => {
+      setManagedEnv({
+        HOME: '/tmp/test-home',
+        PATH: undefined,
+        SSH_AUTH_SOCK: '/tmp/test-sock',
+      })
+
+      expect(() => getLocalDeployEnv()).toThrow(/PATH/)
+    })
+  })
+
+  describe('validateRemotePreconditions', () => {
+    it('does not throw when gh is available', () => {
+      const whichSpy = spyOn(Bun, 'which').mockReturnValue('/opt/homebrew/bin/gh')
+
+      expect(() => validateRemotePreconditions()).not.toThrow()
+
+      whichSpy.mockRestore()
+    })
+
+    it('throws when gh is unavailable', () => {
+      const whichSpy = spyOn(Bun, 'which').mockReturnValue(null)
+
+      expect(() => validateRemotePreconditions()).toThrow(/gh CLI is required/)
+
+      whichSpy.mockRestore()
+    })
+  })
+
+  describe('CLI flag interactions', () => {
+    it('rejects --nginx without --local', async () => {
+      const {stdout, stderr, exitCode} = await runDeployCommand(['--nginx'])
+
+      expect(exitCode).not.toBe(0)
+      expect(`${stdout}${stderr}`).toContain('only valid with --local')
+    })
+
+    it('prints the local dry-run plan without executing deploy.sh', async () => {
+      const deployScriptPath = resolveDeployScriptPath()
+      const {stdout, stderr, exitCode} = await runDeployCommand(['--local', '--dry-run'])
+
+      expect(exitCode).toBe(0)
+      expect(stderr).toBe('')
+      expect(stdout).toContain('Dry run: local KeeWeb deploy')
+      expect(stdout).toContain(deployScriptPath)
+    })
+  })
+})

package/src/commands/keeweb-deploy.ts

@@ -13,7 +13,7 @@ const DEFAULT_SITE_DIR = '/home/user-data/www/kw.igg.ms'
 
 type CliInstance = ReturnType<typeof goke>
 
-function resolveDeployScriptPath(): string {
+export function resolveDeployScriptPath(): string {
   const instructedPath = resolve(import.meta.dir, '../../../apps/keeweb/deploy.sh')
 
   if (existsSync(instructedPath)) {
@@ -25,11 +25,11 @@ function resolveDeployScriptPath(): string {
   return fallbackPath
 }
 
-function resolveDistIndexPath(): string {
+export function resolveDistIndexPath(): string {
   return resolve(import.meta.dir, '../../../../apps/keeweb/dist/index.html')
 }
 
-function getLocalDeployEnv(): Record<string, string> {
+export function getLocalDeployEnv(): Record<string, string> {
   const path = process.env.PATH
   const home = process.env.HOME
   const sshAuthSock = process.env.SSH_AUTH_SOCK
@@ -56,7 +56,10 @@ function getLocalDeployEnv(): Record<string, string> {
   }
 }
 
-function validateLocalPreconditions(options: {nginx?: boolean}): {deployScriptPath: string; distIndexPath: string} {
+export function validateLocalPreconditions(options: {nginx?: boolean}): {
+  deployScriptPath: string
+  distIndexPath: string
+} {
   const deployScriptPath = resolveDeployScriptPath()
   if (!existsSync(deployScriptPath)) {
     throw new Error(`deploy.sh not found at expected path: ${deployScriptPath}`)
@@ -76,7 +79,7 @@ function validateLocalPreconditions(options: {nginx?: boolean}): {deployScriptPa
   return {deployScriptPath, distIndexPath}
 }
 
-function validateRemotePreconditions(): void {
+export function validateRemotePreconditions(): void {
   if (!Bun.which('gh')) {
     throw new Error('gh CLI is required for remote deploy. Install gh and run `gh auth login`.')
   }
@@ -110,12 +113,12 @@ export function registerKeewebDeploy(cli: CliInstance): void {
         .boolean()
         .default(false)
         .describe(
-          'Validate preconditions and print planned actions without executing deploy.sh or triggering GitHub Actions.',
+          'Print planned actions without validating preconditions, executing deploy.sh, or triggering GitHub Actions.',
         ),
     )
     .example('# Trigger GitHub Deploy workflow (default mode)')
     .example('infra keeweb deploy')
-    .example('# Validate local deploy preconditions without side effects')
+    .example('# Preview local deploy plan without side effects')
     .example('infra keeweb deploy --local --dry-run')
     .example('# Run local deploy including nginx config update')
     .example('infra keeweb deploy --local --nginx')
@@ -125,25 +128,27 @@ export function registerKeewebDeploy(cli: CliInstance): void {
       }
 
       if (options.local) {
-        const {deployScriptPath} = validateLocalPreconditions({nginx: options.nginx})
-        const env = getLocalDeployEnv()
-        const args = ['bash', deployScriptPath]
-
-        if (options.nginx) {
-          args.push('--nginx')
-        }
-
         if (options.dryRun) {
+          const deployScriptPath = resolveDeployScriptPath()
+          const args = ['bash', deployScriptPath]
+          if (options.nginx) {
+            args.push('--nginx')
+          }
           console.log('Dry run: local KeeWeb deploy')
           console.log(`- deploy script: ${deployScriptPath}`)
           console.log(`- dist check: ${resolveDistIndexPath()}`)
           console.log(`- command: ${args.join(' ')}`)
-          console.log(`- HOST=${env.HOST}`)
-          console.log(`- REMOTE_USER=${env.REMOTE_USER}`)
-          console.log(`- SITE_DIR=${env.SITE_DIR}`)
           return
         }
 
+        const {deployScriptPath} = validateLocalPreconditions({nginx: options.nginx})
+        const env = getLocalDeployEnv()
+        const args = ['bash', deployScriptPath]
+
+        if (options.nginx) {
+          args.push('--nginx')
+        }
+
         const child = Bun.spawn(args, {
           env,
           stdout: 'inherit',
@@ -158,11 +163,6 @@ export function registerKeewebDeploy(cli: CliInstance): void {
         return
       }
 
-      validateRemotePreconditions()
-
-      console.warn('Warning: the Deploy workflow includes nginx config deployment as part of workflow_dispatch logic.')
-      console.warn('Warning: the workflow requires production environment approval before jobs execute.')
-
       if (options.dryRun) {
         console.log('Dry run: remote KeeWeb deploy')
         console.log(`- command: gh workflow run ${WORKFLOW_NAME} --repo ${REPO}`)
@@ -170,6 +170,11 @@ export function registerKeewebDeploy(cli: CliInstance): void {
         return
       }
 
+      validateRemotePreconditions()
+
+      console.warn('Warning: the Deploy workflow includes nginx config deployment as part of workflow_dispatch logic.')
+      console.warn('Warning: the workflow requires production environment approval before jobs execute.')
+
       const child = Bun.spawn(['gh', 'workflow', 'run', WORKFLOW_NAME, '--repo', REPO], {
         stdout: 'inherit',
         stderr: 'inherit',

package/src/commands/keeweb-status.test.ts

@@ -0,0 +1,196 @@
+import {afterEach, beforeEach, describe, expect, it, mock, spyOn} from 'bun:test'
+
+import {
+  checkContentHash,
+  checkHttpReachability,
+  checkLastDeploy,
+  formatDate,
+  formatDurationMs,
+  hashSha256,
+} from './keeweb-status'
+
+const originalFetch = globalThis.fetch
+
+type SpawnResult = ReturnType<typeof Bun.spawn>
+
+function createFetchImplementation(
+  handler: (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => ReturnType<typeof fetch>,
+): typeof fetch {
+  return Object.assign(
+    (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => handler(input, init),
+    {preconnect: originalFetch.preconnect},
+  )
+}
+
+function textStream(value: string): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode(value))
+      controller.close()
+    },
+  })
+}
+
+function mockSpawnResult(exitCode: number, stdout: string, stderr = ''): SpawnResult {
+  return {
+    exited: Promise.resolve(exitCode),
+    stdout: textStream(stdout),
+    stderr: textStream(stderr),
+  } as unknown as SpawnResult
+}
+
+describe('keeweb status helpers', () => {
+  let fetchMock: ReturnType<typeof mock<typeof fetch>>
+  let fileSpy: ReturnType<typeof spyOn<typeof Bun, 'file'>> | undefined
+  let spawnSpy: ReturnType<typeof spyOn<typeof Bun, 'spawn'>> | undefined
+
+  beforeEach(() => {
+    fetchMock = mock(
+      createFetchImplementation(async () => {
+        throw new Error('Unexpected fetch call')
+      }),
+    )
+    globalThis.fetch = Object.assign(fetchMock, {preconnect: originalFetch.preconnect})
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    fileSpy?.mockRestore()
+    fileSpy = undefined
+    spawnSpy?.mockRestore()
+    spawnSpy = undefined
+  })
+
+  describe('hashSha256', () => {
+    it('returns the known digest for hello', () => {
+      expect(hashSha256('hello')).toBe('2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824')
+    })
+
+    it('returns the known digest for an empty string', () => {
+      expect(hashSha256('')).toBe('e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855')
+    })
+  })
+
+  describe('formatDate', () => {
+    it('formats valid ISO dates', () => {
+      const value = '2026-01-15T10:30:00Z'
+      const formatted = formatDate(value)
+
+      expect(formatted).not.toBe(value)
+      expect(formatted).not.toContain('NaN')
+      expect(formatted).toContain('2026')
+    })
+
+    it('passes through invalid dates', () => {
+      expect(formatDate('not-a-date')).toBe('not-a-date')
+    })
+  })
+
+  describe('formatDurationMs', () => {
+    it('formats positive durations', () => {
+      expect(formatDurationMs(1234)).toBe('1234ms')
+    })
+
+    it('formats zero duration', () => {
+      expect(formatDurationMs(0)).toBe('0ms')
+    })
+
+    it('clamps negative durations to zero', () => {
+      expect(formatDurationMs(-5)).toBe('0ms')
+    })
+  })
+
+  describe('checkHttpReachability', () => {
+    it('returns ok for HTTP 200', async () => {
+      fetchMock.mockImplementation(createFetchImplementation(async () => new Response('ok', {status: 200})))
+
+      const result = await checkHttpReachability(false)
+
+      expect(result.level).toBe('ok')
+      expect(result.summary).toContain('GET https://kw.igg.ms/ → 200')
+    })
+
+    it('returns error for HTTP 500', async () => {
+      fetchMock.mockImplementation(createFetchImplementation(async () => new Response('error', {status: 500})))
+
+      const result = await checkHttpReachability(false)
+
+      expect(result.level).toBe('error')
+      expect(result.summary).toContain('GET https://kw.igg.ms/ → 500')
+    })
+
+    it('returns error details for network failures', async () => {
+      fetchMock.mockImplementation(
+        createFetchImplementation(async () => {
+          throw new Error('Network timeout')
+        }),
+      )
+
+      const result = await checkHttpReachability(true)
+
+      expect(result.level).toBe('error')
+      expect(result.summary).toContain('Network timeout')
+      expect(result.details).toEqual(['URL: https://kw.igg.ms/', 'Timeout: 10000ms'])
+    })
+  })
+
+  describe('checkLastDeploy', () => {
+    it('returns ok for valid gh output', async () => {
+      spawnSpy = spyOn(Bun, 'spawn').mockImplementation(() =>
+        mockSpawnResult(0, JSON.stringify([{createdAt: '2026-01-15T10:30:00Z', url: 'https://example.com'}])),
+      )
+
+      const result = await checkLastDeploy(false)
+
+      expect(result.level).toBe('ok')
+      expect(result.summary).toBe(formatDate('2026-01-15T10:30:00Z'))
+      expect(result.details).toEqual(['Run URL: https://example.com'])
+    })
+
+    it('returns warning when no successful runs are found', async () => {
+      spawnSpy = spyOn(Bun, 'spawn').mockImplementation(() => mockSpawnResult(0, '[]'))
+
+      const result = await checkLastDeploy(false)
+
+      expect(result.level).toBe('warning')
+      expect(result.summary).toContain('No successful')
+    })
+
+    it('returns warning when gh exits non-zero', async () => {
+      spawnSpy = spyOn(Bun, 'spawn').mockImplementation(() => mockSpawnResult(1, '', 'boom'))
+
+      const result = await checkLastDeploy(false)
+
+      expect(result.level).toBe('warning')
+      expect(result.summary).toContain('gh exited 1')
+    })
+
+    it('returns warning when gh cannot be invoked', async () => {
+      spawnSpy = spyOn(Bun, 'spawn').mockImplementation(() => {
+        throw new Error('gh not found')
+      })
+
+      const result = await checkLastDeploy(false)
+
+      expect(result.level).toBe('warning')
+      expect(result.summary).toContain('Unable to query')
+      expect(result.summary).toContain('gh not found')
+    })
+  })
+
+  describe('checkContentHash', () => {
+    it('returns warning when the local dist file does not exist', async () => {
+      fileSpy = spyOn(Bun, 'file').mockImplementation(
+        () =>
+          ({
+            exists: async () => false,
+          }) as ReturnType<typeof Bun.file>,
+      )
+
+      const result = await checkContentHash(false)
+
+      expect(result.level).toBe('warning')
+      expect(result.summary).toContain('not found')
+    })
+  })
+})

package/src/commands/keeweb-status.ts

@@ -35,11 +35,11 @@ function levelLabel(level: CheckLevel): string {
   return 'ERROR'
 }
 
-function formatDurationMs(durationMs: number): string {
+export function formatDurationMs(durationMs: number): string {
   return `${Math.max(0, Math.round(durationMs))}ms`
 }
 
-function formatDate(value: string): string {
+export function formatDate(value: string): string {
   const date = new Date(value)
   if (Number.isNaN(date.getTime())) {
     return value
@@ -48,7 +48,7 @@ function formatDate(value: string): string {
   return date.toLocaleString()
 }
 
-function hashSha256(value: string): string {
+export function hashSha256(value: string): string {
   const hasher = new Bun.CryptoHasher('sha256')
   hasher.update(value)
   return hasher.digest('hex')
@@ -62,7 +62,7 @@ async function streamToText(stream?: ReadableStream<Uint8Array> | null): Promise
   return await new Response(stream).text()
 }
 
-async function checkHttpReachability(verbose: boolean): Promise<CheckResult> {
+export async function checkHttpReachability(verbose: boolean): Promise<CheckResult> {
   const startedAt = performance.now()
 
   try {
@@ -104,7 +104,7 @@ async function checkHttpReachability(verbose: boolean): Promise<CheckResult> {
   }
 }
 
-async function checkLastDeploy(verbose: boolean): Promise<CheckResult> {
+export async function checkLastDeploy(verbose: boolean): Promise<CheckResult> {
   try {
     const proc = Bun.spawn(
       [
@@ -189,7 +189,7 @@ async function checkLastDeploy(verbose: boolean): Promise<CheckResult> {
   }
 }
 
-async function checkContentHash(verbose: boolean): Promise<CheckResult> {
+export async function checkContentHash(verbose: boolean): Promise<CheckResult> {
   const distIndexPath = path.resolve(import.meta.dir, '../../../../apps/keeweb/dist/index.html')
   const localFile = Bun.file(distIndexPath)
   const localExists = await localFile.exists()