@wpelevator/tug 0.11.0 → 0.13.0

package/dist/commands/deploy.js

@@ -1,13 +1,15 @@
-import { openAsBlob } from 'node:fs';
+import { selectDeployment, selectService } from "./selection.js";
+import { existsSync, 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 { createProgress, withProgress } from "../cli-progress.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";
+import { loadCfg, collect, formatDeployment, print, printResult, projectOf, request, waitForCommand, waitForDeployment, } from "./context.js";
 async function makeContext() {
     const cfg = await loadCfg();
     const tmp = path.join(os.tmpdir(), `tug-${Date.now()}.tgz`);
@@ -24,112 +26,157 @@ async function makeContext() {
     }
     return tmp;
 }
+/** The first conventional Compose file name in the working directory; `docker-compose.yml` when none exists. */
+export function defaultComposeFile(cwd = process.cwd()) {
+    const names = ['compose.yaml', 'compose.yml', 'docker-compose.yaml', 'docker-compose.yml'];
+    return names.find((name) => existsSync(path.join(cwd, name))) ?? 'docker-compose.yml';
+}
+/** The top-level `name:` of a Compose file, which Compose would use as the project name. */
+export async function composeName(file) {
+    const text = await fs.readFile(file, 'utf8').catch(() => '');
+    return /^name:\s*["']?([A-Za-z0-9][\w.-]*)["']?\s*(?:#.*)?$/m.exec(text)?.[1];
+}
 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('-f, --file <file>', 'compose file', defaultComposeFile())
         .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')
+        .option('--json', 'print the full result, including the desired state, as JSON')
+        .option('--move <service>', 'acknowledge that a service placed on another node starts empty (its data does not move); the services that write to it are held until you restore it or run `tug hold release` (repeatable)', collect, [])
         .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 progress = createProgress();
+        try {
+            progress.stage('Preparing deployment');
+            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);
+            const movePayload = o.move.length ? { moves: o.move } : {};
+            const declared = await composeName(o.file);
+            if (declared && declared !== project)
+                console.error(`warning: ${o.file} is named ${declared} but the Tug project is ${project}; secrets, backups and restores are scoped to the Tug project (set project: ${declared} in tug.yml, or pass --project)`);
+            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();
+                    progress.stage('Preparing local build snapshot');
+                    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, undefined, progress.stage);
+                    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, ...movePayload }));
+                    progress.stage('Uploading images and preparing deployment on control');
+                    response = await request('POST', '/api/v1/deployments', form, true);
+                }
+                finally {
+                    await fs.rm(directory, { recursive: true, force: true });
+                }
             }
-            finally {
-                await fs.rm(directory, { recursive: true, force: true });
+            else if (Object.values(compose.services).some((service) => service.build)) {
+                progress.stage('Archiving source for remote build');
+                const tarball = await makeContext();
+                try {
+                    const form = new FormData();
+                    form.append('payload', JSON.stringify({ project, version, compose, ...movePayload }));
+                    form.append('context', await openAsBlob(tarball), 'context.tgz');
+                    progress.stage('Uploading source and building images on control');
+                    response = await request('POST', '/api/v1/deployments', form, true);
+                }
+                finally {
+                    await fs.rm(tarball, { 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);
+            else {
+                progress.stage('Resolving images and preparing deployment on control');
+                response = await request('POST', '/api/v1/deployments', {
+                    project,
+                    version,
+                    compose,
+                    ...movePayload,
+                });
             }
-            finally {
-                await fs.rm(tarball, { force: true });
+            if (o.wait) {
+                progress.stage(`Deployment ${response.deployment.id}: ${response.deployment.state}`);
+                response.deployment = await waitForDeployment(response.deployment.id, Number(o.timeout), (deployment) => progress.stage(`Deployment ${deployment.id}: ${deployment.state}`));
             }
+            printResult(o.json, response, formatDeployment);
+        }
+        finally {
+            progress.stop();
         }
-        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>')
+        .command('cancel [id]')
         .description('cancel a deployment that has not finished')
-        .action(async (id) => print(await request('POST', `/api/v1/deployments/${encodeURIComponent(id)}/cancel`, {})));
+        .action(async (id) => print(await request('POST', `/api/v1/deployments/${encodeURIComponent(await selectDeployment(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')
+        .option('--json', 'print the full result, including the desired state, as JSON')
         .action(async (o) => {
-        const response = await request('POST', '/api/v1/rollback', {
-            project: await projectOf(o),
-            force: Boolean(o.force),
+        return withProgress('Preparing rollback on control', async (progress) => {
+            const response = await request('POST', '/api/v1/rollback', {
+                project: await projectOf(o),
+                force: Boolean(o.force),
+            });
+            if (o.wait) {
+                progress.stage(`Deployment ${response.deployment.id}: ${response.deployment.state}`);
+                response.deployment = await waitForDeployment(response.deployment.id, Number(o.timeout), (deployment) => progress.stage(`Deployment ${deployment.id}: ${deployment.state}`));
+            }
+            printResult(o.json, response, formatDeployment);
         });
-        if (o.wait)
-            response.deployment = await waitForDeployment(response.deployment.id, Number(o.timeout));
-        print(response);
     });
     program
-        .command('scale <service> <replicas>')
+        .command('scale [service] [replicas]')
+        .option('--replicas <n>', 'replica count when choosing a service interactively')
         .description('scale a service to N replicas across matching nodes')
+        .option('--json', 'print the full result as JSON')
         .action(async (service, replicas, o) => {
+        if (o.replicas && replicas)
+            throw new Error('pass replicas positionally or with --replicas, not both');
+        replicas = replicas || o.replicas || '';
         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) }));
+        service = await selectService(service);
+        const result = await request('POST', '/api/v1/scale', { project, service, replicas: Number(replicas) });
+        printResult(o.json, result, (r) => `${r.service} scaled to ${r.replicas} replica${r.replicas === 1 ? '' : 's'} on ${r.nodes.join(', ')}`);
     });
     program
-        .command('restart <service>')
+        .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);
+        svc = await selectService(svc);
         const created = await request('POST', '/api/v1/restart', { project, service: svc });
         const cmd = await waitForCommand(created.commandId, Number(o.timeout));
         if (cmd.state === 'failed')

package/dist/commands/hold.d.ts

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

package/dist/commands/hold.js

@@ -0,0 +1,21 @@
+import { selectHolds } from "./selection.js";
+import { print, projectOf, request } from "./context.js";
+export function registerHold(program) {
+    const hold = program
+        .command('hold')
+        .description('services a deploy stopped because their data moved to another node');
+    hold
+        .command('release [services...]')
+        .description('start the services that `tug deploy --move` held, without restoring (all of them when none is named); a restore releases its own holds')
+        .option('--select', 'choose one or more move holds instead of releasing all')
+        .action(async (services, o) => {
+        if (o.select && services.length)
+            throw new Error('--select cannot be combined with explicit services');
+        if (o.select)
+            services = await selectHolds();
+        return print(await request('POST', '/api/v1/holds/release', {
+            project: await projectOf(o),
+            services,
+        }));
+    });
+}

package/dist/commands/host.d.ts

@@ -5,8 +5,8 @@ export declare function preflightRemote(target: string, { controlUrl, ports, min
     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>;
+}): Promise<void>;
+export declare function transferTugImage(target: string, imageTag: string, stage: (label: string) => void): 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>;
@@ -16,3 +16,9 @@ export declare function hostHasDocker(target: string, compose?: boolean): boolea
 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[];
+/**
+ * The script that retires a node host: stops the agent and ingress, removes the project containers, networks and
+ * agent state. Project volumes (your data) and the ingress certificates go only with `deleteData`. A host that runs
+ * the control plane is refused, because removing it would destroy the master key and the private CA.
+ */
+export declare function teardownScript(deleteData: boolean): string;

package/dist/commands/host.js

@@ -6,7 +6,7 @@ import { saveImageArchive } from "../artifacts.js";
 import { controlPortCheck, localImageBuildArgs, shellQuote as sh } from "../cli-install.js";
 import { LIST_ADDRESSES_COMMAND, parseAddressCandidates, sortCandidates, } from "../cli-onboarding.js";
 import { runCapture, runLocal, templatesDir } from "./context.js";
-export function preflightRemote(target, { controlUrl, ports = [], minDiskMb = 1024, compose = false, } = {}) {
+export async function preflightRemote(target, { controlUrl, ports = [], minDiskMb = 1024, compose = false, } = {}) {
     const checks = [
         [
             'docker.version',
@@ -50,18 +50,23 @@ export function preflightRemote(target, { controlUrl, ports = [], minDiskMb = 10
     const script = `set -e
 ${checks.map(([name, cmd, fix]) => `echo "preflight: ${name}"; (${cmd}) || { echo "FAILED ${name}: ${fix}" >&2; exit 20; }`).join('\n')}
 `;
-    runLocal('ssh', ['--', target, script]);
+    await runLocal('ssh', ['--', target, script]);
 }
-export async function transferTugImage(target, imageTag) {
+export async function transferTugImage(target, imageTag, stage) {
+    stage(`Checking architecture on ${target}`);
     const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-runtime-'));
     const archive = path.join(directory, 'image.tar.gz');
     const remote = `/tmp/${path.basename(directory)}.tar.gz`;
     try {
-        const uname = runCapture('ssh', ['--', target, 'uname -m']);
-        runLocal('docker', localImageBuildArgs(imageTag, uname));
+        const uname = await runCapture('ssh', ['--', target, 'uname -m']);
+        stage(`Building Tug image ${imageTag}`);
+        await runLocal('docker', localImageBuildArgs(imageTag, uname));
+        stage(`Exporting Tug image ${imageTag}`);
         await saveImageArchive(imageTag, archive);
-        runLocal('scp', ['--', archive, `${target}:${remote}`]);
-        runLocal('ssh', [
+        stage(`Transferring Tug image to ${target}`);
+        await runLocal('scp', ['--', archive, `${target}:${remote}`]);
+        stage(`Loading Tug image on ${target}`);
+        await runLocal('ssh', [
             '--',
             target,
             `set -eu\ntrap ${sh(`rm -f ${sh(remote)}`)} EXIT\ndocker load --input ${sh(remote)}`,
@@ -76,7 +81,7 @@ export async function dockerBootstrap() {
 }
 /** Installs Docker over SSH; `compose` also installs the Compose plugin, which only the control host needs. */
 export async function bootstrapDocker(target, compose = false) {
-    runLocal('ssh', [
+    await runLocal('ssh', [
         '--',
         target,
         `${compose ? 'TUG_INSTALL_COMPOSE=1 ' : ''}sh -eu -c ${sh(await dockerBootstrap())}`,
@@ -97,3 +102,26 @@ export function discoverAddresses(target) {
     const result = spawnSync('ssh', ['--', target, LIST_ADDRESSES_COMMAND], { encoding: 'utf8' });
     return result.status === 0 ? sortCandidates(parseAddressCandidates(String(result.stdout))) : [];
 }
+/**
+ * The script that retires a node host: stops the agent and ingress, removes the project containers, networks and
+ * agent state. Project volumes (your data) and the ingress certificates go only with `deleteData`. A host that runs
+ * the control plane is refused, because removing it would destroy the master key and the private CA.
+ */
+export function teardownScript(deleteData) {
+    return [
+        'set -eu',
+        "if docker ps -a --format '{{.Names}}' | grep -q '^tug-control'; then echo 'this host runs the control plane; retire it by hand (see docs/migration.md)' >&2; exit 3; fi",
+        'docker rm -f tug-agent tug-caddy >/dev/null 2>&1 || true',
+        'ids=$(docker ps -aq --filter label=tug.project --filter label=tug.job; docker ps -aq --filter label=tug.project)',
+        '[ -z "$ids" ] || docker rm -fv $ids >/dev/null',
+        "docker network ls -q --filter 'name=^tug_' | xargs -r docker network rm >/dev/null 2>&1 || true",
+        'rm -rf /etc/tug /var/lib/tug',
+        ...(deleteData
+            ? [
+                'docker volume ls -q --filter label=tug.project | xargs -r docker volume rm >/dev/null',
+                'docker volume rm tug-caddy-data tug-caddy-config tug-caddy-etc tug_restic_cache >/dev/null 2>&1 || true',
+            ]
+            : []),
+        'echo "node host cleaned"',
+    ].join('\n');
+}

package/dist/commands/image.d.ts

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

package/dist/commands/image.js

@@ -0,0 +1,13 @@
+import { print, request } from "./context.js";
+export function registerImage(program) {
+    const image = program.command('image').description('manage the build archives kept on control');
+    image
+        .command('prune')
+        .description('delete build archives that rollback no longer needs: all but the newest N deployments of each project, the current one and any version a node still runs')
+        .option('--keep <n>', 'deployments per project whose archives are kept', '5')
+        .option('--dry-run', 'list what would be deleted without deleting it')
+        .action(async (o) => print(await request('POST', '/api/v1/images/prune', {
+        keep: Number(o.keep),
+        dryRun: Boolean(o.dryRun),
+    })));
+}

package/dist/commands/init.js

@@ -15,7 +15,7 @@ export async function importCredential(cfg, text, connection) {
         path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'tug', 'credentials');
     const source = path.join(dir, `${new URL(credential.url).host.replace(/[^A-Za-z0-9.-]/g, '_')}.json`);
     await writeFileDurable(source, `${JSON.stringify(credential, null, 2)}\n`, 0o600);
-    for (const file of await writeInitConfig(cfg, source, connection))
+    for (const file of await writeInitConfig(cfg, source, connection, credential.url))
         console.log(`wrote ${file}`);
     console.log(`imported credential to ${source}`);
 }

package/dist/commands/node.d.ts

@@ -9,6 +9,7 @@ export interface NodeIdentityOpts extends InstallOpts {
     label: string[];
     agentControlUrl?: string;
     all?: boolean;
+    select?: boolean;
     wait: boolean;
     ingress?: boolean;
     yes?: boolean;