@wpelevator/tug 0.11.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,9 +30,9 @@ 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 } from "./backup-restore.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";
 class WakeHub {
     cursors = new Map();
@@ -758,6 +761,7 @@ export async function createApp(options = {}) {
         WHERE ds.project_id=? AND ds.deployment_id != ? AND d.state IN (${states}) ORDER BY ds.created_at DESC LIMIT 1`, project, current?.current_deployment_id || '');
             if (!previousDs)
                 throw httpError(404, 'no previous deployment found');
+            assertArtifactsAvailable(JSON.parse(previousDs.state_json), `roll back to ${previousDs.version}`);
             const ts = now();
             const depId = id('dep');
             const previousState = JSON.parse(previousDs.state_json);
@@ -863,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;
@@ -882,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. */
@@ -896,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. */
@@ -934,10 +944,17 @@ export async function createApp(options = {}) {
         const global = ext.global === true;
         const labels = Array.isArray(placement.labels) ? placement.labels : [];
         const matched = nodeInfos.filter((node) => labels.every((label) => node.labels.includes(label)));
-        const pool = labels.length ? matched : nodeInfos;
+        // Explicit `placement.nodes` (without labels or global, which deploy resolves into nodes) bound the pool; scaling never re-homes a service off them.
+        const pinned = !labels.length && !global && Array.isArray(placement.nodes)
+            ? placement.nodes
+            : [];
+        const candidates = pinned.length
+            ? matched.filter((node) => pinned.includes(node.name))
+            : matched;
+        const pool = candidates;
         if (!pool.length)
-            throw httpError(400, labels.length
-                ? 'no healthy nodes match the service placement labels'
+            throw httpError(400, labels.length || pinned.length
+                ? 'no healthy nodes match the service placement'
                 : 'no nodes available for scaling');
         const selected = global ? pool : pool.slice(0, Math.min(replicas, pool.length));
         state.services[service].placement = {
@@ -1277,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;
     };
@@ -1363,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)
@@ -1377,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({
@@ -1407,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}`,
@@ -1428,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 || '');
@@ -1536,7 +1548,70 @@ export async function createApp(options = {}) {
     }
     // Previous-process builds cannot finish after a restart; clear their unpublished files.
     db.run("UPDATE deployments SET state='build_failed',error_message='control restarted during build' WHERE state IN ('uploading','building')");
+    /** Archives deleted by `image prune`, or missing from a backup taken without images, can no longer be deployed. */
+    async function markMissingArtifacts() {
+        for (const row of db.all("SELECT * FROM builds WHERE state='complete' AND artifact_path IS NOT NULL"))
+            if (!(await fs.stat(path.join(DATA_DIR, row.artifact_path)).catch(() => null)))
+                db.run("UPDATE builds SET state='pruned',artifact_path=NULL,updated_at=? WHERE id=?", now(), row.id);
+    }
+    /** Throws a 409 when a desired state needs a build archive that was pruned. */
+    function assertArtifactsAvailable(state, action) {
+        for (const [name, service] of Object.entries(state.services)) {
+            if (!service.artifact)
+                continue;
+            const build = db.get('SELECT * FROM builds WHERE id=?', service.artifact.buildId);
+            if (build?.state === 'pruned')
+                throw httpError(409, `cannot ${action}: the build archive of ${name} was pruned (tug image prune); deploy it again instead`);
+        }
+    }
+    /**
+     * Deletes build archives no longer needed: everything except the newest `keep` desired states of each project,
+     * the current deployment and any version a node still reports. The desired states stay, so history lists them,
+     * but rolling back to a pruned one is refused.
+     */
+    async function pruneArtifacts(keep, dryRun) {
+        const kept = new Set();
+        const reported = db
+            .all('SELECT project_id,status_json FROM node_statuses')
+            .map((row) => ({
+            project: row.project_id,
+            ...JSON.parse(row.status_json),
+        }));
+        const current = new Set(db
+            .all('SELECT current_deployment_id FROM projects')
+            .map((row) => row.current_deployment_id));
+        const rows = db.all('SELECT * FROM desired_states ORDER BY created_at DESC');
+        const seen = new Map();
+        for (const row of rows) {
+            const index = seen.get(row.project_id) ?? 0;
+            seen.set(row.project_id, index + 1);
+            const state = JSON.parse(row.state_json);
+            const lagging = reported.some((r) => r.project === row.project_id &&
+                r.observedVersion === state.version &&
+                (!r.observedRevision || r.observedRevision === state.revision));
+            if (index >= keep && !lagging && !current.has(row.deployment_id))
+                continue;
+            for (const service of Object.values(state.services))
+                if (service.artifact)
+                    kept.add(service.artifact.buildId);
+        }
+        const pruned = [];
+        for (const build of db.all("SELECT * FROM builds WHERE state='complete' AND artifact_path IS NOT NULL")) {
+            if (kept.has(build.id))
+                continue;
+            pruned.push({ id: build.id, service: build.service, sizeBytes: build.size_bytes });
+            if (dryRun)
+                continue;
+            await fs.rm(path.join(DATA_DIR, build.artifact_path), { force: true });
+            db.run("UPDATE builds SET state='pruned',artifact_path=NULL,updated_at=? WHERE id=?", now(), build.id);
+            const shared = db.get("SELECT 1 FROM builds WHERE image_ref=? AND state='complete'", build.image_ref);
+            if (!shared)
+                await images.run('docker', ['image', 'rm', build.image_ref]).catch(() => { });
+        }
+        return { pruned, freedBytes: pruned.reduce((sum, build) => sum + build.sizeBytes, 0) };
+    }
     await collectArtifacts();
+    await markMissingArtifacts();
     const receiveDeployment = upload.any();
     api('post', '/api/v1/deployments', null, (req, res) => {
         receiveDeployment(req, res, (error) => {
@@ -1547,6 +1622,25 @@ export async function createApp(options = {}) {
             });
         });
     });
+    /**
+     * Services that keep data on a node and are placed on different nodes by `compose` than by the current
+     * deployment. Deploying such a change starts the service empty on the new node: the data does not move.
+     */
+    function movedServices(project, compose) {
+        const current = currentDesired(project);
+        if (!current)
+            return [];
+        const before = JSON.parse(current.state_json);
+        return Object.entries(compose.services || {})
+            .filter(([name, svc]) => {
+            const old = before.services?.[name]?.placement?.nodes ?? [];
+            const next = svc['x-tug']?.placement?.nodes ?? [];
+            const keepsData = Boolean(svc['x-tug']?.backup) ||
+                (svc.volumes ?? []).some((mount) => typeof mount === 'object' && mount.type === 'volume');
+            return keepsData && old.length > 0 && next.length > 0 && old.some((n) => !next.includes(n));
+        })
+            .map(([name]) => name);
+    }
     async function deployRequest(req, res, uploadError) {
         const files = (Array.isArray(req.files) ? req.files : []);
         let responseBody;
@@ -1620,6 +1714,10 @@ export async function createApp(options = {}) {
                 throw httpError(400, errMessage(e));
             }
             assertIngressHostsFree(project, compose);
+            const acknowledgedMoves = Array.isArray(body.moves) ? body.moves.map(String) : [];
+            const unacknowledged = movedServices(project, compose).filter((name) => !acknowledgedMoves.includes(name));
+            if (unacknowledged.length)
+                throw httpError(409, `${unacknowledged.join(', ')} would start empty on a different node: its data does not move. Back it up, then deploy with --move ${unacknowledged.join(' --move ')} to hold the services that write to it, and run tug restore run <target> --confirm`);
             // The CLI interpolates control secrets as sentinels; a reference to a secret that is gone would deploy an empty value.
             const referenced = sentinelNames(compose);
             if (referenced.includes(REGISTRY_AUTH_SECRET))
@@ -1677,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);
@@ -1759,17 +1857,20 @@ 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.
+                    for (const moved of acknowledgedMoves.filter((name) => compose.services?.[name]))
+                        for (const writer of discoverWriters(compose, `service:${moved}`))
+                            if (!acknowledgedMoves.includes(writer))
+                                db.run('INSERT OR REPLACE INTO service_holds(project_id,service,reason,restore_id,created_at) VALUES(?,?,?,?,?)', project, writer, `moved ${moved}`, null, ts);
                     for (const [volumeName, volumeSpec] of Object.entries(compose.volumes || {})) {
                         const lp = volumeSpec?.['x-tug'] || {};
                         const nodeName = lp.placement?.nodes?.[0] || null;
@@ -1779,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',
@@ -1888,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';
@@ -1933,6 +2036,31 @@ export async function createApp(options = {}) {
             releaseLock(lock);
         }
     });
+    api('post', '/api/v1/holds/release', bodyProject, async (req, res) => withWriter(async () => {
+        const project = String(req.body?.project || 'site');
+        const services = Array.isArray(req.body?.services)
+            ? req.body.services.map(String)
+            : [];
+        // Only holds a deploy placed for a move; a restore's holds are dropped by `restore release`.
+        const rows = db.all('SELECT service FROM service_holds WHERE project_id=? AND restore_id IS NULL', project);
+        const released = rows
+            .map((row) => row.service)
+            .filter((service) => !services.length || services.includes(service));
+        for (const service of released)
+            db.run('DELETE FROM service_holds WHERE project_id=? AND service=? AND restore_id IS NULL', project, service);
+        wakeAll(project);
+        res.json({ ok: true, project, released });
+    }));
+    api('post', '/api/v1/images/prune', null, async (req, res) => withWriter(async () => {
+        const keep = req.body?.keep === undefined ? 5 : Number(req.body.keep);
+        if (!Number.isInteger(keep) || keep < 1)
+            return res.status(400).json({ error: 'keep must be a positive integer' });
+        res.json({
+            dryRun: Boolean(req.body?.dryRun),
+            keep,
+            ...(await pruneArtifacts(keep, Boolean(req.body?.dryRun))),
+        });
+    }));
     api('post', '/api/v1/control/backups/run', null, async (req, res) => withWriter(async () => {
         const backupDir = process.env.TUG_CONTROL_BACKUP_DIR || path.join(DATA_DIR, 'control-backups');
         // The archive holds the master key and the CA key, so nothing here is ever readable beyond the control user.
@@ -1954,14 +2082,16 @@ export async function createApp(options = {}) {
                 recursive: true,
                 filter: (src) => path.basename(src) !== 'server.json',
             });
-            await fs.cp(artifactDir, path.join(staging, 'images'), { recursive: true });
-            await fs.writeFile(path.join(staging, 'metadata.json'), JSON.stringify({ backupId, createdAt: ts, type: 'control' }, null, 2), { mode: 0o600 });
+            const withImages = req.body?.images !== false;
+            if (withImages)
+                await fs.cp(artifactDir, path.join(staging, 'images'), { recursive: true });
+            await fs.writeFile(path.join(staging, 'metadata.json'), JSON.stringify({ backupId, createdAt: ts, type: 'control', images: withImages }, null, 2), { mode: 0o600 });
             await tar.c({ gzip: true, file: artifactRef, cwd: staging, mode: 0o600 }, [
                 'tug.db',
                 'master.key',
                 'metadata.json',
                 'pki',
-                'images',
+                ...(withImages ? ['images'] : []),
             ]);
         }
         catch (error) {
@@ -2007,11 +2137,16 @@ export async function createApp(options = {}) {
             for (const secret of snapshot.all('SELECT * FROM secrets'))
                 decrypt(secret.encrypted_value, key);
             const states = snapshot.all('SELECT * FROM desired_states');
-            for (const stateRow of states) {
+            const meta = JSON.parse(await fs.readFile(path.join(restoreDir, 'metadata.json'), 'utf8').catch(() => '{}'));
+            // A backup taken without images restores the archive-less builds as pruned on the next start.
+            for (const stateRow of meta.images === false ? [] : states) {
                 const state = JSON.parse(stateRow.state_json);
                 for (const service of Object.values(state.services)) {
                     if (!service.artifact)
                         continue;
+                    // `image prune` already removed this one before the backup.
+                    if (snapshot.get("SELECT 1 FROM builds WHERE id=? AND state='pruned'", service.artifact.buildId))
+                        continue;
                     const build = snapshot.get('SELECT * FROM builds WHERE id=? AND state=?', service.artifact.buildId, 'complete');
                     if (!build?.artifact_path ||
                         !/^images\/build_[a-zA-Z0-9_-]+\.tar\.gz$/.test(build.artifact_path))
@@ -2117,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',
@@ -53,6 +58,8 @@ export const ROUTE_ROLES = {
     'DELETE /api/v1/backup/destination': 'admin',
     'GET /api/v1/backup/repository-password': 'admin',
     'POST /api/v1/control/backups/run': 'admin',
+    'POST /api/v1/images/prune': 'admin',
+    'POST /api/v1/holds/release': 'admin',
     'POST /api/v1/control/restore': 'admin',
     'GET /api/v1/diagnostics': 'admin',
     'POST /api/v1/diagnostics/nodes': 'admin',

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;
+};