@williamthorsen/nmr 0.47.0 → 0.49.0

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

@@ -0,0 +1,31 @@
+import { type HostList } from './remote-run.js';
+/** What a probe found on a host: whether a delegation started now would wait there, or that the host did not answer. */
+export type ProbeResult = 'busy' | 'free' | 'no-answer';
+/**
+ * Probes every host at once and resolves to the one on which to run, per `selectHost`, as soon as the results that
+ * have arrived settle it. Reports each result that arrives before then, and aborts the probes still running once it
+ * has chosen.
+ */
+export declare function chooseHost(options: {
+    hosts: HostList;
+    onSettled: (host: string, result: ProbeResult) => void;
+    probe: (host: string, signal: AbortSignal) => Promise<ProbeResult>;
+}): Promise<string>;
+/**
+ * Asks `host` whether a delegation from this checkout would wait there: whether its machine lock, or the lock of the
+ * checkout at `checkoutPath`, has a live holder. A host that fails to run the probe, or does not print its report,
+ * did not answer.
+ */
+export declare function probeHost(options: {
+    checkoutPath: string;
+    env: NodeJS.ProcessEnv;
+    host: string;
+    signal: AbortSignal;
+}): Promise<ProbeResult>;
+/**
+ * Returns the host on which to run, or `undefined` while a host whose result could change the choice has not
+ * answered: the first free host in list order, otherwise the first busy one, otherwise the first host.
+ *
+ * @internal
+ */
+export declare function selectHost(hosts: HostList, results: ReadonlyMap<string, ProbeResult>): string | undefined;

package/dist/esm/remote-probe.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { quoteForShell } from "./helpers/quoteForShell.js";
+import { isObject } from "./helpers/type-guards.js";
+import { LOCK_DIR_ENV_VAR, LOCK_FILE, STALE_AFTER_MS } from "./machine-lock.js";
+import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
+import { probeHostLocks } from "./remote-probe-host.js";
+import { runSsh } from "./remote-run.js";
+export function chooseHost(options) {
+    const { hosts, onSettled, probe } = options;
+    const controller = new AbortController();
+    const results = new Map();
+    return new Promise((resolve) => {
+        for (const host of hosts) {
+            void settle(host, resolve);
+        }
+    });
+    async function settle(host, resolve) {
+        let result;
+        try {
+            result = await probe(host, controller.signal);
+        }
+        catch {
+            result = 'no-answer';
+        }
+        if (controller.signal.aborted)
+            return;
+        results.set(host, result);
+        onSettled(host, result);
+        const chosen = selectHost(hosts, results);
+        if (chosen === undefined)
+            return;
+        controller.abort();
+        resolve(chosen);
+    }
+}
+export async function probeHost(options) {
+    const { checkoutPath, env, host, signal } = options;
+    const params = {
+        checkoutLockPath: path.posix.join(checkoutPath, CHECKOUT_LOCK_PATH),
+        lockDirEnvVar: LOCK_DIR_ENV_VAR,
+        machineLockFile: LOCK_FILE,
+        staleAfterMs: STALE_AFTER_MS,
+    };
+    const source = `(${probeHostLocks.toString()})(JSON.parse(process.argv[1]));`;
+    const { exitCode, output } = await runSsh(host, `exec node -e ${quoteForShell(source)} ${quoteForShell(JSON.stringify(params))}`, env, signal);
+    if (exitCode !== 0) {
+        return 'no-answer';
+    }
+    const busy = output
+        .split('\n')
+        .map(readBusyField)
+        .findLast((value) => value !== undefined);
+    if (busy === undefined) {
+        return 'no-answer';
+    }
+    return busy ? 'busy' : 'free';
+}
+export function selectHost(hosts, results) {
+    for (const host of hosts) {
+        const result = results.get(host);
+        if (result === undefined) {
+            return undefined;
+        }
+        if (result === 'free') {
+            return host;
+        }
+    }
+    return hosts.find((host) => results.get(host) === 'busy') ?? hosts[0];
+}
+function readBusyField(line) {
+    try {
+        const value = JSON.parse(line);
+        return isObject(value) && typeof value['busy'] === 'boolean' ? value['busy'] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,91 @@
+import type { Writable } from 'node:stream';
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+/** Names the hosts to which nmr delegates a command when the invocation does not say otherwise. */
+export declare const DELEGATE_ENV_VAR = "NMR_DELEGATE";
+/** The flag that runs the command on a host that `NMR_DELEGATE` or the user config names. */
+export declare const DELEGATE_FLAG = "--delegate";
+/** The flag that names the hosts on which to run the command. */
+export declare const DELEGATE_TO_FLAG = "--delegate-to";
+/** 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` or the user config says. */
+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[];
+/** Candidate hosts in order of preference. */
+export type HostList = readonly [string, ...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 and the pass-manifest entries that its run reported, unvalidated, or the phase
+ * that kept it from finishing and what that phase printed, with how long the delegation waited for another
+ * delegation's checkout.
+ */
+export type RemoteRunResult = {
+    ok: true;
+    exitCode: number;
+    passes: unknown[];
+    waitedMs: number;
+} | {
+    ok: false;
+    message: string;
+    output: string;
+    phase: RemotePhase;
+    waitedMs: number;
+};
+/**
+ * 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 delegation flag 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;
+/**
+ * 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. Check out, install, and run take one connection, whose session holds the checkout's lock, so that two
+ * delegations from one worktree run one after the other; 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: {
+    command: string;
+    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>;
+/**
+ * Runs a script on the host through `wrapRemoteScript`, capturing what it prints. An abort stops the `ssh` process.
+ */
+export declare function runSsh(host: string, script: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<{
+    exitCode: number;
+    output: string;
+}>;
+/**
+ * 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,189 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { PASS_MANIFEST_DIR_ENV_VAR, writeDebugNote } from "./check-cache.js";
+import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
+import { quoteForShell } from "./helpers/quoteForShell.js";
+import { STALE_AFTER_MS } from "./machine-lock.js";
+import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
+import { composeSessionScript, createSessionDemultiplexer, formatDelegationWaitingLine } from "./remote-session.js";
+export const DELEGATE_ENV_VAR = 'NMR_DELEGATE';
+export const DELEGATE_FLAG = '--delegate';
+export const DELEGATE_TO_FLAG = '--delegate-to';
+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 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}, ${DELEGATE_TO_FLAG}, and ${NO_DELEGATE_FLAG} after the ` +
+        `command name are passed to \`${command}\`, not read by nmr. Write them before it: ` +
+        `\`nmr ${DELEGATE_TO_FLAG} <host> ${command}\`.`);
+}
+export async function runRemotely(options) {
+    const { command, 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', waitedMs: 0 };
+    }
+    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', waitedMs: 0 };
+    }
+    const nonce = randomUUID();
+    const marker = `__NMR_DELEGATE_${nonce}__`;
+    const statusFile = `.git/nmr-run-status-${nonce}`;
+    const passes = [];
+    let waitStartedAtMs;
+    let waitedMs = 0;
+    let failure;
+    const demultiplexer = createSessionDemultiplexer({
+        marker,
+        onRecord(record) {
+            if (record.kind === 'waiting') {
+                waitStartedAtMs ??= Date.now();
+                stderr.write(`${formatDelegationWaitingLine(record.holder, host)}\n`);
+            }
+            else if (record.kind === 'locked' && waitStartedAtMs !== undefined) {
+                waitedMs = Date.now() - waitStartedAtMs;
+            }
+            else if (record.kind === 'failed') {
+                failure = record;
+            }
+            else if (record.kind === 'passes') {
+                passes.push(...record.entries);
+            }
+        },
+        onMalformedRecord() {
+            writeDebugNote(`discarded a malformed pass manifest from ${host}`, env, stderr);
+        },
+        stderr,
+    });
+    const script = composeSessionScript({
+        checkoutDir,
+        params: {
+            holder: { command, dir: cwd, pid: process.pid },
+            lockPath: CHECKOUT_LOCK_PATH,
+            marker,
+            nmrArgs,
+            passManifestDir: `.git/nmr-passes-${nonce}`,
+            passManifestEnvVar: PASS_MANIFEST_DIR_ENV_VAR,
+            remoteEnv,
+            rootDir: toRemoteRelativeDir(path.relative(snapshot.toplevel, monorepoRoot)),
+            runDir: toRemoteRelativeDir(path.relative(snapshot.toplevel, cwd)),
+            sha: snapshot.sha,
+            staleAfterMs: STALE_AFTER_MS,
+            statusFile,
+        },
+    });
+    const session = await runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(script)], {
+        env,
+        isStreaming: true,
+        stderr: demultiplexer.stream,
+        stdout,
+    });
+    demultiplexer.flush();
+    if (failure !== undefined) {
+        const output = [demultiplexer.readOutput(), failure.output].filter((text) => text !== '').join('\n');
+        return { ok: false, message: describeFailedPhase(failure, host), output, phase: failure.phase, waitedMs };
+    }
+    if (!demultiplexer.hasStarted()) {
+        return {
+            ok: false,
+            message: describeUnfinishedSession(session.exitCode, host),
+            output: demultiplexer.readOutput(),
+            phase: 'check out',
+            waitedMs,
+        };
+    }
+    if (session.exitCode === DELEGATION_FAILURE_EXIT_CODE) {
+        const recorded = await runSsh(host, `cd ${checkoutDir} && cat ${quoteForShell(statusFile)} && rm -f ${quoteForShell(statusFile)}`, env);
+        if (recorded.exitCode !== 0 || recorded.output.trim() !== String(DELEGATION_FAILURE_EXIT_CODE)) {
+            return { ok: false, message: `lost connection to ${host}`, output: '', phase: 'run', waitedMs };
+        }
+    }
+    return { ok: true, exitCode: session.exitCode, passes, waitedMs };
+}
+export function runSsh(host, script, env, signal) {
+    return runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(script)], { env, signal });
+}
+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 COMMAND_NOT_FOUND_EXIT_CODE = 127;
+const PHASE_OUTPUT_LIMIT_BYTES = 65_536;
+const SNAPSHOT_REF = 'refs/nmr/delegate';
+function describeFailedPhase(failure, host) {
+    if (failure.phase === 'check out') {
+        return `could not check out on ${host}`;
+    }
+    return failure.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}`;
+}
+function describeUnfinishedSession(exitCode, host) {
+    if (exitCode === COMMAND_NOT_FOUND_EXIT_CODE) {
+        return `could not check out on ${host}: node is not on the PATH that the interactive login shell sets there`;
+    }
+    return exitCode === DELEGATION_FAILURE_EXIT_CODE ? `lost connection to ${host}` : `could not check out on ${host}`;
+}
+function forwardChunk(chunk, stream, buffer) {
+    if (stream === undefined) {
+        buffer.append(chunk);
+        return;
+    }
+    stream.write(chunk);
+}
+function runProcess(argv, options) {
+    const { cwd, env, isStreaming = false, signal, 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, signal, 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 toRemoteRelativeDir(relativeDir) {
+    return relativeDir === '' ? '.' : relativeDir.split(path.sep).join('/');
+}

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

@@ -0,0 +1,40 @@
+import { Writable } from 'node:stream';
+import { type DelegationHolder, type HostSessionParams, type SessionRecord } from './remote-host-session.js';
+/**
+ * Reads a host session's stderr: its records until the run starts, then the run's own output, and the session's
+ * report of the passes that the run recorded once it has ended.
+ */
+export interface SessionDemultiplexer {
+    /** Forwards what the stream held back as the possible start of a record, once the session has ended. */
+    flush: () => void;
+    /** Whether the session reported that the run started. */
+    hasStarted: () => boolean;
+    /** Returns what the session printed before the run started, other than its records. */
+    readOutput: () => string;
+    stream: Writable;
+}
+/**
+ * Composes the script that runs the host session from the checkout. `checkoutDir` is a shell expression, so that it
+ * can name the host's home directory.
+ */
+export declare function composeSessionScript(options: {
+    checkoutDir: string;
+    params: HostSessionParams;
+}): string;
+/**
+ * Returns a demultiplexer that passes each of the session's records to `onRecord` until the `run` record, keeps the
+ * other text that arrives before it as the session's output, and forwards everything after it to `stderr` as it
+ * arrives, except a `passes` record, which it passes to `onRecord` too. A `passes` record whose entries are not a list
+ * goes to `onMalformedRecord` instead.
+ *
+ * The run's output is forwarded as bytes, so that a character split across chunks arrives unchanged. Only trailing bytes
+ * that may still begin a record are held back, until they turn out not to or the record's newline arrives.
+ */
+export declare function createSessionDemultiplexer(options: {
+    marker: string;
+    onMalformedRecord?: () => void;
+    onRecord: (record: SessionRecord) => void;
+    stderr: Writable;
+}): SessionDemultiplexer;
+/** Renders the line that a delegation prints when it starts waiting for another delegation's checkout. */
+export declare function formatDelegationWaitingLine(holder: DelegationHolder | undefined, host: string): string;

package/dist/esm/remote-session.js

@@ -0,0 +1,151 @@
+import { Writable } from 'node:stream';
+import { quoteForShell } from "./helpers/quoteForShell.js";
+import { isObject } from "./helpers/type-guards.js";
+import { runHostSession, } from "./remote-host-session.js";
+export function composeSessionScript(options) {
+    const { checkoutDir, params } = options;
+    const source = `(${runHostSession.toString()})(JSON.parse(process.argv[1]));`;
+    return `cd ${checkoutDir} && exec node -e ${quoteForShell(source)} ${quoteForShell(JSON.stringify(params))}`;
+}
+export function createSessionDemultiplexer(options) {
+    const { marker, onMalformedRecord, onRecord, stderr } = options;
+    const prefix = `${marker} `;
+    const prefixBytes = Buffer.from(prefix);
+    let pending = Buffer.alloc(0);
+    let output = '';
+    let hasStarted = false;
+    const stream = new Writable({
+        write(chunk, _encoding, callback) {
+            pending = pending.length === 0 ? chunk : Buffer.concat([pending, chunk]);
+            readSessionLines();
+            if (hasStarted) {
+                forwardRunOutput();
+            }
+            callback();
+        },
+    });
+    return {
+        flush() {
+            if (!hasStarted || pending.length === 0) {
+                return;
+            }
+            stderr.write(pending);
+            pending = Buffer.alloc(0);
+        },
+        hasStarted: () => hasStarted,
+        readOutput: () => (hasStarted ? output : output + pending.toString('utf8')),
+        stream,
+    };
+    function readSessionLines() {
+        let newlineIndex = pending.indexOf(NEWLINE);
+        while (!hasStarted && newlineIndex !== -1) {
+            const line = pending.subarray(0, newlineIndex).toString('utf8');
+            pending = pending.subarray(newlineIndex + 1);
+            const record = line.startsWith(prefix) ? parseRecord(line.slice(prefix.length)) : undefined;
+            if (record === undefined) {
+                output += `${line}\n`;
+            }
+            else {
+                onRecord(record);
+                hasStarted = record.kind === 'run';
+            }
+            newlineIndex = pending.indexOf(NEWLINE);
+        }
+    }
+    function forwardRunOutput() {
+        let segmentStart = 0;
+        let searchFrom = 0;
+        let markerIndex = pending.indexOf(prefixBytes, searchFrom);
+        while (markerIndex !== -1) {
+            const newlineIndex = pending.indexOf(NEWLINE, markerIndex);
+            if (newlineIndex === -1) {
+                writeRange(segmentStart, markerIndex);
+                pending = pending.subarray(markerIndex);
+                return;
+            }
+            const kind = readPassesRecord(pending.subarray(markerIndex + prefixBytes.length, newlineIndex).toString('utf8'));
+            if (kind !== 'other') {
+                writeRange(segmentStart, markerIndex);
+                segmentStart = newlineIndex + 1;
+            }
+            searchFrom = newlineIndex + 1;
+            markerIndex = pending.indexOf(prefixBytes, searchFrom);
+        }
+        const holdFrom = findPartialPrefix(searchFrom);
+        writeRange(segmentStart, holdFrom);
+        pending = pending.subarray(holdFrom);
+    }
+    function findPartialPrefix(from) {
+        for (let index = Math.max(from, pending.length - prefixBytes.length + 1); index < pending.length; index++) {
+            if (prefixBytes.subarray(0, pending.length - index).equals(pending.subarray(index))) {
+                return index;
+            }
+        }
+        return pending.length;
+    }
+    function readPassesRecord(json) {
+        let value;
+        try {
+            value = JSON.parse(json);
+        }
+        catch {
+            return 'other';
+        }
+        if (!isObject(value) || value['kind'] !== 'passes') {
+            return 'other';
+        }
+        const entries = value['entries'];
+        if (!Array.isArray(entries)) {
+            onMalformedRecord?.();
+            return 'malformed';
+        }
+        onRecord({ kind: 'passes', entries });
+        return 'passes';
+    }
+    function writeRange(start, end) {
+        if (end > start) {
+            stderr.write(pending.subarray(start, end));
+        }
+    }
+}
+export function formatDelegationWaitingLine(holder, host) {
+    if (holder === undefined) {
+        return `nmr: waiting for another delegation's checkout on ${host}`;
+    }
+    return `nmr: waiting for ${holder.command} in ${holder.dir} (pid ${holder.pid}) to finish on ${host}`;
+}
+const NEWLINE = 0x0a;
+function isDelegationHolder(value) {
+    return (isObject(value) &&
+        typeof value['command'] === 'string' &&
+        typeof value['dir'] === 'string' &&
+        typeof value['pid'] === 'number');
+}
+function isSessionRecord(value) {
+    if (!isObject(value))
+        return false;
+    switch (value['kind']) {
+        case 'failed':
+            return (typeof value['exitCode'] === 'number' &&
+                typeof value['output'] === 'string' &&
+                (value['phase'] === 'check out' || value['phase'] === 'install'));
+        case 'locked':
+        case 'run':
+            return true;
+        case 'passes':
+            return Array.isArray(value['entries']);
+        case 'waiting':
+            return value['holder'] === undefined || isDelegationHolder(value['holder']);
+        default:
+            return false;
+    }
+}
+function parseRecord(json) {
+    try {
+        const value = JSON.parse(json);
+        return isSessionRecord(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,21 @@
+/** A commit that records the working tree, or why one could not be made. */
+export type SnapshotResult = {
+    ok: true;
+    sha: string;
+    toplevel: string;
+    treeId: string;
+} | {
+    ok: false;
+    isUnsupported: boolean;
+    reason: 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;