Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

13.7 KB
Raw Blame
/**
 * Run a DSH's own commands — setup, doctor, workspace init, the viewer — the way the user's terminal
 * would: through their interactive shell, so `uv`, `npm`, `node` and `kicad-cli` resolve from the
 * PATH their rc files build, not from the detached daemon's. This is the same reasoning (and the
 * same shell selection) `engineLaunch.ts` uses to exec an engine in a pane.
 */
import { spawn, type ChildProcess } from 'node:child_process'
import { win32 } from 'node:path'
import { harnessNodePrelude, interactiveEngineShell } from '../lib/engineLaunch.js'
import { managedNodePath } from '../lib/nodeRuntime.js'
import { shellSingleQuote } from '../lib/shellQuote.js'
import { findGitBash, INSTALL_GIT_FOR_WINDOWS } from '../lib/windows/gitBash.js'
import { endGitBashTree, gitBashTreeDeps } from '../lib/windows/gitBashTree.js'
import { ownProcessGroup } from '../lib/windows/noWindow.js'

export interface DshCommandOptions {
  cwd: string
  env?: Record<string, string>
  /** Each line of combined stdout+stderr, as it arrives. */
  onLine?: (line: string) => void
  timeoutMs?: number
  /** The platform and Git Bash to run under, when not this computer's: a test runs Windows' path on any computer. */
  host?: DshShellHost
  /** What the command is, as said when it cannot start: a setup or check script unless said otherwise. */
  purpose?: DshCommandPurpose
}

/** What a DSH's command is to a person: a setup or a doctor, the viewer, or the workspace's init. */
export type DshCommandPurpose = 'setup or check script' | 'viewer' | 'workspace init'

export interface DshCommandResult {
  code: number | null
  signal: NodeJS.Signals | null
  lines: string[]
  timedOut: boolean
}

/**
 * What the shell itself says about being interactive without a terminal — not the DSH's output.
 * `zsh -lic` with no tty cannot enable the line editor, and an rc file that sets `zle` makes zsh
 * complain once per option. `bash -lic`, the usual shell on Linux, says it has no job control, and a
 * login bash says `logout` when a script exits. The engine never sees any of this because its pane
 * HAS a tty. Dropped so a doctor's lines, which the desktop shows verbatim, are the doctor's.
 */
export function isShellNoise(line: string): boolean {
  return /can't change option: zle$/.test(line) || /^\(eval\):\d+: can't change option: zle$/.test(line)
    || BASH_NO_TTY.test(line) || line === 'logout'
}

/**
 * The notice word for word, said by bash under a name it has: an interactive bash says its own base name (`bash`, Git
 * Bash's too), and the paths are the ones bash is installed at, `/usr/bin/bash` as Linux CI saw it. Not any
 * `<path>/bash:`, which dropped a script's own line that only looked like the notice (review of #2025).
 */
const BASH_NO_TTY = /^(?:bash|\/bin\/bash|\/usr\/bin\/bash): (?:cannot set terminal process group \(-?\d+\): Inappropriate ioctl for device|no job control in this shell)$/

/**
 * The shell's report of a job of its own that a signal ended (`/bin/sh: line 1: 31849 Terminated: 15  sleep 30`
 * on macOS, `bash: line 1: 31849 Terminated  sleep 30` on Linux). Once a command has outlived its timeout its
 * whole group is sent SIGTERM, and a shell that is still in `wait` when its job dies says so before it goes:
 * that is the stop, told by the shell, not the command's output. Seen under load (a full unit run with 12
 * busy loops), where the job's death reached the shell before the shell's own SIGTERM did.
 */
export function isKilledJobReport(line: string): boolean {
  return /^(?:\S*\/)?(?:ba)?sh: line \d+: +\d+ (?:Terminated|Killed)(?::\s*\d+)?\s+\S/.test(line)
}

/**
 * `[path, ...args]` that runs `script` through the user's shell, or `/bin/sh -c` when none is known; on Windows,
 * which has neither, through Git Bash (`gitBashArgv`).
 *
 * AS A LOGIN SHELL, whatever the shell. interactiveEngineShell gives bash `-ic` on purpose for a pane
 * (see tmuxOnPath.ts on why), but a bash user's PATH conventionally lives in `.bash_profile`, which
 * only `-l` reads — and Terminal.app opens a login shell, so that file is what "on my terminal it
 * works" means. Measured 2026-09-16: Solid's doctor answered `miss codex on PATH` from the daemon
 * while `harness dsh doctor` in Terminal found it, because codex was an npm global under nvm and nvm
 * is sourced from `.bash_profile`. A setup or a doctor is one process, so the reason bash panes avoid
 * `-l` (a PATH built in .bashrc compounding across subshells) does not apply here.
 */
export function dshShellArgv(
  script: string,
  host: DshShellHost = {},
  purpose: DshCommandPurpose = 'setup or check script',
): { path: string; args: string[]; env?: Record<string, string> } {
  if ((host.platform ?? process.platform) === 'win32') return gitBashArgv(script, (host.gitBash ?? findGitBash)(), purpose)
  const shell = interactiveEngineShell()
  const body = `${dshNodeFallback()}\n${script}`
  if (shell) {
    const args = shell.args.map((a) => (a === '-ic' ? '-lic' : a))
    return { path: shell.path, args: [...args, body] }
  }
  return { path: '/bin/sh', args: ['-c', body] }
}

/** The platform, the Git Bash lookup `dshShellArgv` uses and how a stop ends a run there; a test gives Windows' on
 *  any computer. */
export interface DshShellHost {
  platform?: NodeJS.Platform
  gitBash?: () => string | null
  /** Windows: end [pid] and everything it started (`endWindowsTree` by default). */
  endTree?: (pid: number) => Promise<unknown>
}

/** What a person is told when a package's setup or doctor cannot run here: a Windows computer without Git Bash, as an
 *  install's refusal (before the download, or once fetched) or as a command's one line. */
export const DSH_SHELL_UNAVAILABLE = `This harness runs a setup or check script, which needs Git Bash on Windows, and it was not found. ${INSTALL_GIT_FOR_WINDOWS}`

/** The same, said of the command that could not start. A viewer or a workspace init is not a setup or check script, and
 *  was called one (review of #2025). */
export function dshShellUnavailable(purpose: DshCommandPurpose): string {
  return purpose === 'setup or check script'
    ? DSH_SHELL_UNAVAILABLE
    : `This harness's ${purpose} needs Git Bash on Windows, and it was not found. ${INSTALL_GIT_FOR_WINDOWS}`
}

/**
 * Windows: Git Bash, as a login shell like the user's shell elsewhere, so its profile builds PATH (and puts cygpath
 * on it). Thrown when there is none, and runDshCommand reports that as the command's one line: the doctor or setup
 * says what to install, where `spawn /bin/sh ENOENT` said nothing a person could act on.
 *
 * Two lines go before the command. `unalias node`: Git Bash profiles can say `alias node='winpty node.exe'`, and winpty
 * fails with "stdin is not a tty" here, where the command's output is a pipe. And Harness's Node at the end of a PATH
 * with none, as `dshNodeFallback` does elsewhere, but written by cygpath: its folder is a `C:\...` path, whose colon
 * would split a Git Bash PATH in two. Both were found, and checked on Windows 11, by an outside contribution (#1511).
 *
 * CHERE_INVOKING: Git for Windows' /etc/profile changes a login shell to $HOME unless it is set, and a setup or doctor
 * runs in the harness's folder (review of #2025).
 */
function gitBashArgv(script: string, bash: string | null, purpose: DshCommandPurpose): { path: string; args: string[]; env: Record<string, string> } {
  if (!bash) throw new Error(dshShellUnavailable(purpose))
  const runtimeDir = shellSingleQuote(win32.dirname(managedNodePath()))
  const body = [
    'unalias node 2>/dev/null || true',
    `if ! command -v node >/dev/null 2>&1; then PATH="\${PATH:+$PATH:}$(cygpath -u -- ${runtimeDir})"; export PATH; fi`,
    script,
  ].join('\n')
  return { path: bash, args: ['-lic', body], env: { CHERE_INVOKING: '1' } }
}

/**
 * Whether this computer has a shell for a DSH's commands. Every Store install on Windows failed in its setup or doctor
 * (2026-10-28: 0 of 25 since 10-26): there was no shell there, and the `/bin/sh` fallback is not there. They run in
 * Git Bash now (`gitBashArgv`), so Windows has one when Git for Windows is installed; without it, an install is refused
 * before anything runs, with DSH_SHELL_UNAVAILABLE as its words.
 */
export function dshShellAvailable(host: DshShellHost = {}): boolean {
  return (host.platform ?? process.platform) !== 'win32' || (host.gitBash ?? findGitBash)() !== null
}

/**
 * The line run before a DSH's command: when the login shell's PATH has no `node`, the Node this
 * daemon runs on joins the END of it. Since the product moved to a private runtime, a machine with no
 * node on PATH is the normal case (see nodeRuntime.ts), and a package whose setup says `npm ci` or
 * whose viewer is `node viewer.mjs` would otherwise fail on exactly the machines Harness set up
 * itself. Appended, not prepended, so a node the person installed always wins; and run after the rc
 * files, so a profile that assigns PATH outright cannot drop it.
 */
export function dshNodeFallback(): string {
  return harnessNodePrelude(managedNodePath()).trimEnd()
}

export function spawnDshCommand(
  script: string,
  opts: { cwd: string; env?: Record<string, string>; host?: DshShellHost; purpose?: DshCommandPurpose },
): ChildProcess {
  const { path, args, env } = dshShellArgv(script, opts.host, opts.purpose)
  return spawn(path, args, {
    cwd: opts.cwd,
    env: { ...process.env, ...env, ...(opts.env ?? {}) },
    stdio: ['ignore', 'pipe', 'pipe'],
    // Its own process group, so stopping it stops what it started (`sh -c node …`). Windows ends the tree instead, and
    // Git Bash detached there would flash a window for each program it starts (docs/windows-rules.md).
    ...ownProcessGroup(),
  })
}

/** Run to completion, collecting output lines. Never rejects: a spawn failure is a non-zero exit. */
export function runDshCommand(script: string, opts: DshCommandOptions): Promise<DshCommandResult> {
  return new Promise((resolve) => {
    const lines: string[] = []
    let timedOut = false
    let settled = false
    let child: ChildProcess
    try {
      child = spawnDshCommand(script, { cwd: opts.cwd, env: opts.env, host: opts.host, purpose: opts.purpose })
    } catch (error) {
      // spawn throws only Errors (an invalid argument: a NUL in the cwd, say).
      const line = `could not start: ${(error as Error).message}`
      opts.onLine?.(line)
      resolve({ code: 127, signal: null, lines: [line], timedOut: false })
      return
    }
    const feed = (chunk: Buffer, carry: { rest: string }): void => {
      carry.rest += chunk.toString('utf8')
      let at: number
      while ((at = carry.rest.indexOf('\n')) >= 0) {
        const line = carry.rest.slice(0, at).replace(/\r$/, '')
        carry.rest = carry.rest.slice(at + 1)
        if (isShellNoise(line) || (timedOut && isKilledJobReport(line))) continue
        lines.push(line)
        opts.onLine?.(line)
      }
    }
    const out = { rest: '' }
    const err = { rest: '' }
    child.stdout?.on('data', (chunk: Buffer) => feed(chunk, out))
    child.stderr?.on('data', (chunk: Buffer) => feed(chunk, err))
    const finish = (code: number | null, signal: NodeJS.Signals | null): void => {
      if (settled) return
      settled = true
      if (timer) clearTimeout(timer)
      for (const carry of [out, err]) {
        if (carry.rest && !(timedOut && isKilledJobReport(carry.rest))) { lines.push(carry.rest); opts.onLine?.(carry.rest) }
      }
      resolve({ code, signal, lines, timedOut })
    }
    const timer = opts.timeoutMs
      ? setTimeout(() => {
        timedOut = true
        killProcessGroup(child, undefined, opts.host)
      }, opts.timeoutMs)
      : null
    timer?.unref?.()
    child.on('error', (error) => {
      const line = `could not start: ${error.message}`
      lines.push(line)
      opts.onLine?.(line)
      finish(127, null)
    })
    child.on('exit', (code, signal) => finish(code, signal))
  })
}

/** SIGTERM the child's whole group, then SIGKILL what is left a moment later; on Windows, end its tree. */
export function killProcessGroup(child: ChildProcess, graceMs = 3_000, host: DshShellHost = {}): void {
  const pid = child.pid
  if (!pid) return
  const timer = killPidGroup(pid, graceMs, host)
  child.once('exit', () => clearTimeout(timer))
}

/** [pid], a Git Bash run, and everything it started: what Git Bash lists as its tree and the Windows tree under each,
 *  the furthest first (lib/windows/gitBashTree.ts). */
function endWindowsTree(pid: number, gitBash: () => string | null): Promise<unknown> {
  return endGitBashTree(pid, gitBashTreeDeps(gitBash()))
}

/** The same, for a group this process did not spawn (a viewer left over from an earlier daemon —
 *  see viewerLedger.ts): nothing to wait on, so the SIGKILL follow-up fires unconditionally. */
export function killPidGroup(pid: number, graceMs = 3_000, host: DshShellHost = {}): NodeJS.Timeout {
  // pid 1 would make `-pid` "every process in my session"; nothing this daemon reaps is init.
  if (!Number.isInteger(pid) || pid <= 1) return setTimeout(() => {}, 0)
  // Windows has no process groups, so `-pid` names nothing, and a signal is TerminateProcess of that one process: Git
  // Bash's bin\bash.exe is a launcher, and ending it alone left the real bash, and what the setup or doctor started,
  // running after a timeout (review of #2025). Its whole tree is ended instead, at once: nothing there gets a SIGTERM.
  if ((host.platform ?? process.platform) === 'win32') {
    const endTree = host.endTree ?? ((root: number) => endWindowsTree(root, host.gitBash ?? findGitBash))
    void endTree(pid).catch(() => undefined)
    return setTimeout(() => {}, 0)
  }
  const signalGroup = (signal: NodeJS.Signals): void => {
    try { process.kill(-pid, signal) } catch { /* already gone */ }
    try { process.kill(pid, signal) } catch { /* already gone */ }
  }
  signalGroup('SIGTERM')
  const timer = setTimeout(() => signalGroup('SIGKILL'), graceMs)
  timer.unref?.()
  return timer
}