@kaynooo/cli-docker 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@kaynooo/cli-docker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.2.0",
+  "description": "dc and dx: docker compose on the stack found here, including one only its containers tell of, and a compose service's shell, logs, restart, stop or rebuild.",
+  "author": "Kaynooo <contact@kaynooo.fr>",
+  "license": "MIT",
+  "homepage": "https://git.kaynooo.fr/kaynooo/cli/src/branch/main/packages/docker#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.kaynooo.fr/kaynooo/cli.git",
+    "directory": "packages/docker"
+  },
+  "bugs": "https://git.kaynooo.fr/kaynooo/cli/issues",
+  "keywords": ["docker", "compose", "cli", "bun"],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "dc": "./dist/dc-cli.js",
+    "dx": "./dist/dx-cli.js"
+  },
+  "files": ["dist", "src"],
+  "engines": {
+    "bun": ">=1.4.3"
+  },
+  "publishConfig": {
+    "registry": "https://git.kaynooo.fr/api/packages/kaynooo/npm/"
+  },
+  "scripts": {
+    "build": "$npm_execpath build src/dc-cli.ts src/dx-cli.ts --target bun --outdir dist",
+    "dc": "$npm_execpath src/dc-cli.ts",
+    "dx": "$npm_execpath src/dx-cli.ts"
+  },
+  "devDependencies": {
+    "@kaynooo/cli-kit": "0.20.0"
+  }
+}

package/src/dc-cli.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env bun
+
+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>
+
+Runs docker compose on the stack found here: the nearest compose file or .env setting COMPOSE_FILE up to the repository root, else the only stack with containers here.
+A first word naming a compose project with containers here runs on that project, with the files and env file it came up with (\`dc dash logs\`); the command it stands for is shown on stderr.
+Takes no option of its own: every word reaches compose as typed, \`dc --help\` alone excepted.
+
+Exits with the code of compose, 1 when several stacks have containers here and none is named.`
+
+// A passthrough to compose: only a lone --help or a completion is dc's own, every other word reaches compose as typed.
+async function main(args: string[]): Promise<number> {
+  if (completion.active || (args.length === 1 && (args[0] === '--help' || args[0] === '-h'))) {
+    parse(args, usage, {}, { replaces: 'docker compose -f docker-compose.prod.yaml --env-file .env.prod, typed again for each stack', examples: ['dc up -d', ['dc dash logs -f', 'a stack that came up from other files']] })
+
+    return 0
+  }
+
+  return dc(args)
+}
+
+process.exitCode = await runMain({ name: 'dc', version, run: main })

package/src/dc.ts

@@ -0,0 +1,75 @@
+import type { Labels, Stack } from './stack'
+import process from 'node:process'
+import { paint } from '@kaynooo/cli-kit'
+import { nearestStack, recordedNearby, stackAt, stackOf } from './stack'
+
+// The words a compose command starts with, which never name a stack, so the containers are not listed to check.
+const COMMANDS = new Set(['alpha', 'attach', 'bridge', 'build', 'commit', 'config', 'cp', 'create', 'down', 'events', 'exec', 'export', 'help', 'images', 'kill', 'logs', 'ls', 'pause', 'port', 'ps', 'publish', 'pull', 'push', 'restart', 'rm', 'run', 'scale', 'start', 'stats', 'stop', 'top', 'unpause', 'up', 'version', 'volumes', 'wait', 'watch'])
+
+export type Target
+  = | { kind: 'stack', stack: Stack, args: string[], announce: boolean }
+    | { kind: 'choose', recorded: Labels[], args: string[] }
+
+// Which stack `dc <args>` runs on: one named by a first word, the nearest compose file, or the only one with containers here.
+export async function target(args: string[]): Promise<Target> {
+  const [first = '', ...rest] = args
+  const recorded = first.startsWith('-') || COMMANDS.has(first) ? undefined : await recordedNearby()
+  const chosen = recorded?.find(stack => stack.project === first)
+
+  if (chosen)
+    return { kind: 'stack', stack: stackOf(chosen), args: rest, announce: true }
+
+  const nearest = nearestStack('.')
+
+  if (nearest)
+    return { kind: 'stack', stack: nearest, args, announce: false }
+
+  const withContainers = recorded ?? await recordedNearby()
+
+  if (withContainers.length === 1)
+    return { kind: 'stack', stack: stackOf(withContainers[0]!), args, announce: true }
+
+  if (withContainers.length > 1)
+    return { kind: 'choose', recorded: withContainers, args }
+
+  return { kind: 'stack', stack: stackAt('.'), args, announce: false }
+}
+
+// The project picked with `pick` when it is installed, which draws on stderr and prints the choice.
+async function choose(recorded: Labels[]): Promise<Labels | undefined> {
+  const picker = Bun.which('pick')
+
+  if (picker === null || !process.stdin.isTTY)
+    return undefined
+
+  const proc = Bun.spawn([picker, '--prompt', 'dc> '], { stdin: new Blob([recorded.map(stack => stack.project).join('\n')]), stdout: 'pipe', stderr: 'inherit' })
+  const picked = (await new Response(proc.stdout).text()).trim()
+
+  return recorded.find(stack => stack.project === picked)
+}
+
+async function run(stack: Stack, args: string[], announce: boolean): Promise<number> {
+  // The command it stands for, above its output, since nothing in `dc` says which files it took.
+  if (announce && process.stderr.isTTY)
+    console.error(paint(process.stderr).dim([...stack.run, ...args].join(' ')))
+
+  return Bun.spawn([...stack.list.argv, ...args], { cwd: stack.list.cwd, env: stack.list.env, stdio: ['inherit', 'inherit', 'inherit'] }).exited
+}
+
+// docker compose on the stack found here, with what it came up with when only its containers tell of it.
+export async function dc(args: string[]): Promise<number> {
+  const found = await target(args)
+
+  if (found.kind === 'stack')
+    return run(found.stack, found.args, found.announce)
+
+  const recorded = await choose(found.recorded)
+
+  if (!recorded) {
+    console.error(`several stacks here, name one first: ${found.recorded.map(stack => stack.project).join(', ')}`)
+
+    return 1
+  }
+
+  return run(stackOf(recorded), found.args, true)
+}

package/src/dx-cli.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+
+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 })

package/src/dx.ts

@@ -0,0 +1,172 @@
+import type { Action, Service } from './stack'
+import process from 'node:process'
+import { closest, fail, jsonOption, paint, parse, printJson } from '@kaynooo/cli-kit'
+import { byRecency, record, runs } from './history'
+import { KEY_LABELS, KEYS, pickService } from './picker'
+import { ACTIONS, allServices, commandFor, defaultAction, key, 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\`).
+
+Exits with the code of the command it ran, 1 when there is no compose service here or none by that name.`
+
+const options = {
+  json: jsonOption('[{ key, project, name, state, status, ports, image }]'),
+} as const
+
+function table(services: Service[]): string {
+  const colors = paint(process.stdout)
+  const keys = services.map(key)
+  const width = Math.max(...keys.map(name => name.length))
+  const states = Math.max(...services.map(service => service.state.length))
+
+  return services.map((service, index) => [
+    keys[index]!.padEnd(width),
+    colors[stateColor(service.state)](service.state.padEnd(states)),
+    colors.cyan(service.ports),
+    colors.dim(service.image),
+  ].join('  ').trimEnd()).join('\n')
+}
+
+// This folder's service first, then the same name in a child folder.
+function find(services: Service[], named: string): Service {
+  const found = services.find(service => key(service) === named) ?? services.find(service => service.name === named)
+
+  if (found !== undefined)
+    return found
+
+  const nearest = closest(named, services.map(key))
+
+  return fail(`no service named ${named}${nearest === undefined ? '' : `, did you mean ${nearest}?`}`, 1)
+}
+
+// The rows term lists in place of the picker: what it types back for enter and for each key.
+function listed(services: Service[]): unknown[] {
+  return byRecency(services, runs(), key).map(service => ({
+    label: key(service),
+    hint: [service.state, service.ports, service.image].filter(Boolean).join(' · '),
+    typed: key(service),
+    preview: ['--show', service.stack.dir, service.name, service.stack.project ?? ''],
+    actions: Object.entries(KEYS).map(([pressed, action]) => ({ label: KEY_LABELS[pressed] ?? action, key: pressed, typed: `${key(service)} ${action}` })),
+  }))
+}
+
+// The hidden flags term and the shell completions call, each printing and nothing more.
+async function hidden(flag: string, rest: string[], services: Service[]): Promise<number | undefined> {
+  if (flag === '--list') {
+    console.log(JSON.stringify(listed(services)))
+
+    return 0
+  }
+
+  // With the state as the description fish shows beside each name.
+  if (flag === '--names') {
+    console.log(services.map(service => `${key(service)}\t${service.state}`).join('\n'))
+
+    return 0
+  }
+
+  if (flag === '--show') {
+    const [dir = '.', name = '', project = ''] = rest
+    const service = await serviceNamed(dir, name, project)
+
+    if (service === undefined)
+      return 0
+
+    const colors = paint(process.stdout)
+
+    console.log(`${colors[stateColor(service.state)](service.status || service.state)}  ${colors.dim(service.image)}${service.ports ? `  ${colors.cyan(service.ports)}` : ''}\n`)
+    console.log(await logsOf(service.stack, name))
+
+    return 0
+  }
+
+  return undefined
+}
+
+export async function dx(args: string[]): Promise<number> {
+  const [flag = ''] = args
+
+  if (flag === '--show' || flag === '--list' || flag === '--names') {
+    const services = flag === '--show' ? [] : await allServices()
+
+    if (services.length === 0 && flag !== '--show')
+      fail('no compose service here', 1)
+
+    return await hidden(flag, args.slice(1), services) ?? 0
+  }
+
+  // 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 [named, asked] = parsed.positionals
+  const services = await allServices()
+
+  if (services.length === 0)
+    fail('no compose service here', 1)
+
+  let service: Service | undefined
+  let action: Action | undefined
+
+  if (named === undefined) {
+    const interactive = process.stdin.isTTY && process.stderr.isTTY && parsed.values.json !== true
+
+    if (!interactive || Bun.which('fzf') === null) {
+      if (emit)
+        fail('the picker needs a terminal and fzf', 1)
+
+      if (interactive)
+        console.error('fzf is not installed, listing the services instead')
+
+      if (parsed.values.json === true)
+        printJson(services.map(each => ({ key: key(each), project: each.project, name: each.name, state: each.state, status: each.status, ports: each.ports, image: each.image })))
+      else
+        console.log(table(services))
+
+      return 0
+    }
+
+    const picked = pickService(byRecency(services, runs(), key))
+
+    if (picked === undefined)
+      return 1
+
+    service = picked.service
+    action = KEYS[picked.key]
+  }
+  else if (named === '-') {
+    const last = runs()[0]
+
+    service = last && services.find(candidate => key(candidate) === last.id)
+
+    if (service === undefined)
+      fail(last ? `${last.id} is gone` : 'nothing done here yet', 1)
+
+    action = last!.args[0] as Action | undefined
+  }
+  else {
+    service = find(services, named)
+
+    if (asked !== undefined && !ACTIONS.includes(asked as Action))
+      fail(`no action ${asked}, one of ${ACTIONS.join(', ')}`)
+
+    action = asked as Action | undefined
+  }
+
+  const chosen = action ?? defaultAction(service)
+  const command = await commandFor(service, chosen)
+
+  record({ id: key(service), args: [chosen] })
+
+  if (emit) {
+    console.log(['run', action === undefined ? key(service) : `${key(service)} ${action}`, '', ...command.map(word => `=${word}`)].join('\n'))
+
+    return 0
+  }
+
+  return Bun.spawn(command, { stdio: ['inherit', 'inherit', 'inherit'] }).exited
+}

package/src/history.ts

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+
+export interface Run {
+  id: string
+  args: string[]
+}
+
+const REMEMBERED = 20
+
+function historyFile(): string {
+  return join(process.env.XDG_CACHE_HOME ?? join(homedir(), '.cache'), 'dx', 'history.json')
+}
+
+// Keyed by folder, a broken or missing file reading as nothing run yet.
+function history(): Record<string, Run[]> {
+  try {
+    const file = historyFile()
+
+    return existsSync(file) ? JSON.parse(readFileSync(file, 'utf-8')) as Record<string, Run[]> : {}
+  }
+  catch {
+    return {}
+  }
+}
+
+export function runs(): Run[] {
+  return history()[process.cwd()] ?? []
+}
+
+export function record(run: Run): void {
+  const all = history()
+  const file = historyFile()
+
+  all[process.cwd()] = [run, ...(all[process.cwd()] ?? []).filter(earlier => earlier.id !== run.id)].slice(0, REMEMBERED)
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, JSON.stringify(all))
+}
+
+// The ones run last come first, most recent at the top, the rest keeping their order.
+export function byRecency<T>(items: T[], previous: Run[], idOf: (item: T) => string): T[] {
+  const rank = new Map(previous.map((run, index) => [run.id, index]))
+  const recent = items.filter(item => rank.has(idOf(item))).sort((a, b) => rank.get(idOf(a))! - rank.get(idOf(b))!)
+
+  return [...recent, ...items.filter(item => !rank.has(idOf(item)))]
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './dc'
+export * from './stack'

package/src/picker.ts

@@ -0,0 +1,67 @@
+import type { Action, Service } from './stack'
+import process from 'node:process'
+import { paint } from '@kaynooo/cli-kit'
+import { key, stateColor } from './stack'
+
+export const KEYS: Record<string, Action> = { 'ctrl-l': 'logs', 'ctrl-r': 'restart', 'ctrl-x': 'stop', 'ctrl-b': 'build' }
+export const KEY_LABELS: Record<string, string> = { 'ctrl-l': 'Logs', 'ctrl-r': 'Restart', 'ctrl-x': 'Stop', 'ctrl-b': 'Rebuild' }
+
+// The fields fzf hands back after the visible ones, tab separated: folder, name, key, compose project.
+function row(service: Service): { hidden: string[], cells: string[] } {
+  const colors = paint(process.stderr)
+  const dir = service.stack.dir
+  const project = service.stack.project
+  const name = project === undefined ? service.name : `${colors.dim(`${project}:`)}${service.name}`
+
+  return {
+    hidden: [dir, service.name, key(service), project ?? ''],
+    cells: [dir === '.' ? name : `${colors.dim(`${dir}/`)}${name}`, colors[stateColor(service.state)](service.state), colors.cyan(service.ports), colors.dim(service.image)],
+  }
+}
+
+// Every cell but the last padded to its column, one space short of the two between columns since a tab renders as one.
+function table(rows: { hidden: string[], cells: string[] }[]): string {
+  const widths = rows[0]?.cells.map((_, index) => Math.max(...rows.map(each => Bun.stringWidth(each.cells[index]!)))) ?? []
+
+  return rows.map(each => [
+    ...each.hidden,
+    ...each.cells.map((cell, index) => (index === each.cells.length - 1 ? cell.trimEnd() : `${cell}${' '.repeat(widths[index]! + 1 - Bun.stringWidth(cell))}`)),
+  ].join('\t')).join('\n')
+}
+
+// The service picked with fzf and the key that picked it, enter's being empty; undefined on escape.
+export function pickService(services: Service[]): { service: Service, key: string } | undefined {
+  const proc = Bun.spawnSync([
+    'fzf',
+    '--prompt',
+    'dx> ',
+    '--header',
+    'enter shell or up, ctrl-l logs, ctrl-r restart, ctrl-x stop, ctrl-b rebuild',
+    '--expect',
+    Object.keys(KEYS).join(','),
+    '--ansi',
+    '--reverse',
+    '--height',
+    String(Math.max(15, Math.ceil((services.length + 4) / 0.6))),
+    '--delimiter',
+    '\t',
+    '--with-nth',
+    '5..',
+    '--nth',
+    '1',
+    '--tabstop',
+    '1',
+    '--tiebreak',
+    'chunk,index',
+    '--preview',
+    `${process.execPath} ${process.argv[1]} --show {1} {2} {4}`,
+    '--preview-window',
+    'down,40%',
+  ], { stdin: new TextEncoder().encode(table(services.map(row))), stdout: 'pipe', stderr: 'inherit' })
+
+  const [pressed = '', line] = proc.stdout.toString().split('\n')
+  const keyed = line?.split('\t')[2]
+  const service = services.find(candidate => key(candidate) === keyed)
+
+  return service === undefined ? undefined : { service, key: pressed }
+}