@kaynooo/cli-kit 0.9.0 → 0.11.0

package/src/logs.ts

@@ -0,0 +1,72 @@
+import { lstatSync, openSync } from 'node:fs'
+import { mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+// Whether the folder is a real directory (not a link) that only this user can use.
+function isPrivateDirectory(path: string): boolean {
+  try {
+    const info = lstatSync(path, { throwIfNoEntry: false })
+
+    return info !== undefined && info.isDirectory() && info.uid === (process.getuid?.() ?? info.uid) && (info.mode & 0o077) === 0
+  }
+  catch {
+    return false
+  }
+}
+
+// A folder for log files that only this user can read: `<name>` under $XDG_RUNTIME_DIR, else ~/.cache/agent-tools. When one already exists it must be a private directory of this user, otherwise a fresh private folder in the temp directory is used instead of trusting it.
+export async function privateLogDirectory(name: string, env: Record<string, string | undefined> = process.env): Promise<string> {
+  const runtime = env.XDG_RUNTIME_DIR
+  const base = runtime === undefined || runtime === '' ? join(homedir(), '.cache', 'agent-tools') : join(runtime, 'agent-tools')
+  const path = join(base, name)
+
+  try {
+    await mkdir(path, { recursive: true, mode: 0o700 })
+
+    if (isPrivateDirectory(path))
+      return path
+  }
+  catch {
+    // Falls through to the temp folder below.
+  }
+
+  return mkdtemp(join(tmpdir(), `${name.replaceAll('/', '-')}-`))
+}
+
+// Removes what is older than `maxAgeMs` in the folder, and the empty subfolders it leaves, best effort since another run may be doing the same.
+export async function sweepLogs(dir: string, maxAgeMs = DAY_MS, now = Date.now()): Promise<void> {
+  let names: string[]
+
+  try {
+    names = await readdir(dir)
+  }
+  catch {
+    return
+  }
+
+  for (const name of names) {
+    const path = join(dir, name)
+
+    try {
+      const info = await stat(path)
+
+      if (info.isDirectory())
+        await sweepLogs(path, maxAgeMs, now)
+
+      if (now - info.mtimeMs > maxAgeMs)
+        await rm(path, { force: true, recursive: info.isDirectory() })
+    }
+    catch {
+      continue
+    }
+  }
+}
+
+// Creates a log file nobody else can read and that must not exist yet, so a planted link is never followed; returns its descriptor, for writeSync.
+export function createLog(path: string): number {
+  return openSync(path, 'wx', 0o600)
+}

package/src/process.ts

@@ -14,12 +14,26 @@ export interface Ran {
   // The bytes of every chunk joined.
   output: Buffer
   text: string
+  // The command was ended because `timeoutMs` passed, its code then being the signal's.
+  timedOut: boolean
+  // More than `maxBytes` came, and the rest was left out of chunks, output and text.
+  truncated: boolean
 }
 
 export interface RunSettings {
   cwd?: string
   env?: Record<string, string | undefined>
   stdin?: 'inherit' | 'ignore'
+  // Ends the command and its children after this long.
+  timeoutMs?: number
+  // Ends the command and its children when aborted.
+  signal?: AbortSignal
+  // Bytes kept in the result; the pipes are still read to the end.
+  maxBytes?: number
+  // Called with each chunk as it arrives; throwing ends the command and rethrows once the pipes are drained.
+  onChunk?: (chunk: Chunk) => void
+  // Called once the command runs, with a handle that sends a signal to its whole process group, for `holdSignals().forward`.
+  onStart?: (child: { kill: (signal: NodeJS.Signals) => void }) => void
 }
 
 export interface HeldSignals {
@@ -31,16 +45,12 @@ export interface HeldSignals {
   release: () => void
 }
 
+const KILL_GRACE_MS = 2000
 const SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const
 // A scheme of two letters or more, so a Windows drive is read as a path.
 const SCHEME = /^[a-z][\w+.-]+:/i
 const OPENERS: Partial<Record<NodeJS.Platform, string[]>> = { darwin: ['open'], win32: ['cmd', '/c', 'start', ''] }
 
-async function collect(stream: ReadableStream<Uint8Array>, name: Chunk['stream'], chunks: Chunk[]): Promise<void> {
-  for await (const data of stream)
-    chunks.push({ stream: name, data })
-}
-
 // The exit code a shell would report: the code, or 128 plus the signal.
 export function exitCodeOf(code: number | null, signal: NodeJS.Signals | number | null): number {
   if (code !== null)
@@ -106,15 +116,106 @@ export function openUrl(target: string, env: Record<string, string | undefined>
   }
 }
 
-// Runs a command with stdout and stderr captured; throws when it cannot be started.
-export async function runCommand(argv: string[], { cwd, env, stdin = 'ignore' }: RunSettings = {}): Promise<Ran> {
+// Runs a command with stdout and stderr captured; throws when it cannot be started. With `timeoutMs`, `signal`, `onStart` or `onChunk` the child leads its own process group, and the whole group is ended (SIGTERM, then SIGKILL after a short grace) on the timeout, an abort or a throwing `onChunk`; the pipes are drained to their end either way.
+export async function runCommand(argv: string[], { cwd, env, stdin = 'ignore', timeoutMs, signal, maxBytes = Infinity, onChunk, onStart }: RunSettings = {}): Promise<Ran> {
   const chunks: Chunk[] = []
-  const proc = Bun.spawn(argv, { ...(cwd === undefined ? {} : { cwd }), ...(env === undefined ? {} : { env }), stdin, stdout: 'pipe', stderr: 'pipe' })
+  const grouped = timeoutMs !== undefined || signal !== undefined || onStart !== undefined || onChunk !== undefined
+  const proc = Bun.spawn(argv, { ...(cwd === undefined ? {} : { cwd }), ...(env === undefined ? {} : { env }), stdin, stdout: 'pipe', stderr: 'pipe', ...(grouped ? { detached: true } : {}) })
+  const state = { kept: 0, truncated: false, timedOut: false, failure: undefined as unknown, done: false }
+  const timers: ReturnType<typeof setTimeout>[] = []
+
+  const killGroup = (killing: NodeJS.Signals) => {
+    if (state.done)
+      return
+
+    try {
+      if (grouped)
+        process.kill(-proc.pid, killing)
+      else
+        proc.kill(killing)
+    }
+    catch {
+      // The group is already gone.
+    }
+  }
+
+  const stop = () => {
+    killGroup('SIGTERM')
+    timers.push(setTimeout(killGroup, KILL_GRACE_MS, 'SIGKILL'))
+  }
+
+  const onAbort = () => stop()
+
+  if (timeoutMs !== undefined) {
+    timers.push(setTimeout(() => {
+      state.timedOut = true
+      stop()
+    }, timeoutMs))
+  }
+
+  if (signal?.aborted === true)
+    onAbort()
+  else
+    signal?.addEventListener('abort', onAbort, { once: true })
+
+  onStart?.({ kill: killing => killGroup(killing) })
+
+  const drain = async (stream: ReadableStream<Uint8Array>, name: Chunk['stream']) => {
+    for await (const data of stream) {
+      if (state.failure !== undefined)
+        continue
 
-  await Promise.all([collect(proc.stdout, 'stdout', chunks), collect(proc.stderr, 'stderr', chunks)])
-  await proc.exited
+      try {
+        onChunk?.({ stream: name, data })
+      }
+      catch (error) {
+        state.failure = error
+        stop()
 
-  const output = Buffer.concat(chunks.map(({ data }) => data))
+        continue
+      }
 
-  return { code: exitCodeOf(proc.exitCode, proc.signalCode), chunks, output, text: output.toString() }
+      if (state.kept + data.length > maxBytes) {
+        state.truncated = true
+
+        continue
+      }
+
+      state.kept += data.length
+      chunks.push({ stream: name, data })
+    }
+  }
+
+  try {
+    await Promise.all([drain(proc.stdout, 'stdout'), drain(proc.stderr, 'stderr')])
+    await proc.exited
+  }
+  finally {
+    state.done = true
+
+    for (const timer of timers)
+      clearTimeout(timer)
+
+    signal?.removeEventListener('abort', onAbort)
+  }
+
+  if (state.failure !== undefined)
+    throw state.failure
+
+  const joined = () => Buffer.concat(chunks.map(({ data }) => data))
+  let output: Buffer | undefined
+  let text: string | undefined
+
+  return {
+    code: exitCodeOf(proc.exitCode, proc.signalCode),
+    chunks,
+    timedOut: state.timedOut,
+    truncated: state.truncated,
+    get output() {
+      return output ??= joined()
+    },
+    get text() {
+      return text ??= (output ??= joined()).toString()
+    },
+  }
 }

package/src/secrets.ts

@@ -0,0 +1,10 @@
+// Parts of a name that make it secret wherever they sit in it (`DB_PASSWORD`, `PGPASSWORD`, `clientSecret`).
+const SECRET_PART = /token|secret|passw|credential|private|dsn|apikey|accesskey|key$/i
+// Whole words of a name that make it secret (`DB_PASS`, `SMTP_PWD`, `encryptionKey`, `session_id`), so `compass`, `author` or `keyword` stay plain.
+const SECRET_WORDS = new Set(['key', 'pass', 'pwd', 'auth', 'salt', 'cookie', 'session', 'jwt', 'ssn', 'iban', 'card', 'cvv', 'otp'])
+const WORD_BREAKS = /[^a-zA-Z\d]+|(?<=[a-z\d])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/
+
+// True for the name of a variable, a column or a JSON key that holds a secret, by one definition shared by ev, redact and db.
+export function isSecretName(name: string): boolean {
+  return SECRET_PART.test(name) || name.split(WORD_BREAKS).some(word => SECRET_WORDS.has(word.toLowerCase()))
+}