@marcusrbrown/infra 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @marcusrbrown/infra
+
+Infrastructure management CLI — deploy automation, health checks, and MCP bridge.
+
+> **Requires [Bun](https://bun.sh)** — this package ships TypeScript source with a `#!/usr/bin/env bun` shebang.
+
+## Install
+
+```bash
+bun add -g @marcusrbrown/infra
+```
+
+Or run directly:
+
+```bash
+bunx @marcusrbrown/infra --help
+```
+
+## Commands
+
+### `infra keeweb status`
+
+Operational health check for the KeeWeb deployment:
+
+- HTTP reachability (status code + response time)
+- Last successful deploy timestamp via GitHub Actions
+- SHA-256 content hash comparison (live site vs local `dist/`)
+
+```bash
+bunx @marcusrbrown/infra keeweb status
+```
+
+### `infra keeweb deploy`
+
+Trigger a KeeWeb deployment:
+
+```bash
+bunx @marcusrbrown/infra keeweb deploy              # GitHub Actions workflow
+bunx @marcusrbrown/infra keeweb deploy --dry-run     # preview without executing
+bunx @marcusrbrown/infra keeweb deploy --local       # deploy directly via SSH
+bunx @marcusrbrown/infra keeweb deploy --local --nginx  # include nginx config
+```
+
+Local deploy requires `ssh-agent` running with the deploy key loaded.
+
+### `infra mcp`
+
+Start a stdio MCP server exposing all commands as tools:
+
+```bash
+bunx @marcusrbrown/infra mcp
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@marcusrbrown/infra",
+  "version": "0.1.0",
+  "description": "Infrastructure management CLI — deploy automation, health checks, and MCP bridge",
+  "keywords": [
+    "infra",
+    "cli",
+    "keeweb",
+    "deploy",
+    "mcp",
+    "bun"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marcusrbrown/infra.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "author": "Marcus R. Brown <contact@marcusrbrown.com>",
+  "type": "module",
+  "bin": {
+    "infra": "src/cli.ts"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "cli": "bun run src/cli.ts"
+  },
+  "dependencies": {
+    "@goke/mcp": "^0.0.9",
+    "goke": "^6.3.2",
+    "string-dedent": "^3.0.2",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/cli.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+
+import {goke} from 'goke'
+import pkg from '../package.json' with {type: 'json'}
+import {registerKeewebDeploy} from './commands/keeweb-deploy'
+import {registerKeewebStatus} from './commands/keeweb-status'
+import {registerMcp} from './commands/mcp'
+
+const cli = goke('infra')
+
+cli.option('--verbose', 'Enable verbose output for all commands')
+
+registerKeewebStatus(cli)
+registerKeewebDeploy(cli)
+registerMcp(cli)
+
+cli.help()
+cli.version(pkg.version)
+
+try {
+  cli.parse(process.argv, {run: false})
+  await cli.runMatchedCommand()
+} catch (error) {
+  if (error instanceof Error) {
+    console.error(error.message)
+  }
+  process.exit(1)
+}

package/src/commands/keeweb-deploy.ts

@@ -0,0 +1,186 @@
+import type {goke} from 'goke'
+import {existsSync} from 'node:fs'
+import {resolve} from 'node:path'
+import {z} from 'zod'
+
+const REPO = 'marcusrbrown/infra'
+const WORKFLOW_NAME = 'Deploy'
+const WORKFLOW_URL = 'https://github.com/marcusrbrown/infra/actions/workflows/deploy.yaml'
+
+const DEFAULT_HOST = 'box.heatvision.co'
+const DEFAULT_REMOTE_USER = 'deploy-kw'
+const DEFAULT_SITE_DIR = '/home/user-data/www/kw.igg.ms'
+
+type CliInstance = ReturnType<typeof goke>
+
+function resolveDeployScriptPath(): string {
+  const instructedPath = resolve(import.meta.dir, '../../../apps/keeweb/deploy.sh')
+
+  if (existsSync(instructedPath)) {
+    return instructedPath
+  }
+
+  const fallbackPath = resolve(import.meta.dir, '../../../../apps/keeweb/deploy.sh')
+
+  return fallbackPath
+}
+
+function resolveDistIndexPath(): string {
+  return resolve(import.meta.dir, '../../../../apps/keeweb/dist/index.html')
+}
+
+function getLocalDeployEnv(): Record<string, string> {
+  const path = process.env.PATH
+  const home = process.env.HOME
+  const sshAuthSock = process.env.SSH_AUTH_SOCK
+
+  if (!path) {
+    throw new Error('PATH is required for local deploy')
+  }
+
+  if (!home) {
+    throw new Error('HOME is required for local deploy')
+  }
+
+  if (!sshAuthSock) {
+    throw new Error('SSH_AUTH_SOCK is required for local deploy. Start ssh-agent and load your deploy key first.')
+  }
+
+  return {
+    HOST: process.env.HOST ?? DEFAULT_HOST,
+    REMOTE_USER: process.env.REMOTE_USER ?? DEFAULT_REMOTE_USER,
+    SITE_DIR: process.env.SITE_DIR ?? DEFAULT_SITE_DIR,
+    SSH_AUTH_SOCK: sshAuthSock,
+    PATH: path,
+    HOME: home,
+  }
+}
+
+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}`)
+  }
+
+  const distIndexPath = resolveDistIndexPath()
+  if (!existsSync(distIndexPath)) {
+    throw new Error(`Local deploy requires built assets. Missing: ${distIndexPath}`)
+  }
+
+  getLocalDeployEnv()
+
+  if (options.nginx) {
+    // no-op placeholder to keep validation branch explicit
+  }
+
+  return {deployScriptPath, distIndexPath}
+}
+
+function validateRemotePreconditions(): void {
+  if (!Bun.which('gh')) {
+    throw new Error('gh CLI is required for remote deploy. Install gh and run `gh auth login`.')
+  }
+}
+
+export function registerKeewebDeploy(cli: CliInstance): void {
+  cli
+    .command(
+      'keeweb deploy',
+      'Trigger KeeWeb deployment. Default mode dispatches the GitHub Deploy workflow. Use --local to run apps/keeweb/deploy.sh directly from this repo.',
+    )
+    .option(
+      '--local',
+      z
+        .boolean()
+        .default(false)
+        .describe('Run local deployment using apps/keeweb/deploy.sh instead of triggering GitHub Actions.'),
+    )
+    .option(
+      '--nginx',
+      z
+        .boolean()
+        .default(false)
+        .describe(
+          'Include nginx config deployment. Valid only with --local and passed through to deploy.sh as --nginx.',
+        ),
+    )
+    .option(
+      '--dry-run',
+      z
+        .boolean()
+        .default(false)
+        .describe(
+          'Validate preconditions and print planned actions without 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('infra keeweb deploy --local --dry-run')
+    .example('# Run local deploy including nginx config update')
+    .example('infra keeweb deploy --local --nginx')
+    .action(async options => {
+      if (options.nginx && !options.local) {
+        throw new Error('--nginx is only valid with --local')
+      }
+
+      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) {
+          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 child = Bun.spawn(args, {
+          env,
+          stdout: 'inherit',
+          stderr: 'inherit',
+        })
+
+        const exitCode = await child.exited
+        if (exitCode !== 0) {
+          throw new Error(`Local deploy failed with exit code ${exitCode}`)
+        }
+
+        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}`)
+        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 Deploy workflow (exit code ${exitCode})`)
+      }
+
+      console.log(`Workflow triggered: ${WORKFLOW_URL}`)
+      console.log('Approve the production environment deployment in GitHub Actions to continue.')
+    })
+}

package/src/commands/keeweb-status.ts

@@ -0,0 +1,290 @@
+import type {goke} from 'goke'
+
+import path from 'node:path'
+import {z} from 'zod'
+
+const SITE_URL = 'https://kw.igg.ms/'
+const GH_REPO = 'marcusrbrown/infra'
+const HTTP_TIMEOUT_MS = 10_000
+
+type CheckLevel = 'ok' | 'warning' | 'error'
+
+interface CheckResult {
+  title: string
+  level: CheckLevel
+  summary: string
+  details?: string[]
+}
+
+const ghRunSchema = z.array(
+  z.object({
+    createdAt: z.string().min(1),
+    url: z.url(),
+  }),
+)
+
+function levelLabel(level: CheckLevel): string {
+  if (level === 'ok') {
+    return 'OK'
+  }
+
+  if (level === 'warning') {
+    return 'WARN'
+  }
+
+  return 'ERROR'
+}
+
+function formatDurationMs(durationMs: number): string {
+  return `${Math.max(0, Math.round(durationMs))}ms`
+}
+
+function formatDate(value: string): string {
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) {
+    return value
+  }
+
+  return date.toLocaleString()
+}
+
+function hashSha256(value: string): string {
+  const hasher = new Bun.CryptoHasher('sha256')
+  hasher.update(value)
+  return hasher.digest('hex')
+}
+
+async function streamToText(stream?: ReadableStream<Uint8Array> | null): Promise<string> {
+  if (!stream) {
+    return ''
+  }
+
+  return await new Response(stream).text()
+}
+
+async function checkHttpReachability(verbose: boolean): Promise<CheckResult> {
+  const startedAt = performance.now()
+
+  try {
+    const response = await fetch(SITE_URL, {
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    })
+    const elapsedMs = performance.now() - startedAt
+    const details: string[] = []
+
+    if (verbose) {
+      details.push(`URL: ${SITE_URL}`)
+      details.push(`Status text: ${response.statusText || '(none)'}`)
+
+      if (response.headers.get('content-type')) {
+        details.push(`Content-Type: ${response.headers.get('content-type')}`)
+      }
+
+      if (response.headers.get('server')) {
+        details.push(`Server: ${response.headers.get('server')}`)
+      }
+    }
+
+    return {
+      title: 'HTTP reachability',
+      level: response.ok ? 'ok' : 'error',
+      summary: `GET ${SITE_URL} → ${response.status} (${formatDurationMs(elapsedMs)})`,
+      details,
+    }
+  } catch (error) {
+    const elapsedMs = performance.now() - startedAt
+    const message = error instanceof Error ? error.message : String(error)
+
+    return {
+      title: 'HTTP reachability',
+      level: 'error',
+      summary: `Request failed after ${formatDurationMs(elapsedMs)}: ${message}`,
+      details: verbose ? [`URL: ${SITE_URL}`, `Timeout: ${HTTP_TIMEOUT_MS}ms`] : undefined,
+    }
+  }
+}
+
+async function checkLastDeploy(verbose: boolean): Promise<CheckResult> {
+  try {
+    const proc = Bun.spawn(
+      [
+        'gh',
+        'run',
+        'list',
+        '--workflow=Deploy',
+        '--status=success',
+        '--limit=1',
+        '--json',
+        'createdAt,url',
+        '--repo',
+        GH_REPO,
+      ],
+      {
+        stderr: 'pipe',
+        stdout: 'pipe',
+      },
+    )
+
+    const [exitCode, stdout, stderr] = await Promise.all([
+      proc.exited,
+      streamToText(proc.stdout),
+      streamToText(proc.stderr),
+    ])
+
+    if (exitCode !== 0) {
+      const baseDetails = stderr.trim() ? [stderr.trim()] : []
+      const verboseDetails = verbose && stdout.trim() ? [...baseDetails, `Raw stdout: ${stdout.trim()}`] : baseDetails
+
+      return {
+        title: 'Last successful deploy',
+        level: 'warning',
+        summary: `Unable to query GitHub Actions (gh exited ${exitCode})`,
+        details: verboseDetails,
+      }
+    }
+
+    const parsed = ghRunSchema.safeParse(JSON.parse(stdout))
+    if (!parsed.success) {
+      return {
+        title: 'Last successful deploy',
+        level: 'warning',
+        summary: 'GitHub CLI output did not match expected schema',
+        details: verbose ? [parsed.error.message, `Raw stdout: ${stdout.trim()}`] : undefined,
+      }
+    }
+
+    const [latestRun] = parsed.data
+
+    if (!latestRun) {
+      return {
+        title: 'Last successful deploy',
+        level: 'warning',
+        summary: 'No successful Deploy workflow runs found',
+      }
+    }
+
+    const details = [`Run URL: ${latestRun.url}`]
+
+    if (verbose) {
+      details.push(`Raw createdAt: ${latestRun.createdAt}`)
+    }
+
+    return {
+      title: 'Last successful deploy',
+      level: 'ok',
+      summary: `${formatDate(latestRun.createdAt)}`,
+      details,
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+
+    return {
+      title: 'Last successful deploy',
+      level: 'warning',
+      summary: `Unable to query GitHub Actions: ${message}`,
+      details: verbose
+        ? ['Requires GitHub CLI authenticated with access to marcusrbrown/infra', 'Install: https://cli.github.com/']
+        : undefined,
+    }
+  }
+}
+
+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()
+
+  if (!localExists) {
+    return {
+      title: 'Content hash',
+      level: 'warning',
+      summary: `Local dist file not found: ${distIndexPath}`,
+      details: ['Run: bun run --cwd apps/keeweb build'],
+    }
+  }
+
+  try {
+    const response = await fetch(SITE_URL, {
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    })
+
+    if (!response.ok) {
+      return {
+        title: 'Content hash',
+        level: 'warning',
+        summary: `Could not fetch remote index.html (HTTP ${response.status})`,
+        details: verbose ? [`URL: ${SITE_URL}`] : undefined,
+      }
+    }
+
+    const [remoteBody, localBody] = await Promise.all([response.text(), localFile.text()])
+    const remoteHash = hashSha256(remoteBody)
+    const localHash = hashSha256(localBody)
+
+    const details = verbose ? [`Remote SHA-256: ${remoteHash}`, `Local SHA-256: ${localHash}`] : undefined
+
+    if (remoteHash === localHash) {
+      return {
+        title: 'Content hash',
+        level: 'ok',
+        summary: 'Remote index.html matches local dist/index.html',
+        details,
+      }
+    }
+
+    return {
+      title: 'Content hash',
+      level: 'warning',
+      summary: 'Remote index.html differs from local dist/index.html',
+      details,
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      title: 'Content hash',
+      level: 'warning',
+      summary: `Could not compare hashes: ${message}`,
+      details: verbose ? [`URL: ${SITE_URL}`, `Local path: ${distIndexPath}`] : undefined,
+    }
+  }
+}
+
+function printCheckResult(result: CheckResult): void {
+  console.log(`[${levelLabel(result.level)}] ${result.title}`)
+  console.log(`  ${result.summary}`)
+
+  if (result.details && result.details.length > 0) {
+    for (const detail of result.details) {
+      console.log(`  - ${detail}`)
+    }
+  }
+}
+
+export function registerKeewebStatus(cli: ReturnType<typeof goke>): void {
+  cli.command('keeweb status', 'Show operational health of the KeeWeb deployment').action(async options => {
+    const verbose = options.verbose === true
+
+    console.log('KeeWeb status')
+    console.log('')
+
+    const results = await Promise.all([
+      checkHttpReachability(verbose),
+      checkLastDeploy(verbose),
+      checkContentHash(verbose),
+    ])
+
+    for (const result of results) {
+      printCheckResult(result)
+      console.log('')
+    }
+
+    const errorCount = results.filter(result => result.level === 'error').length
+    const warningCount = results.filter(result => result.level === 'warning').length
+
+    console.log(`Summary: ${results.length} checks, ${errorCount} errors, ${warningCount} warnings`)
+
+    if (errorCount > 0) {
+      process.exitCode = 1
+    }
+  })
+}

package/src/commands/mcp.ts

@@ -0,0 +1,8 @@
+import type {goke} from 'goke'
+import {createMcpAction} from '@goke/mcp'
+
+export function registerMcp(cli: ReturnType<typeof goke>): void {
+  cli
+    .command('mcp', 'Start a stdio MCP server exposing all CLI commands as tools for coding agents')
+    .action(createMcpAction({cli}))
+}