@williamthorsen/nmr 0.46.2 → 0.48.0

package/dist/esm/machine-lock.js

@@ -0,0 +1,229 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { isObject } from "./helpers/type-guards.js";
+const LOCK_FILE = 'heavy.lock';
+const RECLAIM_GUARD = 'heavy.lock.reclaim';
+const RECLAIM_GUARD_STALE_AFTER_MS = 10_000;
+export const HEARTBEAT_INTERVAL_MS = 10_000;
+export const HEAVY_COMMANDS = new Set([
+    'check',
+    'check:strict',
+    'ci',
+    'root:check',
+    'root:test',
+    'root:test:all',
+    'root:test:tool',
+    'root:test:unit',
+    'test',
+    'test:all',
+    'test:coverage',
+    'test:tool',
+    'test:unit',
+]);
+export const LOCK_DIR_ENV_VAR = 'NMR_LOCK_DIR';
+export const LOCK_TOKEN_ENV_VAR = 'NMR_MACHINE_LOCK_TOKEN';
+export const NO_LOCK_ENV_VAR = 'NMR_NO_LOCK';
+export const POLL_INTERVAL_MS = 1_000;
+export const STALE_AFTER_MS = 60_000;
+export async function acquireMachineLock(options) {
+    const { command, dir, env, stderr } = options;
+    if (env[NO_LOCK_ENV_VAR] === '1') {
+        return createHoldFreeLock({ isChainUnlocked: true, waited: false });
+    }
+    const lockDir = options.lockDir ?? resolveLockDir({ env, platform: process.platform, uid: process.getuid?.() });
+    if (await isUnderAncestorHold(lockDir, env)) {
+        return createHoldFreeLock({ isChainUnlocked: false, waited: false });
+    }
+    const lockPath = path.join(lockDir, LOCK_FILE);
+    try {
+        await fs.mkdir(lockDir, { recursive: true, mode: 0o700 });
+    }
+    catch (error) {
+        reportUnwritableDir(lockDir, error, stderr);
+        return createHoldFreeLock({ isChainUnlocked: true, waited: false });
+    }
+    const heartbeatIntervalMs = options.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
+    const staleAfterMs = options.staleAfterMs ?? STALE_AFTER_MS;
+    const record = {
+        command,
+        dir,
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        token: randomUUID(),
+    };
+    let waited = false;
+    let reportedHolder;
+    for (;;) {
+        try {
+            await fs.writeFile(lockPath, JSON.stringify(record), { flag: 'wx' });
+            return createHeldLock({ heartbeatIntervalMs, lockPath, token: record.token, waited });
+        }
+        catch (error) {
+            if (readErrorCode(error) !== 'EEXIST') {
+                reportUnwritableDir(lockDir, error, stderr);
+                return createHoldFreeLock({ isChainUnlocked: true, waited });
+            }
+        }
+        const state = await readLockState(lockPath);
+        if (state === undefined) {
+            continue;
+        }
+        if (isStale(state, staleAfterMs)) {
+            await reclaimStaleLock({ lockDir, lockPath, observed: state, staleAfterMs });
+            continue;
+        }
+        const holderIdentity = state.holder?.token ?? 'unreadable';
+        if (holderIdentity !== reportedHolder) {
+            stderr.write(`${formatWaitingLine(state.holder, lockPath)}\n`);
+            reportedHolder = holderIdentity;
+        }
+        waited = true;
+        await delay(pollIntervalMs);
+    }
+}
+export function formatMisplacedNoLockWarning(command, style) {
+    return (`${STATUS_GLYPHS[style].warning.text} --no-lock after the command name is passed to \`${command}\`, ` +
+        `not read by nmr. Did you mean \`nmr --no-lock ${command}\`?`);
+}
+export function resolveLockDir(options) {
+    const { env, platform, uid } = options;
+    const override = env[LOCK_DIR_ENV_VAR];
+    if (override !== undefined && override !== '') {
+        return override;
+    }
+    if (platform === 'win32' || uid === undefined) {
+        return path.join(os.tmpdir(), 'nmr');
+    }
+    return `/tmp/nmr-${uid}`;
+}
+function createHeldLock(options) {
+    const { heartbeatIntervalMs, lockPath, token, waited } = options;
+    const heartbeat = setInterval(() => void refreshMtime(lockPath), heartbeatIntervalMs);
+    heartbeat.unref();
+    let isReleased = false;
+    return {
+        isChainUnlocked: false,
+        async release() {
+            if (isReleased)
+                return;
+            isReleased = true;
+            clearInterval(heartbeat);
+            const state = await readLockState(lockPath);
+            if (state?.holder?.token === token) {
+                await fs.rm(lockPath, { force: true });
+            }
+        },
+        token,
+        waited,
+    };
+}
+function createHoldFreeLock(options) {
+    return { ...options, release: () => Promise.resolve(), token: undefined };
+}
+function formatWaitingLine(holder, lockPath) {
+    if (holder === undefined) {
+        return `nmr: waiting for the machine lock at ${lockPath}`;
+    }
+    return `nmr: waiting for ${holder.command} in ${holder.dir} (pid ${holder.pid}) to finish`;
+}
+function isHolderRecord(value) {
+    return (isObject(value) &&
+        typeof value['command'] === 'string' &&
+        typeof value['dir'] === 'string' &&
+        typeof value['pid'] === 'number' &&
+        typeof value['startedAt'] === 'string' &&
+        typeof value['token'] === 'string');
+}
+async function isUnderAncestorHold(lockDir, env) {
+    const inheritedToken = env[LOCK_TOKEN_ENV_VAR];
+    if (inheritedToken === undefined || inheritedToken === '') {
+        return false;
+    }
+    const state = await readLockState(path.join(lockDir, LOCK_FILE));
+    return state?.holder?.token === inheritedToken;
+}
+function isProcessGone(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return readErrorCode(error) === 'ESRCH';
+    }
+}
+function isStale(state, staleAfterMs) {
+    if (Date.now() - state.mtimeMs > staleAfterMs) {
+        return true;
+    }
+    return state.holder !== undefined && isProcessGone(state.holder.pid);
+}
+function parseHolder(content) {
+    try {
+        const value = JSON.parse(content);
+        return isHolderRecord(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readErrorCode(error) {
+    return isObject(error) && typeof error['code'] === 'string' ? error['code'] : undefined;
+}
+async function readLockState(lockPath) {
+    try {
+        const [content, stats] = await Promise.all([fs.readFile(lockPath, 'utf8'), fs.stat(lockPath)]);
+        return { holder: parseHolder(content), mtimeMs: stats.mtimeMs };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function reclaimStaleLock(options) {
+    const { lockDir, lockPath, observed, staleAfterMs } = options;
+    const guardPath = path.join(lockDir, RECLAIM_GUARD);
+    try {
+        await fs.mkdir(guardPath);
+    }
+    catch {
+        await removeAbandonedGuard(guardPath);
+        return;
+    }
+    try {
+        const current = await readLockState(lockPath);
+        if (current !== undefined && current.holder?.token === observed.holder?.token && isStale(current, staleAfterMs)) {
+            await fs.rm(lockPath, { force: true });
+        }
+    }
+    finally {
+        await fs.rm(guardPath, { force: true, recursive: true });
+    }
+}
+async function refreshMtime(lockPath) {
+    const now = new Date();
+    try {
+        await fs.utimes(lockPath, now, now);
+    }
+    catch {
+    }
+}
+async function removeAbandonedGuard(guardPath) {
+    try {
+        const stats = await fs.stat(guardPath);
+        if (Date.now() - stats.mtimeMs > RECLAIM_GUARD_STALE_AFTER_MS) {
+            await fs.rm(guardPath, { force: true, recursive: true });
+        }
+    }
+    catch {
+    }
+}
+function reportUnwritableDir(lockDir, error, stderr) {
+    const code = readErrorCode(error) ?? 'unknown error';
+    stderr.write(`nmr: running without the machine lock: cannot write ${lockDir} (${code}). ` +
+        `Grant write access to it, or set ${LOCK_DIR_ENV_VAR} to a writable directory.\n`);
+}

package/dist/esm/remote-run.d.ts

@@ -0,0 +1,136 @@
+import type { Writable } from 'node:stream';
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+/** Names the host to which nmr delegates a command when the invocation does not say otherwise. */
+export declare const DELEGATE_ENV_VAR = "NMR_DELEGATE";
+/** The flag that names the host on which to run the command. */
+export declare const DELEGATE_FLAG = "--delegate";
+/** The exit status of a delegation that failed outside its command, which matches `ssh`'s own. */
+export declare const DELEGATION_FAILURE_EXIT_CODE = 255;
+/** The flag that runs the command here, whatever `NMR_DELEGATE` names. */
+export declare const NO_DELEGATE_FLAG = "--no-delegate";
+/** Keeps `ssh` from prompting or waiting on a terminal, and bounds the wait for a host that does not answer. */
+export declare const SSH_OPTIONS: readonly string[];
+/** Where a delegation runs, or why the invocation cannot run where it asked to. */
+export type DelegationTarget = {
+    kind: 'local';
+} | {
+    kind: 'remote';
+    host: string;
+    source: 'env' | 'flag';
+} | {
+    kind: 'refused';
+    error: string;
+};
+/** The phases of a delegation that run on the host, each reported by name when it fails. */
+export type RemotePhase = 'check out' | 'install' | 'prepare' | 'push' | 'run';
+/** The status of a delegated command, or the phase that kept it from finishing and what that phase printed. */
+export type RemoteRunResult = {
+    ok: true;
+    exitCode: number;
+} | {
+    ok: false;
+    message: string;
+    output: string;
+    phase: RemotePhase;
+};
+/** A commit that records the working tree, or why one could not be made. */
+export type SnapshotResult = {
+    ok: true;
+    sha: string;
+    toplevel: string;
+} | {
+    ok: false;
+    isUnsupported: boolean;
+    reason: string;
+};
+/**
+ * Composes the script that runs nmr on the host, from the directory that corresponds to the local one.
+ *
+ * A Node launcher starts nmr in its own process group, with stdin closed, and reads the connection's stdin, which the
+ * local `ssh` holds open and closes when it exits, as on Ctrl-C; on that end of input, the launcher stops nmr's whole
+ * group, so that an interrupted run does not continue on the host. The launcher rather than the shell's job control
+ * makes the group, because a shell such as dash refuses job control without a terminal. `--no-delegate` keeps a host
+ * whose environment sets `NMR_DELEGATE` from passing the command on again.
+ *
+ * The script writes nmr's status to `statusPath` before it exits, so that a 255 from `ssh` can be told apart: It is
+ * nmr's own when the file records it, and a dropped connection otherwise.
+ *
+ * @internal
+ */
+export declare function composeRunScript(options: {
+    nmrArgs: readonly string[];
+    remoteEnv: Readonly<Record<string, string>>;
+    runDir: string;
+    statusPath: string;
+}): string;
+/**
+ * Builds a commit whose tree is the working tree as it is on disk: tracked changes, staged or not, and untracked
+ * files that git does not ignore. The commit is built in a temporary index, so the repository's index, refs, and
+ * stash are untouched; the only write is to the object database.
+ *
+ * The identity and date are fixed, so that the same tree on the same `HEAD` always yields the same commit and a
+ * repeated push transfers nothing. A submodule, or a nested repository that `git add` would record as one, is
+ * refused: Its content is in a repository that the snapshot does not include.
+ */
+export declare function createSnapshot(cwd: string, env: NodeJS.ProcessEnv): SnapshotResult;
+/**
+ * Returns the checkout's path on the host, relative to its home directory: a key derived from this machine and the
+ * repository, followed by the repository's own directory name, which nmr on the host reports as the root's scope.
+ *
+ * @internal
+ */
+export declare function deriveCheckoutPath(hostname: string, toplevel: string): string;
+/**
+ * Renders the warning for a `--delegate` or `--no-delegate` that appears after the command name, which makes it an
+ * argument to the command rather than a flag to nmr.
+ */
+export declare function formatMisplacedDelegationWarning(command: string, style: OutputStyle): string;
+/**
+ * Decides where an invocation runs. `--no-delegate` outranks `--delegate`, which outranks `NMR_DELEGATE`.
+ *
+ * A command that rewrites the tree, or that runs until it is stopped, cannot be delegated, and neither can `--log`,
+ * which reads this machine's recordings. Asked for by the flag, such an invocation is refused; asked for by the
+ * variable, which sets a default for every invocation, it runs here.
+ */
+export declare function resolveDelegationTarget(options: {
+    command: string;
+    env: NodeJS.ProcessEnv;
+    flagHost: string | undefined;
+    isOptedOut: boolean;
+    isReading: boolean;
+}): DelegationTarget;
+/**
+ * Runs an nmr invocation on `host` against a snapshot of the local working tree, streaming the command's output to
+ * `stdout` and `stderr` and returning its exit status.
+ *
+ * The host keeps one checkout per local repository and host name, under `~/.cache/nmr/delegate/`, so concurrent
+ * delegations from different worktrees do not share a checkout, and `node_modules` and build output persist
+ * between runs. Each phase is its own connection, so that a failure names its phase; what a phase other than `run`
+ * prints is returned rather than streamed, because it matters only when the phase fails.
+ */
+export declare function runRemotely(options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    host: string;
+    monorepoRoot: string;
+    nmrArgs: readonly string[];
+    remoteEnv: Readonly<Record<string, string>>;
+    snapshot: {
+        sha: string;
+        toplevel: string;
+    };
+    stderr: Writable;
+    stdout: Writable;
+}): Promise<RemoteRunResult>;
+/**
+ * Wraps a script to run under `/bin/sh` with the `PATH` that the user's interactive login shell sets. pnpm's own
+ * installer and the common version managers set it up in the interactive startup file, such as `~/.zshrc`, which a
+ * non-interactive shell does not read. The script runs under `sh` rather than that shell itself, because the login
+ * shell, such as fish, may not accept the POSIX syntax in which the scripts are written.
+ *
+ * A startup file may print to stdout, so the shell prints `PATH` after a marker, and only what follows the last
+ * marker is read. When no marker arrives, the script keeps the `PATH` with which `ssh` started it.
+ *
+ * @internal
+ */
+export declare function wrapRemoteScript(script: string): string;

package/dist/esm/remote-run.js

@@ -0,0 +1,251 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { GIT_OUTPUT_LIMIT, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
+import { quoteForShell } from "./helpers/quoteForShell.js";
+export const DELEGATE_ENV_VAR = 'NMR_DELEGATE';
+export const DELEGATE_FLAG = '--delegate';
+export const DELEGATION_FAILURE_EXIT_CODE = 255;
+export const NO_DELEGATE_FLAG = '--no-delegate';
+export const SSH_OPTIONS = ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10'];
+export function composeRunScript(options) {
+    const { nmrArgs, remoteEnv, runDir, statusPath } = options;
+    const assignments = Object.entries(remoteEnv).map(([name, value]) => `${name}=${quoteForShell(value)}`);
+    const invocation = [
+        ...assignments,
+        'node',
+        '-e',
+        quoteForShell(RUN_LAUNCHER_SOURCE),
+        'pnpm',
+        'exec',
+        'nmr',
+        '--no-delegate',
+        ...nmrArgs.map(quoteForShell),
+    ].join(' ');
+    return [
+        `rm -f ${statusPath}`,
+        `mkdir -p ${runDir} && cd ${runDir} || exit 1`,
+        invocation,
+        'nmr_status=$?',
+        String.raw `printf '%s\n' "$nmr_status" > ${statusPath}`,
+        'exit "$nmr_status"',
+    ].join('\n');
+}
+export function createSnapshot(cwd, env) {
+    const toplevelResult = runGit(['rev-parse', '--show-toplevel'], cwd, env);
+    if (!toplevelResult.ok) {
+        return { ok: false, isUnsupported: true, reason: `not a git repository: ${toplevelResult.error}` };
+    }
+    const toplevel = toplevelResult.stdout.trim();
+    if (fs.existsSync(path.join(toplevel, '.gitmodules'))) {
+        return { ok: false, isUnsupported: true, reason: 'the repository declares submodules' };
+    }
+    const indexPathResult = runGit(['rev-parse', '--git-path', 'index'], toplevel, env);
+    if (!indexPathResult.ok) {
+        return { ok: false, isUnsupported: false, reason: indexPathResult.error };
+    }
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nmr-snapshot-'));
+    try {
+        const tempIndex = path.join(tempDir, 'index');
+        const indexPath = path.resolve(toplevel, indexPathResult.stdout.trim());
+        if (fs.existsSync(indexPath)) {
+            fs.copyFileSync(indexPath, tempIndex);
+        }
+        const indexEnv = { ...env, GIT_INDEX_FILE: tempIndex };
+        const addResult = runGit(['add', '--all'], toplevel, indexEnv);
+        if (!addResult.ok) {
+            return { ok: false, isUnsupported: false, reason: addResult.error };
+        }
+        const stageResult = runGit(['ls-files', '--stage', '-z'], toplevel, indexEnv);
+        if (!stageResult.ok) {
+            return { ok: false, isUnsupported: false, reason: stageResult.error };
+        }
+        if (stageResult.stdout.split('\0').some((entry) => entry.startsWith('160000 '))) {
+            return { ok: false, isUnsupported: true, reason: 'the working tree contains a submodule or a nested repository' };
+        }
+        const treeResult = runGit(['write-tree'], toplevel, indexEnv);
+        if (!treeResult.ok) {
+            return { ok: false, isUnsupported: false, reason: treeResult.error };
+        }
+        const headResult = runGit(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], toplevel, env);
+        const parentArgs = headResult.ok ? ['-p', headResult.stdout.trim()] : [];
+        const commitResult = runGit(['commit-tree', treeResult.stdout.trim(), ...parentArgs, '-m', 'nmr delegate snapshot'], toplevel, { ...env, ...SNAPSHOT_IDENTITY_ENV });
+        if (!commitResult.ok) {
+            return { ok: false, isUnsupported: false, reason: commitResult.error };
+        }
+        return { ok: true, sha: commitResult.stdout.trim(), toplevel };
+    }
+    finally {
+        fs.rmSync(tempDir, { force: true, recursive: true });
+    }
+}
+export function deriveCheckoutPath(hostname, toplevel) {
+    const key = createHash('sha256').update(`${hostname}\0${toplevel}`).digest('hex').slice(0, 16);
+    return path.posix.join('.cache/nmr/delegate', key, path.basename(toplevel));
+}
+export function formatMisplacedDelegationWarning(command, style) {
+    return (`${STATUS_GLYPHS[style].warning.text} ${DELEGATE_FLAG} and ${NO_DELEGATE_FLAG} after the command name are passed ` +
+        `to \`${command}\`, not read by nmr. Did you mean \`nmr ${DELEGATE_FLAG} <host> ${command}\`?`);
+}
+export function resolveDelegationTarget(options) {
+    const { command, env, flagHost, isOptedOut, isReading } = options;
+    if (isOptedOut) {
+        return { kind: 'local' };
+    }
+    const isDelegable = !isReading && !NON_DELEGABLE_COMMANDS.has(command);
+    if (flagHost !== undefined) {
+        if (isDelegable) {
+            return { kind: 'remote', host: flagHost, source: 'flag' };
+        }
+        const subject = isReading ? '--log' : `\`${command}\``;
+        return {
+            kind: 'refused',
+            error: `${subject} cannot be delegated: it ${isReading ? "reads this machine's recordings" : 'rewrites the working tree or runs until stopped'}. Run it without ${DELEGATE_FLAG}.`,
+        };
+    }
+    const envHost = env[DELEGATE_ENV_VAR];
+    if (envHost !== undefined && envHost !== '' && isDelegable) {
+        return { kind: 'remote', host: envHost, source: 'env' };
+    }
+    return { kind: 'local' };
+}
+export async function runRemotely(options) {
+    const { cwd, env, host, monorepoRoot, nmrArgs, remoteEnv, snapshot, stderr, stdout } = options;
+    const checkoutPath = deriveCheckoutPath(os.hostname(), snapshot.toplevel);
+    const checkoutDir = `"$HOME"/${quoteForShell(checkoutPath)}`;
+    const prepare = await runSsh(host, `mkdir -p ${checkoutDir} && cd ${checkoutDir} && { [ -d .git ] || git init --quiet; }`, env);
+    if (prepare.exitCode !== 0) {
+        return { ok: false, message: `could not prepare ${host}`, output: prepare.output, phase: 'prepare' };
+    }
+    const push = await runProcess([
+        'git',
+        'push',
+        '--force',
+        '--no-verify',
+        '--quiet',
+        `--receive-pack=${RECEIVE_PACK_COMMAND}`,
+        `${host}:${checkoutPath}`,
+        `${snapshot.sha}:${SNAPSHOT_REF}`,
+    ], { cwd: snapshot.toplevel, env: { ...env, GIT_SSH_COMMAND: ['ssh', ...SSH_OPTIONS].join(' ') } });
+    if (push.exitCode !== 0) {
+        return { ok: false, message: `could not push to ${host}`, output: push.output, phase: 'push' };
+    }
+    const checkout = await runSsh(host, `cd ${checkoutDir} && git checkout --quiet --force --detach ${snapshot.sha} && git clean --force -d --quiet`, env);
+    if (checkout.exitCode !== 0) {
+        return { ok: false, message: `could not check out on ${host}`, output: checkout.output, phase: 'check out' };
+    }
+    const rootDir = joinRemotePath(checkoutDir, path.relative(snapshot.toplevel, monorepoRoot));
+    const install = await runSsh(host, `cd ${rootDir} && CI=true pnpm install --frozen-lockfile`, env);
+    if (install.exitCode !== 0) {
+        const message = install.exitCode === COMMAND_NOT_FOUND_EXIT_CODE
+            ? `could not install on ${host}: pnpm is not on the PATH that the interactive login shell sets there`
+            : `could not install on ${host}`;
+        return { ok: false, message, output: install.output, phase: 'install' };
+    }
+    const runDir = joinRemotePath(checkoutDir, path.relative(snapshot.toplevel, cwd));
+    const statusPath = `${checkoutDir}/.git/${quoteForShell(RUN_STATUS_FILE)}`;
+    const run = await runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(composeRunScript({ nmrArgs, remoteEnv, runDir, statusPath }))], {
+        env,
+        isStreaming: true,
+        stderr,
+        stdout,
+    });
+    if (run.exitCode === DELEGATION_FAILURE_EXIT_CODE) {
+        const recorded = await runSsh(host, `cat ${statusPath}`, env);
+        if (recorded.exitCode !== 0 || recorded.output.trim() !== String(DELEGATION_FAILURE_EXIT_CODE)) {
+            return { ok: false, message: `lost connection to ${host}`, output: '', phase: 'run' };
+        }
+    }
+    return { ok: true, exitCode: run.exitCode };
+}
+export function wrapRemoteScript(script) {
+    return `exec /bin/sh -c ${quoteForShell(`${LOGIN_PATH_PREAMBLE}\n${script}`)}`;
+}
+const PATH_MARKER = '__NMR_LOGIN_PATH__=';
+const LOGIN_PATH_PREAMBLE = [
+    `nmr_login_path=$("\${SHELL:-/bin/sh}" -ilc 'printf "\\n${PATH_MARKER}%s\\n" "$PATH"' </dev/null 2>/dev/null | sed -n 's/^${PATH_MARKER}//p' | tail -n 1)`,
+    '[ -n "$nmr_login_path" ] && PATH=$nmr_login_path',
+    'export PATH',
+].join('; ');
+const RECEIVE_PACK_COMMAND = `/bin/sh -c ${quoteForShell(`${LOGIN_PATH_PREAMBLE}; exec git receive-pack "$1"`)} nmr-receive-pack`;
+const RUN_LAUNCHER_SOURCE = [
+    "const { spawn } = require('node:child_process');",
+    "const { constants } = require('node:os');",
+    'const [file, ...args] = process.argv.slice(1);',
+    "const child = spawn(file, args, { detached: true, stdio: ['ignore', 'inherit', 'inherit'] });",
+    "const stop = () => { try { process.kill(-child.pid, 'SIGTERM'); } catch {} };",
+    "process.stdin.on('end', stop).on('error', stop).resume();",
+    "child.on('error', (error) => { console.error(file + ': ' + error.message); process.exit(127); });",
+    "child.on('close', (code, signal) => process.exit(code ?? 128 + (constants.signals[signal] ?? 0)));",
+].join('\n');
+const RUN_STATUS_FILE = 'nmr-run-status';
+const COMMAND_NOT_FOUND_EXIT_CODE = 127;
+const PHASE_OUTPUT_LIMIT_BYTES = 65_536;
+const NON_DELEGABLE_BASE_COMMANDS = ['build', 'clean', 'compile', 'fix', 'fmt', 'lint', 'test:watch', 'upgrade'];
+const NON_DELEGABLE_COMMANDS = new Set([
+    ...NON_DELEGABLE_BASE_COMMANDS,
+    ...NON_DELEGABLE_BASE_COMMANDS.map((command) => `root:${command}`),
+]);
+const SNAPSHOT_IDENTITY_ENV = {
+    GIT_AUTHOR_DATE: '@0 +0000',
+    GIT_AUTHOR_EMAIL: 'nmr@localhost',
+    GIT_AUTHOR_NAME: 'nmr delegate',
+    GIT_COMMITTER_DATE: '@0 +0000',
+    GIT_COMMITTER_EMAIL: 'nmr@localhost',
+    GIT_COMMITTER_NAME: 'nmr delegate',
+};
+const SNAPSHOT_REF = 'refs/nmr/delegate';
+function forwardChunk(chunk, stream, buffer) {
+    if (stream === undefined) {
+        buffer.append(chunk);
+        return;
+    }
+    stream.write(chunk);
+}
+function joinRemotePath(checkoutDir, relativeDir) {
+    const posixDir = relativeDir.split(path.sep).join('/');
+    return posixDir === '' ? checkoutDir : `${checkoutDir}/${quoteForShell(posixDir)}`;
+}
+function runGit(args, cwd, env) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', env, maxBuffer: GIT_OUTPUT_LIMIT });
+    if (result.error !== undefined) {
+        return { ok: false, error: result.error.message };
+    }
+    if (result.status !== 0) {
+        return { ok: false, error: result.stderr.trim() || `git ${args[0] ?? ''} exited ${result.status ?? 'abnormally'}` };
+    }
+    return { ok: true, stdout: result.stdout };
+}
+function runProcess(argv, options) {
+    const { cwd, env, isStreaming = false, stderr, stdout } = options;
+    const [file = '', ...args] = argv;
+    const buffer = createBoundedBuffer({
+        headLimitBytes: PHASE_OUTPUT_LIMIT_BYTES,
+        tailLimitBytes: PHASE_OUTPUT_LIMIT_BYTES,
+    });
+    return new Promise((resolve) => {
+        const child = spawn(file, args, { cwd, env, stdio: [isStreaming ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
+        child.stdout?.on('data', (chunk) => {
+            forwardChunk(chunk, isStreaming ? stdout : undefined, buffer);
+        });
+        child.stderr?.on('data', (chunk) => {
+            forwardChunk(chunk, isStreaming ? stderr : undefined, buffer);
+        });
+        child.on('error', (error) => {
+            resolve({ exitCode: COMMAND_NOT_FOUND_EXIT_CODE, output: `${file}: ${error.message}` });
+        });
+        child.on('close', (code, signal) => {
+            child.stdin?.destroy();
+            resolve({
+                exitCode: code ?? 128 + (signal === null ? 0 : os.constants.signals[signal]),
+                output: buffer.readBuffer().toString('utf8'),
+            });
+        });
+    });
+}
+function runSsh(host, script, env) {
+    return runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(script)], { env });
+}