@wpelevator/tug 0.3.0 → 0.5.0

package/dist/db-driver.d.ts

@@ -0,0 +1,20 @@
+/** The portable subset shared by synchronous SQLite runtimes. Only anonymous ? bindings are supported. */
+export type SqlValue = string | number | bigint | null | Uint8Array;
+export type SqlRow = Record<string, SqlValue>;
+export interface Db {
+    get<T = SqlRow>(sql: string, ...values: SqlValue[]): T | undefined;
+    all<T = SqlRow>(sql: string, ...values: SqlValue[]): T[];
+    run(sql: string, ...values: SqlValue[]): {
+        changes: number;
+    };
+    exec(sql: string): void;
+    close(): void;
+}
+export type ConnectDb = (filename: string, options: {
+    readOnly: boolean;
+}) => Db;
+export declare class DbError extends Error {
+    readonly kind: 'unique' | 'busy';
+    constructor(kind: DbError['kind'], cause: Error);
+}
+export declare function isUniqueViolation(error: unknown): boolean;

package/dist/db-driver.js

@@ -0,0 +1,11 @@
+export class DbError extends Error {
+    kind;
+    constructor(kind, cause) {
+        super(cause.message, { cause });
+        this.name = 'DbError';
+        this.kind = kind;
+    }
+}
+export function isUniqueViolation(error) {
+    return error instanceof DbError && error.kind === 'unique';
+}

package/dist/db-node.d.ts

@@ -0,0 +1,3 @@
+import type { ConnectDb } from './db-driver.ts';
+/** This module is the only runtime-specific adapter; replace it at build time for a future Bun bundle. */
+export declare const connectNodeDb: ConnectDb;

package/dist/db-node.js

@@ -0,0 +1,60 @@
+import { DatabaseSync } from 'node:sqlite';
+import { DbError } from "./db-driver.js";
+function sqliteCall(operation) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        if (error instanceof Error && 'errcode' in error) {
+            const code = Number(error.errcode);
+            if (code === 1555 || code === 2067)
+                throw new DbError('unique', error);
+            if ((code & 255) === 5 || (code & 255) === 6)
+                throw new DbError('busy', error);
+        }
+        throw error;
+    }
+}
+/** Count anonymous placeholders outside SQL literals, quoted identifiers and comments. */
+function checkBindings(sql, values) {
+    const tokens = sql.match(/'(?:''|[^'])*'|"(?:""|[^"])*"|`(?:``|[^`])*`|\[[^\]]*\]|--[^\r\n]*|\/\*[\s\S]*?\*\/|\?\d*|[:@$][\w]+/g) ?? [];
+    const parameters = tokens.filter((token) => /^[?:@$]/.test(token));
+    if (parameters.some((token) => token !== '?'))
+        throw new TypeError('Only anonymous ? SQL parameters are supported');
+    if (parameters.length !== values.length)
+        throw new TypeError(`Expected ${parameters.length} SQL bindings, received ${values.length}`);
+    for (const value of values) {
+        if (value !== null &&
+            typeof value !== 'string' &&
+            typeof value !== 'bigint' &&
+            !(typeof value === 'number' && Number.isFinite(value)) &&
+            !(value instanceof Uint8Array))
+            throw new TypeError('SQL bindings must be strings, finite numbers, bigints, null or Uint8Array');
+    }
+}
+/** This module is the only runtime-specific adapter; replace it at build time for a future Bun bundle. */
+export const connectNodeDb = (filename, { readOnly }) => {
+    const database = sqliteCall(() => new DatabaseSync(filename, { readOnly }));
+    const prepare = (sql, values) => {
+        checkBindings(sql, values);
+        return database.prepare(sql);
+    };
+    return {
+        get: (sql, ...values) => sqliteCall(() => {
+            const row = prepare(sql, values).get(...values);
+            return row === undefined ? undefined : { ...row };
+        }),
+        all: (sql, ...values) => sqliteCall(() => prepare(sql, values)
+            .all(...values)
+            .map((row) => ({ ...row }))),
+        run: (sql, ...values) => sqliteCall(() => {
+            const { changes } = prepare(sql, values).run(...values);
+            const count = Number(changes);
+            if (!Number.isSafeInteger(count))
+                throw new RangeError('SQL change count exceeds the safe integer range');
+            return { changes: count };
+        }),
+        exec: (sql) => sqliteCall(() => database.exec(sql)),
+        close: () => sqliteCall(() => database.close()),
+    };
+};

package/dist/db.d.ts

@@ -1,6 +1,6 @@
-import sqlite3 from 'sqlite3';
-import type { Database } from 'sqlite';
-export type Db = Database<sqlite3.Database, sqlite3.Statement>;
+import type { ConnectDb, Db } from './db-driver.ts';
+export type { Db } from './db-driver.ts';
+export declare const openDb: (filename: string) => Promise<Db>, openAgentDb: (filename: string) => Promise<Db>, openSnapshotDb: (filename: string) => Db;
 export interface ProjectRow {
     id: string;
     name: string;
@@ -19,7 +19,6 @@ export interface NodeRow {
     status: string;
     labels_json: string | null;
     agent_token_hash: string | null;
-    registry_token_hash: string | null;
     last_seen_at: string | null;
     created_at: string;
     updated_at: string;
@@ -120,5 +119,9 @@ export interface AppliedStateRow {
     service_states_json: string;
     secret_versions_json: string;
 }
-export declare function openDb(filename: string): Promise<Db>;
-export declare function openAgentDb(filename: string): Promise<Db>;
+/** Shared policy for every driver, including read-only restore validation. */
+export declare function databaseAccess(connect: ConnectDb): {
+    openDb: (filename: string) => Promise<Db>;
+    openAgentDb: (filename: string) => Promise<Db>;
+    openSnapshotDb: (filename: string) => Db;
+};

package/dist/db.js

@@ -1,19 +1,38 @@
-import sqlite3 from 'sqlite3';
-import { open } from 'sqlite';
+import { connectNodeDb } from "./db-node.js";
 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;
+// One composition point for all writable and snapshot connections.
+export const { openDb, openAgentDb, openSnapshotDb } = databaseAccess(connectNodeDb);
+function configure(db, writable, initialize) {
+    try {
+        db.exec('PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 1000;');
+        if (writable)
+            db.exec('PRAGMA journal_mode = WAL;');
+        initialize?.(db);
+        return db;
+    }
+    catch (error) {
+        try {
+            db.close();
+        }
+        catch {
+            /* Preserve the initialization failure. */
+        }
+        throw error;
+    }
 }
-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(`
+/** Shared policy for every driver, including read-only restore validation. */
+export function databaseAccess(connect) {
+    function openSnapshotDb(filename) {
+        return configure(connect(filename, { readOnly: true }), false);
+    }
+    async function openDb(filename) {
+        await ensureDir(path.dirname(filename));
+        return configure(connect(filename, { readOnly: false }), true, initializeControl);
+    }
+    async function openAgentDb(filename) {
+        await ensureDir(path.dirname(filename));
+        return configure(connect(filename, { readOnly: false }), true, (db) => db.exec(`
 CREATE TABLE IF NOT EXISTS applied_state(
   project TEXT PRIMARY KEY,
   version TEXT,
@@ -27,14 +46,15 @@ CREATE TABLE IF NOT EXISTS event_state(
   fingerprint TEXT NOT NULL,
   phase TEXT NOT NULL
 );
-`);
-    return db;
+`));
+    }
+    return { openDb, openAgentDb, openSnapshotDb };
 }
-async function migrate(db) {
-    await db.exec(`
+function initializeControl(db) {
+    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, labels_json TEXT, agent_token_hash TEXT, registry_token_hash TEXT, last_seen_at 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, labels_json TEXT, agent_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, actor TEXT);
@@ -51,13 +71,7 @@ CREATE TABLE IF NOT EXISTS api_tokens(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT
 CREATE INDEX IF NOT EXISTS events_by_time ON events(created_at);
 CREATE TABLE IF NOT EXISTS locks(name TEXT PRIMARY KEY, owner TEXT, expires_at TEXT, created_at TEXT);
 `);
-    try {
-        await db.exec('ALTER TABLE nodes ADD COLUMN labels_json TEXT');
-    }
-    catch {
-        /* column already exists */
-    }
-    const row = await db.get('SELECT value FROM meta WHERE key = ?', 'schema_created_at');
+    const row = 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());
+        db.run('INSERT INTO meta(key,value) VALUES(?,?)', 'schema_created_at', now());
 }

package/dist/docker-api.d.ts

@@ -0,0 +1,232 @@
+import { EventEmitter } from 'node:events';
+import type { Readable, Writable } from 'node:stream';
+/** Oldest Engine API the agent speaks (Docker 20.10+, which the nested daemons in the integration tests run). */
+export declare const API_VERSION = "v1.41";
+export declare const DEFAULT_SOCKET = "/var/run/docker.sock";
+/** An Engine API error; `status` is the HTTP status and `message` the daemon's own text. */
+export declare class DockerError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export declare const isNotFound: (error: unknown) => boolean;
+export interface ContainerSummary {
+    Id: string;
+    Names: string[];
+    Image: string;
+    ImageID?: string;
+    State: string;
+    Status?: string;
+    Created?: number;
+    Labels: Record<string, string>;
+    Ports?: {
+        IP?: string;
+        PrivatePort: number;
+        PublicPort?: number;
+        Type: string;
+    }[];
+}
+export interface ContainerInspect {
+    Id: string;
+    Name: string;
+    Image?: string;
+    Config?: {
+        Image?: string;
+        Labels?: Record<string, string>;
+        Env?: string[];
+    };
+    State?: {
+        Status?: string;
+        Running?: boolean;
+        ExitCode?: number;
+        Health?: {
+            Status?: string;
+        };
+    };
+    NetworkSettings?: {
+        Networks?: Record<string, {
+            IPAddress?: string;
+            GlobalIPv6Address?: string;
+        }>;
+    };
+    [key: string]: unknown;
+}
+export interface ContainerFilter {
+    /** `key` or `key=value` label filters, all of which must match. */
+    label?: string[];
+    /** Containers created from this image reference or ID. */
+    ancestor?: string;
+    name?: string;
+}
+export interface ImageInspect {
+    Id: string;
+    Os?: string;
+    Architecture?: string;
+    RepoTags?: string[];
+    RepoDigests?: string[];
+}
+export interface NetworkInspect {
+    Name: string;
+    Id: string;
+    Labels?: Record<string, string>;
+    Containers?: Record<string, unknown>;
+}
+export interface VolumeInspect {
+    Name: string;
+    Driver?: string;
+    Labels?: Record<string, string> | null;
+    Options?: Record<string, string> | null;
+}
+export interface DaemonInfo {
+    OSType?: string;
+    Architecture?: string;
+    ServerVersion?: string;
+    [key: string]: unknown;
+}
+export interface DaemonVersion {
+    Version?: string;
+    ApiVersion?: string;
+    MinAPIVersion?: string;
+    [key: string]: unknown;
+}
+/** `POST /containers/create` body; the agent builds these in `containerSpecs`. */
+export interface CreateContainerBody {
+    Image: string;
+    Env?: string[];
+    Cmd?: string[] | null;
+    Entrypoint?: string[] | null;
+    User?: string;
+    WorkingDir?: string;
+    Hostname?: string;
+    Labels?: Record<string, string>;
+    ExposedPorts?: Record<string, object>;
+    StopSignal?: string;
+    StopTimeout?: number;
+    Healthcheck?: Record<string, unknown>;
+    HostConfig?: Record<string, unknown>;
+    NetworkingConfig?: {
+        EndpointsConfig: Record<string, {
+            Aliases?: string[];
+            [key: string]: unknown;
+        }>;
+    };
+}
+/** A process attached to a container: exec or logs. Shaped like a child process so `live.ts` treats both alike. */
+export interface AttachedProcess extends EventEmitter {
+    stdin: Writable | null;
+    stdout: Readable;
+    stderr: Readable;
+    kill(signal?: NodeJS.Signals): boolean;
+    resize?(columns: number, rows: number): void;
+}
+export interface ExecOptions {
+    cmd: string[];
+    stdin?: boolean;
+    tty?: boolean;
+    columns?: number;
+    rows?: number;
+}
+export interface LogsOptions {
+    follow?: boolean;
+    tail?: number;
+    timestamps?: boolean;
+}
+export interface DockerApi {
+    version(): Promise<DaemonVersion>;
+    info(): Promise<DaemonInfo>;
+    listContainers(filter?: ContainerFilter, all?: boolean): Promise<ContainerSummary[]>;
+    inspectContainer(id: string): Promise<ContainerInspect>;
+    createContainer(name: string, body: CreateContainerBody): Promise<string>;
+    startContainer(id: string): Promise<void>;
+    stopContainer(id: string, timeoutSeconds?: number): Promise<void>;
+    restartContainer(id: string): Promise<void>;
+    /** Removes a container even when running; a missing container is not an error. */
+    removeContainer(id: string): Promise<void>;
+    /** Connects a running container to a network, optionally under service aliases. */
+    connectNetwork(network: string, container: string, aliases?: string[]): Promise<void>;
+    /** Container output as demultiplexed, ended streams (a TTY container's output is all stdout). */
+    logs(id: string, options?: LogsOptions): Promise<AttachedProcess>;
+    /** Copies the tar stream into the container directory `dir`. */
+    putArchive(id: string, dir: string, tar: Readable | Buffer): Promise<void>;
+    /** Runs a command to completion and returns its output; a non-zero exit is reported in `code`. */
+    execRun(id: string, cmd: string[]): Promise<{
+        code: number;
+        out: string;
+        err: string;
+    }>;
+    /** Starts an interactive or streaming exec; `close` carries the exit code. */
+    execStart(id: string, options: ExecOptions): Promise<AttachedProcess>;
+    inspectNetwork(name: string): Promise<NetworkInspect | null>;
+    createNetwork(name: string, labels: Record<string, string>): Promise<void>;
+    inspectVolume(name: string): Promise<VolumeInspect | null>;
+    createVolume(name: string, options: {
+        driver?: string;
+        opts?: Record<string, string>;
+        labels?: Record<string, string>;
+    }): Promise<void>;
+    removeVolume(name: string): Promise<void>;
+    inspectImage(ref: string): Promise<ImageInspect | null>;
+    /** Pulls `ref`; `auth` becomes `X-Registry-Auth`. */
+    pullImage(ref: string, auth?: Record<string, string>): Promise<void>;
+    loadImage(archive: Readable | Buffer): Promise<void>;
+    removeImage(ref: string): Promise<void>;
+}
+/** Splits a reference into `fromImage` and `tag` for `POST /images/create`. */
+export declare function splitImageRef(ref: string): {
+    fromImage: string;
+    tag: string;
+};
+/**
+ * Splits the 8-byte-header multiplexed stream (`[stream, 0, 0, 0, size(4, big endian)]` frames) that
+ * non-TTY attach, exec and logs use into `stdout` and `stderr`. `end` fires once the source ends.
+ */
+export declare function demux(source: Readable, stdout: Writable, stderr: Writable): void;
+/** `unix:///path` or a bare path from `DOCKER_HOST`; the agent talks to the local daemon only. */
+export declare function socketFromEnv(env?: NodeJS.ProcessEnv): string;
+export declare class DockerEngine implements DockerApi {
+    private readonly socketPath;
+    constructor(socketPath?: string);
+    private request;
+    /** Reads the response; non-2xx becomes a `DockerError` carrying the daemon's message. */
+    private call;
+    private json;
+    /** Consumes the JSON-lines progress stream of pull and load; a line with `error` fails the call. */
+    private progress;
+    version: () => Promise<DaemonVersion>;
+    info: () => Promise<DaemonInfo>;
+    listContainers(filter?: ContainerFilter, all?: boolean): Promise<ContainerSummary[]>;
+    inspectContainer: (id: string) => Promise<ContainerInspect>;
+    createContainer(name: string, body: CreateContainerBody): Promise<string>;
+    startContainer(id: string): Promise<void>;
+    stopContainer(id: string, timeoutSeconds?: number): Promise<void>;
+    restartContainer(id: string): Promise<void>;
+    removeContainer(id: string): Promise<void>;
+    connectNetwork(network: string, container: string, aliases?: string[]): Promise<void>;
+    logs(id: string, options?: LogsOptions): Promise<AttachedProcess>;
+    private isTty;
+    /**
+     * Wraps a response or hijacked socket as a process whose output is demultiplexed unless a TTY.
+     * `close` fires with `exitCode()` once the source and both output streams have ended.
+     */
+    private attachedFromStream;
+    putArchive(id: string, dir: string, tar: Readable | Buffer): Promise<void>;
+    execRun(id: string, cmd: string[]): Promise<{
+        code: number;
+        out: string;
+        err: string;
+    }>;
+    execStart(id: string, options: ExecOptions): Promise<AttachedProcess>;
+    private resizeExec;
+    inspectNetwork(name: string): Promise<NetworkInspect | null>;
+    createNetwork(name: string, labels: Record<string, string>): Promise<void>;
+    inspectVolume(name: string): Promise<VolumeInspect | null>;
+    createVolume(name: string, options: {
+        driver?: string;
+        opts?: Record<string, string>;
+        labels?: Record<string, string>;
+    }): Promise<void>;
+    removeVolume(name: string): Promise<void>;
+    inspectImage(ref: string): Promise<ImageInspect | null>;
+    pullImage(ref: string, auth?: Record<string, string>): Promise<void>;
+    loadImage(archive: Readable | Buffer): Promise<void>;
+    removeImage(ref: string): Promise<void>;
+}