parrot-blackbox 2.2.0 → 2.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parrot-blackbox",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Crash-proof, multi-cloud backup & recovery automation for Parrot OS. Daily/weekly off-disk backups with automatic catch-up, smart storage across many MEGA + Google Drive accounts, Timeshift snapshot backups and one-command restore.",
   "type": "module",
   "main": "src/cli.js",

package/src/backup/restore.js

@@ -60,8 +60,12 @@ export async function restoreSnapshot({ id, accounts, cfg, toDir, confirm = fals
 
   if (missingFromChain.length === 0) {
     console.log(`✓ All snapshots already present locally.`);
+    console.log(`⚠ This machine already has this snapshot (and its whole chain).`);
+    console.log(`  If the system hasn't changed since this backup, restoring is effectively a`);
+    console.log(`  no-op — but Timeshift will STILL overwrite the entire running system with the`);
+    console.log(`  snapshot content and update the bootloader. On a fresh install this is exactly`);
+    console.log(`  what you want; on this same machine you can safely abort now.`);
   } else {
-    // Download and receive each missing snapshot in order (oldest to newest)
     console.log(`\n⬇ Downloading ${missingFromChain.length} snapshot(s)...`);
     for (const snapId of missingFromChain) {
       await downloadAndReceiveSnapshot({ snapId, accounts, cfg, privileged, onProgress });

package/src/cli.js

@@ -165,12 +165,17 @@ async function restoreFlow(rest) {
     p.log.warn('No accounts configured — cannot reach the cloud backups. Run `parrot-blackbox account add` first.');
     return;
   }
+  // Rescue paths first: System Snapshot and Urgent backup. The daily "Files"
+  // flow shows only when that job is enabled, keeping this a clean two-option
+  // restore for the default setup.
   const kind = rest[0] || (await p.select({
     message: 'Restore what?',
     options: [
       { value: 'snapshot', label: 'System snapshot (Timeshift) — overwrites the whole system', hint: '[sudo]' },
-      { value: 'files', label: 'File backup — recover fonts/images/docs into a folder' },
       { value: 'urgent', label: 'Urgent backup — user files + tool profiles (fresh install)' },
+      ...(cfg.jobs?.files?.enabled
+        ? [{ value: 'files', label: 'File backup — recover fonts/images/docs into a folder' }]
+        : []),
     ],
   }));
   if (p.isCancel(kind)) return;
@@ -185,13 +190,20 @@ async function restoreFlow(rest) {
     if (p.isCancel(id)) return;
     const toDir = rest[2] || (await p.text({
       message: 'Restore to which directory?',
-      initialValue: `./restored-${id}`,
+      // Urgent backups restore your home (Desktop, .ssh, .gitconfig, …) — an
+      // identical machine reports "nothing changed", a fresh install overwrites.
+      initialValue: kind === 'urgent' ? (process.env.HOME || `./restored-${id}`) : `./restored-${id}`,
     }));
     const s = p.spinner();
     s.start('Restoring…');
     try {
       const res = await restoreFiles({ id, toDir, accounts: accs, cfg, kind });
-      s.stop(`✔ Restored ${res.files} file(s), ${bytesHuman(res.bytes)} into ${toDir}`);
+      if (res.identical) {
+        s.stop(`✔ Nothing to restore — ${kind} backup already matches ${toDir} (${res.unchanged} file(s) identical).`);
+      } else {
+        const skip = res.unchanged ? `  (${res.unchanged} already up-to-date)` : '';
+        s.stop(`✔ Restored ${res.files} file(s), ${bytesHuman(res.bytes)} into ${toDir}${skip}`);
+      }
     } catch (e) {
       s.stop('✖ Restore failed.');
       p.log.warn(e.message);

package/src/commands/wizard.js

@@ -355,12 +355,22 @@ async function restoreFileLike(kind, accs, cfg) {
     options: artifacts.map((a) => ({ value: a.id, label: `${a.id}  (${bytesHuman(a.totalSize)})` })).concat([{ value: '__back', label: '← Back' }]),
   });
   if (p.isCancel(id) || id === '__back') return;
-  const toDir = await p.text({ message: 'Restore into which directory?', initialValue: `./restored-${id}` });
+  const toDir = await p.text({
+    message: 'Restore into which directory?',
+    // Urgent backups restore your home (Desktop, .ssh, .gitconfig, …) — an
+    // identical machine reports "nothing changed", a fresh install overwrites.
+    initialValue: kind === 'urgent' ? (process.env.HOME || `./restored-${id}`) : `./restored-${id}`,
+  });
   if (p.isCancel(toDir) || !toDir) return;
   fs.mkdirSync(toDir, { recursive: true });
   try {
     const res = await restoreFiles({ id, toDir, accounts: accs, cfg, kind });
-    p.log.success(`✔ Restored ${res.files} file(s), ${bytesHuman(res.bytes)} into ${toDir}`);
+    if (res.identical) {
+      p.log.success(`✔ Nothing to restore — ${kind} backup already matches ${toDir} (${res.unchanged} file(s) identical).`);
+    } else {
+      const skip = res.unchanged ? `  (${res.unchanged} already up-to-date)` : '';
+      p.log.success(`✔ Restored ${res.files} file(s), ${bytesHuman(res.bytes)} into ${toDir}${skip}`);
+    }
   } catch (e) {
     p.log.warn(`✖ ${e.message}`);
   }
@@ -371,14 +381,20 @@ async function restoreMenu() {
   const accs = listAccounts();
   if (!accs.length) { p.log.warn('No cloud accounts configured yet.'); return; }
   const cfg = loadConfig();
+  // The two rescue paths come first: System Snapshot and Urgent backup. The
+  // daily "Files" flow shows only when that job is actually enabled, so this
+  // stays a clean two-option restore for the default setup.
+  const options = [
+    { value: 'snapshot', label: '💽 System snapshot', hint: 'full system restore [sudo]' },
+    { value: 'urgent', label: '⚡ Urgent backup', hint: 'user files + tool profiles (fresh install)' },
+  ];
+  if (cfg.jobs?.files?.enabled) {
+    options.push({ value: 'files', label: '📄 Files', hint: 'recover documents, images, etc.' });
+  }
+  options.push({ value: 'back', label: '← Back' });
   const kind = await p.select({
     message: '♻️  Restore backup',
-    options: [
-      { value: 'files', label: '📄 Files', hint: 'recover documents, images, etc.' },
-      { value: 'urgent', label: '⚡ Urgent backup', hint: 'user files + tool profiles (fresh install)' },
-      { value: 'snapshot', label: '💽 System snapshot', hint: 'full system restore [sudo]' },
-      { value: 'back', label: '← Back' },
-    ],
+    options,
   });
   if (p.isCancel(kind) || kind === 'back') return;
 

package/src/storage/allocator.js

@@ -24,12 +24,13 @@ import { createWriteStream } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { copyToFile, copyBatch, mkdirRemote } from './rclone.js';
 import { bytesHuman } from '../util/misc.js';
+import { manifestsDir } from '../core/paths.js';
 
 export { bytesHuman };
 export const GiB = 1024 ** 3;
 export const MANIFEST_NAME = '__MANIFEST__.json';
 
-/** Walk a dir tree returning [{rel, abs, size, isDir}]. Symlinks skipped. */
+/** Walk a dir tree returning [{rel, abs, size, isDir, mtimeMs}]. Symlinks skipped. */
 export function walkFiles(localDir) {
   const out = [];
   const base = path.resolve(localDir);
@@ -45,10 +46,10 @@ export function walkFiles(localDir) {
       }
       if (ent.isSymbolicLink()) continue;
       if (ent.isDirectory()) {
-        out.push({ rel: eRel, abs: eAbs, isDir: true, size: 0 });
+        out.push({ rel: eRel, abs: eAbs, isDir: true, size: 0, mtimeMs: st.mtimeMs });
         rec(eAbs, eRel);
       } else {
-        out.push({ rel: eRel, abs: eAbs, isDir: false, size: st.size });
+        out.push({ rel: eRel, abs: eAbs, isDir: false, size: st.size, mtimeMs: st.mtimeMs });
       }
     }
   }
@@ -169,6 +170,7 @@ export async function planAndPlace(localDir, { kind, id, accounts, remoteRoot, c
         rel: entry.rel,
         type: 'file',
         size: entry.size,
+        mtimeMs: entry.mtimeMs,
         loc: [{ remote: acc.remote, path: `${basePath}/${entry.rel}`, start: 0, end: entry.size, size: entry.size }],
       });
     } else {
@@ -231,11 +233,11 @@ export async function planAndPlace(localDir, { kind, id, accounts, remoteRoot, c
       placedBytes += len;
       emit(placedBytes, `uploaded ${bytesHuman(placedBytes)}`, acc.remote);
     }
-    manifest.entries.push({ rel, type: 'file', size: entry.size, split: true, loc: locs });
+    manifest.entries.push({ rel, type: 'file', size: entry.size, mtimeMs: entry.mtimeMs, split: true, loc: locs });
   }
 
   // Manifest: cloud + local mirror.
-  const manifestLocalDir = process.env.PBB_MANIFESTS_DIR || path.join(process.env.PBB_STATE_DIR || '.', 'manifests');
+  const manifestLocalDir = process.env.PBB_MANIFESTS_DIR || manifestsDir();
   const manifestLocalPath = path.join(manifestLocalDir, `${kind}-${id}.json`);
   fs.mkdirSync(manifestLocalDir, { recursive: true });
   fs.writeFileSync(manifestLocalPath, JSON.stringify(manifest, null, 2));
@@ -379,7 +381,7 @@ export async function planAndPlaceStream(btrfsStream, { kind, id, accounts, remo
   };
 
   // Manifest: cloud + local mirror.
-  const manifestLocalDir = process.env.PBB_MANIFESTS_DIR || path.join(process.env.PBB_STATE_DIR || '.', 'manifests');
+  const manifestLocalDir = process.env.PBB_MANIFESTS_DIR || manifestsDir();
   const manifestLocalPath = path.join(manifestLocalDir, `${kind}-${id}.json`);
   fs.mkdirSync(manifestLocalDir, { recursive: true });
   fs.writeFileSync(manifestLocalPath, JSON.stringify(manifest, null, 2));

package/src/storage/archive.js

@@ -15,6 +15,7 @@ import { execa } from 'execa';
 import { catRemote, lsjson, purge, copyToFile, downloadBatch } from './rclone.js';
 import { MANIFEST_NAME } from './allocator.js';
 import { isValidBtrfsStreamManifest } from '../backup/btrfs-send.js';
+import { manifestsDir } from '../core/paths.js';
 
 export { MANIFEST_NAME };
 
@@ -28,8 +29,10 @@ function isPhantom(kind, manifest) {
   return kind === 'snapshots' && manifest.schema === 2 && !isValidBtrfsStreamManifest(manifest);
 }
 
-function manifestMirrorPath(kind, id) {
-  const dir = process.env.PBB_MANIFESTS_DIR || path.join(process.env.PBB_STATE_DIR || '.', 'manifests');
+export function manifestMirrorPath(kind, id) {
+  // Canonical state dir, NOT a CWD-relative `./manifests` (which would land in
+  // the user's home as stray junk and break the mirror fallback).
+  const dir = process.env.PBB_MANIFESTS_DIR || manifestsDir();
   return path.join(dir, `${kind}-${id}.json`);
 }
 
@@ -85,6 +88,15 @@ export async function restoreArtifact(manifest, destDir, { onProgress } = {}) {
   let bytes = 0;
   const entries = manifest.entries || [];
 
+  // ── Step 0: Smart diff — restore ONLY what differs. If everything already
+  // matches the backup locally, report "nothing changed" and touch NOTHING
+  // (no re-download, no re-copy, no overwrite). A file needs restoring when it
+  // is missing, has a different size, or a meaningfully different mtime.
+  const { unchanged, toRestore } = planRestoreDiff(manifest, destDir);
+  if (toRestore.length === 0) {
+    return { files: 0, bytes: 0, unchanged: unchanged.length, changed: 0, identical: true };
+  }
+
   // ── Step 1: Create all directories up-front ──
   for (const entry of entries) {
     const target = path.join(destDir, ...entry.rel.split('/'));
@@ -95,11 +107,11 @@ export async function restoreArtifact(manifest, destDir, { onProgress } = {}) {
     }
   }
 
-  // ── Step 2: Separate whole files (batchable) from split files ──
+  // ── Step 2: Separate changed whole files (batchable) from changed splits ──
   const wholeFiles = [];    // single-location entries → batched download
   const splitFiles = [];    // multi-location entries → streaming reassembly
 
-  for (const entry of entries) {
+  for (const entry of toRestore) {
     if (entry.type === 'dir') continue;
     if (entry.loc.length === 1) {
       wholeFiles.push(entry);
@@ -152,12 +164,15 @@ export async function restoreArtifact(manifest, destDir, { onProgress } = {}) {
         const loc = entry.loc[0];
         const r = await copyToFile(`${loc.remote}:${loc.path}`, target, { force: true });
         if (!r.ok) throw new Error(`download failed for ${entry.rel}: ${r.error}`);
+        touchToEntry(target, entry);
         files += 1;
         bytes += entry.size;
         if (typeof onProgress === 'function') onProgress({ done: files, text: `restored ${entry.rel}` });
       }
     } else {
       for (const entry of batch.entries) {
+        const target = path.join(destDir, ...entry.rel.split('/'));
+        touchToEntry(target, entry);
         files += 1;
         bytes += entry.size;
         if (typeof onProgress === 'function') onProgress({ done: files, text: `restored ${entry.rel}` });
@@ -184,12 +199,52 @@ export async function restoreArtifact(manifest, destDir, { onProgress } = {}) {
       await streams.finished(out);
     }
     fs.renameSync(partAbs, target);
+    touchToEntry(target, entry);
     files += 1;
     bytes += entry.size;
     if (typeof onProgress === 'function') onProgress({ done: files, text: `restored ${entry.rel}` });
   }
 
-  return { files, bytes };
+  return { files, bytes, unchanged: unchanged.length, changed: toRestore.length, identical: false };
+}
+
+/**
+ * Compare a manifest's file entries against what already exists under destDir.
+ * A file needs restoring when it is missing locally, has a different size, or
+ * has a mtime more than ~2s away from the mtime recorded in the manifest
+ * (backups made before mtime recording simply fall back to size-only).
+ * @returns {{ unchanged: Array, toRestore: Array }}
+ */
+export function planRestoreDiff(manifest, destDir) {
+  const MTIME_TOLERANCE_MS = 2000;
+  const unchanged = [];
+  const toRestore = [];
+  for (const entry of (manifest.entries || [])) {
+    if (entry.type === 'dir') continue;
+    const target = path.join(destDir, ...entry.rel.split('/'));
+    let st = null;
+    try {
+      st = fs.statSync(target);
+    } catch {
+      st = null;
+    }
+    if (!st) { toRestore.push(entry); continue; }
+    if (st.size !== entry.size) { toRestore.push(entry); continue; }
+    if (entry.mtimeMs && Math.abs(st.mtimeMs - entry.mtimeMs) > MTIME_TOLERANCE_MS) { toRestore.push(entry); continue; }
+    unchanged.push(entry);
+  }
+  return { unchanged, toRestore };
+}
+
+/** Restore mtime from the manifest so a later diff reports the file identical. */
+function touchToEntry(target, entry) {
+  if (!entry.mtimeMs) return;
+  try {
+    const t = entry.mtimeMs / 1000;
+    fs.utimesSync(target, t, t);
+  } catch {
+    /* best effort */
+  }
 }
 
 /** Purge an artifact from every account that hosts it (+ local mirror). */

package/src/storage/rclone.js

@@ -43,12 +43,18 @@ export async function listRemotes() {
   return res.stdout.split('\n').map((l) => l.trim().replace(/:$/, '')).filter(Boolean);
 }
 
-/** Recursive JSON listing of a remote path. */
-export async function lsjson(remotePath, { recursive = true } = {}) {
+/** Build args for `rclone lsjson`. IMPORTANT: lsjson outputs JSON natively and
+ *  has NO `--json` flag — passing one makes real rclone fail with
+ *  "unknown flag: --json", which silently emptied every cloud listing. */
+export function lsjsonArgs(remotePath, { recursive = true } = {}) {
   const args = ['lsjson', remotePath];
   if (recursive) args.push('--recursive');
-  args.push('--json');
-  const res = await rejectFalse(args);
+  return args;
+}
+
+/** Recursive JSON listing of a remote path. */
+export async function lsjson(remotePath, { recursive = true } = {}) {
+  const res = await rejectFalse(lsjsonArgs(remotePath, { recursive }));
   if (res.exitCode !== 0) return { ok: false, entries: [], error: res.stderr?.trim() };
   try {
     return { ok: true, entries: JSON.parse(res.stdout), error: null };