@wpelevator/tug 0.0.0 → 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# Tug
+
+The name: tugboats pull ships into place, like the pull-based agents here; `tug` is the CLI.
+
+Deploy Docker Compose projects to one or more ordinary Linux VPSes through a small self-hosted control plane and a pull-based agent on each node, without Kubernetes or a hosted PaaS. The original specification is in [plan.md](plan.md).
+
+## Features
+
+- Control API with bearer-token auth and SQLite metadata.
+- Nodes join over SSH (`node install`) or enroll themselves with a single `docker run` (`node enroll`), with per-node agent and registry tokens. Agents only dial out, so nodes behind NAT work.
+- Agents pull desired state from control, apply a generated per-node Compose file, run TCP/HTTP/Docker health checks and report status.
+- `x-tug` placement of services and volumes on nodes, with immutable desired-state records per deployment.
+- Optional remote Docker builds on the control host from an uploaded source tarball.
+- Secrets encrypted at rest, released only to the nodes whose services reference them, with targeted service recreation when only a secret changes.
+- Deployment convergence, per-project operation locks, cancellation, rollback, per-service rollout events and log fetching through the agents.
+- Per-node registry pull tokens enforced by an htpasswd-backed registry you provide, with rotation and revocation.
+- Optional WireGuard mesh between nodes, health-aware cross-node service names and a managed Caddy ingress with automatic HTTPS, each opt-in. See [Networking](docs/networking.md).
+- Control-plane backup and restore, and `tug doctor` diagnostics.
+
+## Quick start
+
+Install the CLI (Node >= 22.18), or run it without installing through `npx @wpelevator/tug`:
+
+```bash
+npm install -g @wpelevator/tug
+```
+
+The CLI installs the matching `ghcr.io/wpelevator/tug:<version>` image on your hosts.
+
+1. Install the control plane on a Docker host, pointing it at a registry you already run: `tug control install root@control.example.com --registry registry.example.com`.
+2. Point the CLI at it: `tug init --control-url https://control.example.com --token "$TUG_TOKEN"`.
+3. Set the secrets your services need: `tug secret:set DB_PASSWORD`.
+4. Add nodes, either `tug node install root@app1.example.com --name app1 --control-url https://control.example.com --registry registry.example.com`, or `tug node enroll --name app1` and run the printed `docker run` on the host.
+5. Deploy: `tug deploy -f docker-compose.yml`. It waits until every node reports the new version healthy.
+6. Operate with `tug status`, `events`, `logs`, `restart`, `rollback` and `doctor`.
+
+## Documentation
+
+- [Architecture](docs/architecture.md): components, reconciliation, workflow diagrams, secrets and runtime paths.
+- [Compose extensions](docs/compose.md): `x-tug` placement, health checks, volumes and limitations.
+- [Control plane](docs/control-plane.md): install, TLS, registry credentials, backup and restore.
+- [Networking](docs/networking.md): WireGuard mesh, service DNS, ingress and TLS, firewall notes.
+- [Nodes](docs/nodes.md): SSH install, self-service enrollment, registration and status.
+- [CLI reference](docs/cli.md): every `tug` command and option.
+- [Configuration](docs/configuration.md): CLI, control and agent environment variables.
+- [Development](docs/development.md): local setup, CI, Compose stack, host mode and the integration test.
+- [Releases](docs/releases.md): changesets, npm and Docker image publishing.
+- [Roadmap](docs/roadmap.md): planned milestones toward parity with and beyond uncloud.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run lint
+npm run test:integration
+```
+
+See [Development](docs/development.md) for details.

package/dist/agent.d.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import type { DockerRunner, HostRunner, HttpClient } from './runners.ts';
+import type { Command, CommandResult, DesiredState, HealthCheck, ProjectStatus, ServiceEndpoint } from './protocol.ts';
+export interface AgentContext {
+    docker: DockerRunner;
+    http: HttpClient;
+    nodeName: string;
+    stateDir: string;
+    apply: boolean;
+    controlUrl: string;
+    token: string | undefined;
+    /** Runs `wg` / `ip` for the mesh. */
+    host?: HostRunner;
+    /** Manage the WireGuard mesh (generate a key, report it, reconcile `wg0`). */
+    mesh?: boolean;
+    caddyImage?: string;
+}
+export declare function defaultContext(): AgentContext;
+export declare function containerIp(ctx: AgentContext, project: string, service: string, cwd: string): Promise<string>;
+export declare function waitForHealth(ctx: AgentContext, project: string, service: string, health: HealthCheck | null | undefined, cwd: string): Promise<void>;
+export declare function parseDuration(value: string | number): number;
+export declare function executeCommand(command: Command, ctx?: AgentContext): Promise<CommandResult>;
+export declare function reconcile(desiredState: DesiredState, ctx?: AgentContext, endpoints?: Record<string, ServiceEndpoint[]>): Promise<ProjectStatus>;
+/** Reports this node's WireGuard public key when control has not seen the current one yet. */
+export declare function reportWgKey(ctx: AgentContext): Promise<void>;
+export declare function pollOnce(ctx?: AgentContext): Promise<ProjectStatus[]>;
+interface Creds {
+    agentToken: string;
+    nodeName?: string;
+    controlUrl?: string;
+    registry?: string | null;
+    registryToken?: string | null;
+}
+export declare function loadOrEnroll(): Promise<Creds>;
+export declare function main(): Promise<void>;
+export {};

package/dist/agent.js

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import net from 'node:net';
+import { composeForNode, dumpYaml, serviceSecretVersions } from "./compose.js";
+import { ensureDir, errMessage, now } from "./util.js";
+import { openAgentDb } from "./db.js";
+import { createDockerRunner, createHostRunner } from "./runners.js";
+import { CADDY_CONTAINER, reconcileIngress, removeIngress } from "./ingress.js";
+import { WG_INTERFACE, ensureWgKeys, readReportedKey, reconcileMesh, rotateWgKeys, writeReportedKey } from "./mesh.js";
+const CONTROL_URL_FROM_ENV = Boolean(process.env.TUG_CONTROL_URL);
+let CONTROL_URL = process.env.TUG_CONTROL_URL || 'http://localhost:8080';
+let TOKEN = process.env.TUG_AGENT_TOKEN;
+let NODE_NAME = process.env.TUG_NODE_NAME || process.env.HOSTNAME || 'node1';
+const STATE_DIR = process.env.TUG_STATE_DIR || '/var/lib/tug';
+const APPLY = process.env.TUG_APPLY !== 'false';
+const INTERVAL = Number(process.env.TUG_POLL_INTERVAL_MS || 5000);
+// Opt-in WireGuard mesh: needs `wg`/`ip` in the agent image, host networking and NET_ADMIN.
+const MESH = process.env.TUG_MESH === 'true';
+export function defaultContext() {
+    return { docker: createDockerRunner(), http: fetch, nodeName: NODE_NAME, stateDir: STATE_DIR, apply: APPLY, controlUrl: CONTROL_URL, token: TOKEN, host: createHostRunner(), mesh: MESH, caddyImage: process.env.TUG_CADDY_IMAGE };
+}
+const dbsByStateDir = new Map();
+async function agentDb(stateDir) {
+    let db = dbsByStateDir.get(stateDir);
+    if (!db) {
+        await ensureDir(stateDir);
+        db = await openAgentDb(path.join(stateDir, 'agent.db'));
+        dbsByStateDir.set(stateDir, db);
+    }
+    return db;
+}
+function authHeaders(ctx) { if (!ctx.token)
+    throw new Error('TUG_AGENT_TOKEN required'); return { Authorization: `Bearer ${ctx.token}` }; }
+async function api(ctx, route, opts = {}) {
+    const res = await ctx.http(`${ctx.controlUrl}${route}`, { ...opts, headers: { ...authHeaders(ctx), ...(opts.headers || {}) } });
+    if (!res.ok)
+        throw new Error(`${opts.method || 'GET'} ${route}: ${res.status} ${await res.text()}`);
+    return res.json();
+}
+async function writeEnv(file, secrets) {
+    const body = Object.entries(secrets).map(([k, v]) => `${k}=${String(v).replace(/\n/g, '\\n')}`).join('\n') + '\n';
+    await fs.writeFile(file, body, { mode: 0o600 });
+}
+export async function containerIp(ctx, project, service, cwd) {
+    const ids = (await ctx.docker(['compose', '-p', project, 'ps', '-q', service], { cwd })).out.trim().split(/\s+/).filter(Boolean);
+    if (!ids.length)
+        throw new Error(`${service}: no container found`);
+    const inspected = JSON.parse((await ctx.docker(['inspect', ids[0]], { cwd })).out)[0];
+    const networks = inspected?.NetworkSettings?.Networks || {};
+    return Object.values(networks)[0]?.IPAddress || '127.0.0.1';
+}
+function tcpCheck(host, port, timeoutMs = 2000) {
+    return new Promise((resolve, reject) => {
+        const s = net.createConnection({ host, port: Number(port), timeout: timeoutMs }, () => { s.destroy(); resolve(true); });
+        s.on('timeout', () => { s.destroy(); reject(new Error(`tcp timeout ${host}:${port}`)); });
+        s.on('error', reject);
+    });
+}
+export async function waitForHealth(ctx, project, service, health, cwd) {
+    if (!ctx.apply || !health)
+        return;
+    const retries = Number(health.retries || 10);
+    const intervalMs = parseDuration(health.interval || '2s');
+    let last;
+    for (let i = 0; i < retries; i++) {
+        try {
+            if (health.type === 'docker') {
+                const id = (await ctx.docker(['compose', '-p', project, 'ps', '-q', service], { cwd })).out.trim().split(/\s+/)[0];
+                const state = JSON.parse((await ctx.docker(['inspect', id], { cwd })).out)[0]?.State;
+                if (!state?.Running)
+                    throw new Error(`${service}: not running`);
+                if (state.Health && state.Health.Status !== 'healthy')
+                    throw new Error(`${service}: docker health ${state.Health.Status}`);
+            }
+            else if (health.type === 'tcp') {
+                await tcpCheck(await containerIp(ctx, project, service, cwd), health.port, parseDuration(health.timeout || '2s'));
+            }
+            else if (health.type === 'http') {
+                const ip = await containerIp(ctx, project, service, cwd);
+                const res = await ctx.http(`http://${ip}:${health.port || 80}${health.path || '/'}`, { signal: AbortSignal.timeout(parseDuration(health.timeout || '2s')) });
+                if (!res.ok)
+                    throw new Error(`${service}: http ${res.status}`);
+            }
+            return;
+        }
+        catch (e) {
+            last = e;
+            await new Promise(r => setTimeout(r, intervalMs));
+        }
+    }
+    throw last || new Error(`${service}: health check failed`);
+}
+export function parseDuration(value) {
+    if (typeof value === 'number')
+        return value;
+    const m = String(value).match(/^(\d+)(ms|s|m)?$/);
+    if (!m)
+        return 2000;
+    const n = Number(m[1]);
+    return m[2] === 'm' ? n * 60000 : m[2] === 'ms' ? n : n * 1000;
+}
+export async function executeCommand(command, ctx = defaultContext()) {
+    const payload = typeof command.payload_json === 'string' ? JSON.parse(command.payload_json || '{}') : command.payload || {};
+    if (command.type === 'diagnostics.run') {
+        const checks = [];
+        for (const [name, args] of [
+            ['docker.info', ['info']],
+            ['docker.version', ['version']],
+            ['docker.compose.version', ['compose', 'version']]
+        ]) {
+            try {
+                const result = await ctx.docker([...args]);
+                checks.push({ name, ok: true, stdout: result.out.slice(-4000), stderr: result.err.slice(-4000) });
+            }
+            catch (e) {
+                checks.push({ name, ok: false, error: errMessage(e).slice(-4000) });
+            }
+        }
+        const extra = [];
+        if (ctx.mesh && ctx.host) {
+            const host = ctx.host;
+            extra.push(['wireguard.version', () => host('wg', ['--version'])], ['wireguard.interface', () => host('wg', ['show', WG_INTERFACE])]);
+        }
+        if (await fs.stat(path.join(ctx.stateDir, 'ingress')).then(() => true, () => false)) {
+            extra.push(['ingress.caddy', () => ctx.docker(['container', 'inspect', '-f', '{{.State.Status}}', CADDY_CONTAINER])]);
+        }
+        for (const [name, fn] of extra) {
+            try {
+                const result = await fn();
+                checks.push({ name, ok: true, stdout: result.out.slice(-4000), stderr: result.err.slice(-4000) });
+            }
+            catch (e) {
+                checks.push({ name, ok: false, error: errMessage(e).slice(-4000) });
+            }
+        }
+        return { commandId: command.id, state: checks.every(c => c.ok) ? 'succeeded' : 'failed', result: { checks, node: ctx.nodeName } };
+    }
+    if (command.type === 'service.restart') {
+        const project = payload.project;
+        const service = payload.service;
+        const dir = path.join(ctx.stateDir, 'projects', project);
+        await ctx.docker(['compose', '-p', project, 'restart', service], { cwd: dir });
+        return { commandId: command.id, state: 'succeeded', result: { project, service, restarted: true } };
+    }
+    if (command.type === 'logs.fetch') {
+        const project = payload.project;
+        const service = payload.service;
+        const tail = String(payload.tail || 200);
+        const dir = path.join(ctx.stateDir, 'projects', project);
+        const result = await ctx.docker(['compose', '-p', project, 'logs', '--no-color', '--tail', tail, service], { cwd: dir });
+        return { commandId: command.id, state: 'succeeded', result: { stdout: result.out, stderr: result.err } };
+    }
+    if (command.type === 'volume.delete') {
+        const project = payload.project;
+        const volume = payload.volume;
+        const composeVolume = `${project}_${volume}`;
+        try {
+            await ctx.docker(['volume', 'rm', composeVolume]);
+        }
+        catch (e) {
+            if (!errMessage(e).includes('No such volume'))
+                throw e;
+        }
+        return { commandId: command.id, state: 'succeeded', result: { project, volume, deleted: true } };
+    }
+    if (command.type === 'wg.rotate-key') {
+        if (!ctx.mesh)
+            throw new Error('the WireGuard mesh is not enabled on this agent (TUG_MESH=true)');
+        const { publicKey } = await rotateWgKeys(ctx.stateDir);
+        await api(ctx, '/agent/v1/wireguard/key', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ publicKey }) });
+        await writeReportedKey(ctx.stateDir, publicKey);
+        return { commandId: command.id, state: 'succeeded', result: { publicKey } };
+    }
+    return { commandId: command.id, state: 'failed', result: { error: `unsupported command ${command.type}` } };
+}
+export async function reconcile(desiredState, ctx = defaultContext(), endpoints = {}) {
+    const dir = path.join(ctx.stateDir, 'projects', desiredState.project);
+    await ensureDir(dir);
+    const plannedCompose = composeForNode(desiredState, ctx.nodeName, {});
+    const serviceNames = Object.keys(plannedCompose.services || {});
+    if (!serviceNames.length)
+        return { project: desiredState.project, observedVersion: desiredState.version, health: 'skipped', services: [], serviceStates: {} };
+    const serviceStates = Object.fromEntries(serviceNames.map(service => [service, { rolloutState: 'pending', image: desiredState.services[service]?.image }]));
+    const emit = (service, rolloutState, message = rolloutState) => api(ctx, '/agent/v1/events', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ projectId: desiredState.project, level: 'info', type: `service.${rolloutState}`, message, metadata: { service, version: desiredState.version, node: ctx.nodeName } }) }).catch(() => { });
+    const sec = await api(ctx, `/agent/v1/secrets?project=${encodeURIComponent(desiredState.project)}&services=${encodeURIComponent(serviceNames.join(','))}`);
+    const currentSecretVersions = serviceSecretVersions(desiredState.compose, serviceNames, sec.versions || {});
+    const db = await agentDb(ctx.stateDir);
+    const previousRow = await db.get('SELECT version, secret_versions_json FROM applied_state WHERE project = ?', desiredState.project);
+    const previous = previousRow ? { version: previousRow.version, secretVersions: JSON.parse(previousRow.secret_versions_json) } : {};
+    const secretChangedServices = serviceNames.filter(service => JSON.stringify(previous.secretVersions?.[service] || {}) !== JSON.stringify(currentSecretVersions[service] || {}));
+    const sameDesiredVersion = previous.version === desiredState.version;
+    const nodeCompose = composeForNode(desiredState, ctx.nodeName, sec.secrets || {}, endpoints);
+    await fs.writeFile(path.join(dir, 'docker-compose.yml'), dumpYaml(nodeCompose));
+    await writeEnv(path.join(dir, '.env'), sec.secrets || {});
+    if (ctx.apply) {
+        for (const service of serviceNames) {
+            serviceStates[service].rolloutState = 'pulling';
+            await emit(service, 'pulling');
+        }
+        await ctx.docker(['compose', '-p', desiredState.project, 'pull'], { cwd: dir });
+        for (const service of serviceNames) {
+            serviceStates[service].rolloutState = 'starting';
+            await emit(service, 'starting');
+        }
+        await ctx.docker(['compose', '-p', desiredState.project, 'up', '-d', '--remove-orphans'], { cwd: dir });
+        if (sameDesiredVersion && secretChangedServices.length) {
+            for (const service of secretChangedServices)
+                await emit(service, 'secret_recreate', 'secret version changed; recreating service');
+            await ctx.docker(['compose', '-p', desiredState.project, 'up', '-d', '--no-deps', '--force-recreate', ...secretChangedServices], { cwd: dir });
+        }
+        for (const service of serviceNames) {
+            serviceStates[service].rolloutState = 'health_checking';
+            await emit(service, 'health_checking');
+            await waitForHealth(ctx, desiredState.project, service, desiredState.services[service]?.health, dir);
+            serviceStates[service].rolloutState = 'serving';
+            serviceStates[service].healthyAt = now();
+            await emit(service, 'serving');
+        }
+    }
+    else {
+        for (const service of serviceNames)
+            serviceStates[service].rolloutState = 'serving';
+    }
+    await db.run(`INSERT INTO applied_state(project, version, applied_at, service_states_json, secret_versions_json)
+     VALUES(?,?,?,?,?)
+     ON CONFLICT(project) DO UPDATE SET version=excluded.version, applied_at=excluded.applied_at,
+       service_states_json=excluded.service_states_json, secret_versions_json=excluded.secret_versions_json`, desiredState.project, desiredState.version, now(), JSON.stringify(serviceStates), JSON.stringify(currentSecretVersions));
+    return { project: desiredState.project, observedVersion: desiredState.version, health: 'serving', services: serviceNames, serviceStates };
+}
+/** Reports this node's WireGuard public key when control has not seen the current one yet. */
+export async function reportWgKey(ctx) {
+    const { publicKey } = await ensureWgKeys(ctx.stateDir);
+    if (await readReportedKey(ctx.stateDir) === publicKey)
+        return;
+    await api(ctx, '/agent/v1/wireguard/key', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ publicKey }) });
+    await writeReportedKey(ctx.stateDir, publicKey);
+}
+let lastNetworkError = '';
+async function networkStep(label, fn) {
+    try {
+        await fn();
+        lastNetworkError = '';
+    }
+    catch (e) {
+        const message = `${label}: ${errMessage(e)}`;
+        if (message !== lastNetworkError)
+            console.error(message);
+        lastNetworkError = message;
+    }
+}
+export async function pollOnce(ctx = defaultContext()) {
+    if (ctx.mesh)
+        await networkStep('wireguard key report failed', () => reportWgKey(ctx));
+    const work = await api(ctx, '/agent/v1/work');
+    // The mesh comes up first so cross-node service endpoints are routable when containers start.
+    if (ctx.mesh && work.network) {
+        const network = work.network;
+        await networkStep('wireguard reconcile failed', () => reconcileMesh(ctx.host ?? createHostRunner(), ctx.stateDir, network));
+    }
+    const projects = [];
+    for (const desired of work.desiredStates || (work.desiredState ? [work.desiredState] : [])) {
+        try {
+            projects.push(await reconcile(desired, ctx, work.serviceEndpoints?.[desired.project]));
+        }
+        catch (e) {
+            projects.push({ project: desired.project, observedVersion: desired.version, health: 'failed', error: errMessage(e) });
+        }
+    }
+    let ingress;
+    if (ctx.apply) {
+        const ingressCtx = { docker: ctx.docker, stateDir: ctx.stateDir, caddyImage: ctx.caddyImage };
+        if (work.ingress)
+            ingress = await reconcileIngress(ingressCtx, work.ingress);
+        else
+            await removeIngress(ingressCtx).catch(() => false);
+    }
+    const commandResults = [];
+    for (const command of work.commands || []) {
+        try {
+            commandResults.push(await executeCommand(command, ctx));
+        }
+        catch (e) {
+            commandResults.push({ commandId: command.id, state: 'failed', result: { error: errMessage(e) } });
+        }
+    }
+    const report = { node: ctx.nodeName, projects, commandResults };
+    if (ingress)
+        report.ingress = ingress;
+    await api(ctx, '/agent/v1/status', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(report) });
+    return projects;
+}
+const CREDS_FILE = () => path.join(STATE_DIR, 'agent.json');
+async function loadCreds() {
+    try {
+        return JSON.parse(await fs.readFile(CREDS_FILE(), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function saveCreds(creds) {
+    await ensureDir(STATE_DIR);
+    await fs.writeFile(CREDS_FILE(), JSON.stringify(creds), { mode: 0o600 });
+}
+async function readJoinKey() {
+    if (process.env.TUG_JOIN_KEY)
+        return process.env.TUG_JOIN_KEY.trim();
+    const file = process.env.TUG_JOIN_KEY_FILE;
+    if (file) {
+        try {
+            return (await fs.readFile(file, 'utf8')).trim();
+        }
+        catch (e) {
+            throw new Error(`cannot read TUG_JOIN_KEY_FILE ${file}: ${errMessage(e)}`, { cause: e });
+        }
+    }
+    return null;
+}
+function dockerLogin(registry, user, password) {
+    return new Promise((resolve, reject) => {
+        const p = spawn('docker', ['login', registry, '-u', user, '--password-stdin'], { stdio: ['pipe', 'ignore', 'pipe'] });
+        let err = '';
+        p.stderr.on('data', d => err += d);
+        p.on('error', reject);
+        p.on('close', code => code === 0 ? resolve() : reject(new Error(err.trim() || `exit ${code}`)));
+        p.stdin.write(password);
+        p.stdin.end();
+    });
+}
+async function enroll(joinKey) {
+    let decoded;
+    try {
+        decoded = JSON.parse(Buffer.from(joinKey, 'base64url').toString('utf8'));
+    }
+    catch (e) {
+        throw new Error('invalid TUG_JOIN_KEY (expected base64url-encoded JSON)', { cause: e });
+    }
+    if (!decoded.enrollToken)
+        throw new Error('join key is missing enrollToken');
+    const controlUrl = (!CONTROL_URL_FROM_ENV && decoded.controlUrl) ? decoded.controlUrl : CONTROL_URL;
+    // node's fetch reads NODE_EXTRA_CA_CERTS only at startup, so apply an embedded CA by
+    // persisting it and re-execing ourselves once with the env var set.
+    if (decoded.ca && !process.env.NODE_EXTRA_CA_CERTS) {
+        await ensureDir(STATE_DIR);
+        const caPath = path.join(STATE_DIR, 'control-ca.pem');
+        await fs.writeFile(caPath, decoded.ca);
+        const r = spawnSync(process.execPath, process.argv.slice(1), { stdio: 'inherit', env: { ...process.env, NODE_EXTRA_CA_CERTS: caPath } });
+        process.exit(r.status ?? 1);
+    }
+    console.log(`enrolling with ${controlUrl} as ${NODE_NAME}`);
+    const wgPublicKey = MESH ? (await ensureWgKeys(STATE_DIR)).publicKey : undefined;
+    const res = await fetch(`${controlUrl}/agent/v1/enroll`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ enrollToken: decoded.enrollToken, name: NODE_NAME, address: process.env.TUG_NODE_ADDRESS, publicAddress: process.env.TUG_NODE_PUBLIC_ADDRESS, wgPublicKey })
+    });
+    if (!res.ok)
+        throw new Error(`enroll failed: ${res.status} ${await res.text()}`);
+    const out = await res.json();
+    const creds = { agentToken: out.agentToken, nodeName: out.node?.name || NODE_NAME, controlUrl, registry: out.registry || null, registryToken: out.registryToken || null };
+    await saveCreds(creds);
+    if (wgPublicKey)
+        await writeReportedKey(STATE_DIR, wgPublicKey);
+    console.log(`enrolled as node ${creds.nodeName}`);
+    return creds;
+}
+// Establish durable credentials before polling: explicit env token (SSH/push install) wins,
+// then credentials persisted on the state volume, then a one-time enroll via the join key.
+export async function loadOrEnroll() {
+    let creds = TOKEN ? { agentToken: TOKEN, nodeName: NODE_NAME, controlUrl: CONTROL_URL } : await loadCreds();
+    if (!creds) {
+        const joinKey = await readJoinKey();
+        if (!joinKey)
+            throw new Error('no TUG_AGENT_TOKEN, no persisted credentials, and no TUG_JOIN_KEY to enroll with');
+        creds = await enroll(joinKey);
+    }
+    TOKEN = creds.agentToken;
+    NODE_NAME = creds.nodeName || NODE_NAME;
+    if (!CONTROL_URL_FROM_ENV && creds.controlUrl)
+        CONTROL_URL = creds.controlUrl;
+    if (APPLY && creds.registry && creds.registryToken) {
+        try {
+            await dockerLogin(creds.registry, NODE_NAME, creds.registryToken);
+        }
+        catch (e) {
+            console.error(`registry login failed (pulls from ${creds.registry} may fail): ${errMessage(e)}`);
+        }
+    }
+    return creds;
+}
+export async function main() {
+    await loadOrEnroll();
+    console.log(`tug-agent node=${NODE_NAME} control=${CONTROL_URL} apply=${APPLY}`);
+    for (;;) {
+        try {
+            await pollOnce();
+        }
+        catch (e) {
+            console.error(errMessage(e));
+        }
+        await new Promise(r => setTimeout(r, INTERVAL));
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    main();

package/dist/build.d.ts

@@ -0,0 +1,22 @@
+export interface RunResult {
+    out: string;
+    err: string;
+}
+export interface RunOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface BuildSpec {
+    context?: string;
+    dockerfile?: string;
+}
+export declare function run(cmd: string, args: string[], opts?: RunOptions): Promise<RunResult>;
+export declare function unpackContext(tarball: string, dest: string): Promise<void>;
+export interface BuildAndPushOptions {
+    contextDir: string;
+    service: string;
+    buildSpec: string | BuildSpec;
+    imageRef: string;
+    push?: boolean;
+}
+export declare function buildAndPush({ contextDir, service, buildSpec, imageRef, push }: BuildAndPushOptions): Promise<void>;

package/dist/build.js

@@ -0,0 +1,29 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import * as tar from 'tar';
+import { ensureDir, exists } from "./util.js";
+export function run(cmd, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const p = spawn(cmd, args, { ...opts, stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '', err = '';
+        p.stdout.on('data', d => out += d);
+        p.stderr.on('data', d => err += d);
+        p.on('close', code => code === 0 ? resolve({ out, err }) : reject(new Error(`${cmd} ${args.join(' ')} failed (${code})\n${out}\n${err}`)));
+    });
+}
+export async function unpackContext(tarball, dest) {
+    await fs.rm(dest, { recursive: true, force: true });
+    await ensureDir(dest);
+    await tar.x({ file: tarball, cwd: dest });
+}
+export async function buildAndPush({ contextDir, service, buildSpec, imageRef, push = true }) {
+    const buildPath = typeof buildSpec === 'string' ? buildSpec : buildSpec?.context || '.';
+    const dockerfile = typeof buildSpec === 'object' && buildSpec.dockerfile ? ['-f', path.join(contextDir, buildPath, buildSpec.dockerfile)] : [];
+    const fullContext = path.resolve(contextDir, buildPath);
+    if (!(await exists(fullContext)))
+        throw new Error(`build context not found for ${service}: ${buildPath}`);
+    await run('docker', ['build', ...dockerfile, '-t', imageRef, fullContext]);
+    if (push)
+        await run('docker', ['push', imageRef]);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};