parrot-blackbox 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DonArtkins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# parrot-blackbox 🦜📦
+
+**Crash-proof, multi-cloud backup & recovery automation for Parrot OS.**
+
+`parrot-blackbox` is the "black box flight recorder you lost last time your
+Parrot install died" — a single CLI + background daemon that:
+
+1. **Automates backups** — a full **Timeshift system snapshot** every
+   **Saturday at 22:00** (the weekly snapshot IS the backup — no noisy daily
+   file backups, so storage stays lean).
+2. **Installs whatever your system needs** — running the wizard checks for
+   `rclone`, `timeshift`, `git` and `curl` and **auto-installs the missing
+   ones** (sudo prompt, exactly like theamify) so snapshot backup AND restore
+   always work on a fresh Parrot.
+3. **Is crash-proof** — if the laptop is off or offline at backup time, the
+   missed backups are run **in order, oldest first, the moment WiFi is back**.
+   Every job is journalled and retried; a lock prevents collisions; state is
+   written atomically. Nothing is silently lost.
+4. **Manages ~150 GB of free cloud storage for you** — 5 MEGA + 5 Google Drive
+   accounts are connected as one pool. Files are placed whole on whichever
+   account has the most relative headroom; anything bigger than a single
+   account's free space is split into byte-range chunks across accounts and a
+   manifest remembers how to reassemble it. You can never be "out of space".
+5. **Keeps the disk honest** — old snapshots (keep the latest 3, the middle one
+   as the sanity safety-net) are pruned **both locally and in the cloud in the
+   same pass**. Daily file backups are available as an **opt-in** if you ever
+   want them.
+6. **Brings you back from a fresh install** — restore a snapshot from the cloud
+   onto fresh Parrot (works whether or not you used disk encryption; it just
+   needs your `sudo` password, exactly like gitswitch/theamify).
+
+---
+
+## Why this exists
+
+From `research.txt`: a Parrot OS crash once wiped every local file, every
+customization, and the VS Codium profile. Only GitHub was safe. Timeshift
+snapshots existed — but they lived on the *same* disk, so a dead SSD took them
+too. This tool automates the fix:
+
+- Timeshift snapshots are created **and uploaded to the cloud pool** weekly.
+- File backups live on MEGA + Drive only.
+- The only recovery-critical local thing left is the CLI itself (`npx` is a
+  clone away).
+
+---
+
+## Requirements
+
+| Tool | Why |
+|---|---|
+| Node.js ≥ 18 | runs the CLI |
+| `rclone` | talks to MEGA and Google Drive (one rclone remote = one account) |
+| `timeshift` | system snapshots (BTRFS mode; rsync mode also works) |
+| `git` | detecting repos so their files are excluded |
+| `curl` | connectivity checks |
+
+```bash
+sudo apt install rclone timeshift git curl
+```
+
+---
+
+## Install
+
+```bash
+npm install -g parrot-blackbox
+```
+
+Run the setup wizard:
+
+```bash
+parrot-blackbox
+```
+
+**The wizard first checks your system and auto-installs anything needed** for
+snapshot backup + restore (`rclone`, `timeshift`, `git`, `curl` — it detects
+your package manager and runs the install with an interactive sudo prompt,
+the gitswitch/theamify way). Then it walks you through: authorizing your
+MEGA / Drive accounts in `rclone config` → registering each remote as an
+account → installing the always-on service → an optional first snapshot.
+
+---
+
+## Quick start (the important bit)
+
+```bash
+# 1. Install, then run the wizard (installs missing tools for you):
+npm install -g parrot-blackbox
+parrot-blackbox
+
+# 2. Create your rclone remotes (one per MEGA / Drive account) if not done:
+rclone config
+
+# 3. Add them to the pool (repeat for every account):
+parrot-blackbox account add mega mega-account-1
+parrot-blackbox account add gdrive my-drive-1
+parrot-blackbox account list          # see the whole pool + quota
+
+# 4. Force your FIRST snapshot backup right now (do this before a fresh
+#    install — it captures the whole system and uploads it to the cloud):
+parrot-blackbox force
+```
+
+`parrot-blackbox status` shows the pool, network state, daemon state, last run
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `parrot-blackbox` | Interactive setup wizard (checks & **auto-installs** needed tools) |
+| `parrot-blackbox run` | Run any due/pending backups now (safe for cron) |
+| `parrot-blackbox force` | ⭐ Run every enabled backup NOW (default = weekly snapshot) `[sudo]` |
+| `parrot-blackbox snapshot now` | Create + upload a Weekly Timeshift snapshot `[sudo]` |
+| `parrot-blackbox snapshot list` | Local & cloud snapshots |
+| `parrot-blackbox snapshot prune` | Delete snapshots past the keep limit `[sudo]` |
+| `parrot-blackbox list` | List cloud file backups |
+| `parrot-blackbox restore` | Interactive restore wizard `[sudo]` |
+| `parrot-blackbox restore files <id> <dir>` | Recover a file backup into a folder |
+| `parrot-blackbox restore snapshot <id> --yes` | Overwrite the whole system from a cloud snapshot `[sudo]` |
+| `parrot-blackbox account add <mega\|gdrive> <remote>` | Add an account to the pool |
+| `parrot-blackbox account list` | Pool summary + per-account quota |
+| `parrot-blackbox account remove <id>` | Remove an account |
+| `parrot-blackbox account quota <id> <GiB>` | Override an account's quota |
+| `parrot-blackbox daemon start\|stop\|status` | Background automation |
+| `parrot-blackbox schedule install\|remove` | systemd / cron always-on setup |
+| `parrot-blackbox doctor` | Full diagnostics |
+| `parrot-blackbox status` | Quick status |
+| `parrot-blackbox uninstall` | Remove everything (cloud backups kept) |
+
+---
+
+## How the smart storage pool works
+
+```
+5 MEGA      (20 GiB each)
+5 Drive     (10 GiB each)
+──────────────────────────────
+≈ 150 GiB managed automatically
+```
+
+- Every account is exactly one rclone remote (`mega-1:`, `drive-2:` …).
+- Each backup has **one manifest** that records where every file (or chunk) is.
+- Placement picks the account that would end up with the **lowest used
+  percentage** (water-filling), then most free.
+- A file that doesn't fit any single account is split at `chunkSize` boundaries
+  and the pieces are spread across accounts — restore reassembles byte-perfect.
+- The manifest is written to the cloud **and** mirrored locally, so a wiped
+  machine can still find and restore everything.
+
+Never out of storage again — and if you ever pass 175 GiB of backups, the
+allocator fails loudly with guidance instead of half-uploading.
+
+---
+
+## Retention (the "never out of disk / cloud" guarantees)
+
+| What | Default | Result |
+|---|---|---|
+| Snapshots (Timeshift) | enabled, keep the newest **3** | latest + 2 previous weeks; the middle one is the sanity net |
+| File backups | **disabled** (opt-in), keep newest 3 if enabled | no noisy daily uploads unless you want them |
+| Pruning | happens for **local AND cloud in the same pass** | a fresh install can't resurrect old clutter |
+
+The snapshot keep strategy: with `keep: 3` you always have *today's* snapshot
+plus two earlier ones — so a crash mid-backup can still roll back to the most
+recent working state, without wasting cloud or disk space. If you want the most
+space-efficient option, set `keep: 1` and every successful backup erases the
+previous one, leaving a single sane restore point:
+
+```
+$EDITOR ~/.config/parrot-blackbox/config.json   # jobs.snapshots.keep = 1
+```
+
+To ALSO run a daily file-level backup (opt-in), flip it on in the same file:
+
+```
+$EDITOR ~/.config/parrot-blackbox/config.json   # jobs.files.enabled = true
+```
+---
+
+## Recovery guide (fresh install / new machine)
+
+### Option A — restore your files (fonts, images, docs…)
+
+```bash
+parrot-blackbox restore files <backup-id> ~/recovered
+```
+
+### Option B — restore the whole system snapshot (recommended)
+
+```bash
+# on the fresh Parrot:
+npm install -g parrot-blackbox
+rclone config                       # re-add the same remotes
+parrot-blackbox account add mega mega-1   # …add every account
+parrot-blackbox snapshot list       # see what's in the cloud
+parrot-blackbox restore snapshot <snapshot-id> --yes
+```
+
+This downloads the snapshot into Timeshift, then runs the interactive restore
+(expect a `sudo` password prompt) — it **overwrites the fresh install's system
+root** with the snapshot. After a reboot you're back to your old system; then
+`sudo apt update && sudo apt upgrade` to move onto a newer Parrot release if
+you installed one. Encryption or not makes no difference — snapshot restore is
+run from inside the OS.
+
+---
+
+## Automation details (what "crash-proof" actually means)
+
+- **Scheduling** — file backups daily 22:00, snapshots every Saturday 22:00
+  (a recent Friday-through-Sunday window is hidden from storage by keeping
+  only 3 generations). Both schedules are configurable.
+- **Catch-up** — the daemon polls every 60s. On each tick it computes *every*
+  calendar due that has passed since the last one it considered, drops the
+  ancient backlog beyond `catchUpLimit`, and drains the rest **oldest first**.
+  If it's offline at that moment, the dues stay pending and the daemon watches
+  for the offline→online edge to fire immediately.
+- **Crash-proofing** — state is written atomically (tmp + rename); the journal
+  appends one line per event; every job opens a journal entry and only closes
+  it on success; a single process lock (`withLock`) keeps the daemon and a
+  manual `force` from colliding; stale locks (dead pid / expired TTL) are
+  reclaimed automatically.
+- **Non-interactive sudo** — the daemon never hangs on a password: it uses
+  `sudo -n`, and if the sudo timestamp is lapsed it marks the snapshot job
+  `deferred` and retries on the next tick. Run any interactive command (e.g.
+  `parrot-blackbox snapshot now`) once to re-arm sudo.
+
+---
+
+## Uninstall
+
+```bash
+parrot-blackbox uninstall
+```
+
+Stops the daemon, drops the systemd/cron schedule, deletes local config/state
+and the npm package. **Cloud backups are never touched.**
+
+---
+
+## Development
+
+```bash
+npm install
+npm test                # unit tests + sandbox e2e tests (real CLI, fake cloud)
+npm run publish:dry-run # inspect the tarball
+npm run release:patch   # test → version bump → git push --follow-tags
+npm publish             # to the public npm registry
+```
+
+The e2e suite (Level-5 safety proof) runs the **real CLI** against **stub**
+`rclone`/`timeshift`/`sudo` binaries and a **fake cloud** — it never touches a
+real disk, real account or real network.
+
+## License
+
+MIT
+and pending backups. `parrot-blackbox doctor` is the full diagnostic.

package/bin/parrot-blackbox.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "parrot-blackbox",
+  "version": "1.0.0",
+  "description": "parrot-blackbox — 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",
+  "bin": {
+    "parrot-blackbox": "bin/parrot-blackbox.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:sandbox": "node --test test/e2e.test.js",
+    "publish:dry-run": "npm publish --dry-run --access public",
+    "prepublishOnly": "npm test",
+    "release:patch": "npm test && npm version patch -m \"chore(release): %s\" && git push --follow-tags",
+    "release:minor": "npm test && npm version minor -m \"chore(release): %s\" && git push --follow-tags",
+    "release:major": "npm test && npm version major -m \"chore(release): %s\" && git push --follow-tags"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DonArtkins/parrot-blackbox.git"
+  },
+  "homepage": "https://github.com/DonArtkins/parrot-blackbox#readme",
+  "bugs": {
+    "url": "https://github.com/DonArtkins/parrot-blackbox/issues"
+  },
+  "keywords": [
+    "backup",
+    "recovery",
+    "snapshot",
+    "timeshift",
+    "mega",
+    "google-drive",
+    "rclone",
+    "parrot",
+    "parrot-os",
+    "linux",
+    "automation",
+    "crash-proof",
+    "cli",
+    "wizard"
+  ],
+  "author": "Don Artkins (https://github.com/DonArtkins)",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "citty": "^0.2.2",
+    "execa": "^8.0.1",
+    "picocolors": "^1.1.1"
+  }
+}

package/src/backup/git-exclude.js

@@ -0,0 +1,122 @@
+/**
+ * Source walker with the parrot-blackbox golden rule: EVERYTHING tracked by
+ * GitHub is already backed up, so any directory inside a git work tree is
+ * skipped entirely (we keep only what GitHub does NOT have). User-provided
+ * exclude globs are applied on top.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execaSync } from 'execa';
+import { matchesAny } from '../util/misc.js';
+
+/** Resolve `~/x` and relative paths against a home dir. */
+export function expandPath(p, home) {
+  if (String(p).startsWith('~/')) return path.join(home, p.slice(2));
+  if (String(p) === '~') return home;
+  return path.resolve(p);
+}
+
+/** Nearest enclosing git work-tree root above `dir`, or null. */
+export function gitTopLevel(dir) {
+  try {
+    const res = execaSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { reject: false });
+    if (res.exitCode === 0 && res.stdout.trim()) return path.resolve(res.stdout.trim());
+  } catch {
+    /* no git available */
+  }
+  return null;
+}
+
+function pathHasGitDir(dir) {
+  return fs.existsSync(path.join(dir, '.git'));
+}
+
+/**
+ * Collect files to back up from `sources`, skipping:
+ *  - any source that lives inside a git work tree (GitHub has those files)
+ *  - any nested directory that is itself a git repo
+ *  - anything matching the exclude globs
+ * @param {string[]} sources
+ * @param {{exclude?:string[], home?:string}} opts
+ * @returns {{files:Array<{abs:string,rel:string}>, skippedRepos:string[], skipped:number, missing:string[]}}
+ */
+export function collectFiles(sources, { exclude = [], home = process.env.HOME } = {}) {
+  const files = [];
+  const skippedRepos = [];
+  const missing = [];
+  let skipped = 0;
+
+  for (const src of sources) {
+    const abs = expandPath(src, home);
+    if (!fs.existsSync(abs)) {
+      missing.push(src);
+      continue;
+    }
+
+    const top = gitTopLevel(abs);
+    if (top) {
+      // The whole source is inside a git repo — GitHub already owns it.
+      skippedRepos.push(abs);
+      continue;
+    }
+
+    const prefix = path.basename(abs) || 'sources';
+    walk(abs, prefix, abs);
+  }
+
+  function walk(abs, relPrefix, sourceRoot) {
+    for (const ent of fs.readdirSync(abs, { withFileTypes: true })) {
+      const eAbs = path.join(abs, ent.name);
+      const rel = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+      const relFromSource = path.relative(sourceRoot, eAbs);
+      if (matchesAny(relFromSource.replace(/\\/g, '/'), exclude)) {
+        skipped += 1;
+        continue;
+      }
+      let st;
+      try {
+        st = fs.statSync(eAbs);
+      } catch {
+        skipped += 1;
+        continue;
+      }
+      if (ent.isSymbolicLink()) {
+        skipped += 1; // symlinks resolved when restoring via snapshot; keep tree clean here
+        continue;
+      }
+      if (ent.isDirectory()) {
+        if (pathHasGitDir(eAbs)) {
+          skippedRepos.push(eAbs); // nested git repo — GitHub has it
+          continue;
+        }
+        walk(eAbs, rel, sourceRoot);
+      } else {
+        files.push({ abs: eAbs, rel });
+      }
+    }
+  }
+
+  return { files, skippedRepos, skipped, missing };
+}
+
+/** Copy collected files into a staging root, preserving `rel`. */
+export function stageFiles(files, stagingRoot) {
+  for (const f of files) {
+    const dest = path.join(stagingRoot, ...f.rel.split('/'));
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(f.abs, dest);
+  }
+  return stagingRoot;
+}
+
+/** Total byte size of collected files. */
+export function sumFiles(files) {
+  return files.reduce((s, f) => {
+    try {
+      return s + fs.statSync(f.abs).size;
+    } catch {
+      return s;
+    }
+  }, 0);
+}

package/src/backup/restore.js

@@ -0,0 +1,93 @@
+/**
+ * Recovery. Two paths:
+ *  - `restore snapshot` — pull a cloud snapshot onto local disk, register it
+ *    with Timeshift, then run the interactive restore (overwrites the running
+ *    system's root files, exactly what you want over a fresh install). sudo
+ *    password is prompted interactively, the same way gitswitch/theamify do.
+ *  - `restore files`   — download one file-backup generation to a local
+ *    directory so specific lost files (fonts, images…) come back without
+ *    touching the system.
+ *
+ * Restoring a snapshot is Level-5 destructive: requires an explicit
+ * confirmation (or `--yes`) before anything is overwritten.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { journal } from '../core/store.js';
+import { stateDir, timeshiftDir } from '../core/paths.js';
+import { refreshAccounts } from '../storage/accounts.js';
+import { discoverManifest, restoreArtifact } from '../storage/archive.js';
+import { listLocalSnapshots } from './snapshot.js';
+import { sudoInteractive } from '../util/sudo.js';
+import { bytesHuman } from '../util/misc.js';
+
+/** Restore a file backup generation into a writable local directory. */
+export async function restoreFiles({ id, toDir, accounts, cfg, onProgress }) {
+  const found = await discoverManifest('files', id, accounts, cfg.storage.remoteRoot);
+  if (!found) {
+    // Fall back to scanning every account for the artifact id.
+    throw new Error(`no file backup found for id "${id}" — check with \`parrot-blackbox list\``);
+  }
+  fs.mkdirSync(toDir, { recursive: true });
+  const res = await restoreArtifact(found.manifest, toDir, { onProgress });
+  journal('restore', `files id=${id} -> ${toDir} files=${res.files} bytes=${res.bytes}`);
+  return { id, toDir, ...res, manifest: found.manifest };
+}
+
+/**
+ * Restore a system snapshot.
+ * @param {object} opts {id, accounts, cfg, toDir?, confirm, privileged?, onProgress}
+ */
+export async function restoreSnapshot({ id, accounts, cfg, toDir, confirm = false, privileged = 'interactive', onProgress }) {
+  if (!confirm) {
+    throw new Error('Refusing without confirmation — pass `--yes` (or confirm interactively). This overwrites the whole system.');
+  }
+
+  const found = await discoverManifest('snapshots', id, accounts, cfg.storage.remoteRoot);
+  if (!found) {
+    throw new Error(`no snapshot backup found for id "${id}" — check with \`parrot-blackbox snapshot list\``);
+  }
+
+  // Is it already on local disk?
+  const localSnaps = await listLocalSnapshots({ privileged }).catch(() => []);
+  const localSnap = localSnaps.find((s) => s.name === id);
+
+  if (!localSnap) {
+    // Download to a staging dir first, then move into the Timeshift folder.
+    const tmpRoot = path.join(stateDir(), 'restore', id);
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+    fs.mkdirSync(tmpRoot, { recursive: true });
+    const res = await restoreArtifact(found.manifest, tmpRoot, { onProgress });
+    journal('restore', `snapshot id=${id} downloaded ${res.bytes} bytes`);
+    await placeIntoTimeshift(id, tmpRoot, cfg, privileged);
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+    console.log(`✔ Downloaded snapshot ${bytesHuman(res.bytes)} and registered it with Timeshift.`);
+  }
+
+  // Run the actual restore (interactive sudo → the password prompt is visible).
+  console.log(`\nRestoring snapshot ${id} over the current system…\n`);
+  const res = await sudoInteractive(['timeshift', '--restore', '--snapshot', id, '--yes']);
+  if (res.exitCode !== 0) throw new Error(`timeshift --restore failed (exit ${res.exitCode})`);
+  journal('restore', `snapshot id=${id} RESTORED`);
+  console.log(`\n✔ Restore complete. REBOOT now to boot into the restored system.\n`);
+  return { id };
+}
+
+/** Move a downloaded snapshot tree into the Timeshift snapshot folder (root-owned). */
+async function placeIntoTimeshift(id, tmpRoot, cfg, privileged) {
+  const base = determineSnapshotBase();
+  const target = path.join(base, id);
+  const cmd = `mkdir -p ${shq(base)} && rm -rf ${shq(target)} && cp -a ${shq(tmpRoot)}/. ${shq(target)}/ && chown -R root:root ${shq(target)}`;
+  const res = await sudoInteractive(['bash', '-c', cmd]);
+  if (res.exitCode !== 0) throw new Error(`could not move snapshot into ${base} (exit ${res.exitCode})`);
+  return target;
+}
+
+function determineSnapshotBase() {
+  return path.join(timeshiftDir(), 'snapshots');
+}
+
+function shq(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}

package/src/backup/retention.js

@@ -0,0 +1,22 @@
+/**
+ * Retention: keep only the newest `keep` artifacts (by due date), return the
+ * rest for removal. File backups and snapshots share this rule — snapshots are
+ * pruned BOTH locally (timeshift delete) and in the cloud in one pass.
+ */
+
+/** Newest-first list of artifact ids with the rest marked for removal. */
+export function planPrune(ids, keep) {
+  if (typeof keep !== 'number' || keep < 1) keep = 3;
+  const sorted = [...ids].sort(); // ISO-ish ids sort chronologically
+  if (sorted.length <= keep) return { keep: sorted, prune: [] };
+  return { keep: sorted.slice(-keep), prune: sorted.slice(0, -keep) };
+}
+
+/** Older-than-N-days pruning rule for file backups (kept, prune by date). */
+export function pruneOlderThan(artifacts, maxAgeDays) {
+  const cutoff = Date.now() - maxAgeDays * 86_400_000;
+  return artifacts.filter((a) => {
+    const t = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+    return t < cutoff;
+  });
+}