@marcusrbrown/infra 0.4.8 → 0.4.10

package/src/commands/gateway/status.ts

@@ -0,0 +1,209 @@
+import type {goke} from 'goke'
+import type {StatusSummary} from '../status'
+
+import {z} from 'zod'
+
+import {validateGatewayHost} from './host'
+
+declare const process: {
+  env: Record<string, string | undefined>
+  exitCode?: number
+}
+
+const COMPOSE_PROJECT_DIR = '/opt/gateway/deploy'
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface ComposePsEntry {
+  Name: string
+  State: string
+  Health: string
+}
+
+export type HealthStatus = 'healthy' | 'unhealthy' | 'starting' | 'n-a'
+
+export interface ServiceRow {
+  service: string
+  state: string
+  health: HealthStatus
+}
+
+export interface GatewayStatusResult {
+  ok: boolean
+  services: ServiceRow[]
+  error?: string
+}
+
+export type SpawnFn = (
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'pipe'; stderr: 'pipe'},
+) => {
+  stdout: ReadableStream<Uint8Array>
+  stderr: ReadableStream<Uint8Array>
+  exited: Promise<number>
+}
+
+// ─── Pure helpers ─────────────────────────────────────────────────────────────
+
+function normalizeHealth(raw: string): HealthStatus {
+  if (raw === 'healthy' || raw === 'unhealthy' || raw === 'starting') {
+    return raw
+  }
+
+  return 'n-a'
+}
+
+export function parseComposePs(entries: ComposePsEntry[]): ServiceRow[] {
+  return entries.map(entry => ({
+    service: entry.Name,
+    state: entry.State,
+    // Workspace has no upstream healthcheck in v1; health will upgrade automatically
+    // when upstream adds one and docker compose ps starts reporting it.
+    health: normalizeHealth(entry.Health),
+  }))
+}
+
+export function isAllRunning(rows: ServiceRow[]): boolean {
+  return rows.every(row => row.state === 'running')
+}
+
+// ─── SSH-backed status fetch ──────────────────────────────────────────────────
+
+function defaultSpawn(
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'pipe'; stderr: 'pipe'},
+): ReturnType<SpawnFn> {
+  return Bun.spawn(cmd, opts) as ReturnType<SpawnFn>
+}
+
+export async function getGatewayComposeStatus(
+  host: string,
+  spawn: SpawnFn = defaultSpawn,
+): Promise<GatewayStatusResult> {
+  validateGatewayHost(host)
+
+  const sshCmd = [
+    'ssh',
+    '-o',
+    'BatchMode=yes',
+    '-o',
+    'StrictHostKeyChecking=yes',
+    `root@${host}`,
+    `docker compose --project-directory ${COMPOSE_PROJECT_DIR} ps --format json`,
+  ]
+
+  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: 'pipe', stderr: 'pipe'})
+
+  const [stdoutText, stderrText, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+
+  if (exitCode !== 0) {
+    return {
+      ok: false,
+      services: [],
+      error: `SSH command failed (exit ${exitCode}): ${stderrText.trim() || 'unknown error'}`,
+    }
+  }
+
+  let entries: ComposePsEntry[]
+
+  try {
+    const parsed: unknown = JSON.parse(stdoutText)
+    entries = Array.isArray(parsed) ? (parsed as ComposePsEntry[]) : []
+  } catch {
+    return {ok: false, services: [], error: `Failed to parse docker compose ps output: ${stdoutText.slice(0, 200)}`}
+  }
+
+  const services = parseComposePs(entries)
+  const ok = isAllRunning(services)
+
+  return {ok, services}
+}
+
+// ─── Unified status aggregator export ────────────────────────────────────────
+
+export async function getGatewayStatusSummary(host: string): Promise<StatusSummary> {
+  const result = await getGatewayComposeStatus(host)
+
+  if (!result.ok || result.services.length === 0) {
+    const errorMsg = result.error ?? 'No services reported'
+    return {
+      app: 'gateway',
+      http: `ERROR: ${errorMsg}`,
+      lastDeploy: '—',
+      version: '—',
+      contentHash: '—',
+      usageStats: '—',
+    }
+  }
+
+  const rows = result.services.map(s => `${s.service}:${s.state}/${s.health}`).join(', ')
+
+  return {
+    app: 'gateway',
+    http: `OK: ${rows}`,
+    lastDeploy: '—',
+    version: '—',
+    contentHash: '—',
+    usageStats: '—',
+  }
+}
+
+// ─── Command registration ─────────────────────────────────────────────────────
+
+export function registerGatewayStatus(cli: ReturnType<typeof goke>): void {
+  cli
+    .command('gateway status', 'Show operational health of the gateway deployment via docker compose ps.')
+    .option(
+      '--key [key]',
+      z.string().describe('Environment variable name holding the SSH host. Falls back to GATEWAY_HOST when omitted.'),
+    )
+    .action(async options => {
+      const hostEnvKey = options.key ?? 'GATEWAY_HOST'
+      const host = process.env[hostEnvKey]
+
+      if (!host) {
+        console.error(`Gateway host not set. Export ${hostEnvKey} or pass --key <env-name> pointing to a set variable.`)
+        process.exitCode = 1
+        return
+      }
+
+      console.log('Gateway status')
+      console.log('')
+
+      const result = await getGatewayComposeStatus(host)
+
+      if (!result.ok && result.services.length === 0) {
+        console.error(`Error: ${result.error ?? 'Unknown error'}`)
+        process.exitCode = 1
+        return
+      }
+
+      console.log('Service          State      Health')
+      console.log('─────────────────────────────────────')
+
+      for (const row of result.services) {
+        const svc = row.service.padEnd(16)
+        const state = row.state.padEnd(10)
+        console.log(`${svc} ${state} ${row.health}`)
+      }
+
+      console.log('')
+
+      if (result.ok) {
+        console.log('Status: OK')
+      } else {
+        console.log('Status: DEGRADED (one or more services not running)')
+        process.exitCode = 1
+      }
+    })
+}

package/src/commands/status.test.ts

@@ -50,11 +50,20 @@ describe('top-level status command', () => {
         contentHash: '—',
         usageStats: '12 req / 0 fail',
       }),
+      getGatewayStatusSummary: async () => ({
+        app: 'gateway',
+        http: 'OK: gateway:running/healthy',
+        lastDeploy: '—',
+        version: '—',
+        contentHash: '—',
+        usageStats: '—',
+      }),
     })
 
     expect(lines).toContain('| App | HTTP | Last Deploy | Version | Content Hash | Usage Stats |')
     expect(lines).toContain('| keeweb | OK | 2026-04-12 10:00 | — | match | — |')
     expect(lines).toContain('| cliproxy | OK | — | v1.2.3 | — | 12 req / 0 fail |')
+    expect(lines).toContain('| gateway | OK: gateway:running/healthy | — | — | — | — |')
   })
 
   it('shows an error row when one app fails and keeps the other result', async () => {
@@ -70,6 +79,14 @@ describe('top-level status command', () => {
         contentHash: '—',
         usageStats: '12 req / 0 fail',
       }),
+      getGatewayStatusSummary: async () => ({
+        app: 'gateway',
+        http: 'OK: gateway:running/healthy',
+        lastDeploy: '—',
+        version: '—',
+        contentHash: '—',
+        usageStats: '—',
+      }),
     })
 
     expect(lines).toContain(
@@ -96,6 +113,14 @@ describe('top-level status command', () => {
         contentHash: '—',
         usageStats: '12 req / 0 fail',
       }),
+      getGatewayStatusSummary: async () => ({
+        app: 'gateway',
+        http: 'OK: gateway:running/healthy',
+        lastDeploy: '—',
+        version: '—',
+        contentHash: '—',
+        usageStats: '—',
+      }),
     })
 
     expect(lines).toHaveLength(1)

package/src/commands/status.ts

@@ -3,6 +3,7 @@ import type {goke} from 'goke'
 import {z} from 'zod'
 
 import {getCliproxyStatusSummary} from './cliproxy/status'
+import {getGatewayStatusSummary} from './gateway'
 import {getKeewebStatusSummary} from './keeweb/status'
 
 declare const process: {
@@ -10,7 +11,7 @@ declare const process: {
 }
 
 export interface StatusSummary {
-  app: 'keeweb' | 'cliproxy'
+  app: 'keeweb' | 'cliproxy' | 'gateway'
   http: string
   lastDeploy: string
   version: string
@@ -23,6 +24,7 @@ type AppName = StatusSummary['app']
 interface StatusDependencies {
   getKeewebStatusSummary: (verbose: boolean) => Promise<StatusSummary>
   getCliproxyStatusSummary: (baseUrl: string, key: string, verbose: boolean) => Promise<StatusSummary>
+  getGatewayStatusSummary: (host: string) => Promise<StatusSummary>
 }
 
 const DEFAULT_CLIPROXY_URL = 'https://cliproxy.fro.bot'
@@ -58,6 +60,7 @@ function toJsonPayload(rows: StatusSummary[]): Record<AppName, StatusSummary> {
   return {
     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'),
   }
 }
 
@@ -71,11 +74,15 @@ export function registerStatus(
   dependencies: StatusDependencies = {
     getKeewebStatusSummary,
     getCliproxyStatusSummary,
+    getGatewayStatusSummary,
   },
 ): void {
   cli
     .command('status', 'Show status of all deployments')
-    .option('--json', z.boolean().describe('Output machine-readable JSON with keeweb and cliproxy summary objects.'))
+    .option(
+      '--json',
+      z.boolean().describe('Output machine-readable JSON with keeweb, cliproxy, and gateway summary objects.'),
+    )
     .option(
       '--verbose',
       z.boolean().describe('Include verbose per-app health check details when building the summary rows.'),
@@ -84,14 +91,17 @@ export function registerStatus(
       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 results = await Promise.allSettled([
         dependencies.getKeewebStatusSummary(verbose),
         dependencies.getCliproxyStatusSummary(cliproxyBaseUrl, cliproxyKey, verbose),
+        dependencies.getGatewayStatusSummary(gatewayHost),
       ])
 
+      const appNames: AppName[] = ['keeweb', 'cliproxy', 'gateway']
       const rows: StatusSummary[] = results.map((result, index) => {
-        const app: AppName = index === 0 ? 'keeweb' : 'cliproxy'
+        const app = appNames[index] ?? 'keeweb'
         return result.status === 'fulfilled' ? result.value : errorSummary(app, result.reason)
       })
 

package/src/conventions.test.ts

@@ -71,6 +71,80 @@ export function findCrossOrgSecretsInherit(parsed: unknown): {jobId: string; use
   return violations
 }
 
+/**
+ * Detect dorny/paths-filter steps that use negation patterns without declaring
+ * `predicate-quantifier: every`. The default quantifier (`some`) applies OR-logic
+ * across patterns, which silently makes negations truthy whenever any other file
+ * matches — the opposite of the intended behaviour.
+ *
+ * Rule: any step using dorny/paths-filter that contains a filter pattern starting
+ * with `!` MUST also set `predicate-quantifier: every` in the same step's `with:` block.
+ */
+export interface PathsFilterQuantifierViolation {
+  file?: string
+  jobId: string
+  stepIndex: number
+  reason: string
+}
+
+export function findPathsFilterQuantifierViolations(workflowText: string): PathsFilterQuantifierViolation[] {
+  const parsed = parseYaml(workflowText, {merge: true}) as unknown
+  if (typeof parsed !== 'object' || parsed === null) return []
+  const jobs = (parsed as {jobs?: Record<string, unknown>}).jobs
+  if (typeof jobs !== 'object' || jobs === null) return []
+
+  const violations: PathsFilterQuantifierViolation[] = []
+
+  for (const [jobId, jobRaw] of Object.entries(jobs)) {
+    if (typeof jobRaw !== 'object' || jobRaw === null) continue
+    const job = jobRaw as {steps?: unknown[]}
+    if (!Array.isArray(job.steps)) continue
+
+    for (const [index, stepRaw] of job.steps.entries()) {
+      if (typeof stepRaw !== 'object' || stepRaw === null) continue
+      const step = stepRaw as {uses?: unknown; with?: Record<string, unknown>}
+      if (typeof step.uses !== 'string') continue
+      if (!step.uses.startsWith('dorny/paths-filter')) continue
+
+      const withBlock = step.with ?? {}
+      const filtersRaw = withBlock.filters
+      if (typeof filtersRaw !== 'string') continue
+
+      // Parse the inner YAML of the filters block to inspect pattern lists
+      const filters = parseYaml(filtersRaw, {merge: true}) as unknown
+      if (typeof filters !== 'object' || filters === null) continue
+
+      let hasNegation = false
+      for (const patternsRaw of Object.values(filters as Record<string, unknown>)) {
+        const patterns = Array.isArray(patternsRaw) ? patternsRaw : [patternsRaw]
+        for (const p of patterns) {
+          if (typeof p === 'string' && p.startsWith('!')) {
+            hasNegation = true
+            break
+          }
+        }
+        if (hasNegation) break
+      }
+
+      if (!hasNegation) continue
+
+      const quantifier = withBlock['predicate-quantifier']
+      if (quantifier !== 'every') {
+        violations.push({
+          jobId,
+          stepIndex: index,
+          reason:
+            quantifier === undefined
+              ? `job '${jobId}' step ${index} uses dorny/paths-filter with negation patterns but is missing predicate-quantifier: every`
+              : `job '${jobId}' step ${index} uses dorny/paths-filter with negation patterns but predicate-quantifier is '${String(quantifier)}' (must be 'every')`,
+        })
+      }
+    }
+  }
+
+  return violations
+}
+
 describe('repo conventions', () => {
   it('tripwire: workflow glob resolves to at least one file (catches dot-dir glob regressions)', () => {
     const workflows = listWorkflowFiles('.yaml')
@@ -314,3 +388,144 @@ jobs:
     expect(findCrossOrgSecretsInherit(parsed)).toEqual([])
   })
 })
+
+describe('findPathsFilterQuantifierViolations', () => {
+  it('paths-filter with negations and predicate-quantifier: every → 0 violations', () => {
+    const yaml = `
+jobs:
+  detect:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          predicate-quantifier: every
+          filters: |
+            app:
+              - 'apps/myapp/**'
+              - '!apps/myapp/**/*.md'
+`
+    expect(findPathsFilterQuantifierViolations(yaml)).toEqual([])
+  })
+
+  it('paths-filter with negations and missing predicate-quantifier → 1 violation', () => {
+    const yaml = `
+jobs:
+  detect:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          filters: |
+            app:
+              - 'apps/myapp/**'
+              - '!apps/myapp/**/*.md'
+`
+    const violations = findPathsFilterQuantifierViolations(yaml)
+    expect(violations).toEqual([
+      {
+        jobId: 'detect',
+        stepIndex: 0,
+        reason: `job 'detect' step 0 uses dorny/paths-filter with negation patterns but is missing predicate-quantifier: every`,
+      },
+    ])
+  })
+
+  it('paths-filter with negations and predicate-quantifier: some → 1 violation', () => {
+    const yaml = `
+jobs:
+  detect:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          predicate-quantifier: some
+          filters: |
+            app:
+              - 'apps/myapp/**'
+              - '!apps/myapp/**/*.md'
+`
+    const violations = findPathsFilterQuantifierViolations(yaml)
+    expect(violations).toEqual([
+      {
+        jobId: 'detect',
+        stepIndex: 0,
+        reason: `job 'detect' step 0 uses dorny/paths-filter with negation patterns but predicate-quantifier is 'some' (must be 'every')`,
+      },
+    ])
+  })
+
+  it('paths-filter without negations → 0 violations regardless of quantifier', () => {
+    const yaml = `
+jobs:
+  detect:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          filters: |
+            app:
+              - 'apps/myapp/**'
+              - 'apps/myapp/**/*.ts'
+`
+    expect(findPathsFilterQuantifierViolations(yaml)).toEqual([])
+  })
+
+  it('bare-string negation filter without predicate-quantifier → 1 violation', () => {
+    const yaml = `
+jobs:
+  detect:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          filters: |
+            cliproxy: '!apps/cliproxy/**/*.md'
+`
+    const violations = findPathsFilterQuantifierViolations(yaml)
+    expect(violations).toEqual([
+      {
+        jobId: 'detect',
+        stepIndex: 0,
+        reason: `job 'detect' step 0 uses dorny/paths-filter with negation patterns but is missing predicate-quantifier: every`,
+      },
+    ])
+  })
+
+  it('bare-string negation filter with predicate-quantifier: every → 0 violations', () => {
+    const yaml = `
+jobs:
+  detect:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          predicate-quantifier: every
+          filters: |
+            cliproxy: '!apps/cliproxy/**/*.md'
+`
+    expect(findPathsFilterQuantifierViolations(yaml)).toEqual([])
+  })
+})
+
+describe('dorny/paths-filter quantifier guard', () => {
+  it('tripwire: workflow glob resolves to at least one file (catches dot-dir glob regressions)', () => {
+    // `.github/` is a dot-directory; Bun.Glob skips dot-dirs by default unless `dot: true` is set.
+    const glob = new Bun.Glob('.github/workflows/**')
+    const files = [...glob.scanSync({cwd: REPO_ROOT, absolute: true, dot: true})]
+    expect(files.length).toBeGreaterThan(0)
+  })
+
+  it('all workflow files using dorny/paths-filter with negations declare predicate-quantifier: every', async () => {
+    const files = listWorkflowFiles('.yaml')
+    expect(files.length).toBeGreaterThan(0)
+
+    const violations: PathsFilterQuantifierViolation[] = []
+    for (const file of files) {
+      const text = await Bun.file(file).text()
+      for (const v of findPathsFilterQuantifierViolations(text)) {
+        violations.push({...v, file: relative(REPO_ROOT, file)})
+      }
+    }
+    expect(violations).toEqual([])
+  })
+})