@wpelevator/tug 0.0.0 → 0.1.0

package/dist/db.d.ts

@@ -0,0 +1,115 @@
+import sqlite3 from 'sqlite3';
+import type { Database } from 'sqlite';
+export type Db = Database<sqlite3.Database, sqlite3.Statement>;
+export interface ProjectRow {
+    id: string;
+    name: string;
+    current_deployment_id: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface NodeRow {
+    id: string;
+    name: string;
+    address: string | null;
+    public_address: string | null;
+    overlay_ip: string | null;
+    ingress: number;
+    ingress_status_json: string | null;
+    status: string;
+    agent_token_hash: string | null;
+    registry_token_hash: string | null;
+    last_seen_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface WgPeerRow {
+    node_id: string;
+    public_key: string;
+    overlay_ip: string;
+    endpoint: string | null;
+    allowed_ips: string;
+    updated_at: string;
+}
+export interface EnrollTokenRow {
+    token_hash: string;
+    name: string | null;
+    uses_remaining: number;
+    expires_at: string;
+    created_at: string;
+}
+export interface DeploymentRow {
+    id: string;
+    project_id: string;
+    version: string;
+    state: string;
+    created_at: string;
+    updated_at: string;
+    error_message: string | null;
+}
+export interface DesiredStateRow {
+    id: string;
+    project_id: string;
+    deployment_id: string;
+    version: string;
+    state_json: string;
+    created_at: string;
+}
+export interface NodeStatusRow {
+    id: string;
+    node_id: string;
+    project_id: string;
+    observed_version: string;
+    status_json: string;
+    health: string;
+    updated_at: string;
+}
+export interface SecretRow {
+    id: string;
+    project_id: string;
+    name: string;
+    encrypted_value: string;
+    version: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface VolumeRow {
+    id: string;
+    project_id: string;
+    name: string;
+    type: string;
+    driver: string | null;
+    node_id: string | null;
+    config_json: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface CommandRow {
+    id: string;
+    node_id: string;
+    project_id: string | null;
+    type: string;
+    state: string;
+    payload_json: string | null;
+    result_json: string | null;
+    attempts: number;
+    run_after: string | null;
+    deadline: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface LockRow {
+    name: string;
+    owner: string;
+    expires_at: string;
+    created_at: string;
+}
+export interface AppliedStateRow {
+    project: string;
+    version: string;
+    applied_at: string;
+    service_states_json: string;
+    secret_versions_json: string;
+}
+export declare function openDb(filename: string): Promise<Db>;
+export declare function openAgentDb(filename: string): Promise<Db>;

package/dist/db.js

@@ -0,0 +1,48 @@
+import sqlite3 from 'sqlite3';
+import { open } from 'sqlite';
+import path from 'node:path';
+import { ensureDir, now } from "./util.js";
+export async function openDb(filename) {
+    await ensureDir(path.dirname(filename));
+    const db = await open({ filename, driver: sqlite3.Database });
+    await db.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;');
+    await migrate(db);
+    return db;
+}
+export async function openAgentDb(filename) {
+    await ensureDir(path.dirname(filename));
+    const db = await open({ filename, driver: sqlite3.Database });
+    await db.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;');
+    await db.exec(`
+CREATE TABLE IF NOT EXISTS applied_state(
+  project TEXT PRIMARY KEY,
+  version TEXT,
+  applied_at TEXT,
+  service_states_json TEXT,
+  secret_versions_json TEXT
+);
+`);
+    return db;
+}
+async function migrate(db) {
+    await db.exec(`
+CREATE TABLE IF NOT EXISTS meta(key TEXT PRIMARY KEY, value TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS projects(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT NULL, current_deployment_id TEXT, created_at TEXT, updated_at TEXT);
+CREATE TABLE IF NOT EXISTS nodes(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT NULL, address TEXT, public_address TEXT, overlay_ip TEXT UNIQUE, ingress INTEGER NOT NULL DEFAULT 0, ingress_status_json TEXT, status TEXT, agent_token_hash TEXT, registry_token_hash TEXT, last_seen_at TEXT, created_at TEXT, updated_at TEXT);
+CREATE TABLE IF NOT EXISTS wg_peers(node_id TEXT PRIMARY KEY, public_key TEXT NOT NULL UNIQUE, overlay_ip TEXT NOT NULL, endpoint TEXT, allowed_ips TEXT NOT NULL, updated_at TEXT);
+CREATE TABLE IF NOT EXISTS enroll_tokens(token_hash TEXT PRIMARY KEY, name TEXT, uses_remaining INTEGER, expires_at TEXT, created_at TEXT);
+CREATE TABLE IF NOT EXISTS deployments(id TEXT PRIMARY KEY, project_id TEXT, version TEXT, state TEXT, created_at TEXT, updated_at TEXT, error_message TEXT);
+CREATE TABLE IF NOT EXISTS desired_states(id TEXT PRIMARY KEY, project_id TEXT, deployment_id TEXT, version TEXT, state_json TEXT, created_at TEXT);
+CREATE TABLE IF NOT EXISTS node_statuses(id TEXT PRIMARY KEY, node_id TEXT, project_id TEXT, observed_version TEXT, status_json TEXT, health TEXT, updated_at TEXT, UNIQUE(node_id, project_id));
+CREATE TABLE IF NOT EXISTS builds(id TEXT PRIMARY KEY, project_id TEXT, deployment_id TEXT, service TEXT, source_hash TEXT, image_ref TEXT, state TEXT, logs_path TEXT, created_at TEXT, updated_at TEXT);
+CREATE TABLE IF NOT EXISTS secrets(id TEXT PRIMARY KEY, project_id TEXT, name TEXT, encrypted_value TEXT, version INTEGER, created_at TEXT, updated_at TEXT, UNIQUE(project_id, name));
+CREATE TABLE IF NOT EXISTS volumes(id TEXT PRIMARY KEY, project_id TEXT, name TEXT, type TEXT, driver TEXT, node_id TEXT, config_json TEXT, created_at TEXT, updated_at TEXT, UNIQUE(project_id, name));
+CREATE TABLE IF NOT EXISTS backups(id TEXT PRIMARY KEY, project_id TEXT, target TEXT, node_id TEXT, state TEXT, artifact_ref TEXT, metadata_json TEXT, created_at TEXT, completed_at TEXT);
+CREATE TABLE IF NOT EXISTS commands(id TEXT PRIMARY KEY, node_id TEXT, project_id TEXT, type TEXT, state TEXT, payload_json TEXT, result_json TEXT, attempts INTEGER DEFAULT 0, run_after TEXT, deadline TEXT, created_at TEXT, updated_at TEXT);
+CREATE TABLE IF NOT EXISTS events(id TEXT PRIMARY KEY, project_id TEXT, deployment_id TEXT, node_id TEXT, level TEXT, type TEXT, message TEXT, metadata_json TEXT, created_at TEXT);
+CREATE TABLE IF NOT EXISTS locks(name TEXT PRIMARY KEY, owner TEXT, expires_at TEXT, created_at TEXT);
+`);
+    const row = await db.get('SELECT value FROM meta WHERE key = ?', 'schema_created_at');
+    if (!row)
+        await db.run('INSERT INTO meta(key,value) VALUES(?,?)', 'schema_created_at', now());
+}

package/dist/image.d.ts

@@ -0,0 +1,9 @@
+/** Registry repository the release workflow publishes the Tug image to. */
+export declare const IMAGE_REPOSITORY = "ghcr.io/wpelevator/tug";
+/** Tag `--build-local-image` builds and ships when no `--image` is given; for development against a checkout. */
+export declare const LOCAL_IMAGE = "tug:local";
+export declare function packageVersion(): string;
+/** The published image matching this CLI's version, so the CLI and the agents it installs stay in step. */
+export declare function defaultImage(version?: string): string;
+/** An explicit `--image` always wins; otherwise a locally built image is `tug:local` and anything else is the published image. */
+export declare function resolveImage(image: string | undefined, buildLocalImage?: boolean, version?: string): string;

package/dist/image.js

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Registry repository the release workflow publishes the Tug image to. */
+export const IMAGE_REPOSITORY = 'ghcr.io/wpelevator/tug';
+/** Tag `--build-local-image` builds and ships when no `--image` is given; for development against a checkout. */
+export const LOCAL_IMAGE = 'tug:local';
+// package.json sits one level above this file in src/ (dev), dist/ (build) and the installed package.
+const packageJsonPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+export function packageVersion() {
+    return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')).version;
+}
+/** The published image matching this CLI's version, so the CLI and the agents it installs stay in step. */
+export function defaultImage(version = packageVersion()) {
+    return `${IMAGE_REPOSITORY}:${version}`;
+}
+/** An explicit `--image` always wins; otherwise a locally built image is `tug:local` and anything else is the published image. */
+export function resolveImage(image, buildLocalImage = false, version = packageVersion()) {
+    return image || (buildLocalImage ? LOCAL_IMAGE : defaultImage(version));
+}

package/dist/ingress.d.ts

@@ -0,0 +1,50 @@
+import type { DesiredState, IngressRoute, IngressStatus, IngressWork, ProjectStatus, ServiceEndpoints } from './protocol.ts';
+import type { DockerRunner } from './runners.ts';
+export declare const CADDY_CONTAINER = "tug-caddy";
+export declare const DEFAULT_CADDY_IMAGE = "caddy:2-alpine";
+export interface NodeView {
+    name: string;
+    /** Reachable mesh address; null when the mesh is off or the node has not reported a key yet. */
+    overlayIp: string | null;
+    address: string | null;
+    lastSeenAt: string | null;
+}
+export interface ReportedStatus {
+    node: string;
+    project: string;
+    status: ProjectStatus;
+}
+/**
+ * Where each service can be reached right now: one endpoint per placement node whose agent is
+ * fresh and reports that service `serving`. Withdrawn automatically when a node goes stale or its
+ * rollout state drops, which is what makes DNS and ingress health-aware.
+ */
+export declare function resolveServiceEndpoints(states: DesiredState[], nodes: NodeView[], statuses: ReportedStatus[], staleBefore: string): ServiceEndpoints;
+export interface IngressInput {
+    states: DesiredState[];
+    endpoints: ServiceEndpoints;
+    /** The ingress node being configured; its own upstreams are reached on loopback. */
+    node: string;
+    /** Decrypted project secrets for custom TLS, keyed `<project>/<secret name>`. */
+    secrets: Map<string, string>;
+    acmeEmail?: string;
+}
+export declare function buildIngressWork({ states, endpoints, node, secrets, acmeEmail }: IngressInput): IngressWork;
+export declare function renderCaddyfile(routes: IngressRoute[], opts?: {
+    acmeEmail?: string;
+}): string;
+export declare function ingressConfigHash(work: Pick<IngressWork, 'caddyfile' | 'files'>): string;
+export interface IngressContext {
+    docker: DockerRunner;
+    stateDir: string;
+    caddyImage?: string;
+}
+/**
+ * Makes the Caddy container match the control-rendered config. Config is copied into the
+ * container (`docker cp`, so it works whether the agent runs on the host or in a container) and
+ * applied with `caddy reload`, which swaps config gracefully without dropping connections. If
+ * Caddy rejects the new config the previous one is restored and the error reported.
+ */
+export declare function reconcileIngress(ctx: IngressContext, work: IngressWork): Promise<IngressStatus>;
+/** Removes the Caddy container when a node stops being an ingress node; ACME data volumes are kept. */
+export declare function removeIngress(ctx: IngressContext): Promise<boolean>;

package/dist/ingress.js

@@ -0,0 +1,178 @@
+// Service endpoints (health-aware DNS source), ingress route resolution and Caddyfile rendering
+// on the control side; the managed Caddy container reconcile on the agent side. Docker access goes
+// through the injectable DockerRunner.
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { publishedPort } from "./compose.js";
+import { ensureDir, errMessage } from "./util.js";
+export const CADDY_CONTAINER = 'tug-caddy';
+export const DEFAULT_CADDY_IMAGE = 'caddy:2-alpine';
+const CADDY_ETC = '/etc/caddy';
+/**
+ * Where each service can be reached right now: one endpoint per placement node whose agent is
+ * fresh and reports that service `serving`. Withdrawn automatically when a node goes stale or its
+ * rollout state drops, which is what makes DNS and ingress health-aware.
+ */
+export function resolveServiceEndpoints(states, nodes, statuses, staleBefore) {
+    const byName = new Map(nodes.map(n => [n.name, n]));
+    const reported = new Map(statuses.map(s => [`${s.node}\0${s.project}`, s.status]));
+    const out = {};
+    for (const state of states) {
+        for (const [service, spec] of Object.entries(state.services)) {
+            const endpoints = [];
+            for (const nodeName of spec.placement?.nodes || []) {
+                const node = byName.get(nodeName);
+                const address = node && (node.overlayIp || node.address);
+                if (!node || !address || !node.lastSeenAt || node.lastSeenAt < staleBefore)
+                    continue;
+                if (reported.get(`${nodeName}\0${state.project}`)?.serviceStates?.[service]?.rolloutState !== 'serving')
+                    continue;
+                endpoints.push({ node: nodeName, address });
+            }
+            if (endpoints.length)
+                (out[state.project] ||= {})[service] = endpoints.sort((a, b) => a.node.localeCompare(b.node));
+        }
+    }
+    return out;
+}
+const certFile = (host, ext) => `certs/${host.replace(/\*/g, '_wildcard_')}.${ext}`;
+export function buildIngressWork({ states, endpoints, node, secrets, acmeEmail }) {
+    const routes = [];
+    const files = {};
+    const warnings = [];
+    const seenHosts = new Map();
+    const tagged = [];
+    for (const state of states) {
+        for (const [service, svc] of Object.entries(state.compose.services || {})) {
+            const ingress = svc['x-tug']?.ingress;
+            if (ingress)
+                tagged.push({ project: state.project, service, ingress, port: publishedPort(svc, ingress.port) });
+        }
+    }
+    tagged.sort((a, b) => `${a.project}/${a.service}`.localeCompare(`${b.project}/${b.service}`));
+    for (const { project, service, ingress, port } of tagged) {
+        const label = `${project}/${service}`;
+        const host = ingress.host.toLowerCase();
+        const tls = ingress.tls || 'auto';
+        if (seenHosts.has(host)) {
+            warnings.push(`${label}: host ${host} is already routed by ${seenHosts.get(host)}; skipped`);
+            continue;
+        }
+        if (port == null) {
+            warnings.push(`${label}: ingress.port ${ingress.port} is not published; skipped`);
+            continue;
+        }
+        const upstreams = (endpoints[project]?.[service] || []).map(e => `${e.node === node ? '127.0.0.1' : e.address}:${port}`);
+        if (!upstreams.length) {
+            warnings.push(`${label}: no serving upstream for ${host}; route withheld`);
+            continue;
+        }
+        if (tls === 'custom') {
+            const cert = secrets.get(`${project}/${ingress.cert}`);
+            const key = secrets.get(`${project}/${ingress.key}`);
+            if (!cert || !key) {
+                warnings.push(`${label}: custom TLS secrets ${ingress.cert}/${ingress.key} not found in project ${project}; skipped`);
+                continue;
+            }
+            files[certFile(host, 'crt')] = cert.endsWith('\n') ? cert : `${cert}\n`;
+            files[certFile(host, 'key')] = key.endsWith('\n') ? key : `${key}\n`;
+        }
+        seenHosts.set(host, label);
+        routes.push({ project, service, host, tls, upstreams });
+    }
+    return { caddyfile: renderCaddyfile(routes, { acmeEmail }), files, routes, warnings };
+}
+export function renderCaddyfile(routes, opts = {}) {
+    const out = [];
+    if (opts.acmeEmail)
+        out.push('{', `\temail ${opts.acmeEmail}`, '}', '');
+    for (const route of routes) {
+        // An explicit http:// address turns off automatic HTTPS for that site.
+        out.push(`${route.tls === 'off' ? 'http://' : ''}${route.host} {`);
+        if (route.tls === 'custom')
+            out.push(`\ttls ${CADDY_ETC}/${certFile(route.host, 'crt')} ${CADDY_ETC}/${certFile(route.host, 'key')}`);
+        out.push(`\treverse_proxy ${route.upstreams.join(' ')} {`, '\t\tlb_policy round_robin', '\t}', '}', '');
+    }
+    return out.length ? out.join('\n') : '# no ingress routes\n';
+}
+// ---- Agent: managed Caddy container ------------------------------------------------------------
+export function ingressConfigHash(work) {
+    const h = crypto.createHash('sha256').update(work.caddyfile);
+    for (const name of Object.keys(work.files).sort())
+        h.update('\0').update(name).update('\0').update(work.files[name]);
+    return h.digest('hex');
+}
+async function writeStage(dir, work) {
+    await fs.rm(dir, { recursive: true, force: true });
+    await ensureDir(dir);
+    await fs.writeFile(path.join(dir, 'Caddyfile'), work.caddyfile);
+    for (const [name, body] of Object.entries(work.files)) {
+        const file = path.join(dir, name);
+        await ensureDir(path.dirname(file));
+        await fs.writeFile(file, body, { mode: name.endsWith('.key') ? 0o600 : 0o644 });
+    }
+}
+/**
+ * Makes the Caddy container match the control-rendered config. Config is copied into the
+ * container (`docker cp`, so it works whether the agent runs on the host or in a container) and
+ * applied with `caddy reload`, which swaps config gracefully without dropping connections. If
+ * Caddy rejects the new config the previous one is restored and the error reported.
+ */
+export async function reconcileIngress(ctx, work) {
+    const root = path.join(ctx.stateDir, 'ingress');
+    const stage = path.join(root, 'stage');
+    const applied = path.join(root, 'applied');
+    const configHash = ingressConfigHash(work);
+    const routes = work.routes.length;
+    const running = await ctx.docker(['container', 'inspect', '-f', '{{.State.Running}}', CADDY_CONTAINER])
+        .then(r => r.out.trim() === 'true', () => null);
+    const appliedHash = await fs.readFile(path.join(root, 'applied.hash'), 'utf8').then(s => s.trim(), () => '');
+    if (running && appliedHash === configHash)
+        return { state: 'serving', configHash, routes };
+    await writeStage(stage, work);
+    try {
+        if (running === null) {
+            await ctx.docker([
+                'create', '--name', CADDY_CONTAINER, '--restart', 'unless-stopped', '--network', 'host',
+                '-v', 'tug-caddy-data:/data', '-v', 'tug-caddy-config:/config', '-v', `tug-caddy-etc:${CADDY_ETC}`,
+                ctx.caddyImage || DEFAULT_CADDY_IMAGE
+            ]);
+            await ctx.docker(['cp', `${stage}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]);
+            await ctx.docker(['start', CADDY_CONTAINER]);
+        }
+        else if (running === false) {
+            await ctx.docker(['cp', `${stage}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]);
+            await ctx.docker(['start', CADDY_CONTAINER]);
+        }
+        else {
+            try {
+                await ctx.docker(['exec', CADDY_CONTAINER, 'rm', '-rf', `${CADDY_ETC}/certs`]);
+                await ctx.docker(['cp', `${stage}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]);
+                await ctx.docker(['exec', CADDY_CONTAINER, 'caddy', 'reload', '--config', `${CADDY_ETC}/Caddyfile`, '--adapter', 'caddyfile']);
+            }
+            catch (e) {
+                if (await fs.stat(applied).then(() => true, () => false))
+                    await ctx.docker(['cp', `${applied}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]).catch(() => { });
+                throw e;
+            }
+        }
+    }
+    catch (e) {
+        await fs.rm(stage, { recursive: true, force: true });
+        return { state: 'failed', configHash, routes, error: errMessage(e).slice(-1000) };
+    }
+    await fs.rm(applied, { recursive: true, force: true });
+    await fs.rename(stage, applied);
+    await fs.writeFile(path.join(root, 'applied.hash'), `${configHash}\n`);
+    return { state: 'serving', configHash, routes };
+}
+/** Removes the Caddy container when a node stops being an ingress node; ACME data volumes are kept. */
+export async function removeIngress(ctx) {
+    const root = path.join(ctx.stateDir, 'ingress');
+    if (!(await fs.stat(root).then(() => true, () => false)))
+        return false;
+    await ctx.docker(['rm', '-f', CADDY_CONTAINER]).catch(() => { });
+    await fs.rm(root, { recursive: true, force: true });
+    return true;
+}

package/dist/main.d.ts

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

package/dist/main.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Single entrypoint for the control plane and agent images; role picked via TUG_ROLE or argv.
+const role = process.argv[2] || process.env.TUG_ROLE;
+switch (role) {
+    case 'control': {
+        const { createApp, listen } = await import("./control.js");
+        const app = await createApp();
+        await listen(app);
+        break;
+    }
+    case 'agent': {
+        const { main } = await import("./agent.js");
+        await main();
+        break;
+    }
+    default: {
+        const self = process.argv[1] ? `node ${process.argv[1].split('/').slice(-2).join('/')}` : 'main';
+        console.error(`Usage: TUG_ROLE=control|agent ${self}, or ${self} <control|agent>`);
+        process.exit(1);
+    }
+}
+export {};

package/dist/mesh.d.ts

@@ -0,0 +1,70 @@
+import type { NetworkConfig, WgPeer } from './protocol.ts';
+import type { HostRunner } from './runners.ts';
+/** 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 declare const DEFAULT_MESH_CIDR = "10.210.0.0/16";
+export declare const DEFAULT_WG_PORT = 51820;
+export declare const WG_INTERFACE = "wg0";
+export declare const WG_KEEPALIVE = 25;
+export declare const WG_KEY_RE: RegExp;
+export declare const isWgKey: (value: unknown) => value is string;
+/** Public key for a base64 private key (X25519, as `wg pubkey` computes it). */
+export declare function publicKeyFromPrivate(privateKey: string): string;
+export declare function generateWgKeyPair(): {
+    privateKey: string;
+    publicKey: string;
+};
+/** Loads the node's keypair from the state dir, generating it on first use. The private key never leaves this directory. */
+export declare function ensureWgKeys(stateDir: string): Promise<{
+    privateKey: string;
+    publicKey: string;
+}>;
+export declare function rotateWgKeys(stateDir: string): Promise<{
+    privateKey: string;
+    publicKey: string;
+}>;
+/** The public key control last accepted, so the agent only re-reports when it changed. */
+export declare function readReportedKey(stateDir: string): Promise<string | null>;
+export declare function writeReportedKey(stateDir: string, publicKey: string): Promise<void>;
+export declare function ipToInt(ip: string): number;
+export declare const intToIp: (n: number) => string;
+export declare function parseCidr(cidr: string): {
+    base: number;
+    prefix: number;
+    size: number;
+};
+/** First free host address in the mesh CIDR (never the network or broadcast address). */
+export declare function allocateOverlayIp(cidr: string, used: Iterable<string>): string;
+/** `host:port`, adding the WireGuard port when the public address has none. IPv6 literals are bracketed. */
+export declare function wgEndpoint(publicAddress: string | null | undefined, port: number): string | undefined;
+/** `wg syncconf` input: interface key and port plus peers (no wg-quick-only keys such as Address). */
+export declare function renderWgConfig(privateKey: string, listenPort: number, peers: WgPeer[]): string;
+export interface AppliedPeer {
+    publicKey: string;
+    endpoint?: string;
+    allowedIps: string[];
+    keepalive: number;
+}
+export interface AppliedInterface {
+    publicKey: string;
+    listenPort: number;
+    peers: AppliedPeer[];
+}
+/** Parses `wg show <iface> dump` (tab separated; first line is the interface, then one line per peer). */
+export declare function parseWgDump(dump: string): AppliedInterface;
+export interface PeerDiff {
+    add: string[];
+    remove: string[];
+    update: string[];
+}
+/** Compares desired peers with what `wg` reports. A desired endpoint is authoritative; a peer without one keeps whatever it roamed to. */
+export declare function diffPeers(desired: WgPeer[], applied: AppliedPeer[]): PeerDiff;
+export interface MeshResult {
+    created: boolean;
+    synced: boolean;
+    diff: PeerDiff;
+}
+/**
+ * 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 declare function reconcileMesh(host: HostRunner, stateDir: string, network: NetworkConfig): Promise<MeshResult>;