@wpelevator/tug 0.10.0 → 0.12.0

package/dist/backup-restore.js

@@ -8,8 +8,36 @@ const VERIFY_TIMEOUT_MS = 5 * MINUTE;
 /** Restore states in which the project must stay locked. */
 const LOCKED_STATES = ['locking', 'holding', 'safety_backup', 'restoring', 'interrupted'];
 const TERMINAL = ['succeeded', 'failed', 'released'];
+const HOST_KEY = /host|server|addr|endpoint|url|uri|dsn/i;
 /**
- * The services that write to a target. For a service they are the services that depend on it, transitively;
+ * True when an environment entry points at `service` over the network: a host-like variable that is exactly the
+ * service name (`WORDPRESS_DB_HOST=db`), or a value that names it as a host (`db:3306`, `mysql://u:p@db/app`,
+ * `mysql:host=db;dbname=app`). A service reached across nodes has no `depends_on` to find it by.
+ */
+export function environmentReaches(service, key, value) {
+    const name = service.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (value === service)
+        return HOST_KEY.test(key);
+    return [
+        new RegExp(`^${name}:\\d+$`),
+        new RegExp(`(?:://|@)(?:[^/@\\s]*@)?${name}(?::\\d+)?(?:[/?\\s]|$)`),
+        new RegExp(`(?:host|server)=${name}(?:[;:,\\s]|$)`, 'i'),
+    ].some((pattern) => pattern.test(value));
+}
+function environmentOf(service) {
+    const env = service.environment;
+    if (Array.isArray(env))
+        return env.map(String).map((entry) => {
+            const at = entry.indexOf('=');
+            return at < 0 ? [entry, ''] : [entry.slice(0, at), entry.slice(at + 1)];
+        });
+    return env && typeof env === 'object'
+        ? Object.entries(env).map(([k, v]) => [k, String(v ?? '')])
+        : [];
+}
+/**
+ * The services that write to a target. For a service they are the services that depend on it, transitively,
+ * plus the services whose environment names it as a host, which is how a service on another node reaches it (only for the target itself, not for what depends on the writers);
  * for a volume, the services that mount it and everything depending on those. Stored `depends_on` is used,
  * because the per-node copies drop cross-node dependencies.
  */
@@ -34,7 +62,12 @@ export function discoverWriters(compose, target) {
     while (queue.length) {
         const current = queue.pop();
         for (const service of Object.keys(compose.services))
-            if (!writers.has(service) && service !== name && dependsOn(service).includes(current)) {
+            if (!writers.has(service) &&
+                service !== name &&
+                (dependsOn(service).includes(current) ||
+                    (kind === 'service' &&
+                        current === name &&
+                        environmentOf(compose.services[service]).some(([k, v]) => environmentReaches(name, k, v))))) {
                 writers.add(service);
                 queue.push(service);
             }
@@ -106,7 +139,7 @@ export function createRestoreService(deps) {
                     return { error: `writer ${writer} is not a service of ${request.project}`, status: 400 };
             if (!writers.length && !request.noWriters && !request.writers)
                 return {
-                    error: `no services were found that write to ${request.target}; pass --writers to name them or --no-writers to restore without holding any`,
+                    error: `no services were found that write to ${request.target} (looked at depends_on, volume mounts and host names in environment variables); pass --writers to name them or --no-writers to restore without holding any`,
                     status: 409,
                 };
         }
@@ -136,8 +169,16 @@ export function createRestoreService(deps) {
     function unlock(restore) {
         db.run('DELETE FROM locks WHERE name=? AND owner=?', `project:${restore.project_id}`, `restore:${restore.id}`);
     }
-    function release(restore) {
+    /**
+     * Drops a restore's holds and lock. Holds a deploy placed for a move (no `restore_id`) are dropped with them,
+     * unless `keepMoveHolds`: a restore that failed before changing data must not start the writers against the
+     * empty database it was meant to fill.
+     */
+    function release(restore, keepMoveHolds = false) {
         db.run('DELETE FROM service_holds WHERE restore_id=?', restore.id);
+        if (!keepMoveHolds)
+            for (const service of JSON.parse(restore.writers_json))
+                db.run('DELETE FROM service_holds WHERE project_id=? AND service=? AND restore_id IS NULL', restore.project_id, service);
         unlock(restore);
         deps.wake(restore.project_id);
     }
@@ -166,8 +207,12 @@ export function createRestoreService(deps) {
         else
             move(restore, 'holding');
         if (restore.mode === 'in-place')
-            for (const service of restorePlan.writers)
+            for (const service of restorePlan.writers) {
+                // A hold a deploy placed for a move stays as it is; this restore drops it when it succeeds.
+                if (db.get('SELECT 1 FROM service_holds WHERE project_id=? AND service=? AND restore_id IS NULL', restore.project_id, service))
+                    continue;
                 db.run('INSERT OR REPLACE INTO service_holds(project_id,service,reason,restore_id,created_at) VALUES(?,?,?,?,?)', restore.project_id, service, `restore ${restoreId}`, restoreId, ts);
+            }
         deps.wake(restore.project_id);
         advance();
         return {
@@ -189,15 +234,32 @@ export function createRestoreService(deps) {
             });
         });
     };
+    /** Says which writers never reported `held` and why: the node's own apply error, or that it has not reported. */
+    const holdDiagnosis = (restore, writers) => {
+        const desired = deployed(restore.project_id);
+        const problems = [];
+        for (const service of writers)
+            for (const node of desired?.services[service]?.placement.nodes ?? []) {
+                const row = db.get('SELECT s.* FROM node_statuses s JOIN nodes n ON n.id=s.node_id WHERE n.name=? AND s.project_id=?', node, restore.project_id);
+                const status = row ? JSON.parse(row.status_json) : undefined;
+                const state = status?.serviceStates?.[service]?.rolloutState;
+                if (state === 'held')
+                    continue;
+                problems.push(!status
+                    ? `${service} on ${node}: the node has not reported`
+                    : `${service} on ${node}: ${state ?? 'no state'}${status.error ? `; the node's apply failed with: ${status.error}` : ''}`);
+            }
+        return problems.join('; ');
+    };
     /** Fails a restore. Before anything changed, holds and the lock are dropped; after, they stay until released. */
     function fail(restore, error, dataChanged) {
         if (dataChanged)
             move(restore, 'interrupted', { error });
         else {
-            release(restore);
+            release(restore, true);
             move(restore, 'failed', { error });
         }
-        event('error', 'restore.failed', restore, `restore of ${restore.target} failed: ${error}${dataChanged ? '; the writers stay held until tug restore-release' : ''}`, { error, held: dataChanged });
+        event('error', 'restore.failed', restore, `restore of ${restore.target} failed: ${error}${dataChanged ? '; the writers stay held until tug restore release' : ''}`, { error, held: dataChanged });
     }
     function queueRestoreJob(restore) {
         const queued = backups.queueRestore(restore.project_id, restore.target, {
@@ -210,72 +272,74 @@ export function createRestoreService(deps) {
         move(restore, 'restoring', { commandId: queued.commandId });
         db.run('UPDATE restore_runs SET node_id=? WHERE id=?', queued.nodeId, restore.id);
     }
-    /** Advances every restore that is waiting on something; safe to call often. */
-    function advance() {
-        for (const restore of db.all(`SELECT * FROM restore_runs WHERE state NOT IN ('succeeded','failed','released')`)) {
-            const age = clock().getTime() -
-                new Date(restore.state_changed_at ?? restore.started_at ?? stamp()).getTime();
-            // Keep the project locked while a restore is unfinished, across a control restart.
-            if (restore.mode === 'in-place' && LOCKED_STATES.includes(restore.state))
-                lock(restore);
-            const writers = JSON.parse(restore.writers_json);
-            switch (restore.state) {
-                case 'holding': {
-                    if (!writersReport(restore, writers, 'held')) {
-                        if (age > HOLD_TIMEOUT_MS)
-                            fail(restore, 'the writers did not stop in time', false);
-                        break;
-                    }
-                    if (!restore.safety_backup) {
-                        queueRestoreJob(restore);
-                        break;
-                    }
-                    const safety = backups.runNow(restore.project_id, [restore.target], restore.actor ?? 'restore', 'pre-restore');
-                    if (!safety.runs.length)
-                        return fail(restore, `the safety backup could not start: ${safety.errors.join('; ')}`, false);
-                    move(restore, 'safety_backup', { safetyRunId: safety.runs[0].runId });
-                    break;
-                }
-                case 'safety_backup': {
-                    const run = db.get('SELECT * FROM backup_runs WHERE id=?', restore.safety_run_id);
-                    if (!run || run.state === 'queued' || run.state === 'running')
-                        break;
-                    if (run.state === 'succeeded')
-                        queueRestoreJob(restore);
-                    else
-                        fail(restore, `the safety backup ${run.state}${run.error ? ` (${run.error})` : ''}; nothing was changed`, false);
-                    break;
-                }
-                case 'restoring': {
-                    const command = db.get('SELECT * FROM commands WHERE id=?', restore.command_id);
-                    if (!command || ['pending', 'running'].includes(command.state))
-                        break;
-                    if (command.state === 'succeeded') {
-                        if (restore.mode === 'in-place')
-                            release(restore);
-                        // The data is back; the restore is done when the services that were stopped are serving again.
-                        if (restore.mode === 'in-place' && writers.length)
-                            move(restore, 'verifying');
-                        else
-                            complete(restore);
-                    }
-                    else {
-                        const error = JSON.parse(command.result_json ?? '{}').error ??
-                            `the restore command ${command.state}`;
-                        fail(restore, error, restore.mode === 'in-place');
-                    }
-                    break;
-                }
-                case 'verifying': {
-                    if (writersReport(restore, writers, 'serving'))
-                        complete(restore);
-                    else if (age > VERIFY_TIMEOUT_MS)
-                        complete(restore, `the data was restored, but ${writers.join(', ')} did not report serving within ${VERIFY_TIMEOUT_MS / MINUTE} minutes; check tug status`);
-                    break;
-                }
-                default:
+    function advanceHolding(restore, writers, age) {
+        if (!writersReport(restore, writers, 'held')) {
+            if (age > HOLD_TIMEOUT_MS) {
+                const why = holdDiagnosis(restore, writers);
+                fail(restore, `the writers did not stop in time${why ? ` (${why})` : ''}`, false);
             }
+            return;
+        }
+        if (!restore.safety_backup)
+            return queueRestoreJob(restore);
+        const safety = backups.runNow(restore.project_id, [restore.target], restore.actor ?? 'restore', 'pre-restore');
+        if (!safety.runs.length)
+            return fail(restore, `the safety backup could not start: ${safety.errors.join('; ')}`, false);
+        move(restore, 'safety_backup', { safetyRunId: safety.runs[0].runId });
+    }
+    function advanceSafetyBackup(restore) {
+        const run = db.get('SELECT * FROM backup_runs WHERE id=?', restore.safety_run_id);
+        if (!run || run.state === 'queued' || run.state === 'running')
+            return;
+        if (run.state === 'succeeded')
+            return queueRestoreJob(restore);
+        fail(restore, `the safety backup ${run.state}${run.error ? ` (${run.error})` : ''}; nothing was changed`, false);
+    }
+    function advanceRestoring(restore, writers) {
+        const command = db.get('SELECT * FROM commands WHERE id=?', restore.command_id);
+        if (!command || ['pending', 'running'].includes(command.state))
+            return;
+        if (command.state !== 'succeeded') {
+            const error = JSON.parse(command.result_json ?? '{}').error ??
+                `the restore command ${command.state}`;
+            return fail(restore, error, restore.mode === 'in-place');
         }
+        if (restore.mode === 'in-place')
+            release(restore);
+        // The data is back; the restore is done when the services that were stopped are serving again.
+        if (restore.mode === 'in-place' && writers.length)
+            move(restore, 'verifying');
+        else
+            complete(restore);
+    }
+    function advanceVerifying(restore, writers, age) {
+        if (writersReport(restore, writers, 'serving'))
+            return complete(restore);
+        if (age > VERIFY_TIMEOUT_MS)
+            complete(restore, `the data was restored, but ${writers.join(', ')} did not report serving within ${VERIFY_TIMEOUT_MS / MINUTE} minutes; check tug status`);
+    }
+    function advanceRestore(restore) {
+        const age = clock().getTime() -
+            new Date(restore.state_changed_at ?? restore.started_at ?? stamp()).getTime();
+        // Keep the project locked while a restore is unfinished, across a control restart.
+        if (restore.mode === 'in-place' && LOCKED_STATES.includes(restore.state))
+            lock(restore);
+        const writers = JSON.parse(restore.writers_json);
+        switch (restore.state) {
+            case 'holding':
+                return advanceHolding(restore, writers, age);
+            case 'safety_backup':
+                return advanceSafetyBackup(restore);
+            case 'restoring':
+                return advanceRestoring(restore, writers);
+            case 'verifying':
+                return advanceVerifying(restore, writers, age);
+        }
+    }
+    /** Advances every restore that is waiting on something; safe to call often. */
+    function advance() {
+        for (const restore of db.all(`SELECT * FROM restore_runs WHERE state NOT IN ('succeeded','failed','released')`))
+            advanceRestore(restore);
     }
     function complete(restore, warning) {
         move(restore, 'succeeded', warning ? { error: warning } : {});

package/dist/backup-scheduler.js

@@ -189,7 +189,7 @@ export function createBackupService(deps) {
                 actor,
             });
             if (runId)
-                event('warn', 'backup.no_destination', schedule.project_id, `backup of ${schedule.target} skipped: no backup destination is configured; run tug backup-destination-set`, {
+                event('warn', 'backup.no_destination', schedule.project_id, `backup of ${schedule.target} skipped: no backup destination is configured; run tug backup destination set`, {
                     runId,
                     target: schedule.target,
                 }, null, actor);

package/dist/cli-build.js

@@ -29,7 +29,7 @@ export function sourceArchiveFilter(entry, configPaths, ignores) {
         return false;
     return !compileIgnore(ignores)(relative);
 }
-/** Credential documents written by `control-install --credential-out` (default `tug-root.credential.json`). */
+/** Credential documents, such as the copy `control setup --credential-out` writes (conventionally `*.credential.json`). */
 const CREDENTIAL_FILE = /\.credential\.json$/;
 const ignoreCache = new WeakMap();
 /** Translates one `.dockerignore` pattern: `*`, `?` and `[...]` classes stay within a path segment, `**` crosses them. */

package/dist/cli-config.d.ts

@@ -44,13 +44,18 @@ export declare function localConfigPath(file: string): string;
 export declare function resolveCliConfig(options: ConnectionOptions, env: NodeJS.ProcessEnv, cwd: string, creating?: boolean): Promise<ResolvedCliConfig>;
 /** `nodeDefaults` under the node's own keys; a list in the node replaces the default list. */
 export declare function nodeSettings(config: ResolvedCliConfig, name?: string): SettingValues;
-interface OptionSource {
+interface Named {
     name(): string;
+    parent?: Named | null;
+}
+interface OptionSource extends Named {
     options: readonly {
         attributeName(): string;
     }[];
     getOptionValueSource(key: string): string | undefined;
 }
+/** The space-joined command names from the first subject down, such as `node add`; `setup` is `control setup`. */
+export declare function commandPath(command: Named): string;
 /**
  * Use config values as defaults for the options of a command: a key applies to a command that lists it
  * and has an option of that name, and never over a value given on the command line.
@@ -61,7 +66,7 @@ export declare function applyConfigDefaults(command: OptionSource, values: objec
  * overlay at the credential file, git-ignoring it. An existing tracked file is never rewritten, so its comments survive;
  * connection flags passed to `init` are saved to the overlay instead.
  */
-export declare function writeInitConfig(config: ResolvedCliConfig, credentialFile: string, explicit: ConnectionOptions): Promise<string[]>;
+export declare function writeInitConfig(config: ResolvedCliConfig, credentialFile: string, explicit: ConnectionOptions, credentialUrl?: string): Promise<string[]>;
 export declare function normalizeControlUrl(value: string): string;
 export declare function integerOption(value: string, name: string, minimum?: number, maximum?: number): number;
 export {};

package/dist/cli-config.js

@@ -11,14 +11,7 @@ export const COMMAND_SETTINGS = {
     wait: {
         type: 'boolean',
         flag: '--no-wait',
-        commands: [
-            'deploy',
-            'rollback',
-            'backup-run',
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-        ],
+        commands: ['deploy', 'rollback', 'backup run', 'node add', 'node replace', 'node repair'],
     },
 };
 /** Per-node connection data (`nodes.<name>`); `nodeDefaults` takes the subset that is not node-specific. */
@@ -26,61 +19,32 @@ export const NODE_SETTINGS = {
     ssh: {
         type: 'string',
         flag: '<ssh-target>',
-        commands: ['node-install', 'node-replace-identity', 'node-repair-identity'],
+        commands: ['node add', 'node replace', 'node repair'],
     },
     address: {
         type: 'string',
         flag: '--address',
-        commands: [
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-            'node-register',
-            'node-prepare-enrollment',
-        ],
+        commands: ['node add', 'node replace', 'node repair', 'node register', 'node enroll'],
     },
     label: {
         type: 'list',
         flag: '--label',
-        commands: [
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-            'node-register',
-            'node-prepare-enrollment',
-        ],
+        commands: ['node add', 'node replace', 'node repair', 'node register', 'node enroll'],
     },
     installDocker: {
         type: 'boolean',
         flag: '--install-docker',
-        commands: [
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-            'node-prepare-enrollment',
-            'control-install',
-        ],
+        commands: ['node add', 'node replace', 'node repair', 'node enroll', 'control setup'],
     },
     image: {
         type: 'string',
         flag: '--image',
-        commands: [
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-            'node-prepare-enrollment',
-            'control-install',
-        ],
+        commands: ['node add', 'node replace', 'node repair', 'node enroll', 'control setup'],
     },
     agentControlUrl: {
         type: 'string',
         flag: '--agent-control-url',
-        commands: [
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-            'node-prepare-enrollment',
-        ],
+        commands: ['node add', 'node replace', 'node repair', 'node enroll'],
     },
 };
 const NODE_SPECIFIC_KEYS = ['ssh', 'address'];
@@ -147,6 +111,16 @@ export async function resolveCliConfig(options, env, cwd, creating = false) {
 export function nodeSettings(config, name) {
     return { ...config.nodeDefaults, ...(name ? config.nodes[name] : undefined) };
 }
+/** Top-level shortcuts that run a grouped command, so config keys and validation treat them alike. */
+const SHORTCUTS = { setup: 'control setup' };
+/** The space-joined command names from the first subject down, such as `node add`; `setup` is `control setup`. */
+export function commandPath(command) {
+    const names = [command.name()];
+    for (let parent = command.parent; parent?.parent; parent = parent.parent)
+        names.unshift(parent.name());
+    const path = names.join(' ');
+    return SHORTCUTS[path] ?? path;
+}
 /**
  * Use config values as defaults for the options of a command: a key applies to a command that lists it
  * and has an option of that name, and never over a value given on the command line.
@@ -154,7 +128,7 @@ export function nodeSettings(config, name) {
 export function applyConfigDefaults(command, values, settings) {
     const attributes = new Set(command.options.map((option) => option.attributeName()));
     for (const [key, value] of Object.entries(settings)) {
-        if (SETTINGS[key]?.commands.includes(command.name()) &&
+        if (SETTINGS[key]?.commands.includes(commandPath(command)) &&
             attributes.has(key) &&
             command.getOptionValueSource(key) !== 'cli')
             values[key] = value;
@@ -298,11 +272,16 @@ function serialize(file, data, notice) {
  * overlay at the credential file, git-ignoring it. An existing tracked file is never rewritten, so its comments survive;
  * connection flags passed to `init` are saved to the overlay instead.
  */
-export async function writeInitConfig(config, credentialFile, explicit) {
+export async function writeInitConfig(config, credentialFile, explicit, credentialUrl) {
     const written = [];
     if (!config.fileExists) {
         await fs.mkdir(path.dirname(config.file), { recursive: true });
-        await fs.writeFile(config.file, serialize(config.file, { controlUrl: config.controlUrl, project: config.project }, `Safe to commit: keep credentials out of this file (use TUG_CREDENTIAL_FILE or ${path.basename(config.localFile)}).`));
+        await fs.writeFile(config.file, serialize(config.file, {
+            controlUrl: explicit.controlUrl
+                ? config.controlUrl
+                : (credentialUrl ?? config.controlUrl),
+            project: config.project,
+        }, `Safe to commit: keep credentials out of this file (use TUG_CREDENTIAL_FILE or ${path.basename(config.localFile)}).`));
         written.push(config.file);
     }
     let local = {};

package/dist/cli-install.d.ts

@@ -8,12 +8,14 @@ export declare function shellQuote(value: unknown): string;
 export declare function dockerRunSnippet(image: string, joinKey: string, address?: string): string;
 /** The bootstrap runs in its own shell so its idempotent early exit cannot skip enrollment. */
 export declare function enrollmentCloudInit(bootstrap: string, command: string): string;
-/** Name of the container `control-install` creates (Compose project `tug-control`, service `control`). */
+/** Name of the container `control setup` creates (Compose project `tug-control`, service `control`). */
 export declare const CONTROL_CONTAINER = "tug-control-control-1";
 /** A TCP port is free, or is held by the control container this install would replace, so installing again upgrades in place. */
 export declare function controlPortCheck(port: number): string;
+/** The host of an SSH target: `host`, `user@host`, `ssh://user@host:2222` or bracketed IPv6. */
+export declare function sshHost(sshTarget: string): string;
 /**
- * The default control URL for `control-install`: the SSH target's host and the published port. Accepts
+ * The default control URL for `control setup`: the SSH target's host and the published port. Accepts
  * `host`, `user@host`, `ssh://user@host:2222` and bracketed IPv6. An SSH alias from ~/.ssh/config is used as written,
  * so pass `--control-url` when the alias is not a name or address clients can reach.
  */

package/dist/cli-install.js

@@ -30,7 +30,7 @@ export function enrollmentCloudInit(bootstrap, command) {
             runcmd: [['sh', '-eu', '-c', `sh /opt/tug/install-docker.sh && ${command}`]],
         }, { lineWidth: -1, noRefs: true }));
 }
-/** Name of the container `control-install` creates (Compose project `tug-control`, service `control`). */
+/** Name of the container `control setup` creates (Compose project `tug-control`, service `control`). */
 export const CONTROL_CONTAINER = 'tug-control-control-1';
 /** A TCP port is free, or is held by the control container this install would replace, so installing again upgrades in place. */
 export function controlPortCheck(port) {
@@ -41,12 +41,8 @@ ss -ltn | awk '{print $4}' | grep -qE '[.:]${port}$' || exit 0
 [ -n "$(docker ps -q --filter 'name=^/${CONTROL_CONTAINER}$' --filter 'publish=${port}' 2>/dev/null)" ]
 `;
 }
-/**
- * The default control URL for `control-install`: the SSH target's host and the published port. Accepts
- * `host`, `user@host`, `ssh://user@host:2222` and bracketed IPv6. An SSH alias from ~/.ssh/config is used as written,
- * so pass `--control-url` when the alias is not a name or address clients can reach.
- */
-export function defaultControlUrl(sshTarget, port) {
+/** The host of an SSH target: `host`, `user@host`, `ssh://user@host:2222` or bracketed IPv6. */
+export function sshHost(sshTarget) {
     let host = sshTarget
         .trim()
         .replace(/^ssh:\/\//, '')
@@ -59,5 +55,14 @@ export function defaultControlUrl(sshTarget, port) {
         host = host.split(':')[0];
     if (!host || /[\s'"]/.test(host))
         throw new Error(`cannot derive a host from SSH target ${sshTarget}`);
+    return host;
+}
+/**
+ * The default control URL for `control setup`: the SSH target's host and the published port. Accepts
+ * `host`, `user@host`, `ssh://user@host:2222` and bracketed IPv6. An SSH alias from ~/.ssh/config is used as written,
+ * so pass `--control-url` when the alias is not a name or address clients can reach.
+ */
+export function defaultControlUrl(sshTarget, port) {
+    const host = sshHost(sshTarget);
     return `https://${host.includes(':') ? `[${host}]` : host}:${port}`;
 }

package/dist/cli-live.js

@@ -232,12 +232,10 @@ export async function runCliLive(request, transport, io = {}) {
         finally {
             try {
                 if (session) {
-                    if (controller.signal.aborted || failure) {
-                        try {
-                            await session.send({ type: 'cancel' });
-                        }
-                        catch { }
-                    }
+                    if (controller.signal.aborted || failure)
+                        await Promise.resolve()
+                            .then(() => session.send({ type: 'cancel' }))
+                            .catch(() => { });
                     await session.close();
                 }
             }

package/dist/cli-onboarding.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A node name from an SSH target's host: the first DNS label (`app1` for `root@app1.example.com`). An IP address
+ * says nothing about the machine, so it yields no name and the operator has to choose one.
+ */
+export declare const isValidNodeName: (name: string) => boolean;
+export declare function inferNodeName(sshTarget: string): string | undefined;
+export interface AddressCandidate {
+    interface: string;
+    address: string;
+    /** RFC 1918 or carrier-grade NAT, the range overlay networks such as Tailscale use. */
+    private: boolean;
+}
+/** The remote command that prints one line per global IPv4 address. */
+export declare const LIST_ADDRESSES_COMMAND = "ip -o -4 addr show scope global 2>/dev/null || true";
+export declare function isPrivateIPv4(address: string): boolean;
+/** Parse `ip -o -4 addr show` output (`2: eth0    inet 10.0.0.7/24 brd ... scope global eth0`). */
+export declare function parseAddressCandidates(output: string): AddressCandidate[];
+/** Private addresses first, since a node's address carries cross-node traffic; otherwise the order the host reports. */
+export declare function sortCandidates(candidates: AddressCandidate[]): AddressCandidate[];
+export interface NodePlan {
+    name: string;
+    ssh: string;
+    installDocker?: boolean;
+    /** False when nothing asked the host, so whether Docker is present is unknown. */
+    probed: boolean;
+    address?: string;
+    ingress?: boolean;
+    image: string;
+}
+/** The plan `node add` shows before it changes anything; it never claims what it did not check. */
+export declare function formatNodePlan(plan: NodePlan): string;

package/dist/cli-onboarding.js

@@ -0,0 +1,66 @@
+import { isIP } from 'node:net';
+import { sshHost } from "./cli-install.js";
+const NODE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+/**
+ * A node name from an SSH target's host: the first DNS label (`app1` for `root@app1.example.com`). An IP address
+ * says nothing about the machine, so it yields no name and the operator has to choose one.
+ */
+export const isValidNodeName = (name) => NODE_NAME.test(name);
+export function inferNodeName(sshTarget) {
+    let host;
+    try {
+        host = sshHost(sshTarget);
+    }
+    catch {
+        return undefined;
+    }
+    if (isIP(host) !== 0)
+        return undefined;
+    const label = host.split('.')[0];
+    return NODE_NAME.test(label) ? label : undefined;
+}
+/** The remote command that prints one line per global IPv4 address. */
+export const LIST_ADDRESSES_COMMAND = 'ip -o -4 addr show scope global 2>/dev/null || true';
+export function isPrivateIPv4(address) {
+    const [a, b] = address.split('.').map(Number);
+    return (a === 10 ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 100 && b >= 64 && b <= 127));
+}
+/** Parse `ip -o -4 addr show` output (`2: eth0    inet 10.0.0.7/24 brd ... scope global eth0`). */
+export function parseAddressCandidates(output) {
+    const candidates = [];
+    for (const line of output.split('\n')) {
+        const match = /^\d+:\s+(\S+)\s+inet\s+(\d{1,3}(?:\.\d{1,3}){3})\//.exec(line.trim());
+        if (!match || isIP(match[2]) !== 4)
+            continue;
+        candidates.push({
+            interface: match[1],
+            address: match[2],
+            private: isPrivateIPv4(match[2]),
+        });
+    }
+    return candidates;
+}
+/** Private addresses first, since a node's address carries cross-node traffic; otherwise the order the host reports. */
+export function sortCandidates(candidates) {
+    return [...candidates].sort((a, b) => Number(b.private) - Number(a.private));
+}
+/** The plan `node add` shows before it changes anything; it never claims what it did not check. */
+export function formatNodePlan(plan) {
+    const docker = plan.installDocker
+        ? 'install'
+        : plan.probed
+            ? 'already installed'
+            : 'not checked; must already be installed';
+    return [
+        'Node plan',
+        `  name:     ${plan.name}`,
+        `  ssh:      ${plan.ssh}`,
+        `  docker:   ${docker}`,
+        `  address:  ${plan.address ?? 'not set'}`,
+        `  ingress:  ${plan.ingress ? 'enabled (Caddy on ports 80 and 443)' : 'no'}`,
+        `  image:    ${plan.image}`,
+    ].join('\n');
+}

package/dist/cli-prompt.d.ts

@@ -0,0 +1,9 @@
+/** True when both ends are a terminal and the run is not CI, so asking a question can be answered. */
+export declare function canPrompt(env?: NodeJS.ProcessEnv): boolean;
+export type Prompter = (question: string, hidden?: boolean) => Promise<string>;
+/** Ask a line of text on the terminal; with `hidden` the typed characters are not echoed. */
+export declare const ask: Prompter;
+/** A yes/no question; an empty answer takes `fallback`. */
+export declare function confirm(question: string, fallback?: boolean, prompt?: Prompter): Promise<boolean>;
+/** Pick one of `options` by number; an empty answer takes the option at `fallback`. */
+export declare function choose(question: string, options: readonly string[], fallback?: number, prompt?: Prompter): Promise<number>;