@wpelevator/tug 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+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 { 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)); }
+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 headers = tok ? { Authorization: `Bearer ${tok}` } : {};
+    if (!multipart)
+        headers['content-type'] = 'application/json';
+    const res = await fetch(`${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 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`);
+}
+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);
+}
+function remoteHost(sshTarget) { return sshTarget.replace(/^[^@]+@/, '').split(':')[0]; }
+function assertHttps(url, allowHttp) {
+    if (!allowHttp && !String(url).startsWith('https://'))
+        throw new Error(`${url} must use https:// outside local development (pass --http-only-dev to override)`);
+}
+function preflightRemote(target, { controlUrl, ports = [], udpPorts = [], minDiskMb = 1024, mesh = false } = {}) {
+    const checks = [
+        ['docker.version', 'docker version >/dev/null', 'Install Docker Engine and ensure the SSH user can access it.'],
+        ['docker.compose.version', 'docker compose version >/dev/null', 'Install Docker Compose v2.'],
+        ['paths', 'mkdir -p /opt/tug-preflight /var/lib/tug-preflight /etc/tug && test -w /opt/tug-preflight && test -w /var/lib/tug-preflight && test -w /etc/tug', 'Ensure /opt, /var/lib, and /etc/tug are writable by the installer.'],
+        ['disk.space', `[ "$(df -Pm /var/lib | tail -1 | awk '{print $4}')" -ge ${Number(minDiskMb)} ]`, `Free at least ${minDiskMb}MB on the filesystem backing /var/lib.`]
+    ];
+    for (const port of ports) {
+        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.']);
+    }
+    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).`]);
+    }
+    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]);
+}
+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 });
+}
+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}`);
+}
+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 });
+    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 });
+    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) => {
+    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) => {
+    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) => {
+    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) => {
+    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>')
+    .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('--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-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');
+    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 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 || ''
+    });
+    const remote = await loadTemplate(templatesDir, 'control-install.sh', {
+        COMPOSE: compose, OPERATOR_TOKEN_SH: sh(operatorToken)
+    });
+    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>')
+    .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('--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('--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';
+    assertHttps(controlUrl, o.httpOnlyDev);
+    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);
+    if (o.buildLocalImage)
+        await transferTugImage(sshTarget, image);
+    const env = await loadTemplate(templatesDir, 'agent.env', {
+        CONTROL_URL: controlUrl, NODE_NAME: o.name, AGENT_TOKEN: registered.agentToken
+    }) + (o.mesh ? 'TUG_MESH=true\n' : '');
+    const dockerLogin = o.registry ? `printf %s ${sh(registered.registryToken)} | docker login ${sh(o.registry)} --username ${sh(o.name)} --password-stdin` : 'true';
+    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]);
+    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')
+    .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('--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')
+    .action(async (o) => {
+    const cfg = await loadCfg();
+    const controlUrl = o.controlUrl || cfg.controlUrl || process.env.TUG_CONTROL_URL || 'http://localhost:8080';
+    assertHttps(controlUrl, o.httpOnlyDev);
+    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');
+    const joinKey = Buffer.from(JSON.stringify(keyPayload)).toString('base64url');
+    if (o.json) {
+        console.log(JSON.stringify({ ...minted, controlUrl, joinKey }, null, 2));
+        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));
+});
+program.command('secret:set <name>').option('--project <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')}`)));
+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));
+    }
+    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) => {
+    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 }));
+        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 });
+    }
+    else
+        response = await request('POST', '/api/v1/deployments', { project, version, compose });
+    if (o.wait)
+        response.deployment = await waitForDeployment(response.deployment.id, Number(o.timeout));
+    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) => {
+    const cfg = await loadCfg();
+    const project = 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) => {
+    const local = [];
+    for (const [name, cmd, args] of [['node', 'node', ['--version']], ['docker', 'docker', ['version', '--format', '{{.Server.Version}}']], ['docker_compose', 'docker', ['compose', 'version']]]) {
+        try {
+            local.push({ name, ok: true, output: runCapture(cmd, args).trim() });
+        }
+        catch (e) {
+            local.push({ name, ok: false, error: errMessage(e) });
+        }
+    }
+    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 });
+    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) => {
+    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) => {
+    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) => {
+    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)));
+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}`);
+}
+program.command('restart <service>').option('--project <name>').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 });
+    const cmd = await waitForCommand(created.commandId, Number(o.timeout));
+    if (cmd.state === 'failed')
+        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) => {
+    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) });
+    const cmd = await waitForCommand(created.commandId, 60);
+    const result = JSON.parse(cmd.result_json || '{}');
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    if (result.error)
+        throw new Error(result.error);
+});
+program.parseAsync().catch((e) => { console.error(errMessage(e)); process.exit(1); });

package/dist/compose.d.ts

@@ -0,0 +1,23 @@
+import type { ComposeFile, ComposeService, DesiredState, ServiceEndpoint } from './protocol.ts';
+export declare function readCompose(file?: string): Promise<ComposeFile>;
+export declare function composeHash(compose: ComposeFile): string;
+/**
+ * The host port a service publishes for `port`, matching either side of a `ports` entry (a
+ * 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;
+export declare function validateCompose(compose: ComposeFile | undefined, nodes?: string[]): asserts compose is ComposeFile;
+export interface BuildDesiredStateOptions {
+    project: string;
+    version: string;
+    compose: ComposeFile;
+    registry: string;
+    defaultNode?: string | null;
+}
+export declare function buildDesiredState({ project, version, compose, registry, 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;
+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;

package/dist/compose.js

@@ -0,0 +1,182 @@
+import fs from 'node:fs/promises';
+import yaml from 'js-yaml';
+import crypto from 'node:crypto';
+export async function readCompose(file = 'docker-compose.yml') {
+    return yaml.load(await fs.readFile(file, 'utf8'));
+}
+export function composeHash(compose) {
+    return crypto.createHash('sha1').update(JSON.stringify(compose)).digest('hex').slice(0, 12);
+}
+/**
+ * The host port a service publishes for `port`, matching either side of a `ports` entry (a
+ * container port resolves to its published host port). Null when the port is not published.
+ */
+export function publishedPort(svc, port) {
+    for (const entry of svc.ports || []) {
+        if (typeof entry === 'object') {
+            const published = Number(entry.published);
+            if ((Number(entry.target) === port || published === port) && published > 0)
+                return published;
+            continue;
+        }
+        const spec = String(entry).split('/')[0].split(':');
+        if (spec.length < 2)
+            continue;
+        const container = Number(spec[spec.length - 1]);
+        const host = Number(spec[spec.length - 2]);
+        if ((container === port || host === port) && host > 0)
+            return host;
+    }
+    return null;
+}
+const HOSTNAME_RE = /^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i;
+function validateIngress(name, svc, seen, errors) {
+    const ingress = svc['x-tug']?.ingress;
+    if (ingress === undefined)
+        return;
+    if (!ingress || typeof ingress !== 'object') {
+        errors.push(`${name}: x-tug.ingress must be an object`);
+        return;
+    }
+    const host = typeof ingress.host === 'string' ? ingress.host.toLowerCase() : '';
+    if (!HOSTNAME_RE.test(host))
+        errors.push(`${name}: ingress.host must be a fully qualified hostname`);
+    else if (seen.has(host))
+        errors.push(`${name}: ingress.host ${host} is already used by ${seen.get(host)}`);
+    else
+        seen.set(host, name);
+    const port = Number(ingress.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        errors.push(`${name}: ingress.port must be a port number`);
+    else if (publishedPort(svc, port) == null)
+        errors.push(`${name}: ingress.port ${port} must be published in ports (e.g. "8080:${port}"); the edge reaches the service on its published host port`);
+    const tls = ingress.tls ?? 'auto';
+    if (!['auto', 'custom', 'off'].includes(tls))
+        errors.push(`${name}: ingress.tls must be auto, custom or off`);
+    if (tls === 'custom' && (!ingress.cert || !ingress.key))
+        errors.push(`${name}: ingress.tls custom requires cert and key (names of project secrets holding the PEM certificate and private key)`);
+}
+export function validateCompose(compose, nodes = []) {
+    if (!compose?.services || typeof compose.services !== 'object')
+        throw new Error('compose file must define services');
+    const errors = [];
+    const ingressHosts = new Map();
+    for (const [name, svc] of Object.entries(compose.services)) {
+        if (svc.container_name)
+            errors.push(`${name}: container_name is not supported`);
+        if (svc.deploy)
+            errors.push(`${name}: swarm deploy semantics are not supported`);
+        const lp = svc['x-tug'] || {};
+        const selected = lp.placement?.nodes || [];
+        if (nodes.length > 1 && selected.length === 0)
+            errors.push(`${name}: multi-node deployments require x-tug.placement.nodes`);
+        if (lp.replicas && selected.length && lp.replicas !== selected.length)
+            errors.push(`${name}: replicas must match placement node count in v1`);
+        validateIngress(name, svc, ingressHosts, errors);
+    }
+    if (errors.length)
+        throw new Error(errors.join('; '));
+}
+export function buildDesiredState({ project, version, compose, registry, defaultNode = null }) {
+    const services = {};
+    for (const [name, src] of Object.entries(compose.services || {})) {
+        const lp = src['x-tug'] || {};
+        const placement = lp.placement || (defaultNode ? { nodes: [defaultNode] } : {});
+        const image = src.build ? `${registry}/${project}/${name}:${version}` : src.image;
+        services[name] = { image, build: src.build || null, placement, replicas: lp.replicas || placement.nodes?.length || 1, health: lp.health || null };
+    }
+    return { project, version, services, compose };
+}
+/** `extra_hosts` entries (`name:ip`) for services that run on other nodes, from health-aware endpoints. */
+export function crossNodeHosts(project, endpoints, local) {
+    const hosts = [];
+    for (const [service, list] of Object.entries(endpoints).sort(([a], [b]) => a.localeCompare(b))) {
+        if (local.has(service))
+            continue;
+        for (const ep of list)
+            hosts.push(`${service}:${ep.address}`, `${service}.${project}.tug:${ep.address}`);
+    }
+    return hosts;
+}
+function extraHostsList(value) {
+    if (!value)
+        return [];
+    return Array.isArray(value) ? value.map(String) : Object.entries(value).map(([k, v]) => `${k}:${v}`);
+}
+export function composeForNode(desiredState, nodeName, secrets = {}, endpoints = {}) {
+    const out = { services: {}, volumes: {} };
+    const outVolumes = out.volumes;
+    const usedVolumes = new Set();
+    for (const [name, src] of Object.entries(desiredState.compose.services || {})) {
+        const lp = src['x-tug'] || {};
+        const nodes = lp.placement?.nodes || [];
+        if (nodes.length && !nodes.includes(nodeName))
+            continue;
+        const svc = { ...src, image: desiredState.services[name].image };
+        delete svc.build;
+        delete svc['x-tug'];
+        delete svc.deploy;
+        delete svc.container_name;
+        if (Object.keys(secrets).length)
+            svc.env_file = Array.from(new Set([...(Array.isArray(svc.env_file) ? svc.env_file : svc.env_file ? [svc.env_file] : []), '.env']));
+        for (const vol of svc.volumes || []) {
+            const source = typeof vol === 'string' ? vol.split(':')[0] : vol.source;
+            if (source && desiredState.compose?.volumes?.[source])
+                usedVolumes.add(source);
+        }
+        out.services[name] = svc;
+    }
+    const hosts = crossNodeHosts(desiredState.project, endpoints, new Set(Object.keys(out.services)));
+    if (hosts.length) {
+        for (const svc of Object.values(out.services)) {
+            const existing = extraHostsList(svc.extra_hosts);
+            const taken = new Set(existing.map(h => h.split(':')[0]));
+            svc.extra_hosts = [...existing, ...hosts.filter(h => !taken.has(h.split(':')[0]))];
+        }
+    }
+    for (const name of usedVolumes) {
+        const vol = desiredState.compose.volumes?.[name] || {};
+        const nodes = vol['x-tug']?.placement?.nodes || [];
+        if (!nodes.length || nodes.includes(nodeName))
+            outVolumes[name] = vol;
+    }
+    if (!Object.keys(outVolumes).length)
+        delete out.volumes;
+    return out;
+}
+export function serviceSecretNames(compose, serviceNames) {
+    const allowed = new Set();
+    for (const serviceName of serviceNames) {
+        const env = compose?.services?.[serviceName]?.environment || {};
+        if (Array.isArray(env)) {
+            for (const entry of env) {
+                const [key, value = ''] = String(entry).split('=');
+                if (key)
+                    allowed.add(key);
+                for (const match of String(value).matchAll(/\$\{?([A-Z_][A-Z0-9_]*)[^}]*\}?/g))
+                    allowed.add(match[1]);
+            }
+        }
+        else {
+            for (const [key, value] of Object.entries(env)) {
+                if (typeof value === 'string' && value.match(/^\$\{?[A-Z_][A-Z0-9_]*(?::-[^}]*)?\}?$/)) {
+                    const m = value.match(/^\$\{?([A-Z_][A-Z0-9_]*)/);
+                    if (m)
+                        allowed.add(m[1]);
+                }
+                else
+                    allowed.add(key);
+            }
+        }
+    }
+    return allowed;
+}
+export function serviceSecretVersions(compose, serviceNames, versions = {}) {
+    const out = {};
+    for (const service of serviceNames) {
+        const names = serviceSecretNames(compose, [service]);
+        out[service] = Object.fromEntries([...names].filter(name => versions[name] != null).map(name => [name, versions[name]]));
+    }
+    return out;
+}
+export function dumpYaml(obj) { return yaml.dump(obj, { noRefs: true, lineWidth: 120 }); }

package/dist/control.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import express from 'express';
+import https from 'node:https';
+import type { NodeRow } from './db.ts';
+declare module 'express-serve-static-core' {
+    interface Request {
+        node?: NodeRow;
+    }
+}
+export declare function createApp(): Promise<import("express-serve-static-core").Express>;
+export declare function listen(app: express.Express, port?: number): Promise<import('node:http').Server | https.Server>;