@williamthorsen/nmr 0.48.0 → 0.50.0

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

@@ -0,0 +1,63 @@
+import { type HostList } from './remote-run.js';
+/**
+ * The host on which to run, or that `ssh` could not connect to any host, with what it printed for the first one
+ * listed.
+ */
+export type HostChoice = {
+    kind: 'chosen';
+    host: string;
+} | {
+    kind: 'unreachable';
+    host: string;
+    sshMessage: string;
+};
+/**
+ * The host that the probe results settle on, or that every host is unreachable.
+ *
+ * @internal
+ */
+export type HostSelection = {
+    kind: 'chosen';
+    host: string;
+} | {
+    kind: 'unreachable';
+};
+/** What a probe found, with the last line that `ssh` printed when it could not connect. */
+export interface ProbeReport {
+    result: ProbeResult;
+    sshMessage: string;
+}
+/**
+ * What a probe found on a host: whether a delegation started now would wait there, that the host connected but did
+ * not answer, or that `ssh` could not connect to it.
+ */
+export type ProbeResult = 'busy' | 'free' | 'no-answer' | 'unreachable';
+/**
+ * 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<ProbeReport>;
+}): Promise<HostChoice>;
+/**
+ * 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 to which `ssh` cannot connect is unreachable, and one 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<ProbeReport>;
+/**
+ * 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 one that connected.
+ * When `ssh` could not connect to any host, returns that every host is unreachable.
+ *
+ * @internal
+ */
+export declare function selectHost(hosts: HostList, results: ReadonlyMap<string, ProbeResult>): HostSelection | undefined;

package/dist/esm/remote-probe.js

@@ -0,0 +1,88 @@
+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 { DELEGATION_FAILURE_EXIT_CODE, readLastLine, runSsh } from "./remote-run.js";
+export function chooseHost(options) {
+    const { hosts, onSettled, probe } = options;
+    const controller = new AbortController();
+    const results = new Map();
+    const sshMessages = new Map();
+    return new Promise((resolve) => {
+        for (const host of hosts) {
+            void settle(host, resolve);
+        }
+    });
+    async function settle(host, resolve) {
+        let report;
+        try {
+            report = await probe(host, controller.signal);
+        }
+        catch {
+            report = { result: 'no-answer', sshMessage: '' };
+        }
+        if (controller.signal.aborted)
+            return;
+        results.set(host, report.result);
+        sshMessages.set(host, report.sshMessage);
+        onSettled(host, report.result);
+        const selection = selectHost(hosts, results);
+        if (selection === undefined)
+            return;
+        controller.abort();
+        const [first] = hosts;
+        resolve(selection.kind === 'chosen'
+            ? selection
+            : { kind: 'unreachable', host: first, sshMessage: sshMessages.get(first) ?? '' });
+    }
+}
+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 === DELEGATION_FAILURE_EXIT_CODE) {
+        return { result: 'unreachable', sshMessage: readLastLine(output) };
+    }
+    if (exitCode !== 0) {
+        return { result: 'no-answer', sshMessage: '' };
+    }
+    const busy = output
+        .split('\n')
+        .map(readBusyField)
+        .findLast((value) => value !== undefined);
+    if (busy === undefined) {
+        return { result: 'no-answer', sshMessage: '' };
+    }
+    return { result: busy ? 'busy' : 'free', sshMessage: '' };
+}
+export function selectHost(hosts, results) {
+    for (const host of hosts) {
+        const result = results.get(host);
+        if (result === undefined) {
+            return undefined;
+        }
+        if (result === 'free') {
+            return { kind: 'chosen', host };
+        }
+    }
+    const host = hosts.find((candidate) => results.get(candidate) === 'busy') ??
+        hosts.find((candidate) => results.get(candidate) === 'no-answer');
+    return host === undefined ? { kind: 'unreachable' } : { kind: 'chosen', host };
+}
+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

@@ -1,78 +1,61 @@
 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. */
+/** 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 names the host on which to run the command. */
+/** 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` names. */
+/** The flag that runs the command here, whatever `NMR_DELEGATE` or the user config says. */
 export declare const NO_DELEGATE_FLAG = "--no-delegate";
+/** Names the ssh command that the environment supplies, which git and nmr run in place of plain `ssh`. */
+export declare const SSH_COMMAND_ENV_VAR = "GIT_SSH_COMMAND";
 /** 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;
-};
+/** 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, or the phase that kept it from finishing and what that phase printed. */
+/**
+ * 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. A failed `prepare` also reports whether `ssh` could not connect to the host.
+ */
 export type RemoteRunResult = {
     ok: true;
     exitCode: number;
+    passes: unknown[];
+    waitedMs: number;
 } | {
     ok: false;
+    isUnreachable: boolean;
     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;
+    phase: 'prepare';
+    waitedMs: number;
 } | {
     ok: false;
-    isUnsupported: boolean;
-    reason: string;
+    message: string;
+    output: string;
+    phase: Exclude<RemotePhase, 'prepare'>;
+    waitedMs: number;
 };
 /**
- * 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.
+ * Returns the `GIT_SSH_COMMAND` with which `git push` reaches the host: the environment's ssh command, or plain
+ * `ssh`, followed by nmr's own options.
  *
  * @internal
  */
-export declare function composeRunScript(options: {
-    nmrArgs: readonly string[];
-    remoteEnv: Readonly<Record<string, string>>;
-    runDir: string;
-    statusPath: string;
-}): string;
+export declare function composeGitSshCommand(env: NodeJS.ProcessEnv): 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.
+ * Returns the argv that runs `remoteCommand` on `host` with nmr's own options. An ssh command in the environment
+ * runs under `/bin/sh` with the arguments appended, as git runs it, because it may contain shell quoting.
  *
- * 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.
+ * @internal
  */
-export declare function createSnapshot(cwd: string, env: NodeJS.ProcessEnv): SnapshotResult;
+export declare function composeSshArgv(env: NodeJS.ProcessEnv, host: string, remoteCommand: string): string[];
 /**
  * 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.
@@ -81,34 +64,24 @@ export declare function createSnapshot(cwd: string, env: NodeJS.ProcessEnv): Sna
  */
 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.
+ * 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;
-/**
- * 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;
+/** Returns the last line of `output` that is not blank, trimmed, or an empty string when there is none. */
+export declare function readLastLine(output: string): 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. 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.
+ * 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;
@@ -122,6 +95,13 @@ export declare function runRemotely(options: {
     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