@wpelevator/tug 0.0.0-stage → 0.1.0

package/dist/mesh.js

@@ -0,0 +1,183 @@
+// WireGuard mesh: overlay IP allocation and key handling (control), config rendering, peer diffing
+// and the idempotent `wg0` reconcile (agent). All shell-outs go through an injectable HostRunner.
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { ensureDir, errMessage } from "./util.js";
+/** Default mesh CIDR. Chosen to avoid the integration subnet 10.89.240.0/24, Docker's 172.16/12 and common home/VPN ranges. */
+export const DEFAULT_MESH_CIDR = '10.210.0.0/16';
+export const DEFAULT_WG_PORT = 51820;
+export const WG_INTERFACE = 'wg0';
+export const WG_KEEPALIVE = 25;
+/** Below the usual 1500 path MTU minus WireGuard's 60 byte overhead (80 with IPv6 endpoints). */
+const WG_MTU = 1420;
+// ---- Keys --------------------------------------------------------------------------------------
+export const WG_KEY_RE = /^[A-Za-z0-9+/]{43}=$/;
+export const isWgKey = (value) => typeof value === 'string' && WG_KEY_RE.test(value);
+const PKCS8_X25519_PREFIX = Buffer.from('302e020100300506032b656e04220420', 'hex');
+/** Public key for a base64 private key (X25519, as `wg pubkey` computes it). */
+export function publicKeyFromPrivate(privateKey) {
+    const key = crypto.createPrivateKey({ key: Buffer.concat([PKCS8_X25519_PREFIX, Buffer.from(privateKey, 'base64')]), format: 'der', type: 'pkcs8' });
+    const jwk = crypto.createPublicKey(key).export({ format: 'jwk' });
+    return Buffer.from(jwk.x, 'base64url').toString('base64');
+}
+export function generateWgKeyPair() {
+    const jwk = crypto.generateKeyPairSync('x25519').privateKey.export({ format: 'jwk' });
+    const privateKey = Buffer.from(jwk.d, 'base64url').toString('base64');
+    return { privateKey, publicKey: Buffer.from(jwk.x, 'base64url').toString('base64') };
+}
+const wgDir = (stateDir) => path.join(stateDir, 'wireguard');
+/** Loads the node's keypair from the state dir, generating it on first use. The private key never leaves this directory. */
+export async function ensureWgKeys(stateDir) {
+    const file = path.join(wgDir(stateDir), 'private.key');
+    try {
+        const privateKey = (await fs.readFile(file, 'utf8')).trim();
+        if (isWgKey(privateKey))
+            return { privateKey, publicKey: publicKeyFromPrivate(privateKey) };
+    }
+    catch { /* first boot */ }
+    return rotateWgKeys(stateDir);
+}
+export async function rotateWgKeys(stateDir) {
+    const pair = generateWgKeyPair();
+    await ensureDir(wgDir(stateDir));
+    await fs.writeFile(path.join(wgDir(stateDir), 'private.key'), `${pair.privateKey}\n`, { mode: 0o600 });
+    return pair;
+}
+/** The public key control last accepted, so the agent only re-reports when it changed. */
+export async function readReportedKey(stateDir) {
+    try {
+        return (await fs.readFile(path.join(wgDir(stateDir), 'reported.pub'), 'utf8')).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeReportedKey(stateDir, publicKey) {
+    await ensureDir(wgDir(stateDir));
+    await fs.writeFile(path.join(wgDir(stateDir), 'reported.pub'), `${publicKey}\n`);
+}
+// ---- Overlay addressing (control) --------------------------------------------------------------
+export function ipToInt(ip) {
+    const parts = ip.split('.').map(Number);
+    if (parts.length !== 4 || parts.some(p => !Number.isInteger(p) || p < 0 || p > 255))
+        throw new Error(`invalid IPv4 address ${ip}`);
+    return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
+}
+export const intToIp = (n) => [n >>> 24, (n >>> 16) & 255, (n >>> 8) & 255, n & 255].join('.');
+export function parseCidr(cidr) {
+    const [ip, bits, extra] = cidr.split('/');
+    const prefix = Number(bits);
+    if (extra !== undefined || bits === undefined || !Number.isInteger(prefix) || prefix < 8 || prefix > 29)
+        throw new Error(`invalid mesh CIDR ${cidr} (IPv4, prefix /8 to /29)`);
+    const size = 2 ** (32 - prefix);
+    const base = (ipToInt(ip) & ~(size - 1)) >>> 0;
+    return { base, prefix, size };
+}
+/** First free host address in the mesh CIDR (never the network or broadcast address). */
+export function allocateOverlayIp(cidr, used) {
+    const { base, size } = parseCidr(cidr);
+    const taken = new Set([...used].map(ipToInt));
+    for (let offset = 1; offset < size - 1; offset++) {
+        if (!taken.has(base + offset))
+            return intToIp(base + offset);
+    }
+    throw new Error(`mesh CIDR ${cidr} has no free overlay addresses`);
+}
+/** `host:port`, adding the WireGuard port when the public address has none. IPv6 literals are bracketed. */
+export function wgEndpoint(publicAddress, port) {
+    const addr = publicAddress?.trim();
+    if (!addr)
+        return undefined;
+    if (addr.startsWith('['))
+        return /\]:\d+$/.test(addr) ? addr : `${addr}:${port}`;
+    if (addr.includes(':') && addr.split(':').length > 2)
+        return `[${addr}]:${port}`;
+    return /:\d+$/.test(addr) ? addr : `${addr}:${port}`;
+}
+// ---- Config rendering and diffing (agent) ------------------------------------------------------
+/** `wg syncconf` input: interface key and port plus peers (no wg-quick-only keys such as Address). */
+export function renderWgConfig(privateKey, listenPort, peers) {
+    const lines = ['[Interface]', `PrivateKey = ${privateKey}`, `ListenPort = ${listenPort}`];
+    for (const peer of [...peers].sort((a, b) => a.publicKey.localeCompare(b.publicKey))) {
+        lines.push('', '[Peer]', `PublicKey = ${peer.publicKey}`, `AllowedIPs = ${[...peer.allowedIps].sort().join(', ')}`);
+        if (peer.endpoint)
+            lines.push(`Endpoint = ${peer.endpoint}`);
+        lines.push(`PersistentKeepalive = ${peer.persistentKeepalive}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** Parses `wg show <iface> dump` (tab separated; first line is the interface, then one line per peer). */
+export function parseWgDump(dump) {
+    const [header, ...rest] = dump.split('\n').filter(Boolean);
+    const h = (header || '').split('\t');
+    return {
+        publicKey: h[1] || '',
+        listenPort: Number(h[2]) || 0,
+        peers: rest.map(line => {
+            const f = line.split('\t');
+            return {
+                publicKey: f[0],
+                endpoint: f[2] && f[2] !== '(none)' ? f[2] : undefined,
+                allowedIps: f[3] && f[3] !== '(none)' ? f[3].split(',') : [],
+                keepalive: f[7] && f[7] !== 'off' ? Number(f[7]) : 0
+            };
+        })
+    };
+}
+/** Compares desired peers with what `wg` reports. A desired endpoint is authoritative; a peer without one keeps whatever it roamed to. */
+export function diffPeers(desired, applied) {
+    const have = new Map(applied.map(p => [p.publicKey, p]));
+    const want = new Map(desired.map(p => [p.publicKey, p]));
+    const sameSet = (a, b) => a.length === b.length && [...a].sort().every((v, i) => v === [...b].sort()[i]);
+    const diff = { add: [], remove: [], update: [] };
+    for (const [key, peer] of want) {
+        const cur = have.get(key);
+        if (!cur)
+            diff.add.push(key);
+        else if (!sameSet(peer.allowedIps, cur.allowedIps) || peer.persistentKeepalive !== cur.keepalive || (peer.endpoint && peer.endpoint !== cur.endpoint))
+            diff.update.push(key);
+    }
+    for (const key of have.keys())
+        if (!want.has(key))
+            diff.remove.push(key);
+    return diff;
+}
+/**
+ * Brings `wg0` in line with the control-provided network block without tearing it down: creates the
+ * link and address only when missing, and calls `wg syncconf` only when keys, port or peers differ.
+ */
+export async function reconcileMesh(host, stateDir, network) {
+    const { privateKey, publicKey } = await ensureWgKeys(stateDir);
+    const iface = network.interface;
+    const prefix = parseCidr(network.cidr).prefix;
+    let created = false;
+    try {
+        await host('ip', ['link', 'show', iface]);
+    }
+    catch {
+        await host('ip', ['link', 'add', iface, 'type', 'wireguard']);
+        created = true;
+    }
+    await host('ip', ['address', 'replace', `${network.overlayIp}/${prefix}`, 'dev', iface]);
+    if (created)
+        await host('ip', ['link', 'set', 'mtu', String(WG_MTU), 'up', 'dev', iface]);
+    let applied = { publicKey: '', listenPort: 0, peers: [] };
+    if (!created) {
+        try {
+            applied = parseWgDump((await host('wg', ['show', iface, 'dump'])).out);
+        }
+        catch (e) {
+            throw new Error(`wg show ${iface} failed: ${errMessage(e)}`, { cause: e });
+        }
+    }
+    const diff = diffPeers(network.peers, applied.peers);
+    const synced = created || applied.publicKey !== publicKey || applied.listenPort !== network.listenPort || diff.add.length + diff.remove.length + diff.update.length > 0;
+    if (synced) {
+        const file = path.join(wgDir(stateDir), `${iface}.conf`);
+        await ensureDir(wgDir(stateDir));
+        await fs.writeFile(file, renderWgConfig(privateKey, network.listenPort, network.peers), { mode: 0o600 });
+        await host('wg', ['syncconf', iface, file]);
+    }
+    return { created, synced, diff };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,282 @@
+export interface Placement {
+    nodes?: string[];
+}
+export interface HealthCheck {
+    type: 'docker' | 'tcp' | 'http';
+    port?: number | string;
+    path?: string;
+    /** Duration: number (ms) or "2s" / "500ms" / "1m". */
+    interval?: string | number;
+    timeout?: string | number;
+    retries?: number | string;
+}
+export type IngressTls = 'auto' | 'custom' | 'off';
+/** `x-tug.ingress`: publish a service on a hostname through the managed Caddy edge. */
+export interface IngressSpec {
+    host: string;
+    /** Container port (or the host port) of the service; must be published in the service's `ports`. */
+    port: number;
+    /** `auto` (ACME, default), `custom` (cert/key from project secrets) or `off` (plain HTTP). */
+    tls?: IngressTls;
+    /** Names of project secrets holding the PEM certificate chain and private key; required for `tls: custom`. */
+    cert?: string;
+    key?: string;
+}
+/** The `x-tug` extension on a Compose service. */
+export interface ServiceExtension {
+    placement?: Placement;
+    replicas?: number;
+    health?: HealthCheck;
+    ingress?: IngressSpec;
+}
+/** The `x-tug` extension on a top-level Compose volume. */
+export interface VolumeExtension {
+    type?: string;
+    driver?: string;
+    persistent?: boolean;
+    placement?: Placement;
+}
+export type BuildConfig = string | {
+    context?: string;
+    dockerfile?: string;
+    [key: string]: unknown;
+};
+export type ComposeVolumeMount = string | {
+    source?: string;
+    [key: string]: unknown;
+};
+export interface ComposeService {
+    image?: string;
+    build?: BuildConfig;
+    environment?: Record<string, unknown> | string[];
+    volumes?: ComposeVolumeMount[];
+    env_file?: string | string[];
+    container_name?: string;
+    deploy?: unknown;
+    ports?: (string | number | {
+        target?: number;
+        published?: number | string;
+        [key: string]: unknown;
+    })[];
+    extra_hosts?: string[] | Record<string, string>;
+    'x-tug'?: ServiceExtension;
+    [key: string]: unknown;
+}
+export interface ComposeVolume {
+    'x-tug'?: VolumeExtension;
+    [key: string]: unknown;
+}
+export interface ComposeFile {
+    services: Record<string, ComposeService>;
+    volumes?: Record<string, ComposeVolume>;
+    [key: string]: unknown;
+}
+export interface ServiceSpec {
+    image?: string;
+    build: BuildConfig | null;
+    placement: Placement;
+    replicas: number;
+    health: HealthCheck | null;
+}
+export interface DesiredState {
+    project: string;
+    version: string;
+    services: Record<string, ServiceSpec>;
+    compose: ComposeFile;
+}
+/** Deployment states during which a project is considered busy. */
+export declare const ACTIVE_DEPLOYMENT_STATES: readonly ["uploading", "building", "pending_dependencies", "rolling_out"];
+/** Deployment states a CLI wait loop stops on. */
+export declare const TERMINAL_DEPLOYMENT_STATES: readonly ["succeeded", "failed", "build_failed", "cancelled"];
+export type DeploymentState = (typeof ACTIVE_DEPLOYMENT_STATES)[number] | (typeof TERMINAL_DEPLOYMENT_STATES)[number];
+export type CommandType = 'diagnostics.run' | 'service.restart' | 'logs.fetch' | 'volume.delete' | 'wg.rotate-key';
+/** A `commands` table row as delivered in `GET /agent/v1/work`. */
+export interface Command {
+    id: string;
+    node_id?: string;
+    project_id?: string | null;
+    type: CommandType | (string & {});
+    state?: string;
+    payload_json?: string | null;
+    /** Already-parsed payload; takes effect only when `payload_json` is not a string. */
+    payload?: Record<string, unknown>;
+    result_json?: string | null;
+    attempts?: number;
+    run_after?: string | null;
+    deadline?: string | null;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface DiagnosticCheck {
+    name: string;
+    ok: boolean;
+    stdout?: string;
+    stderr?: string;
+    error?: string;
+}
+export type CommandResultPayload = {
+    checks: DiagnosticCheck[];
+    node: string;
+} | {
+    project: string;
+    service: string;
+    restarted: true;
+} | {
+    stdout: string;
+    stderr: string;
+} | {
+    project: string;
+    volume: string;
+    deleted: true;
+} | {
+    publicKey: string;
+} | {
+    error: string;
+};
+export interface CommandResult {
+    commandId: string;
+    state: 'succeeded' | 'failed';
+    result: CommandResultPayload;
+}
+export interface WorkResponse {
+    serverTime: string;
+    nodeId: string;
+    desiredStates: DesiredState[];
+    commands: Command[];
+    /** WireGuard mesh config for this node; present only when the mesh is enabled on control. */
+    network?: NetworkConfig;
+    /** Healthy cross-node endpoints per project and service; present only when service DNS is enabled. */
+    serviceEndpoints?: ServiceEndpoints;
+    /** Edge proxy config; present only for nodes marked as ingress nodes. */
+    ingress?: IngressWork;
+}
+export interface WgPeer {
+    node: string;
+    publicKey: string;
+    /** `host:port` the peer can be dialed on; absent for nodes behind NAT (they dial out instead). */
+    endpoint?: string;
+    allowedIps: string[];
+    persistentKeepalive: number;
+}
+/** The `network` block of `GET /agent/v1/work`: everything an agent needs to reconcile `wg0`. */
+export interface NetworkConfig {
+    interface: string;
+    /** This node's overlay address, e.g. `10.210.0.2`. */
+    overlayIp: string;
+    /** Mesh CIDR, e.g. `10.210.0.0/16`; `overlayIp` is assigned to `wg0` with this prefix length. */
+    cidr: string;
+    listenPort: number;
+    peers: WgPeer[];
+}
+/** Body of `POST /agent/v1/wireguard/key` (also accepted as `wgPublicKey` on register and enroll). */
+export interface WgKeyRequest {
+    publicKey: string;
+}
+export interface ServiceEndpoint {
+    node: string;
+    address: string;
+}
+/** project -> service -> endpoints of nodes whose copy of the service reports `serving`. */
+export type ServiceEndpoints = Record<string, Record<string, ServiceEndpoint[]>>;
+export interface IngressRoute {
+    project: string;
+    service: string;
+    host: string;
+    tls: IngressTls;
+    /** `host:port` upstreams, one per serving node (`127.0.0.1` for the ingress node itself). */
+    upstreams: string[];
+}
+/** Edge config rendered by control for one ingress node. */
+export interface IngressWork {
+    caddyfile: string;
+    /** Extra files for the Caddy container, keyed by path relative to `/etc/caddy` (custom TLS certs and keys). */
+    files: Record<string, string>;
+    routes: IngressRoute[];
+    /** Routes control had to skip (no serving upstream, missing TLS secret), for operator visibility. */
+    warnings: string[];
+}
+export interface IngressStatus {
+    state: 'serving' | 'failed';
+    /** sha256 of the applied Caddyfile and files. */
+    configHash: string;
+    routes: number;
+    error?: string;
+}
+export type ProjectHealth = 'serving' | 'skipped' | 'failed';
+export type RolloutState = 'pending' | 'pulling' | 'starting' | 'health_checking' | 'serving';
+export interface ServiceState {
+    rolloutState: RolloutState;
+    image?: string;
+    healthyAt?: string;
+}
+export interface ProjectStatus {
+    project: string;
+    observedVersion: string;
+    health: ProjectHealth;
+    services?: string[];
+    serviceStates?: Record<string, ServiceState>;
+    error?: string;
+}
+export interface StatusReport {
+    node: string;
+    projects: ProjectStatus[];
+    commandResults: CommandResult[];
+    ingress?: IngressStatus;
+}
+export interface SecretsResponse {
+    secrets: Record<string, string>;
+    versions: Record<string, number>;
+}
+export interface AgentEvent {
+    projectId?: string | null;
+    deploymentId?: string | null;
+    level?: string;
+    type?: string;
+    message?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface NodeInfo {
+    id: string;
+    name: string;
+    address: string | null;
+    public_address: string | null;
+    overlay_ip?: string | null;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+/** Response of `POST /api/v1/nodes/register`. */
+export interface RegisterResponse {
+    node: NodeInfo;
+    agentToken: string;
+    registryToken: string;
+}
+/** Body of `POST /agent/v1/enroll`. */
+export interface EnrollRequest {
+    enrollToken?: string;
+    name?: string;
+    address?: string;
+    publicAddress?: string;
+    /** Base64 WireGuard public key; the private key never leaves the node. */
+    wgPublicKey?: string;
+}
+/** Response of `POST /agent/v1/enroll`. */
+export interface EnrollResponse extends RegisterResponse {
+    registry: string;
+}
+/** Response of `POST /api/v1/nodes/enroll-token`. */
+export interface EnrollTokenResponse {
+    enrollToken: string;
+    name: string | null;
+    usesRemaining: number;
+    expiresAt: string;
+    registry: string;
+}
+/** The base64url-encoded JSON payload of TUG_JOIN_KEY. */
+export interface JoinKey {
+    v: number;
+    controlUrl?: string;
+    enrollToken: string;
+    /** PEM CA certificate to trust for a private/self-signed control plane. */
+    ca?: string;
+}

package/dist/protocol.js

@@ -0,0 +1,8 @@
+// Single source of truth for everything that crosses the control <-> agent boundary and for the
+// desired-state shape persisted in `desired_states.state_json`. Types plus a few shared constants;
+// control.ts, agent.ts, compose.ts and cli.ts all import from here.
+// ---- Deployments -------------------------------------------------------------------------------
+/** Deployment states during which a project is considered busy. */
+export const ACTIVE_DEPLOYMENT_STATES = ['uploading', 'building', 'pending_dependencies', 'rolling_out'];
+/** Deployment states a CLI wait loop stops on. */
+export const TERMINAL_DEPLOYMENT_STATES = ['succeeded', 'failed', 'build_failed', 'cancelled'];

package/dist/runners.d.ts

@@ -0,0 +1,12 @@
+import type { RunResult } from './build.ts';
+export type DockerRunner = (args: string[], opts?: {
+    cwd?: string;
+}) => Promise<RunResult>;
+export type HttpClient = typeof fetch;
+/** Default runner: `docker <args>` via the shared `run()` helper. */
+export declare function createDockerRunner(): DockerRunner;
+/** Runs a host binary (`wg`, `ip`); rejects on a non-zero exit like the docker runner. */
+export type HostRunner = (cmd: string, args: string[], opts?: {
+    cwd?: string;
+}) => Promise<RunResult>;
+export declare function createHostRunner(): HostRunner;

package/dist/runners.js

@@ -0,0 +1,10 @@
+// Injectable seams for the agent's side effects so rollout/health/secret logic can be unit-tested
+// without a real Docker daemon or control plane.
+import { run } from "./build.js";
+/** Default runner: `docker <args>` via the shared `run()` helper. */
+export function createDockerRunner() {
+    return (args, opts) => run('docker', args, opts);
+}
+export function createHostRunner() {
+    return (cmd, args, opts) => run(cmd, args, opts);
+}

package/dist/secrets.d.ts

@@ -0,0 +1,3 @@
+export declare function loadOrCreateMasterKey(file: string): Promise<string>;
+export declare function encrypt(value: unknown, masterKey: string): string;
+export declare function decrypt(payload: string, masterKey: string): string;

package/dist/secrets.js

@@ -0,0 +1,29 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import { ensureDir, exists } from "./util.js";
+import path from 'node:path';
+export async function loadOrCreateMasterKey(file) {
+    await ensureDir(path.dirname(file));
+    if (await exists(file))
+        return (await fs.readFile(file, 'utf8')).trim();
+    const key = crypto.randomBytes(32).toString('base64');
+    await fs.writeFile(file, key, { mode: 0o600 });
+    return key;
+}
+function keyBytes(key) { return crypto.createHash('sha256').update(key).digest(); }
+export function encrypt(value, masterKey) {
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', keyBytes(masterKey), iv);
+    const encrypted = Buffer.concat([cipher.update(String(value), 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, encrypted]).toString('base64');
+}
+export function decrypt(payload, masterKey) {
+    const buf = Buffer.from(payload, 'base64');
+    const iv = buf.subarray(0, 12);
+    const tag = buf.subarray(12, 28);
+    const data = buf.subarray(28);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', keyBytes(masterKey), iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8');
+}

package/dist/templates/agent.env

@@ -0,0 +1,6 @@
+TUG_CONTROL_URL={{CONTROL_URL}}
+TUG_NODE_NAME={{NODE_NAME}}
+TUG_AGENT_TOKEN={{AGENT_TOKEN}}
+TUG_STATE_DIR=/var/lib/tug
+TUG_APPLY=true
+TUG_POLL_INTERVAL_MS=5000

package/dist/templates/control-compose.yml

@@ -0,0 +1,18 @@
+services:
+  control:
+    image: {{IMAGE}}
+    restart: unless-stopped
+    command: control
+    environment:
+      PORT: 8080
+      TUG_DATA_DIR: /data
+      TUG_OPERATOR_TOKEN: {{OPERATOR_TOKEN}}
+      TUG_REGISTRY: {{REGISTRY_HOST}}
+      TUG_REGISTRY_AUTH_PATH: {{REGISTRY_AUTH_PATH}}
+      TUG_REGISTRY_CONTAINER: {{REGISTRY_CONTAINER}}
+    ports:
+      - "{{PORT}}:8080"
+    volumes:
+      - /var/lib/tug-control:/data
+      - /var/lib/tug-registry-auth:/registry-auth
+      - /var/run/docker.sock:/var/run/docker.sock

package/dist/templates/control-install.sh

@@ -0,0 +1,7 @@
+set -euo pipefail
+mkdir -p /opt/tug-control /var/lib/tug-control
+cat > /opt/tug-control/docker-compose.yml <<'YAML'
+{{COMPOSE}}YAML
+docker compose -f /opt/tug-control/docker-compose.yml up -d
+install -m 0600 /dev/null /var/lib/tug-control/operator.token
+printf %s {{OPERATOR_TOKEN_SH}} > /var/lib/tug-control/operator.token

package/dist/templates/node-install.sh

@@ -0,0 +1,8 @@
+set -euo pipefail
+mkdir -p /etc/tug /var/lib/tug
+cat > /etc/tug/agent.env <<'ENV'
+{{ENV}}ENV
+chmod 0600 /etc/tug/agent.env
+{{DOCKER_LOGIN}}
+docker rm -f tug-agent >/dev/null 2>&1 || true
+docker run -d --name tug-agent --restart unless-stopped --env-file /etc/tug/agent.env {{RUN_FLAGS}}-v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/tug:/var/lib/tug {{IMAGE_SH}} agent

package/dist/util.d.ts

@@ -0,0 +1,12 @@
+export declare const now: () => string;
+export declare const id: (prefix: string) => string;
+export declare const token: (prefix?: string) => string;
+export declare const hashToken: (value: string) => string;
+export declare function ensureDir(dir: string): Promise<void>;
+export declare function exists(p: string): Promise<boolean>;
+export declare function requireEnv(name: string, fallback?: string): string;
+export declare function projectRoot(): string;
+export declare function safeJoin(base: string, child: string): string;
+export declare function renderTemplate(str: string, vars: Record<string, string>): string;
+export declare function loadTemplate(templatesDir: string, name: string, vars: Record<string, string>): Promise<string>;
+export declare const errMessage: (e: unknown) => string;

package/dist/util.js

@@ -0,0 +1,24 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export const now = () => new Date().toISOString();
+export const id = (prefix) => `${prefix}_${crypto.randomBytes(8).toString('hex')}`;
+export const token = (prefix = 'tug') => `${prefix}_${crypto.randomBytes(24).toString('base64url')}`;
+export const hashToken = (value) => crypto.createHash('sha256').update(value).digest('hex');
+export async function ensureDir(dir) { await fs.mkdir(dir, { recursive: true }); }
+export async function exists(p) { try {
+    await fs.access(p);
+    return true;
+}
+catch {
+    return false;
+} }
+export function requireEnv(name, fallback) { const v = process.env[name] ?? fallback; if (!v)
+    throw new Error(`Missing ${name}`); return v; }
+export function projectRoot() { return process.cwd(); }
+export function safeJoin(base, child) { const out = path.resolve(base, child); if (!out.startsWith(path.resolve(base)))
+    throw new Error('unsafe path'); return out; }
+export function renderTemplate(str, vars) { return str.replace(/\{\{(\w+)\}\}/g, (m, key) => { if (!(key in vars))
+    throw new Error(`missing template var ${key}`); return vars[key]; }); }
+export async function loadTemplate(templatesDir, name, vars) { return renderTemplate(await fs.readFile(path.join(templatesDir, name), 'utf8'), vars); }
+export const errMessage = (e) => (e instanceof Error ? e.message : String(e));