@wpelevator/tug 0.4.0 → 0.6.0

package/dist/cron.d.ts

@@ -0,0 +1,17 @@
+/** A small UTC cron parser for `x-tug.backup.schedule`: five fields, lists, ranges, steps and `@` aliases. */
+export interface CronSchedule {
+    minutes: ReadonlySet<number>;
+    hours: ReadonlySet<number>;
+    days: ReadonlySet<number>;
+    months: ReadonlySet<number>;
+    weekdays: ReadonlySet<number>;
+    /** True when the field was `*`; cron matches day-of-month OR day-of-week when neither is. */
+    anyDay: boolean;
+    anyWeekday: boolean;
+}
+/** Parse a five-field cron expression or an `@hourly`-style alias. Throws a readable `Error` on bad input. */
+export declare function parseCron(expression: string): CronSchedule;
+/** The first matching minute strictly after `after` (UTC), or `null` when the schedule never fires (such as Feb 31). */
+export declare function nextCronRun(schedule: CronSchedule | string, after: Date): Date | null;
+/** Approximate gap between runs in milliseconds, from the next two matches after `from`; used to size deadlines and staleness. */
+export declare function cronPeriodMs(schedule: CronSchedule | string, from: Date): number | null;

package/dist/cron.js

@@ -0,0 +1,124 @@
+/** A small UTC cron parser for `x-tug.backup.schedule`: five fields, lists, ranges, steps and `@` aliases. */
+const ALIASES = {
+    '@hourly': '0 * * * *',
+    '@daily': '0 0 * * *',
+    '@midnight': '0 0 * * *',
+    '@weekly': '0 0 * * 0',
+    '@monthly': '0 0 1 * *',
+    '@yearly': '0 0 1 1 *',
+    '@annually': '0 0 1 1 *',
+};
+const FIELDS = [
+    { name: 'minute', min: 0, max: 59 },
+    { name: 'hour', min: 0, max: 23 },
+    { name: 'day of month', min: 1, max: 31 },
+    { name: 'month', min: 1, max: 12 },
+    { name: 'day of week', min: 0, max: 7 },
+];
+function parseNumber(text, field) {
+    if (!/^\d+$/.test(text))
+        throw new Error(`${field.name} "${text}" is not a number`);
+    const value = Number(text);
+    if (value < field.min || value > field.max)
+        throw new Error(`${field.name} ${value} is outside ${field.min}-${field.max}`);
+    return value;
+}
+function parseField(text, field) {
+    const values = new Set();
+    for (const part of text.split(',')) {
+        if (!part)
+            throw new Error(`${field.name} has an empty list item`);
+        const [range, stepText, extra] = part.split('/');
+        if (extra !== undefined)
+            throw new Error(`${field.name} "${part}" has more than one step`);
+        let step = 1;
+        if (stepText !== undefined) {
+            step = parseNumber(stepText, { name: `${field.name} step`, min: 1, max: field.max });
+        }
+        let low;
+        let high;
+        if (range === '*') {
+            low = field.min;
+            high = field.name === 'day of week' ? 6 : field.max;
+        }
+        else if (range.includes('-')) {
+            const [from, to, more] = range.split('-');
+            if (more !== undefined)
+                throw new Error(`${field.name} range "${range}" is malformed`);
+            low = parseNumber(from, field);
+            high = parseNumber(to, field);
+            if (low > high)
+                throw new Error(`${field.name} range "${range}" runs backwards`);
+        }
+        else {
+            low = parseNumber(range, field);
+            high = stepText === undefined ? low : field.max;
+        }
+        for (let value = low; value <= high; value += step)
+            values.add(value);
+    }
+    return values;
+}
+/** Parse a five-field cron expression or an `@hourly`-style alias. Throws a readable `Error` on bad input. */
+export function parseCron(expression) {
+    if (typeof expression !== 'string')
+        throw new Error('schedule must be a string');
+    const text = ALIASES[expression.trim().toLowerCase()] ?? expression.trim();
+    const parts = text.split(/\s+/);
+    if (parts.length !== 5)
+        throw new Error(`schedule "${expression}" must have five fields (minute hour day month weekday) or be one of ${Object.keys(ALIASES).join(', ')}`);
+    const [minutes, hours, days, months, weekdays] = parts.map((part, index) => parseField(part, FIELDS[index]));
+    // Both 0 and 7 mean Sunday.
+    if (weekdays.delete(7))
+        weekdays.add(0);
+    return {
+        minutes,
+        hours,
+        days,
+        months,
+        weekdays,
+        anyDay: parts[2].startsWith('*'),
+        anyWeekday: parts[4].startsWith('*'),
+    };
+}
+function dayMatches(schedule, date) {
+    const dayOk = schedule.days.has(date.getUTCDate());
+    const weekdayOk = schedule.weekdays.has(date.getUTCDay());
+    if (!schedule.anyDay && !schedule.anyWeekday)
+        return dayOk || weekdayOk;
+    return dayOk && weekdayOk;
+}
+/** Longest gap between two matches is a Feb 29 across a skipped century leap year: eight years. */
+const SEARCH_YEARS = 9;
+/** The first matching minute strictly after `after` (UTC), or `null` when the schedule never fires (such as Feb 31). */
+export function nextCronRun(schedule, after) {
+    const parsed = typeof schedule === 'string' ? parseCron(schedule) : schedule;
+    const next = new Date(Math.floor(after.getTime() / 60_000) * 60_000 + 60_000);
+    const limit = next.getUTCFullYear() + SEARCH_YEARS;
+    while (next.getUTCFullYear() <= limit) {
+        if (!parsed.months.has(next.getUTCMonth() + 1)) {
+            next.setUTCMonth(next.getUTCMonth() + 1, 1);
+            next.setUTCHours(0, 0, 0, 0);
+        }
+        else if (!dayMatches(parsed, next)) {
+            next.setUTCDate(next.getUTCDate() + 1);
+            next.setUTCHours(0, 0, 0, 0);
+        }
+        else if (!parsed.hours.has(next.getUTCHours())) {
+            next.setUTCHours(next.getUTCHours() + 1, 0, 0, 0);
+        }
+        else if (!parsed.minutes.has(next.getUTCMinutes())) {
+            next.setUTCMinutes(next.getUTCMinutes() + 1, 0, 0);
+        }
+        else {
+            return next;
+        }
+    }
+    return null;
+}
+/** Approximate gap between runs in milliseconds, from the next two matches after `from`; used to size deadlines and staleness. */
+export function cronPeriodMs(schedule, from) {
+    const first = nextCronRun(schedule, from);
+    const second = first && nextCronRun(schedule, first);
+    return first && second ? second.getTime() - first.getTime() : null;
+}

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;
@@ -66,6 +65,76 @@ export interface NodeStatusRow {
     health: string;
     updated_at: string;
 }
+export interface BackupScheduleRow {
+    id: string;
+    project_id: string;
+    target: string;
+    type: string;
+    node_id: string | null;
+    config_json: string;
+    schedule: string;
+    jitter_seconds: number;
+    next_run_at: string;
+    last_run_at: string | null;
+    last_success_at: string | null;
+    last_status: string | null;
+    stale_notified_at: string | null;
+    deployment_id: string | null;
+    enabled: number;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface BackupRunRow {
+    id: string;
+    schedule_id: string | null;
+    project_id: string;
+    target: string;
+    type: string;
+    node_id: string | null;
+    command_id: string | null;
+    trigger: string;
+    state: string;
+    scheduled_for: string | null;
+    queued_at: string | null;
+    started_at: string | null;
+    finished_at: string | null;
+    snapshot_id: string | null;
+    size_bytes: number | null;
+    added_bytes: number | null;
+    duration_ms: number | null;
+    restic_version: string | null;
+    error: string | null;
+    actor: string | null;
+    deployment_version: string | null;
+    metadata_json: string | null;
+}
+export interface RestoreRunRow {
+    id: string;
+    project_id: string;
+    target: string;
+    node_id: string | null;
+    snapshot_id: string;
+    mode: 'in-place' | 'scratch';
+    scratch_volume: string | null;
+    safety_backup: number;
+    safety_run_id: string | null;
+    writers_json: string;
+    state: string;
+    command_id: string | null;
+    actor: string | null;
+    started_at: string | null;
+    state_changed_at: string | null;
+    finished_at: string | null;
+    error: string | null;
+}
+export interface BackupDestinationRow {
+    id: 'default';
+    url: string;
+    env_names_json: string;
+    checked_at: string | null;
+    check_result_json: string | null;
+    updated_at: string;
+}
 export interface SecretRow {
     id: string;
     project_id: string;
@@ -120,5 +189,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);
@@ -50,14 +70,15 @@ CREATE INDEX IF NOT EXISTS events_project_created ON events(project_id, created_
 CREATE TABLE IF NOT EXISTS api_tokens(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT NULL, token_hash TEXT UNIQUE NOT NULL, role TEXT NOT NULL, projects_json TEXT, created_at TEXT, created_by TEXT, last_used_at TEXT, expires_at TEXT, revoked_at TEXT);
 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);
+CREATE TABLE IF NOT EXISTS backup_destination(id TEXT PRIMARY KEY CHECK(id='default'), url TEXT NOT NULL, env_names_json TEXT NOT NULL, checked_at TEXT, check_result_json TEXT, updated_at TEXT);
+CREATE TABLE IF NOT EXISTS backup_schedules(id TEXT PRIMARY KEY, project_id TEXT NOT NULL, target TEXT NOT NULL, type TEXT NOT NULL, node_id TEXT, config_json TEXT NOT NULL, schedule TEXT NOT NULL, jitter_seconds INTEGER NOT NULL, next_run_at TEXT NOT NULL, last_run_at TEXT, last_success_at TEXT, last_status TEXT, stale_notified_at TEXT, deployment_id TEXT, enabled INTEGER NOT NULL DEFAULT 1, created_at TEXT, updated_at TEXT, UNIQUE(project_id, target));
+CREATE TABLE IF NOT EXISTS backup_runs(id TEXT PRIMARY KEY, schedule_id TEXT, project_id TEXT NOT NULL, target TEXT NOT NULL, type TEXT NOT NULL, node_id TEXT, command_id TEXT, trigger TEXT NOT NULL, state TEXT NOT NULL, scheduled_for TEXT, queued_at TEXT, started_at TEXT, finished_at TEXT, snapshot_id TEXT, size_bytes INTEGER, added_bytes INTEGER, duration_ms INTEGER, restic_version TEXT, error TEXT, actor TEXT, deployment_version TEXT, metadata_json TEXT);
+CREATE TABLE IF NOT EXISTS restore_runs(id TEXT PRIMARY KEY, project_id TEXT NOT NULL, target TEXT NOT NULL, node_id TEXT, snapshot_id TEXT NOT NULL, mode TEXT NOT NULL, scratch_volume TEXT, safety_backup INTEGER NOT NULL DEFAULT 1, safety_run_id TEXT, writers_json TEXT NOT NULL DEFAULT '[]', state TEXT NOT NULL, command_id TEXT, actor TEXT, started_at TEXT, state_changed_at TEXT, finished_at TEXT, error TEXT);
+CREATE TABLE IF NOT EXISTS service_holds(project_id TEXT NOT NULL, service TEXT NOT NULL, reason TEXT NOT NULL, restore_id TEXT, created_at TEXT, PRIMARY KEY(project_id, service));
+CREATE UNIQUE INDEX IF NOT EXISTS backup_runs_slot ON backup_runs(schedule_id, scheduled_for) WHERE trigger='schedule';
+CREATE INDEX IF NOT EXISTS backup_runs_target ON backup_runs(project_id, target, finished_at);
 `);
-    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

@@ -33,6 +33,13 @@ export interface ContainerInspect {
         Image?: string;
         Labels?: Record<string, string>;
         Env?: string[];
+        User?: string;
+        WorkingDir?: string;
+    };
+    HostConfig?: {
+        NetworkMode?: string;
+        Binds?: string[];
+        Mounts?: unknown[];
     };
     State?: {
         Status?: string;

package/dist/docker-api.js

@@ -19,8 +19,14 @@ export const isNotFound = (error) => error instanceof DockerError && error.statu
 /** Splits a reference into `fromImage` and `tag` for `POST /images/create`. */
 export function splitImageRef(ref) {
     const digest = ref.indexOf('@');
-    if (digest >= 0)
-        return { fromImage: ref.slice(0, digest), tag: ref.slice(digest + 1) };
+    if (digest >= 0) {
+        const name = ref.slice(0, digest);
+        const colon = name.lastIndexOf(':');
+        return {
+            fromImage: colon > name.lastIndexOf('/') ? name.slice(0, colon) : name,
+            tag: ref.slice(digest + 1),
+        };
+    }
     const colon = ref.lastIndexOf(':');
     if (colon > ref.lastIndexOf('/'))
         return { fromImage: ref.slice(0, colon), tag: ref.slice(colon + 1) };
@@ -396,8 +402,14 @@ export class DockerEngine {
         const { fromImage, tag } = splitImageRef(ref);
         const res = await this.request('POST', '/images/create', {
             query: { fromImage, tag },
+            // Docker uses Go's padded base64.URLEncoding; Node's base64url encoding omits required '='.
             headers: auth
-                ? { 'x-registry-auth': Buffer.from(JSON.stringify(auth)).toString('base64url') }
+                ? {
+                    'x-registry-auth': Buffer.from(JSON.stringify(auth))
+                        .toString('base64')
+                        .replaceAll('+', '-')
+                        .replaceAll('/', '_'),
+                }
                 : {},
         });
         await this.progress(res, `pull ${ref}`);

package/dist/live.d.ts

@@ -18,6 +18,8 @@ export type LiveRequest = {
     tty?: boolean;
     columns?: number;
     rows?: number;
+    /** `container` is only the template: run the command in a new container with its image, environment and mounts. */
+    oneOff?: boolean;
 } | {
     operation: 'logs';
     sessionId: string;
@@ -81,3 +83,9 @@ export declare class LiveOperationEngine {
     private output;
     private finish;
 }
+/**
+ * Runs `command` in a new container cloned from `template`: the same image, environment (secrets included),
+ * user, working directory, network and mounts, with no published ports and none of the service's labels, so
+ * reconciliation never mistakes it for the service. The container is removed when the command ends.
+ */
+export declare function startOneOff(docker: DockerApi, template: string, command: string[]): Promise<LiveProcess>;

package/dist/live.js

@@ -1,5 +1,6 @@
 import { EventEmitter } from 'node:events';
 import { LIVE_MAX_FRAME_BYTES } from "./protocol.js";
+import { LABEL_JOB } from "./container-spec.js";
 const identifier = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,255}$/;
 function object(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -22,6 +23,8 @@ function validate(value) {
             !value.command.every((arg) => typeof arg === 'string' && !arg.includes('\0') && Buffer.byteLength(arg) <= 32768) ||
             value.command[0].length === 0)
             throw new Error('Invalid exec command');
+        if (value.oneOff !== undefined && typeof value.oneOff !== 'boolean')
+            throw new Error('Invalid one-off flag');
         if (value.interactive !== undefined && typeof value.interactive !== 'boolean')
             throw new Error('Invalid interactive flag');
         if (value.tty !== undefined && typeof value.tty !== 'boolean')
@@ -187,6 +190,8 @@ export class LiveOperationEngine {
                 tail: request.tail ?? 100,
                 timestamps: request.timestamps,
             });
+        if (request.operation === 'exec' && request.oneOff)
+            return startOneOff(docker, request.container, request.command);
         const proc = await docker.execStart(request.container, {
             cmd: request.command,
             stdin: request.interactive !== false,
@@ -274,3 +279,82 @@ export class LiveOperationEngine {
         });
     }
 }
+/**
+ * Runs `command` in a new container cloned from `template`: the same image, environment (secrets included),
+ * user, working directory, network and mounts, with no published ports and none of the service's labels, so
+ * reconciliation never mistakes it for the service. The container is removed when the command ends.
+ */
+export async function startOneOff(docker, template, command) {
+    const source = await docker.inspectContainer(template);
+    const image = source.Config?.Image;
+    if (!image)
+        throw new Error('the service container has no image to run from');
+    const host = source.HostConfig ?? {};
+    const name = `tug-run-${Math.random().toString(36).slice(2, 10)}`;
+    const id = await docker.createContainer(name, {
+        Image: image,
+        Env: source.Config?.Env,
+        User: source.Config?.User || undefined,
+        WorkingDir: source.Config?.WorkingDir || undefined,
+        // Bypass the image's entrypoint script, like `docker exec`, so the command is exactly what was typed.
+        Entrypoint: command,
+        Cmd: [],
+        Labels: { [LABEL_JOB]: 'run' },
+        HostConfig: {
+            NetworkMode: host.NetworkMode,
+            ...(host.Binds?.length ? { Binds: host.Binds } : {}),
+            ...(host.Mounts?.length ? { Mounts: host.Mounts } : {}),
+        },
+    });
+    const remove = () => docker.removeContainer(id).catch(() => { });
+    try {
+        await docker.startContainer(id);
+        const logs = await docker.logs(id, { follow: true });
+        let killed = false;
+        const proc = Object.assign(new EventEmitter(), {
+            stdin: null,
+            stdout: logs.stdout,
+            stderr: logs.stderr,
+            kill: () => {
+                killed = true;
+                logs.kill();
+                void remove();
+                return true;
+            },
+        });
+        const drained = (stream) => new Promise((resolve) => {
+            if (stream.readableEnded || stream.destroyed)
+                return resolve();
+            stream.once('end', resolve);
+            stream.once('close', resolve);
+        });
+        // The exit code comes from the container, not from the log stream, which only ends once it is consumed.
+        void (async () => {
+            let code = -1;
+            while (!killed) {
+                const state = (await docker.inspectContainer(id).catch(() => undefined))?.State;
+                if (!state)
+                    break;
+                if (!state.Running && state.Status !== 'created') {
+                    code = state.ExitCode ?? -1;
+                    break;
+                }
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+            if (killed)
+                return;
+            // Give the consumer a moment to read the last output before the container goes away.
+            await Promise.race([
+                Promise.all([drained(logs.stdout), drained(logs.stderr)]),
+                new Promise((resolve) => setTimeout(resolve, 1500)),
+            ]);
+            await remove();
+            proc.emit('close', code, null);
+        })();
+        return proc;
+    }
+    catch (error) {
+        await remove();
+        throw error;
+    }
+}