@kaynooo/cli-docker 0.3.0 → 0.5.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@kaynooo/cli-docker",
   "type": "module",
-  "version": "0.3.0",
-  "description": "dc, dx and sf: docker compose on the stack found here, including one only its containers tell of, a compose service's shell, logs, restart, stop or rebuild, and a Symfony console command picked and run.",
+  "version": "0.5.0",
+  "description": "dc, dx, dlog and sf: docker compose on the stack found here, including one only its containers tell of, a compose service's shell, logs, restart, stop or rebuild, every service's health and recent errors in one call, and a Symfony console command picked and run.",
   "author": "Kaynooo <contact@kaynooo.fr>",
   "license": "MIT",
   "homepage": "https://git.kaynooo.fr/kaynooo/cli/src/branch/main/packages/docker#readme",
@@ -18,6 +18,7 @@
   },
   "bin": {
     "dc": "./dist/dc-cli.js",
+    "dlog": "./dist/dlog-cli.js",
     "dx": "./dist/dx-cli.js",
     "sf": "./dist/sf-cli.js"
   },
@@ -29,12 +30,14 @@
     "registry": "https://git.kaynooo.fr/api/packages/kaynooo/npm/"
   },
   "scripts": {
-    "build": "$npm_execpath build src/dc-cli.ts src/dx-cli.ts src/sf-cli.ts --target bun --outdir dist",
+    "build": "$npm_execpath build src/dc-cli.ts src/dlog-cli.ts src/dx-cli.ts src/sf-cli.ts --target bun --outdir dist",
     "dc": "$npm_execpath src/dc-cli.ts",
+    "dlog": "$npm_execpath src/dlog-cli.ts",
     "dx": "$npm_execpath src/dx-cli.ts",
     "sf": "$npm_execpath src/sf-cli.ts"
   },
   "devDependencies": {
+    "@kaynooo/cli-env": "0.8.1",
     "@kaynooo/cli-kit": "0.20.0"
   }
 }

package/src/dc-cli.ts

@@ -2,7 +2,6 @@
 
 import process from 'node:process'
 import { completion, parse, runMain } from '@kaynooo/cli-kit'
-import { version } from '../package.json'
 import { dc } from './dc'
 
 const usage = `dc [project] <compose args>
@@ -24,4 +23,4 @@ async function main(args: string[]): Promise<number> {
   return dc(args)
 }
 
-process.exitCode = await runMain({ name: 'dc', version, run: main })
+process.exitCode = await runMain({ name: 'dc', run: main })

package/src/dlog-cli.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+
+import process from 'node:process'
+import { runMain } from '@kaynooo/cli-kit'
+import { dlog } from './dlog'
+
+process.exitCode = await runMain({ name: 'dlog', run: dlog })

package/src/dlog.ts

@@ -0,0 +1,219 @@
+import type { KnownSecrets } from '@kaynooo/cli-env/mask'
+import type { ExitRow } from '@kaynooo/cli-kit'
+import type { Container, Service } from './stack'
+import process from 'node:process'
+import { loadKnown } from '@kaynooo/cli-env/files'
+import { maskLine, PEM_BEGIN, PEM_END } from '@kaynooo/cli-env/mask'
+import { badUsage, fail, jsonOption, paint, parse, printJson, stripAnsi, wholeNumber } from '@kaynooo/cli-kit'
+import { allServices, attempt, containers, key, stateColor } from './stack'
+
+const usage = `dlog [service...]
+
+One line per compose service with its state and health, then the last distinct error lines of the services that log some or are not healthy, repeats collapsed to one line with a count and secrets masked as redact does.
+With service names, only those are read. The stacks are the ones dx lists: this folder's, its child folders' and the ones only their containers tell of.
+\`--level warn\` keeps warnings too, \`--grep <regex>\` keeps the lines matching a case insensitive regex instead of the error words. What fails the exit is \`--fail-on\`: by default a service down, unhealthy or still starting, an error line or logs compose could not read, so it can gate a script; \`--fail-on down\` leaves out an old error line that \`--since\` has not aged out yet. A service that exited with code 0 (a migration, an init) is not down.`
+
+const EXITS: ExitRow[] = [[0, 'nothing the --fail-on list names: every service is up and quiet'], [1, 'a service is down, unhealthy or still starting, logged a matching line or has logs compose could not read (as --fail-on keeps them), or there is no compose service here'], [2, 'a usage error']]
+
+const FAIL_ON = ['down', 'unhealthy', 'errors'] as const
+
+type FailOn = typeof FAIL_ON[number]
+
+const options = {
+  'lines': { type: 'string', short: 'n', default: '5', description: 'error lines kept per service' },
+  'since': { type: 'string', default: '1h', description: 'how far back the logs are read (compose --since: 30m, 2h, a timestamp)' },
+  'level': { type: 'string', choices: ['error', 'warn'], default: 'error', description: 'lowest level of the lines kept: error (the default) or warn, warnings too' },
+  'grep': { type: 'string', description: 'keep the lines matching this regex, case insensitive, instead of the --level words' },
+  'fail-on': { type: 'string', multiple: true, choices: FAIL_ON, description: 'what makes the exit 1, repeatable: down, unhealthy or errors (all three)' },
+  'all': { type: 'boolean', short: 'a', description: 'the last log lines of a service with no error too' },
+  'json': jsonOption('[{ key, state, health, status, errors: [{ line, count }], tail, down, unhealthy }]'),
+} as const
+
+const ERROR = /\b(?:error|err|fatal|exception|panic|critical|crit|traceback|failed|failure|refused|denied|timeout|timed out|oom|killed)\b/i
+const WARNING = /\b(?:warn|warning|deprecated|deprecation)\b/i
+const LEVELS = { error: ERROR, warn: new RegExp(`${ERROR.source}|${WARNING.source}`, 'i') }
+const TAIL = 500
+const MAX_WIDTH = 220
+const TIMESTAMP = /\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[.,]\d+)?(?:Z|[+-]\d{2}:?\d{2})?|\d{2}[/-][A-Za-z]{3}[/-]\d{4}:\d{2}:\d{2}:\d{2}(?: [+-]\d{4})?|\d{2}:\d{2}:\d{2}(?:[.,]\d+)?/g
+const IDENTIFIER = /\b(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|0x[0-9a-f]+|[0-9a-f]{12,})\b/gi
+const NUMBER = /\d+/g
+const STATUS_HEALTH = /\((healthy|unhealthy|health: starting)\)/
+const LEADING_BRACKETS = /^(?:\[\s*\]|\s)+/
+
+export interface ErrorLine {
+  line: string
+  count: number
+}
+
+/** The line two occurrences of the same message share: no timestamp, id or number. */
+function shape(line: string): string {
+  return line.replace(TIMESTAMP, '').replace(IDENTIFIER, '#').replace(NUMBER, '#').replace(LEADING_BRACKETS, '').trim()
+}
+
+function clip(line: string): string {
+  return line.length > MAX_WIDTH ? `${line.slice(0, MAX_WIDTH - 1)}…` : line
+}
+
+/** The last `limit` distinct lines of a log matching `matches`, oldest first, each as its latest occurrence with how often its message came up, secrets masked. */
+export function errorLines(log: string, limit: number, known?: KnownSecrets, matches: RegExp = ERROR): ErrorLine[] {
+  const seen = new Map<string, ErrorLine>()
+
+  for (const raw of log.split('\n')) {
+    const line = stripAnsi(raw).trim()
+
+    if (line === '' || !matches.test(line))
+      continue
+
+    const shared = shape(line)
+    const before = seen.get(shared)
+
+    // Re-inserted so the Map's order is the order of the latest occurrences.
+    seen.delete(shared)
+    seen.set(shared, { line: clip(maskLine(line, known)), count: (before?.count ?? 0) + 1 })
+  }
+
+  return [...seen.values()].slice(-limit)
+}
+
+export interface Health {
+  /** `healthy`, `unhealthy`, `starting`, or empty when the container has no healthcheck. */
+  health: string
+  /** Whether the service is up and, when it has a healthcheck, healthy. */
+  fine: boolean
+}
+
+/** Whether the service runs, or ended cleanly (exit code 0) as a migration does. */
+export function isUp(state: string, container: Container | undefined): boolean {
+  return state === 'running' || (state === 'exited' && container?.ExitCode === 0)
+}
+
+export function healthOf(state: string, container: Container | undefined): Health {
+  const health = (container?.Health ?? '') || (STATUS_HEALTH.exec(container?.Status ?? '')?.[1]?.replace('health: ', '') ?? '')
+
+  return { health, fine: isUp(state, container) && (health === '' || health === 'healthy') }
+}
+
+export interface Report {
+  key: string
+  state: string
+  health: string
+  status: string
+  errors: ErrorLine[]
+  tail: string[]
+  /** Why compose could not list the service or read its logs. */
+  unreadable: string | undefined
+  fine: boolean
+  /** Not running, and not a clean exit. */
+  down: boolean
+  /** Up, but unhealthy or still starting. */
+  unhealthy: boolean
+}
+
+/** Whether the report fails the exit for what `failOn` names; logs compose could not read count as down and as errors alike. */
+export function needsLook(report: Report, failOn: ReadonlySet<FailOn>): boolean {
+  return (failOn.has('down') && (report.down || report.unreadable !== undefined))
+    || (failOn.has('unhealthy') && report.unhealthy)
+    || (failOn.has('errors') && (report.errors.length > 0 || report.unreadable !== undefined))
+}
+
+function matcherOf(level: keyof typeof LEVELS, grep: string | undefined): RegExp {
+  if (grep === undefined)
+    return LEVELS[level]
+
+  try {
+    return new RegExp(grep, 'i')
+  }
+  catch {
+    return badUsage(`--grep takes a regex, ${grep} is not one`)
+  }
+}
+
+async function read(service: Service, since: string): Promise<{ log: string, container: Container | undefined, unreadable: string | undefined }> {
+  const [ps, logs] = await Promise.all([
+    attempt(service.stack, ['ps', '--all', '--format', 'json', service.name]),
+    attempt(service.stack, ['logs', '--no-color', '--no-log-prefix', `--tail=${TAIL}`, `--since=${since}`, service.name]),
+  ])
+
+  return { log: logs.text, container: containers(ps.text)[0], unreadable: ps.error ?? logs.error }
+}
+
+/** The lines of a log without the body of a private key. */
+export function withoutKeys(lines: string[]): string[] {
+  let inKey = false
+
+  return lines.filter((text) => {
+    const opens = PEM_BEGIN.test(text)
+    const hidden = inKey || opens
+
+    inKey = (inKey || opens) && !PEM_END.test(text)
+
+    return !hidden
+  })
+}
+
+function line(report: Report): string {
+  const colors = paint(process.stdout)
+  const status = report.status.replace(STATUS_HEALTH, '').trim()
+  const detail = [report.health, status].filter(Boolean).join(' · ')
+
+  return `${report.key.padEnd(24)} ${colors[stateColor(report.state)](report.state.padEnd(9))} ${colors.dim(detail)}`.trimEnd()
+}
+
+function show(reports: Report[]): void {
+  const colors = paint(process.stdout)
+
+  for (const report of reports) {
+    console.log(line(report))
+
+    if (report.unreadable !== undefined)
+      console.log(`  ${colors.red(`logs unavailable: ${report.unreadable}`)}`)
+
+    for (const { line: text, count } of report.errors)
+      console.log(`  ${colors.red(text)}${count > 1 ? colors.dim(` ×${count}`) : ''}`)
+
+    for (const text of report.tail)
+      console.log(`  ${colors.dim(text)}`)
+  }
+}
+
+export async function dlog(args: string[]): Promise<number> {
+  const parsed = parse(args, usage, options, { exits: EXITS, replaces: 'docker compose ps, logs --tail | grep -i error and docker inspect for health', examples: ['dlog', ['dlog php db', 'only those services'], ['dlog -n 10 --since 15m', 'ten error lines of the last quarter of an hour'], ['dlog --level warn', 'warnings too'], ['dlog --grep "timeout|5\\d\\d"', 'the lines matching a regex'], ['dlog --fail-on down --fail-on unhealthy', 'a gate that ignores old errors'], ['dlog --json', 'the report as JSON']] })
+  const limit = wholeNumber(parsed.values.lines, 'lines', 5)
+  const matches = matcherOf(parsed.values.level === 'warn' ? 'warn' : 'error', parsed.values.grep)
+  const failOn = new Set<FailOn>((parsed.values['fail-on'] ?? []).length > 0 ? parsed.values['fail-on'] ?? FAIL_ON : FAIL_ON)
+  const known = await loadKnown()
+
+  const services = await allServices()
+
+  if (services.length === 0)
+    fail('no compose service here', 1)
+
+  const wanted = parsed.positionals
+  const unknown = wanted.filter(name => !services.some(service => key(service) === name || service.name === name))
+
+  if (unknown.length > 0)
+    fail(`no service named ${unknown.join(', ')}`, 1)
+
+  const chosen = wanted.length === 0 ? services : services.filter(service => wanted.includes(key(service)) || wanted.includes(service.name))
+  const reports: Report[] = await Promise.all(chosen.map(async (service) => {
+    const { log, container, unreadable } = await read(service, parsed.values.since)
+    const { health, fine } = healthOf(service.state, container)
+    const lines = withoutKeys(log.split('\n'))
+    const errors = errorLines(lines.join('\n'), limit, known, matches)
+    const tail = parsed.values.all === true && errors.length === 0 ? lines.map(text => clip(maskLine(stripAnsi(text).trim(), known))).filter(Boolean).slice(-limit) : []
+
+    return { key: key(service), state: service.state, health, status: service.status, errors, tail, unreadable, fine, down: !isUp(service.state, container), unhealthy: isUp(service.state, container) && !fine }
+  }))
+
+  if (parsed.values.json === true)
+    printJson(reports)
+  else
+    show(reports)
+
+  const down = reports.filter(report => needsLook(report, failOn))
+
+  if (parsed.values.json !== true && down.length > 0)
+    console.error(paint(process.stderr).dim(`${down.length} of ${reports.length} services need a look: ${down.map(report => report.key).join(', ')}`))
+
+  return down.length > 0 ? 1 : 0
+}

package/src/dx-cli.ts

@@ -2,7 +2,6 @@
 
 import process from 'node:process'
 import { runMain } from '@kaynooo/cli-kit'
-import { version } from '../package.json'
 import { dx } from './dx'
 
-process.exitCode = await runMain({ name: 'dx', version, run: dx })
+process.exitCode = await runMain({ name: 'dx', run: dx })

package/src/dx.ts

@@ -1,21 +1,26 @@
+import type { ExitRow } from '@kaynooo/cli-kit'
 import type { Action, Service } from './stack'
 import process from 'node:process'
-import { closest, fail, jsonOption, paint, parse, printJson } from '@kaynooo/cli-kit'
+import { loadKnown } from '@kaynooo/cli-env/files'
+import { Redactor } from '@kaynooo/cli-env/redactor'
+import { closest, fail, jsonOption, paint, parse, printJson, wholeNumber } from '@kaynooo/cli-kit'
 import { byRecency, record, runs } from '@kaynooo/cli-kit/fzf'
 import { KEY_LABELS, KEYS, pickService } from './picker'
-import { ACTIONS, allServices, commandFor, defaultAction, key, logsOf, serviceNamed, stateColor } from './stack'
+import { ACTIONS, allServices, commandFor, defaultAction, key, LOGS_TAIL, logsOf, serviceNamed, stateColor } from './stack'
 
 const usage = `dx [service] [action]
 dx -
 
-Without a service, picks one with fzf when it is installed and a terminal is attached: enter opens its shell (or brings a stopped service up), ctrl-l follows its logs, ctrl-r restarts, ctrl-x stops and ctrl-b rebuilds it. The services last acted on come first, per folder. Without fzf or a terminal it lists them instead.
-\`dx -\` does the last action again, \`dx <service> [action]\` acts without the picker: \`shell\` (bash when the container has it), \`logs\` (follows the last 200 lines), \`restart\`, \`up\`, \`stop\` or \`build\` (up with a rebuild).
-The services are the stack of this folder or its nearest parent, the ones of the child folders (keyed \`api/php\`), and stacks found only through their containers (keyed \`<project>:php\`).
+Without a terminal or without fzf (a script, a pipe, an agent) \`dx\` lists the services with their state, ports and image: that listing is the form to use there, \`--json\` giving the full record. On a terminal with fzf it picks one instead: enter opens its shell (or brings a stopped service up), ctrl-l follows its logs, ctrl-r restarts, ctrl-x stops and ctrl-b rebuilds it. The services last acted on come first, per folder.
+\`dx -\` does the last action again, \`dx <service> [action]\` acts without the picker: \`shell\` (bash when the container has it), \`logs\` (follows the last ${LOGS_TAIL} lines; \`--tail N\` changes the count and \`--no-follow\` prints them once and exits, for a script), \`restart\`, \`up\`, \`stop\` or \`build\` (up with a rebuild).
+The services are the stack of this folder or its nearest parent, the ones of the child folders (keyed \`api/php\`), and stacks found only through their containers (keyed \`<project>:php\`).`
 
-Exits with the code of the command it ran, 1 when there is no compose service here or none by that name.`
+const EXITS: ExitRow[] = [['the code of the command it ran', 'a listing, a shell, logs, restart, up, stop or build'], [0, 'it listed the services'], [1, 'no compose service here or none by that name'], [2, 'a usage error']]
 
 const options = {
   json: jsonOption('[{ key, project, name, state, status, ports, image }]'),
+  tail: { type: 'string', description: `log lines shown by the logs action (${LOGS_TAIL})` },
+  follow: { type: 'boolean', negative: 'print the logs once and exit instead of following them' },
 } as const
 
 function table(services: Service[]): string {
@@ -88,6 +93,27 @@ async function hidden(flag: string, rest: string[], services: Service[]): Promis
   return undefined
 }
 
+/** The logs command with its output piped through `redact`, for the picker that runs the words itself; refused when `redact` is missing rather than leaking the logs. */
+export function maskedLogs(command: string[], redactPath: string | null = Bun.which('redact')): string[] {
+  if (redactPath === null)
+    fail('redact is not installed, so the logs would not be masked', 1)
+
+  return ['sh', '-c', '"$@" | redact', 'sh', ...command]
+}
+
+export async function followMasked(command: string[]): Promise<number> {
+  const redactor = new Redactor(await loadKnown())
+  const decoder = new TextDecoder()
+  const proc = Bun.spawn(command, { stdio: ['inherit', 'pipe', 'inherit'] })
+
+  for await (const chunk of proc.stdout)
+    process.stdout.write(redactor.push(decoder.decode(chunk, { stream: true })))
+
+  process.stdout.write(redactor.end())
+
+  return proc.exited
+}
+
 export async function dx(args: string[]): Promise<number> {
   const [flag = ''] = args
 
@@ -102,7 +128,7 @@ export async function dx(args: string[]): Promise<number> {
 
   // The protocol the tmux picker reads instead of running the command: its mode, the words typed back, and the command's words.
   const emit = flag === '--emit'
-  const parsed = parse(emit ? args.slice(1) : args, usage, options, { replaces: 'docker compose exec <service> bash, logs -f and restart typed per service', examples: ['dx', ['dx php', 'a shell in php, or php brought up when stopped'], ['dx php logs', 'follow its logs'], ['dx -', 'the last action again']] })
+  const parsed = parse(emit ? args.slice(1) : args, usage, options, { allowNegative: true, exits: EXITS, replaces: 'docker compose exec <service> bash, logs -f and restart typed per service', examples: ['dx', ['dx php', 'a shell in php, or php brought up when stopped'], ['dx php logs', 'follow its logs'], ['dx php logs --tail 50 --no-follow', 'the last 50 lines, then exit'], ['dx -', 'the last action again']] })
   const [named, asked] = parsed.positionals
   const services = await allServices()
 
@@ -158,15 +184,20 @@ export async function dx(args: string[]): Promise<number> {
   }
 
   const chosen = action ?? defaultAction(service)
-  const command = await commandFor(service, chosen)
+  const { tail, follow } = parsed.values
+
+  if ((tail !== undefined || follow !== undefined) && chosen !== 'logs')
+    fail('--tail and --no-follow apply to the logs action: dx <service> logs')
+
+  const command = await commandFor(service, chosen, { tail: tail === undefined ? undefined : wholeNumber(tail, 'tail', LOGS_TAIL, 0), follow })
 
   record('dx', { id: key(service), args: [chosen] })
 
   if (emit) {
-    console.log(['run', action === undefined ? key(service) : `${key(service)} ${action}`, '', ...command.map(word => `=${word}`)].join('\n'))
+    console.log(['run', action === undefined ? key(service) : `${key(service)} ${action}`, '', ...(chosen === 'logs' ? maskedLogs(command) : command).map(word => `=${word}`)].join('\n'))
 
     return 0
   }
 
-  return Bun.spawn(command, { stdio: ['inherit', 'inherit', 'inherit'] }).exited
+  return chosen === 'logs' ? followMasked(command) : Bun.spawn(command, { stdio: ['inherit', 'inherit', 'inherit'] }).exited
 }

package/src/sf-cli.ts

@@ -2,7 +2,6 @@
 
 import process from 'node:process'
 import { runMain } from '@kaynooo/cli-kit'
-import { version } from '../package.json'
 import { sf } from './sf'
 
-process.exitCode = await runMain({ name: 'sf', version, run: sf })
+process.exitCode = await runMain({ name: 'sf', run: sf })

package/src/sf.ts

@@ -1,9 +1,10 @@
+import type { ExitRow } from '@kaynooo/cli-kit'
 import type { Arg, Row } from '@kaynooo/cli-kit/fzf'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import process from 'node:process'
-import { fail, paint, parse } from '@kaynooo/cli-kit'
+import { fail, paint, parse, printJson } from '@kaynooo/cli-kit'
 import { byRecency, emit, fzf, list, record, runs, table } from '@kaynooo/cli-kit/fzf'
 import { input } from '@kaynooo/cli-kit/prompt'
 import { children, from, nearestStack, services, up } from './stack'
@@ -47,12 +48,13 @@ export interface Entry {
 const usage = `sf [command] [args...]
 sf -
 
-Picks a Symfony console command with fzf and runs it, asking for each required argument it needs. The commands last run come first, per folder, and the picker opens on the list cached from the last run while the console answers.
+Without a terminal or without fzf (a script, a pipe, an agent) \`sf\` lists the commands, one per line with its description: that listing is the form to use there, and \`sf --list --json\` gives each with its arguments and options. On a terminal with fzf it picks a Symfony console command instead and runs it, asking for each required argument it needs. The commands last run come first, per folder, and the picker opens on the list cached from the last run while the console answers.
 The console is the nearest bin/console up to the repository root, then those of the child folders (keyed \`api/cache:clear\`). It runs in the php service of the nearest compose stack when there is one, else with the local php; the container's working directory is taken to be the app.
-\`sf -\` runs the last command again with the arguments it ran with, \`sf <command> [args...]\` runs without the picker: a name the list does not hold goes to the console as is, which resolves \`c:c\` to \`cache:clear\` itself. Without fzf or a terminal it lists the commands instead.
-The hidden flags --list, --names, --rows, --show, --record and --emit are for term, tmux and the shell completions.
+\`sf -\` runs the last command again with the arguments it ran with, \`sf <command> [args...]\` runs without the picker: a name the list does not hold goes to the console as is, which resolves \`c:c\` to \`cache:clear\` itself.
+\`sf --list --json\` (or \`sf --json\`) prints every command as JSON, each with its console folder, description, signature, arguments and options.
+The hidden flags --list, --names, --rows, --show, --record and --emit are for term, tmux and the shell completions.`
 
-Exits with the code of the console, 1 when there is no bin/console here.`
+const EXITS: ExitRow[] = [['the code of the console', 'a command it ran'], [0, 'it listed the commands'], [1, 'no bin/console here, or it listed no command'], [2, 'a usage error']]
 
 /** Fzf paints its rows and previews itself, so these keep their colors whatever stream they are written to. */
 const colors = paint({ isTTY: true })
@@ -109,14 +111,21 @@ function fromCache(dir: string): Command[] | undefined {
   }
 }
 
-async function live(app: Console): Promise<Command[]> {
+export async function live(app: Console): Promise<Command[]> {
   const proc = Bun.spawn([...app.list.argv, 'list', '--format=json'], { cwd: app.list.cwd, env: app.list.env, stdout: 'pipe', stderr: 'pipe' })
   const text = await new Response(proc.stdout).text()
 
   if ((await proc.exited) !== 0)
     return fromCache(app.dir) ?? []
 
-  const commands = (JSON.parse(text) as { commands: Command[] }).commands.filter(command => !command.hidden)
+  let commands: Command[]
+
+  try {
+    commands = (JSON.parse(text) as { commands: Command[] }).commands.filter(command => !command.hidden)
+  }
+  catch {
+    return fromCache(app.dir) ?? []
+  }
 
   mkdirSync(dirname(cached(app.dir)), { recursive: true })
   writeFileSync(cached(app.dir), JSON.stringify(commands))
@@ -150,6 +159,21 @@ export function signature(command: Command): string {
     .join(' ')
 }
 
+/** A command as `sf --json` prints it, the arguments and options of the console's own definition. */
+export function entryJson(entry: Entry) {
+  const { command } = entry
+
+  return {
+    name: key(entry),
+    command: command.name,
+    dir: entry.app.dir,
+    description: command.description,
+    signature: signature(command),
+    arguments: argumentsOf(command).map(argument => ({ name: argument.name, required: argument.is_required, array: argument.is_array, description: argument.description })),
+    options: optionsOf(command).map(option => ({ name: option.name, shortcut: option.shortcut, acceptsValue: option.accept_value, description: option.description })),
+  }
+}
+
 function rows(found: Entry[]): Row[] {
   return byRecency(found, runs('sf'), key).map(entry => ({
     hidden: [entry.app.dir, entry.command.name],
@@ -293,6 +317,15 @@ async function hidden(flag: string, rest: string[]): Promise<number | undefined>
 
 export async function sf(args: string[]): Promise<number> {
   const [flag = ''] = args
+
+  if (args.length <= 2 && args.includes('--json') && (flag === '--json' || flag === '--list')) {
+    const found = await entries(false)
+
+    printJson(byRecency(found, runs('sf'), key).map(entryJson))
+
+    return 0
+  }
+
   const flagged = await hidden(flag, args.slice(1))
 
   if (flagged !== undefined)
@@ -305,6 +338,7 @@ export async function sf(args: string[]): Promise<number> {
   const parsed = parse(last ? [] : words, usage, {}, {
     positionals: ['[command]'],
     trailing: true,
+    exits: EXITS,
     replaces: 'bin/console typed in the php container, with the command names and arguments looked up by hand',
     examples: ['sf', ['sf cache:clear', 'run it without the picker'], ['sf c:c --env=prod', 'the console resolves abbreviations itself'], ['sf -', 'the last command again, with its arguments']],
   })

package/src/stack.ts

@@ -1,5 +1,9 @@
+import type { KnownSecrets } from '@kaynooo/cli-env/mask'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { dirname, join, relative, resolve } from 'node:path'
+import { loadKnown } from '@kaynooo/cli-env/files'
+import { Redactor } from '@kaynooo/cli-env/redactor'
+import { captureOutput, composeError } from '@kaynooo/cli-kit'
 
 /** How to reach one compose project: the command a user runs, and the one this package lists it with. */
 export interface Stack {
@@ -42,6 +46,9 @@ export interface Container {
   Service: string
   State: string
   Status: string
+  /** Empty for a container with no healthcheck. */
+  Health?: string
+  ExitCode?: number
 }
 
 const LABEL_FORMAT = ['project', 'project.config_files', 'project.environment_file', 'project.working_dir'].map(label => `{{.Label "com.docker.compose.${label}"}}`).join('\t')
@@ -158,10 +165,15 @@ export async function recordedNearby(): Promise<Labels[]> {
   return (await labels()).filter(stack => dirs.has(stack.workdir))
 }
 
-async function output(stack: Stack, args: string[]): Promise<string> {
-  const proc = Bun.spawn([...stack.list.argv, ...args], { cwd: stack.list.cwd, env: stack.list.env, stdout: 'pipe', stderr: 'pipe' })
+/** What compose printed, and its stderr when it exited non-zero. */
+export async function attempt(stack: Stack, args: string[]): Promise<{ text: string, error: string | undefined }> {
+  const result = await captureOutput([...stack.list.argv, ...args], { cwd: stack.list.cwd, env: stack.list.env })
 
-  return (await proc.exited) === 0 ? new Response(proc.stdout).text() : ''
+  return result.code === 0 ? { text: result.stdout, error: undefined } : { text: '', error: composeError(result) }
+}
+
+async function output(stack: Stack, args: string[]): Promise<string> {
+  return (await attempt(stack, args)).text
 }
 
 /** Compose prints one container per line, where older versions printed a JSON array. */
@@ -216,14 +228,21 @@ async function shellOf(service: Service): Promise<string> {
   return (await output(service.stack, ['exec', '-T', service.name, 'sh', '-c', 'command -v bash'])) ? 'bash' : 'sh'
 }
 
-export async function commandFor(service: Service, action: Action): Promise<string[]> {
+export const LOGS_TAIL = 200
+
+export interface LogsOptions {
+  tail?: number | undefined
+  follow?: boolean | undefined
+}
+
+export async function commandFor(service: Service, action: Action, logs: LogsOptions = {}): Promise<string[]> {
   const run = service.stack.run
 
   switch (action) {
     case 'shell':
       return [...run, 'exec', service.name, await shellOf(service)]
     case 'logs':
-      return [...run, 'logs', '-f', '--tail=200', service.name]
+      return [...run, 'logs', ...logs.follow === false ? [] : ['-f'], `--tail=${logs.tail ?? LOGS_TAIL}`, service.name]
     case 'restart':
       return [...run, 'restart', service.name]
     case 'up':
@@ -259,7 +278,14 @@ export async function serviceNamed(dir: string, name: string, project: string):
   return (await services(stack)).find(candidate => candidate.name === name)
 }
 
-// Compose's own words for its output of one service, the last lines of its logs.
+/** A whole log with its secrets masked as `redact` does. */
+export function maskLog(text: string, known?: KnownSecrets): string {
+  const redactor = new Redactor(known)
+
+  return redactor.push(text) + redactor.end()
+}
+
+// Compose's own words for its output of one service, the last lines of its logs, secrets masked.
 export async function logsOf(stack: Stack, name: string): Promise<string> {
-  return output(stack, ['logs', '--tail=30', '--no-log-prefix', name])
+  return maskLog(await output(stack, ['logs', '--tail=30', '--no-log-prefix', name]), await loadKnown())
 }