@kaynooo/cli-kit 0.0.0-stage → 0.7.3

package/src/prompt.ts

@@ -0,0 +1,331 @@
+import type { Colors } from './style'
+import process from 'node:process'
+import { fail } from './args'
+import { truncate } from './format'
+import { paint } from './style'
+
+// What the terminal sends for a key: a whole escape sequence, such as an arrow's or Home's, which no prompt but the arrows reads, or one character, a lone Escape included.
+// eslint-disable-next-line no-control-regex -- escape sequences are what it splits
+const KEY_SEQUENCES = /\x1B\[[0-9;]*[A-Z~]|\x1BO[A-Z]|[\s\S]/giu
+// eslint-disable-next-line no-control-regex -- control characters are what it leaves out
+const CONTROL = /^[\x00-\x1F\x7F]/
+const WORDS = /\s+/
+// Choices drawn at once at most, the rest scrolled to.
+const MAX_ROWS = 10
+
+type Key = 'up' | 'down' | 'enter' | 'cancel' | 'erase' | { text: string }
+type Outcome = 'enter' | 'cancel'
+type State = 'asking' | Outcome
+
+const KEYS: Record<string, Key> = { '\x1B[A': 'up', '\x1BOA': 'up', '\x1B[B': 'down', '\x1BOB': 'down', '\r': 'enter', '\n': 'enter', '\x03': 'cancel', '\x1B': 'cancel', '\x7F': 'erase', '\b': 'erase' }
+
+export interface Choice<T> {
+  value: T
+  label: string
+  hint: string
+}
+
+// The ends a prompt reads keys from and draws on, the process's own by default.
+export interface Terminal {
+  stdin: Pick<NodeJS.ReadStream, 'setRawMode' | 'resume' | 'pause' | 'on' | 'off'> & { isTTY?: boolean }
+  stderr: Pick<NodeJS.WriteStream, 'write' | 'columns' | 'rows'> & { isTTY?: boolean }
+}
+
+export interface PromptSettings {
+  // Shown under the error a prompt fails with off a terminal, such as `pass --yes`.
+  hint?: string
+  terminal?: Terminal
+}
+
+// The keys a chunk of terminal input holds, in order: the ones prompts read, and printable text.
+function readKeys(input: string): Key[] {
+  return (input.match(KEY_SEQUENCES) ?? []).flatMap(sequence => KEYS[sequence] ?? (CONTROL.test(sequence) ? [] : [{ text: sequence }]))
+}
+
+export interface SelectSettings extends PromptSettings {
+  // The index of the choice the cursor starts on.
+  initial?: number
+}
+
+// One choice among several, typing filtering them, the arrows moving and Enter picking; undefined once Escape or Ctrl+C cancels.
+export async function select<T>(question: string, choices: Choice<T>[], { initial = 0, ...settings }: SelectSettings = {}): Promise<T | undefined> {
+  const list = new List(choices, initial)
+  const picked = await ask(question, settings, (colors, state, rows) => state === 'asking'
+    ? [asking(colors, question, list.query, 'type to filter, enter picks'), ...list.rows(colors, rows, () => '')]
+    : [answer(colors, question, state, list.current()?.label ?? '')], (key) => {
+    if (key === 'enter')
+      return list.current() === undefined ? undefined : 'enter'
+
+    if (key === 'cancel')
+      return 'cancel'
+
+    list.press(key)
+
+    return undefined
+  })
+
+  return picked ? list.current()?.value : undefined
+}
+
+export interface ChecklistSettings<T> extends PromptSettings {
+  initial?: ReadonlySet<T>
+  // What checking or unchecking `value` leaves checked, which may change other choices along; flips `value` alone by default.
+  toggle?: (checked: ReadonlySet<T>, value: T) => ReadonlySet<T>
+}
+
+function flip<T>(checked: ReadonlySet<T>, value: T): ReadonlySet<T> {
+  const next = new Set(checked)
+
+  if (!next.delete(value))
+    next.add(value)
+
+  return next
+}
+
+// Several choices, typing filtering them, Space checking or unchecking the one under the cursor and Enter accepting what is checked; undefined once cancelled.
+export async function checklist<T>(question: string, choices: Choice<T>[], { initial = new Set(), toggle = flip, ...settings }: ChecklistSettings<T> = {}): Promise<ReadonlySet<T> | undefined> {
+  const list = new List(choices, 0)
+  let checked = initial
+  const accepted = await ask(question, settings, (colors, state, rows) => state === 'asking'
+    ? [asking(colors, question, list.query, 'type to filter, space toggles, enter accepts'), ...list.rows(colors, rows, choice => checked.has(choice.value) ? `${colors.cyan('◉')} ` : `${colors.dim('◯')} `)]
+    : [answer(colors, question, state, choices.filter(choice => checked.has(choice.value)).map(choice => choice.label).join(', ') || 'none')], (key) => {
+    if (key === 'enter' || key === 'cancel')
+      return key
+
+    const current = list.current()
+
+    if (typeof key === 'object' && key.text === ' ') {
+      if (current !== undefined)
+        checked = toggle(checked, current.value)
+
+      return undefined
+    }
+
+    list.press(key)
+
+    return undefined
+  })
+
+  return accepted ? checked : undefined
+}
+
+export interface ConfirmSettings extends PromptSettings {
+  // What Enter answers; without one, Enter waits for y or n.
+  default?: boolean
+}
+
+// A yes or no, y or n answering it and Enter taking the default; undefined once cancelled.
+export async function confirm(question: string, { default: fallback, ...settings }: ConfirmSettings = {}): Promise<boolean | undefined> {
+  let answered = fallback
+  const choices = { true: 'Y/n', false: 'y/N', undefined: 'y/n' }[String(fallback) as 'true' | 'false' | 'undefined']
+  const accepted = await ask(question, settings, (colors, state) => [state === 'asking' ? asking(colors, question, '', choices) : answer(colors, question, state, answered ? 'yes' : 'no')], (key) => {
+    if (key === 'cancel')
+      return 'cancel'
+
+    if (key === 'enter')
+      return answered === undefined ? undefined : 'enter'
+
+    const letter = typeof key === 'object' ? key.text.toLowerCase() : ''
+
+    if (letter !== 'y' && letter !== 'n')
+      return undefined
+
+    answered = letter === 'y'
+
+    return 'enter'
+  })
+
+  return accepted ? answered : undefined
+}
+
+export interface InputPromptSettings extends PromptSettings {
+  // What an empty answer stands for, shown dimmed until something is typed.
+  default?: string
+  // Draws each character typed as `*`, for a password or a token.
+  mask?: boolean
+  // What is wrong with the answer, shown under it until Enter is pressed on one it takes; undefined takes it.
+  validate?: (value: string) => string | undefined
+}
+
+// A line of text, Enter taking it once `validate` does; undefined once cancelled.
+export async function input(question: string, { default: fallback, mask = false, validate, ...settings }: InputPromptSettings = {}): Promise<string | undefined> {
+  let value = ''
+  let invalid: string | undefined
+  const taken = () => value === '' ? fallback ?? '' : value
+  const shown = () => mask ? '*'.repeat([...taken()].length) : taken()
+  const accepted = await ask(question, settings, (colors, state, { columns }) => {
+    if (state !== 'asking')
+      return [answer(colors, question, state, shown())]
+
+    // Its end alone where it would wrap: `? `, the question, a space, the caret, and the last column kept free.
+    const characters = [...shown()]
+    const room = Math.max(columns - question.length - 5, 1)
+    const tail = characters.length > room ? `…${characters.slice(1 - room).join('')}` : shown()
+    const typed = value === '' ? colors.dim(tail) : tail
+
+    return [`${colors.cyan('?')} ${question} ${typed}${colors.dim('█')}`, ...invalid === undefined ? [] : [`  ${colors.red(invalid)}`]]
+  }, (key) => {
+    if (key === 'cancel')
+      return 'cancel'
+
+    invalid = undefined
+
+    if (key === 'enter') {
+      invalid = validate?.(taken())
+
+      return invalid === undefined ? 'enter' : undefined
+    }
+
+    if (key === 'erase')
+      value = [...value].slice(0, -1).join('')
+    else if (typeof key === 'object')
+      value += key.text
+
+    return undefined
+  })
+
+  return accepted ? taken() : undefined
+}
+
+// The choices a filter leaves, the cursor on one of them and the window of rows drawn around it.
+class List<T> {
+  query = ''
+  private matches: Choice<T>[]
+  private cursor: number
+  private top = 0
+  private readonly width: number
+
+  constructor(private readonly choices: Choice<T>[], initial: number) {
+    this.matches = choices
+    this.cursor = Math.min(Math.max(initial, 0), choices.length - 1)
+    this.width = Math.max(0, ...choices.map(choice => choice.label.length))
+  }
+
+  current(): Choice<T> | undefined {
+    return this.matches[this.cursor]
+  }
+
+  press(key: Key): void {
+    if (key === 'up' || key === 'down') {
+      if (this.matches.length > 0)
+        this.cursor = (this.cursor + (key === 'up' ? this.matches.length - 1 : 1)) % this.matches.length
+
+      return
+    }
+
+    if (key === 'erase')
+      this.filter([...this.query].slice(0, -1).join(''))
+    else if (typeof key === 'object')
+      this.filter(this.query + key.text)
+  }
+
+  // Every word typed is in the label or the hint, case ignored; the cursor stays on its choice while it still matches, else goes to the first.
+  private filter(query: string): void {
+    const words = query.toLowerCase().split(WORDS).filter(word => word !== '')
+    const current = this.current()
+
+    this.query = query
+    this.matches = this.choices.filter(({ label, hint }) => words.every(word => `${label} ${hint}`.toLowerCase().includes(word)))
+    this.cursor = current === undefined ? 0 : Math.max(this.matches.indexOf(current), 0)
+    this.top = 0
+  }
+
+  // A line per choice in the window, each cut to the terminal's width so none wraps, which would throw off the redraw, and a dimmed count of those scrolled past.
+  rows(colors: Colors, { columns, rows }: { columns: number, rows: number }, marker: (choice: Choice<T>) => string): string[] {
+    if (this.matches.length === 0)
+      return [colors.dim('  no match')]
+
+    const height = Math.max(1, Math.min(MAX_ROWS, rows - 3, this.matches.length))
+
+    this.top = Math.min(Math.max(this.top, this.cursor - height + 1), this.cursor)
+
+    const shown = this.matches.slice(this.top, this.top + height).map((choice, index) => {
+      const here = this.top + index === this.cursor
+      const mark = marker(choice)
+      const head = `${here ? '❯' : ' '} ${mark}`
+      const label = choice.label.padEnd(this.width)
+      // What is left of the line for the hint: the pointer and a space, a mark of two visible characters (`◉ `) when there is one, the label, two spaces, and the last column kept free.
+      const room = columns - 5 - (mark === '' ? 0 : 2) - this.width
+
+      return `${here ? colors.cyan(head) : head}${here ? colors.cyan(label) : label}  ${colors.dim(truncate(choice.hint, Math.max(room, 0)))}`
+    })
+    const below = this.matches.length - this.top - height
+
+    return [...this.top > 0 ? [colors.dim(`  … ${this.top} more`)] : [], ...shown, ...below > 0 ? [colors.dim(`  … ${below} more`)] : []]
+  }
+}
+
+// The question line while asking: what was typed after it, else a dimmed note of the keys.
+function asking(colors: Colors, question: string, typed: string, keys: string): string {
+  return `${colors.cyan('?')} ${question} ${typed === '' ? colors.dim(`(${keys})`) : typed}`
+}
+
+// The line a prompt leaves once answered: what was picked, or that it was cancelled.
+function answer(colors: Colors, question: string, state: Outcome, picked: string): string {
+  return state === 'enter' ? `${colors.green('✓')} ${question} ${colors.cyan(picked)}` : `${colors.red('✗')} ${question} ${colors.dim('cancelled')}`
+}
+
+type Render = (colors: Colors, state: State, size: { columns: number, rows: number }) => string[]
+
+// Draws a prompt on stderr and redraws it after each key stdin sends raw, until `press` answers `enter` or `cancel`; true once entered. Off a terminal, nobody could answer, so it fails at once.
+async function ask(question: string, { hint, terminal = process }: PromptSettings, render: Render, press: (key: Key) => Outcome | undefined): Promise<boolean> {
+  const { stdin, stderr } = terminal
+
+  if (stdin.isTTY !== true || stderr.isTTY !== true)
+    fail(`cannot ask "${question}" off a terminal`, 2, hint)
+
+  const colors = paint(stderr)
+  let drawn = 0
+  let outcome: Outcome | undefined
+  const draw = (state: State) => {
+    // A terminal that does not say its size, as a pseudo-terminal may, answers 0.
+    const frame = render(colors, state, { columns: stderr.columns || 80, rows: stderr.rows || 24 })
+
+    stderr.write(`${drawn > 1 ? `\x1B[${drawn - 1}A` : ''}\r\x1B[0J${frame.join('\n')}`)
+    drawn = frame.length
+  }
+
+  try {
+    stdin.setRawMode(true)
+    stdin.resume()
+    stderr.write('\x1B[?25l')
+    draw('asking')
+
+    return await new Promise<boolean>((resolve) => {
+      function onData(data: Buffer) {
+        for (const key of readKeys(data.toString())) {
+          const pressed = press(key)
+
+          if (pressed !== undefined) {
+            settle(pressed)
+
+            return
+          }
+        }
+
+        draw('asking')
+      }
+
+      // A stdin closing before an answer, as a terminal hung up does, cancels instead of leaving the prompt waiting forever.
+      function onEnd() {
+        settle('cancel')
+      }
+
+      function settle(settled: Outcome) {
+        outcome = settled
+        stdin.off('data', onData)
+        stdin.off('end', onEnd)
+        resolve(settled === 'enter')
+      }
+
+      stdin.on('data', onData)
+      stdin.on('end', onEnd)
+    })
+  }
+  finally {
+    draw(outcome ?? 'cancel')
+    stderr.write('\n\x1B[?25h')
+    stdin.setRawMode(false)
+    stdin.pause()
+  }
+}

package/src/shell.ts

@@ -0,0 +1,373 @@
+// `text` is the piece as written, `command` the same less its heredoc bodies, which are data and never commands; `separator` is what ends it (`|`, `&&`, `;`, a newline...), empty for the last; `expanded` holds the bodies of its unquoted heredocs, where the shell still runs `$(...)`.
+export interface Piece { text: string, start: number, end: number, command: string, separator: string, expanded: string }
+export interface Invocation { program: string, args: string[], assignments: string[], isWrapped: boolean }
+
+const SEPARATORS = new Set(['\n', ';', '|'])
+const PLAIN_BREAKERS = new Set(['<', '>', '(', ')', '&', '|'])
+const WHITESPACE = /\s/
+const ASSIGNMENT = /^\w+=/
+const TRAILING_SLASHES = /\/+$/
+const LEADING_TILDE = /^~(?=\/|$)/
+const LEADING_TABS = /^\t+/
+const OPENERS = /^[({]+/
+const CLOSERS = /[)}]+$/
+const HEREDOC = /^<<(-?)[ \t]*(?:'([^']*)'|"([^"]*)"|([^\s;&|<>()-][^\s;&|<>()]*))/
+// Programs that run the command following them, which is the one that counts.
+const WRAPPERS = new Set(['command', 'env', 'sudo', 'exec', 'nohup', 'time'])
+
+// A lone `&` sends the command before it to the background, unless it belongs to a redirection such as `2>&1` or `&>`.
+function separatorWidth(command: string, i: number): number {
+  const pair = command.slice(i, i + 2)
+
+  if (pair === '&&' || pair === '||')
+    return 2
+
+  const char = command[i] ?? ''
+
+  if (char === '&')
+    return command[i - 1] === '>' || command[i - 1] === '<' || command[i + 1] === '>' ? 0 : 1
+
+  return SEPARATORS.has(char) ? 1 : 0
+}
+
+// Where the heredocs opened on a line end: from the newline closing that line to the end of the last delimiter line.
+function heredocEnd(command: string, newline: number, words: readonly { word: string, stripsTabs: boolean }[]): number {
+  let lineStart = newline + 1
+
+  for (const { word, stripsTabs } of words) {
+    while (lineStart <= command.length) {
+      const next = command.indexOf('\n', lineStart)
+      const lineEnd = next === -1 ? command.length : next
+      const line = command.slice(lineStart, lineEnd)
+
+      lineStart = lineEnd + 1
+
+      if ((stripsTabs ? line.replace(LEADING_TABS, '') : line) === word)
+        break
+    }
+  }
+
+  return Math.min(lineStart - 1, command.length)
+}
+
+function withoutRanges(command: string, start: number, end: number, ranges: readonly [number, number][]): string {
+  let text = ''
+  let at = start
+
+  for (const [from, to] of ranges) {
+    if (to <= start || from >= end)
+      continue
+
+    text += command.slice(at, Math.max(at, from))
+    at = Math.max(at, to)
+  }
+
+  return text + command.slice(at, end)
+}
+
+// Splits on the shell separators outside quotes and heredocs, so the `;` and `|` of an inline script stay in its piece, each piece keeping where it sits in the command.
+export function splitCommand(command: string): Piece[] {
+  const bounds: [number, number, string][] = []
+  const bodies: [number, number, boolean][] = []
+  let heredocs: { word: string, stripsTabs: boolean, isQuoted: boolean }[] = []
+  let start = 0
+  let quote: string | null = null
+
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i] ?? ''
+
+    if (char === '\\' && quote !== '\'') {
+      i++
+
+      continue
+    }
+
+    if (quote !== null) {
+      if (char === quote)
+        quote = null
+
+      continue
+    }
+
+    if (char === '\'' || char === '"') {
+      quote = char
+
+      continue
+    }
+
+    const heredoc = char === '<' && command[i + 1] === '<' && command[i + 2] !== '<' ? HEREDOC.exec(command.slice(i)) : null
+
+    if (heredoc) {
+      heredocs.push({ word: heredoc[2] ?? heredoc[3] ?? heredoc[4] ?? '', stripsTabs: heredoc[1] === '-', isQuoted: heredoc[4] === undefined })
+      i += heredoc[0].length - 1
+
+      continue
+    }
+
+    if (char === '\n' && heredocs.length > 0) {
+      const end = heredocEnd(command, i, heredocs)
+
+      bodies.push([i, end, heredocs.some(each => !each.isQuoted)])
+      heredocs = []
+      i = end - 1
+
+      continue
+    }
+
+    const width = separatorWidth(command, i)
+
+    if (width === 0)
+      continue
+
+    bounds.push([start, i, command.slice(i, i + width)])
+    i += width - 1
+    start = i + 1
+  }
+  bounds.push([start, command.length, ''])
+
+  const ranges = bodies.map(([from, to]): [number, number] => [from, to])
+
+  return bounds.map(([from, to, separator]) => ({
+    text: command.slice(from, to),
+    start: from,
+    end: to,
+    command: withoutRanges(command, from, to, ranges),
+    separator,
+    expanded: bodies.filter(([body, , expands]) => expands && body >= from && body < to).map(([body, bodyEnd]) => command.slice(body, bodyEnd)).join(''),
+  }))
+}
+
+// True when the text holds no redirect, substitution, subshell or group outside single quotes, and closes every quote it opens.
+export function isPlain(text: string): boolean {
+  let quote: string | null = null
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i] ?? ''
+    const isSubstitution = char === '`' || (char === '$' && text[i + 1] === '(')
+
+    if (char === '\\' && quote !== '\'')
+      i++
+    else if (quote !== null && char === quote)
+      quote = null
+    else if (quote === null && (char === '"' || char === '\''))
+      quote = char
+    else if (quote !== '\'' && (isSubstitution || (quote === null && PLAIN_BREAKERS.has(char))))
+      return false
+  }
+
+  return quote === null
+}
+
+// The index of the `)` closing the `(` at `open`, past nested parentheses and quotes; the text's end when it never closes.
+function closingParen(text: string, open: number): number {
+  let depth = 0
+  let quote: string | null = null
+
+  for (let i = open; i < text.length; i++) {
+    const char = text[i] ?? ''
+
+    if (char === '\\' && quote !== '\'') {
+      i++
+    }
+    else if (quote !== null) {
+      if (char === quote)
+        quote = null
+    }
+    else if (char === '\'' || char === '"') {
+      quote = char
+    }
+    else if (char === '(') {
+      depth++
+    }
+    else if (char === ')' && --depth === 0) {
+      return i
+    }
+  }
+
+  return text.length
+}
+
+// The index of the backquote closing the one at `open`, past escaped characters; the text's end when it never closes.
+function closingBackquote(text: string, open: number): number {
+  for (let i = open + 1; i < text.length; i++) {
+    if (text[i] === '\\')
+      i++
+    else if (text[i] === '`')
+      return i
+  }
+
+  return text.length
+}
+
+// The bodies of the outermost `$(...)` and backquotes; quotes only count where `isQuoting`, as a heredoc body holds them as plain text.
+function bodies(text: string, isQuoting: boolean): string[] {
+  const found: string[] = []
+  let quote: string | null = null
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i] ?? ''
+
+    if (quote === '\'') {
+      if (char === '\'')
+        quote = null
+    }
+    else if (char === '\\') {
+      i++
+    }
+    else if (char === '$' && text[i + 1] === '(') {
+      const end = closingParen(text, i + 1)
+
+      found.push(text.slice(i + 2, end))
+      i = end
+    }
+    else if (char === '`') {
+      const end = closingBackquote(text, i)
+
+      found.push(text.slice(i + 1, end))
+      i = end
+    }
+    else if (isQuoting && char === '"') {
+      quote = quote === null ? char : null
+    }
+    else if (isQuoting && char === '\'' && quote === null) {
+      quote = char
+    }
+  }
+
+  return found
+}
+
+// The commands each piece runs through `$(...)` or backquotes, inside double quotes and unquoted heredoc bodies too; a nested one is found by reading each result in turn.
+export function substitutions(command: string): string[] {
+  return splitCommand(command).flatMap(piece => [...bodies(piece.command, true), ...bodies(piece.expanded, false)])
+}
+
+// A word as the shell would pass it; `isProse` when a quoted part of it holds whitespace, a message or a pattern rather than a path.
+export interface Word { text: string, isProse: boolean }
+
+// The words of a piece, quotes and line continuations removed.
+export function words(text: string): Word[] {
+  const found: Word[] = []
+  let current = ''
+  let isStarted = false
+  let isProse = false
+  let quote: string | null = null
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i] ?? ''
+    const isContinuation = char === '\\' && quote !== '\'' && text[i + 1] === '\n'
+
+    if (isContinuation)
+      i++
+
+    if (quote === null && (isContinuation || WHITESPACE.test(char))) {
+      if (isStarted)
+        found.push({ text: current, isProse })
+
+      current = ''
+      isStarted = false
+      isProse = false
+
+      continue
+    }
+
+    if (isContinuation)
+      continue
+
+    isStarted = true
+
+    if (char === '\\' && quote !== '\'')
+      current += text[++i] ?? ''
+    else if (quote !== null && char === quote)
+      quote = null
+    else if (quote === null && (char === '"' || char === '\''))
+      quote = char
+    else
+      current += char
+
+    isProse ||= quote !== null && WHITESPACE.test(char)
+  }
+
+  if (isStarted)
+    found.push({ text: current, isProse })
+
+  return found
+}
+
+// The words of a piece as the shell would pass them, quotes and line continuations removed.
+export function tokenize(text: string): string[] {
+  return words(text).map(word => word.text)
+}
+
+// The program a piece runs, by its base name, past any subshell opener, variable assignment or wrapper such as `env` or `sudo`.
+export function parseCommand(text: string): Invocation {
+  const tokens = tokenize(text)
+  const assignments: string[] = []
+  let isWrapped = false
+
+  for (;;) {
+    const first = tokens[0] ?? ''
+
+    if (OPENERS.test(first)) {
+      isWrapped = true
+      const rest = first.replace(OPENERS, '')
+
+      if (rest === '')
+        tokens.shift()
+      else tokens[0] = rest
+    }
+    else if (ASSIGNMENT.test(first)) {
+      assignments.push(tokens.shift() ?? '')
+    }
+    else if (WRAPPERS.has(first)) {
+      isWrapped = true
+      tokens.shift()
+
+      while (tokens[0]?.startsWith('-')) tokens.shift()
+    }
+    else {
+      break
+    }
+  }
+  // the closing of a subshell or a group, `(git stash)` or `{ cd x && npm i; }`, ends the last word
+  const last = (tokens.at(-1) ?? '').replace(CLOSERS, '')
+
+  if (tokens.length > 0)
+    tokens.splice(-1, 1, ...(last === '' ? [] : [last]))
+
+  const [program = '', ...args] = tokens
+
+  return { program: program.split('/').pop() ?? '', args, assignments, isWrapped }
+}
+
+// Swaps each piece's text for its replacement, keeping the separators between them.
+export function replacePieces(command: string, replacements: ReadonlyMap<Piece, string>): string {
+  let result = command
+
+  for (const [piece, text] of [...replacements].sort(([a], [b]) => b.start - a.start)) {
+    result = result.slice(0, piece.start) + text + result.slice(piece.end)
+  }
+
+  return result
+}
+
+export function parentDir(path: string): string {
+  const cut = path.replace(TRAILING_SLASHES, '').lastIndexOf('/')
+
+  return cut <= 0 ? '/' : path.slice(0, cut)
+}
+
+// Resolves a shell path argument against a directory, `~` included, `.` and `..` folded.
+export function resolvePath(base: string, arg: string, home: string): string {
+  const expanded = arg.replace(LEADING_TILDE, home)
+  const parts: string[] = []
+
+  for (const part of (expanded.startsWith('/') ? expanded : `${base}/${expanded}`).split('/')) {
+    if (part === '..')
+      parts.pop()
+    else if (part !== '' && part !== '.')
+      parts.push(part)
+  }
+
+  return `/${parts.join('/')}`
+}