@wpelevator/tug 0.4.0 → 0.6.0

package/dist/backup-scheduler.js

@@ -0,0 +1,403 @@
+import { cronPeriodMs, nextCronRun } from "./cron.js";
+import { resolveBackups } from "./backup-config.js";
+import { projectRepository } from "./backup-destination.js";
+import { volumeName } from "./container-spec.js";
+import { id } from "./util.js";
+import { isUniqueViolation } from "./db-driver.js";
+/** Pinned by tag; override on control with `TUG_RESTIC_IMAGE` (a digest reference is recommended for production). */
+export const DEFAULT_RESTIC_IMAGE = 'restic/restic:0.17.3';
+const MINUTE = 60_000;
+const DEFAULT_MEMORY = '512m';
+const RETRY_DELAY_MS = 10 * MINUTE;
+const AGENT_LOST_MS = 10 * MINUTE;
+const MAX_DEADLINE_MS = 6 * 3600_000;
+const MANUAL_DEADLINE_MS = 30 * MINUTE;
+const STALE_REPEAT_MS = 24 * 3600_000;
+const MAX_CATCH_UP_SLOTS = 20_000;
+function parse(json, fallback) {
+    try {
+        return json ? JSON.parse(json) : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Where a backup target runs, from the resolved desired state (labels are already resolved there). */
+export function targetNode(target, desired) {
+    if (target.kind === 'service') {
+        const nodes = desired.services[target.name]?.placement.nodes ?? [];
+        return nodes.length === 1 ? nodes[0] : undefined;
+    }
+    const placed = desired.compose.volumes?.[target.name]?.['x-tug']?.placement?.nodes ?? [];
+    if (placed.length)
+        return placed.length === 1 ? placed[0] : undefined;
+    const mounting = Object.entries(desired.compose.services).filter(([, svc]) => (svc.volumes ?? []).some((mount) => typeof mount === 'object' && mount.type === 'volume' && mount.source === target.name));
+    const nodes = [
+        ...new Set(mounting.flatMap(([name]) => desired.services[name]?.placement.nodes ?? [])),
+    ];
+    return nodes.length === 1 ? nodes[0] : undefined;
+}
+export function createBackupService(deps) {
+    const { db } = deps;
+    const clock = deps.clock ?? (() => new Date());
+    const resticImage = deps.resticImage || DEFAULT_RESTIC_IMAGE;
+    const redact = deps.redact ?? ((text) => text);
+    const started = clock().getTime();
+    const stamp = () => clock().toISOString();
+    const heartbeats = new Map();
+    const destination = () => db.get("SELECT * FROM backup_destination WHERE id='default'");
+    const nodeId = (name) => db.get('SELECT id FROM nodes WHERE name=?', name)?.id;
+    const nodeName = (nodeIdValue) => nodeIdValue
+        ? (db.get('SELECT name FROM nodes WHERE id=?', nodeIdValue)?.name ?? null)
+        : null;
+    function event(level, type, projectId, message, metadata, node, actor) {
+        db.run('INSERT INTO events(id,project_id,deployment_id,node_id,level,type,message,metadata_json,created_at,actor) VALUES(?,?,?,?,?,?,?,?,?,?)', id('evt'), projectId, null, node ?? null, level, type, message, JSON.stringify(metadata), stamp(), actor ?? null);
+    }
+    /** Desired states of projects whose current deployment succeeded. */
+    function deployed(projectId) {
+        const rows = db.all(`SELECT p.id AS project, ds.state_json, d.id AS deployment_id FROM projects p
+       JOIN deployments d ON d.id=p.current_deployment_id AND d.state='succeeded'
+       JOIN desired_states ds ON ds.deployment_id=d.id ${projectId ? 'WHERE p.id=?' : ''}`, ...(projectId ? [projectId] : []));
+        return rows.map((row) => ({
+            project: row.project,
+            desired: JSON.parse(row.state_json),
+            deploymentId: row.deployment_id,
+        }));
+    }
+    /** Brings `backup_schedules` in line with the current successful deployments. */
+    function sync(at = clock()) {
+        for (const { project, desired, deploymentId } of deployed()) {
+            const { targets } = resolveBackups(desired.compose, project);
+            const seen = new Set();
+            for (const target of targets) {
+                const node = targetNode(target, desired);
+                const config = JSON.stringify({ ...target, node });
+                const existing = db.get('SELECT * FROM backup_schedules WHERE project_id=? AND target=?', project, target.target);
+                seen.add(target.target);
+                const ts = stamp();
+                if (!existing) {
+                    const next = nextCronRun(target.schedule, at);
+                    if (!next)
+                        continue;
+                    db.run(`INSERT INTO backup_schedules(id,project_id,target,type,node_id,config_json,schedule,jitter_seconds,next_run_at,deployment_id,enabled,created_at,updated_at)
+             VALUES(?,?,?,?,?,?,?,?,?,?,1,?,?)`, id('bks'), project, target.target, target.type, node ? (nodeId(node) ?? null) : null, config, target.schedule, target.jitterSeconds, next.toISOString(), deploymentId, ts, ts);
+                    continue;
+                }
+                const scheduleChanged = existing.schedule !== target.schedule;
+                const next = scheduleChanged ? nextCronRun(target.schedule, at) : null;
+                db.run(`UPDATE backup_schedules SET type=?,node_id=?,config_json=?,schedule=?,jitter_seconds=?,deployment_id=?,enabled=1,next_run_at=?,updated_at=? WHERE id=?`, target.type, node ? (nodeId(node) ?? null) : null, config, target.schedule, target.jitterSeconds, deploymentId, next ? next.toISOString() : existing.next_run_at, ts, existing.id);
+            }
+            // A target that left the Compose file stops running; its snapshots stay in the repository.
+            for (const row of db.all('SELECT * FROM backup_schedules WHERE project_id=? AND enabled=1', project))
+                if (!seen.has(row.target))
+                    db.run('UPDATE backup_schedules SET enabled=0,updated_at=? WHERE id=?', stamp(), row.id);
+        }
+    }
+    function buildPayload(schedule, runId, trigger, desired, node) {
+        const config = parse(schedule.config_json, {});
+        const dest = destination();
+        const payload = {
+            runId,
+            project: schedule.project_id,
+            target: schedule.target,
+            type: config.type,
+            repository: projectRepository(dest.url, schedule.project_id),
+            resticImage,
+            node,
+            tags: [
+                'tug',
+                `project:${schedule.project_id}`,
+                `target:${schedule.target}`,
+                `type:${config.type}`,
+                `run:${runId}`,
+                `trigger:${trigger}`,
+            ],
+            retention: config.retention,
+            limits: { memory: DEFAULT_MEMORY, timeoutSec: config.timeoutSec },
+        };
+        if (config.kind === 'service') {
+            payload.command = {
+                service: config.name,
+                argv: config.command ?? [],
+                filename: config.filename ?? `${config.name}.out`,
+                verify: config.verify,
+                restoreArgv: config.restore,
+            };
+        }
+        else {
+            payload.volume = {
+                name: config.name,
+                dockerVolume: volumeName(schedule.project_id, config.name),
+                exclude: config.exclude,
+            };
+        }
+        return payload;
+    }
+    function insertRun(schedule, trigger, scheduledFor, state, extra = {}) {
+        const runId = extra.runId ?? id('bkr');
+        try {
+            db.run(`INSERT INTO backup_runs(id,schedule_id,project_id,target,type,node_id,command_id,trigger,state,scheduled_for,queued_at,finished_at,error,actor,deployment_version)
+         VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, runId, schedule.id, schedule.project_id, schedule.target, schedule.type, extra.nodeId ?? schedule.node_id, extra.commandId ?? null, trigger, state, scheduledFor, stamp(), state === 'queued' ? null : stamp(), extra.error ?? null, extra.actor ?? null, null);
+        }
+        catch (error) {
+            if (isUniqueViolation(error))
+                return null; // this slot already has a run
+            throw error;
+        }
+        return runId;
+    }
+    /** Queues one backup of a schedule's target; returns the run id, or why it could not be queued. */
+    function queueRun(schedule, trigger, scheduledFor, at, actor) {
+        const config = parse(schedule.config_json, {});
+        const fail = (error, type) => {
+            const runId = insertRun(schedule, trigger, scheduledFor, 'missed', { error, actor });
+            if (runId)
+                event('error', type, schedule.project_id, `backup of ${schedule.target} could not start: ${error}`, {
+                    runId,
+                    target: schedule.target,
+                    reason: error,
+                }, nodeName(schedule.node_id), actor);
+            return { error };
+        };
+        // A restore rewrites this target's data; a backup taken mid-restore would capture a half-restored state.
+        if (trigger !== 'pre-restore' &&
+            db.get("SELECT 1 FROM restore_runs WHERE project_id=? AND target=? AND mode='in-place' AND state NOT IN ('succeeded','failed','released')", schedule.project_id, schedule.target)) {
+            insertRun(schedule, trigger, scheduledFor, 'cancelled', { error: 'restore_in_progress' });
+            return { error: 'a restore of this target is in progress' };
+        }
+        if (!destination()) {
+            const runId = insertRun(schedule, trigger, scheduledFor, 'missed', {
+                error: 'no backup destination is configured',
+                actor,
+            });
+            if (runId)
+                event('warn', 'backup.no_destination', schedule.project_id, `backup of ${schedule.target} skipped: no backup destination is configured; run tug backup-destination-set`, {
+                    runId,
+                    target: schedule.target,
+                }, null, actor);
+            return { error: 'no backup destination is configured' };
+        }
+        const current = deployed(schedule.project_id)[0];
+        const node = current ? targetNode(config, current.desired) : undefined;
+        if (!current || !node || !schedule.node_id)
+            return fail('the target is not placed on exactly one node', 'backup.failed');
+        const runId = id('bkr');
+        const payload = buildPayload(schedule, runId, trigger, current.desired, node);
+        const period = cronPeriodMs(schedule.schedule, at) ?? MAX_DEADLINE_MS * 2;
+        const window = trigger === 'manual' || trigger === 'pre-restore'
+            ? MANUAL_DEADLINE_MS
+            : Math.min(period / 2, MAX_DEADLINE_MS);
+        const commandId = deps.queueCommand(schedule.node_id, schedule.project_id, 'backup.run', payload, new Date(at.getTime() + window).toISOString());
+        const inserted = insertRun(schedule, trigger, scheduledFor, 'queued', {
+            runId,
+            commandId,
+            actor,
+            nodeId: schedule.node_id,
+        });
+        if (!inserted) {
+            db.run("UPDATE commands SET state='cancelled' WHERE id=?", commandId);
+            return { error: 'this slot already has a run' };
+        }
+        return { runId };
+    }
+    /** Marks a run's schedule row with its latest outcome. */
+    function noteOutcome(run, status, at, success) {
+        if (!run.schedule_id)
+            return;
+        db.run(`UPDATE backup_schedules SET last_run_at=?,last_status=?${success ? ',last_success_at=?' : ''} WHERE id=?`, ...(success ? [at, status, at, run.schedule_id] : [at, status, run.schedule_id]));
+    }
+    function tick(at = clock()) {
+        sync(at);
+        const iso = at.toISOString();
+        // Commands the node never fetched before their deadline: the slot is missed, not silently dropped.
+        for (const run of db.all(`SELECT r.*, c.deadline FROM backup_runs r JOIN commands c ON c.id=r.command_id
+       WHERE r.state='queued' AND c.state IN ('pending','expired') AND c.deadline IS NOT NULL AND c.deadline<?`, iso)) {
+            db.run("UPDATE commands SET state='expired',updated_at=? WHERE id=?", iso, run.command_id);
+            db.run("UPDATE backup_runs SET state='missed',finished_at=?,error=? WHERE id=?", iso, 'node_offline', run.id);
+            noteOutcome(run, 'missed', iso, false);
+            event('error', 'backup.missed', run.project_id, `backup of ${run.target} missed: node ${nodeName(run.node_id) ?? ''} did not pick it up before its deadline`, {
+                runId: run.id,
+                target: run.target,
+                reason: 'node_offline',
+                lastSeenAt: db.get('SELECT last_seen_at FROM nodes WHERE id=?', run.node_id)?.last_seen_at ?? null,
+            }, nodeName(run.node_id));
+        }
+        // A job whose agent stopped reporting for ten minutes is lost.
+        for (const run of db.all("SELECT * FROM backup_runs WHERE state='running'")) {
+            const last = heartbeats.get(run.command_id ?? '') ?? started;
+            if (at.getTime() - last < AGENT_LOST_MS)
+                continue;
+            db.run("UPDATE backup_runs SET state='failed',finished_at=?,error=? WHERE id=?", iso, 'agent_lost', run.id);
+            db.run("UPDATE commands SET state='failed',updated_at=? WHERE id=? AND state='running'", iso, run.command_id);
+            noteOutcome(run, 'failed', iso, false);
+            event('error', 'backup.failed', run.project_id, `backup of ${run.target} failed: the agent stopped reporting`, {
+                runId: run.id,
+                target: run.target,
+                reason: 'agent_lost',
+            }, nodeName(run.node_id));
+        }
+        // Due slots. A slot long overdue (control was down) becomes one missed event and one catch-up run, never a burst.
+        for (const schedule of db.all('SELECT * FROM backup_schedules WHERE enabled=1 AND next_run_at<=?', iso)) {
+            const jitterMs = schedule.jitter_seconds * 1000;
+            const slot = new Date(schedule.next_run_at);
+            if (slot.getTime() + jitterMs > at.getTime())
+                continue;
+            const grace = Math.max(10 * MINUTE, jitterMs);
+            const lateness = at.getTime() - (slot.getTime() + jitterMs);
+            let next = nextCronRun(schedule.schedule, slot);
+            let latest = slot;
+            let missedSlots = 0;
+            if (lateness > grace) {
+                // Find the most recent slot that is not in the future; every earlier one is part of the gap.
+                for (let i = 0; next && next.getTime() <= at.getTime() && i < MAX_CATCH_UP_SLOTS; i++) {
+                    latest = next;
+                    missedSlots++;
+                    next = nextCronRun(schedule.schedule, next);
+                }
+                const runId = insertRun(schedule, 'schedule', latest.toISOString(), 'missed', {
+                    error: 'control_down',
+                });
+                if (runId)
+                    event('error', 'backup.missed', schedule.project_id, `backup of ${schedule.target} missed ${missedSlots + 1} scheduled run${missedSlots ? 's' : ''} while control was not running`, {
+                        runId,
+                        target: schedule.target,
+                        reason: 'control_down',
+                        gapMinutes: Math.round((at.getTime() - slot.getTime()) / MINUTE),
+                    }, nodeName(schedule.node_id));
+                noteOutcome({ schedule_id: schedule.id }, 'missed', iso, false);
+                queueRun(schedule, 'catch-up', null, at);
+            }
+            else {
+                queueRun(schedule, 'schedule', slot.toISOString(), at);
+            }
+            db.run('UPDATE backup_schedules SET next_run_at=? WHERE id=?', (next ?? new Date(at.getTime() + 24 * 3600_000)).toISOString(), schedule.id);
+        }
+        // One automatic retry, ten minutes after a scheduled run failed.
+        for (const run of db.all(`SELECT r.* FROM backup_runs r WHERE r.state='failed' AND r.trigger IN ('schedule','catch-up') AND r.finished_at<=?
+       AND NOT EXISTS (SELECT 1 FROM backup_runs x WHERE x.schedule_id=r.schedule_id AND x.trigger='retry' AND x.scheduled_for IS r.scheduled_for AND x.queued_at>=r.queued_at)`, new Date(at.getTime() - RETRY_DELAY_MS).toISOString())) {
+            const schedule = run.schedule_id
+                ? db.get('SELECT * FROM backup_schedules WHERE id=? AND enabled=1', run.schedule_id)
+                : undefined;
+            if (schedule)
+                queueRun(schedule, 'retry', run.scheduled_for, at);
+        }
+        // Independent of single runs: a target that has not succeeded for two periods is stale, even when each run failed alike.
+        for (const schedule of db.all('SELECT * FROM backup_schedules WHERE enabled=1')) {
+            const period = cronPeriodMs(schedule.schedule, at);
+            if (!period)
+                continue;
+            const since = new Date(schedule.last_success_at ?? schedule.created_at ?? iso).getTime();
+            if (at.getTime() - since <= 2 * period + 10 * MINUTE)
+                continue;
+            if (schedule.stale_notified_at &&
+                at.getTime() - new Date(schedule.stale_notified_at).getTime() < STALE_REPEAT_MS)
+                continue;
+            db.run('UPDATE backup_schedules SET stale_notified_at=? WHERE id=?', iso, schedule.id);
+            event('error', 'backup.stale', schedule.project_id, `backup of ${schedule.target} has not succeeded since ${schedule.last_success_at ?? 'it was configured'}`, {
+                target: schedule.target,
+                lastSuccessAt: schedule.last_success_at,
+            }, nodeName(schedule.node_id));
+        }
+    }
+    /** Heartbeats from `StatusReport.jobs`: a queued run becomes running, and a running one stays alive. */
+    function onHeartbeat(jobs) {
+        const at = clock().getTime();
+        for (const job of jobs) {
+            heartbeats.set(job.commandId, at);
+            db.run("UPDATE backup_runs SET state='running',started_at=COALESCE(started_at,?) WHERE command_id=? AND state='queued'", job.startedAt, job.commandId);
+        }
+    }
+    function onResult(commandId, state, result) {
+        const run = db.get('SELECT * FROM backup_runs WHERE command_id=?', commandId);
+        if (!run || ['succeeded', 'failed', 'missed', 'cancelled'].includes(run.state))
+            return;
+        const at = stamp();
+        heartbeats.delete(commandId);
+        if (state === 'succeeded') {
+            const r = result;
+            db.run(`UPDATE backup_runs SET state='succeeded',finished_at=?,snapshot_id=?,size_bytes=?,added_bytes=?,duration_ms=?,restic_version=?,metadata_json=? WHERE id=?`, at, r.snapshotId ?? null, r.totalBytes ?? null, r.addedBytes ?? null, r.durationMs ?? null, r.resticVersion ?? null, JSON.stringify({ warnings: r.warnings ?? [] }), run.id);
+            noteOutcome(run, 'succeeded', at, true);
+            db.run('UPDATE backup_schedules SET stale_notified_at=NULL WHERE id=?', run.schedule_id);
+            event('info', 'backup.completed', run.project_id, `backup of ${run.target} completed${r.snapshotId ? ` as snapshot ${r.snapshotId.slice(0, 8)}` : ''}`, {
+                runId: run.id,
+                target: run.target,
+                snapshotId: r.snapshotId,
+                addedBytes: r.addedBytes,
+                totalBytes: r.totalBytes,
+                durationMs: r.durationMs,
+                warnings: r.warnings,
+            }, nodeName(run.node_id), run.actor ?? undefined);
+            return;
+        }
+        const error = redact(result.error ?? 'the backup job failed').slice(0, 2000);
+        db.run("UPDATE backup_runs SET state='failed',finished_at=?,error=? WHERE id=?", at, error, run.id);
+        noteOutcome(run, 'failed', at, false);
+        event('error', 'backup.failed', run.project_id, `backup of ${run.target} failed: ${error}`, {
+            runId: run.id,
+            target: run.target,
+            error,
+        }, nodeName(run.node_id), run.actor ?? undefined);
+    }
+    /** Queues manual backups of the named targets, or every target of the project when none are named. */
+    function runNow(project, targets, actor, trigger = 'manual') {
+        sync();
+        const schedules = db.all('SELECT * FROM backup_schedules WHERE project_id=? AND enabled=1 ORDER BY target', project);
+        const wanted = targets?.length
+            ? targets.map((name) => (name.includes(':') ? name : undefined) ?? name)
+            : schedules.map((row) => row.target);
+        const runs = [];
+        const errors = [];
+        for (const name of wanted) {
+            const schedule = schedules.find((row) => row.target === name) ??
+                schedules.find((row) => row.target.endsWith(`:${name}`));
+            if (!schedule) {
+                errors.push(`${name} is not a backup target of project ${project}`);
+                continue;
+            }
+            const queued = queueRun(schedule, trigger, null, clock(), actor);
+            if ('error' in queued)
+                errors.push(`${schedule.target}: ${queued.error}`);
+            else
+                runs.push({ runId: queued.runId, target: schedule.target });
+        }
+        return { runs, errors };
+    }
+    function list(project, limit = 50) {
+        const targets = db
+            .all('SELECT * FROM backup_schedules WHERE project_id=? ORDER BY target', project)
+            .map((row) => ({
+            project: row.project_id,
+            target: row.target,
+            node: nodeName(row.node_id),
+            type: row.type,
+            schedule: row.schedule,
+            enabled: row.enabled === 1,
+            nextRunAt: row.next_run_at,
+            lastRunAt: row.last_run_at,
+            lastSuccessAt: row.last_success_at,
+            lastStatus: row.last_status,
+        }));
+        const runs = db.all('SELECT * FROM backup_runs WHERE project_id=? ORDER BY COALESCE(finished_at,queued_at) DESC LIMIT ?', project, limit);
+        return { targets, runs };
+    }
+    /** Queues the `backup.restore` job for a target on its node. */
+    function queueRestore(project, target, restore, runId) {
+        const schedule = db.get('SELECT * FROM backup_schedules WHERE project_id=? AND target=? AND enabled=1', project, target);
+        const current = deployed(project)[0];
+        if (!schedule || !current)
+            return { error: `${target} is not a backup target of project ${project}` };
+        if (!destination())
+            return { error: 'no backup destination is configured' };
+        const config = parse(schedule.config_json, {});
+        const node = targetNode(config, current.desired);
+        if (!node || !schedule.node_id)
+            return { error: 'the target is not placed on exactly one node' };
+        const payload = buildPayload(schedule, runId, 'manual', current.desired, node);
+        payload.restore = restore;
+        delete payload.retention;
+        const deadline = new Date(clock().getTime() + (config.timeoutSec + 10 * 60) * 1000);
+        const commandId = deps.queueCommand(schedule.node_id, project, 'backup.restore', payload, deadline.toISOString());
+        return { commandId, nodeId: schedule.node_id };
+    }
+    return { sync, tick, onHeartbeat, onResult, runNow, list, queueRestore };
+}

package/dist/build.d.ts

@@ -12,11 +12,10 @@ export interface BuildSpec {
 }
 export declare function run(cmd: string, args: string[], opts?: RunOptions): Promise<RunResult>;
 export declare function unpackContext(tarball: string, dest: string): Promise<void>;
-export interface BuildAndPushOptions {
+export interface BuildImageOptions {
     contextDir: string;
     service: string;
     buildSpec: string | BuildSpec;
     imageRef: string;
-    push?: boolean;
 }
-export declare function buildAndPush({ contextDir, service, buildSpec, imageRef, push, }: BuildAndPushOptions): Promise<void>;
+export declare function buildImage({ contextDir, service, buildSpec, imageRef, }: BuildImageOptions): Promise<void>;

package/dist/build.js

@@ -33,7 +33,7 @@ export async function unpackContext(tarball, dest) {
     });
     await tar.x({ file: tarball, cwd: dest, strict: true });
 }
-export async function buildAndPush({ contextDir, service, buildSpec, imageRef, push = true, }) {
+export async function buildImage({ contextDir, service, buildSpec, imageRef, }) {
     const buildPath = typeof buildSpec === 'string' ? buildSpec : buildSpec?.context || '.';
     const dockerfilePath = typeof buildSpec === 'object' && buildSpec.dockerfile
         ? path.resolve(contextDir, buildPath, buildSpec.dockerfile)
@@ -48,6 +48,4 @@ export async function buildAndPush({ contextDir, service, buildSpec, imageRef, p
     if (!(await exists(fullContext)))
         throw new Error(`build context not found for ${service}: ${buildPath}`);
     await run('docker', ['build', ...dockerfile, '-t', imageRef, fullContext]);
-    if (push)
-        await run('docker', ['push', imageRef]);
 }

package/dist/cli-build.d.ts

@@ -1,14 +1,14 @@
-import { buildAndPush } from './build.ts';
+import { buildImage } from './build.ts';
 import { saveImageArchive } from './artifacts.ts';
 import type { ComposeFile, LocalImageUpload } from './protocol.ts';
 export interface LocalBuildDependencies {
-    build: typeof buildAndPush;
+    build: typeof buildImage;
     save: typeof saveImageArchive;
     nonce: () => string;
     remove: (imageRef: string) => Promise<void>;
     cleanupWarning?: (message: string) => void;
 }
-/** Credential exclusions are mandatory and cannot be re-included by source ignore rules. */
+/** Credential exclusions are mandatory and cannot be re-included by source ignore rules. The tracked config names are excluded at the context root only, so an app's own nested `tug.json` is kept. */
 export declare function sourceArchiveFilter(entry: string, configPaths: string[], ignores: string[]): boolean;
 export declare function createSourceArchive(contextDir: string, archive: string, configFiles: string[]): Promise<void>;
 /** Build only application build services; callers own temporary files and upload transport. */

package/dist/cli-build.js

@@ -2,15 +2,28 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import * as tar from 'tar';
-import { buildAndPush, run } from "./build.js";
+import { buildImage, run } from "./build.js";
 import { saveImageArchive } from "./artifacts.js";
-/** Credential exclusions are mandatory and cannot be re-included by source ignore rules. */
+import { CONFIG_NAMES } from "./cli-config.js";
+/** At any depth: the git directory and every file that can hold a token (the untracked config overlays). */
+const ALWAYS_EXCLUDED = [
+    '.git',
+    '.tug.json',
+    '.tug.local.json',
+    'tug.local.yml',
+    'tug.local.yaml',
+    'tug.local.json',
+];
+/** Credential exclusions are mandatory and cannot be re-included by source ignore rules. The tracked config names are excluded at the context root only, so an app's own nested `tug.json` is kept. */
 export function sourceArchiveFilter(entry, configPaths, ignores) {
     const relative = entry
         .replaceAll('\\', '/')
         .replace(/^(\.\/)+/, '')
         .replace(/\/$/, '');
-    if (relative.split('/').some((part) => ['.git', '.tug.json'].includes(part)))
+    const parts = relative.split('/');
+    if (parts.some((part) => ALWAYS_EXCLUDED.includes(part)))
+        return false;
+    if (parts.length === 1 && CONFIG_NAMES.includes(relative))
         return false;
     return ![...configPaths, ...ignores].some((ignore) => relative === ignore || relative.startsWith(`${ignore}/`));
 }
@@ -18,7 +31,7 @@ export async function createSourceArchive(contextDir, archive, configFiles) {
     const configPaths = configFiles
         .map((file) => path.relative(contextDir, file).split(path.sep).join('/'))
         .filter((file) => file !== '..' && !file.startsWith('../') && !path.isAbsolute(file));
-    const ignores = ['node_modules', 'data', 'registry-data'];
+    const ignores = ['node_modules', 'data'];
     try {
         ignores.push(...(await fs.readFile(path.join(contextDir, '.dockerignore'), 'utf8'))
             .split(/\r?\n/)
@@ -38,7 +51,7 @@ export async function createSourceArchive(contextDir, archive, configFiles) {
 }
 /** Build only application build services; callers own temporary files and upload transport. */
 export async function prepareLocalImages(compose, contextDir, directory, dependencies = {
-    build: buildAndPush,
+    build: buildImage,
     save: saveImageArchive,
     nonce: randomUUID,
     remove: async (imageRef) => {
@@ -58,7 +71,6 @@ export async function prepareLocalImages(compose, contextDir, directory, depende
                 service,
                 buildSpec: spec.build,
                 imageRef,
-                push: false,
             });
             const archive = await dependencies.save(imageRef, path.join(directory, `${field}.tar.gz`));
             images.push({ service, imageRef, ...archive, field });

package/dist/cli-config.d.ts

@@ -1,20 +1,60 @@
-export interface CliConfig {
-    controlUrl?: string;
-    operatorToken?: string;
-    project?: string;
+export type SettingType = 'string' | 'boolean' | 'port' | 'list' | 'path';
+export interface Setting {
+    type: SettingType;
+    /** The flag or positional argument the key stands for; the key is the camelCase of the long flag. */
+    flag: string;
+    /** Commands that read the key as a default for `flag`. */
+    commands: string[];
 }
+/** Defaults for options of commands that work on the project (top level of the config file). */
+export declare const COMMAND_SETTINGS: Record<string, Setting>;
+/** Per-node connection data (`nodes.<name>`); `nodeDefaults` takes the subset that is not node-specific. */
+export declare const NODE_SETTINGS: Record<string, Setting>;
+/** Default file names, in lookup order; more than one present is an error. */
+export declare const CONFIG_NAMES: string[];
+export type SettingValues = Record<string, string | boolean | string[]>;
 export interface ConnectionOptions {
     config?: string;
     controlUrl?: string;
     project?: string;
 }
 export interface ResolvedCliConfig {
+    /** The tracked config: selected, discovered, or where `init` creates it. */
     file: string;
+    fileExists: boolean;
+    /** The untracked overlay next to `file`, the only place a token may be stored. */
+    localFile: string;
     controlUrl: string;
-    operatorToken?: string;
+    token?: string;
     project: string;
+    commandDefaults: SettingValues;
+    nodeDefaults: SettingValues;
+    nodes: Record<string, SettingValues>;
 }
+/** `tug.yml` becomes `tug.local.yml`, `.tug.json` becomes `.tug.local.json`. */
+export declare function localConfigPath(file: string): string;
 /** Resolve adapter settings once; domain operations receive these explicit values. */
 export declare function resolveCliConfig(options: ConnectionOptions, env: NodeJS.ProcessEnv, cwd: string, creating?: boolean): Promise<ResolvedCliConfig>;
+/** `nodeDefaults` under the node's own keys; a list in the node replaces the default list. */
+export declare function nodeSettings(config: ResolvedCliConfig, name?: string): SettingValues;
+interface OptionSource {
+    name(): string;
+    options: readonly {
+        attributeName(): string;
+    }[];
+    getOptionValueSource(key: string): string | undefined;
+}
+/**
+ * Use config values as defaults for the options of a command: a key applies to a command that lists it
+ * and has an option of that name, and never over a value given on the command line.
+ */
+export declare function applyConfigDefaults(command: OptionSource, values: object, settings: SettingValues): void;
+/**
+ * `tug init`: create the tracked file when it is missing and always store the token in the untracked
+ * overlay, git-ignoring it. An existing tracked file is never rewritten, so its comments survive;
+ * connection flags passed to `init` are saved to the overlay instead.
+ */
+export declare function writeInitConfig(config: ResolvedCliConfig, token: string, explicit: ConnectionOptions): Promise<string[]>;
 export declare function normalizeControlUrl(value: string): string;
 export declare function integerOption(value: string, name: string, minimum?: number, maximum?: number): number;
+export {};