parrot-blackbox 1.0.1 → 1.0.3

package/README.md

@@ -67,21 +67,21 @@ sudo apt install rclone timeshift git curl
 npm install -g parrot-blackbox
 ```
 
-Run the setup wizard — it does the whole install for you:
+Run it — you land in the **menu wizard** (just like gitswitch):
 
 ```bash
 parrot-blackbox
 ```
 
-**What the wizard does, start to finish:**
-1. **Checks + auto-installs** `rclone`, `timeshift`, `git`, `curl` (interactive
-   sudo prompt, the gitswitch/theamify way).
-2. **Adds your cloud accounts for you** — pick MEGA or Google Drive and enter
-   your email/password; parrot-blackbox creates the rclone remote and registers
-   it in the pool. No raw 68-option `rclone config` menu needed.
-3. Confirms the **schedule** (snapshot every Saturday 22:00).
-4. Installs the **always-on service** (systemd / cron).
-5. Offers to run your **first snapshot** right away.
+**On every launch the wizard:**
+1. **Checks npm for the latest version** and offers to self-update
+   (`npm install -g parrot-blackbox@latest`) if a newer one is published — the
+   latest always comes from the npm registry, never from local state.
+2. Shows a **menu with every feature**: add account, storage pool, check &
+   install tools, snapshot now, run backup, list backups, restore, always-on
+   service, daemon, guided setup, status, doctor, **repair**, **update**,
+   **uninstall**. Choosing an action runs it and returns to the menu — saying
+   "No" to a prompt never kicks you out; only **Exit** / **Ctrl+C** leaves.
 
 ---
 
@@ -110,8 +110,14 @@ and pending backups.
 ## Managing cloud accounts (rclone remotes)
 
 Every MEGA / Google Drive login becomes one rclone remote = one pool account.
-`parrot-blackbox` manages them for you — you never need to use the raw rclone
-menu except for advanced edits.
+There are **two ways** to connect them:
+
+- **Guided (recommended):** `parrot-blackbox` creates the rclone remote *for
+  you* — no menus. `parrot-blackbox remote add mega` prompts for the remote
+  name, email, password and optional 2FA, then registers it.
+- **Manual:** configure remote(s) yourself with the raw `rclone config` — the
+  **complete step-by-step walkthrough of every prompt and every letter is
+  documented below** in the next section.
 
 **Add** (guided — creates the remote AND saves it in the pool):
 ```bash
@@ -150,11 +156,258 @@ passwords, and the allocator's manifests are safe to share.
 
 ---
 
+## 📖 The full `rclone config` manual walkthrough (every letter, every prompt)
+
+> The wizard's *"Configure rclone myself, then register the remote"* path (and
+> the `parrot-blackbox remote config` command) open rclone's interactive menu.
+> This is that menu, explained **prompt by prompt** so you never get lost.
+> The quick alternative that skips all of this: `parrot-blackbox remote add mega`
+> (or `gdrive`) creates the remote for you automatically.
+
+### 1. The main menu — what each letter does
+
+```
+Current remotes:
+
+Name                 Type
+====                 ====
+mega                 mega
+
+e) Edit existing remote
+n) New remote
+d) Delete remote
+r) Rename remote
+c) Copy remote
+s) Set configuration password
+q) Quit config
+e/n/d/r/c/s/q>
+```
+
+| Letter | Word | What it does |
+|---|---|---|
+| `e` | **Edit** | Change an **existing** remote's login (email / password / 2FA) or storage type |
+| `n` | **New** | **Create a brand-new remote** → the flow below |
+| `d` | **Delete** | Remove a remote from the config — rclone asks `y` to confirm |
+| `r` | **Rename** | Give an existing remote a different name |
+| `c` | **Copy** | Duplicate an existing remote under a new name (handy for a 2nd account of the same type) |
+| `s` | **Set config password** | Lock the whole `rclone.conf` with a passphrase (optional; skip unless you want it) |
+| `q` | **Quit** | Leave the menu → you return to parrot-blackbox |
+
+> **The letters you'll use most:** `n` (new remote), `e` (fix a wrong password),
+> `d` (remove an account you don't use), `q` (done).
+
+---
+
+### 2. Adding a MEGA remote (storage number **39**)
+
+Start the menu with `n`, then follow exactly:
+
+```
+e/n/d/r/c/s/q> n                          ⬅ type the letter n and press Enter
+Enter name for new remote.
+name> mega-account-1                       ⬅ type the remote name and press Enter
+```
+
+> **What the name is:** a label for this login. Use something meaningful per
+> account, e.g. `mega-account-1`, `mega-2`, `mega-main`. You'll type this exact
+> name into parrot-blackbox later.
+
+```
+Option Storage.
+Type of storage to configure.
+...long numbered list of 68 providers...
+Storage> 39                                ⬅ type 39 for Mega and press Enter
+```
+
+> **The storage number for each provider:**
+> | Provider | Number to type | (what it says in the list) |
+> |---|---|---|
+> | **Mega** (the one you use) | **`39`** | `39 / Mega - Tier 2 \ (mega)` |
+> | **Google Drive** | **`24`** | `24 / Google Drive - Tier 1 \ (drive)` |
+
+Next rclone asks for login details — this means **the email + password of the
+cloud account** you want to back up to:
+
+```
+Option user.
+User name.
+Enter a value.
+user> info.donartkins.ke@gmail.com         ⬅ type the account's EMAIL and press Enter
+
+Option pass.
+Password.
+Choose an alternative below.
+y) Yes, type in my own password
+g) Generate random password
+y/g> y                                     ⬅ type y to enter your own password
+
+Enter the password:
+password: ********                          ⬅ type the account PASSWORD (invisible)
+Confirm the password:
+password: ********                          ⬅ type it again to confirm
+```
+
+> **What this means:** `user` = the **email address** of your MEGA account.
+> `pass` = that account's **password**. rclone encrypts it before saving it —
+> you'll see `*** ENCRYPTED ***` later.
+
+After the password, optional but present for accounts that have it:
+
+```
+Option 2fa.
+The 2FA code of your MEGA account if the account is set up with one
+Enter a value. Press Enter to leave empty.
+2fa>                                     ⬅ if you use 2FA on this MEGA account, enter the
+                                              current 6-digit code here; if not, press Enter
+```
+---
+
+### 3. Advanced config — ⚠️ **SAY NO** (this is the mistake you kept making)
+
+rclone then asks `Edit advanced config?` **twice**. You almost always want
+**`n` (No)** here — parrot-blackbox works fine with the defaults:
+
+```
+Edit advanced config?
+y) Yes
+n) No (default)
+y/n> n                                  ⬅ type n and press Enter   ✅ SAY NO
+```
+
+If you mistakenly choose `y`, rclone will march you through `debug`,
+`hard_delete`, `use_https`, `encoding`, `description`… — you can press **Enter**
+on every single one to accept defaults, then it asks `Edit advanced config?`
+again → answer `n` the second time. But the easy path is simply **`n` the
+first time**.
+
+When it finishes you get a confirmation:
+
+```
+Configuration complete.
+Options:
+- type: mega
+- user: info.donartkins.ke@gmail.com
+- pass: *** ENCRYPTED ***
+Keep this "mega-account-1" remote?
+y) Yes this is OK (default)
+e) Edit this remote
+d) Delete this remote
+y/e/d> y                                 ⬅ type y to save this remote
+```
+
+> **Important:** this confirmation `y` ("keep this remote") is DIFFERENT from
+> the advanced-config prompt. Here you DO want `y` — it saves the remote you
+> just created.
+
+---
+
+### 4. Adding a Google Drive remote (storage number **24**)
+
+Same `n` flow, but the two differences are the storage number and the auth step:
+
+```
+e/n/d/r/c/s/q> n                          ⬅ n for new
+name> gdrive-account-1                    ⬅ the remote name
+Storage> 24                               ⬅ 24 = Google Drive
+
+-- rclone then prints a big "Use auto config?" section --
+Use auto config?
+y) Yes
+n) No
+y/n> y                                    ⬅ y (opens your browser automatically)
+```
+
+rclone opens a **browser page asking you to sign in to Google** and grant
+access — log in, allow, done. Back in the terminal:
+
+```
+Edit advanced config?
+y) Yes
+n) No (default)
+y/n> n                                    ⬅ ✅ NO
+
+Keep this "gdrive-account-1" remote?
+y) Yes this is OK (default)
+y/e/d> y                                  ⬅ y to keep it
+```
+
+> If the browser doesn't open (headless), choose the manual option rclone gives
+> you and paste the printed verification code into `http://localhost:53682` —
+> but on your desktop the browser usually just opens.
+
+---
+
+### 5. After you quit (`q`) — register the remotes
+
+You arrive back in parrot-blackbox with the message
+`Starting rclone config — follow its prompts, then come back.` Once rclone's
+menu is closed (`q`), the wizard automatically shows the remotes it found and
+lets you pick which to register into the pool:
+
+```
+Select which rclone remotes to add to the backup pool:   ⬅ tick your new names
+```
+
+Each one is then tagged with its provider as you type it into rclone. If you
+quit the wizard before registering, that's fine — either re-run
+`parrot-blackbox` or:
+
+```bash
+parrot-blackbox account add mega mega-account-1     # provider + the remote name you chose in rclone
+parrot-blackbox remote list                         # confirm it's now registered
+```
+
+---
+
+### 6. Editing / renaming / deleting a remote later (the `e` `r` `d` letters)
+
+Fix a wrong password, rename, or delete an old account:
+
+```
+e/n/d/r/c/s/q> e                             ⬅ e = Edit an existing remote
+Choose a number from below ...               ⬅ pick the remote to edit
+Edit remote
+u) Update current
+y) Yes type in my own password
+g) Generate random password
+q) Quit config
+u> y                                         ⬅ choose what to change (u = update this field)
+Name or type of remote > user                ⬅ which field: user, pass, 2fa, type, ...
+user> new@email.com                          ⬅ the new value
+```
+
+Rename:
+```
+e/n/d/r/c/s/q> r                             ⬅ r = Rename
+Old name> mega-account-1                     ⬅ current name
+New name> mega-backup-1                      ⬅ new name
+```
+
+Delete:
+```
+e/n/d/r/c/s/q> d                             ⬅ d = Delete
+Choose a number from below ...               ⬅ pick the remote
+y) Yes this is OK
+e) Edit this remote
+y/e> y                                       ⬅ y confirms permanent deletion
+```
+
+> Any rename/delete also must be mirrored in parrot-blackbox's pool:
+> `parrot-blackbox remote list` shows what's registered, and
+> `parrot-blackbox remote remove <name>` removes an entry from BOTH rclone and
+> the pool in one go.
+
+---
+
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `parrot-blackbox` | Interactive setup wizard (checks & **auto-installs** needed tools) |
+| `parrot-blackbox` | ⭐ **Menu wizard** — every feature in one menu; automatic update check on launch |
+| `parrot-blackbox install` | Same as the menu wizard |
+| `parrot-blackbox repair [--yes]` | Fix a broken install (tools, config, service, pool) |
+| `parrot-blackbox update [--force]` | Check npm & update to the latest published version |
+| `parrot-blackbox setup` | Guided full setup (tools, accounts, schedule, service) |
 | `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]` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parrot-blackbox",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "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",

package/src/cli.js

@@ -3,6 +3,9 @@ import pc from 'picocolors';
 import * as p from '@clack/prompts';
 import { createRequire } from 'node:module';
 import { runSetup } from './commands/setup.js';
+import { runWizard } from './commands/wizard.js';
+import { runRepair } from './commands/manage.js';
+import { runSelfUpdate } from './lib/self.js';
 import { guidedRemoteAdd, deleteRemote, registerRemotesAsAccounts, remoteStatus } from './commands/remote.js';
 import { runDoctor, runStatus, runUninstallWizard } from './commands/manage.js';
 import { installService, removeService } from './commands/service.js';
@@ -36,7 +39,11 @@ function printUsage() {
 ${pc.bold('parrot-blackbox')} ${pc.dim(`v${pkg.version}`)} — crash-proof multi-cloud backup & recovery for Parrot OS
 
 ${pc.bold('Usage:')}
-  parrot-blackbox                     Interactive setup wizard (checks & installs tools)
+  parrot-blackbox                     ⭐ Menu wizard (all features; auto-update check on launch)
+  parrot-blackbox install             Same as the menu wizard
+  parrot-blackbox repair [--yes]      Fix a broken install (tools, config, service, pool)
+  parrot-blackbox update [--force]    Check npm & update to the latest version
+  parrot-blackbox setup               Guided full setup (tools, accounts, schedule, service)
   parrot-blackbox run                 Run any due / pending backups now (safe for cron)
   parrot-blackbox force               ⭐ Run every enabled backup NOW (default = weekly snapshot)  ${pc.dim('[sudo]')}
   parrot-blackbox snapshot now        Create a weekly snapshot + upload it now  ${pc.dim('[sudo]')}
@@ -349,13 +356,27 @@ const main = defineCommand({
       return;
     }
 
-    if (!cmd) return runSetup();
+    if (!cmd) return runWizard();
 
     switch (cmd) {
       case 'setup':
+        // Guided full setup — a distinct, deeper flow (still menu-accessible).
+        return runSetup();
+
       case 'wizard':
+      case 'menu':
       case 'install':
-        return runSetup();
+        return runWizard();
+
+      case 'repair':
+      case 'fix':
+        return runRepair({ auto: process.argv.includes('--yes') });
+
+      case 'update':
+      case 'self-update':
+      case 'selfupdate':
+      case 'upgrade':
+        return runSelfUpdate({ force: process.argv.includes('--force') });
 
       case 'run':
         process.exitCode = await invokeRun('noninteractive');

package/src/commands/manage.js

@@ -124,5 +124,110 @@ export async function runUninstallWizard() {
   if (removed.length) p.log.success(`Removed local data: ${removed.join(', ')}`);
   else p.log.message(pc.dim('No local parrot-blackbox data found.'));
 
-  p.outro(pc.green('Uninstalled. Cloud backups remain safe in your accounts.'));
+  // Remove the npm package too, exactly like gitswitch/theamify.
+  const { selfUninstall } = await import('../lib/self.js');
+  const pkgRemoved = await selfUninstall();
+
+  p.outro(pc.green(
+    `Uninstalled. Cloud backups remain safe in your accounts.${pkgRemoved ? ' The parrot-blackbox command is gone from PATH.' : ''}`,
+  ));
+}
+
+/**
+ * `repair` — fix a broken/partial install. Re-runs every integrity probe:
+ *   - system tools (rclone / timeshift / git / curl) checked + auto-installed
+ *   - config + state dirs recreated if missing / regenerated if corrupt
+ *   - always-on service (systemd / cron) re-installed if missing
+ *   - storage pool entries cross-checked against rclone remotes (stale removed)
+ *   - optional npm reinstall when the data dir is healthy but the CLI is broken
+ * When `auto` is true it runs in non-interactive / repair-and-summary mode.
+ */
+export async function runRepair({ auto = false } = {}) {
+  const { runToolsCheck } = await import('./tools.js');
+  const { installService } = await import('./service.js');
+  const { listRemotes } = await import('../storage/rclone.js');
+  const { listAccounts, removeAccount } = await import('../storage/accounts.js');
+
+  p.intro(pc.bgGreen(pc.black(' 🛠 parrot-blackbox repair ')));
+  const fixed = [];
+
+  // 1. Tools
+  const stillMissing = await runToolsCheck();
+  if (stillMissing.length === 0) p.log.success('Tools OK.');
+  else { p.log.warn('Some tools are still missing — snapshot backup/restore may be unavailable.'); }
+
+  // 2. Config & state
+  let cfgPath;
+  const { configFile, ensureStateDirs } = await import('../core/paths.js');
+  const { loadConfig } = await import('../core/store.js');
+  try {
+    cfgPath = configFile();
+    ensureStateDirs();
+    loadConfig(); // throws if corrupt JSON
+    p.log.success('Config & state OK.');
+  } catch (e) {
+    p.log.warn(`Config/state issue: ${e.message}`);
+    // Regenerate a fresh config if absent or corrupt.
+    try {
+      const { defaultConfig, saveConfig } = await import('../core/store.js');
+      let cfg = null;
+      try { cfg = loadConfig(); } catch { cfg = null; }
+      if (!cfg) {
+        saveConfig(defaultConfig());
+        fixed.push('config');
+        p.log.success('Config recreated.');
+      }
+    } catch (e2) {
+      p.log.warn(`Could not recreate config: ${e2.message}`);
+    }
+  }
+
+  // 3. Service
+  try {
+    const { serviceFile, daemonLogFile } = await import('../core/paths.js');
+    const { serviceBackend } = await import('./service.js');
+    const fsMod = await import('node:fs');
+    if (serviceBackend() === 'systemd' && !fsMod.existsSync(serviceFile())) {
+      const backend = await installService();
+      p.log.success(`Always-on service re-installed via ${backend}.`);
+      fixed.push('service');
+    } else {
+      p.log.success('Service OK.');
+    }
+  } catch (e) {
+    p.log.warn(`Service check failed: ${e.message}`);
+  }
+
+  // 4. Pool ↔ rclone cross-check
+  try {
+    const remotes = await listRemotes();
+    const accs = listAccounts();
+    let stale = 0;
+    for (const a of accs) {
+      if (!remotes.includes(a.remote)) {
+        removeAccount(a.remote);
+        stale += 1;
+      }
+    }
+    if (stale) { p.log.success(`Removed ${stale} stale pool entry(ies) whose rclone remote no longer exists.`); fixed.push(`pool(${stale})`); }
+    else p.log.success(`Pool OK (${accs.length} account(s), ${remotes.length} rclone remote(s)).`);
+  } catch (e) {
+    p.log.warn(`Pool check failed: ${e.message}`);
+  }
+
+  // 5. Optional npm reinstall (repair a broken CLI install)
+  if (!auto) {
+    const want = await p.confirm({
+      message: 'Reinstall parrot-blackbox from npm to repair the executable?',
+      initialValue: false,
+    });
+    if (!p.isCancel(want) && want) {
+      const { runSelfUpdate } = await import('../lib/self.js');
+      p.log.step('Reinstalling from npm…');
+      const did = await runSelfUpdate({ force: true });
+      if (did) fixed.push('npm');
+    }
+  }
+
+  p.outro(pc.green(fixed.length ? `Repair complete — fixed: ${fixed.join(', ')}.` : 'Nothing to repair — everything looks healthy.'));
 }

package/src/commands/tools.js

@@ -0,0 +1,93 @@
+/**
+ * System tools needed for snapshot backup & restore — detection + auto-install
+ * (the gitswitch/theamify companion-tool pattern). Shared by the wizard menu,
+ * the guided setup and the CLI.
+ */
+
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { execa } from 'execa';
+import { hasCommandSync } from '../core/store.js';
+
+export 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). */
+export function detectPackageManager() {
+  const order = ['apt-get', 'dnf', 'yum', 'pacman', 'zypper', 'apk'];
+  return order.find((name) => hasCommandSync(name)) || null;
+}
+
+/** Tools that are missing on the system right now. */
+export function missingTools() {
+  return REQUIRED.filter((t) => !hasCommandSync(t.bin));
+}
+
+/**
+ * Auto-install the tools the system needs. Prompts per missing tool, then runs
+ * the package-manager install with an interactive sudo prompt (spinner released
+ * first, Ctrl+C safe). Returns the freshly installed tool names.
+ */
+export async function ensureSystemTools() {
+  const missing = missingTools();
+  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) || !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}…`);
+    s.stop(''); // release the terminal first so the sudo password prompt is usable
+    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;
+}
+
+/** Check & install; reports status. Returns still-missing tools. */
+export async function runToolsCheck() {
+  const missing = missingTools();
+  if (missing.length === 0) {
+    p.log.success(`All tools present: ${REQUIRED.map((r) => r.bin).join(', ')}`);
+    return [];
+  }
+  const installed = await ensureSystemTools();
+  const still = missingTools();
+  if (installed.length) p.log.success(`Installed: ${installed.join(', ')}`);
+  if (still.length) p.log.warn(`Still missing: ${still.map((m) => m.bin).join(', ')}`);
+  else p.log.success(`All required tools now present: ${REQUIRED.map((r) => r.bin).join(', ')}`);
+  if (still.includes('timeshift')) {
+    p.log.message(pc.dim('Timeshift missing = snapshot backup & restore are unavailable. Install it before relying on snapshots.'));
+  }
+  return still;
+}

package/src/commands/wizard.js

@@ -0,0 +1,368 @@
+/**
+ * The gitswitch-style menu wizard (default command).
+ *
+ *  - CARRIES OUT AN AUTOMATIC UPDATE CHECK on launch (latest from the npm
+ *    registry, never from local state) and offers to install it.
+ *  - Then shows a menu with EVERY feature; choosing an action runs it and
+ *    RETURNS TO THE MENU. Saying "No" to a prompt never kicks you out — only
+ *    Exit / Ctrl+C leaves the wizard.
+ */
+
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { runToolsCheck } from './tools.js';
+import { guidedRemoteAdd } from './remote.js';
+import { listAccounts, refreshAccounts, poolSummary, addAccount, removeAccount } from '../storage/accounts.js';
+import { loadConfig, saveConfig } from '../core/store.js';
+import { runDueJobs } from '../daemon/scheduler.js';
+import { runSnapshotNow, listLocalSnapshots } from '../backup/snapshot.js';
+import { listArtifacts } from '../storage/archive.js';
+import { restoreFiles, restoreSnapshot } from '../backup/restore.js';
+import { installService, removeService } from './service.js';
+import { startDaemon, stopDaemon, daemonRunning } from '../daemon/daemon.js';
+import { runDoctor, runStatus, runUninstallWizard } from './manage.js';
+import { runSetup } from './setup.js';
+import { bytesHuman } from '../util/misc.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+
+async function importSelf() {
+  return import('../lib/self.js');
+}
+
+/** Launch-time upgrade check — latest is always fetched from npm. */
+async function autoUpdateCheck() {
+  const { checkForUpdate, promptSelfUpdate } = await importSelf();
+  try {
+    const { outdated } = await checkForUpdate();
+    if (outdated) await promptSelfUpdate();
+  } catch {
+    /* offline / npm missing — never block the wizard on the update check */
+  }
+}
+
+/** Add one (or more) cloud accounts, guided. */
+async function addAccountAction() {
+  for (;;) {
+    const provider = await p.select({
+      message: 'Which provider?',
+      options: [
+        { value: 'mega', label: 'MEGA (20 GB free tier)' },
+        { value: 'gdrive', label: 'Google Drive (10 GB free tier)' },
+        { value: 'back', label: '← Back' },
+      ],
+    });
+    if (p.isCancel(provider) || provider === 'back') return;
+    const res = await guidedRemoteAdd({ provider });
+    if (res.ok) p.log.success(`✔ ${pc.bold(res.name)} (${res.provider}) added to the pool.`);
+    else if (res.error) p.log.warn(res.error);
+    else if (res.cancelled) { p.log.message(pc.dim('Cancelled.')); return; }
+    const again = await p.confirm({ message: 'Add another account?', initialValue: false });
+    if (p.isCancel(again) || !again) return;
+  }
+}
+
+/** Storage pool sub-menu: list / add / remove / quota. */
+async function accountsMenu() {
+  const sub = await p.select({
+    message: 'Storage pool — accounts are rclone remotes (MEGA / Google Drive)',
+    options: [
+      { value: 'list', label: '🔎 List accounts & quotas' },
+      { value: 'add', label: '➕ Add account to the pool (existing rclone remote)' },
+      { value: 'remove', label: '➖ Remove account from the pool' },
+      { value: 'quota', label: '📐 Set an account quota (GiB)' },
+      { value: 'back', label: '← Back' },
+    ],
+  });
+  if (p.isCancel(sub) || sub === 'back') return;
+
+  if (sub === 'list') {
+    const accs = listAccounts();
+    const cfg = loadConfig();
+    if (!accs.length) { p.log.message(pc.dim('No accounts yet — choose “Add account”.')); return; }
+    const refreshed = await refreshAccounts(cfg);
+    p.log.message(poolSummary(refreshed).text);
+    for (const a of refreshed) {
+      p.log.message(`  - ${pc.bold(a.label)}  ${a.provider}  remote=${a.remote}  ${bytesHuman(a.free)} free / ${bytesHuman(a.total)}`);
+    }
+    return;
+  }
+  if (sub === 'add') {
+    const provider = await p.select({
+      message: 'Provider of the remote you already created (via rclone config / remote add)?',
+      options: [
+        { value: 'mega', label: 'MEGA' },
+        { value: 'gdrive', label: 'Google Drive' },
+      ],
+    });
+    if (p.isCancel(provider)) return;
+    const name = await p.text({ message: 'rclone remote name (e.g. mega, mega-account-1):' });
+    if (p.isCancel(name) || !name) return;
+    const res = await addAccount({ provider, remote: name });
+    if (res.ok) p.log.success(`✔ ${res.account.label} added.`);
+    else p.log.warn(res.error);
+    return;
+  }
+  if (sub === 'remove') {
+    const accs = listAccounts();
+    if (!accs.length) { p.log.message(pc.dim('No accounts to remove.')); return; }
+    const pick = await p.select({
+      message: 'Remove which account?',
+      options: accs.map((a) => ({ value: a.remote, label: `${a.remote} (${a.provider})` })).concat([{ value: '__back', label: '← Back' }]),
+    });
+    if (p.isCancel(pick) || pick === '__back') return;
+    if (removeAccount(pick)) p.log.success(`✔ Removed ${pc.bold(pick)} from the pool.`);
+    else p.log.warn(`Could not remove ${pick}.`);
+    return;
+  }
+  if (sub === 'quota') {
+    const accs = listAccounts();
+    if (!accs.length) { p.log.message(pc.dim('No accounts yet.')); return; }
+    const pick = await p.select({
+      message: 'Which account?',
+      options: accs.map((a) => ({ value: a.remote, label: `${a.remote} (${a.provider})` })).concat([{ value: '__back', label: '← Back' }]),
+    });
+    if (p.isCancel(pick) || pick === '__back') return;
+    const giB = await p.text({ message: `Quota in GiB for ${pick}:`, initialValue: '20' });
+    if (p.isCancel(giB) || !giB) return;
+    const cfg = loadConfig();
+    const acc = (cfg.storage.accounts || []).find((a) => a.remote === pick);
+    if (!acc) { p.log.warn(`No account matched ${pick}.`); return; }
+    acc.quotaGiB = Number(giB);
+    saveConfig(cfg);
+    p.log.success(`✔ ${pick} quota set to ${giB} GiB.`);
+  }
+}
+
+/** Run every enabled backup right now. */
+async function backupNowAction() {
+  const s = p.spinner();
+  s.start('Running backup…');
+  s.stop('');
+  const res = await runDueJobs({ force: true, privileged: 'interactive' });
+  const report = res.report || [];
+  if (report.length === 0) { p.log.message(pc.dim('No enabled backup jobs.')); return; }
+  for (const r of report) {
+    if (r.ok) {
+      const size = r.size ? ` (${bytesHuman(r.size)})` : '';
+      p.log.success(r.snapshot
+        ? `✔ Snapshot ${r.snapshot} created & uploaded${size}.`
+        : `✔ File backup ${r.due} stored${size}.`);
+      if (r.pruned?.length) p.log.message(pc.dim(`Pruned: ${r.pruned.join(', ')}`));
+    } else if (r.deferred) {
+      p.log.warn(`⏸ Snapshot deferred (sudo needed) — run \`parrot-blackbox snapshot now\` once to authenticate.`);
+    } else {
+      p.log.warn(`✖ ${r.type} ${r.due} failed: ${r.error}`);
+    }
+  }
+}
+
+/** Create + upload a snapshot immediately. */
+async function snapshotNowAction() {
+  try {
+    const r = await runSnapshotNow();
+    p.log.success(`✔ Snapshot ${r.snapshot} created & uploaded (${bytesHuman(r.manifest?.totalSize ?? 0)}).`);
+    if (r.pruned?.length) p.log.message(pc.dim(`Pruned: ${r.pruned.join(', ')}`));
+  } catch (e) {
+    p.log.warn(`✖ ${e.message}`);
+  }
+}
+
+/** List local + cloud snapshots and file backups. */
+async function listBackupsAction() {
+  const cfg = loadConfig();
+  const accs = listAccounts();
+  p.log.message(pc.bold('Local snapshots (Timeshift):'));
+  try {
+    const local = await listLocalSnapshots({ privileged: 'noninteractive' });
+    if (!local.length) p.log.message(pc.dim('  none'));
+    for (const sn of local) p.log.message(`  - ${pc.cyan(sn.name)}`);
+  } catch (e) {
+    p.log.message(pc.dim(`  ${e.message}`));
+  }
+  if (accs.length) {
+    p.log.message(pc.bold('Cloud snapshots:'));
+    const cloudSnaps = await listArtifacts('snapshots', accs, cfg.storage.remoteRoot);
+    if (!cloudSnaps.length) p.log.message(pc.dim('  none'));
+    for (const c of cloudSnaps) p.log.message(`  - ${pc.cyan(c.id)}  ${bytesHuman(c.totalSize)}`);
+    p.log.message(pc.bold('Cloud file backups:'));
+    const files = await listArtifacts('files', accs, cfg.storage.remoteRoot);
+    if (!files.length) p.log.message(pc.dim('  none'));
+    for (const f of files) p.log.message(`  - ${pc.cyan(f.id)}  ${bytesHuman(f.totalSize)}`);
+  } else {
+    p.log.message(pc.dim('No accounts configured — add one from the menu.'));
+  }
+}
+/** Restore files or a system snapshot. */
+async function restoreMenu() {
+  const accs = listAccounts();
+  if (!accs.length) { p.log.warn('No accounts configured — nothing to restore from cloud yet.'); return; }
+  const cfg = loadConfig();
+  const kind = await p.select({
+    message: 'Restore what?',
+    options: [
+      { value: 'files', label: '📄 File backup (fonts/images/docs into a folder)' },
+      { value: 'snapshot', label: '💽 System snapshot (overwrites the running system)', hint: '[sudo]' },
+      { value: 'back', label: '← Back' },
+    ],
+  });
+  if (p.isCancel(kind) || kind === 'back') return;
+
+  if (kind === 'files') {
+    const artifacts = await listArtifacts('files', accs, cfg.storage.remoteRoot);
+    if (!artifacts.length) { p.log.warn('No file backups found.'); return; }
+    const id = await p.select({
+      message: 'Pick a backup generation:',
+      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}` });
+    if (p.isCancel(toDir) || !toDir) return;
+    fs.mkdirSync(toDir, { recursive: true });
+    try {
+      const res = await restoreFiles({ id, toDir, accounts: accs, cfg });
+      p.log.success(`✔ Restored ${res.files} file(s), ${bytesHuman(res.bytes)} into ${toDir}`);
+    } catch (e) {
+      p.log.warn(`✖ ${e.message}`);
+    }
+    return;
+  }
+
+  const cloud = await listArtifacts('snapshots', accs, cfg.storage.remoteRoot);
+  if (!cloud.length) { p.log.warn('No cloud snapshots found.'); return; }
+  const id = await p.select({
+    message: 'Pick a snapshot to restore:',
+    options: cloud.map((c) => ({ value: c.id, label: `${c.id}  (${bytesHuman(c.totalSize)})` })).concat([{ value: '__back', label: '← Back' }]),
+  });
+  if (p.isCancel(id) || id === '__back') return;
+  const confirm = await p.confirm({
+    message: pc.red(`This OVERWRITES the running system with snapshot ${id}. Continue?`),
+    initialValue: false,
+  });
+  if (p.isCancel(confirm) || !confirm) { p.log.message(pc.dim('Restore aborted — nothing was touched.')); return; }
+  const s = p.spinner();
+  s.start('Preparing restore…');
+  s.stop('');
+  try {
+    await restoreSnapshot({ id, accounts: accs, cfg, confirm: true, privileged: 'interactive' });
+  } catch (e) {
+    p.log.warn(`✖ ${e.message}`);
+  }
+}
+
+/** Always-on service sub-menu. */
+async function serviceMenu() {
+  const sub = await p.select({
+    message: 'Always-on background service (systemd user unit / cron fallback)',
+    options: [
+      { value: 'install', label: '✅ Install service' },
+      { value: 'remove', label: '❌ Remove service' },
+      { value: 'back', label: '← Back' },
+    ],
+  });
+  if (p.isCancel(sub) || sub === 'back') return;
+  if (sub === 'install') {
+    const backend = await installService();
+    p.log.success(`✔ Always-on service installed via ${pc.cyan(backend)}.`);
+  } else {
+    await removeService();
+    p.log.success('✔ Service removed.');
+  }
+}
+
+/** Daemon sub-menu. */
+async function daemonMenu() {
+  const sub = await p.select({
+    message: `Daemon is currently ${daemonRunning() ? pc.green('running') : pc.yellow('stopped')}`,
+    options: [
+      { value: 'start', label: '▶️  Start daemon' },
+      { value: 'stop', label: '⏹  Stop daemon' },
+      { value: 'status', label: '📊 Show status' },
+      { value: 'back', label: '← Back' },
+    ],
+  });
+  if (p.isCancel(sub) || sub === 'back') return;
+  if (sub === 'start') {
+    const res = await startDaemon();
+    if (res.started) p.log.success(`✔ Daemon started (pid ${res.pid}).`);
+    else p.log.message(pc.yellow(`Daemon ${res.reason || 'already running'}.`));
+  } else if (sub === 'stop') {
+    const res = await stopDaemon();
+    if (res.stopped) p.log.success('✔ Daemon stopped.');
+    else p.log.message(pc.yellow(`Daemon ${res.reason || 'not running'}.`));
+  } else {
+    p.log.message(`Daemon: ${daemonRunning() ? pc.green('running') : pc.yellow('not running')}`);
+  }
+}
+/**
+ * Main wizard — menu loop. Only Exit / Ctrl+C leaves it; saying "No" to any
+ * prompt just returns you to this menu.
+ */
+export async function runWizard() {
+  p.intro(pc.bgYellow(pc.black(` 🦜 parrot-blackbox v${pkg.version} `)));
+
+  if (!process.stdin.isTTY) {
+    p.log.warn('No interactive terminal detected — run subcommands directly: `parrot-blackbox help`');
+    p.outro('Bye! 👋');
+    return;
+  }
+
+  // Automatic update check (latest always fetched from npm).
+  await autoUpdateCheck();
+
+  for (;;) {
+    const action = await p.select({
+      message: 'What would you like to do?',
+      options: [
+        { value: 'add', label: '➕ Add cloud account  (MEGA / Google Drive)', hint: 'sets up rclone for you' },
+        { value: 'accounts', label: '🗂 Storage pool', hint: 'list / add / remove / quota' },
+        { value: 'tools', label: '🛠 Check & install tools', hint: 'rclone, timeshift, git, curl' },
+        { value: 'snapshot', label: '📸 Snapshot now', hint: 'create + upload a weekly snapshot' },
+        { value: 'backup', label: '💾 Run backup now', hint: 'every enabled job (default = snapshot)' },
+        { value: 'list', label: '📋 List backups', hint: 'local + cloud snapshots, file backups' },
+        { value: 'restore', label: '♻️  Restore', hint: 'files or system snapshot' },
+        { value: 'service', label: '⏱ Always-on service', hint: 'install / remove' },
+        { value: 'daemon', label: '🐚 Daemon', hint: 'start / stop / status' },
+        { value: 'setup', label: '🧭 Guided setup', hint: 'walk every setup step' },
+        { value: 'status', label: '📊 Status', hint: 'quick overview' },
+        { value: 'doctor', label: '🩺 Doctor', hint: 'full diagnostics' },
+        { value: 'repair', label: '🛠  Repair broken install', hint: 'check tools, config, service, pool' },
+        { value: 'update', label: '🔄 Update parrot-blackbox', hint: 'check npm & install latest' },
+        { value: 'uninstall', label: '🗑 Uninstall', hint: 'remove everything (cloud kept)' },
+        { value: 'exit', label: '📴 Exit', hint: 'leave the wizard' },
+      ],
+    });
+
+    if (p.isCancel(action) || action === 'exit') {
+      p.outro('Bye! 👋');
+      return;
+    }
+
+    try {
+      switch (action) {
+        case 'add': await addAccountAction(); break;
+        case 'accounts': await accountsMenu(); break;
+        case 'tools': await runToolsCheck(); break;
+        case 'snapshot': await snapshotNowAction(); break;
+        case 'backup': await backupNowAction(); break;
+        case 'list': await listBackupsAction(); break;
+        case 'restore': await restoreMenu(); break;
+        case 'service': await serviceMenu(); break;
+        case 'daemon': await daemonMenu(); break;
+        case 'setup': await runSetup(); break;
+        case 'status': await runStatus(); break;
+        case 'doctor': await runDoctor(); break;
+        case 'repair': { const { runRepair } = await import('./manage.js'); await runRepair(); break; }
+        case 'update': { const { runSelfUpdate } = await import('../lib/self.js'); await runSelfUpdate(); break; }
+        case 'uninstall': await runUninstallWizard(); p.outro('parrot-blackbox removed — cloud backups are safe.'); return;
+        default: break;
+      }
+    } catch (e) {
+      p.log.warn(`✖ ${e.message}`);
+    }
+    p.log.message(pc.dim('──────────────────────────────────────────'));
+  }
+}

package/src/lib/self.js

@@ -0,0 +1,122 @@
+/**
+ * Self-update — mirrors the gitswitch/theamify/warp-wizard pattern.
+ *
+ * The LATEST version always comes from the npm registry (`npm view`), never
+ * from local state, so stale installs are caught and updated on launch.
+ */
+
+import { execa } from 'execa';
+import pc from 'picocolors';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+
+export const NPM_NAME = pkg.name; // parrot-blackbox
+
+export function compareVersions(a, b) {
+  const pa = String(a || '').split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || '').split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Query npm for the latest published version of this package (network). */
+export async function getLatestVersion() {
+  try {
+    const res = await execa('npm', ['view', NPM_NAME, 'version'], { reject: false });
+    const v = (res.stdout || '').trim();
+    return /^\d+\.\d+\.\d+/.test(v) ? v : null;
+  } catch {
+    return null; // offline / npm missing — never crash the wizard on this
+  }
+}
+
+/** Compare the running local version to the latest published one. */
+export async function checkForUpdate() {
+  const latest = await getLatestVersion();
+  if (!latest) return { outdated: false, latest: null, current: pkg.version };
+  return { outdated: compareVersions(latest, pkg.version) > 0, latest, current: pkg.version };
+}
+
+/**
+ * Offer to self-update via `npm install -g`. Returns true when updated.
+ * Interactive; nothing happens when not on a TTY.
+ */
+export async function promptSelfUpdate() {
+  const { outdated, latest, current } = await checkForUpdate();
+  if (!outdated || !latest) return false;
+
+  const p = await import('@clack/prompts');
+  if (!process.stdin.isTTY) {
+    p.log.message(pc.dim(`Update available: v${latest} (you have v${current}). Run: npm install -g ${NPM_NAME}@latest`));
+    return false;
+  }
+  const want = await p.confirm({
+    message: `A new version (${pc.cyan('v' + latest)}) is available — you have ${pc.dim('v' + current)}. Update now?`,
+    initialValue: true,
+  });
+  if (p.isCancel(want) || !want) {
+    p.log.message(pc.dim(`Keeping v${current} — update later with: npm install -g ${NPM_NAME}@latest`));
+    return false;
+  }
+
+  // Release the terminal so npm's progress & any prompts are visible/interruptible.
+  console.log();
+  const res = await execa('npm', ['install', '-g', `${NPM_NAME}@latest`], { stdio: 'inherit', reject: false });
+  if (res.exitCode !== 0) {
+    p.log.warn('Update failed. You can retry with: npm install -g ' + NPM_NAME + '@latest');
+    return false;
+  }
+  p.log.success(`Updated to v${latest}. ` + 'Run `parrot-blackbox` again to use the new version.');
+  return true;
+}
+
+/**
+ * `update` command — always check npm and report, prompt to install when
+ * outdated (or when `force` is set even if already current).
+ */
+export async function runSelfUpdate({ force = false } = {}) {
+  const p = await import('@clack/prompts');
+  const { latest, current } = await checkForUpdate();
+  if (!latest) {
+    p.log.warn(`Could not reach the npm registry — you are on v${current}. Try: npm install -g ${NPM_NAME}@latest`);
+    return false;
+  }
+  const outdated = compareVersions(latest, current) > 0;
+  if (!outdated && !force) p.log.success(`You are on the latest version (v${current}).`);
+  if (!outdated && !force) return false;
+  if (outdated) p.log.info(`${pc.cyan('v' + latest)} available — you have ${pc.dim('v' + current)}.`);
+  if (!process.stdin.isTTY) {
+    p.log.message(outdated
+      ? pc.dim(`Update to v${latest} with: npm install -g ${NPM_NAME}@latest`)
+      : pc.dim(`You are on v${current}. Run: npm install -g ${NPM_NAME}@latest --force to reinstall`));
+    return false;
+  }
+  const want = await p.confirm({ message: `Update parrot-blackbox to v${latest} now?`, initialValue: true });
+  if (p.isCancel(want) || !want) { p.log.message(pc.dim('Update skipped.')); return false; }
+  console.log();
+  const res = await execa('npm', ['install', '-g', `${NPM_NAME}@latest`], { stdio: 'inherit', reject: false });
+  if (res.exitCode !== 0) {
+    p.log.warn('Update failed. You can retry with: npm install -g ' + NPM_NAME + '@latest');
+    return false;
+  }
+  p.log.success(`Updated to v${latest}. Restart parrot-blackbox to use the new version.`);
+  return true;
+}
+
+/** Fully remove the npm package (used by uninstall). */
+export async function selfUninstall() {
+  const p = await import('@clack/prompts');
+  console.log();
+  const res = await execa('npm', ['uninstall', '-g', NPM_NAME], { stdio: 'inherit', reject: false });
+  if (res.exitCode === 0) {
+    p.log.success(`${NPM_NAME} removed. The parrot-blackbox command is no longer available.`);
+    return true;
+  }
+  p.log.warn(`Could not uninstall ${NPM_NAME} automatically. Run: npm uninstall -g ${NPM_NAME}`);
+  return false;
+}