@wpelevator/tug 0.12.0 → 0.13.0

package/dist/commands/service.js

@@ -1,21 +1,30 @@
+import { selectService } from "./selection.js";
 import { projectOf, request, runLive, waitForCommand } from "./context.js";
 export function registerService(program) {
     program
-        .command('exec <service> [command...]')
+        .command('exec [service] [command...]')
         .description('execute a command on a service container (default: sh)')
+        .option('--select', 'choose the service; all positional arguments are the remote command')
         .option('-i, --interactive', 'forward stdin to the remote command')
         .option('-t, --tty', 'allocate a terminal (requires a local terminal and agent TTY support)')
         .option('--node <name>', 'select the node when a service has multiple placements')
         .action(async (service, command, o) => {
+        if (o.select && service)
+            command.unshift(service);
+        service = await selectService(o.select ? undefined : service);
         await runLive('exec', { service, command, ...o });
     });
     program
-        .command('run <service> [command...]')
+        .command('run [service] [command...]')
         .description("run a one-off command in a new container from the service: same image, environment, secrets, network and mounts, removed afterwards (for example: tug run web -- wp core update-db). Exits with the command's exit code")
         .option('--node <name>', 'select the node when a service has multiple placements')
+        .option('--select', 'choose the service; all positional arguments are the remote command')
         .action(async (service, command, o) => {
+        if (o.select && service)
+            command.unshift(service);
         if (!command.length)
             throw new Error('run needs a command, such as: tug run web -- wp core update-db');
+        service = await selectService(o.select ? undefined : service);
         await runLive('exec', { service, command, node: o.node, oneOff: true });
     });
     program
@@ -26,25 +35,27 @@ export function registerService(program) {
         await runLive('ps', o);
     });
     program
-        .command('inspect <service>')
+        .command('inspect [service]')
         .description('print container details as JSON')
         .option('--node <name>', 'select one node')
         .action(async (service, o) => {
+        service = await selectService(service);
         await runLive('inspect', { service, ...o });
     });
     program
-        .command('logs <service>')
+        .command('logs [service]')
         .description('fetch service container logs from the node that runs the service')
         .option('--tail <n>', 'number of lines', '200')
         .option('-f, --follow', 'follow live logs')
         .option('--node <name>', 'select a node for followed logs')
         .action(async (svc, o) => {
+        if (o.node && !o.follow)
+            throw new Error('--node requires --follow for logs');
+        svc = await selectService(svc);
         if (o.follow) {
             await runLive('logs', { service: svc, node: o.node, tail: o.tail });
             return;
         }
-        if (o.node)
-            throw new Error('--node requires --follow for logs');
         const created = await request('POST', '/api/v1/logs', {
             project: await projectOf(o),
             service: svc,

package/dist/commands/volume.js

@@ -1,3 +1,4 @@
+import { selectResource } from "./selection.js";
 import { print, projectOf, request } from "./context.js";
 export function registerVolume(program) {
     const volume = program.command('volume').description("list and remove a project's volumes");
@@ -6,8 +7,8 @@ export function registerVolume(program) {
         .description('list the volumes of the project and where they live')
         .action(async (o) => print(await request('GET', `/api/v1/volumes?project=${encodeURIComponent(await projectOf(o))}`)));
     volume
-        .command('remove <name>')
+        .command('remove [name]')
         .description('remove a volume from the project')
         .option('--delete-data', 'delete underlying Docker volume data')
-        .action(async (name, o) => print(await request('DELETE', `/api/v1/volumes/${encodeURIComponent(name)}?project=${encodeURIComponent(await projectOf(o))}&deleteData=${Boolean(o.deleteData)}`)));
+        .action(async (name, o) => print(await request('DELETE', `/api/v1/volumes/${encodeURIComponent(await selectResource(name, 'volumes'))}?project=${encodeURIComponent(await projectOf(o))}&deleteData=${Boolean(o.deleteData)}`)));
 }

package/dist/control.js

@@ -15,6 +15,9 @@ import { WebSocketServer, WebSocket } from 'ws';
 import * as tar from 'tar';
 import { openDb, openSnapshotDb } from "./db.js";
 import { isUniqueViolation } from "./db-driver.js";
+import { lockQueries } from "./db-locks.js";
+import { backupDestinationQueries } from "./db-backup-destination.js";
+import { immediateTransaction } from "./db-transaction.js";
 import { encrypt, decrypt, loadOrCreateMasterKey } from "./secrets.js";
 import { buildDesiredState, ingressHostsOf, ingressHostsOverlap, loopbackIngressServices, serviceSecretNames, validateCompose, } from "./compose.js";
 import { buildImage, unpackContext, run as runCommand } from "./build.js";
@@ -27,7 +30,7 @@ import { isNodeHost } from "./node-address.js";
 import { buildIngressWork, ingressConfigHash, resolveServiceEndpoints } from "./ingress.js";
 import { parseStatusReport } from "./status-report.js";
 import { ACTIVE_DEPLOYMENT_STATES, LIVE_MAX_FRAME_BYTES, LIVE_MAX_BUFFERED_BYTES, LIVE_MAX_SESSIONS, LIVE_START_TIMEOUT_MS, BACKUP_COMMAND_TYPES, } from "./protocol.js";
-import { BACKUP_SECRET_PROJECT, isReservedProject, parseBackupDestination, projectRepository, repositoryPassword, redactSecrets, } from "./backup-destination.js";
+import { isReservedProject, parseBackupDestination, projectRepository, repositoryPassword, redactSecrets, } from "./backup-destination.js";
 import { createBackupService } from "./backup-scheduler.js";
 import { createRestoreService, discoverWriters } from "./backup-restore.js";
 import { AUTO_ROLLBACK_ACTOR, ROUTE_ROLES, PROJECT_NAME_PATTERN, authenticate, hasRole, assertProject, bodyProject, createGuard, createCredential, listCredentials, parseCredentialRequest, queryProject, recordEvent, revokeCredential, } from "./credentials.js";
@@ -864,18 +867,24 @@ export async function createApp(options = {}) {
     api('get', '/api/v1/live', null, (_req, res) => {
         res.status(426).json({ error: 'WebSocket upgrade required' });
     });
+    const locks = lockQueries(db);
     function acquireProjectLock(project, operation, ttlMs = Number(process.env.TUG_LOCK_TTL_MS || 10 * 60 * 1000)) {
         const name = `project:${project}`;
         const ts = now();
-        db.run('DELETE FROM locks WHERE expires_at < ?', ts);
+        locks.purgeExpired(ts);
         const owner = `${operation}:${id('lock')}`;
         try {
-            db.run('INSERT INTO locks(name,owner,expires_at,created_at) VALUES(?,?,?,?)', name, owner, new Date(Date.now() + ttlMs).toISOString(), ts);
+            locks.insert({
+                name,
+                owner,
+                expires_at: new Date(Date.now() + ttlMs).toISOString(),
+                created_at: ts,
+            });
         }
         catch (e) {
             if (!isUniqueViolation(e))
                 throw e;
-            const existing = db.get('SELECT * FROM locks WHERE name=?', name);
+            const existing = locks.find(name);
             const err = new Error(`project ${project} is locked by ${existing?.owner} until ${existing?.expires_at}`);
             err.status = 409;
             err.lock = existing;
@@ -883,7 +892,7 @@ export async function createApp(options = {}) {
         }
         const heartbeat = setInterval(() => {
             try {
-                db.run('UPDATE locks SET expires_at=? WHERE name=? AND owner=?', new Date(Date.now() + ttlMs).toISOString(), name, owner);
+                locks.renew(name, owner, new Date(Date.now() + ttlMs).toISOString());
             }
             catch {
                 /* Best-effort bookkeeping. */
@@ -897,7 +906,7 @@ export async function createApp(options = {}) {
             clearInterval(lock.heartbeat);
         if (lock)
             try {
-                db.run('DELETE FROM locks WHERE name=? AND owner=?', lock.name, lock.owner);
+                locks.release(lock.name, lock.owner);
             }
             catch {
                 /* Best-effort bookkeeping. */
@@ -1285,16 +1294,17 @@ export async function createApp(options = {}) {
         });
         res.json({ ok: true, name: String(req.params.name) });
     });
-    const backupDestination = () => db.get("SELECT * FROM backup_destination WHERE id='default'");
+    const destinationQueries = backupDestinationQueries(db);
+    const backupDestination = () => destinationQueries.find();
     const backupEnv = () => {
         const row = backupDestination();
         if (!row)
             return {};
         const env = {};
         for (const name of JSON.parse(row.env_names_json)) {
-            const secret = db.get('SELECT encrypted_value FROM secrets WHERE project_id=? AND name=?', BACKUP_SECRET_PROJECT, name);
+            const secret = destinationQueries.secret(name);
             if (secret)
-                env[name] = decrypt(secret.encrypted_value, masterKey);
+                env[name] = decrypt(secret, masterKey);
         }
         return env;
     };
@@ -1371,7 +1381,9 @@ export async function createApp(options = {}) {
             return res.status(started.status).json({ error: started.error });
         res.json({ confirmed: true, plan, ...started });
     });
-    api('get', '/api/v1/restores', queryProject, async (req, res) => res.json({ restores: restores.list(String(req.query.project || 'site')) }));
+    api('get', '/api/v1/restores', queryProject, async (req, res) => res.json({
+        restores: restores.list(String(req.query.project || 'site'), 20, req.query.state === 'interrupted'),
+    }));
     api('post', '/api/v1/restores/:id/release', null, async (req, res) => {
         const result = restores.releaseInterrupted(String(req.params.id));
         if ('error' in result)
@@ -1385,6 +1397,7 @@ export async function createApp(options = {}) {
         res.json(result);
     });
     api('get', '/api/v1/backups', queryProject, async (req, res) => {
+        backups.sync();
         const project = String(req.query.project || 'site');
         const limit = Math.min(Math.max(Number(req.query.limit) || 50, 1), 500);
         res.json({
@@ -1415,19 +1428,11 @@ export async function createApp(options = {}) {
             return res.status(400).json({ error: errMessage(e) });
         }
         const ts = now();
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            db.run('DELETE FROM secrets WHERE project_id=?', BACKUP_SECRET_PROJECT);
-            for (const [name, value] of Object.entries(parsed.env))
-                db.run('INSERT INTO secrets(id,project_id,name,encrypted_value,version,created_at,updated_at) VALUES(?,?,?,?,?,?,?)', id('sec'), BACKUP_SECRET_PROJECT, name, encrypt(value, masterKey), 1, ts, ts);
-            db.run(`INSERT INTO backup_destination(id,url,env_names_json,checked_at,check_result_json,updated_at) VALUES('default',?,?,NULL,NULL,?)
-        ON CONFLICT(id) DO UPDATE SET url=excluded.url,env_names_json=excluded.env_names_json,checked_at=NULL,check_result_json=NULL,updated_at=excluded.updated_at`, parsed.url, JSON.stringify(Object.keys(parsed.env).sort()), ts);
-            db.exec('COMMIT');
-        }
-        catch (e) {
-            db.exec('ROLLBACK');
-            throw e;
-        }
+        destinationQueries.replace(parsed.url, Object.entries(parsed.env).map(([name, value]) => ({
+            id: id('sec'),
+            name,
+            encryptedValue: encrypt(value, masterKey),
+        })), ts);
         audit(req.actor, {
             type: 'backup.destination_set',
             message: `backup destination set to ${parsed.url} by ${req.actor.name}`,
@@ -1436,14 +1441,13 @@ export async function createApp(options = {}) {
         res.json({ ok: true, url: parsed.url, envNames: Object.keys(parsed.env).sort() });
     });
     api('delete', '/api/v1/backup/destination', null, async (req, res) => {
-        db.run('DELETE FROM secrets WHERE project_id=?', BACKUP_SECRET_PROJECT);
-        const removed = db.run("DELETE FROM backup_destination WHERE id='default'");
-        if (removed.changes)
+        const removed = destinationQueries.remove();
+        if (removed)
             audit(req.actor, {
                 type: 'backup.destination_removed',
                 message: `backup destination removed by ${req.actor.name}`,
             });
-        res.json({ ok: true, removed: removed.changes > 0 });
+        res.json({ ok: true, removed });
     });
     api('get', '/api/v1/backup/repository-password', null, async (req, res) => {
         const project = String(req.query.project || '');
@@ -1771,7 +1775,7 @@ export async function createApp(options = {}) {
             lock = acquireProjectLock(project, 'deploy');
             const active = db.get(`SELECT * FROM deployments WHERE project_id=? AND state IN (${ACTIVE_STATES_SQL}) LIMIT 1`, project);
             if (active)
-                throw httpError(409, `deployment ${active.id} is already ${active.state}`);
+                throw httpError(409, `deployment ${active.id} is already ${active.state}; wait for it, or cancel it with: tug deploy cancel ${active.id}`);
             depId = id('dep');
             const ts = now();
             db.run('INSERT OR IGNORE INTO projects(id,name,created_at,updated_at) VALUES(?,?,?,?)', project, project, ts, ts);
@@ -1853,15 +1857,13 @@ export async function createApp(options = {}) {
             const buildLock = lock;
             const publishingId = depId;
             await withPublication(() => {
-                const owned = db.get('SELECT 1 FROM locks WHERE name=? AND owner=? AND expires_at>?', buildLock.name, buildLock.owner, now());
+                const owned = locks.owns(buildLock.name, buildLock.owner, now());
                 const pending = db.get('SELECT 1 FROM deployments WHERE id=? AND state=?', publishingId, 'building');
                 if (!owned || !pending)
                     throw httpError(409, 'deployment was cancelled or its build lease was lost');
-                db.exec('BEGIN IMMEDIATE');
-                try {
+                immediateTransaction(db, () => {
                     const published = db.run("UPDATE deployments SET state='rolling_out',updated_at=? WHERE id=? AND state='building'", now(), publishingId);
-                    if (published.changes !== 1 ||
-                        !db.get('SELECT 1 FROM locks WHERE name=? AND owner=? AND expires_at>?', buildLock.name, buildLock.owner, now()))
+                    if (published.changes !== 1 || !locks.owns(buildLock.name, buildLock.owner, now()))
                         throw httpError(409, 'deployment was cancelled or its build lease was lost');
                     db.run('INSERT INTO desired_states(id,project_id,deployment_id,version,state_json,created_at) VALUES(?,?,?,?,?,?)', id('ds'), project, publishingId, version, JSON.stringify(desired), ts);
                     // The moved service starts empty: keep what writes to it stopped until its data is restored.
@@ -1878,17 +1880,7 @@ export async function createApp(options = {}) {
                         db.run(`INSERT INTO volumes(id,project_id,name,type,driver,node_id,config_json,created_at,updated_at) VALUES(?,?,?,?,?,?,?,?,?) ON CONFLICT(project_id,name) DO UPDATE SET type=excluded.type,driver=excluded.driver,node_id=excluded.node_id,config_json=excluded.config_json,updated_at=excluded.updated_at`, id('vol'), project, volumeName, lp.type || 'local', lp.driver || null, node?.id || null, JSON.stringify(lp), ts, ts);
                     }
                     db.run('UPDATE projects SET current_deployment_id=?,updated_at=? WHERE id=?', publishingId, now(), project);
-                    db.exec('COMMIT');
-                }
-                catch (e) {
-                    try {
-                        db.exec('ROLLBACK');
-                    }
-                    catch {
-                        /* Preserve the publication error. */
-                    }
-                    throw e;
-                }
+                });
             });
             audit(req.actor, {
                 type: 'deploy',
@@ -1987,9 +1979,21 @@ export async function createApp(options = {}) {
             sendError(res, e);
         }
     }));
-    api('get', '/api/v1/volumes', queryProject, async (req, res) => res.json({
-        volumes: db.all('SELECT * FROM volumes WHERE project_id=? ORDER BY name', String(req.query.project || 'site')),
-    }));
+    api('get', '/api/v1/volumes', queryProject, async (req, res) => {
+        const project = String(req.query.project || 'site');
+        const desired = currentDesired(project);
+        const state = desired ? JSON.parse(desired.state_json) : undefined;
+        const volumes = db.all('SELECT v.*,n.name AS node FROM volumes v LEFT JOIN nodes n ON n.id=v.node_id WHERE v.project_id=? ORDER BY v.name', project);
+        res.json({
+            volumes: volumes.map((volume) => ({
+                ...volume,
+                persistent: Boolean(JSON.parse(volume.config_json || '{}').persistent || volume.type !== 'ephemeral'),
+                usedBy: Object.entries(state?.compose?.services || {})
+                    .filter(([, service]) => (service.volumes || []).some((mount) => (typeof mount === 'string' ? mount.split(':')[0] : mount.source) === volume.name))
+                    .map(([name]) => name),
+            })),
+        });
+    });
     api('delete', '/api/v1/volumes/:name', queryProject, async (req, res) => {
         const project = String(req.query.project || 'site');
         const deleteData = String(req.query.deleteData || 'false') === 'true';
@@ -2248,6 +2252,50 @@ export async function createApp(options = {}) {
         res.json({ commandId: cmdId, nodeId: node.id });
     });
     api('get', '/api/v1/commands/:id', commandProject, async (req, res) => res.json(db.get('SELECT * FROM commands WHERE id=?', String(req.params.id))));
+    api('get', '/api/v1/projects', null, async (req, res) => {
+        const scope = projectScope(req.actor, 'id');
+        res.json({
+            projects: db.all(`SELECT id AS name FROM projects WHERE ${scope.where} ORDER BY id`, ...scope.args),
+        });
+    });
+    api('get', '/api/v1/services', queryProject, async (req, res) => {
+        const project = String(req.query.project || 'site');
+        const row = currentDesired(project);
+        const desired = row ? JSON.parse(row.state_json) : undefined;
+        const nodes = db.all('SELECT * FROM nodes ORDER BY name');
+        res.json({
+            services: Object.entries(desired?.services || {})
+                .map(([name, service]) => ({
+                name,
+                nodes: nodes
+                    .filter((node) => !service.placement?.nodes?.length || service.placement.nodes.includes(node.name))
+                    .map((node) => ({
+                    name: node.name,
+                    status: node.disabled_at ? 'disabled' : isStale(node) ? 'stale' : node.status,
+                })),
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name)),
+        });
+    });
+    api('get', '/api/v1/deployments', queryProject, async (req, res) => {
+        res.json({
+            deployments: db.all(`SELECT id,project_id,version,state,created_at FROM deployments WHERE project_id=? AND state IN (${ACTIVE_STATES_SQL}) ORDER BY created_at DESC,id`, String(req.query.project || 'site')),
+        });
+    });
+    api('get', '/api/v1/backup/snapshots', queryProject, async (req, res) => {
+        const project = String(req.query.project || 'site');
+        const target = String(req.query.target || '');
+        if (!target)
+            throw httpError(400, 'target is required');
+        res.json({
+            snapshots: db.all(`SELECT id,target,snapshot_id,finished_at,size_bytes,trigger FROM backup_runs WHERE project_id=? AND target=? AND state='succeeded' AND snapshot_id IS NOT NULL ORDER BY finished_at DESC,id`, project, target),
+        });
+    });
+    api('get', '/api/v1/holds', queryProject, async (req, res) => {
+        res.json({
+            holds: db.all('SELECT service,reason,created_at FROM service_holds WHERE project_id=? AND restore_id IS NULL ORDER BY service', String(req.query.project || 'site')),
+        });
+    });
     api('get', '/api/v1/status', null, async (req, res) => {
         const staleSeconds = Number(process.env.TUG_STALE_SECONDS || 60);
         const cutoff = new Date(Date.now() - staleSeconds * 1000).toISOString();

package/dist/credentials.js

@@ -18,6 +18,11 @@ const LAST_USED_INTERVAL_MS = 60_000;
  */
 export const ROUTE_ROLES = {
     'GET /api/v1/live': 'deploy',
+    'GET /api/v1/services': 'read',
+    'GET /api/v1/projects': 'read',
+    'GET /api/v1/deployments': 'read',
+    'GET /api/v1/backup/snapshots': 'read',
+    'GET /api/v1/holds': 'admin',
     'GET /api/v1/status': 'read',
     'GET /api/v1/events': 'read',
     'GET /api/v1/projects/:project': 'read',

package/dist/db-backup-destination.d.ts

@@ -0,0 +1,14 @@
+import type { BackupDestinationRow, Db } from './db.ts';
+interface DestinationSecret {
+    id: string;
+    name: string;
+    encryptedValue: string;
+}
+/** Accepts encrypted values only. Encryption and credential parsing belong to the caller. */
+export declare function backupDestinationQueries(db: Db): {
+    find(): BackupDestinationRow | undefined;
+    secret(name: string): string | undefined;
+    replace(url: string, secrets: DestinationSecret[], at: string): void;
+    remove(): boolean;
+};
+export {};

package/dist/db-backup-destination.js

@@ -0,0 +1,28 @@
+import { BACKUP_SECRET_PROJECT } from "./backup-destination.js";
+import { immediateTransaction } from "./db-transaction.js";
+/** Accepts encrypted values only. Encryption and credential parsing belong to the caller. */
+export function backupDestinationQueries(db) {
+    return {
+        find() {
+            return db.get("SELECT * FROM backup_destination WHERE id='default'");
+        },
+        secret(name) {
+            return db.get('SELECT encrypted_value FROM secrets WHERE project_id=? AND name=?', BACKUP_SECRET_PROJECT, name)?.encrypted_value;
+        },
+        replace(url, secrets, at) {
+            immediateTransaction(db, () => {
+                db.run('DELETE FROM secrets WHERE project_id=?', BACKUP_SECRET_PROJECT);
+                for (const secret of secrets)
+                    db.run('INSERT INTO secrets(id,project_id,name,encrypted_value,version,created_at,updated_at) VALUES(?,?,?,?,?,?,?)', secret.id, BACKUP_SECRET_PROJECT, secret.name, secret.encryptedValue, 1, at, at);
+                db.run(`INSERT INTO backup_destination(id,url,env_names_json,checked_at,check_result_json,updated_at) VALUES('default',?,?,NULL,NULL,?)
+          ON CONFLICT(id) DO UPDATE SET url=excluded.url,env_names_json=excluded.env_names_json,checked_at=NULL,check_result_json=NULL,updated_at=excluded.updated_at`, url, JSON.stringify(secrets.map((secret) => secret.name).sort()), at);
+            });
+        },
+        remove() {
+            return immediateTransaction(db, () => {
+                db.run('DELETE FROM secrets WHERE project_id=?', BACKUP_SECRET_PROJECT);
+                return db.run("DELETE FROM backup_destination WHERE id='default'").changes > 0;
+            });
+        },
+    };
+}

package/dist/db-locks.d.ts

@@ -0,0 +1,10 @@
+import type { Db, LockRow } from './db.ts';
+/** SQL persistence only; callers own lease clocks, heartbeats and conflict responses. */
+export declare function lockQueries(db: Db): {
+    purgeExpired(at: string): void;
+    insert(lock: LockRow): void;
+    find(name: string): LockRow | undefined;
+    owns(name: string, owner: string, at: string): boolean;
+    renew(name: string, owner: string, expiresAt: string): void;
+    release(name: string, owner: string): void;
+};

package/dist/db-locks.js

@@ -0,0 +1,23 @@
+/** SQL persistence only; callers own lease clocks, heartbeats and conflict responses. */
+export function lockQueries(db) {
+    return {
+        purgeExpired(at) {
+            db.run('DELETE FROM locks WHERE expires_at < ?', at);
+        },
+        insert(lock) {
+            db.run('INSERT INTO locks(name,owner,expires_at,created_at) VALUES(?,?,?,?)', lock.name, lock.owner, lock.expires_at, lock.created_at);
+        },
+        find(name) {
+            return db.get('SELECT * FROM locks WHERE name=?', name);
+        },
+        owns(name, owner, at) {
+            return Boolean(db.get('SELECT 1 FROM locks WHERE name=? AND owner=? AND expires_at>?', name, owner, at));
+        },
+        renew(name, owner, expiresAt) {
+            db.run('UPDATE locks SET expires_at=? WHERE name=? AND owner=?', expiresAt, name, owner);
+        },
+        release(name, owner) {
+            db.run('DELETE FROM locks WHERE name=? AND owner=?', name, owner);
+        },
+    };
+}

package/dist/db-transaction.d.ts

@@ -0,0 +1,3 @@
+import type { Db } from './db-driver.ts';
+/** Run synchronous work in an immediate transaction. Nested transactions are rejected by SQLite. */
+export declare function immediateTransaction<T>(db: Db, operation: () => T & (T extends PromiseLike<unknown> ? never : unknown)): T;

package/dist/db-transaction.js

@@ -0,0 +1,24 @@
+/** Run synchronous work in an immediate transaction. Nested transactions are rejected by SQLite. */
+export function immediateTransaction(db, operation) {
+    // Keep BEGIN outside the catch: a failed BEGIN must not roll back somebody else's transaction.
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const result = operation();
+        if (result !== null &&
+            (typeof result === 'object' || typeof result === 'function') &&
+            'then' in result &&
+            typeof result.then === 'function')
+            throw new TypeError('Database transactions require synchronous callbacks');
+        db.exec('COMMIT');
+        return result;
+    }
+    catch (error) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch {
+            /* Preserve the operation or commit failure. */
+        }
+        throw error;
+    }
+}

package/dist/image.d.ts

@@ -7,3 +7,12 @@ export declare function packageVersion(): string;
 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;
+/**
+ * Fails before any host is touched when the published image for this CLI version does not exist yet. A release
+ * publishes the npm package a few minutes before its image, so a fresh CLI can briefly name a missing tag. Only a
+ * definitive "no such manifest" answer fails; no Docker, no network or a private registry carry on silently.
+ */
+export declare function assertImagePublished(image: string, inspect?: (image: string) => {
+    status: number | null;
+    stderr: string;
+}): void;

package/dist/image.js

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -18,3 +19,21 @@ export function defaultImage(version = packageVersion()) {
 export function resolveImage(image, buildLocalImage = false, version = packageVersion()) {
     return image || (buildLocalImage ? LOCAL_IMAGE : defaultImage(version));
 }
+/**
+ * Fails before any host is touched when the published image for this CLI version does not exist yet. A release
+ * publishes the npm package a few minutes before its image, so a fresh CLI can briefly name a missing tag. Only a
+ * definitive "no such manifest" answer fails; no Docker, no network or a private registry carry on silently.
+ */
+export function assertImagePublished(image, inspect = (ref) => {
+    const result = spawnSync('docker', ['manifest', 'inspect', ref], {
+        encoding: 'utf8',
+        timeout: 20_000,
+    });
+    return { status: result.status, stderr: String(result.stderr ?? '') };
+}) {
+    if (!image.startsWith(`${IMAGE_REPOSITORY}:`))
+        return;
+    const result = inspect(image);
+    if (result.status !== 0 && /no such manifest|manifest unknown|not found/i.test(result.stderr))
+        throw new Error(`${image} is not published yet: a release builds its image a few minutes after the npm package. Retry shortly, or pass --image ${IMAGE_REPOSITORY}:latest to use the latest release.`);
+}

package/dist/util.d.ts

@@ -20,3 +20,5 @@ export declare const isDuration: (value: unknown) => boolean;
  * interface. Hostnames and other non-IP strings return false.
  */
 export declare function isPublicAddress(address: string): boolean;
+/** Node's fetch reports every network failure as "fetch failed"; the system error that explains it is on `cause`. */
+export declare function describeFetchError(error: unknown): string;

package/dist/util.js

@@ -90,3 +90,9 @@ export function isPublicAddress(address) {
     }
     return false;
 }
+/** Node's fetch reports every network failure as "fetch failed"; the system error that explains it is on `cause`. */
+export function describeFetchError(error) {
+    const e = error;
+    const cause = e?.cause?.code || e?.cause?.message;
+    return cause ? `${e?.message ?? 'error'} (${cause})` : errMessage(error);
+}