@wpelevator/tug 0.1.0 → 0.2.1

package/dist/cli.js

@@ -1,35 +1,37 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
+import { openAsBlob } from 'node:fs';
+import { resolveCliConfig, integerOption, normalizeControlUrl } from "./cli-config.js";
+import { dockerRunSnippet, enrollmentCloudInit, shellQuote as sh, MESH_RUN_FLAGS, meshPortCheck } from "./cli-install.js";
+import { createSourceArchive, prepareLocalImages } from "./cli-build.js";
+import { saveImageArchive } from "./artifacts.js";
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import * as tar from 'tar';
 import { readCompose, composeHash } from "./compose.js";
 import { errMessage, token, loadTemplate } from "./util.js";
+import { PROJECT_NAME_PATTERN, ROLES, TOKEN_NAME_PATTERN } from "./tokens.js";
 import { packageVersion, resolveImage } from "./image.js";
 import { TERMINAL_DEPLOYMENT_STATES } from "./protocol.js";
 // Templates live next to this file: 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).
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const templatesDir = path.join(__dirname, 'templates');
-/** `docker run` flags a mesh agent needs: host networking so `wg0` lives in the host's network namespace, and NET_ADMIN to manage it. */
-const MESH_RUN_FLAGS = '--network host --cap-add NET_ADMIN';
 const program = new Command();
-program.name('tug').description('Portable VPS deployments with Docker Compose').version(packageVersion());
-const cfgPath = () => process.env.TUG_CONFIG || path.join(process.cwd(), '.tug.json');
-async function loadCfg() { try {
-    return JSON.parse(await fs.readFile(cfgPath(), 'utf8'));
-}
-catch {
-    return {};
-} }
-async function saveCfg(c) { await fs.writeFile(cfgPath(), JSON.stringify(c, null, 2)); }
+program.name('tug').description('Portable VPS deployments with Docker Compose').version(packageVersion()).enablePositionalOptions()
+    .option('--config <file>', 'CLI JSON config file (default: TUG_CONFIG or .tug.json)')
+    .option('--control-url <url>', 'control API URL (overrides TUG_CONTROL_URL and config)')
+    .option('--project <name>', 'project (overrides TUG_PROJECT and config; default: site)');
+let resolvedConfig;
+const cfgPath = () => resolvedConfig.file;
+async function loadCfg() { return resolvedConfig; }
+async function saveCfg(c) { await fs.writeFile(cfgPath(), JSON.stringify(c, null, 2), { mode: 0o600 }); }
 async function request(method, route, body, multipart = false) {
     const c = await loadCfg();
-    const base = process.env.TUG_CONTROL_URL || c.controlUrl || 'http://localhost:8080';
-    const tok = process.env.TUG_TOKEN || c.operatorToken;
+    const base = c.controlUrl;
+    const tok = c.operatorToken;
     const headers = tok ? { Authorization: `Bearer ${tok}` } : {};
     if (!multipart)
         headers['content-type'] = 'application/json';
@@ -38,11 +40,10 @@ async function request(method, route, body, multipart = false) {
         throw new Error(`${method} ${route}: ${res.status} ${await res.text()}`);
     return res.json();
 }
-function sh(value) { return `'${String(value).replace(/'/g, `'\\''`)}'`; }
 function runLocal(cmd, args, opts = {}) {
     const result = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
     if (result.status !== 0)
-        throw new Error(`${cmd} ${args.join(' ')} failed`);
+        throw new Error(`${cmd} failed${result.error ? `: ${result.error.message}` : ` (exit ${result.status ?? result.signal})`}`);
 }
 function runCapture(cmd, args, opts = {}) {
     const result = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
@@ -66,26 +67,34 @@ function preflightRemote(target, { controlUrl, ports = [], udpPorts = [], minDis
         checks.push([`port.${port}.free`, `! ( command -v ss >/dev/null 2>&1 && ss -ltn | awk '{print $4}' | grep -qE "[.:]${port}$" )`, `Port ${port} is already in use on the target host; stop the conflicting service or choose another port.`]);
     }
     if (mesh) {
-        checks.push(['wireguard.kernel', 'ip link add lpwgtest type wireguard && ip link del lpwgtest || modprobe -n wireguard 2>/dev/null', 'Install WireGuard (kernel 5.6+ has it built in; older kernels need the wireguard-dkms package) and ensure iproute2 is present.']);
+        checks.push(['wireguard.kernel', 'ip link add tugwgtest type wireguard && ip link del tugwgtest || modprobe -n wireguard 2>/dev/null', 'Install WireGuard (kernel 5.6+ has it built in; older kernels need the wireguard-dkms package) and ensure iproute2 is present.']);
     }
     for (const port of udpPorts) {
-        checks.push([`udp.${port}.free`, `! ( command -v ss >/dev/null 2>&1 && ss -lun | awk '{print $4}' | grep -qE "[.:]${port}$" )`, `UDP port ${port} is already in use on the target host; the WireGuard mesh needs it (set TUG_WG_PORT on control and open it between nodes).`]);
+        checks.push([`udp.${port}.free`, meshPortCheck(port), `UDP port ${port} is in use by something other than this node's running Tug mesh agent (or the ss tool is missing). Stop the conflicting service, or choose another port with --wg-port and set TUG_WG_PORT on control.`]);
     }
     if (controlUrl)
         checks.push(['control.reachable', `curl -fsS ${sh(controlUrl)}/healthz >/dev/null`, 'Verify DNS/firewall/TLS for the control URL from the node.']);
     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]);
+    runLocal('ssh', ['--', target, script]);
 }
 async function transferTugImage(target, imageTag) {
-    const archive = path.join(os.tmpdir(), `tug-image-${Date.now()}.tar.gz`);
-    runLocal('docker', ['build', '-t', imageTag, '.']);
-    runLocal('bash', ['-lc', `docker save ${sh(imageTag)} | gzip > ${sh(archive)}`]);
-    runLocal('scp', [archive, `${target}:/tmp/tug-image.tar.gz`]);
-    runLocal('ssh', [target, 'gzip -dc /tmp/tug-image.tar.gz | docker load && rm -f /tmp/tug-image.tar.gz']);
-    await fs.rm(archive, { force: true });
+    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 {
+        runLocal('docker', ['build', '-t', imageTag, '.']);
+        await saveImageArchive(imageTag, archive);
+        runLocal('scp', ['--', archive, `${target}:${remote}`]);
+        runLocal('ssh', ['--', target, `set -eu\ntrap ${sh(`rm -f ${sh(remote)}`)} EXIT\ndocker load --input ${sh(remote)}`]);
+    }
+    finally {
+        await fs.rm(directory, { recursive: true, force: true });
+    }
 }
+async function dockerBootstrap() { return fs.readFile(path.join(templatesDir, 'install-docker.sh'), 'utf8'); }
+async function bootstrapDocker(target) { runLocal('ssh', ['--', target, `sh -eu -c ${sh(await dockerBootstrap())}`]); }
 async function waitForDeployment(deploymentId, timeoutSeconds = 300) {
     const deadline = Date.now() + timeoutSeconds * 1000;
     while (Date.now() < deadline) {
@@ -99,77 +108,83 @@ async function waitForDeployment(deploymentId, timeoutSeconds = 300) {
     }
     throw new Error(`timed out waiting for deployment ${deploymentId}`);
 }
-program.command('init').option('--control-url <url>', 'control API URL', 'http://localhost:8080').option('--token <token>', 'operator token').option('--project <name>', 'project name', 'site').action(async (o) => {
-    const operatorToken = o.token || process.env.TUG_TOKEN || token('tug_op');
-    await saveCfg({ controlUrl: o.controlUrl, operatorToken, project: o.project });
+program.command('init').option('--token <token>', 'operator token (prefer TUG_TOKEN to avoid process-list exposure)').action(async (o) => {
+    const cfg = await loadCfg();
+    const operatorToken = o.token || cfg.operatorToken || token('tug_op');
+    await saveCfg({ controlUrl: cfg.controlUrl, operatorToken, project: cfg.project });
     console.log(`wrote ${cfgPath()}`);
 });
-program.command('node:register').description('register a node with the control plane').requiredOption('--name <name>').option('--address <addr>').option('--public-address <addr>').action(async (o) => {
-    const r = await request('POST', '/api/v1/nodes/register', { name: o.name, address: o.address, publicAddress: o.publicAddress });
+program.command('node-register <name>').description('register a node with the control plane').option('--address <addr>').option('--public-address <addr>').action(async (name, o) => {
+    const r = await request('POST', '/api/v1/nodes/register', { name, address: o.address, publicAddress: o.publicAddress });
     console.log(JSON.stringify(r, null, 2));
 });
-program.command('node:rotate-registry-token <name>').description('issue a new registry pull token for a node, invalidating the old one').action(async (name) => {
+program.command('node-rotate-registry-token <name>').description('issue a new registry pull token for a node, invalidating the old one').action(async (name) => {
     console.log(JSON.stringify(await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/rotate-registry-token`, {}), null, 2));
 });
-program.command('node:rotate-wg-key <name>').description('generate a new WireGuard keypair on the node; peers pick up the new public key on their next poll').option('--timeout <seconds>', 'wait timeout', '60').action(async (name, o) => {
+program.command('node-rotate-wg-key <name>').description('generate a new WireGuard keypair on the node; peers pick up the new public key on their next poll').option('--timeout <seconds>', 'wait timeout', '60').action(async (name, o) => {
     const created = await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/rotate-wg-key`, {});
     const cmd = await waitForCommand(created.commandId, Number(o.timeout));
     if (cmd.state === 'failed')
         throw new Error(JSON.parse(cmd.result_json || '{}').error || 'key rotation failed');
     console.log(JSON.stringify({ ok: true, node: name, ...JSON.parse(cmd.result_json || '{}') }, null, 2));
 });
-program.command('node:ingress <name>').description('mark a node as an ingress node (managed Caddy on ports 80/443), or remove the role with --disable').option('--disable', 'stop acting as an ingress node').action(async (name, o) => {
+program.command('node-ingress <name>').description('mark a node as an ingress node (managed Caddy on ports 80/443), or remove the role with --disable').option('--disable', 'stop acting as an ingress node').action(async (name, o) => {
     console.log(JSON.stringify(await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/ingress`, { enabled: !o.disable }), null, 2));
 });
-program.command('node:revoke-registry-token <name>').description('revoke a node\'s registry pull token, blocking future pulls until rotated').action(async (name) => {
+program.command('node-revoke-registry-token <name>').description('revoke a node\'s registry pull token, blocking future pulls until rotated').action(async (name) => {
     console.log(JSON.stringify(await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/revoke-registry-token`, {}), null, 2));
 });
-program.command('control:token').description('print local dev operator token if available').action(async () => console.log((await fs.readFile('./data/operator.token', 'utf8')).trim()));
-const control = program.command('control');
-control.command('install <sshTarget>')
+program.command('control-token').description('print local dev operator token if available').action(async () => console.log((await fs.readFile('./data/operator.token', 'utf8')).trim()));
+program.command('control-install <sshTarget>')
     .description('install the control plane on a Docker-capable host over SSH; front it with your own reverse proxy/TLS if exposing it publicly')
     .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)')
     .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('--token <token>', 'operator token')
     .option('--port <port>', 'published API port', '8080')
-    .requiredOption('--registry <host>', 'registry host used in desired images; bring your own registry, Tug does not provision one')
+    .option('--registry <host>', 'registry host used in desired images; bring your own registry, Tug does not provision one')
     .option('--registry-auth-path <path>', 'container path to an htpasswd file tug-control should manage credentials in, if your registry uses one')
     .option('--registry-container <name>', 'docker container name to restart when a node\'s registry credentials change, if your registry uses an htpasswd file')
     .action(async (sshTarget, o) => {
     const operatorToken = o.token || process.env.TUG_TOKEN || token('tug_op');
+    if (o.installDocker)
+        await bootstrapDocker(sshTarget);
     preflightRemote(sshTarget, { ports: [Number(o.port)], minDiskMb: 2048 });
     const image = resolveImage(o.image, o.buildLocalImage);
     if (o.buildLocalImage)
         await transferTugImage(sshTarget, image);
-    const registryHost = o.registry;
+    const registryHost = o.registry || '';
+    const yamlValue = (value) => JSON.stringify(value);
     const compose = await loadTemplate(templatesDir, 'control-compose.yml', {
-        IMAGE: image, OPERATOR_TOKEN: operatorToken, REGISTRY_HOST: registryHost, PORT: o.port,
-        REGISTRY_AUTH_PATH: o.registryAuthPath || '',
-        REGISTRY_CONTAINER: o.registryContainer || ''
+        IMAGE: yamlValue(image), OPERATOR_TOKEN: yamlValue(operatorToken), REGISTRY_HOST: yamlValue(registryHost), PORT: o.port,
+        REGISTRY_AUTH_PATH: yamlValue(o.registryAuthPath || ''),
+        REGISTRY_CONTAINER: yamlValue(o.registryContainer || '')
     });
     const remote = await loadTemplate(templatesDir, 'control-install.sh', {
         COMPOSE: compose, OPERATOR_TOKEN_SH: sh(operatorToken)
     });
-    runLocal('ssh', [sshTarget, remote]);
+    runLocal('ssh', ['--', sshTarget, remote]);
     console.log(JSON.stringify({ ok: true, sshTarget, operatorToken, url: `http://${remoteHost(sshTarget)}:${o.port}`, registry: registryHost }, null, 2));
 });
-const node = program.command('node');
-node.command('install <sshTarget>')
+program.command('node-install <sshTarget>')
     .description('register and install an agent container on a Docker-capable host over SSH')
     .requiredOption('--name <name>')
     .option('--address <addr>')
     .option('--public-address <addr>')
-    .option('--control-url <url>', 'URL agents use to reach control')
+    .option('--agent-control-url <url>', 'control URL reachable by the agent (default: resolved operator control URL)')
     .option('--registry <host>', 'registry host for docker login')
     .option('--http-only-dev', 'allow plaintext HTTP control URL for local/private development')
     .option('--mesh', 'join the WireGuard mesh (agent runs with host networking and NET_ADMIN; control needs TUG_MESH=true)')
     .option('--wg-port <port>', 'WireGuard UDP port checked by preflight', '51820')
     .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)')
     .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')
     .action(async (sshTarget, o) => {
     const cfg = await loadCfg();
-    const controlUrl = o.controlUrl || cfg.controlUrl || process.env.TUG_CONTROL_URL || 'http://localhost:8080';
+    const controlUrl = normalizeControlUrl(o.agentControlUrl ?? cfg.controlUrl);
     assertHttps(controlUrl, o.httpOnlyDev);
+    if (o.installDocker)
+        await bootstrapDocker(sshTarget);
     preflightRemote(sshTarget, { controlUrl, mesh: o.mesh, udpPorts: o.mesh ? [Number(o.wgPort)] : [] });
     const registered = await request('POST', '/api/v1/nodes/register', { name: o.name, address: o.address, publicAddress: o.publicAddress });
     const image = resolveImage(o.image, o.buildLocalImage);
@@ -182,72 +197,104 @@ node.command('install <sshTarget>')
     const remote = await loadTemplate(templatesDir, 'node-install.sh', {
         ENV: env, DOCKER_LOGIN: dockerLogin, IMAGE_SH: sh(image), RUN_FLAGS: o.mesh ? `${MESH_RUN_FLAGS} ` : ''
     });
-    runLocal('ssh', [sshTarget, remote]);
+    runLocal('ssh', ['--', sshTarget, remote]);
     console.log(JSON.stringify({ ok: true, node: registered.node, registryToken: registered.registryToken }, null, 2));
 });
-function dockerRunSnippet(image, joinKey, mesh = false) {
-    return `docker run -d --name tug-agent --restart unless-stopped \\
-${mesh ? `  ${MESH_RUN_FLAGS} -e TUG_MESH=true \\\n` : ''}  -v /var/run/docker.sock:/var/run/docker.sock \\
-  -v tug-agent:/var/lib/tug \\
-  -e TUG_JOIN_KEY=${joinKey} \\
-  ${image} agent`;
-}
-node.command('enroll')
+program.command('node-enroll')
     .description('mint a single-use enrollment key so a fresh host can self-join with one docker run (no SSH)')
     .option('--name <name>', 'pre-bind the node name (default: the agent uses its own hostname)')
-    .option('--control-url <url>', 'control URL the agent will connect to')
+    .option('--agent-control-url <url>', 'control URL reachable by the agent (default: resolved operator control URL)')
     .option('--ttl <seconds>', 'enrollment key lifetime', '3600')
     .option('--uses <n>', 'how many hosts may enroll with this key', '1')
     .option('--ca <file>', 'PEM CA cert to embed so agents trust a private/self-signed control')
     .option('--http-only-dev', 'allow a plaintext HTTP control URL for local/private development')
     .option('--image <tag>', 'agent image used in the printed docker run (default: ghcr.io/wpelevator/tug:<this CLI\'s version>)')
     .option('--mesh', 'print a docker run that joins the WireGuard mesh (host networking, NET_ADMIN)')
-    .option('--json', 'print machine-readable JSON instead of the docker run snippet')
+    .option('--install-docker', 'print cloud-init that installs Docker and starts the agent')
+    .option('--json', 'print JSON including the command or cloud-init payload')
     .action(async (o) => {
     const cfg = await loadCfg();
-    const controlUrl = o.controlUrl || cfg.controlUrl || process.env.TUG_CONTROL_URL || 'http://localhost:8080';
+    const controlUrl = normalizeControlUrl(o.agentControlUrl ?? cfg.controlUrl);
     assertHttps(controlUrl, o.httpOnlyDev);
+    const ca = o.ca ? await fs.readFile(o.ca, 'utf8') : undefined;
     const minted = await request('POST', '/api/v1/nodes/enroll-token', { name: o.name || null, ttlSeconds: Number(o.ttl), uses: Number(o.uses) });
     const keyPayload = { v: 1, controlUrl, enrollToken: minted.enrollToken };
-    if (o.ca)
-        keyPayload.ca = await fs.readFile(o.ca, 'utf8');
+    if (ca)
+        keyPayload.ca = ca;
     const joinKey = Buffer.from(JSON.stringify(keyPayload)).toString('base64url');
+    const command = dockerRunSnippet(resolveImage(o.image), joinKey, o.mesh);
+    const cloudInit = o.installDocker ? enrollmentCloudInit(await dockerBootstrap(), command) : undefined;
     if (o.json) {
-        console.log(JSON.stringify({ ...minted, controlUrl, joinKey }, null, 2));
+        console.log(JSON.stringify({ ...minted, controlUrl, joinKey, command, ...(cloudInit ? { cloudInit } : {}) }, null, 2));
+        return;
+    }
+    if (cloudInit) {
+        process.stdout.write(cloudInit);
         return;
     }
     console.log(`# Enrollment key valid until ${minted.expiresAt} (${minted.usesRemaining} use(s)). Run on each fresh host:\n`);
-    console.log(dockerRunSnippet(resolveImage(o.image), joinKey, o.mesh));
+    console.log(command);
 });
-program.command('secret:set <name>').option('--project <name>').option('--value <value>').action(async (name, o) => {
+program.command('secret-set <name>').option('--value <value>').action(async (name, o) => {
     const value = o.value ?? await new Promise(resolve => { process.stdout.write(`${name}: `); process.stdin.once('data', d => resolve(String(d).trim())); });
     console.log(await request('POST', '/api/v1/secrets', { project: o.project || (await loadCfg()).project || 'site', name, value }));
 });
-program.command('secret:list').option('--project <name>').action(async (o) => console.log(JSON.stringify(await request('GET', `/api/v1/secrets?project=${encodeURIComponent(o.project || (await loadCfg()).project || 'site')}`), null, 2)));
-program.command('secret:rm <name>').option('--project <name>').action(async (name, o) => console.log(await request('DELETE', `/api/v1/secrets/${encodeURIComponent(name)}?project=${encodeURIComponent(o.project || (await loadCfg()).project || 'site')}`)));
+program.command('secret-list').action(async (o) => console.log(JSON.stringify(await request('GET', `/api/v1/secrets?project=${encodeURIComponent(o.project || (await loadCfg()).project || 'site')}`), null, 2)));
+program.command('secret-remove <name>').action(async (name, o) => console.log(await request('DELETE', `/api/v1/secrets/${encodeURIComponent(name)}?project=${encodeURIComponent(o.project || (await loadCfg()).project || 'site')}`)));
+program.command('token-create <name>')
+    .description('create a named API token for CI or a teammate; the secret is printed once and cannot be shown again')
+    .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 token to this project; repeat for several').default([], 'all projects').argParser((value, previous) => [...previous, value]))
+    .option('--expires-in-days <n>', 'expire the token after this many days (default: never)')
+    .action(async (name, o) => {
+    const created = await request('POST', '/api/v1/tokens', { name, role: o.role, projects: o.project.length ? o.project : undefined, expiresInSeconds: o.expiresInDays ? Number(o.expiresInDays) * 86400 : undefined });
+    console.error('Store this token now (for example as the TUG_TOKEN secret in CI); it is not shown again.');
+    console.log(JSON.stringify(created, null, 2));
+});
+program.command('token-list').description('list API tokens with role, projects, expiry and last use; secrets are never shown').action(async () => console.log(JSON.stringify(await request('GET', '/api/v1/tokens'), null, 2)));
+program.command('token-revoke <name>').description('revoke an API token immediately; its name stays reserved for the audit trail').action(async (name) => console.log(JSON.stringify(await request('DELETE', `/api/v1/tokens/${encodeURIComponent(name)}`), null, 2)));
 async function makeContext() {
     const tmp = path.join(os.tmpdir(), `tug-${Date.now()}.tgz`);
-    const ignores = new Set(['.git', 'node_modules', 'data', 'registry-data']);
     try {
-        (await fs.readFile('.dockerignore', 'utf8')).split(/\r?\n/).map(l => l.trim()).filter(Boolean).forEach(l => ignores.add(l));
+        await createSourceArchive(process.cwd(), tmp, [cfgPath()]);
+    }
+    catch (error) {
+        await fs.rm(tmp, { force: true });
+        throw error;
     }
-    catch { }
-    await tar.c({ gzip: true, file: tmp, cwd: process.cwd(), filter: (p) => ![...ignores].some(i => p === i || p.startsWith(`${i}/`)) }, ['.']);
     return tmp;
 }
-program.command('deploy').option('-f, --file <file>', 'compose file', 'docker-compose.yml').option('--project <name>').option('--version <version>').option('--no-build-upload', 'do not upload source tarball/build context').option('--no-wait', 'return after desired state is created').option('--timeout <seconds>', 'wait timeout', '300').action(async (o) => {
+program.command('deploy').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-build-upload', 'deploy published images without uploading source; conflicts with --build-local').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 compose = await readCompose(o.file);
     const project = o.project || cfg.project || 'site';
     const version = o.version || `git-${composeHash(compose)}`;
     let response;
-    if (o.buildUpload) {
-        const form = new FormData();
-        form.append('payload', JSON.stringify({ project, version, compose }));
+    if (o.buildLocal) {
+        const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-local-build-'));
+        try {
+            const form = new FormData();
+            const localImages = await prepareLocalImages(compose, process.cwd(), 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 (o.buildUpload && Object.values(compose.services).some(service => service.build)) {
         const tarball = await makeContext();
-        form.append('context', new Blob([await fs.readFile(tarball)]), 'context.tgz');
-        response = await request('POST', '/api/v1/deployments', form, true);
-        await fs.rm(tarball, { force: true });
+        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 });
@@ -256,13 +303,15 @@ program.command('deploy').option('-f, --file <file>', 'compose file', 'docker-co
     console.log(JSON.stringify(response, null, 2));
 });
 program.command('status').action(async () => console.log(JSON.stringify(await request('GET', '/api/v1/status'), null, 2)));
-program.command('events').option('--project <name>').option('--limit <n>', 'number of events', '100').action(async (o) => {
+program.command('events').description('list recent events with the token that caused each control action; defaults to the resolved project').option('--limit <n>', 'number of events', '100').option('--all', 'list events across all projects (limited to your projects for scoped tokens)').action(async (o) => {
+    if (o.all && o.project)
+        throw new Error('--all and --project cannot be combined');
     const cfg = await loadCfg();
-    const project = o.project || cfg.project;
+    const project = o.all ? undefined : o.project || cfg.project;
     const query = `limit=${encodeURIComponent(o.limit)}${project ? `&project=${encodeURIComponent(project)}` : ''}`;
     console.log(JSON.stringify(await request('GET', `/api/v1/events?${query}`), null, 2));
 });
-program.command('doctor').description('run local and control-plane diagnostics').option('--nodes', 'also queue diagnostics on registered agents').option('--node <name>', 'specific node for agent diagnostics').action(async (o) => {
+program.command('doctor').description('run local and control-plane diagnostics').option('--nodes', 'also run diagnostics on every registered agent and wait').option('--node <name>', 'run diagnostics on one agent and wait').option('--timeout <seconds>', 'wait timeout for node diagnostics', '60').action(async (o) => {
     const local = [];
     for (const [name, cmd, args] of [['node', 'node', ['--version']], ['docker', 'docker', ['version', '--format', '{{.Server.Version}}']], ['docker_compose', 'docker', ['compose', 'version']]]) {
         try {
@@ -274,30 +323,38 @@ program.command('doctor').description('run local and control-plane diagnostics')
     }
     const controlDiagnostics = await request('GET', '/api/v1/diagnostics');
     const output = { ok: local.every(c => c.ok) && controlDiagnostics.ok, local, control: controlDiagnostics };
-    if (o.nodes || o.node)
-        output.nodeDiagnostics = await request('POST', '/api/v1/diagnostics/nodes', { node: o.node || null });
+    if (o.nodes || o.node) {
+        const queued = await request('POST', '/api/v1/diagnostics/nodes', { node: o.node || null });
+        const commands = [];
+        for (const command of queued.commands) {
+            const finished = await waitForCommand(command.commandId, Number(o.timeout));
+            commands.push({ nodeId: command.nodeId, state: finished.state, result: JSON.parse(finished.result_json || '{}') });
+        }
+        output.nodeDiagnostics = { commands };
+        if (commands.some(command => command.state !== 'succeeded'))
+            output.ok = false;
+    }
     console.log(JSON.stringify(output, null, 2));
 });
-program.command('rollback').option('--project <name>').option('--force').option('--no-wait', 'return immediately after activating rollback').option('--timeout <seconds>', 'wait timeout', '300').action(async (o) => {
+program.command('rollback').option('--force').option('--no-wait', 'return immediately after activating rollback').option('--timeout <seconds>', 'wait timeout', '300').action(async (o) => {
     const cfg = await loadCfg();
     const response = await request('POST', '/api/v1/rollback', { project: o.project || cfg.project || 'site', force: Boolean(o.force) });
     if (o.wait)
         response.deployment = await waitForDeployment(response.deployment.id, Number(o.timeout));
     console.log(JSON.stringify(response, null, 2));
 });
-program.command('deploy:cancel <id>').action(async (id) => console.log(JSON.stringify(await request('POST', `/api/v1/deployments/${encodeURIComponent(id)}/cancel`, {}), null, 2)));
-program.command('volume:list').option('--project <name>').action(async (o) => {
+program.command('deploy-cancel <id>').action(async (id) => console.log(JSON.stringify(await request('POST', `/api/v1/deployments/${encodeURIComponent(id)}/cancel`, {}), null, 2)));
+program.command('volume-list').action(async (o) => {
     const cfg = await loadCfg();
     console.log(JSON.stringify(await request('GET', `/api/v1/volumes?project=${encodeURIComponent(o.project || cfg.project || 'site')}`), null, 2));
 });
-program.command('volume:rm <name>').option('--project <name>').option('--delete-data', 'delete underlying Docker volume data').action(async (name, o) => {
+program.command('volume-remove <name>').option('--delete-data', 'delete underlying Docker volume data').action(async (name, o) => {
     const cfg = await loadCfg();
     const project = o.project || cfg.project || 'site';
     console.log(JSON.stringify(await request('DELETE', `/api/v1/volumes/${encodeURIComponent(name)}?project=${encodeURIComponent(project)}&deleteData=${Boolean(o.deleteData)}`), null, 2));
 });
-const controlBackup = program.command('control-backup');
-controlBackup.command('run').description('create a control-plane SQLite/master-key backup').action(async () => console.log(JSON.stringify(await request('POST', '/api/v1/control/backups/run', {}), null, 2)));
-controlBackup.command('restore <artifactRef>').description('restore a control-plane backup; requires control restart').option('--confirm').action(async (artifactRef, o) => console.log(JSON.stringify(await request('POST', '/api/v1/control/restore', { artifactRef, confirm: Boolean(o.confirm) }), null, 2)));
+program.command('control-backup').description('create a control-plane SQLite/master-key backup').action(async () => console.log(JSON.stringify(await request('POST', '/api/v1/control/backups/run', {}), null, 2)));
+program.command('control-restore <artifactRef>').description('restore a control-plane backup; requires control restart').option('--confirm').action(async (artifactRef, o) => console.log(JSON.stringify(await request('POST', '/api/v1/control/restore', { artifactRef, confirm: Boolean(o.confirm) }), null, 2)));
 async function waitForCommand(commandId, timeoutSeconds = 60) {
     const deadline = Date.now() + timeoutSeconds * 1000;
     while (Date.now() < deadline) {
@@ -308,7 +365,7 @@ async function waitForCommand(commandId, timeoutSeconds = 60) {
     }
     throw new Error(`timed out waiting for command ${commandId}`);
 }
-program.command('restart <service>').option('--project <name>').option('--timeout <seconds>', 'wait timeout', '60').action(async (svc, o) => {
+program.command('restart <service>').option('--timeout <seconds>', 'wait timeout', '60').action(async (svc, o) => {
     const cfg = await loadCfg();
     const project = o.project || cfg.project || 'site';
     const created = await request('POST', '/api/v1/restart', { project, service: svc });
@@ -317,7 +374,7 @@ program.command('restart <service>').option('--project <name>').option('--timeou
         throw new Error(JSON.parse(cmd.result_json || '{}').error || 'restart failed');
     console.log(JSON.stringify(cmd, null, 2));
 });
-program.command('logs <service>').description('fetch logs from the assigned node agent').option('--project <name>').option('--tail <n>', 'number of lines', '200').action(async (svc, o) => {
+program.command('logs <service>').description('fetch logs from the assigned node agent').option('--tail <n>', 'number of lines', '200').action(async (svc, o) => {
     const cfg = await loadCfg();
     const project = o.project || cfg.project || 'site';
     const created = await request('POST', '/api/v1/logs', { project, service: svc, tail: Number(o.tail) });
@@ -330,4 +387,45 @@ program.command('logs <service>').description('fetch logs from the assigned node
     if (result.error)
         throw new Error(result.error);
 });
-program.parseAsync().catch((e) => { console.error(errMessage(e)); process.exit(1); });
+program.hook('preAction', async (_root, command) => {
+    const options = command.opts();
+    for (const [key, min, max] of [['port', 1, 65535], ['wgPort', 1, 65535], ['timeout', 1, 86400], ['ttl', 1, 31536000], ['uses', 1, 1000000], ['expiresInDays', 1, 3650], ['limit', 1, 500], ['tail', 1, 1000000]]) {
+        if (options[key] !== undefined)
+            integerOption(String(options[key]), '--' + key.replace(/[A-Z]/g, c => '-' + c.toLowerCase()), min, max);
+    }
+    if (options.buildLocal && options.buildUpload === false)
+        throw new Error('--build-local and --no-build-upload cannot be combined');
+    if ((options.registryAuthPath || options.registryContainer) && !options.registry)
+        throw new Error('--registry-auth-path and --registry-container require --registry');
+    if (command.name() === 'control-restore' && !options.confirm)
+        throw new Error('control-restore requires --confirm');
+    for (const value of [...command.args, ...Object.values(options), ...Object.values(program.opts())])
+        if (typeof value === 'string' && /[\r\n\0]/.test(value))
+            throw new Error('arguments and option values must not contain line breaks or NUL');
+    if (options.name && !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(options.name))
+        throw new Error('--name must contain only letters, numbers, dots, underscores or hyphens');
+    const connection = command.optsWithGlobals();
+    if (command.name() === 'token-create') {
+        // --project is repeatable here and scopes the new token, so it must not also select the connection project.
+        if (!TOKEN_NAME_PATTERN.test(command.args[0]))
+            throw new Error('token name must be 1-64 letters, numbers, dots, underscores or hyphens, starting with a letter or number');
+        for (const project of options.project)
+            if (!PROJECT_NAME_PATTERN.test(project))
+                throw new Error('--project must contain only letters, numbers, dots, underscores or hyphens');
+        if (options.role === 'admin' && options.project.length)
+            throw new Error('admin tokens cannot be limited to projects; use --role read or --role deploy with --project');
+        connection.project = undefined;
+    }
+    resolvedConfig = await resolveCliConfig(connection, process.env, process.cwd(), command.name() === 'init');
+});
+for (const command of program.commands) {
+    command
+        .option('--config <file>', 'CLI JSON config file (default: TUG_CONFIG or .tug.json)')
+        .option('--control-url <url>', 'control API URL (overrides TUG_CONTROL_URL and config)');
+    if (!command.options.some(option => option.long === '--project'))
+        command.option('--project <name>', 'project (overrides TUG_PROJECT and config; default: site)');
+}
+for (const command of [program, ...program.commands])
+    command.allowExcessArguments(false);
+program.showHelpAfterError();
+program.parseAsync().catch((e) => { console.error(`${errMessage(e)}\nRun tug <command> --help for usage.`); process.exit(1); });

package/dist/compose.d.ts

@@ -6,18 +6,28 @@ export declare function composeHash(compose: ComposeFile): string;
  * container port resolves to its published host port). Null when the port is not published.
  */
 export declare function publishedPort(svc: ComposeService, port: number): number | null;
+/** True when the service opted in to `x-tug.rollout.strategy: rolling`. */
+export declare function isRolling(svc: ComposeService | undefined): boolean;
 export declare function validateCompose(compose: ComposeFile | undefined, nodes?: string[]): asserts compose is ComposeFile;
 export interface BuildDesiredStateOptions {
     project: string;
     version: string;
     compose: ComposeFile;
     registry: string;
+    revision?: string;
     defaultNode?: string | null;
 }
-export declare function buildDesiredState({ project, version, compose, registry, defaultNode }: BuildDesiredStateOptions): DesiredState;
+export declare function buildDesiredState({ project, version, compose, registry, revision, defaultNode }: BuildDesiredStateOptions): DesiredState;
 /** `extra_hosts` entries (`name:ip`) for services that run on other nodes, from health-aware endpoints. */
 export declare function crossNodeHosts(project: string, endpoints: Record<string, ServiceEndpoint[]>, local: Set<string>): string[];
-export declare function composeForNode(desiredState: DesiredState, nodeName: string, secrets?: Record<string, string>, endpoints?: Record<string, ServiceEndpoint[]>): ComposeFile;
+/** Removes `depends_on` references to `names` (services that live in another Compose project). */
+export declare function dropDependsOn(svc: ComposeService, names: ReadonlySet<string>): void;
+/**
+ * The Compose file for one node. `exclude` names services placed here that are managed outside the
+ * node's main project (rolling services run in their own revision projects); they still count as
+ * local, so they get no cross-node `extra_hosts` entry, and `depends_on` references to them are dropped.
+ */
+export declare function composeForNode(desiredState: DesiredState, nodeName: string, secrets?: Record<string, string>, endpoints?: Record<string, ServiceEndpoint[]>, exclude?: ReadonlySet<string>): ComposeFile;
 export declare function serviceSecretNames(compose: ComposeFile | undefined, serviceNames: Iterable<string>): Set<string>;
 export declare function serviceSecretVersions(compose: ComposeFile | undefined, serviceNames: Iterable<string>, versions?: Record<string, number>): Record<string, Record<string, number>>;
 export declare function dumpYaml(obj: unknown): string;