parrot-blackbox 1.0.0

package/src/cli.js

@@ -0,0 +1,426 @@
+import { defineCommand, runMain } from 'citty';
+import pc from 'picocolors';
+import * as p from '@clack/prompts';
+import { createRequire } from 'node:module';
+import { runSetup } from './commands/setup.js';
+import { runDoctor, runStatus, runUninstallWizard } from './commands/manage.js';
+import { installService, removeService } from './commands/service.js';
+import { runDueJobs } from './daemon/scheduler.js';
+import { startDaemon, stopDaemon, daemonRunning } from './daemon/daemon.js';
+import { runSnapshotNow, listLocalSnapshots, pruneSnapshots } from './backup/snapshot.js';
+import { restoreSnapshot, restoreFiles } from './backup/restore.js';
+import { listAccounts, addAccount, removeAccount, refreshAccounts, poolSummary } from './storage/accounts.js';
+import { listArtifacts } from './storage/archive.js';
+import { loadConfig, loadState, saveConfig } from './core/store.js';
+import { configFile, stateDir } from './core/paths.js';
+import { bytesHuman } from './util/misc.js';
+import { isOnline } from './util/network.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+/** Terminal safety net (same as gitswitch/theamify/warp-wizard). */
+function terminateAndRestore(code) {
+  try {
+    if (process.stdout.isTTY) process.stdout.write('\x1b[?25h\n\r');
+  } catch { /* best effort */ }
+  process.exit(code);
+}
+if (process.platform !== 'win32') process.on('SIGTSTP', () => terminateAndRestore(130));
+process.on('SIGINT', () => terminateAndRestore(130));
+process.on('SIGTERM', () => terminateAndRestore(143));
+
+function printUsage() {
+  console.log(`
+${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 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]')}
+  parrot-blackbox snapshot list       List local & cloud snapshots
+  parrot-blackbox snapshot prune      Delete snapshots beyond the keep limit  ${pc.dim('[sudo]')}
+  parrot-blackbox list [files]        List cloud file backups
+  parrot-blackbox restore             Restore a snapshot or file backup       ${pc.dim('[sudo]')}
+  parrot-blackbox account add         Add a MEGA / Google Drive account
+  parrot-blackbox account list        Show the storage pool & usage
+  parrot-blackbox account remove <id> Remove an account from the pool
+  parrot-blackbox account quota <id> <GiB>  Override an account 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 data kept)
+  parrot-blackbox version | help
+`);
+}
+
+async function invokeRun(privileged) {
+  const res = await runDueJobs({ privileged });
+  const report = res.report || [];
+  if (report.length === 0) {
+    console.log(pc.dim('Nothing due right now — the default schedule is the weekly snapshot (Saturday 22:00).'));
+    return 0;
+  }
+  for (const r of report) {
+    if (r.ok) {
+      if (r.deferred) {
+        console.log(`${pc.yellow('⏸')} ${r.type} ${r.due} deferred (sudo needed) — will retry automatically when the sudo timestamp is re-armed.`);
+        continue;
+      }
+      const extra = r.pruned?.length ? ` (pruned ${r.pruned.join(', ')})` : '';
+      const sizeLabel = r.size ? ` (${bytesHuman(r.size)})` : '';
+      console.log(`${pc.green('✔')} ${r.type} ${r.due} ${r.snapshot ? `snapshot=${r.snapshot}` : 'stored'}${sizeLabel}${extra}`);
+    } else {
+      console.log(`${pc.red('✖')} ${r.type} ${r.due} failed: ${r.error}`);
+    }
+  }
+  if (res.deferred) console.log(pc.yellow('Deferred (offline or sudo needed) — will catch up automatically when possible.'));
+  return report.some((r) => !r.ok) ? 1 : 0;
+}
+
+async function snapshotList() {
+  const cfg = loadConfig();
+  const accs = listAccounts();
+  console.log(`${pc.bold('\nLocal snapshots (Timeshift):')}`);
+  try {
+    const local = await listLocalSnapshots({ privileged: 'noninteractive' });
+    if (local.length === 0) console.log(`  ${pc.dim('none')}`);
+    for (const s of local) console.log(`  - ${pc.cyan(s.name)}  ${pc.dim(s.tags)}`);
+  } catch (e) {
+    console.log(`  ${pc.yellow(e.message)}`);
+  }
+  if (accs.length) {
+    const cloud = await listArtifacts('snapshots', accs, cfg.storage.remoteRoot);
+    console.log(`\nCloud snapshots:`);
+    if (cloud.length === 0) console.log(`  ${pc.dim('none')}`);
+    for (const c of cloud) {
+      console.log(`  - ${pc.cyan(c.id)}  ${bytesHuman(c.totalSize)}  ${pc.dim(c.account)}`);
+    }
+  } else {
+    console.log(`\n${pc.yellow('No accounts configured — run `parrot-blackbox account add` or setup.')}`);
+  }
+  console.log();
+}
+
+async function listFiles() {
+  const cfg = loadConfig();
+  const accs = listAccounts();
+  if (!accs.length) {
+    console.log(pc.yellow('No accounts configured yet.'));
+    return;
+  }
+  const artifacts = await listArtifacts('files', accs, cfg.storage.remoteRoot);
+  console.log(`\n${pc.bold('Cloud file backups:')}`);
+  if (artifacts.length === 0) console.log(`  ${pc.dim('none yet — run `parrot-blackbox force`')}`);
+  for (const a of artifacts) {
+    console.log(`  - ${pc.cyan(a.id)}  ${bytesHuman(a.totalSize)}  ${pc.dim(a.account)}`);
+  }
+  console.log();
+}
+
+async function accountAddFlow(args) {
+  const provider = args[0] || (await p.select({
+    message: 'Provider?',
+    options: [
+      { value: 'mega', label: 'MEGA' },
+      { value: 'gdrive', label: 'Google Drive' },
+    ],
+  }));
+  if (p.isCancel(provider)) return;
+  const remote = args[1] || (await p.text({ message: 'rclone remote name (create it first with `rclone config`):' }));
+  if (!remote) return;
+  const res = await addAccount({ provider, remote });
+  if (res.ok) console.log(pc.green(`✔ Added ${res.account.label} (${res.account.provider}).`));
+  else p.log.warn(res.error);
+}
+async function restoreFlow(rest) {
+  const cfg = loadConfig();
+  const accs = listAccounts();
+  if (accs.length === 0) {
+    p.log.warn('No accounts configured — cannot reach the cloud backups. Run `parrot-blackbox account add` first.');
+    return;
+  }
+  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' },
+    ],
+  }));
+  if (p.isCancel(kind)) return;
+
+  if (kind === 'files') {
+    const artifacts = await listArtifacts('files', accs, cfg.storage.remoteRoot);
+    if (artifacts.length === 0) { p.log.warn('No file backups found.'); return; }
+    const id = rest[1] || (await p.select({
+      message: 'Pick a backup generation:',
+      options: artifacts.map((a) => ({ value: a.id, label: `${a.id}  (${bytesHuman(a.totalSize)})` })),
+    }));
+    if (p.isCancel(id)) return;
+    const toDir = rest[2] || (await p.text({
+      message: 'Restore to which directory?',
+      initialValue: `./restored-${id}`,
+    }));
+    const s = p.spinner();
+    s.start('Restoring…');
+    try {
+      const res = await restoreFiles({ id, toDir, accounts: accs, cfg });
+      s.stop(`✔ Restored ${res.files} file(s), ${bytesHuman(res.bytes)} into ${toDir}`);
+    } catch (e) {
+      s.stop('✖ Restore failed.');
+      p.log.warn(e.message);
+    }
+    return;
+  }
+
+  // System snapshot restore — Level 5.
+  if (!rest[1]) {
+    // Interactive picker requires a terminal.
+    const cloud0 = await listArtifacts('snapshots', accs, cfg.storage.remoteRoot);
+    if (cloud0.length === 0) { p.log.warn('No cloud snapshots found.'); return; }
+    const pick = await p.select({
+      message: 'Pick a snapshot to restore:',
+      options: cloud0.map((c) => ({ value: c.id, label: `${c.id}  (${bytesHuman(c.totalSize)})` })),
+    });
+    if (p.isCancel(pick)) return;
+    rest[1] = pick;
+  }
+  const id = rest[1];
+  if (!rest.includes('--yes') && !process.stdin.isTTY) {
+    console.log(pc.yellow('Restore aborted — snapshot restore overwrites the whole system. Pass --yes to confirm in non-interactive mode.'));
+    return;
+  }
+  const confirm = rest.includes('--yes') || (await p.confirm({
+    message: pc.red(`This OVERWRITES the entire running system with snapshot ${id}. Continue?`),
+    initialValue: false,
+  }));
+  if (p.isCancel(confirm)) { p.cancel('Aborted.'); return; }
+  if (!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);
+  }
+}
+
+async function accountCommands(rest) {
+  const [sub, ...args] = rest;
+  switch (sub) {
+    case 'list':
+    case 'ls': {
+      const cfg = loadConfig();
+      const accs = listAccounts();
+      if (!accs.length) { console.log(pc.yellow('No accounts yet.')); return; }
+      const pool = poolSummary(await refreshAccounts(cfg));
+      console.log(`\n${pc.bold('Storage pool:')} ${pool.text}\n`);
+      for (const a of await refreshAccounts(cfg)) {
+        console.log(`  - ${pc.bold(a.label)}  ${a.provider}  remote=${a.remote}  ${bytesHuman(a.free)} free / ${bytesHuman(a.total)}`);
+      }
+      console.log();
+      return;
+    }
+    case 'add':
+      await accountAddFlow(args);
+      return;
+    case 'remove':
+    case 'rm': {
+      if (!args[0]) { console.log(pc.yellow('Usage: parrot-blackbox account remove <id-or-remote>')); return; }
+      console.log(removeAccount(args[0]) ? pc.green(`✔ Removed account ${args[0]}.`) : pc.yellow(`No account matched ${args[0]}.`));
+      return;
+    }
+    case 'quota': {
+      const [id, giB] = args;
+      if (!id || !giB) { console.log(pc.yellow('Usage: parrot-blackbox account quota <id-or-remote> <GiB>')); return; }
+      const cfg = loadConfig();
+      const acc = (cfg.storage.accounts || []).find((a) => a.id === id || a.remote === id);
+      if (!acc) { console.log(pc.yellow(`No account matched ${id}.`)); return; }
+      acc.quotaGiB = Number(giB);
+      writeConfigQuiet(cfg);
+      console.log(pc.green(`✔ ${acc.label} quota set to ${giB} GiB.`));
+      return;
+    }
+    default:
+      console.log(pc.yellow('account subcommands: add | list | remove <id> | quota <id> <GiB>'));
+  }
+}
+
+function writeConfigQuiet(cfg) {
+  saveConfig(cfg);
+}
+
+const main = defineCommand({
+  meta: {
+    name: 'parrot-blackbox',
+    version: pkg.version,
+    description: 'crash-proof multi-cloud backup & recovery automation for Parrot OS',
+  },
+  async run({ args }) {
+    const [cmd, ...rest] = args._;
+
+    if (process.platform !== 'linux') {
+      console.error(pc.red('parrot-blackbox is Linux-only: it orchestrates Timeshift snapshots, which only exist on Linux.'));
+      process.exitCode = 1;
+      return;
+    }
+    if (args.V) {
+      console.log(`parrot-blackbox v${pkg.version}`);
+      return;
+    }
+
+    if (!cmd) return runSetup();
+
+    switch (cmd) {
+      case 'setup':
+      case 'wizard':
+      case 'install':
+        return runSetup();
+
+      case 'run':
+        process.exitCode = await invokeRun('noninteractive');
+        return;
+
+      case 'force':
+      case 'backup': {
+        // Runs every ENABLED job right now (default = the weekly snapshot).
+        const res = await runDueJobs({ force: true, privileged: 'interactive' });
+        const report = res.report || [];
+        if (report.length === 0) console.log(pc.dim('No enabled backup jobs — run `parrot-blackbox` to set up the schedule.'));
+        for (const r of report) {
+          if (r.ok) {
+            const sizeLabel = r.size ? ` (${bytesHuman(r.size)})` : '';
+            const label = r.snapshot ? `Snapshot ${r.snapshot}` : `File backup ${r.due}`;
+            console.log(`${pc.green('✔')} ${label} created & uploaded${sizeLabel}.`);
+          } else if (r.deferred) {
+            console.log(`${pc.yellow('⏸')} Snapshot deferred (sudo needed) — run \`parrot-blackbox snapshot now\` once to authenticate.`);
+          } else {
+            console.log(`${pc.red('✖')} Backup failed: ${r.error}`);
+            process.exitCode = 1;
+          }
+        }
+        return;
+      }
+
+      case 'snapshot': {
+        const [sub, ...args] = rest;
+        if (sub === 'now' || sub === 'create' || sub === 'force') {
+          try {
+            const r = await runSnapshotNow();
+            console.log(`${pc.green('✔')} Snapshot ${r.snapshot} created & uploaded (${bytesHuman(r.manifest.totalSize)}).`);
+            if (r.pruned?.length) console.log(pc.dim(`Pruned: ${r.pruned.join(', ')}`));
+          } catch (e) {
+            console.error(pc.red(`✖ ${e.message}`));
+            process.exitCode = 1;
+          }
+          return;
+        }
+        if (sub === 'list' || sub === 'ls') return snapshotList();
+        if (sub === 'prune') {
+          const cfg = loadConfig();
+          try {
+            const pruned = await pruneSnapshots(cfg, loadState(), listAccounts(), { privileged: 'interactive' });
+            if (pruned.length) console.log(pc.green(`✔ Pruned: ${pruned.join(', ')} (local + cloud).`));
+            else console.log(pc.dim('Nothing to prune.'));
+          } catch (e) {
+            console.error(pc.red(`✖ ${e.message}`));
+            process.exitCode = 1;
+          }
+          return;
+        }
+        console.log(pc.yellow('snapshot subcommands: now | list | prune'));
+        return;
+      }
+
+      case 'list':
+      case 'ls':
+      case 'files':
+        return listFiles();
+
+      case 'restore':
+      case 'recover':
+        return restoreFlow(rest);
+
+      case 'account':
+      case 'accounts':
+        return accountCommands(rest);
+
+      case 'daemon': {
+        const [sub] = rest;
+        if (sub === 'start') {
+          const res = await startDaemon();
+          console.log(res.started ? pc.green(`✔ Daemon started (pid ${res.pid}).`) : pc.yellow(`Daemon ${res.reason || 'already running'}.`));
+          return;
+        }
+        if (sub === 'stop') {
+          const res = await stopDaemon();
+          console.log(res.stopped ? pc.green(`✔ Daemon stopped.`) : pc.yellow(`Daemon ${res.reason || 'not running'}.`));
+          return;
+        }
+        if (sub === 'status') {
+          console.log(`Daemon: ${daemonRunning() ? pc.green('running') : pc.yellow('not running')}`);
+          return;
+        }
+        if (sub === 'foreground') {
+          const { daemonForeground } = await import('./daemon/daemon.js');
+          await daemonForeground();
+          return;
+        }
+        console.log(pc.yellow('daemon subcommands: start | stop | status | foreground'));
+        return;
+      }
+
+      case 'schedule': {
+        const [sub] = rest;
+        if (sub === 'install' || sub === 'on') {
+          const backend = await installService();
+          console.log(pc.green(`✔ Always-on schedule installed (${backend}).`));
+          return;
+        }
+        if (sub === 'remove' || sub === 'off') {
+          await removeService();
+          console.log(pc.green('✔ Schedule removed.'));
+          return;
+        }
+        console.log(pc.yellow('schedule subcommands: install | remove'));
+        return;
+      }
+
+      case 'doctor':
+        return runDoctor().then(() => undefined);
+
+      case 'status':
+        return runStatus();
+
+      case 'uninstall':
+        return runUninstallWizard();
+
+      case 'config':
+        console.log(`config: ${configFile()}`);
+        console.log(`state : ${stateDir()}`);
+        return;
+
+      case 'version':
+      case '-v':
+      case '-V':
+      case '--version':
+        console.log(`parrot-blackbox v${pkg.version}`);
+        return;
+
+      case 'help':
+      case '-h':
+      case '--help':
+      default:
+        if (['help', '-h', '--help'].includes(cmd)) { printUsage(); return; }
+        console.error(pc.red(`Unknown command: ${cmd}`));
+        printUsage();
+        process.exitCode = 1;
+    }
+  },
+});
+
+runMain(main);

package/src/commands/manage.js

@@ -0,0 +1,128 @@
+/**
+ * Diagnostics & lifecycle: `doctor`, `status`, `uninstall`.
+ */
+
+import fs from 'node:fs';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { execa } from 'execa';
+import { loadConfig, loadState, journal, hasCommandSync, lastJournal } from '../core/store.js';
+import { configFile, stateDir } from '../core/paths.js';
+import { bytesHuman } from '../util/misc.js';
+import { listAccounts, refreshAccounts, poolSummary } from '../storage/accounts.js';
+import { listArtifacts } from '../storage/archive.js';
+import { rcloneVersion } from '../storage/rclone.js';
+import { listLocalSnapshots, timeshiftAvailable } from '../backup/snapshot.js';
+import { daemonRunning } from '../daemon/daemon.js';
+import { serviceBackend } from './service.js';
+import { isOnline } from '../util/network.js';
+
+export async function runDoctor() {
+  const cfg = loadConfig();
+  const state = loadState();
+
+  p.intro(pc.bold('🩺 parrot-blackbox doctor'));
+  console.log(`\n  Tooling:`);
+  const tools = [
+    ['node', () => process.version],
+    ['rclone', rcloneVersion],
+    ['timeshift', () => (timeshiftAvailable() ? 'present' : 'MISSING')],
+    ['git', () => (hasCommandSync('git') ? 'present' : 'MISSING')],
+    ['systemd', () => (serviceBackend() === 'systemd' ? 'available' : serviceBackend())],
+  ];
+  for (const [name, fn] of tools) {
+    let v;
+    try { v = await fn(); } catch { v = 'error'; }
+    console.log(`    - ${pc.cyan(name.padEnd(10))} ${v}`);
+  }
+
+  console.log(`\n  Network : ${(await isOnline()) ? pc.green('online') : pc.yellow('offline')}`);
+  console.log(`  Daemon  : ${daemonRunning() ? pc.green('running') : pc.yellow('stopped')}`);
+  console.log(`  Config  : ${configFile()}`);
+  console.log(`  State   : ${stateDir()}`);
+
+  console.log(`\n  Storage accounts:`);
+  const accs = listAccounts();
+  if (accs.length === 0) {
+    console.log(`    ${pc.yellow('none — run `parrot-blackbox setup`')}`);
+  } else {
+    const refreshed = await refreshAccounts(cfg);
+    for (const a of refreshed) {
+      console.log(`    - ${pc.bold(a.label)} (${a.provider}, ${a.remote})  ${bytesHuman(a.free)} free / ${bytesHuman(a.total)}`);
+    }
+    console.log(`    ${pc.dim(poolSummary(refreshed).text)}`);
+  }
+
+  console.log(`\n  Recent journal:`);
+  for (const line of lastJournal(8)) console.log(`    ${pc.dim(line)}`);
+
+  console.log(`\n  Schedule state:`);
+  for (const type of ['files', 'snapshots']) {
+    const j = state.jobs[type];
+    const icfg = cfg.jobs[type];
+    console.log(
+      `    - ${pc.bold(type)}  ${icfg?.schedule?.kind} ${icfg?.enabled ? '' : pc.yellow('(disabled)')}` +
+        `  last=${j.lastCompletedDue || '—'}  pending=${(j.pending || []).join(',') || '—'}  status=${j.lastStatus || '—'}`,
+    );
+  }
+}
+
+export async function runStatus() {
+  const cfg = loadConfig();
+  const state = loadState();
+  const accs = listAccounts();
+
+  console.log(pc.bold(`\n🧠 parrot-blackbox status\n`));
+  if (accs.length) {
+    const pool = poolSummary(await refreshAccounts(cfg));
+    console.log(`  Pool      : ${pool.text}`);
+  } else {
+    console.log(`  Pool      : ${pc.yellow('no accounts — run `parrot-blackbox setup`')}`);
+  }
+  console.log(`  Network   : ${(await isOnline()) ? pc.green('online') : pc.yellow('offline — backups will defer & catch up later')}`);
+  console.log(`  Daemon    : ${daemonRunning() ? pc.green('running') : pc.yellow('stopped')}`);
+
+  for (const type of ['files', 'snapshots']) {
+    const j = state.jobs[type] || {};
+    const icfg = cfg.jobs[type] || {};
+    console.log(`\n  ${pc.bold(type)} (${icfg.schedule?.kind ?? '?'}, keep ${icfg.keep})`);
+    console.log(`    Last done : ${j.lastCompletedDue || pc.dim('never')}`);
+    console.log(`    Pending   : ${(j.pending || []).join(', ') || pc.dim('none')}`);
+    if (j.lastError) console.log(`    Last error: ${pc.red(j.lastError.slice(0, 160))}`);
+  }
+
+  const clouds = await listArtifacts('snapshots', accs, cfg.storage.remoteRoot).catch(() => []);
+  if (clouds.length) {
+    console.log(`\n  Cloud snapshots: ${clouds.map((c) => `${c.id} (${bytesHuman(c.totalSize)})`).join(', ')}`);
+  }
+  console.log();
+}
+
+export async function runUninstallWizard() {
+  p.intro(pc.bgRed(pc.black(' parrot-blackbox uninstaller ')));
+
+  const confirm = await p.confirm({
+    message:
+      'Uninstall parrot-blackbox completely? This stops the daemon, removes the systemd/cron schedule, deletes the local config & journal (~/.config/parrot-blackbox, ~/.local/state/parrot-blackbox) and the npm package. CLOUD BACKUPS ARE NOT DELETED.',
+    initialValue: false,
+  });
+  if (p.isCancel(confirm)) { p.cancel('Aborted.'); process.exit(0); }
+  if (!confirm) { p.outro('Nothing was removed.'); return; }
+
+  // Stop daemon & remove service
+  try { await execa('bash', ['-c', `"${process.execPath}" "${process.argv[1]}" daemon stop`], { reject: false }); } catch { /* best effort */ }
+  try { await execa('bash', ['-c', `"${process.execPath}" "${process.argv[1]}" schedule remove`], { reject: false }); } catch { /* best effort */ }
+
+  const removed = [];
+  for (const dir of [configFile(), stateDir()]) {
+    if (fs.existsSync(dir)) {
+      if (fs.statSync(dir).isDirectory() && dir.includes('parrot-blackbox')) fs.rmSync(dir, { recursive: true, force: true });
+      else fs.rmSync(dir, { force: true });
+      removed.push(dir);
+    }
+  }
+  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.'));
+}

package/src/commands/service.js

@@ -0,0 +1,122 @@
+/**
+ * Always-on integration. Preferred: a systemd USER unit that keeps the daemon
+ * running (Restart=always, starts on login). Fallback for systems without
+ * systemd: a cron line that runs `parrot-blackbox run` every 15 minutes (the
+ * run itself defers when offline and catches up later, so it never hangs).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execa } from 'execa';
+import { serviceFile, daemonLogFile } from '../core/paths.js';
+import { loadConfig, journal, hasCommandSync } from '../core/store.js';
+
+function findCliBin() {
+  // npm-installed global binary (preferred) or our own bin entry.
+  const candidates = [
+    process.env.PBB_BIN,
+    path.join(path.dirname(process.argv[1] || ''), 'parrot-blackbox.js'),
+  ];
+  return candidates.find((c) => c && fs.existsSync(c)) || 'parrot-blackbox';
+}
+
+export function serviceBackend() {
+  if (process.env.PBB_SERVICE_BACKEND) return process.env.PBB_SERVICE_BACKEND;
+  if (hasCommandSync('systemctl')) return 'systemd';
+  if (hasCommandSync('crontab')) return 'cron';
+  return 'none';
+}
+
+/** Install the systemd user unit (or cron fallback). Returns detected backend. */
+export async function installService() {
+  const backend = serviceBackend();
+  if (backend === 'systemd') {
+    const bin = findCliBin();
+    const unit = [
+      '[Unit]',
+      'Description=parrot-blackbox — crash-proof backup daemon',
+      'After=network-online.target',
+      'Wants=network-online.target',
+      '',
+      '[Service]',
+      'Type=simple',
+      `ExecStart=${process.execPath} ${bin} daemon foreground`,
+      'Restart=always',
+      'RestartSec=60',
+      `StandardOutput=append:${daemonLogFile()}`,
+      `StandardError=append:${daemonLogFile()}`,
+      '',
+      '[Install]',
+      'WantedBy=default.target',
+      '',
+    ].join('\n');
+    fs.mkdirSync(path.dirname(serviceFile()), { recursive: true });
+    fs.writeFileSync(serviceFile(), unit);
+    journal('service', `systemd unit written: ${serviceFile()}`);
+    for (const cmd of [
+      ['systemctl', '--user', 'daemon-reload'],
+      ['systemctl', '--user', 'enable', '--now', 'parrot-blackbox.service'],
+    ]) {
+      const res = await execa(cmd[0], cmd.slice(1), { reject: false });
+      if (res.exitCode !== 0) {
+        journal('service', `systemctl ${cmd.slice(2).join(' ')} failed: ${res.stderr?.trim()}`, 'warn');
+      }
+    }
+    return 'systemd';
+  }
+  if (backend === 'cron') {
+    await installCron();
+    return 'cron';
+  }
+  return 'none';
+}
+
+function cronLinesFor() {
+  const bin = findCliBin();
+  const marker = '# parrot-blackbox automatic backup schedule';
+  const line = `*/15 * * * * "${process.execPath}" ${bin} run >> ${daemonLogFile()} 2>&1`;
+  return { marker, line };
+}
+
+async function installCron() {
+  const { marker, line } = cronLinesFor();
+  const existing = await execa('crontab', ['-l'], { reject: false });
+  const body = existing.exitCode === 0 ? existing.stdout : '';
+  const lines = body.split('\n').filter((l) => !l.includes(marker));
+  lines.push(marker);
+  lines.push(line);
+  lines.push('');
+  const write = await execa('crontab', ['-'], { reject: false, input: lines.join('\n') });
+  journal('service', write.exitCode === 0 ? 'cron line installed' : `crontab failed: ${write.stderr?.trim()}`, write.exitCode === 0 ? 'info' : 'warn');
+}
+
+async function removeCron() {
+  const { marker } = cronLinesFor();
+  const existing = await execa('crontab', ['-l'], { reject: false });
+  if (existing.exitCode !== 0) return;
+  const lines = existing.stdout.split('\n').filter((l) => !l.includes(marker));
+  await execa('crontab', ['-'], { reject: false, input: lines.join('\n') + '\n' });
+  journal('service', 'cron line removed');
+}
+
+export async function removeService() {
+  const backend = serviceBackend();
+  if (backend === 'systemd') {
+    for (const cmd of [
+      ['systemctl', '--user', 'stop', 'parrot-blackbox.service'],
+      ['systemctl', '--user', 'disable', 'parrot-blackbox.service'],
+    ]) {
+      const res = await execa(cmd[0], cmd.slice(1), { reject: false });
+      if (res.exitCode !== 0) journal('service', `${cmd.join(' ')} failed`, 'warn');
+    }
+    try {
+      fs.rmSync(serviceFile(), { force: true });
+    } catch { /* best effort */ }
+    return 'systemd';
+  }
+  if (backend === 'cron') {
+    await removeCron();
+    return 'cron';
+  }
+  return 'none';
+}