parrot-blackbox 1.0.0

package/src/commands/setup.js

@@ -0,0 +1,214 @@
+/**
+ * Interactive setup wizard (default command, like gitswitch/theamify).
+ * Walks: dependency check + AUTO-INSTALL → rclone remotes (accounts) →
+ * schedule overview → always-on service install → optional first backup.
+ */
+
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { execa } from 'execa';
+import { loadConfig, journal, hasCommandSync } from '../core/store.js';
+import { listRemotes } from '../storage/rclone.js';
+import { addAccount, listAccounts, refreshAccounts, poolSummary } from '../storage/accounts.js';
+import { installService } from './service.js';
+import { runDueJobs } from '../daemon/scheduler.js';
+import { isOnline } from '../util/network.js';
+import { bytesHuman } from '../util/misc.js';
+
+const REQUIRED = [
+  { bin: 'rclone', pkg: 'rclone', why: 'talks to MEGA / Google Drive (cloud storage)' },
+  { bin: 'timeshift', pkg: 'timeshift', why: 'system snapshots — create AND restore' },
+  { bin: 'git', pkg: 'git', why: 'skip GitHub-tracked files' },
+  { bin: 'curl', pkg: 'curl', why: 'connectivity checks' },
+];
+
+/** Detect the distro package manager (apt/dnf/yum/pacman/zypper/apk). */
+function detectPackageManager() {
+  const order = ['apt-get', 'dnf', 'yum', 'pacman', 'zypper', 'apk'];
+  return order.find((name) => hasCommandSync(name)) || null;
+}
+
+/**
+ * Auto-install the tools the system needs for snapshot backup & restore.
+ * Prompts per missing tool, then runs the package-manager install with an
+ * interactive sudo prompt (spinner released first, Ctrl+C safe).
+ * @returns {Promise<string[]>} tools that were freshly installed
+ */
+async function ensureSystemTools() {
+  const missing = REQUIRED.filter((t) => !hasCommandSync(t.bin));
+  if (missing.length === 0) return [];
+
+  const pm = detectPackageManager();
+  if (!pm) {
+    p.log.warn('No supported package manager detected (apt/dnf/yum/pacman/zypper/apk).');
+    p.log.message(pc.dim(`Install manually, then re-run: sudo apt install ${missing.map((m) => m.pkg).join(' ')}`));
+    return [];
+  }
+
+  const installed = [];
+  for (const tool of missing) {
+    const want = await p.confirm({
+      message: `${pc.cyan(tool.bin)} is missing. Install it now? (needed for ${tool.why})`,
+      initialValue: true,
+    });
+    if (p.isCancel(want)) { p.cancel('Aborted.'); process.exit(0); }
+    if (!want) {
+      p.log.warn(`Skipped ${pc.cyan(tool.bin)} — snapshot backup/restore may not work without it.`);
+      continue;
+    }
+    p.log.step(`Installing ${pc.cyan(tool.bin)}…`);
+    const s = p.spinner();
+    s.start(`Installing ${tool.bin}…`);
+    // Release the spinner FIRST so the sudo password prompt is visible & interruptible.
+    s.stop('');
+    try {
+      const args = pm === 'pacman' ? ['-S', '--noconfirm', tool.pkg] : [pm, 'install', '-y', tool.pkg];
+      const res = await execa('sudo', args, { stdio: 'inherit', reject: false });
+      if (res.exitCode === 0 && hasCommandSync(tool.bin)) {
+        p.log.success(`${pc.cyan(tool.bin)} installed.`);
+        installed.push(tool.bin);
+      } else {
+        p.log.warn(`Could not install ${pc.cyan(tool.bin)} — run: sudo ${args.join(' ')}`);
+      }
+    } catch (e) {
+      p.log.warn(`${pc.cyan(tool.bin)} install failed: ${e.message}`);
+    }
+    s.stop('');
+  }
+  return installed;
+}
+export async function runSetup() {
+  p.intro(pc.bgYellow(pc.black(' parrot-blackbox setup ')));
+
+  // 1. Dependencies — check the system and INSTALL anything needed for the
+  //    snapshot to be created, uploaded and (later) RESTORED.
+  p.note('Checking & installing the tools needed for snapshot backup + restore…', 'Step 1/5 — tools');
+  const missing = REQUIRED.filter((t) => !hasCommandSync(t.bin));
+  if (missing.length === 0) {
+    p.log.success(`All tools present: ${REQUIRED.map((r) => r.bin).join(', ')}`);
+  } else {
+    const installed = await ensureSystemTools();
+    const stillMissing = REQUIRED.filter((t) => !hasCommandSync(t.bin));
+    if (installed.length) p.log.success(`Installed: ${installed.join(', ')}`);
+    if (stillMissing.length) {
+      p.log.warn(`Still missing: ${stillMissing.map((m) => m.bin).join(', ')}`);
+    } else {
+      p.log.success(`All required tools now present: ${REQUIRED.map((r) => r.bin).join(', ')}`);
+    }
+  }
+  if (!hasCommandSync('timeshift')) {
+    p.log.message(pc.dim('Timeshift missing = snapshot backup & restore are unavailable. Run `parrot-blackbox` again after installing it.'));
+  }
+
+  // 2. Accounts
+  p.note('Accounts are rclone remotes — one per MEGA or Google Drive login.', 'Step 2/5 — storage pool');
+  const existing = listAccounts();
+  const needMore = await p.confirm({
+    message: existing.length
+      ? `You already have ${existing.length} account(s). Add or authorize another cloud login?`
+      : 'No accounts yet — add a MEGA or Google Drive account now?',
+    initialValue: true,
+  });
+  if (p.isCancel(needMore)) { p.cancel('Aborted.'); process.exit(0); }
+
+  if (needMore) {
+    const want = await p.select({
+      message: 'How do you want to add the account?',
+      options: [
+        { value: 'wizard', label: 'Run `rclone config` (recommended — handles MEGA + Google OAuth)', hint: 'authenticates in your browser' },
+        { value: 'manual', label: 'I already created the rclone remote myself' },
+      ],
+    });
+    if (p.isCancel(want)) { p.cancel('Aborted.'); process.exit(0); }
+
+    if (want === 'wizard') {
+      p.log.step('Starting rclone config — follow its prompts, then come back.');
+      await execa('rclone', ['config'], { stdio: 'inherit' });
+    }
+    await registerAccountsFlow();
+  }
+
+  // 3. Schedule overview — snapshot ONLY by default (storage-conscious).
+  const cfg = loadConfig();
+  p.note(
+    `   Snapshot backup: ${pc.bold('every Saturday at 22:00')} (keep ${cfg.jobs.snapshots.keep}, local + cloud)\n` +
+    `   File backups   : ${cfg.jobs.files.enabled ? pc.bold('daily 22:00 (enabled)') + ` (keep ${cfg.jobs.files.keep})` : pc.dim('disabled by default — opt-in, storage-conscious')}\n` +
+    `   Missed backups : caught up automatically in order when WiFi returns`,
+    'Step 3/5 — schedule',
+  );
+
+  // 4. Always-on service
+  const install = await p.confirm({
+    message: 'Install the always-on background service (systemd / cron fallback)?',
+    initialValue: true,
+  });
+  if (p.isCancel(install)) { p.cancel('Aborted.'); process.exit(0); }
+  if (install) {
+    const backend = await installService();
+    p.log.success(`Always-on service installed via ${pc.cyan(backend)}.`);
+    p.log.message(pc.dim('It survives reboots — a missed Saturday 22:00 run fires as soon as the machine is back online.'));
+  }
+
+  // 5. First snapshot now?
+  const first = await p.confirm({
+    message: 'Run the FIRST snapshot backup right now? (recommended before a fresh install)',
+    initialValue: true,
+  });
+  if (p.isCancel(first)) { p.cancel('Aborted.'); process.exit(0); }
+  if (first) {
+/** Register discovered rclone remotes as accounts (multi-select). */
+async function registerAccountsFlow() {
+  const remotes = await listRemotes();
+  if (remotes.length === 0) {
+    p.log.warn('No rclone remotes found yet. Create one with `rclone config` or re-run setup.');
+    return;
+  }
+  const toAdd = await p.multiselect({
+    message: 'Select which rclone remotes to add to the backup pool (one per account):',
+    options: remotes.map((r) => ({ value: r, label: r })),
+    required: false,
+  });
+  if (p.isCancel(toAdd) || toAdd.length === 0) {
+    p.log.message(pc.dim('No accounts added.'));
+    return;
+  }
+  for (const remote of toAdd) {
+    const provider = await p.select({
+      message: `Provider for "${remote}"?`,
+      options: [
+        { value: 'mega', label: 'MEGA (20 GB free tier)' },
+        { value: 'gdrive', label: 'Google Drive (10 GB free tier)' },
+      ],
+    });
+    if (p.isCancel(provider)) continue;
+    const res = await addAccount({ provider, remote });
+    if (res.ok) p.log.success(`Added ${pc.cyan(remote)} (${provider}).`);
+    else p.log.warn(res.error);
+  }
+  const accounts = await refreshAccounts();
+  p.log.success(poolSummary(accounts).text);
+  journal('setup', `accounts registered: ${accounts.map((a) => a.remote).join(',')}`);
+}
+    if (!(await isOnline())) {
+      p.log.warn('Offline right now — the backup stays pending and will run automatically when online.');
+    } else {
+      const s = p.spinner();
+      s.start('Creating snapshot…');
+      s.stop('');
+      try {
+        const res = await runDueJobs({ force: true, privileged: 'interactive' });
+        for (const r of res.report) {
+          if (r.ok) p.log.success(r.snapshot
+            ? `Snapshot ${r.snapshot} created & uploaded${r.size ? ` (${pc.cyan(bytesHuman(r.size))})` : ''}.`
+            : `Backup ${r.due} stored.`);
+          else if (r.deferred) p.log.warn(`Snapshot deferred (sudo needed) — run \`parrot-blackbox snapshot now\`.`);
+          else p.log.warn(`Backup failed: ${r.error}`);
+        }
+      } catch (e) {
+        p.log.warn(`Backup failed: ${e.message}`);
+      }
+    }
+  }
+
+  p.outro(pc.green('Setup complete. Run `parrot-blackbox status` to see everything, or `parrot-blackbox help` for all commands.'));
+}

package/src/core/lock.js

@@ -0,0 +1,67 @@
+/**
+ * Scheduler lock — prevents a manual `force` from colliding with the daemon.
+ * Locks are reclaimed automatically when their PID is dead or the TTL passed.
+ */
+
+import fs from 'node:fs';
+import { lockFile, ensureStateDirs } from './paths.js';
+import { readJsonSafe } from './store.js';
+
+export class LockError extends Error {}
+
+export function releaseLock() {
+  try {
+    fs.rmSync(lockFile(), { force: true });
+  } catch {
+    /* best effort */
+  }
+}
+
+function pidAlive(pid) {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Acquire the lock. Throws LockError when another live run holds it. */
+export function acquireLock({ ttlMs = Number(process.env.PBB_LOCK_TTL_MS || 6 * 3_600_000) } = {}) {
+  ensureStateDirs();
+  let attempts = 0;
+  while (attempts < 2) {
+    attempts += 1;
+    try {
+      const fd = fs.openSync(lockFile(), 'wx');
+      const record = { pid: process.pid, at: Date.now(), host: process.env.HOSTNAME || 'localhost' };
+      fs.writeFileSync(fd, JSON.stringify(record));
+      fs.closeSync(fd);
+      return record;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw new LockError(`cannot create lock: ${err.message}`);
+      const existing = readJsonSafe(lockFile(), {});
+      const stale =
+        !existing.pid || !pidAlive(existing.pid) || Number(existing.at) + ttlMs < Date.now();
+      if (stale) {
+        fs.rmSync(lockFile(), { force: true });
+        continue; // one reclaim attempt
+      }
+      throw new LockError(
+        `another run is already in progress (pid ${existing.pid} since ${new Date(existing.at).toISOString()})`,
+      );
+    }
+  }
+  throw new LockError('could not acquire lock');
+}
+
+/** Run `fn` inside the lock; always releases afterwards. */
+export async function withLock(fn, opts) {
+  const lock = acquireLock(opts);
+  try {
+    return await fn(lock);
+  } finally {
+    releaseLock();
+  }
+}

package/src/core/paths.js

@@ -0,0 +1,95 @@
+/**
+ * parrot-blackbox — paths & environment.
+ *
+ * Every mutable location is overridable so the whole tool can run inside a
+ * sandbox (fake HOME / fake cloud / fake timeshift) without ever touching the
+ * real filesystem or cloud accounts.
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+export const PKG_NAME = 'parrot-blackbox';
+
+export function sandboxMode() {
+  return process.env.PBB_SANDBOX === '1';
+}
+
+/** Root of all runtime state (journal, state, staging, manifests, logs). */
+export function stateDir() {
+  return (
+    process.env.PBB_STATE_DIR ||
+    path.join(process.env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state'), PKG_NAME)
+  );
+}
+
+/** User-editable config file. */
+export function configFile() {
+  return (
+    process.env.PBB_CONFIG_FILE ||
+    path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), PKG_NAME, 'config.json')
+  );
+}
+
+export function journalFile() {
+  return path.join(stateDir(), 'journal.log');
+}
+
+export function lockFile() {
+  return path.join(stateDir(), 'lock.json');
+}
+
+export function stateFile() {
+  return path.join(stateDir(), 'state.json');
+}
+
+export function stagingDir() {
+  return path.join(stateDir(), 'staging');
+}
+
+export function chunkDir() {
+  return path.join(stateDir(), 'chunks');
+}
+
+export function manifestsDir() {
+  return path.join(stateDir(), 'manifests');
+}
+
+export function daemonPidFile() {
+  return path.join(stateDir(), 'daemon.pid');
+}
+
+export function daemonLogFile() {
+  return path.join(stateDir(), 'daemon.log');
+}
+
+export function serviceFile() {
+  return path.join(
+    process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'),
+    'systemd',
+    'user',
+    `${PKG_NAME}.service`,
+  );
+}
+
+/** Timeshift snapshot directory (used by the real tool and by sandbox stubs). */
+export function timeshiftDir() {
+  return process.env.PBB_TIMESHIFT_DIR || '/timeshift';
+}
+
+export function ensureStateDirs() {
+  for (const dir of [
+    stateDir(),
+    configFileDir(configFile()),
+    stagingDir(),
+    chunkDir(),
+    manifestsDir(),
+  ]) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function configFileDir(file) {
+  return path.dirname(file);
+}

package/src/core/store.js

@@ -0,0 +1,173 @@
+/**
+ * Crash-proof persistence: config, state and append-only journal.
+ *
+ * State writes are atomic (tmp + rename) so a crash mid-write can never leave
+ * a truncated file. Every job opens a journal entry on start and only closes
+ * it on success, so interrupted runs are always discoverable and retried.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execaSync } from 'execa';
+import { configFile, ensureStateDirs, journalFile, stateFile } from './paths.js';
+import { iso, clock } from './time.js';
+import deepMerge from '../util/misc.js';
+
+const GiB = 1024 ** 3;
+
+/** Factory defaults — safe, conservative, self-documenting. */
+export function defaultConfig() {
+  return {
+    version: 1,
+    jobs: {
+      // The weekly snapshot is THE default backup. Daily file backups are an
+      // OPT-IN (enabled:true) so cloud + local storage are respected by default
+      // — a full system snapshot already contains your data.
+      files: {
+        enabled: false,
+        schedule: { kind: 'daily', at: { hour: 22, minute: 0 } },
+        keep: 3, // latest + 2 previous days
+        catchUpLimit: 3,
+        sources: ['~/Desktop', '~/Documents', '~/Pictures'],
+        exclude: [
+          '**/.cache/**',
+          '**/.git/**',
+          '**/node_modules/**',
+          '**/__pycache__/**',
+          '**/*.tmp',
+          '**/*.swp',
+          '**/lost+found/**',
+        ],
+      },
+      snapshots: {
+        enabled: true, // default: one weekly system snapshot keeps storage sane
+        schedule: { kind: 'weekly', on: 6, at: { hour: 22, minute: 0 } }, // Saturday 22:00
+        keep: 3, // latest + 2 previous (the middle one is the sanity safety net)
+        catchUpLimit: 3,
+        chunkSize: 2 * GiB,
+      },
+    },
+    storage: {
+      remoteRoot: 'parrot-blackbox',
+      chunkSize: 2 * GiB,
+      providers: {
+        mega: { defaultQuotaGiB: 20 },
+        gdrive: { defaultQuotaGiB: 10 },
+      },
+      accounts: [], // {id, provider, label, remote, quotaGiB?}
+    },
+    network: {
+      pingHost: 'https://api.mega.nz',
+      retryEveryMinutes: 15,
+    },
+    daemon: {
+      pollIntervalSeconds: 60,
+    },
+  };
+}
+
+export function readJsonSafe(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+/** Atomic JSON write: tmp + rename. Never yields a half-written file. */
+export function writeJsonAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
+  fs.renameSync(tmp, file);
+}
+
+export function loadConfig() {
+  const cfg = deepMerge(defaultConfig(), readJsonSafe(configFile(), {}));
+  if (!Array.isArray(cfg.storage.accounts)) cfg.storage.accounts = [];
+  return cfg;
+}
+
+export function saveConfig(cfg) {
+  writeJsonAtomic(configFile(), cfg);
+}
+
+export function defaultState() {
+  const now = iso(clock());
+  return {
+    version: 1,
+    createdAt: now,
+    jobs: {
+      files: { since: now, lastDue: null, lastCompletedDue: null, lastRunAt: null, lastStatus: null, lastError: null, completed: [], pending: [] },
+      snapshots: { since: now, lastDue: null, lastCompletedDue: null, lastRunAt: null, lastStatus: null, lastError: null, completed: [], pending: [] },
+    },
+    manifests: {},
+    storage: { lastRefreshAt: null },
+  };
+}
+
+export function loadState() {
+  const file = stateFile();
+  if (!fs.existsSync(file)) {
+    // Persist the initial defaults so the "since" anchor survives across
+    // separate process runs (daemon, cron, force) — otherwise every fresh CLI
+    // invocation would re-anchor the schedule to *its* now and never see dues.
+    const fresh = defaultState();
+    saveState(fresh);
+    return fresh;
+  }
+  return deepMerge(defaultState(), readJsonSafe(file, {}));
+}
+
+export function saveState(st) {
+  writeJsonAtomic(stateFile(), st);
+}
+
+/* ------------------------------------------------------------------ */
+/* Journal                                                             */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Append one event to the journal. Lines look like:
+ *   `2026-08-29T22:00:01|info|files|started due=2026-08-29T22:00:00`
+ */
+export function journal(event, detail = '', level = 'info') {
+  try {
+    fs.mkdirSync(path.dirname(journalFile()), { recursive: true });
+    const line = `${iso(clock())}|${level}|${event}|${String(detail).replace(/\n/g, ' ').slice(0, 400)}\n`;
+    fs.appendFileSync(journalFile(), line);
+  } catch {
+    /* journaling must never take the tool down */
+  }
+}
+
+/** Read the last n journal lines, optionally filtering by substring. */
+export function lastJournal(n = 20, filter = '') {
+  try {
+    const lines = fs.existsSync(journalFile()) ? fs.readFileSync(journalFile(), 'utf8').split('\n').filter(Boolean) : [];
+    return lines.filter((l) => !filter || l.includes(filter)).slice(-n);
+  } catch {
+    return [];
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Runtime helpers used by setup / service / daemon control            */
+/* ------------------------------------------------------------------ */
+
+export function currentTimeIso() {
+  return iso(clock());
+}
+
+export function hasCommandSync(name) {
+  try {
+    const res = execaSync('bash', ['-c', `command -v "${name}"`], { reject: false });
+    return Boolean(res.stdout.trim());
+  } catch {
+    return false;
+  }
+}
+
+export function setStateDirs() {
+  ensureStateDirs();
+}

package/src/core/time.js

@@ -0,0 +1,142 @@
+/**
+ * Time & scheduling math.
+ *
+ * The whole scheduler is built around calendar "due times" (e.g. every day at
+ * 22:00, or every Saturday at 22:00). Catch-up works by listing every due time
+ * strictly after the last one we considered and strictly before/at *now*, then
+ * running those we have not completed yet — oldest first. A machine that was
+ * off or offline simply finds its missed dues on the next wake-up and drains
+ * them in order.
+ *
+ * `clock()` is injectable via PBB_TEST_NOW so tests can fake the wall clock.
+ */
+
+export const MS_HOUR = 3_600_000;
+export const MS_DAY = 24 * MS_HOUR;
+
+/** Injectable wall clock. @returns {Date} */
+export function clock() {
+  if (process.env.PBB_TEST_NOW) {
+    return new Date(process.env.PBB_TEST_NOW);
+  }
+  return new Date();
+}
+
+function startOfLocalDay(d) {
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+}
+
+/** Build a Date at `at:{hour,minute}` on the local calendar day of `dayBase`. */
+function localAt(dayBase, at) {
+  const d = new Date(dayBase.getFullYear(), dayBase.getMonth(), dayBase.getDate());
+  d.setHours(at.hour ?? 0, at.minute ?? 0, 0, 0);
+  return d;
+}
+
+/**
+ * Every due time in (from, to] for a daily schedule.
+ * @param {Date} from exclusive lower bound
+ * @param {Date} to inclusive upper bound
+ * @param {{hour:number,minute:number}} at
+ * @returns {Date[]} ascending
+ */
+export function dailyDues(from, to, at) {
+  const out = [];
+  if (to.getTime() <= from.getTime()) return out;
+  let day = startOfLocalDay(new Date(from.getTime() + 1));
+  const lastDay = startOfLocalDay(to);
+  while (day.getTime() <= lastDay.getTime()) {
+    const due = localAt(day, at);
+    if (due.getTime() > from.getTime() && due.getTime() <= to.getTime()) out.push(due);
+    day = new Date(day.getFullYear(), day.getMonth(), day.getDate() + 1);
+  }
+  return out;
+}
+
+/**
+ * Every due time in (from, to] for a weekly schedule.
+ * @param {Date} from exclusive lower bound
+ * @param {Date} to inclusive upper bound
+ * @param {0|1|2|3|4|5|6} on day of week, 0=Sunday .. 6=Saturday
+ * @param {{hour:number,minute:number}} at
+ * @returns {Date[]} ascending
+ */
+export function weeklyDues(from, to, on, at) {
+  const out = [];
+  if (to.getTime() <= from.getTime()) return out;
+  let day = startOfLocalDay(new Date(from.getTime() + 1));
+  const lastDay = startOfLocalDay(to);
+  // Advance to the first matching weekday at-or-after `day`.
+  while (day.getDay() !== on) day = new Date(day.getFullYear(), day.getMonth(), day.getDate() + 1);
+  while (day.getTime() <= lastDay.getTime()) {
+    const due = localAt(day, at);
+    if (due.getTime() > from.getTime() && due.getTime() <= to.getTime()) out.push(due);
+    day = new Date(day.getFullYear(), day.getMonth(), day.getDate() + 7);
+  }
+  return out;
+}
+
+/**
+ * Resolve a job schedule object into a due-time generator.
+ * @param {{kind:'daily'|'weekly', at:{hour,minute}, on?:number}} schedule
+ */
+export function dueList(schedule, from, to) {
+  if (schedule.kind === 'weekly') {
+    return weeklyDues(from, to, schedule.on ?? 6, schedule.at ?? { hour: 22, minute: 0 });
+  }
+  return dailyDues(from, to, schedule.at ?? { hour: 22, minute: 0 });
+}
+
+/** RFC3339-ish local ISO stamp without milliseconds (stable for keys). */
+export function iso(d) {
+  const pad = (n, w = 2) => String(n).padStart(w, '0');
+  return (
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T` +
+    `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+  );
+}
+
+/** `2026-08-29T22:00:00` -> `2026-08-29` (the calendar day of the due). */
+export function dueDay(isoDue) {
+  return (isoDue || '').slice(0, 10);
+}
+
+/**
+ * Compute the pending due list for one job and persist window advancement.
+ *
+ * @param {string} jobType 'files' | 'snapshots'
+ * @param {object} jobState state.jobs[jobType]
+ * @param {object} jobCfg  config.jobs[jobType] (has schedule + catchUpLimit)
+ * @param {Date} now
+ * @returns {{pending:string[], lastDue:string|null, dropped:number}}
+ */
+export function advancePending(jobState, jobCfg, now) {
+  const from = jobState.lastDue ? new Date(jobState.lastDue) : new Date(jobState.since);
+  if (now.getTime() <= from.getTime()) {
+    return { pending: jobState.pending || [], lastDue: jobState.lastDue, dropped: 0 };
+  }
+  const candidates = dueList(jobCfg.schedule, from, now);
+  if (candidates.length === 0) {
+    return { pending: jobState.pending || [], lastDue: jobState.lastDue, dropped: 0 };
+  }
+  const completedDues = new Set((jobState.completed || []).map((c) => c.due));
+  const alreadyPending = new Set(jobState.pending || []);
+  const fresh = candidates
+    .map((d) => iso(d))
+    .filter((due) => !completedDues.has(due) && !alreadyPending.has(due));
+
+  const limit = jobCfg.catchUpLimit ?? 3;
+  const dropped = Math.max(0, fresh.length - limit);
+  const kept = fresh.slice(-limit); // keep the most recent `limit` missed dues
+
+  const merged = [...(jobState.pending || []), ...kept]
+    .filter((d, i, arr) => arr.indexOf(d) === i)
+    .sort();
+  const lastDue = iso(candidates[candidates.length - 1]);
+  return { pending: merged, lastDue, dropped };
+}
+
+/** Do two due stamps correspond to the same calendar slot? (string compare is exact) */
+export function dueEqual(a, b) {
+  return a === b;
+}