@wpelevator/tug 0.10.0 → 0.11.0

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>;

package/dist/cli-prompt.js

@@ -0,0 +1,60 @@
+import readline from 'node:readline';
+import { Writable } from 'node:stream';
+/** True when both ends are a terminal and the run is not CI, so asking a question can be answered. */
+export function canPrompt(env = process.env) {
+    return !!process.stdin.isTTY && !!process.stdout.isTTY && !env.CI;
+}
+/** Ask a line of text on the terminal; with `hidden` the typed characters are not echoed. */
+export const ask = async (question, hidden = false) => {
+    const muted = { on: false };
+    const output = new Writable({
+        write(chunk, _encoding, callback) {
+            if (!muted.on)
+                process.stdout.write(chunk);
+            callback();
+        },
+    });
+    const rl = readline.createInterface({ input: process.stdin, output, terminal: true });
+    try {
+        return await new Promise((resolve, reject) => {
+            rl.once('close', () => reject(new Error('input closed before an answer was given')));
+            rl.question(question, (answer) => {
+                if (hidden)
+                    process.stdout.write('\n');
+                resolve(answer);
+            });
+            muted.on = hidden;
+        });
+    }
+    finally {
+        rl.removeAllListeners('close');
+        rl.close();
+    }
+};
+/** A yes/no question; an empty answer takes `fallback`. */
+export async function confirm(question, fallback = true, prompt = ask) {
+    for (;;) {
+        const answer = (await prompt(`${question} ${fallback ? '(Y/n)' : '(y/N)'} `))
+            .trim()
+            .toLowerCase();
+        if (answer === '')
+            return fallback;
+        if (answer === 'y' || answer === 'yes')
+            return true;
+        if (answer === 'n' || answer === 'no')
+            return false;
+    }
+}
+/** Pick one of `options` by number; an empty answer takes the option at `fallback`. */
+export async function choose(question, options, fallback = 0, prompt = ask) {
+    console.error(question);
+    options.forEach((option, index) => console.error(`  ${index + 1}) ${option}`));
+    for (;;) {
+        const answer = (await prompt(`Choose 1-${options.length} (${fallback + 1}): `)).trim();
+        if (answer === '')
+            return fallback;
+        const index = Number(answer) - 1;
+        if (Number.isInteger(index) && index >= 0 && index < options.length)
+            return index;
+    }
+}

package/dist/cli-secrets.d.ts

@@ -0,0 +1,12 @@
+import type { Prompter } from './cli-prompt.ts';
+/** Variable names a Compose file requires, in order of appearance; ones with a default are optional. */
+export declare function requiredVariables(source: string): string[];
+/**
+ * Variables the Compose file references that nothing supplies: not a control secret, the environment
+ * or `.env`. Compose would render them empty, which for a password is never intended.
+ */
+export declare function findMissingSecrets(file: string, secretNames: readonly string[], env?: NodeJS.ProcessEnv): Promise<string[]>;
+/** A URL-safe random secret with 192 bits of entropy. */
+export declare function generateSecret(): string;
+/** Resolve each missing secret interactively; returns the values to store. */
+export declare function promptForSecrets(names: readonly string[], prompt?: Prompter): Promise<Record<string, string>>;

package/dist/cli-secrets.js

@@ -0,0 +1,71 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { ask } from "./cli-prompt.js";
+/** `$$` is an escaped dollar; `${NAME}` is required only when it has no `:-`, `-`, `:+`, `+`, `:?` or `?` modifier. */
+const REFERENCE = /\$\$|\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+/** Variable names a Compose file requires, in order of appearance; ones with a default are optional. */
+export function requiredVariables(source) {
+    const names = new Set();
+    for (const line of source.split('\n')) {
+        if (/^\s*#/.test(line))
+            continue;
+        for (const match of line.matchAll(REFERENCE)) {
+            const name = match[1] ?? match[2];
+            if (name)
+                names.add(name);
+        }
+    }
+    return [...names];
+}
+/** Variables Compose reads from the `.env` file next to the Compose file. */
+async function dotEnvNames(dir) {
+    try {
+        const text = await fs.readFile(path.join(dir, '.env'), 'utf8');
+        return new Set(text
+            .split('\n')
+            .map((line) => /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1])
+            .filter((name) => !!name));
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * Variables the Compose file references that nothing supplies: not a control secret, the environment
+ * or `.env`. Compose would render them empty, which for a password is never intended.
+ */
+export async function findMissingSecrets(file, secretNames, env = process.env) {
+    const known = new Set(secretNames);
+    const dotEnv = await dotEnvNames(path.dirname(file));
+    // An unreadable file is reported by `docker compose config` with its own message.
+    const source = await fs.readFile(file, 'utf8').catch(() => '');
+    return requiredVariables(source).filter((name) => !known.has(name) && env[name] === undefined && !dotEnv.has(name));
+}
+/** A URL-safe random secret with 192 bits of entropy. */
+export function generateSecret() {
+    return crypto.randomBytes(24).toString('base64url');
+}
+/** Resolve each missing secret interactively; returns the values to store. */
+export async function promptForSecrets(names, prompt = ask) {
+    const values = {};
+    for (const name of names) {
+        for (;;) {
+            const choice = (await prompt(`${name} is missing. [g]enerate a strong password or [e]nter a value? (g) `))
+                .trim()
+                .toLowerCase();
+            if (choice === '' || choice === 'g') {
+                values[name] = generateSecret();
+                break;
+            }
+            if (choice === 'e') {
+                const value = await prompt(`${name}: `, true);
+                if (value) {
+                    values[name] = value;
+                    break;
+                }
+            }
+        }
+    }
+    return values;
+}

package/dist/cli-status.d.ts

@@ -27,3 +27,14 @@ export interface StatusResponse {
 }
 /** Render observations without treating a stale node's last report as current health. */
 export declare function formatStatus(status: StatusResponse): string;
+export interface NodeListing {
+    name: string;
+    status: string;
+    address: string | null;
+    ingress: number | boolean;
+    labels: string[];
+    last_seen_at: string | null;
+    disabled_at?: string | null;
+}
+/** A table of the registered nodes: state, inter-node address, ingress role, labels and last contact. */
+export declare function formatNodes(nodes: NodeListing[]): string;

package/dist/cli-status.js

@@ -36,13 +36,7 @@ export function formatStatus(status) {
                     'serviceStates' in detail &&
                     detail.serviceStates &&
                     typeof detail.serviceStates === 'object') {
-                    for (const [name, state] of Object.entries(detail.serviceStates).sort(([a], [b]) => a.localeCompare(b))) {
-                        if (!state || typeof state !== 'object')
-                            continue;
-                        const item = state;
-                        if (typeof item.rolloutState === 'string')
-                            lines.push(`    ${name}: ${item.rolloutState}${typeof item.rolloutError === 'string' && item.rolloutError ? ` — ${item.rolloutError}` : ''}`);
-                    }
+                    lines.push(...serviceStateLines(detail.serviceStates));
                 }
             }
             catch {
@@ -59,3 +53,39 @@ export function formatStatus(status) {
         lines.push(`  ${node.name}: ${node.status}; last seen ${node.last_seen_at || 'never'}`);
     return lines.join('\n');
 }
+/** A table of the registered nodes: state, inter-node address, ingress role, labels and last contact. */
+export function formatNodes(nodes) {
+    if (!nodes.length)
+        return 'No nodes';
+    const rows = [
+        ['NODE', 'STATUS', 'ADDRESS', 'INGRESS', 'LABELS', 'LAST SEEN'],
+        ...[...nodes]
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((node) => [
+            node.name,
+            node.disabled_at ? 'disabled' : node.status,
+            node.address || '-',
+            node.ingress ? 'yes' : 'no',
+            node.labels.join(',') || '-',
+            node.last_seen_at || 'never',
+        ]),
+    ];
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+    return rows
+        .map((row) => row
+        .map((cell, column) => cell.padEnd(widths[column]))
+        .join('  ')
+        .trimEnd())
+        .join('\n');
+}
+function serviceStateLines(serviceStates) {
+    return Object.entries(serviceStates)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .flatMap(([name, state]) => {
+        const item = (state && typeof state === 'object' ? state : {});
+        if (typeof item.rolloutState !== 'string')
+            return [];
+        const error = typeof item.rolloutError === 'string' && item.rolloutError ? ` — ${item.rolloutError}` : '';
+        return [`    ${name}: ${item.rolloutState}${error}`];
+    });
+}