@wpelevator/tug 0.10.0 → 0.11.0

package/dist/commands/backup.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerBackup(program: Command): void;

package/dist/commands/backup.js

@@ -0,0 +1,109 @@
+import { backupCheckProblems } from "../backup-check.js";
+import { collect, loadCfg, print, readStdin, request } from "./context.js";
+const formatBytes = (bytes) => bytes === null
+    ? '-'
+    : bytes < 1024 ** 2
+        ? `${Math.ceil(bytes / 1024)} KiB`
+        : `${(bytes / 1024 ** 2).toFixed(1)} MiB`;
+const BACKUP_TERMINAL = ['succeeded', 'failed', 'missed', 'cancelled'];
+export function registerBackup(program) {
+    const backup = program
+        .command('backup')
+        .description('run and inspect workload backups and set where they go');
+    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('--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 (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;
+    });
+    backup
+        .command('list')
+        .description('show each backup target with its last success and next run, then recent runs')
+        .option('--limit <n>', 'number of recent runs to show', '20')
+        .option('--check', 'exit nonzero when a target is stale, or its last run failed or was missed, or there is no destination; for cron and monitors')
+        .action(async (o) => {
+        const project = (await loadCfg()).project || 'site';
+        const listing = await request('GET', `/api/v1/backups?project=${encodeURIComponent(project)}&limit=${encodeURIComponent(o.limit)}`);
+        if (!listing.destinationConfigured)
+            console.error('no backup destination is configured; run tug backup destination set');
+        if (!listing.targets.length)
+            console.log('no backup targets; add x-tug.backup to a database service or volume');
+        for (const t of listing.targets)
+            console.log(`${t.target}\t${t.node ?? '-'}\t${t.schedule}\tlast success ${t.lastSuccessAt ?? 'never'}\tnext ${t.enabled ? t.nextRunAt : 'disabled'}`);
+        for (const r of listing.runs)
+            console.log(`${r.finished_at ?? r.queued_at}\t${r.target}\t${r.trigger}\t${r.state}\t${r.snapshot_id?.slice(0, 8) ?? '-'}\t${formatBytes(r.size_bytes)}${r.error ? `\t${r.error}` : ''}`);
+        if (o.check) {
+            const problems = backupCheckProblems(listing);
+            for (const problem of problems)
+                console.error(`PROBLEM ${problem}`);
+            if (problems.length)
+                process.exitCode = 1;
+        }
+    });
+    backup
+        .command('password')
+        .description("print the project's repository and its password for offline escrow; anyone holding the password and destination credentials can read the project's backups")
+        .action(async () => {
+        const project = (await loadCfg()).project || 'site';
+        print(await request('GET', `/api/v1/backup/repository-password?project=${encodeURIComponent(project)}`));
+    });
+    const destination = backup
+        .command('destination')
+        .description('set, show or remove where backups go');
+    destination
+        .command('set <url>')
+        .description('set where backups go, such as s3:https://s3.example.com/bucket/tug-backups; credentials are stored encrypted on control')
+        .option('--env <name>', 'credential variable for the backend, such as AWS_ACCESS_KEY_ID (repeatable); each value is read from the variable of that name in your environment, else from a line on stdin', collect, [])
+        .action(async (url, o) => {
+        const missing = o.env.filter((name) => process.env[name] === undefined);
+        const lines = missing.length
+            ? (await readStdin()).split(/\r?\n/).filter((line) => line.length > 0)
+            : [];
+        if (lines.length < missing.length)
+            throw new Error(`expected a value on stdin for ${missing.slice(lines.length).join(', ')}`);
+        const env = Object.fromEntries(o.env.map((name) => [name, process.env[name] ?? lines[missing.indexOf(name)]]));
+        console.log(JSON.stringify(await request('POST', '/api/v1/backup/destination', { url, env })));
+    });
+    destination
+        .command('show')
+        .description('show the backup destination and the names of its credential variables, never values')
+        .action(async () => print(await request('GET', '/api/v1/backup/destination')));
+    destination
+        .command('remove')
+        .description('remove the backup destination and its stored credentials; existing backups stay in the repository')
+        .action(async () => console.log(JSON.stringify(await request('DELETE', '/api/v1/backup/destination'))));
+}

package/dist/commands/context.d.ts

@@ -0,0 +1,54 @@
+import type { SpawnSyncOptions } from 'node:child_process';
+import type { ResolvedCliConfig } from '../cli-config.ts';
+import type { LiveInput, LiveRequest } from '../cli-live.ts';
+import type { DeploymentState } from '../protocol.ts';
+export declare const templatesDir: string;
+export interface DeploymentRecord {
+    id: string;
+    state: DeploymentState;
+    error_message?: string | null;
+}
+export interface CommandRecord {
+    state: string;
+    result_json?: string | null;
+}
+export interface DeployResponse {
+    deployment: DeploymentRecord;
+    desiredState?: unknown;
+}
+export interface CommonOpts {
+    project?: string;
+}
+export interface WaitOpts {
+    wait: boolean;
+    timeout: string;
+}
+export interface InstallOpts {
+    buildLocalImage?: boolean;
+    image?: string;
+    installDocker?: boolean;
+}
+export declare const CONFIG_HELP = "CLI config file, YAML or JSON (default: TUG_CONFIG, else tug.yml, tug.yaml, tug.json or .tug.json)";
+type Config = ResolvedCliConfig;
+/** Set by the root `preAction` hook before any command runs. */
+export declare function setResolvedConfig(config: Config): void;
+export declare function loadCfg(): Promise<Config>;
+export declare const collect: (v: string, a: string[]) => string[];
+export declare function readStdin(): Promise<string>;
+/** The pinned mTLS transport for the resolved credential; an address override only changes the connect target. */
+export declare function transportFor(c: Config): Promise<{
+    http: import("../agent-credential.ts").HttpClient;
+    base: string;
+    dispatcher: import("undici").Agent;
+    close: () => Promise<void>;
+}>;
+export declare function request<T = any>(method: string, route: string, body?: unknown, multipart?: boolean): Promise<T>;
+/** 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 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

@@ -0,0 +1,96 @@
+import { spawnSync } from 'node:child_process';
+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";
+// 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');
+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. */
+export function setResolvedConfig(config) {
+    resolvedConfig = config;
+}
+export async function loadCfg() {
+    return resolvedConfig;
+}
+export const collect = (v, a) => [...a, v];
+export async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** The pinned mTLS transport for the resolved credential; an address override only changes the connect target. */
+export async function transportFor(c) {
+    if (!c.credential)
+        throw new Error('no credential: run `tug init <credential-file>`, set TUG_CREDENTIAL_FILE or pass --credential');
+    return createTransport(c.credential, c.controlUrl);
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function request(method, route, body, multipart = false) {
+    const c = await loadCfg();
+    const transport = await transportFor(c);
+    const headers = {};
+    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,
+        });
+        if (!res.ok)
+            throw new Error(`${method} ${route}: ${res.status} ${await res.text()}`);
+        return (await res.json());
+    }
+    finally {
+        void transport.close();
+    }
+}
+/** The project a project-scoped command works on: `--project`, then the resolved config, then `site`. */
+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) {
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    while (Date.now() < deadline) {
+        const deployment = await request('GET', `/api/v1/deployments/${encodeURIComponent(deploymentId)}`);
+        if (TERMINAL_DEPLOYMENT_STATES.includes(deployment.state)) {
+            if (deployment.state !== 'succeeded')
+                throw new Error(`deployment ${deploymentId} ${deployment.state}${deployment.error_message ? `: ${deployment.error_message}` : ''}`);
+            return deployment;
+        }
+        await new Promise((r) => setTimeout(r, 2000));
+    }
+    throw new Error(`timed out waiting for deployment ${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}`);
+}
+export async function runLive(operation, input) {
+    const cfg = await loadCfg();
+    process.exitCode = await runCliLive(parseLiveRequest(operation, { ...input, project: cfg.project || 'site' }), createCliLiveTransport(cfg.credential, cfg.controlUrl));
+}

package/dist/commands/control.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerControl(program: Command): void;

package/dist/commands/control.js

@@ -0,0 +1,110 @@
+import { spawnSync } from 'node:child_process';
+import { canPrompt, confirm } from "../cli-prompt.js";
+import { CONTROL_CONTAINER, defaultControlUrl, shellQuote as sh } from "../cli-install.js";
+import { 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";
+import { bootstrapDocker, hostHasDocker, preflightRemote, transferTugImage } from "./host.js";
+import { importCredential } from "./init.js";
+/** `control setup`, also registered as the top-level shortcut `setup`. */
+function addSetup(parent, description) {
+    parent
+        .command('setup <sshTarget>')
+        .description(description)
+        .option('--extra-san <name>', 'additional DNS name or IP for the server certificate (repeatable)', collect, [])
+        .option('--image <tag>', "Tug image to run (default: ghcr.io/wpelevator/tug:<this CLI's version>)")
+        .option('--install-docker', 'install missing Docker Engine and Compose on supported Debian, Ubuntu, Fedora and RHEL-compatible hosts (root required); in a terminal you are asked when they are missing')
+        .option('--build-local-image', 'build the image from the current checkout and copy it to the host over SSH (tags it tug:local unless --image is set); for development')
+        .option('--port <port>', 'published mTLS port', '8443')
+        .option('--credential-out <file>', 'also write the root credential to this 0600 file (for example to hand it to CI)')
+        .option('--no-import', 'do not import the root credential into the local config (requires --credential-out)')
+        .option('--recover-root', "replace root's key from the control host without the API (lost credential); other admins are unaffected")
+        .option('-y, --yes', 'do not ask for confirmation in a terminal')
+        .action(async (sshTarget, o, command) => {
+        const cfg = await loadCfg();
+        if (!o.import && !o.credentialOut)
+            throw new Error('--no-import needs --credential-out, or the root credential would be lost');
+        // The control URL clients use: --control-url, TUG_CONTROL_URL or the config's controlUrl, else the SSH target's host
+        // and the published port. Clients verify a name generated from the CA, so this is only an address.
+        const controlUrl = cfg.requestedControlUrl ?? defaultControlUrl(sshTarget, o.port);
+        console.error(`control URL: ${controlUrl} (${cfg.requestedControlUrl ? 'from --control-url, TUG_CONTROL_URL or the config file' : 'from the SSH target and --port'}); clients connect there by default`);
+        const interactive = canPrompt();
+        let missingDocker = false;
+        if (!o.installDocker && interactive && !hostHasDocker(sshTarget, true)) {
+            missingDocker = true;
+            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);
+        console.error([
+            'Control plan',
+            `  host:        ${sshTarget}`,
+            `  control URL: ${controlUrl}`,
+            `  mTLS port:   ${o.port}`,
+            `  image:       ${image}`,
+            `  docker:      ${o.installDocker ? 'install Engine and Compose' : missingDocker ? 'not installed (the preflight will fail)' : 'must already be installed'}`,
+            `  credential:  ${[o.import ? 'imported into the local config' : '', o.credentialOut ? `written to ${o.credentialOut}` : ''].filter(Boolean).join(' and ')}`,
+        ].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}`);
+            }
+            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) {
+    const description = 'install the control plane on a Docker-capable host over SSH and import the root credential into the local config; it listens for mTLS only, so front it with TCP passthrough rather than a terminating proxy';
+    const control = program
+        .command('control')
+        .description('install, back up and restore the control plane');
+    addSetup(control, description);
+    addSetup(program, 'shortcut for `tug control setup`');
+    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', {})));
+    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', {
+        artifactRef,
+        confirm: Boolean(o.confirm),
+    })));
+}

package/dist/commands/credential.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerCredential(program: Command): void;

package/dist/commands/credential.js

@@ -0,0 +1,36 @@
+import { Option } from 'commander';
+import { ROLES } from "../credentials.js";
+import { print, request } from "./context.js";
+export function registerCredential(program) {
+    const credential = program
+        .command('credential')
+        .description('create, list and revoke operator credentials');
+    credential
+        .command('create <name>')
+        .description('create a named operator credential for CI or a teammate; it is printed once, control keeps no copy of its private key, and it expires after one year at most')
+        .addOption(new Option('--role <role>', 'read: status and listings; deploy: read plus deploy, rollback, cancel, restart, logs; admin: everything')
+        .choices(ROLES)
+        .makeOptionMandatory())
+        .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('--expires-in-days <n>', 'expire the credential after this many days (default and maximum: 365)')
+        .action(async (name, o) => {
+        const created = await request('POST', '/api/v1/credentials', {
+            name,
+            role: o.role,
+            projects: o.project.length ? o.project : undefined,
+            expiresInSeconds: o.expiresInDays ? Number(o.expiresInDays) * 86400 : undefined,
+        });
+        console.error('Store this credential now (for example as the TUG_CREDENTIAL secret in CI); it is not shown again. Replace one by creating a new name, verifying it, then revoking the old name.');
+        print(created);
+    });
+    credential
+        .command('list')
+        .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>')
+        .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)}`)));
+}

package/dist/commands/deploy.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerDeploy(program: Command): void;

package/dist/commands/deploy.js

@@ -0,0 +1,139 @@
+import { openAsBlob } from 'node:fs';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createLocalBuildSnapshot, createSourceArchive, prepareLocalImages } from "../cli-build.js";
+import { canPrompt } from "../cli-prompt.js";
+import { findMissingSecrets, promptForSecrets } from "../cli-secrets.js";
+import { composeHash } from "../compose.js";
+import { normalizeCompose } from "../normalize.js";
+import { loadCfg, print, projectOf, request, waitForCommand, waitForDeployment, } from "./context.js";
+async function makeContext() {
+    const cfg = await loadCfg();
+    const tmp = path.join(os.tmpdir(), `tug-${Date.now()}.tgz`);
+    try {
+        await createSourceArchive(process.cwd(), tmp, [
+            cfg.file,
+            cfg.localFile,
+            ...(cfg.credentialFile ? [cfg.credentialFile] : []),
+        ]);
+    }
+    catch (error) {
+        await fs.rm(tmp, { force: true });
+        throw error;
+    }
+    return tmp;
+}
+export function registerDeploy(program) {
+    const deploy = program
+        .command('deploy')
+        .description('deploy the Compose project, or cancel a deployment with `deploy cancel <id>`')
+        .option('-f, --file <file>', 'compose file', 'docker-compose.yml')
+        .option('--version <version>', 'display version (default: git-<Compose hash>)')
+        .option('--build-local', 'build application images locally and upload them without source')
+        .option('--no-wait', 'return after desired state is created')
+        .option('--timeout <seconds>', 'wait timeout in seconds', '300')
+        .action(async (o) => {
+        const cfg = await loadCfg();
+        const project = o.project || cfg.project || 'site';
+        // Control secrets are interpolated as sentinels; the agent substitutes the node's released values.
+        const { secrets } = await request('GET', `/api/v1/secrets?project=${encodeURIComponent(project)}`);
+        const secretNames = secrets.map((secret) => secret.name);
+        const missing = await findMissingSecrets(o.file, secretNames);
+        if (missing.length) {
+            if (!canPrompt())
+                throw new Error(`${o.file} needs values that are not set: ${missing.join(', ')}; create each with tug secret set <name> (or run tug deploy in a terminal to be prompted)`);
+            console.error(`Missing secrets for project ${project}: ${missing.join(', ')}`);
+            // Only names that do not exist yet are stored, so an existing secret is never overwritten.
+            for (const [name, value] of Object.entries(await promptForSecrets(missing))) {
+                await request('POST', '/api/v1/secrets', { project, name, value });
+                secretNames.push(name);
+            }
+        }
+        const compose = await normalizeCompose(o.file, secretNames, { project });
+        const version = o.version || `git-${composeHash(compose)}`;
+        let response;
+        if (o.buildLocal) {
+            const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-local-build-'));
+            try {
+                const form = new FormData();
+                const source = Object.values(compose.services).some((service) => service.build)
+                    ? await createLocalBuildSnapshot(process.cwd(), directory, [
+                        cfg.file,
+                        cfg.localFile,
+                        ...(cfg.credentialFile ? [cfg.credentialFile] : []),
+                    ])
+                    : process.cwd();
+                const localImages = await prepareLocalImages(compose, source, directory);
+                for (const { field } of localImages)
+                    form.append(field, await openAsBlob(path.join(directory, `${field}.tar.gz`)), `${field}.tar.gz`);
+                form.append('payload', JSON.stringify({ project, version, compose, localImages }));
+                response = await request('POST', '/api/v1/deployments', form, true);
+            }
+            finally {
+                await fs.rm(directory, { recursive: true, force: true });
+            }
+        }
+        else if (Object.values(compose.services).some((service) => service.build)) {
+            const tarball = await makeContext();
+            try {
+                const form = new FormData();
+                form.append('payload', JSON.stringify({ project, version, compose }));
+                form.append('context', await openAsBlob(tarball), 'context.tgz');
+                response = await request('POST', '/api/v1/deployments', form, true);
+            }
+            finally {
+                await fs.rm(tarball, { force: true });
+            }
+        }
+        else
+            response = await request('POST', '/api/v1/deployments', {
+                project,
+                version,
+                compose,
+            });
+        if (o.wait)
+            response.deployment = await waitForDeployment(response.deployment.id, Number(o.timeout));
+        print(response);
+    });
+    deploy
+        .command('cancel <id>')
+        .description('cancel a deployment that has not finished')
+        .action(async (id) => print(await request('POST', `/api/v1/deployments/${encodeURIComponent(id)}/cancel`, {})));
+    program
+        .command('rollback')
+        .description('activate the previous successful deployment')
+        .option('--force')
+        .option('--no-wait', 'return immediately after activating rollback')
+        .option('--timeout <seconds>', 'wait timeout', '300')
+        .action(async (o) => {
+        const response = await request('POST', '/api/v1/rollback', {
+            project: await projectOf(o),
+            force: Boolean(o.force),
+        });
+        if (o.wait)
+            response.deployment = await waitForDeployment(response.deployment.id, Number(o.timeout));
+        print(response);
+    });
+    program
+        .command('scale <service> <replicas>')
+        .description('scale a service to N replicas across matching nodes')
+        .action(async (service, replicas, o) => {
+        const project = await projectOf(o);
+        if (!/^[1-9]\d*$/.test(replicas))
+            throw new Error('replicas must be a positive integer');
+        print(await request('POST', '/api/v1/scale', { project, service, replicas: Number(replicas) }));
+    });
+    program
+        .command('restart <service>')
+        .description('restart a service on every node that runs it')
+        .option('--timeout <seconds>', 'wait timeout', '60')
+        .action(async (svc, o) => {
+        const project = await projectOf(o);
+        const created = await request('POST', '/api/v1/restart', { project, service: svc });
+        const cmd = await waitForCommand(created.commandId, Number(o.timeout));
+        if (cmd.state === 'failed')
+            throw new Error(JSON.parse(cmd.result_json || '{}').error || 'restart failed');
+        print(cmd);
+    });
+}

package/dist/commands/host.d.ts

@@ -0,0 +1,18 @@
+import type { AddressCandidate } from '../cli-onboarding.ts';
+export declare function preflightRemote(target: string, { controlUrl, ports, minDiskMb, compose, }?: {
+    controlUrl?: string;
+    ports?: number[];
+    minDiskMb?: number;
+    /** Requires the Compose plugin; only the control host runs Compose, nodes need the Docker Engine alone. */
+    compose?: boolean;
+}): void;
+export declare function transferTugImage(target: string, imageTag: string): Promise<void>;
+export declare function dockerBootstrap(): Promise<string>;
+/** Installs Docker over SSH; `compose` also installs the Compose plugin, which only the control host needs. */
+export declare function bootstrapDocker(target: string, compose?: boolean): Promise<void>;
+/** Whether the host already has the Docker Engine (and the Compose plugin when `compose`). */
+export declare function hostHasDocker(target: string, compose?: boolean): boolean;
+/** The host's short hostname, or undefined when it cannot be read. */
+export declare function remoteHostname(target: string): string | undefined;
+/** The host's global IPv4 addresses, private ones first; empty when the host cannot say. */
+export declare function discoverAddresses(target: string): AddressCandidate[];