@osdlc/command-seam 0.0.0-stage → 0.4.0

package/result.ts

@@ -0,0 +1,403 @@
+/**
+ * Helpers for reading a {@link CommandResult}: did it run and succeed, what
+ * to tell a person, and its stdout as JSON.
+ *
+ * None of them throw for a failed command: a failure stays a value the
+ * caller reads. Use `runChecked` when stopping on failure is the only
+ * sensible response.
+ */
+
+import type { AsyncCommandRunner, AsyncCommandRunOptions } from './async.ts'
+import type { CommandResult, CommandRunner, CommandRunOptions } from './sync.ts'
+
+/**
+ * Whether the process started and exited 0. `exitCode` alone is not enough:
+ * a spawn failure, timeout or abort reports a stand-in `1`, and a caller that
+ * reads exit codes as answers must rule that out first.
+ *
+ * Takes any runner's result: a `CommandResult`, a `StreamResult` or a
+ * `ManagedProcessExit`.
+ *
+ * @returns `true` when `neverExited` is not set and `exitCode` is 0.
+ */
+export function ran(result: { exitCode: number; neverExited?: boolean | undefined }): boolean {
+  return result.neverExited !== true && result.exitCode === 0
+}
+
+/**
+ * The child's trimmed stderr, else the runner's trimmed `error` (a failed
+ * spawn, a timeout, an abort), else `''`. Use it where a failure message reads
+ * stderr: since the runner's message is only in `error`, reading `stderr`
+ * alone shows nothing when the command never ran.
+ *
+ * @param result - A run's result.
+ * @returns The text, trimmed; `''` when both are empty.
+ * @experimental
+ *
+ * @example
+ * ```ts
+ * const r = spawnRunner('git').run(['fetch'], { cwd: '.' })
+ * if (!ran(r)) console.error(`fetch failed: ${stderrOrError(r)}`)
+ * ```
+ */
+export function stderrOrError(result: Pick<CommandResult, 'stderr' | 'error'>): string {
+  return result.stderr.trim() || (result.error?.trim() ?? '')
+}
+
+/** Options for {@link failureText}. */
+export interface FailureTextOptions {
+  /**
+   * Return both streams instead of one: trimmed stderr (or the runner's
+   * `error`, when the child wrote no stderr) and trimmed stdout,
+   * newline-joined, empty ones dropped. Empty when stderr, `error` and stdout
+   * are all empty; there is no `exit N` fallback. This is what `CommandFailed.detail`
+   * returns. Use it when both halves matter, such as a git hook that rejects
+   * a commit: git's own error is on stderr, the hook's reason on stdout.
+   */
+  both?: boolean | undefined
+}
+
+/**
+ * The failure text to show a person. By default it picks one stream, which
+ * suits a one-line message: trimmed stderr, else the runner's trimmed
+ * `error` (a failed spawn, a timeout), else trimmed stdout (some commands
+ * explain a failure there), else `exit N`. With `both: true` it
+ * joins both streams (see {@link FailureTextOptions.both}).
+ *
+ * @param result - The result of a failed run.
+ * @param opts - `both: true` to join both streams.
+ * @returns The message. Non-empty unless `both` is set and there is no text
+ * at all.
+ */
+export function failureText(
+  result: Pick<CommandResult, 'exitCode' | 'stdout' | 'stderr' | 'error'>,
+  opts: FailureTextOptions = {},
+): string {
+  const stderr = stderrOrError(result)
+  const stdout = result.stdout.trim()
+  if (opts.both === true) return [stderr, stdout].filter(Boolean).join('\n')
+  return stderr || stdout || `exit ${result.exitCode}`
+}
+
+/**
+ * The first non-blank line of `text`, trimmed; `fallback` when there is
+ * none. For short diagnostics from multi-line tool output.
+ *
+ * @param text - Usually `stdout` or `stderr`.
+ * @param fallback - Returned when every line is blank. Defaults to `''`.
+ * @experimental
+ */
+export function firstLine(text: string, fallback = ''): string {
+  return (
+    text
+      .split('\n')
+      .map((l) => l.trim())
+      .find((l) => l !== '') ?? fallback
+  )
+}
+
+/**
+ * Outcome of {@link runJson}: a parsed value, or why there is none. Two
+ * fields are named `reason`: `j.reason` says why there is no value (`failed`,
+ * `unparseable` or `invalid`), and `j.result.reason` says why the command
+ * never finished, when it did not (see `NeverExitedReason`).
+ *
+ * @experimental
+ */
+export type JsonRun<T> =
+  | { ok: true; value: T; result: CommandResult }
+  | {
+      ok: false
+      /**
+       * `failed`: did not run, or exited with a code not in `okExitCodes`.
+       * `unparseable`: exited with an accepted code, and stdout was not JSON.
+       */
+      reason: 'failed' | 'unparseable'
+      /** A human-readable explanation (the failure text, or the parse error). */
+      message: string
+      result: CommandResult
+    }
+  | {
+      ok: false
+      /** `invalid`: stdout was JSON, and the `parse` option threw for it. */
+      reason: 'invalid'
+      /** `stdout JSON was rejected: ` and the thrown error's message. */
+      message: string
+      /** What `parse` threw, such as a schema library's error with its issue list. */
+      cause: unknown
+      result: CommandResult
+    }
+
+/**
+ * Options for {@link runJson}, apart from `parse`, which is typed by the
+ * value it returns. A value typed `RunJsonOptions` leaves `T` to the caller.
+ *
+ * @experimental
+ */
+export interface RunJsonOptions {
+  /**
+   * Skip leading non-JSON output (log lines, banners). The JSON is the rest of
+   * stdout from the first line (after `\n` or `\r`) that starts with `{` or
+   * `[` and parses to the end, so a `[INFO] ...` prefix is skipped too.
+   * Trailing output is not handled. Off by default: strict `JSON.parse` of
+   * the whole stdout.
+   */
+  tolerateLeadingLog?: boolean | undefined
+  /**
+   * Exit codes that count as an answer, for a tool that prints JSON and
+   * exits non-zero on purpose (`npm outdated --json` exits 1 when anything is
+   * outdated). Default `[0]`. List `0` too if it still counts. A run that
+   * never exited is `failed` whatever its stand-in code. Output from an
+   * accepted non-zero exit must still parse, so pass a `parse` that rejects
+   * the tool's own error output.
+   */
+  okExitCodes?: readonly number[] | undefined
+}
+
+/** The `parse` option of `runJson` and its siblings. `T` is what it returns. */
+interface ParseOption<T> {
+  /**
+   * Check the parsed value and return it typed, such as a schema's `parse`.
+   * A throw makes the outcome `invalid`. It must be sync: a returned promise
+   * is also `invalid`. Without it, `T` is the caller's claim and is not
+   * checked.
+   */
+  parse?: ((value: unknown) => T) | undefined
+}
+
+/** Options with an optional `parse`. */
+type JsonOptions<T> = RunJsonOptions & ParseOption<T>
+
+/**
+ * Parse a finished run's stdout as JSON, if it ran and exited with a code in
+ * `okExitCodes` (default `[0]`). Without the `parse` option, `T` is the
+ * caller's claim about the shape and is not checked; pass `parse` when the
+ * producer is not trusted. Never throws.
+ *
+ * @param result - A finished run.
+ * @param opts - Parse options.
+ * @returns `{ ok: true, value }`, or `{ ok: false, reason, message }` with
+ * `reason` `failed` (did not run, or exited with a code not accepted),
+ * `unparseable`, or `invalid` (`parse` threw; `cause` holds what it threw).
+ * @experimental
+ */
+export function parseJsonResult<T = unknown>(
+  result: CommandResult,
+  opts: JsonOptions<T> = {},
+): JsonRun<T> {
+  const okExitCodes = opts.okExitCodes ?? [0]
+  if (result.neverExited === true || !okExitCodes.includes(result.exitCode)) {
+    return { ok: false, reason: 'failed', message: failureText(result), result }
+  }
+  const parsed = tryParse(result.stdout, opts.tolerateLeadingLog === true)
+  if (!parsed.ok) {
+    return {
+      ok: false,
+      reason: 'unparseable',
+      message: `stdout is not JSON: ${parsed.error}`,
+      result,
+    }
+  }
+  if (opts.parse === undefined) return { ok: true, value: parsed.value as T, result }
+  let value: T
+  try {
+    value = opts.parse(parsed.value)
+  } catch (e) {
+    const why = e instanceof Error ? e.message : String(e)
+    return {
+      ok: false,
+      reason: 'invalid',
+      message: `stdout JSON was rejected: ${why}`,
+      cause: e,
+      result,
+    }
+  }
+  if (isThenable(value)) {
+    // An async `parse` (such as `parseAsync`): its verdict would arrive too
+    // late, so say so, and keep its rejection from going unhandled.
+    value.then(undefined, () => {})
+    return {
+      ok: false,
+      reason: 'invalid',
+      message: 'stdout JSON was rejected: parse returned a promise; it must be sync',
+      cause: value,
+      result,
+    }
+  }
+  return { ok: true, value, result }
+}
+
+function isThenable(v: unknown): v is PromiseLike<unknown> {
+  return (
+    (typeof v === 'object' || typeof v === 'function') &&
+    v !== null &&
+    typeof (v as { then?: unknown }).then === 'function'
+  )
+}
+
+function tryParse(
+  stdout: string,
+  tolerateLeadingLog: boolean,
+): { ok: true; value: unknown } | { ok: false; error: string } {
+  try {
+    return { ok: true, value: JSON.parse(stdout) }
+  } catch (e) {
+    const start = tolerateLeadingLog ? jsonStart(stdout) : -1
+    if (start > 0) {
+      try {
+        return { ok: true, value: JSON.parse(stdout.slice(start)) }
+      } catch {
+        // Report the whole-stdout error below.
+      }
+    }
+    return { ok: false, error: (e as Error).message }
+  }
+}
+
+/**
+ * Where the JSON starts for `tolerateLeadingLog`: the line starting with `{` or
+ * `[` whose brackets stay open until the last bracket in stdout closes them.
+ * Only that line's suffix can parse, so stdout is parsed once more at most.
+ * A JSON string holds no raw line break, so string state resets at each one.
+ * `-1` when no line qualifies.
+ */
+function jsonStart(stdout: string): number {
+  // The bracket depth after each bracket outside a string, in order.
+  const depths: number[] = []
+  // Each candidate line: where it starts, its first bracket's index in
+  // `depths`, and the depth before that bracket.
+  const lines: { at: number; first: number; before: number }[] = []
+  let depth = 0
+  let inString = false
+  for (let i = 0; i < stdout.length; i++) {
+    const c = stdout[i]
+    if (c === '\n' || c === '\r') {
+      inString = false
+    } else if (inString) {
+      if (c === '"') inString = false
+      else if (c === '\\' && stdout[i + 1] !== '\n' && stdout[i + 1] !== '\r') i++
+    } else if (c === '"') {
+      inString = true
+    } else if (c === '{' || c === '[') {
+      const prev = stdout[i - 1]
+      if (prev === '\n' || prev === '\r') lines.push({ at: i, first: depths.length, before: depth })
+      depths.push(++depth)
+    } else if (c === '}' || c === ']') {
+      depths.push(--depth)
+    }
+  }
+  const end = depths.at(-1)
+  // The lowest depth from each bracket on, leaving out the last bracket.
+  let low = Infinity
+  let next = depths.length - 2
+  for (let k = lines.length - 1; k >= 0; k--) {
+    const { at, first, before } = lines[k]!
+    for (; next >= first; next--) low = Math.min(low, depths[next]!)
+    if (before === end && low > before) return at
+  }
+  return -1
+}
+
+/**
+ * The runner's options tuple, `[opts]` or `[opts?]`, with the `runJson`
+ * options added. A conditional rather than a mapped type, so `T` can be inferred
+ * from `parse`; `NoInfer` keeps `P` inferred from the runner alone.
+ */
+type WithJsonOptions<P extends unknown[], T> = P extends [opts: infer O]
+  ? [opts: NoInfer<O> & JsonOptions<T>]
+  : P extends [opts?: infer O]
+    ? [opts?: NoInfer<O> & JsonOptions<T>]
+    : never
+
+/**
+ * Run a command with a sync runner and parse its stdout as JSON
+ * ({@link parseJsonResult}). Never throws for a failed command; a programmer
+ * error, such as an invalid `timeoutMs`, throws. With the `parse` option,
+ * `T` is what `parse` returns.
+ *
+ * Takes the runner's own options, so a `withDefaults` runner needs only the
+ * options it did not bind.
+ *
+ * @param runner - Runs the command; pass a fake in tests.
+ * @param argv - Arguments, without the binary name.
+ * @param opts - Per-call options and {@link RunJsonOptions}.
+ * @returns A {@link JsonRun}: the parsed value, or why there is none.
+ *
+ * @example
+ * ```ts
+ * const gh = spawnRunner('gh')
+ * const r = runJson<{ login: string }>(gh, ['api', 'user'], { cwd: '.' })
+ * if (r.ok) console.log(r.value.login)
+ * else console.error(r.message)
+ * ```
+ *
+ * @experimental
+ */
+export function runJson<T = unknown>(
+  runner: CommandRunner,
+  argv: string[],
+  opts: CommandRunOptions & JsonOptions<T>,
+): JsonRun<T>
+// A runner that needs no options, such as one with `cwd` bound. Its only type
+// parameter is `T`, so `runJson<T>(bound, argv)` compiles: naming `T` on the
+// generic overload below would also fix `P` to its default.
+export function runJson<T = unknown>(
+  runner: { run(argv: string[]): CommandResult },
+  argv: string[],
+  opts?: Partial<CommandRunOptions> & JsonOptions<T>,
+): JsonRun<T>
+export function runJson<T = unknown, P extends unknown[] = [opts: CommandRunOptions]>(
+  runner: { run(argv: string[], ...opts: P): CommandResult },
+  argv: string[],
+  ...opts: WithJsonOptions<P, T>
+): JsonRun<T>
+export function runJson<T>(
+  runner: { run(argv: string[], ...opts: unknown[]): CommandResult },
+  argv: string[],
+  ...opts: unknown[]
+): JsonRun<T> {
+  const { run, json } = splitJsonOptions<T>(opts)
+  return parseJsonResult<T>(runner.run(argv, ...run), json)
+}
+
+/**
+ * The async version of {@link runJson}. Never rejects for a failed command;
+ * a programmer error, such as an invalid `timeoutMs`, rejects. `parse` is
+ * sync, as in `runJson`.
+ *
+ * @experimental
+ */
+export async function runJsonAsync<T = unknown>(
+  runner: AsyncCommandRunner,
+  argv: string[],
+  opts: AsyncCommandRunOptions & JsonOptions<T>,
+): Promise<JsonRun<T>>
+// A runner that needs no options; see the same overload of `runJson`.
+export async function runJsonAsync<T = unknown>(
+  runner: { run(argv: string[]): Promise<CommandResult> },
+  argv: string[],
+  opts?: Partial<AsyncCommandRunOptions> & JsonOptions<T>,
+): Promise<JsonRun<T>>
+export async function runJsonAsync<
+  T = unknown,
+  P extends unknown[] = [opts: AsyncCommandRunOptions],
+>(
+  runner: { run(argv: string[], ...opts: P): Promise<CommandResult> },
+  argv: string[],
+  ...opts: WithJsonOptions<P, T>
+): Promise<JsonRun<T>>
+export async function runJsonAsync<T>(
+  runner: { run(argv: string[], ...opts: unknown[]): Promise<CommandResult> },
+  argv: string[],
+  ...opts: unknown[]
+): Promise<JsonRun<T>> {
+  const { run, json } = splitJsonOptions<T>(opts)
+  return parseJsonResult<T>(await runner.run(argv, ...run), json)
+}
+
+/** Split `runJson`'s options into the runner's and the parse step's. */
+function splitJsonOptions<T>(opts: unknown[]): { run: unknown[]; json: JsonOptions<T> } {
+  if (opts[0] === undefined) return { run: [], json: {} }
+  const { tolerateLeadingLog, parse, okExitCodes, ...run } = opts[0] as JsonOptions<T>
+  return { run: [run], json: { tolerateLeadingLog, parse, okExitCodes } }
+}

package/shell.ts

@@ -0,0 +1,131 @@
+/**
+ * The shell runner: the one place in this package that runs a shell string.
+ *
+ * Every other runner passes argv straight to a binary, so nothing is parsed
+ * as shell. A configured command such as `bun install --filter '@x/y'` or
+ * `a && b` is a shell string by nature, and it runs as `sh -c -- <verb>`.
+ * Keeping that call in one place makes shell use easy to find and audit, and
+ * keeps the invocation the same everywhere.
+ *
+ * Built on the capture runners, so it uses their types
+ * ({@link CommandResult}, {@link CommandRunOptions}, `CommandFailed`) and
+ * their timeout, env and stdin handling.
+ */
+
+import { spawnRunnerAsync, type AsyncCommandRunner, type AsyncCommandRunOptions } from './async.ts'
+import {
+  normalizeTimeout,
+  spawnRunner,
+  type CommandResult,
+  type CommandRunner,
+  type CommandRunOptions,
+} from './sync.ts'
+
+/**
+ * Positional parameters for the verb. They ride as separate argv entries,
+ * never spliced into the string, so they are inert data.
+ */
+export interface ShellPositionals {
+  /** Sets `$0`, the name the script sees for itself, used in its error messages. Default `sh`. */
+  scriptName?: string | undefined
+  /** Visible to the script as `$1`, `$2`, … */
+  args?: readonly string[] | undefined
+}
+
+/** {@link CommandRunOptions} plus {@link ShellPositionals}. */
+export interface ShellRunOptions extends CommandRunOptions, ShellPositionals {}
+
+/** {@link ShellPositionals} plus the async runner's options. */
+export interface AsyncShellRunOptions extends AsyncCommandRunOptions, ShellPositionals {}
+
+/** Runs a shell string. `verb` is interpreted by `sh`, so quote data with `shellQuote`. */
+export interface ShellRunner {
+  run(verb: string, opts: ShellRunOptions): CommandResult
+}
+
+/**
+ * The async version of {@link ShellRunner}.
+ *
+ * @experimental
+ */
+export interface AsyncShellRunner {
+  run(verb: string, opts: AsyncShellRunOptions): Promise<CommandResult>
+}
+
+/**
+ * The `sh -c -- <verb>` argv; `$0`/`$1…` are appended only when given. The
+ * `--` keeps a verb that starts with `-` or `+` from being read as an option.
+ */
+function shellArgv(
+  verb: string,
+  scriptName: string | undefined,
+  args: readonly string[] | undefined,
+): string[] {
+  const rest = args ?? []
+  if (scriptName === undefined && rest.length === 0) return ['-c', '--', verb]
+  return ['-c', '--', verb, scriptName ?? 'sh', ...rest]
+}
+
+/**
+ * A {@link ShellRunner} over `sh`. Pass `sh` to run through a different
+ * {@link CommandRunner}, such as a test fake. An invalid `timeoutMs` throws
+ * before `sh` is called, as it does on the capture runners.
+ *
+ * @param sh - The runner that receives `['-c', '--', verb]`, then
+ * `scriptName` and `args` when given. Defaults to `spawnRunner('sh')`.
+ */
+export function shellRunner(sh: CommandRunner = spawnRunner('sh')): ShellRunner {
+  return {
+    run: (verb, { scriptName, args, ...opts }) => {
+      normalizeTimeout(opts.timeoutMs)
+      return sh.run(shellArgv(verb, scriptName, args), opts)
+    },
+  }
+}
+
+/**
+ * The async version of {@link shellRunner}. Wrap a sync fake with `asAsync`
+ * to pass it in. An invalid `timeoutMs` rejects before `sh` is called.
+ *
+ * @param sh - The runner that receives `['-c', '--', verb]`, then
+ * `scriptName` and `args` when given. Defaults to `spawnRunnerAsync('sh')`.
+ * @experimental
+ */
+export function shellRunnerAsync(
+  sh: AsyncCommandRunner = spawnRunnerAsync('sh'),
+): AsyncShellRunner {
+  return {
+    run: async (verb, { scriptName, args, ...opts }) => {
+      normalizeTimeout(opts.timeoutMs)
+      return sh.run(shellArgv(verb, scriptName, args), opts)
+    },
+  }
+}
+
+/**
+ * Run `verb` once through `sh -c --` and capture the result. Needs `sh` on
+ * `PATH`. Never throws for a failed command, like `spawnRunner`; programmer
+ * errors such as an invalid `timeoutMs` throw.
+ *
+ * @param verb - A shell string. Quote any data in it with `shellQuote`, or
+ * pass it through `args`.
+ * @param opts - The capture options plus `scriptName` (`$0`) and `args` (`$1`…).
+ * @returns The captured result.
+ *
+ * @example
+ * ```ts
+ * const r = runShell('ls "$1" | wc -l', { cwd: '.', args: ['my dir'] })
+ * console.log(r.stdout.trim())
+ * ```
+ */
+export function runShell(verb: string, opts: ShellRunOptions): CommandResult {
+  return shellRunner().run(verb, opts)
+}
+
+/**
+ * The async version of {@link runShell}. Never rejects for a failed command;
+ * rejects for programmer errors such as an invalid `timeoutMs`.
+ */
+export function runShellAsync(verb: string, opts: AsyncShellRunOptions): Promise<CommandResult> {
+  return shellRunnerAsync().run(verb, opts)
+}

package/smoke.mjs

@@ -0,0 +1,61 @@
+// Runs the BUILT package under Node, which no other check does: `bun test`
+// resolves the `bun` export condition to the TypeScript sources, so dist/ is
+// compiled and never executed. A broken emit — an unrewritten `.ts` import, a
+// dependency with no dist/ of its own — passes every other gate and fails on
+// the consumer's machine.
+//
+// Deliberately not a test-runner suite: it must run from the extracted
+// snapshot with only `dist/` and production dependencies present.
+
+import { strict as assert } from 'node:assert'
+import { spawnRunner, runChecked, CommandFailed, asAsync, withDefaults } from './dist/index.js'
+import { fakeProcess, fakeRunner } from './dist/testing.js'
+
+const runner = spawnRunner('node')
+const ok = runner.run(['-e', "process.stdout.write('hi')"], { cwd: process.cwd() })
+assert.equal(ok.exitCode, 0)
+assert.equal(ok.stdout, 'hi')
+
+const bad = runner.run(['-e', "process.stderr.write('boom'); process.exit(3)"], {
+  cwd: process.cwd(),
+})
+assert.equal(bad.exitCode, 3)
+assert.match(bad.stderr, /boom/)
+
+// `run` never throws; `runChecked` does.
+assert.throws(
+  () => runChecked(runner, ['-e', 'process.exit(1)'], { cwd: process.cwd() }),
+  (e) => e instanceof CommandFailed && e.argv.length === 2,
+)
+
+// detail joins both streams, empty ones dropped — the reason it exists is a
+// command that explains itself on stdout while git reports failure on stderr.
+const both = new CommandFailed(['x'], { exitCode: 1, stdout: 'why\n', stderr: 'what\n' })
+assert.equal(both.detail, 'what\nwhy')
+assert.equal(new CommandFailed(['x'], { exitCode: 1, stdout: 'only\n', stderr: '' }).detail, 'only')
+
+// env merges over the parent environment.
+const withEnv = runner.run(['-e', "process.stdout.write(process.env.SMOKE_VAR ?? '')"], {
+  cwd: process.cwd(),
+  env: { SMOKE_VAR: 'set' },
+})
+assert.equal(withEnv.stdout, 'set')
+
+const async = asAsync(runner)
+const viaAsync = await async.run(['-e', "process.stdout.write('async')"], { cwd: process.cwd() })
+assert.equal(viaAsync.stdout, 'async')
+
+// An invalid timeoutMs is a caller error.
+assert.throws(() => runner.run(['-e', ''], { cwd: process.cwd(), timeoutMs: 0 }), RangeError)
+
+const bound = withDefaults(runner, { cwd: process.cwd() })
+assert.equal(bound.run(['-e', "process.stdout.write('bound')"]).stdout, 'bound')
+
+// The /testing entry point, built.
+const fake = fakeRunner({ 'rev-parse HEAD': { stdout: 'abc\n' } })
+assert.equal(runChecked(fake.runner, ['rev-parse', 'HEAD'], { cwd: '/' }).stdout, 'abc\n')
+const proc = fakeProcess()
+proc.kill()
+assert.equal((await proc.exited).reason, 'abort')
+
+console.log('command-seam smoke: OK')