@matthesketh/fleet 1.8.1 → 1.11.1

package/dist/core/backup/config.js

@@ -0,0 +1,80 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { requireEnv } from '../env.js';
+import { FleetError } from '../errors.js';
+import { isPseudoApp } from './types.js';
+// read at call time so test env overrides land. consumers that want the
+// resolved path should call backupConfigDir() / backupVaultDir().
+export function backupConfigDir() {
+    return process.env.FLEET_BACKUP_CONFIG_DIR ?? '/etc/fleet/backups';
+}
+// the vault holds the age-encrypted restic passwords — no safe default,
+// so an unset FLEET_BACKUP_VAULT_DIR is a hard error rather than a guess.
+export function backupVaultDir() {
+    return requireEnv('FLEET_BACKUP_VAULT_DIR');
+}
+export const DEFAULT_RETENTION = {
+    hourly: 24,
+    daily: 14,
+    weekly: 8,
+    monthly: 12,
+};
+export const DEFAULT_EXCLUDES = [
+    'node_modules',
+    '.next',
+    'dist',
+    'build',
+    'target',
+    '__pycache__',
+    '.cache',
+    '.venv',
+    'venv',
+    '.npm',
+    '.yarn',
+    'coverage',
+    '.pytest_cache',
+    '*.log',
+    '*.pid',
+    '*.lock',
+    '.DS_Store',
+    'tmp',
+];
+function configPath(app) {
+    return join(backupConfigDir(), `${app}.json`);
+}
+export function loadConfig(app) {
+    const path = configPath(app);
+    if (!existsSync(path))
+        return null;
+    const raw = JSON.parse(readFileSync(path, 'utf-8'));
+    // basic shape check
+    if (!raw.app || !Array.isArray(raw.paths) || !raw.retention) {
+        throw new FleetError(`malformed backup config at ${path}`);
+    }
+    return raw;
+}
+export function saveConfig(cfg) {
+    const dir = backupConfigDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    writeFileSync(configPath(cfg.app), JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+}
+export function listConfiguredApps() {
+    const dir = backupConfigDir();
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter(f => f.endsWith('.json'))
+        .map(f => f.slice(0, -5))
+        .sort();
+}
+export function validateAppName(app) {
+    if (!app)
+        throw new FleetError('app name required');
+    if (isPseudoApp(app))
+        return;
+    if (!/^[a-z0-9_][a-z0-9._-]{0,62}$/.test(app)) {
+        throw new FleetError(`invalid app name: ${app}`);
+    }
+}

package/dist/core/backup/detect.d.ts

@@ -0,0 +1,11 @@
+import { AppBackupConfig, DumpHook, Schedule } from './types.js';
+/** detect the db dump hook (if any) for a registered fleet app. matches by
+ * container image keyword: postgres/mysql/mongo/redis. */
+export declare function detectDumpHook(appName: string): DumpHook | undefined;
+/** detect named docker volumes attached to the app's containers. anonymous
+ * volumes (uuid names) are skipped — they're transient. */
+export declare function detectVolumes(appName: string): string[];
+/** decide a sensible default schedule based on whether the app has a db. */
+export declare function defaultScheduleFor(hasDump: boolean): Schedule;
+/** build a baseline config for a registered fleet app. */
+export declare function detectAppConfig(appName: string): AppBackupConfig | null;

package/dist/core/backup/detect.js

@@ -0,0 +1,71 @@
+import { existsSync } from 'node:fs';
+import { listContainers } from '../docker.js';
+import { execSafe } from '../exec.js';
+import { load as loadRegistry } from '../registry.js';
+import { DEFAULT_RETENTION, DEFAULT_EXCLUDES } from './config.js';
+/** detect the db dump hook (if any) for a registered fleet app. matches by
+ * container image keyword: postgres/mysql/mongo/redis. */
+export function detectDumpHook(appName) {
+    const all = listContainers();
+    const candidates = all.filter(c => c.name.startsWith(appName) ||
+        c.name.endsWith(`-${appName}`) ||
+        c.name === appName);
+    for (const c of candidates) {
+        const img = c.image.toLowerCase();
+        if (img.includes('postgres') || img.includes('postgis')) {
+            return { type: 'postgres', container: c.name };
+        }
+        if (img.startsWith('mysql') || img.includes('mariadb')) {
+            return { type: 'mysql', container: c.name };
+        }
+        if (img.includes('mongo')) {
+            return { type: 'mongo', container: c.name };
+        }
+        if (img.startsWith('redis')) {
+            return { type: 'redis', container: c.name };
+        }
+    }
+    return undefined;
+}
+/** detect named docker volumes attached to the app's containers. anonymous
+ * volumes (uuid names) are skipped — they're transient. */
+export function detectVolumes(appName) {
+    const r = execSafe('docker', ['ps', '-q', '--filter', `name=${appName}`], { timeout: 5_000 });
+    if (!r.ok)
+        return [];
+    const vols = new Set();
+    for (const cid of r.stdout.split('\n').filter(Boolean)) {
+        const v = execSafe('docker', ['inspect', cid, '--format', '{{range .Mounts}}{{if eq .Type "volume"}}{{.Name}}|{{end}}{{end}}'], { timeout: 5_000 });
+        for (const name of v.stdout.split('|').filter(Boolean)) {
+            // skip anonymous (uuid-looking)
+            if (!/^[0-9a-f]{60,}$/i.test(name)) {
+                vols.add(name);
+            }
+        }
+    }
+    return [...vols].sort();
+}
+/** decide a sensible default schedule based on whether the app has a db. */
+export function defaultScheduleFor(hasDump) {
+    return hasDump ? 'hourly' : 'daily';
+}
+/** build a baseline config for a registered fleet app. */
+export function detectAppConfig(appName) {
+    const reg = loadRegistry();
+    const app = reg.apps.find(a => a.name === appName);
+    if (!app)
+        return null;
+    const composeDir = app.composePath;
+    const paths = existsSync(composeDir) ? [composeDir] : [];
+    const dump = detectDumpHook(appName);
+    const volumes = detectVolumes(appName);
+    return {
+        app: appName,
+        schedule: defaultScheduleFor(!!dump),
+        paths,
+        exclude: DEFAULT_EXCLUDES,
+        volumes: volumes.length > 0 ? volumes : undefined,
+        preDump: dump,
+        retention: DEFAULT_RETENTION,
+    };
+}

package/dist/core/backup/dump.d.ts

@@ -0,0 +1,11 @@
+import { FleetError } from '../errors.js';
+import { DumpHook } from './types.js';
+export declare class DumpError extends FleetError {
+}
+/** returns the shell command that streams a database dump to stdout.
+ * caller pipes the output into `restic backup --stdin` via sh -c so the
+ * dump bytes flow kernel-to-kernel and never enter node's spawnSync
+ * buffer (which has a 1mb ceiling and dies on multi-gb dumps). */
+export declare function dumpStreamCommand(hook: DumpHook): string;
+/** filename used inside the restic snapshot for the dump stream. */
+export declare function dumpFilename(hook: DumpHook): string;

package/dist/core/backup/dump.js

@@ -0,0 +1,82 @@
+import { FleetError } from '../errors.js';
+export class DumpError extends FleetError {
+}
+/** sh single-quote escape — wraps s in '...' with embedded quotes escaped
+ * as '\''. safe even if s contains $, `, \, *, spaces, or single quotes. */
+function shq(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+/** returns the shell command that streams a database dump to stdout.
+ * caller pipes the output into `restic backup --stdin` via sh -c so the
+ * dump bytes flow kernel-to-kernel and never enter node's spawnSync
+ * buffer (which has a 1mb ceiling and dies on multi-gb dumps). */
+export function dumpStreamCommand(hook) {
+    switch (hook.type) {
+        case 'postgres': {
+            // postgres_user is set as env in shared-postgres compose; password
+            // auth not needed because pg_dumpall runs as the postgres unix user
+            // and gets peer auth on the unix socket inside the container.
+            const user = hook.user ? shq(hook.user) : `"$${hook.userEnv ?? 'POSTGRES_USER'}"`;
+            const inner = hook.db
+                ? `pg_dump -U ${user} -d ${shq(hook.db)} --no-owner --no-acl --clean --if-exists`
+                : `pg_dumpall -U ${user} --no-role-passwords`;
+            return `docker exec ${hook.container} sh -c ${shq(inner)}`;
+        }
+        case 'mysql': {
+            const user = hook.user ?? (hook.userEnv ? `\${${hook.userEnv}}` : 'root');
+            const dbFlag = hook.db ? shq(hook.db) : '--all-databases';
+            const passwordExpr = hook.passwordFile
+                ? `"$(cat ${shq(hook.passwordFile)})"`
+                : hook.passwordEnv
+                    ? `"\${${hook.passwordEnv}}"`
+                    : '"${MYSQL_ROOT_PASSWORD}"';
+            const inner = `mysqldump -u${user} -p${passwordExpr} --single-transaction --routines --triggers ${dbFlag}`;
+            return `docker exec ${hook.container} sh -c ${shq(inner)}`;
+        }
+        case 'mongo': {
+            const user = hook.user ?? (hook.userEnv ? `\${${hook.userEnv}}` : 'root');
+            const dbFlag = hook.db ? `--db=${shq(hook.db)}` : '';
+            const passwordExpr = hook.passwordFile
+                ? `"$(cat ${shq(hook.passwordFile)})"`
+                : hook.passwordEnv
+                    ? `"\${${hook.passwordEnv}}"`
+                    : '"${MONGO_INITDB_ROOT_PASSWORD}"';
+            const inner = `mongodump --archive --quiet --username ${user} --password ${passwordExpr} --authenticationDatabase admin ${dbFlag}`.trim();
+            return `docker exec ${hook.container} sh -c ${shq(inner)}`;
+        }
+        case 'redis': {
+            const portFlag = hook.port ? `-p ${hook.port}` : '';
+            // redis-cli --rdb writes to a tempfile, then we cat it. >/dev/null on
+            // the rdb step keeps redis-cli's progress chatter out of the stream.
+            // when a host command supplies the password, inject it via docker exec
+            // -e so it never lives on the redis-cli cmdline (which would show in
+            // ps inside the container).
+            if (hook.passwordHostCommand) {
+                const inner = `redis-cli --no-auth-warning ${portFlag} -a "$REDIS_PASSWORD" --rdb /tmp/dump.rdb >/dev/null && cat /tmp/dump.rdb`;
+                return `docker exec -e REDIS_PASSWORD="$(${hook.passwordHostCommand})" ${hook.container} sh -c ${shq(inner)}`;
+            }
+            const passwordExpr = hook.passwordFile
+                ? `"$(cat ${shq(hook.passwordFile)})"`
+                : hook.passwordEnv
+                    ? `"\${${hook.passwordEnv}}"`
+                    : '"${REDIS_PASSWORD:-}"';
+            const inner = `redis-cli --no-auth-warning ${portFlag} -a ${passwordExpr} --rdb /tmp/dump.rdb >/dev/null && cat /tmp/dump.rdb`;
+            return `docker exec ${hook.container} sh -c ${shq(inner)}`;
+        }
+        default:
+            throw new DumpError(`unsupported dump type: ${hook.type}`);
+    }
+}
+/** filename used inside the restic snapshot for the dump stream. */
+export function dumpFilename(hook) {
+    switch (hook.type) {
+        case 'postgres':
+            return `${hook.db ?? 'all'}.pg.sql`;
+        case 'mysql':
+            return `${hook.db ?? 'all'}.mysql.sql`;
+        case 'mongo':
+            return `${hook.db ?? 'all'}.mongo.archive`;
+        case 'redis':
+            return `dump.rdb`;
+    }
+}

package/dist/core/backup/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './config.js';
+export * from './unlock.js';
+export * from './repo.js';
+export * from './dump.js';
+export * from './system.js';
+export * from './cloudflare.js';
+export * from './schedule.js';
+export * from './detect.js';

package/dist/core/backup/index.js

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './config.js';
+export * from './unlock.js';
+export * from './repo.js';
+export * from './dump.js';
+export * from './system.js';
+export * from './cloudflare.js';
+export * from './schedule.js';
+export * from './detect.js';

package/dist/core/backup/repo.d.ts

@@ -0,0 +1,71 @@
+import { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { FleetError } from '../errors.js';
+import { Retention, SnapshotInfo, RepoStats } from './types.js';
+export declare const SFTP_HOST_ALIAS: string;
+export declare class ResticError extends FleetError {
+}
+/** true when the backend rejects deletions/rewrites (rest-server --append-only
+ *  in particular). primary-side prune must skip on such backends — pruning
+ *  happens locally on the backup vps via its own cron. */
+export declare function isAppendOnly(): boolean;
+export declare function initRepo(app: string): void;
+export interface BackupOptions {
+    paths: string[];
+    excludes?: string[];
+    tags?: string[];
+    /** add a host=... override (useful for restoring tests). */
+    hostname?: string;
+    /** when set, restic gets --stdin --stdin-filename and paths are ignored
+     *  (restic does not accept both). */
+    stdinFilename?: string;
+    /** small in-memory payloads piped via process stdin (~1mb safe). */
+    stdinData?: string;
+    /** for large/streaming payloads: a shell command whose stdout is piped
+     *  into `restic backup --stdin` via `sh -c "<cmd> | restic ..."`. avoids
+     *  the spawnSync 1mb buffer ceiling so multi-gb dumps work. */
+    stdinCommand?: string;
+    /** dry-run: restic walks paths and reports what would be added, no upload. */
+    dryRun?: boolean;
+}
+export declare function snapshot(app: string, opts: BackupOptions, timeoutMs?: number): SnapshotInfo;
+export declare function listSnapshots(app: string): SnapshotInfo[];
+export interface RestoreOptions {
+    snapshotId: string;
+    target: string;
+    /** restore only these subpaths (restic --include). */
+    include?: string[];
+    /** dry-run: list files that would be restored without writing. */
+    dryRun?: boolean;
+    /** post-restore integrity check: re-walks the restored tree and confirms
+     *  file contents match the snapshot's chunk hashes (restic --verify). */
+    verify?: boolean;
+}
+export interface TreeEntry {
+    name: string;
+    type: 'dir' | 'file';
+    path: string;
+    size: number;
+    mtime: string;
+}
+/** parses `restic ls --json` output into the direct children of dirPath.
+ *  restic ls recurses, so deeper descendants are filtered out here. */
+export declare function parseLsOutput(stdout: string, dirPath: string): TreeEntry[];
+/** lists the immediate children of dirPath within a snapshot. */
+export declare function lsTree(app: string, snapshotId: string, dirPath: string): TreeEntry[];
+/** the argv (after `restic`) for dumping a file from a snapshot. */
+export declare function dumpFileArgs(app: string, snapshotId: string, filePath: string): string[];
+/** spawns `restic dump`; caller pipes child.stdout to an http response and
+ *  must handle 'error' / non-zero 'close'. streaming avoids buffering a
+ *  potentially multi-gb file in node memory. */
+export declare function dumpFileSpawn(app: string, snapshotId: string, filePath: string): ChildProcessWithoutNullStreams;
+export declare function restore(app: string, opts: RestoreOptions, timeoutMs?: number): void;
+/** orthogonal integrity check: walks the restic repo, recomputes chunk
+ *  hashes, asserts the index is consistent. catches bit-rot on the
+ *  backup-vps disk. callable independently or right after a restore. */
+export declare function checkIntegrity(app: string, readDataPercent?: number): {
+    ok: boolean;
+    output: string;
+};
+export declare function prune(app: string, retention: Retention): void;
+export declare function check(app: string): boolean;
+export declare function stats(app: string): RepoStats | null;

package/dist/core/backup/repo.js

@@ -0,0 +1,256 @@
+import { spawn } from 'node:child_process';
+import { FleetError } from '../errors.js';
+import { execSafe } from '../exec.js';
+import { passwordCommandFor } from './unlock.js';
+export const SFTP_HOST_ALIAS = process.env.FLEET_BACKUP_SFTP_ALIAS ?? 'backup-vps-sftp';
+export class ResticError extends FleetError {
+}
+/** when fleet_backup_base_url is set we use it as the backend base — that
+ *  enables rest:// + append-only protection. when unset we fall back to the
+ *  legacy sftp alias. the systemd unit loads the url + rest creds from
+ *  encrypted credstore so they never sit on disk in plaintext. */
+function repoUri(app) {
+    const base = process.env.FLEET_BACKUP_BASE_URL;
+    if (base) {
+        return base.endsWith('/') ? `${base}${app}` : `${base}/${app}`;
+    }
+    return `sftp:${SFTP_HOST_ALIAS}:${app}`;
+}
+/** true when the backend rejects deletions/rewrites (rest-server --append-only
+ *  in particular). primary-side prune must skip on such backends — pruning
+ *  happens locally on the backup vps via its own cron. */
+export function isAppendOnly() {
+    return (process.env.FLEET_BACKUP_BASE_URL ?? '').startsWith('rest:');
+}
+function resticEnv(app) {
+    // restic respects restic_rest_username/password env vars; the wrapper
+    // populates them from the encrypted credstore.
+    const env = { RESTIC_PASSWORD_COMMAND: passwordCommandFor(app) };
+    if (process.env.RESTIC_REST_USERNAME)
+        env.RESTIC_REST_USERNAME = process.env.RESTIC_REST_USERNAME;
+    if (process.env.RESTIC_REST_PASSWORD)
+        env.RESTIC_REST_PASSWORD = process.env.RESTIC_REST_PASSWORD;
+    return env;
+}
+function runRestic(app, args, timeoutMs = 60_000) {
+    const r = execSafe('restic', ['-r', repoUri(app), ...args], {
+        timeout: timeoutMs,
+        env: resticEnv(app),
+    });
+    return { stdout: r.stdout, stderr: r.stderr, ok: r.ok };
+}
+export function initRepo(app) {
+    // if it already exists, snapshots --no-lock succeeds; only init when it doesn't.
+    const probe = runRestic(app, ['snapshots', '--no-lock', '--quiet'], 15_000);
+    if (probe.ok)
+        return;
+    const init = runRestic(app, ['init'], 30_000);
+    if (!init.ok)
+        throw new ResticError(`restic init failed: ${init.stderr}`);
+}
+/** sh single-quote escape — wraps s in '...' with embedded quotes as '\''. */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+export function snapshot(app, opts, timeoutMs = 30 * 60_000) {
+    const args = ['backup'];
+    if (opts.dryRun)
+        args.push('--dry-run');
+    for (const ex of opts.excludes ?? []) {
+        args.push('--exclude', ex);
+    }
+    for (const tag of opts.tags ?? []) {
+        args.push('--tag', tag);
+    }
+    if (opts.hostname) {
+        args.push('--host', opts.hostname);
+    }
+    if (opts.stdinFilename) {
+        // restic --stdin reads from stdin only; positional paths must be omitted.
+        args.push('--stdin', '--stdin-filename', opts.stdinFilename);
+    }
+    else {
+        args.push(...opts.paths);
+    }
+    args.push('--json');
+    let r;
+    if (opts.stdinCommand) {
+        // stream via bash — kernel pipes between the dump cmd and restic, so
+        // the dump bytes never enter node's spawnSync buffer. bash is used
+        // explicitly (rather than /bin/sh which is dash on ubuntu) because
+        // we need `pipefail` to surface dump errors that would otherwise be
+        // masked by restic's exit code.
+        const resticInvocation = ['restic', '-r', repoUri(app), ...args]
+            .map(shellQuote)
+            .join(' ');
+        const fullCmd = `set -eo pipefail; ${opts.stdinCommand} | ${resticInvocation}`;
+        if (process.env.FLEET_DEBUG_DUMP === '1') {
+            process.stderr.write(`[fleet-debug] bash -c: ${fullCmd}\n`);
+        }
+        r = execSafe('bash', ['-c', fullCmd], {
+            timeout: timeoutMs,
+            env: resticEnv(app),
+        });
+    }
+    else {
+        r = execSafe('restic', ['-r', repoUri(app), ...args], {
+            timeout: timeoutMs,
+            env: resticEnv(app),
+            input: opts.stdinData,
+        });
+    }
+    if (!r.ok)
+        throw new ResticError(`restic backup failed: ${r.stderr || r.stdout}`);
+    // last json line is the summary with snapshot_id (or counters for dry-run)
+    const lines = r.stdout.split('\n').filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const obj = JSON.parse(lines[i]);
+            if (obj.message_type === 'summary') {
+                return {
+                    id: obj.snapshot_id ?? 'dry-run',
+                    shortId: (obj.snapshot_id ?? 'dry-run').slice(0, 8),
+                    time: new Date().toISOString(),
+                    hostname: opts.hostname ?? '',
+                    paths: opts.paths,
+                    tags: opts.tags ?? [],
+                    sizeBytes: obj.data_added,
+                };
+            }
+        }
+        catch { /* not json, skip */ }
+    }
+    throw new ResticError(`could not parse restic snapshot summary`);
+}
+export function listSnapshots(app) {
+    const r = runRestic(app, ['snapshots', '--json'], 15_000);
+    if (!r.ok) {
+        if (r.stderr.includes('does not exist'))
+            return [];
+        throw new ResticError(`restic snapshots failed: ${r.stderr}`);
+    }
+    if (!r.stdout)
+        return [];
+    const arr = JSON.parse(r.stdout);
+    return arr.map(s => ({
+        id: s.id,
+        shortId: s.short_id,
+        time: s.time,
+        hostname: s.hostname,
+        paths: s.paths,
+        tags: s.tags ?? [],
+    }));
+}
+/** parses `restic ls --json` output into the direct children of dirPath.
+ *  restic ls recurses, so deeper descendants are filtered out here. */
+export function parseLsOutput(stdout, dirPath) {
+    const base = dirPath === '/' ? '' : dirPath.replace(/\/+$/, '');
+    const entries = [];
+    for (const line of stdout.split('\n')) {
+        if (!line)
+            continue;
+        let node;
+        try {
+            node = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (node.struct_type !== 'node')
+            continue;
+        const path = typeof node.path === 'string' ? node.path : '';
+        if (!path || !path.startsWith(base + '/'))
+            continue;
+        const rest = path.slice(base.length + 1);
+        if (rest.length === 0 || rest.includes('/'))
+            continue;
+        entries.push({
+            name: typeof node.name === 'string' ? node.name : rest,
+            type: node.type === 'dir' ? 'dir' : 'file',
+            path,
+            size: typeof node.size === 'number' ? node.size : 0,
+            mtime: typeof node.mtime === 'string' ? node.mtime : '',
+        });
+    }
+    entries.sort((a, b) => a.type === b.type ? a.name.localeCompare(b.name) : a.type === 'dir' ? -1 : 1);
+    return entries;
+}
+/** lists the immediate children of dirPath within a snapshot. */
+export function lsTree(app, snapshotId, dirPath) {
+    const r = runRestic(app, ['ls', snapshotId, '--json', dirPath], 60_000);
+    if (!r.ok) {
+        throw new ResticError(`restic ls failed for ${dirPath}: ${r.stderr || r.stdout}`);
+    }
+    return parseLsOutput(r.stdout, dirPath);
+}
+/** the argv (after `restic`) for dumping a file from a snapshot. */
+export function dumpFileArgs(app, snapshotId, filePath) {
+    return ['-r', repoUri(app), 'dump', snapshotId, filePath];
+}
+/** spawns `restic dump`; caller pipes child.stdout to an http response and
+ *  must handle 'error' / non-zero 'close'. streaming avoids buffering a
+ *  potentially multi-gb file in node memory. */
+export function dumpFileSpawn(app, snapshotId, filePath) {
+    return spawn('restic', dumpFileArgs(app, snapshotId, filePath), {
+        env: { ...process.env, ...resticEnv(app) },
+    });
+}
+export function restore(app, opts, timeoutMs = 60 * 60_000) {
+    const args = ['restore', opts.snapshotId, '--target', opts.target];
+    if (opts.dryRun)
+        args.push('--dry-run');
+    if (opts.verify)
+        args.push('--verify');
+    for (const inc of opts.include ?? []) {
+        args.push('--include', inc);
+    }
+    const r = runRestic(app, args, timeoutMs);
+    if (!r.ok)
+        throw new ResticError(`restic restore failed: ${r.stderr}`);
+}
+/** orthogonal integrity check: walks the restic repo, recomputes chunk
+ *  hashes, asserts the index is consistent. catches bit-rot on the
+ *  backup-vps disk. callable independently or right after a restore. */
+export function checkIntegrity(app, readDataPercent = 5) {
+    const r = runRestic(app, ['check', `--read-data-subset=${readDataPercent}%`], 30 * 60_000);
+    return { ok: r.ok, output: r.ok ? r.stdout : `${r.stdout}\n${r.stderr}`.trim() };
+}
+export function prune(app, retention) {
+    const args = ['forget', '--prune'];
+    if (retention.hourly)
+        args.push('--keep-hourly', String(retention.hourly));
+    if (retention.daily)
+        args.push('--keep-daily', String(retention.daily));
+    if (retention.weekly)
+        args.push('--keep-weekly', String(retention.weekly));
+    if (retention.monthly)
+        args.push('--keep-monthly', String(retention.monthly));
+    if (retention.yearly)
+        args.push('--keep-yearly', String(retention.yearly));
+    if (args.length === 2) {
+        throw new ResticError('retention is empty — refusing to forget all snapshots');
+    }
+    const r = runRestic(app, args, 5 * 60_000);
+    if (!r.ok)
+        throw new ResticError(`restic forget failed: ${r.stderr}`);
+}
+export function check(app) {
+    const r = runRestic(app, ['check', '--read-data-subset=5%'], 10 * 60_000);
+    return r.ok;
+}
+export function stats(app) {
+    const r = runRestic(app, ['stats', 'latest', '--json'], 15_000);
+    if (!r.ok || !r.stdout)
+        return null;
+    try {
+        const obj = JSON.parse(r.stdout);
+        return {
+            totalSize: obj.total_size ?? 0,
+            totalFileCount: obj.total_file_count ?? 0,
+            snapshotCount: obj.snapshots_count ?? 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/backup/schedule.d.ts

@@ -0,0 +1,17 @@
+import { Schedule } from './types.js';
+export declare const SYSTEMD_UNIT_DIR: string;
+export declare function timerUnitName(app: string): string;
+export declare function serviceUnitName(app: string): string;
+export interface ScheduleInstallResult {
+    timerPath: string;
+    timerContent: string;
+    sharedServicePath: string;
+    sharedServiceContent: string;
+    sharedServiceWrote: boolean;
+}
+/** plans the timer + service units. returns the unit file contents so callers
+ *  can show a dry-run. set apply=true to actually write+enable. */
+export declare function installScheduleUnits(app: string, schedule: Schedule, opts?: {
+    apply?: boolean;
+}): ScheduleInstallResult;
+export declare function disableSchedule(app: string): void;