@wpelevator/tug 0.11.0 → 0.13.0

package/dist/cli-process.js

@@ -0,0 +1,46 @@
+import { spawn } from 'node:child_process';
+import { RUN_OUTPUT_LIMIT } from "./build.js";
+/** Keep the event loop free for progress timers during SSH, Docker and file transfers. */
+export function runProcess(cmd, args, { capture = false, input } = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, {
+            stdio: [
+                input === undefined ? 'inherit' : 'pipe',
+                capture ? 'pipe' : 'inherit',
+                capture ? 'pipe' : 'inherit',
+            ],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout = (stdout + String(chunk)).slice(-RUN_OUTPUT_LIMIT);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr = (stderr + String(chunk)).slice(-RUN_OUTPUT_LIMIT);
+        });
+        child.on('error', reject);
+        child.stdin?.on('error', (error) => {
+            if (error.code !== 'EPIPE')
+                reject(error);
+        });
+        if (input !== undefined)
+            child.stdin?.end(input);
+        child.on('close', (status, signal) => {
+            if (signal)
+                reject(new Error(`${cmd} terminated by ${signal}`));
+            else
+                resolve({ status, stdout, stderr });
+        });
+    });
+}
+export async function runLocal(cmd, args) {
+    const result = await runProcess(cmd, args);
+    if (result.status !== 0)
+        throw new Error(`${cmd} failed (exit ${result.status})`);
+}
+export async function runCapture(cmd, args, opts = {}) {
+    const result = await runProcess(cmd, args, { ...opts, capture: true });
+    if (result.status !== 0)
+        throw new Error(`${cmd} failed (exit ${result.status})\n${result.stderr}`);
+    return result.stdout;
+}

package/dist/cli-progress.d.ts

@@ -0,0 +1,11 @@
+/** Line-based stderr progress works in terminals and CI without changing stdout results. */
+export declare function createProgress({ write, now, intervalMs, }?: {
+    write?: ((line: string) => void) | undefined;
+    now?: (() => number) | undefined;
+    intervalMs?: number | undefined;
+}): {
+    stage(next: string): void;
+    stop(): void;
+};
+/** Own the timer for one operation, including failures and early returns. */
+export declare function withProgress<T>(label: string, operation: (progress: ReturnType<typeof createProgress>) => Promise<T>): Promise<T>;

package/dist/cli-progress.js

@@ -0,0 +1,37 @@
+/** Line-based stderr progress works in terminals and CI without changing stdout results. */
+export function createProgress({ write = (line) => {
+    process.stderr.write(`${line}\n`);
+}, now = Date.now, intervalMs = 10_000, } = {}) {
+    let label = '';
+    let started = now();
+    let timer;
+    const report = () => write(`[${Math.floor((now() - started) / 1000)}s] ${label}`);
+    return {
+        stage(next) {
+            if (next === label)
+                return;
+            label = next;
+            started = now();
+            report();
+            if (!timer) {
+                timer = setInterval(report, intervalMs);
+                timer.unref();
+            }
+        },
+        stop() {
+            clearInterval(timer);
+            timer = undefined;
+        },
+    };
+}
+/** Own the timer for one operation, including failures and early returns. */
+export async function withProgress(label, operation) {
+    const progress = createProgress();
+    try {
+        progress.stage(label);
+        return await operation(progress);
+    }
+    finally {
+        progress.stop();
+    }
+}

package/dist/cli-prompt.js

@@ -10,24 +10,25 @@ export const ask = async (question, hidden = false) => {
     const output = new Writable({
         write(chunk, _encoding, callback) {
             if (!muted.on)
-                process.stdout.write(chunk);
+                process.stderr.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')));
+            const onClose = () => reject(new Error('input closed before an answer was given'));
+            rl.once('close', onClose);
             rl.question(question, (answer) => {
+                rl.off('close', onClose);
                 if (hidden)
-                    process.stdout.write('\n');
+                    process.stderr.write('\n');
                 resolve(answer);
             });
             muted.on = hidden;
         });
     }
     finally {
-        rl.removeAllListeners('close');
         rl.close();
     }
 };

package/dist/cli-selection.d.ts

@@ -0,0 +1,13 @@
+import type { Prompter } from './cli-prompt.ts';
+export interface Choice {
+    value: string;
+    label: string;
+}
+export interface SelectionIO {
+    interactive: boolean;
+    prompt: Prompter;
+    write: (message: string) => void;
+}
+/** Resolve lazily so explicit arguments never need a discovery request. */
+export declare function selectOne(value: string | undefined, question: string, load: () => Promise<Choice[]>, io?: SelectionIO): Promise<string>;
+export declare function selectMany(question: string, load: () => Promise<Choice[]>, io?: SelectionIO): Promise<string[]>;

package/dist/cli-selection.js

@@ -0,0 +1,39 @@
+import { ask, canPrompt } from "./cli-prompt.js";
+const terminal = () => ({
+    interactive: canPrompt(),
+    prompt: ask,
+    write: console.error,
+});
+/** Resolve lazily so explicit arguments never need a discovery request. */
+export async function selectOne(value, question, load, io = terminal()) {
+    if (value)
+        return value;
+    const selected = await selectChoices(question, load, false, io);
+    return selected[0];
+}
+export async function selectMany(question, load, io = terminal()) {
+    return selectChoices(question, load, true, io);
+}
+async function selectChoices(question, load, multiple, io) {
+    if (!io.interactive)
+        throw new Error(`${question}: pass an explicit target; selection requires a terminal outside CI`);
+    const options = await load();
+    if (!options.length)
+        throw new Error(`${question}: no eligible options`);
+    io.write(question);
+    options.forEach((option, index) => io.write(`  ${index + 1}) ${option.label}`));
+    for (;;) {
+        const answer = (await io.prompt(multiple
+            ? 'Choose numbers separated by commas (or q to cancel): '
+            : 'Choose a number (or q to cancel): ')).trim();
+        if (/^(q|quit|cancel)$/i.test(answer))
+            throw new Error('cancelled; nothing was changed');
+        const parts = answer.split(',').map((part) => part.trim());
+        if ((!multiple && parts.length !== 1) || parts.some((part) => !/^[1-9]\d*$/.test(part)))
+            continue;
+        const indexes = parts.map((part) => Number(part) - 1);
+        if (indexes.some((index) => index >= options.length))
+            continue;
+        return [...new Set(indexes)].map((index) => options[index].value);
+    }
+}

package/dist/cli.js

@@ -14,6 +14,8 @@ import { registerInit } from "./commands/init.js";
 import { registerNode } from "./commands/node.js";
 import { registerObserve } from "./commands/observe.js";
 import { registerRestore } from "./commands/restore.js";
+import { registerHold } from "./commands/hold.js";
+import { registerImage } from "./commands/image.js";
 import { registerSecret } from "./commands/secret.js";
 import { registerService } from "./commands/service.js";
 import { registerVolume } from "./commands/volume.js";
@@ -33,6 +35,8 @@ registerNode(program);
 registerDeploy(program);
 registerObserve(program);
 registerService(program);
+registerHold(program);
+registerImage(program);
 registerSecret(program);
 registerBackup(program);
 registerRestore(program);

package/dist/commands/backup.js

@@ -1,3 +1,5 @@
+import { selectBackups } from "./selection.js";
+import { withProgress } from "../cli-progress.js";
 import { backupCheckProblems } from "../backup-check.js";
 import { collect, loadCfg, print, readStdin, request } from "./context.js";
 const formatBytes = (bytes) => bytes === null
@@ -13,42 +15,57 @@ export function registerBackup(program) {
     backup
         .command('run [targets...]')
         .description('back up the named services or volumes now, or every backup target of the project; waits and exits nonzero if any backup fails')
+        .option('--select', 'choose one or more backup targets instead of backing up all')
         .option('--no-wait', 'return once the backups are queued')
         .option('--timeout <seconds>', 'give up waiting after this many seconds', '3600')
         .action(async (targets, o) => {
-        const project = (await loadCfg()).project || 'site';
-        const queued = await request('POST', '/api/v1/backups/run', {
-            project,
-            targets: targets.length ? targets : undefined,
-        });
-        for (const message of queued.errors)
-            console.error(message);
-        for (const run of queued.runs)
-            console.log(`queued ${run.target} as ${run.runId}`);
-        let failed = queued.errors.length > 0;
-        if (o.wait) {
-            const deadline = Date.now() + Number(o.timeout) * 1000;
-            const pending = new Set(queued.runs.map((run) => run.runId));
-            while (pending.size && Date.now() < deadline) {
-                await new Promise((resolve) => setTimeout(resolve, 2000));
-                const listing = await request('GET', `/api/v1/backups?project=${encodeURIComponent(project)}&limit=200`);
-                for (const run of listing.runs)
-                    if (pending.has(run.id) && BACKUP_TERMINAL.includes(run.state)) {
-                        pending.delete(run.id);
-                        const ok = run.state === 'succeeded';
-                        failed ||= !ok;
-                        console.log(ok
-                            ? `${run.target}: snapshot ${run.snapshot_id?.slice(0, 8)}, ${formatBytes(run.added_bytes)} added`
-                            : `${run.target}: ${run.state}${run.error ? ` (${run.error})` : ''}`);
+        if (o.select && targets.length)
+            throw new Error('--select cannot be combined with explicit targets');
+        if (o.select)
+            targets = await selectBackups();
+        return withProgress('Queueing backups', async (progress) => {
+            const project = (await loadCfg()).project || 'site';
+            const queued = await request('POST', '/api/v1/backups/run', {
+                project,
+                targets: targets.length ? targets : undefined,
+            });
+            for (const message of queued.errors)
+                console.error(message);
+            for (const run of queued.runs)
+                console.log(`queued ${run.target} as ${run.runId}`);
+            let failed = queued.errors.length > 0;
+            if (o.wait) {
+                const deadline = Date.now() + Number(o.timeout) * 1000;
+                const pending = new Set(queued.runs.map((run) => run.runId));
+                if (pending.size)
+                    progress.stage(`Waiting for backups: ${queued.runs.map((run) => run.target).join(', ')}`);
+                const states = new Map();
+                while (pending.size && Date.now() < deadline) {
+                    await new Promise((resolve) => setTimeout(resolve, 2000));
+                    const listing = await request('GET', `/api/v1/backups?project=${encodeURIComponent(project)}&limit=200`);
+                    for (const run of listing.runs) {
+                        if (pending.has(run.id))
+                            states.set(run.id, `${run.target}: ${run.state}`);
+                        if (pending.has(run.id) && BACKUP_TERMINAL.includes(run.state)) {
+                            pending.delete(run.id);
+                            const ok = run.state === 'succeeded';
+                            failed ||= !ok;
+                            console.log(ok
+                                ? `${run.target}: snapshot ${run.snapshot_id?.slice(0, 8)}, ${formatBytes(run.added_bytes)} added`
+                                : `${run.target}: ${run.state}${run.error ? ` (${run.error})` : ''}`);
+                        }
                     }
+                    if (pending.size)
+                        progress.stage(`Backups: ${[...pending].map((id) => states.get(id) ?? id).join(', ')}`);
+                }
+                if (pending.size) {
+                    console.error(`timed out waiting for ${pending.size} backup(s); they keep running on the node`);
+                    failed = true;
+                }
             }
-            if (pending.size) {
-                console.error(`timed out waiting for ${pending.size} backup(s); they keep running on the node`);
-                failed = true;
-            }
-        }
-        if (failed)
-            process.exitCode = 1;
+            if (failed)
+                process.exitCode = 1;
+        });
     });
     backup
         .command('list')

package/dist/commands/context.d.ts

@@ -1,4 +1,4 @@
-import type { SpawnSyncOptions } from 'node:child_process';
+export { runCapture, runLocal } from '../cli-process.ts';
 import type { ResolvedCliConfig } from '../cli-config.ts';
 import type { LiveInput, LiveRequest } from '../cli-live.ts';
 import type { DeploymentState } from '../protocol.ts';
@@ -16,6 +16,10 @@ export interface DeployResponse {
     deployment: DeploymentRecord;
     desiredState?: unknown;
 }
+/** One line for a person: which project and version reached which state, and how many services it runs. */
+export declare function formatDeployment(response: DeployResponse): string;
+/** Prints the full API result with `--json`, otherwise the human summary. */
+export declare function printResult<T>(json: boolean | undefined, value: T, summary: (value: T) => string): void;
 export interface CommonOpts {
     project?: string;
 }
@@ -46,9 +50,6 @@ export declare function request<T = any>(method: string, route: string, body?: u
 /** The project a project-scoped command works on: `--project`, then the resolved config, then `site`. */
 export declare function projectOf(o: CommonOpts): Promise<string>;
 export declare const print: (value: unknown) => void;
-export declare function runLocal(cmd: string, args: string[], opts?: SpawnSyncOptions): void;
-export declare function runCapture(cmd: string, args: string[], opts?: SpawnSyncOptions): string;
-export declare function waitForDeployment(deploymentId: string, timeoutSeconds?: number): Promise<DeploymentRecord>;
+export declare function waitForDeployment(deploymentId: string, timeoutSeconds?: number, onProgress?: (deployment: DeploymentRecord) => void): Promise<DeploymentRecord>;
 export declare function waitForCommand(commandId: string, timeoutSeconds?: number): Promise<CommandRecord>;
 export declare function runLive(operation: LiveRequest['operation'], input: Omit<LiveInput, 'project'>): Promise<void>;
-export {};

package/dist/commands/context.js

@@ -1,13 +1,32 @@
-import { spawnSync } from 'node:child_process';
+import { canPrompt } from "../cli-prompt.js";
+import { selectOne } from "../cli-selection.js";
+import { withProgress } from "../cli-progress.js";
+export { runCapture, runLocal } from "../cli-process.js";
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createTransport } from "../agent-credential.js";
 import { createCliLiveTransport } from "../cli-live-transport.js";
 import { parseLiveRequest, runCliLive } from "../cli-live.js";
 import { TERMINAL_DEPLOYMENT_STATES } from "../protocol.js";
+import { describeFetchError, errMessage } from "../util.js";
 // Templates live next to the commands' parent: src/templates in dev (`node src/cli.ts`), dist/templates in the
 // built image (`node dist/cli.js`; tools/scripts/copy-templates.js puts them there).
 export const templatesDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'templates');
+/** One line for a person: which project and version reached which state, and how many services it runs. */
+export function formatDeployment(response) {
+    const { deployment } = response;
+    const state = response.desiredState;
+    const services = Object.keys(state?.services ?? {}).length;
+    const label = [state?.project, state?.version].filter(Boolean).join(' ');
+    return `${label ? `${label}: ` : ''}deployment ${deployment.id} ${deployment.state}${services ? `, ${services} service${services === 1 ? '' : 's'}` : ''}${deployment.error_message ? ` (${deployment.error_message})` : ''}`;
+}
+/** Prints the full API result with `--json`, otherwise the human summary. */
+export function printResult(json, value, summary) {
+    if (json)
+        print(value);
+    else
+        console.log(summary(value));
+}
 export const CONFIG_HELP = 'CLI config file, YAML or JSON (default: TUG_CONFIG, else tug.yml, tug.yaml, tug.json or .tug.json)';
 let resolvedConfig;
 /** Set by the root `preAction` hook before any command runs. */
@@ -38,11 +57,17 @@ export async function request(method, route, body, multipart = false) {
     if (!multipart)
         headers['content-type'] = 'application/json';
     try {
-        const res = await transport.http(`${transport.base}${route}`, {
-            method,
-            headers,
-            body: multipart ? body : body ? JSON.stringify(body) : undefined,
-        });
+        let res;
+        try {
+            res = await transport.http(`${transport.base}${route}`, {
+                method,
+                headers,
+                body: multipart ? body : body ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (error) {
+            throw new Error(`${method} ${route}: could not reach control at ${transport.base}: ${describeFetchError(error)}`, { cause: error });
+        }
         if (!res.ok)
             throw new Error(`${method} ${route}: ${res.status} ${await res.text()}`);
         return (await res.json());
@@ -56,21 +81,17 @@ export async function projectOf(o) {
     return o.project || (await loadCfg()).project || 'site';
 }
 export const print = (value) => console.log(JSON.stringify(value, null, 2));
-export function runLocal(cmd, args, opts = {}) {
-    const result = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
-    if (result.status !== 0)
-        throw new Error(`${cmd} failed${result.error ? `: ${result.error.message}` : ` (exit ${result.status ?? result.signal})`}`);
-}
-export function runCapture(cmd, args, opts = {}) {
-    const result = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
-    if (result.status !== 0)
-        throw new Error(`${cmd} ${args.join(' ')} failed\n${result.stderr || ''}`);
-    return String(result.stdout);
-}
-export async function waitForDeployment(deploymentId, timeoutSeconds = 300) {
+export async function waitForDeployment(deploymentId, timeoutSeconds = 300, onProgress) {
     const deadline = Date.now() + timeoutSeconds * 1000;
     while (Date.now() < deadline) {
-        const deployment = await request('GET', `/api/v1/deployments/${encodeURIComponent(deploymentId)}`);
+        let deployment;
+        try {
+            deployment = await request('GET', `/api/v1/deployments/${encodeURIComponent(deploymentId)}`);
+        }
+        catch (error) {
+            throw new Error(`lost contact with control while waiting for deployment ${deploymentId} (${errMessage(error)}); it may still be rolling out: check tug status, or stop it with: tug deploy cancel ${deploymentId}`, { cause: error });
+        }
+        onProgress?.(deployment);
         if (TERMINAL_DEPLOYMENT_STATES.includes(deployment.state)) {
             if (deployment.state !== 'succeeded')
                 throw new Error(`deployment ${deploymentId} ${deployment.state}${deployment.error_message ? `: ${deployment.error_message}` : ''}`);
@@ -78,19 +99,35 @@ export async function waitForDeployment(deploymentId, timeoutSeconds = 300) {
         }
         await new Promise((r) => setTimeout(r, 2000));
     }
-    throw new Error(`timed out waiting for deployment ${deploymentId}`);
+    throw new Error(`timed out waiting for deployment ${deploymentId}; it is still rolling out: check tug status, or stop it with: tug deploy cancel ${deploymentId}`);
 }
 export async function waitForCommand(commandId, timeoutSeconds = 60) {
-    const deadline = Date.now() + timeoutSeconds * 1000;
-    while (Date.now() < deadline) {
-        const cmd = await request('GET', `/api/v1/commands/${commandId}`);
-        if (cmd?.state === 'succeeded' || cmd?.state === 'failed')
-            return cmd;
-        await new Promise((r) => setTimeout(r, 1000));
-    }
-    throw new Error(`timed out waiting for command ${commandId}`);
+    return withProgress(`Waiting for command ${commandId}`, async (progress) => {
+        const deadline = Date.now() + timeoutSeconds * 1000;
+        while (Date.now() < deadline) {
+            const cmd = await request('GET', `/api/v1/commands/${commandId}`);
+            if (cmd)
+                progress.stage(`Command ${commandId}: ${cmd.state}`);
+            if (cmd?.state === 'succeeded' || cmd?.state === 'failed')
+                return cmd;
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+        throw new Error(`timed out waiting for command ${commandId}`);
+    });
 }
 export async function runLive(operation, input) {
     const cfg = await loadCfg();
+    if (!input.node && canPrompt()) {
+        const { services: listing } = await request('GET', `/api/v1/services?project=${encodeURIComponent(cfg.project || 'site')}`);
+        const candidates = new Map(listing
+            .filter((service) => operation === 'ps' || service.name === input.service)
+            .flatMap((service) => service.nodes)
+            .map((node) => [node.name, node]));
+        if (candidates.size > 1)
+            input.node = await selectOne(undefined, 'Select a node for this operation', async () => [...candidates.values()].map((node) => ({
+                value: node.name,
+                label: `${node.name} (${node.status})`,
+            })));
+    }
     process.exitCode = await runCliLive(parseLiveRequest(operation, { ...input, project: cfg.project || 'site' }), createCliLiveTransport(cfg.credential, cfg.controlUrl));
 }

package/dist/commands/control.js

@@ -1,7 +1,8 @@
-import { spawnSync } from 'node:child_process';
+import { withProgress } from "../cli-progress.js";
+import { runProcess } from "../cli-process.js";
 import { canPrompt, confirm } from "../cli-prompt.js";
 import { CONTROL_CONTAINER, defaultControlUrl, shellQuote as sh } from "../cli-install.js";
-import { resolveImage } from "../image.js";
+import { assertImagePublished, resolveImage } from "../image.js";
 import { decodeCredential, writeFileDurable } from "../pki.js";
 import { loadTemplate } from "../util.js";
 import { collect, loadCfg, print, request, runLocal, templatesDir } from "./context.js";
@@ -36,6 +37,7 @@ function addSetup(parent, description) {
             o.installDocker = await confirm(`Docker with the Compose plugin is not installed on ${sshTarget}. Install it now (needs root)?`);
         }
         const image = resolveImage(o.image, o.buildLocalImage);
+        assertImagePublished(image);
         console.error([
             'Control plan',
             `  host:        ${sshTarget}`,
@@ -47,45 +49,56 @@ function addSetup(parent, description) {
         ].join('\n'));
         if (interactive && !o.yes && !(await confirm('Install the control plane?')))
             throw new Error('cancelled; nothing was changed');
-        if (o.installDocker)
-            await bootstrapDocker(sshTarget, true);
-        preflightRemote(sshTarget, { ports: [Number(o.port)], minDiskMb: 2048, compose: true });
-        if (o.buildLocalImage)
-            await transferTugImage(sshTarget, image);
-        const yamlValue = (value) => JSON.stringify(value);
-        const compose = await loadTemplate(templatesDir, 'control-compose.yml', {
-            IMAGE: yamlValue(image),
-            CONTROL_URL: yamlValue(new URL(controlUrl).origin),
-            EXTRA_SANS: yamlValue(o.extraSan.join(',')),
-            PORT: o.port,
-        });
-        const remote = await loadTemplate(templatesDir, 'control-install.sh', {
-            COMPOSE: compose,
-            CONTAINER_SH: sh(CONTROL_CONTAINER),
-        });
-        runLocal('ssh', ['--', sshTarget, remote]);
-        // Upgrades never reissue root: fresh installs create it, `--recover-root` replaces its key. Output goes straight to files.
-        const issue = `docker exec ${sh(CONTROL_CONTAINER)} node dist/main.js control issue-credential --name root --role admin${o.recoverRoot ? ' --replace' : ''}`;
-        const out = spawnSync('ssh', ['--', sshTarget, issue], { encoding: 'utf8' });
-        if (out.status !== 0) {
-            if (!o.recoverRoot && /already used/.test(String(out.stderr)))
-                console.error('control already has a root credential; upgrade complete (pass --recover-root to replace it)');
-            else
-                throw new Error(`issuing the root credential failed: ${String(out.stderr).trim()}`);
-        }
-        else {
-            const text = `${String(out.stdout).trim()}\n`;
-            decodeCredential(text);
-            if (o.credentialOut) {
-                await writeFileDurable(o.credentialOut, text, 0o600);
-                console.error(`root credential written to ${o.credentialOut}`);
+        return withProgress(`Preparing control on ${sshTarget}`, async (progress) => {
+            if (o.installDocker) {
+                progress.stage(`Installing Docker on ${sshTarget}`);
+                await bootstrapDocker(sshTarget, true);
             }
-            if (o.import) {
-                const { controlUrl: connectUrl, project } = command.optsWithGlobals();
-                await importCredential(cfg, text, { controlUrl: connectUrl, project });
+            progress.stage(`Checking control host ${sshTarget}`);
+            await preflightRemote(sshTarget, {
+                ports: [Number(o.port)],
+                minDiskMb: 2048,
+                compose: true,
+            });
+            if (o.buildLocalImage)
+                await transferTugImage(sshTarget, image, progress.stage);
+            const yamlValue = (value) => JSON.stringify(value);
+            const compose = await loadTemplate(templatesDir, 'control-compose.yml', {
+                IMAGE: yamlValue(image),
+                CONTROL_URL: yamlValue(new URL(controlUrl).origin),
+                EXTRA_SANS: yamlValue(o.extraSan.join(',')),
+                PORT: o.port,
+            });
+            const remote = await loadTemplate(templatesDir, 'control-install.sh', {
+                COMPOSE: compose,
+                CONTAINER_SH: sh(CONTROL_CONTAINER),
+            });
+            progress.stage(`Installing control on ${sshTarget}`);
+            await runLocal('ssh', ['--', sshTarget, remote]);
+            // Upgrades never reissue root: fresh installs create it, `--recover-root` replaces its key. Output goes straight to files.
+            const issue = `docker exec ${sh(CONTROL_CONTAINER)} node dist/main.js control issue-credential --name root --role admin${o.recoverRoot ? ' --replace' : ''}`;
+            progress.stage(`Issuing root credential on ${sshTarget}`);
+            const out = await runProcess('ssh', ['--', sshTarget, issue], { capture: true });
+            if (out.status !== 0) {
+                if (!o.recoverRoot && /already used/.test(String(out.stderr)))
+                    console.error('control already has a root credential; upgrade complete (pass --recover-root to replace it)');
+                else
+                    throw new Error(`issuing the root credential failed: ${String(out.stderr).trim()}`);
             }
-        }
-        print({ ok: true, sshTarget, url: controlUrl });
+            else {
+                const text = `${String(out.stdout).trim()}\n`;
+                decodeCredential(text);
+                if (o.credentialOut) {
+                    await writeFileDurable(o.credentialOut, text, 0o600);
+                    console.error(`root credential written to ${o.credentialOut}`);
+                }
+                if (o.import) {
+                    const { controlUrl: connectUrl, project } = command.optsWithGlobals();
+                    await importCredential(cfg, text, { controlUrl: connectUrl, project });
+                }
+            }
+            print({ ok: true, sshTarget, url: controlUrl });
+        });
     });
 }
 export function registerControl(program) {
@@ -98,13 +111,14 @@ export function registerControl(program) {
     control
         .command('backup')
         .description('create a control-plane backup (state, PKI, master key and retained image archives; not workload volumes)')
-        .action(async () => print(await request('POST', '/api/v1/control/backups/run', {})));
+        .option('--no-images', 'leave the retained build archives out (deploy again to rebuild them)')
+        .action(async (o) => withProgress('Creating control-plane backup', async () => print(await request('POST', '/api/v1/control/backups/run', { images: o.images }))));
     control
         .command('restore <artifactRef>')
         .description('restore a control-plane backup on the control-plane host; requires a control restart')
         .option('--confirm')
-        .action(async (artifactRef, o) => print(await request('POST', '/api/v1/control/restore', {
+        .action(async (artifactRef, o) => withProgress('Restoring control-plane backup', async () => print(await request('POST', '/api/v1/control/restore', {
         artifactRef,
         confirm: Boolean(o.confirm),
-    })));
+    }))));
 }

package/dist/commands/credential.js

@@ -1,3 +1,5 @@
+import { selectMany } from "../cli-selection.js";
+import { selectResource } from "./selection.js";
 import { Option } from 'commander';
 import { ROLES } from "../credentials.js";
 import { print, request } from "./context.js";
@@ -14,8 +16,25 @@ export function registerCredential(program) {
         .addOption(new Option('--project <name>', 'limit a read or deploy credential to this project; repeat for several')
         .default([], 'all projects')
         .argParser((value, previous) => [...previous, value]))
+        .option('--select-projects', 'choose existing projects for the credential scope')
         .option('--expires-in-days <n>', 'expire the credential after this many days (default and maximum: 365)')
         .action(async (name, o) => {
+        if (o.selectProjects) {
+            if (o.role === 'admin' || o.project.length)
+                throw new Error('--select-projects requires read/deploy role and no --project');
+            o.project = await selectMany('Select projects (choose all projects alone for unrestricted access)', async () => {
+                const { projects } = await request('GET', '/api/v1/projects');
+                return [
+                    { value: '*', label: 'All projects, including future projects' },
+                    ...projects.map((project) => ({ value: project.name, label: project.name })),
+                ];
+            });
+            if (o.project.includes('*')) {
+                if (o.project.length !== 1)
+                    throw new Error('all projects must be selected alone');
+                o.project = [];
+            }
+        }
         const created = await request('POST', '/api/v1/credentials', {
             name,
             role: o.role,
@@ -30,7 +49,7 @@ export function registerCredential(program) {
         .description('list operator credentials with role, projects, expiry and last use; secrets are never shown')
         .action(async () => print(await request('GET', '/api/v1/credentials')));
     credential
-        .command('revoke <name>')
+        .command('revoke [name]')
         .description('revoke an operator credential immediately; its name stays reserved for the audit trail')
-        .action(async (name) => print(await request('DELETE', `/api/v1/credentials/${encodeURIComponent(name)}`)));
+        .action(async (name) => print(await request('DELETE', `/api/v1/credentials/${encodeURIComponent(await selectResource(name, 'credentials'))}`)));
 }

package/dist/commands/deploy.d.ts

@@ -1,2 +1,6 @@
 import type { Command } from 'commander';
+/** The first conventional Compose file name in the working directory; `docker-compose.yml` when none exists. */
+export declare function defaultComposeFile(cwd?: string): string;
+/** The top-level `name:` of a Compose file, which Compose would use as the project name. */
+export declare function composeName(file: string): Promise<string | undefined>;
 export declare function registerDeploy(program: Command): void;