@celilo/cli 0.3.26 → 0.3.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/cli/commands/storage-add-local.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Tests for `storage add local`'s pre-save write probe.
+ *
+ * Background: an operator on celilo-mgmt typed `/var/backups/celilo`
+ * for the path. The CLI accepted it, saved a storage row, then the
+ * heavyweight verify step failed with EACCES — leaving an unverified
+ * row that confused subsequent `system update` runs. The probe
+ * catches unwriteable paths before any persistent state is created.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { probePathWriteable } from './storage-add-local';
+
+describe('probePathWriteable', () => {
+  let tempRoot: string;
+
+  beforeEach(() => {
+    tempRoot = mkdtempSync(join(tmpdir(), 'celilo-probe-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempRoot, { recursive: true, force: true });
+  });
+
+  test('returns null for a writeable existing directory', () => {
+    expect(probePathWriteable(tempRoot)).toBeNull();
+  });
+
+  test("creates parent dirs that don't exist yet (mkdir -p semantics)", () => {
+    // The probe's mkdirSync uses `recursive: true`, so a path several
+    // levels below the temp root works on the first try. This is the
+    // common case for the user's typed path under their data dir.
+    const deep = join(tempRoot, 'a', 'b', 'c', 'backups');
+    expect(probePathWriteable(deep)).toBeNull();
+  });
+
+  test('returns an error message for a path under a read-only ancestor', () => {
+    const readOnly = join(tempRoot, 'readonly');
+    mkdirSync(readOnly);
+    // 0o500 = read+execute for owner, no write. mkdirSync into it
+    // should EACCES.
+    require('node:fs').chmodSync(readOnly, 0o500);
+    try {
+      const target = join(readOnly, 'celilo-backups');
+      const err = probePathWriteable(target);
+      expect(err).not.toBeNull();
+      expect(err).toContain('EACCES');
+    } finally {
+      // Restore permissions so afterEach can clean up.
+      require('node:fs').chmodSync(readOnly, 0o700);
+    }
+  });
+
+  test('cleans up the probe directory on success (no leftover state)', () => {
+    const dir = join(tempRoot, 'check');
+    expect(probePathWriteable(dir)).toBeNull();
+    // The probe creates `<dir>/.celilo-write-probe` then removes it.
+    // The directory itself stays (mkdir -p), but the probe sentinel
+    // doesn't.
+    const { existsSync } = require('node:fs');
+    expect(existsSync(join(dir, '.celilo-write-probe'))).toBe(false);
+  });
+});

package/src/cli/commands/storage-add-local.ts

@@ -3,8 +3,10 @@
  * Configure a local filesystem backup storage destination
  */
 
+import { mkdirSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
+import { getDataDir } from '../../config/paths';
 import {
   addBackupStorage,
   setDefaultBackupStorage,
@@ -14,6 +16,27 @@ import { celiloIntro, celiloOutro, promptConfirm, promptText } from '../prompts'
 import type { CommandResult } from '../types';
 import { validateRequired } from '../validators';
 
+/**
+ * Best-effort write probe. Attempts to mkdir -p a `.celilo-write-probe`
+ * subdir, then deletes it. Returns null on success, or a one-line
+ * error message on failure (suitable for surfacing to the operator).
+ *
+ * Exists so we can catch unwriteable paths AT INTERVIEW TIME instead
+ * of saving a storage row, failing the heavyweight verify step, and
+ * leaving a dangling unverified row that confuses subsequent
+ * `system update` runs (the regression that prompted this work).
+ */
+export function probePathWriteable(path: string): string | null {
+  const probe = join(path, '.celilo-write-probe');
+  try {
+    mkdirSync(probe, { recursive: true });
+    rmSync(probe, { recursive: true, force: true });
+    return null;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
 /**
  * Expand leading tilde to the user's home directory.
  * Node.js fs functions don't expand ~ like the shell does.
@@ -45,15 +68,55 @@ export async function handleStorageAddLocal(
         validate: validateRequired('Storage name'),
       }));
 
-    const path =
-      flagPath ??
-      (await promptText({
-        message: 'Storage directory path:',
-        placeholder: 'e.g., /mnt/nas/backups or /var/backups/celilo',
-        validate: validateRequired('Storage path'),
-      }));
-
-    const resolvedPath = resolve(expandTilde(path));
+    // Default path lives under celilo's own data dir
+    // (~/.local/share/celilo/backups on Linux, ~/Library/Application
+    // Support/celilo/backups on macOS). The directory is owned by the
+    // running user, mkdir -p succeeds without sudo, and operators who
+    // want NAS / external paths can override at the prompt. This
+    // replaces the prior placeholder of "/var/backups/celilo" which
+    // looked authoritative but required root to write.
+    const defaultPath = join(getDataDir(), 'backups');
+
+    // Probe writability BEFORE saving the storage row. The previous
+    // flow (save → verify → fail with EACCES → leave dangling
+    // unverified row) was confusing and required the operator to know
+    // about `storage verify` to recover. Probing here means an
+    // unwriteable path never produces persistent state.
+    //
+    // Non-interactive (--name + --path): probe once, fail loud.
+    // Interactive: re-prompt until a writeable path is supplied.
+    let resolvedPath: string;
+    if (flagPath !== undefined) {
+      resolvedPath = resolve(expandTilde(flagPath));
+      const writeError = probePathWriteable(resolvedPath);
+      if (writeError !== null) {
+        return {
+          success: false,
+          error: `Path '${resolvedPath}' is not writeable: ${writeError}\n\nTry a path under your home directory (e.g. '${defaultPath}') or run with elevated permissions.`,
+        };
+      }
+    } else {
+      let candidate: string | undefined;
+      while (candidate === undefined) {
+        const typed = await promptText({
+          message: 'Storage directory path:',
+          defaultValue: defaultPath,
+          placeholder: defaultPath,
+          validate: validateRequired('Storage path'),
+        });
+        const resolved = resolve(expandTilde(typed));
+        const writeError = probePathWriteable(resolved);
+        if (writeError === null) {
+          candidate = resolved;
+          break;
+        }
+        console.log(
+          `\n✗ Path '${resolved}' is not writeable: ${writeError}\nTry a path under your home directory (default '${defaultPath}' works without sudo).\n`,
+        );
+        // Loop continues — re-prompt with the same default suggestion.
+      }
+      resolvedPath = candidate;
+    }
 
     const storage = await addBackupStorage({
       name,
@@ -67,6 +130,10 @@ export async function handleStorageAddLocal(
     const { result } = await verifyBackupStorage(storage.id);
 
     if (!result.success) {
+      // Should be unreachable in interactive mode (the pre-save probe
+      // covers the EACCES path); could still fire for less-common
+      // verify failures (full disk, etc.). Keep the dangling-row
+      // recovery hint as a safety net.
       console.log(`\n✗ Verification failed: ${result.message}`);
       celiloOutro(
         `Storage '${storage.storageId}' added but not verified.\n\nFix the path and re-verify: celilo storage verify ${storage.storageId}`,

package/src/cli/commands/system-update.test.ts

@@ -0,0 +1,188 @@
+/**
+ * Tests for the `system update` storage pre-flight.
+ *
+ * Background: an operator on celilo-mgmt hit a confusing chain when
+ * they ran `celilo storage add local /var/backups/celilo` (a system
+ * path that needs root). The verify step failed with EACCES, leaving
+ * an unverified storage row on disk. The next `celilo system update`
+ * said "No default backup storage configured" — technically true
+ * (unverified storage never auto-defaults), but misleading: there
+ * IS a storage, it just needs fixing. The pre-flight now distinguishes
+ * the cases and points at the right next command for each.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { ModuleSnapshot } from '../../services/update/orchestrator';
+import {
+  type BackupStorageLike,
+  checkBackupStoragePreflight,
+  shouldTakeBackup,
+} from './system-update';
+
+const verified = (id: string): BackupStorageLike => ({ storageId: id, verified: true });
+const unverified = (id: string): BackupStorageLike => ({ storageId: id, verified: false });
+
+describe('checkBackupStoragePreflight', () => {
+  test('verified default → ok', () => {
+    const result = checkBackupStoragePreflight({
+      defaultStorage: verified('home-backups'),
+      allStorages: [verified('home-backups')],
+    });
+    expect(result.kind).toBe('ok');
+  });
+
+  test('default exists but unverified → suggests `storage verify`', () => {
+    const result = checkBackupStoragePreflight({
+      defaultStorage: unverified('home-backups'),
+      allStorages: [unverified('home-backups')],
+    });
+    if (result.kind !== 'error') throw new Error('expected error');
+    expect(result.message).toContain("Default backup storage 'home-backups' is not verified");
+    expect(result.message).toContain('celilo storage verify home-backups');
+  });
+
+  test('no storage at all → suggests `storage add local`', () => {
+    const result = checkBackupStoragePreflight({
+      defaultStorage: null,
+      allStorages: [],
+    });
+    if (result.kind !== 'error') throw new Error('expected error');
+    expect(result.message).toContain('No backup storage configured');
+    expect(result.message).toContain('celilo storage add local');
+    // Always offer the --no-backup escape so the operator knows the
+    // CLI self-update can still run on a system without storage.
+    expect(result.message).toContain('--no-backup');
+  });
+
+  // The exact case the operator hit on celilo-mgmt: ran storage add,
+  // path was unwriteable (/var/backups/celilo without sudo), verify
+  // failed, the unverified row stayed in the DB and isn't default.
+  test('only unverified storage → suggests `storage verify`, not `storage add`', () => {
+    const result = checkBackupStoragePreflight({
+      defaultStorage: null,
+      allStorages: [unverified('local-backups')],
+    });
+    if (result.kind !== 'error') throw new Error('expected error');
+    expect(result.message).toContain('none is verified yet');
+    expect(result.message).toContain('Storages: local-backups');
+    expect(result.message).toContain('celilo storage verify <storage-id>');
+    // Critically, this case does NOT direct the operator to run
+    // `storage add local` — they already did, the row exists.
+    expect(result.message).not.toContain('celilo storage add local');
+    // Surface the most common cause inline rather than burying it.
+    expect(result.message).toContain('elevated permissions');
+    expect(result.message).toContain('--no-backup');
+  });
+
+  test('multiple unverified storages → lists all storage IDs', () => {
+    const result = checkBackupStoragePreflight({
+      defaultStorage: null,
+      allStorages: [unverified('local-a'), unverified('local-b'), unverified('local-c')],
+    });
+    if (result.kind !== 'error') throw new Error('expected error');
+    expect(result.message).toContain('Storages: local-a, local-b, local-c');
+  });
+
+  test('verified storage exists but none is default → suggests `storage set-default`', () => {
+    const result = checkBackupStoragePreflight({
+      defaultStorage: null,
+      allStorages: [verified('home-backups'), unverified('s3-cold')],
+    });
+    if (result.kind !== 'error') throw new Error('expected error');
+    expect(result.message).toContain('verified but no default is set');
+    expect(result.message).toContain('Verified: home-backups');
+    // Doesn't mention the unverified one in the "Verified:" listing
+    // (that would mislead).
+    expect(result.message).not.toContain('Verified: home-backups, s3-cold');
+    expect(result.message).toContain('celilo storage set-default <storage-id>');
+  });
+
+  test('multiple verified, no default → lists all verified IDs', () => {
+    const result = checkBackupStoragePreflight({
+      defaultStorage: null,
+      allStorages: [verified('home-backups'), verified('s3-cold'), unverified('nas')],
+    });
+    if (result.kind !== 'error') throw new Error('expected error');
+    expect(result.message).toContain('Verified: home-backups, s3-cold');
+  });
+});
+
+const snap = (
+  id: string,
+  installedVersion: string,
+  latestVersion: string | null,
+): ModuleSnapshot => ({
+  id,
+  installedVersion,
+  latestVersion,
+  installedProvides: {},
+  pendingRequires: {},
+});
+
+const snapshotsOf = (...entries: ModuleSnapshot[]): Map<string, ModuleSnapshot> =>
+  new Map(entries.map((s) => [s.id, s]));
+
+describe('shouldTakeBackup', () => {
+  test('false when no module updates at all', () => {
+    expect(
+      shouldTakeBackup({
+        snapshots: snapshotsOf(snap('caddy', '2.0.0+5', '2.0.0+5')),
+        wasDeployed: new Set(['caddy']),
+      }),
+    ).toBe(false);
+  });
+
+  test('true when a deployed module has a registry-newer version', () => {
+    expect(
+      shouldTakeBackup({
+        snapshots: snapshotsOf(snap('caddy', '2.0.0+5', '2.0.0+6')),
+        wasDeployed: new Set(['caddy']),
+      }),
+    ).toBe(true);
+  });
+
+  // The exact case the operator hit on celilo-mgmt: namecheap was
+  // imported but never deployed; system update wanted to back up the
+  // celilo DB even though no live state would be touched.
+  test('false when only IMPORTED modules have updates (live state untouched)', () => {
+    expect(
+      shouldTakeBackup({
+        snapshots: snapshotsOf(snap('namecheap', '3.1.0+10', '3.1.1+4')),
+        wasDeployed: new Set(), // nothing deployed
+      }),
+    ).toBe(false);
+  });
+
+  test('true when any deployed module needs updating, regardless of imported ones', () => {
+    expect(
+      shouldTakeBackup({
+        snapshots: snapshotsOf(
+          snap('namecheap', '3.1.0+10', '3.1.1+4'), // imported, has update
+          snap('caddy', '2.0.0+5', '2.0.0+6'), // deployed, has update
+        ),
+        wasDeployed: new Set(['caddy']),
+      }),
+    ).toBe(true);
+  });
+
+  test('false when registry has no info (latestVersion null)', () => {
+    // Network failure — we don't know if updates exist. Default to
+    // "no backup needed" rather than blocking the run; the per-module
+    // upgrade step will report individual failures if any.
+    expect(
+      shouldTakeBackup({
+        snapshots: snapshotsOf(snap('caddy', '2.0.0+5', null)),
+        wasDeployed: new Set(['caddy']),
+      }),
+    ).toBe(false);
+  });
+
+  test('false on empty snapshots', () => {
+    expect(
+      shouldTakeBackup({
+        snapshots: new Map(),
+        wasDeployed: new Set(),
+      }),
+    ).toBe(false);
+  });
+});

package/src/cli/commands/system-update.ts

@@ -17,6 +17,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { eq } from 'drizzle-orm';
@@ -50,6 +51,126 @@ import { fetchAndUpgrade } from './module-upgrade';
  */
 const MANAGED_PACKAGES = ['@celilo/cli', '@celilo/event-bus', '@celilo/e2e'] as const;
 
+/**
+ * Result of inspecting backup-storage configuration before letting
+ * `runSystemUpdate` take a celilo-DB snapshot. Three failure shapes
+ * the operator might hit, each with a distinct friendly message:
+ *
+ *   1. No storage rows at all          → run `storage add local`
+ *   2. Storage rows exist, none verified → run `storage verify <id>`
+ *      (the case the operator hits when an unverified storage was
+ *      left behind by a failed verify)
+ *   3. Verified storage exists, none is default → run
+ *      `storage set-default <id>`
+ *   4. Default exists but isn't verified → run `storage verify <id>`
+ *
+ * Pure data in / data out so it's testable without setting up an
+ * audit, registry, or DB.
+ */
+export interface BackupStorageLike {
+  storageId: string;
+  verified: boolean;
+}
+
+export function checkBackupStoragePreflight(input: {
+  defaultStorage: BackupStorageLike | null;
+  allStorages: BackupStorageLike[];
+}): { kind: 'ok' } | { kind: 'error'; message: string } {
+  const { defaultStorage, allStorages } = input;
+
+  if (defaultStorage) {
+    if (defaultStorage.verified) return { kind: 'ok' };
+    return {
+      kind: 'error',
+      message: `Default backup storage '${defaultStorage.storageId}' is not verified.
+
+Run:  celilo storage verify ${defaultStorage.storageId}
+
+Then re-run system update.`,
+    };
+  }
+
+  if (allStorages.length === 0) {
+    return {
+      kind: 'error',
+      message: `No backup storage configured.
+
+celilo system update snapshots the celilo DB before applying module
+updates as a safety net. Configure backup storage first:
+
+  celilo storage add local
+
+Or skip the safety net entirely (the CLI self-update still runs):
+
+  celilo system update --no-backup`,
+    };
+  }
+
+  const verified = allStorages.filter((s) => s.verified);
+  if (verified.length === 0) {
+    const ids = allStorages.map((s) => s.storageId).join(', ');
+    return {
+      kind: 'error',
+      message: `Backup storage exists but none is verified yet.
+
+Storages: ${ids}
+
+Verify one before re-running system update:
+
+  celilo storage verify <storage-id>
+
+Common causes of failed verification:
+  - The path requires elevated permissions (try a path under your
+    home directory; the default '${join(homedir(), '.local/share/celilo/backups')}'
+    works without sudo).
+  - The disk is full or the mount point isn't writeable.
+
+Or skip the safety net entirely (the CLI self-update still runs):
+
+  celilo system update --no-backup`,
+    };
+  }
+
+  const ids = verified.map((s) => s.storageId).join(', ');
+  return {
+    kind: 'error',
+    message: `Backup storage is verified but no default is set.
+
+Verified: ${ids}
+
+Set a default before re-running system update:
+
+  celilo storage set-default <storage-id>
+
+Or skip the safety net entirely (the CLI self-update still runs):
+
+  celilo system update --no-backup`,
+  };
+}
+
+/**
+ * Should `system update` take a celilo-DB snapshot for this run?
+ * True iff at least one module that's currently DEPLOYED has a
+ * registry-newer version waiting. Pure data in / data out.
+ *
+ * Excludes IMPORTED-but-not-yet-deployed modules — refreshing their
+ * on-disk source has no impact on live state, so the safety net
+ * isn't needed (and an operator who hasn't configured storage yet
+ * shouldn't be blocked by a snapshot they don't need).
+ */
+export function shouldTakeBackup(input: {
+  snapshots: Map<string, ModuleSnapshot>;
+  wasDeployed: Set<string>;
+}): boolean {
+  for (const [id, s] of input.snapshots) {
+    if (!input.wasDeployed.has(id)) continue;
+    if (!s.latestVersion) continue;
+    if (s.latestVersion === s.installedVersion) continue;
+    return true;
+  }
+  return false;
+}
+
 function readInstalledCliVersion(): string {
   const here = dirname(fileURLToPath(import.meta.url));
   const candidates = [
@@ -489,45 +610,36 @@ export async function handleSystemUpdate(
   }
 
   // Decide whether the celilo-db snapshot is even needed for this run.
-  // If nothing's changing at the module level, there's nothing to roll
-  // back to — taking a snapshot would be pointless work, and on a fresh
-  // box (no storage configured yet) it would actively fail. Treat the
-  // "nothing-to-update" case as implicit --no-backup.
-  const hasModuleUpdates = [...snapshots.values()].some(
-    (s) => s.latestVersion && s.latestVersion !== s.installedVersion,
-  );
-  const effectiveNoBackup = noBackup || !hasModuleUpdates;
+  //
+  // The snapshot is a safety net — its purpose is to let `system update`
+  // roll back if a deploy / health step bricks a running module. So
+  // we ONLY need it when the run will actually upgrade-and-redeploy
+  // a currently-deployed module. Two cases that don't qualify:
+  //
+  //   1. Nothing has new code waiting at all (everyone's at latest).
+  //   2. The only modules with new code are IMPORTED-but-not-deployed.
+  //      Their upgrade is a pure source-files-on-disk refresh; no
+  //      live state to roll back, no risk to mitigate. Forcing a
+  //      backup here means an operator on a fresh celilo-mgmt with
+  //      nothing deployed yet has to configure backup storage just
+  //      to refresh the on-disk modules they imported — which is
+  //      exactly the friction that prompted this code path.
+  const effectiveNoBackup = noBackup || !shouldTakeBackup({ snapshots, wasDeployed });
 
-  // Pre-flight the storage check so a missing default doesn't reach the
-  // orchestrator's snapshot hook (where the throw would surface as a
-  // hostile stack trace). Skip when we're already not going to backup.
+  // Pre-flight the storage check so a missing/unusable default doesn't
+  // reach the orchestrator's snapshot hook (where the throw would
+  // surface as a hostile stack trace). Skip when we're already not
+  // going to backup.
   if (!effectiveNoBackup) {
-    const { getDefaultBackupStorage } = await import('../../services/backup-storage');
-    const storage = getDefaultBackupStorage();
-    if (!storage) {
-      return {
-        success: false,
-        error: `No default backup storage configured.
-
-celilo system update snapshots the celilo DB before applying module
-updates as a safety net. Configure backup storage first:
-
-  celilo storage add local
-
-Or skip the safety net entirely (the CLI self-update still runs):
-
-  celilo system update --no-backup`,
-      };
-    }
-    if (!storage.verified) {
-      return {
-        success: false,
-        error: `Default backup storage '${storage.storageId}' is not verified.
-
-Run:  celilo storage verify ${storage.storageId}
-
-Then re-run system update.`,
-      };
+    const { getDefaultBackupStorage, listBackupStorages } = await import(
+      '../../services/backup-storage'
+    );
+    const preflight = checkBackupStoragePreflight({
+      defaultStorage: getDefaultBackupStorage(),
+      allStorages: listBackupStorages(),
+    });
+    if (preflight.kind === 'error') {
+      return { success: false, error: preflight.message };
     }
   }