@wpelevator/tug 0.9.0 → 0.11.0

package/dist/backup-restore.js

@@ -1,5 +1,5 @@
 import { id } from "./util.js";
-import { volumeName } from "./container-spec.js";
+import { scratchVolumeName } from "./container-spec.js";
 const MINUTE = 60_000;
 const LOCK_TTL_MS = 15 * MINUTE;
 const HOLD_TIMEOUT_MS = 5 * MINUTE;
@@ -77,6 +77,8 @@ export function createRestoreService(deps) {
     }
     /** Validates a request and describes what a restore would do; nothing is changed. */
     function plan(request) {
+        // The most recent deployment may have moved the target since the last scheduler tick.
+        backups.sync();
         const desired = deployed(request.project);
         if (!desired)
             return { error: `project ${request.project} has no successful deployment`, status: 409 };
@@ -115,9 +117,7 @@ export function createRestoreService(deps) {
             snapshotId: snapshot.snapshotId,
             snapshotTime: snapshot.time,
             mode,
-            ...(mode === 'scratch'
-                ? { scratchVolume: volumeName(request.project, `restore-${id('r').slice(-6)}`) }
-                : {}),
+            ...(mode === 'scratch' ? { scratchVolume: scratchVolumeName(request.project, id('r')) } : {}),
             writers,
             safetyBackup: mode === 'in-place' && request.safetyBackup !== false,
         };
@@ -197,7 +197,7 @@ export function createRestoreService(deps) {
             release(restore);
             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 +210,72 @@ export function createRestoreService(deps) {
         move(restore, 'restoring', { commandId: queued.commandId });
         db.run('UPDATE restore_runs SET node_id=? WHERE id=?', queued.nodeId, restore.id);
     }
+    function advanceHolding(restore, writers, age) {
+        if (!writersReport(restore, writers, 'held')) {
+            if (age > HOLD_TIMEOUT_MS)
+                fail(restore, 'the writers did not stop in time', 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')`)) {
-            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:
-            }
-        }
+        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);
@@ -397,6 +397,8 @@ export function createBackupService(deps) {
     }
     /** Queues the `backup.restore` job for a target on its node. */
     function queueRestore(project, target, restore, runId) {
+        // Placement can change after planning; never queue a restore using a stale schedule.
+        sync();
         const schedule = db.get('SELECT * FROM backup_schedules WHERE project_id=? AND target=? AND enabled=1', project, target);
         const current = deployed(project)[0];
         if (!schedule || !current)

package/dist/cli-build.d.ts

@@ -11,5 +11,7 @@ export interface LocalBuildDependencies {
 /** Credential exclusions are mandatory and cannot be re-included by source ignore rules. The tracked config names are excluded at the context root only, so an app's own nested `tug.json` is kept. */
 export declare function sourceArchiveFilter(entry: string, configPaths: string[], ignores: string[]): boolean;
 export declare function createSourceArchive(contextDir: string, archive: string, configFiles: string[]): Promise<void>;
+/** Build from the same filtered, validated source snapshot used for remote builds. */
+export declare function createLocalBuildSnapshot(contextDir: string, directory: string, configFiles: string[]): Promise<string>;
 /** Build only application build services; callers own temporary files and upload transport. */
 export declare function prepareLocalImages(compose: ComposeFile, contextDir: string, directory: string, dependencies?: LocalBuildDependencies): Promise<LocalImageUpload[]>;

package/dist/cli-build.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import * as tar from 'tar';
-import { buildImage, run } from "./build.js";
+import { buildImage, run, unpackContext } from "./build.js";
 import { saveImageArchive } from "./artifacts.js";
 import { CONFIG_NAMES } from "./cli-config.js";
 /** At any depth: the git directory and every file that can hold a token (the untracked config overlays). */
@@ -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. */
@@ -122,6 +122,19 @@ export async function createSourceArchive(contextDir, archive, configFiles) {
         filter: (entry) => sourceArchiveFilter(entry, configPaths, ignores),
     }, ['.']);
 }
+/** Build from the same filtered, validated source snapshot used for remote builds. */
+export async function createLocalBuildSnapshot(contextDir, directory, configFiles) {
+    const archive = path.join(directory, 'source.tgz');
+    const snapshot = path.join(directory, 'source');
+    try {
+        await createSourceArchive(contextDir, archive, configFiles);
+        await unpackContext(archive, snapshot);
+        return snapshot;
+    }
+    finally {
+        await fs.rm(archive, { force: true });
+    }
+}
 /** Build only application build services; callers own temporary files and upload transport. */
 export async function prepareLocalImages(compose, contextDir, directory, dependencies = {
     build: buildImage,

package/dist/cli-config.d.ts

@@ -1,5 +1,5 @@
 import type { Credential } from './pki.ts';
-export type SettingType = 'string' | 'boolean' | 'port' | 'list' | 'path';
+export type SettingType = 'string' | 'boolean' | 'list' | 'path';
 export interface Setting {
     type: SettingType;
     /** The flag or positional argument the key stands for; the key is the camelCase of the long flag. */
@@ -28,6 +28,9 @@ export interface ResolvedCliConfig {
     localFile: string;
     /** Where connections go: the credential's public URL unless overridden (an override changes the connect target only). */
     controlUrl: string;
+    /** Shared config address for installation, before connection-only flags, environment and credential defaults. */
+    /** The control URL the operator asked for (flag, environment or config), without credential or default fallbacks. */
+    requestedControlUrl?: string;
     credential?: Credential;
     credentialFile?: string;
     project: string;
@@ -41,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.

package/dist/cli-config.js

@@ -8,73 +8,46 @@ import { errMessage } from "./util.js";
 export const COMMAND_SETTINGS = {
     file: { type: 'path', flag: '--file', commands: ['deploy'] },
     buildLocal: { type: 'boolean', flag: '--build-local', commands: ['deploy'] },
-    wait: { type: 'boolean', flag: '--no-wait', commands: ['deploy', 'rollback'] },
+    wait: {
+        type: 'boolean',
+        flag: '--no-wait',
+        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. */
 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-register'] },
-    publicAddress: {
+    address: {
         type: 'string',
-        flag: '--public-address',
-        commands: ['node-install', 'node-register'],
+        flag: '--address',
+        commands: ['node add', 'node replace', 'node repair', 'node register', 'node enroll'],
     },
     label: {
         type: 'list',
         flag: '--label',
-        commands: ['node-install', 'node-register', 'node-prepare-enrollment'],
-    },
-    mesh: {
-        type: 'boolean',
-        flag: '--mesh',
-        commands: [
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-            'node-prepare-enrollment',
-        ],
-    },
-    wgPort: {
-        type: 'port',
-        flag: '--wg-port',
-        commands: ['node-install', 'node-replace-identity', 'node-repair-identity'],
+        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',
-        ],
+        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',
-        ],
+        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', 'publicAddress'];
+const NODE_SPECIFIC_KEYS = ['ssh', 'address'];
 const SETTINGS = { ...COMMAND_SETTINGS, ...NODE_SETTINGS };
 /** Default file names, in lookup order; more than one present is an error. */
 export const CONFIG_NAMES = ['tug.yml', 'tug.yaml', 'tug.json', '.tug.json'];
@@ -118,16 +91,14 @@ export async function resolveCliConfig(options, env, cwd, creating = false) {
             if (!creating)
                 throw new Error(`cannot use credential ${credentialFile ?? 'from TUG_CREDENTIAL'}: ${errMessage(e)}`, { cause: e });
         }
-    const controlUrl = options.controlUrl ||
-        env.TUG_CONTROL_URL ||
-        config.controlUrl ||
-        credential?.url ||
-        'https://localhost:8443';
+    const requestedControlUrl = options.controlUrl || env.TUG_CONTROL_URL || config.controlUrl;
+    const controlUrl = requestedControlUrl || credential?.url || 'https://localhost:8443';
     return {
         file,
         fileExists: Boolean(base),
         localFile,
         controlUrl: normalizeControlUrl(controlUrl),
+        requestedControlUrl: requestedControlUrl ? normalizeControlUrl(requestedControlUrl) : undefined,
         credential,
         credentialFile,
         project: options.project || env.TUG_PROJECT || config.project || 'site',
@@ -140,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.
@@ -147,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;
@@ -214,8 +195,6 @@ function settingValue(setting, value, where, dir) {
             if (typeof value !== 'boolean')
                 throw new Error(`${where} must be true or false`);
             return value;
-        case 'port':
-            return String(integerOption(String(value), where, 1, 65535));
         case 'list':
             return (Array.isArray(value) ? value : [value]).map((item, index) => text(item, Array.isArray(value) ? `${where}[${index}]` : where));
     }

package/dist/cli-install.d.ts

@@ -1,17 +1,22 @@
 /** The agent dials container IPs for health checks; from the default bridge they are unreachable on current Docker (29.x), so it always shares the host network namespace. */
 export declare const HOST_NETWORK_FLAG = "--network host";
-export declare const MESH_RUN_FLAGS = "--network host --cap-add NET_ADMIN";
 /** Docker platform for the architecture a host reports with `uname -m`. */
 export declare function dockerPlatform(uname: string): string;
 /** Build for the host the image will run on, not the machine that builds it (an arm64 laptop and an amd64 VPS differ). */
 export declare function localImageBuildArgs(imageTag: string, uname: string): string[];
 export declare function shellQuote(value: unknown): string;
-export declare function dockerRunSnippet(image: string, joinKey: string, mesh?: boolean): 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;
-/** An occupied mesh port is reusable only when the installed Tug agent owns the live key. */
-export declare function meshPortCheck(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 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 declare function defaultControlUrl(sshTarget: string, port: number | string): string;

package/dist/cli-install.js

@@ -1,7 +1,6 @@
 import * as yaml from 'js-yaml';
 /** The agent dials container IPs for health checks; from the default bridge they are unreachable on current Docker (29.x), so it always shares the host network namespace. */
 export const HOST_NETWORK_FLAG = '--network host';
-export const MESH_RUN_FLAGS = `${HOST_NETWORK_FLAG} --cap-add NET_ADMIN`;
 /** Docker platform for the architecture a host reports with `uname -m`. */
 export function dockerPlatform(uname) {
     const arch = uname.trim();
@@ -18,8 +17,8 @@ export function localImageBuildArgs(imageTag, uname) {
 export function shellQuote(value) {
     return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
-export function dockerRunSnippet(image, joinKey, mesh = false) {
-    return `docker run -d --name tug-agent --restart unless-stopped ${mesh ? `${MESH_RUN_FLAGS} -e TUG_MESH=true ` : `${HOST_NETWORK_FLAG} `}-v /var/run/docker.sock:/var/run/docker.sock -v tug-agent:/var/lib/tug -e TUG_JOIN_KEY=${shellQuote(joinKey)} ${shellQuote(image)} agent`;
+export function dockerRunSnippet(image, joinKey, address) {
+    return `docker run -d --name tug-agent --restart unless-stopped ${HOST_NETWORK_FLAG} -v /var/run/docker.sock:/var/run/docker.sock -v tug-agent:/var/lib/tug -e TUG_JOIN_KEY=${shellQuote(joinKey)} ${address ? `-e TUG_NODE_ADDRESS=${shellQuote(address)} ` : ''}${shellQuote(image)} agent`;
 }
 /** The bootstrap runs in its own shell so its idempotent early exit cannot skip enrollment. */
 export function enrollmentCloudInit(bootstrap, command) {
@@ -31,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) {
@@ -42,24 +41,28 @@ ss -ltn | awk '{print $4}' | grep -qE '[.:]${port}$' || exit 0
 [ -n "$(docker ps -q --filter 'name=^/${CONTROL_CONTAINER}$' --filter 'publish=${port}' 2>/dev/null)" ]
 `;
 }
-/** An occupied mesh port is reusable only when the installed Tug agent owns the live key. */
-export function meshPortCheck(port) {
-    if (!Number.isInteger(port) || port < 1 || port > 65535)
-        throw new Error('mesh port must be an integer from 1 to 65535');
-    return `command -v ss >/dev/null 2>&1 || exit 1
-listeners=$(ss -lun) || exit 1
-if ! printf '%s\\n' "$listeners" | awk '{print $4}' | grep -qE '[.:]${port}$'; then exit 0; fi
-[ "$(docker inspect --format '{{.HostConfig.NetworkMode}}' tug-agent 2>/dev/null)" = host ] || exit 1
-[ "$(docker inspect --format '{{.State.Running}}' tug-agent 2>/dev/null)" = true ] || exit 1
-docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' tug-agent 2>/dev/null | grep -qx 'TUG_MESH=true' || exit 1
-[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/var/lib/tug"}}{{.Source}}{{end}}{{end}}' tug-agent 2>/dev/null)" = /var/lib/tug ] || exit 1
-docker exec tug-agent sh -eu -c ${shellQuote(`
-test -s /var/lib/tug/wireguard/private.key
-test -s /var/lib/tug/wireguard/reported.pub
-test "$(wg show wg0 listen-port)" = "${port}"
-live_key=$(wg show wg0 public-key)
-test -n "$live_key"
-test "$live_key" = "$(wg pubkey < /var/lib/tug/wireguard/private.key)"
-test "$live_key" = "$(cat /var/lib/tug/wireguard/reported.pub)"`)}
-`;
+/** 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:\/\//, '')
+        .replace(/\/.*$/, '');
+    host = host.replace(/^[^@]*@/, '');
+    const bracketed = /^\[([^\]]+)\]/.exec(host);
+    if (bracketed)
+        host = bracketed[1];
+    else if (host.split(':').length === 2)
+        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');
+}