@williamthorsen/nmr 0.48.0 → 0.50.0

package/dist/esm/remote-run.js

@@ -1,124 +1,61 @@
-import { spawn, spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
-import { GIT_OUTPUT_LIMIT, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+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_COMMAND_ENV_VAR = 'GIT_SSH_COMMAND';
 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 composeGitSshCommand(env) {
+    return [resolveSshCommand(env) ?? 'ssh', ...SSH_OPTIONS].join(' ');
 }
-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 composeSshArgv(env, host, remoteCommand) {
+    const sshCommand = resolveSshCommand(env);
+    const sshArgs = [...SSH_OPTIONS, host, remoteCommand];
+    return sshCommand === undefined
+        ? ['ssh', ...sshArgs]
+        : ['/bin/sh', '-c', `${sshCommand} "$@"`, sshCommand, ...sshArgs];
 }
 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}\`?`);
+    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 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 function readLastLine(output) {
+    return (output
+        .split('\n')
+        .map((line) => line.trim())
+        .findLast((line) => line !== '') ?? '');
 }
 export async function runRemotely(options) {
-    const { cwd, env, host, monorepoRoot, nmrArgs, remoteEnv, snapshot, stderr, stdout } = 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' };
+        return {
+            ok: false,
+            isUnreachable: prepare.exitCode === DELEGATION_FAILURE_EXIT_CODE,
+            message: `could not prepare ${host}`,
+            output: prepare.output,
+            phase: 'prepare',
+            waitedMs: 0,
+        };
     }
     const push = await runProcess([
         'git',
@@ -129,37 +66,86 @@ export async function runRemotely(options) {
         `--receive-pack=${RECEIVE_PACK_COMMAND}`,
         `${host}:${checkoutPath}`,
         `${snapshot.sha}:${SNAPSHOT_REF}`,
-    ], { cwd: snapshot.toplevel, env: { ...env, GIT_SSH_COMMAND: ['ssh', ...SSH_OPTIONS].join(' ') } });
+    ], { cwd: snapshot.toplevel, env: { ...env, [SSH_COMMAND_ENV_VAR]: composeGitSshCommand(env) } });
     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 }))], {
+        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(composeSshArgv(env, host, wrapRemoteScript(script)), {
         env,
         isStreaming: true,
-        stderr,
+        stderr: demultiplexer.stream,
         stdout,
     });
-    if (run.exitCode === DELEGATION_FAILURE_EXIT_CODE) {
-        const recorded = await runSsh(host, `cat ${statusPath}`, env);
+    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' };
+            return { ok: false, message: `lost connection to ${host}`, output: '', phase: 'run', waitedMs };
         }
     }
-    return { ok: true, exitCode: run.exitCode };
+    return { ok: true, exitCode: session.exitCode, passes, waitedMs };
+}
+export function runSsh(host, script, env, signal) {
+    return runProcess(composeSshArgv(env, host, wrapRemoteScript(script)), { env, signal });
 }
 export function wrapRemoteScript(script) {
     return `exec /bin/sh -c ${quoteForShell(`${LOGIN_PATH_PREAMBLE}\n${script}`)}`;
@@ -171,33 +157,23 @@ const LOGIN_PATH_PREAMBLE = [
     '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 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);
@@ -205,29 +181,19 @@ function forwardChunk(chunk, stream, buffer) {
     }
     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 resolveSshCommand(env) {
+    const sshCommand = env[SSH_COMMAND_ENV_VAR];
+    return sshCommand === undefined || sshCommand === '' ? undefined : sshCommand;
 }
 function runProcess(argv, options) {
-    const { cwd, env, isStreaming = false, stderr, stdout } = 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, stdio: [isStreaming ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
+        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);
         });
@@ -246,6 +212,6 @@ function runProcess(argv, options) {
         });
     });
 }
-function runSsh(host, script, env) {
-    return runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(script)], { env });
+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;

package/dist/esm/remote-snapshot.js

@@ -0,0 +1,80 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { GIT_OUTPUT_LIMIT } from '@williamthorsen/nmr-core';
+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)) {
+            copyIndex(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 treeId = treeResult.stdout.trim();
+        const commitResult = runGit(['commit-tree', treeId, ...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, treeId };
+    }
+    finally {
+        fs.rmSync(tempDir, { force: true, recursive: true });
+    }
+}
+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',
+};
+function copyIndex(source, destination) {
+    fs.copyFileSync(source, destination);
+    const { atime, mtime } = fs.statSync(source);
+    fs.utimesSync(destination, atime, mtime);
+}
+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 };
+}