@vellumai/assistant 0.6.2 → 0.6.4

package/src/backup/list-snapshots.ts

@@ -0,0 +1,147 @@
+/**
+ * Helpers for listing on-disk backup snapshots.
+ *
+ * A "snapshot" here is any file inside a backup destination directory whose
+ * name matches the canonical `backup-YYYYMMDD-HHMMSS.vbundle[.enc]` pattern
+ * defined in `./paths.ts`. Anything else (READMEs, dotfiles, partial writes)
+ * is silently ignored so callers can scan a destination without worrying
+ * about non-snapshot clutter.
+ *
+ * The list helper is intentionally pure: it takes an explicit directory and
+ * touches no global state, which makes both production code and tests cheap
+ * to drive against tmp directories.
+ */
+
+import { readdir, stat, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { parseBackupTimestamp } from "./paths.js";
+
+/**
+ * Metadata about a single backup snapshot file. The `path` is the absolute
+ * path on disk; `createdAt` is parsed from the filename (UTC) rather than
+ * read from filesystem mtime so that copies/restores preserve their original
+ * snapshot identity.
+ */
+export interface SnapshotEntry {
+  path: string;
+  filename: string;
+  createdAt: Date;
+  sizeBytes: number;
+  encrypted: boolean;
+}
+
+/**
+ * Lists all backup snapshots in a directory, newest-first.
+ *
+ * Returns `[]` when the directory does not exist -- this is a normal case
+ * for fresh installs where no backup has been written yet, so callers do
+ * not need to special-case ENOENT.
+ *
+ * Files that don't match the canonical backup filename pattern are
+ * filtered out. Encrypted snapshots (`.vbundle.enc`) and plaintext
+ * snapshots (`.vbundle`) are both returned, distinguished by the
+ * `encrypted` flag on each entry.
+ */
+export async function listSnapshotsInDir(
+  dir: string,
+): Promise<SnapshotEntry[]> {
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+
+  const entries: SnapshotEntry[] = [];
+  for (const name of names) {
+    const createdAt = parseBackupTimestamp(name);
+    if (createdAt == null) continue;
+    const fullPath = join(dir, name);
+    let stats;
+    try {
+      stats = await stat(fullPath);
+    } catch (err) {
+      // Race: a file we just listed may have been removed (e.g. by a
+      // concurrent prune). Skip it rather than failing the whole listing.
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw err;
+    }
+    if (!stats.isFile()) continue;
+    entries.push({
+      path: fullPath,
+      filename: name,
+      createdAt,
+      sizeBytes: stats.size,
+      encrypted: name.endsWith(".vbundle.enc"),
+    });
+  }
+
+  // Newest-first by parsed snapshot timestamp. Stable across filesystems
+  // since we don't depend on inode/mtime ordering from `readdir`.
+  entries.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+  return entries;
+}
+
+/**
+ * Apply retention policy to a backup directory.
+ *
+ * Lists snapshots newest-first, keeps the first `retention` entries, and
+ * `unlink`s the rest. Returns a `{ kept, deleted }` split so callers can
+ * log/report what happened without re-listing the directory.
+ *
+ * The `skipped` flag distinguishes two missing-directory cases:
+ *
+ * - **Parent missing** (`skipped: true`): the parent of `dir` does not exist.
+ *   For offsite destinations this typically means the backing volume is not
+ *   available (e.g. iCloud Drive not enabled, external SSD unplugged). The
+ *   caller should treat the destination as temporarily unavailable rather
+ *   than silently creating it.
+ * - **`dir` missing, parent exists** (no `skipped` flag): the destination is
+ *   just empty. Returns `{ kept: [], deleted: [] }`. This is the normal
+ *   fresh-install case for local backups, where `writeLocalSnapshot` creates
+ *   the directory on demand.
+ *
+ * Treats both `.vbundle` and `.vbundle.enc` files as one pool ordered by
+ * parsed timestamp, so mixing plaintext and encrypted snapshots in the same
+ * directory retains the newest `retention` regardless of extension.
+ */
+export async function pruneDir(
+  dir: string,
+  retention: number,
+): Promise<{
+  kept: SnapshotEntry[];
+  deleted: SnapshotEntry[];
+  skipped?: boolean;
+}> {
+  // If the parent of `dir` does not exist, the destination is unreachable
+  // (e.g. iCloud Drive disabled, external volume unplugged). Signal the
+  // skipped state so callers can surface a useful error rather than treating
+  // an unavailable destination as an empty one.
+  try {
+    await stat(dirname(dir));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return { kept: [], deleted: [], skipped: true };
+    }
+    throw err;
+  }
+
+  const snapshots = await listSnapshotsInDir(dir);
+  const kept = snapshots.slice(0, retention);
+  const deleted = snapshots.slice(retention);
+
+  for (const entry of deleted) {
+    try {
+      await unlink(entry.path);
+    } catch (err) {
+      // Tolerate races with concurrent prunes / external deletions: a file
+      // we just stat'd may have been removed before we could unlink.
+      // Anything else (EACCES, EBUSY, ...) should still propagate.
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+  }
+
+  return { kept, deleted };
+}

package/src/backup/local-writer.ts

@@ -0,0 +1,133 @@
+/**
+ * Local snapshot writer + retention pruner.
+ *
+ * The "local" destination is the on-device backup directory (typically under
+ * `~/.vellum/backups/local`). It always stores plaintext `.vbundle` files --
+ * the encrypted variant is reserved for offsite destinations where the user
+ * cannot rely on filesystem-level access controls.
+ *
+ * Both helpers operate on an explicit directory path so callers can pick the
+ * right destination from config and so tests can drive everything against
+ * tmp directories without monkey-patching path helpers.
+ */
+
+import { randomBytes } from "node:crypto";
+import { copyFile, mkdir, rename, stat, unlink } from "node:fs/promises";
+import { basename, join } from "node:path";
+
+import { pruneDir, type SnapshotEntry } from "./list-snapshots.js";
+import { formatBackupFilename } from "./paths.js";
+
+/**
+ * Resolve a destination path that does not already exist on disk. Milliseconds
+ * in the filename already make same-second collisions effectively impossible
+ * from normal operation, but two backups fired in the same millisecond (or a
+ * leftover file from a previous run) would still collide. Fall back to a
+ * random suffix so the write never silently overwrites an existing file.
+ */
+async function resolveUniqueDestPath(
+  localDir: string,
+  filename: string,
+): Promise<string> {
+  const primary = join(localDir, filename);
+  try {
+    await stat(primary);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return primary;
+    throw err;
+  }
+  // Path occupied — insert a short random token before the extension. Loop in
+  // case the collision itself repeats, though 6 hex chars gives 16M values.
+  const extIdx = filename.indexOf(".vbundle");
+  const base = filename.slice(0, extIdx);
+  const ext = filename.slice(extIdx);
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const token = randomBytes(3).toString("hex");
+    const candidate = join(localDir, `${base}-${token}${ext}`);
+    try {
+      await stat(candidate);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return candidate;
+      throw err;
+    }
+  }
+  throw new Error(
+    `Unable to find a unique backup filename under ${localDir} for ${filename}`,
+  );
+}
+
+/**
+ * Move a freshly-built `.vbundle` temp file into the local backup directory
+ * under its canonical timestamped name.
+ *
+ * - Creates `localDir` (recursively, mode `0o700`) if it does not yet exist.
+ * - Renames the temp file to `<localDir>/backup-YYYYMMDD-HHMMSS-SSS.vbundle`.
+ *   On EXDEV (cross-device move, e.g. when the temp dir is on a different
+ *   filesystem than the backup directory) it falls back to copy + unlink.
+ * - If the canonical filename is already taken on disk (two backups in the
+ *   same millisecond, or a leftover from a prior crash), a short random
+ *   suffix is appended so the rename never silently overwrites an existing
+ *   snapshot.
+ * - Returns a `SnapshotEntry` describing the final on-disk file.
+ *
+ * The caller is expected to pass the same `now` it used when staging the
+ * bundle so that the filename, the entry's `createdAt`, and any external
+ * record stay in sync.
+ */
+export async function writeLocalSnapshot(
+  tempVBundlePath: string,
+  localDir: string,
+  now: Date,
+): Promise<SnapshotEntry> {
+  await mkdir(localDir, { recursive: true, mode: 0o700 });
+
+  const baseFilename = formatBackupFilename(now, { encrypted: false });
+  const destPath = await resolveUniqueDestPath(localDir, baseFilename);
+  const filename = basename(destPath);
+
+  try {
+    await rename(tempVBundlePath, destPath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "EXDEV") throw err;
+    // Cross-device fallback: copy then remove the source so callers don't
+    // leak the temp file. We deliberately use copyFile (not a stream pipe)
+    // because the bundle has already been fully written to disk by the
+    // staging step -- there's nothing to stream.
+    await copyFile(tempVBundlePath, destPath);
+    await unlink(tempVBundlePath);
+  }
+
+  const stats = await stat(destPath);
+  return {
+    path: destPath,
+    filename,
+    createdAt: now,
+    sizeBytes: stats.size,
+    encrypted: false,
+  };
+}
+
+/**
+ * Apply retention policy to the local backup directory.
+ *
+ * Thin wrapper around the shared `pruneDir` helper in `list-snapshots.ts`.
+ * Local backup directories live under `~/.vellum/backups/local` and are
+ * created on demand by `writeLocalSnapshot`, so the parent is effectively
+ * always present — we strip the `skipped` flag from the returned shape to
+ * match the original local-writer contract.
+ *
+ * Edge cases:
+ * - Missing directory: returns `{ kept: [], deleted: [] }` (inherited from
+ *   `pruneDir`, which defers to `listSnapshotsInDir`'s ENOENT handling).
+ * - `retention >= snapshots.length`: nothing is deleted; everything is kept.
+ * - `retention === 0`: every snapshot is deleted. The config schema rejects
+ *   `retention: 0` (min is 1), so this branch only fires when callers
+ *   explicitly opt into a wipe; treat it as a defensive guarantee.
+ */
+export async function pruneLocalSnapshots(
+  localDir: string,
+  retention: number,
+): Promise<{ kept: SnapshotEntry[]; deleted: SnapshotEntry[] }> {
+  const { kept, deleted } = await pruneDir(localDir, retention);
+  return { kept, deleted };
+}

package/src/backup/offsite-writer.ts

@@ -0,0 +1,222 @@
+/**
+ * Offsite snapshot writer with per-destination encryption.
+ *
+ * "Offsite" destinations are any location outside the local backup directory
+ * where the user wants a redundant copy of a just-written local snapshot.
+ * Canonical examples: iCloud Drive, an external SSD, a network share.
+ *
+ * Per-destination `encrypt` flag:
+ * - `encrypt: true`  → AES-256-GCM stream-encrypt into `.vbundle.enc`.
+ * - `encrypt: false` → plaintext copy into `.vbundle`. Intended for volumes
+ *   where the user controls physical access (e.g. an external SSD).
+ *
+ * Each destination is written independently and sequentially, so one bad
+ * destination cannot poison the others: a missing iCloud mount or a broken
+ * external drive surfaces as a per-destination `skipped` or `error` in the
+ * returned array while every other destination still gets its copy.
+ *
+ * The helpers are pure with respect to daemon state — they operate on an
+ * explicit `localSnapshotPath`, `destinations`, `key`, and `now` so tests can
+ * drive the whole surface against temp directories.
+ */
+
+import { copyFile, mkdir, rename, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { BackupDestination } from "../config/schema.js";
+import {
+  pruneDir,
+  type SnapshotEntry,
+} from "./list-snapshots.js";
+import { deriveSafeAncestor, formatBackupFilename } from "./paths.js";
+import { encryptFile } from "./stream-crypt.js";
+
+/**
+ * Result of writing a single offsite destination.
+ *
+ * Exactly one of `entry`, `skipped`, or `error` is meaningful:
+ * - `entry` non-null → the write succeeded.
+ * - `skipped: "parent-missing"` → the destination's safe ancestor does not
+ *   exist (e.g. iCloud Drive not enabled, external volume unplugged). Not an
+ *   error — the write is simply deferred until the volume is back. The
+ *   ancestor is derived by `deriveSafeAncestor`: for iCloud Drive or
+ *   `/Volumes/<name>/...` paths it is a well-known mount root, which lets us
+ *   bootstrap intermediate directories on first run; for arbitrary
+ *   user-configured paths it falls back to the immediate parent.
+ * - `error` set → an unexpected failure while writing. Surfaced as a string
+ *   so callers can log without serializing an `Error` object.
+ *
+ * `destination` always preserves the full config record (path + encrypt) so
+ * callers can correlate a result with the destination that produced it.
+ */
+export interface OffsiteWriteResult {
+  destination: BackupDestination;
+  entry: SnapshotEntry | null;
+  skipped?: "parent-missing";
+  error?: string;
+}
+
+/**
+ * Write a local snapshot to a single offsite destination.
+ *
+ * Behavior:
+ * - If the destination's safe ancestor (see `deriveSafeAncestor`) does not
+ *   exist → returns `{ destination, entry: null, skipped: "parent-missing" }`.
+ *   The offsite volume is (temporarily) unavailable; the caller should not
+ *   treat this as an error.
+ * - Otherwise `mkdir -p` the destination directory (mode `0o700`). This
+ *   bootstraps any intermediate directories between the safe ancestor and
+ *   the destination (e.g. creating `VellumAssistant/backups/` under iCloud
+ *   Drive on first run).
+ * - If `destination.encrypt === true`, stream-encrypts via `encryptFile`
+ *   with the provided `key` and writes `.vbundle.enc`. A missing `key`
+ *   here is a programmer error, but per the plan we still catch it rather
+ *   than throwing — a broken destination must never poison the others.
+ * - If `destination.encrypt === false`, copies the local snapshot into a
+ *   `.tmp` sibling and renames into place (atomic; cross-filesystem safe
+ *   because `copyFile` handles the copy itself).
+ *
+ * On any unexpected throw, returns `{ destination, entry: null, error: msg }`.
+ */
+export async function writeOffsiteSnapshotToOne(
+  localSnapshotPath: string,
+  destination: BackupDestination,
+  key: Buffer | null,
+  now: Date,
+): Promise<OffsiteWriteResult> {
+  try {
+    // Ancestor-missing probe: if the destination's derived "safe ancestor"
+    // does not exist we treat the destination as temporarily unavailable
+    // rather than auto-creating a deep tree we have no reason to own. The
+    // ancestor is a well-known mount root (iCloud Drive, /Volumes/<name>)
+    // for recognized path shapes, or the immediate parent otherwise. That
+    // way an unplugged external drive still skips cleanly while the default
+    // iCloud destination can bootstrap its intermediate folders on first run.
+    try {
+      await stat(deriveSafeAncestor(destination.path));
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return { destination, entry: null, skipped: "parent-missing" };
+      }
+      throw err;
+    }
+
+    // `destination.path` itself may not exist yet — create it now that we
+    // know its parent is reachable.
+    await mkdir(destination.path, { recursive: true, mode: 0o700 });
+
+    const filename = formatBackupFilename(now, {
+      encrypted: destination.encrypt,
+    });
+    const outputPath = join(destination.path, filename);
+
+    if (destination.encrypt) {
+      // Programmer-contract: the caller must have ensured a key exists if any
+      // destination is encrypted. We still route this through the catch block
+      // so a single broken destination cannot poison the others.
+      if (key == null) {
+        throw new Error(
+          "Offsite destination requires encryption but no key was provided",
+        );
+      }
+      await encryptFile(localSnapshotPath, outputPath, key);
+    } else {
+      // Atomic plaintext copy: write into a sibling `.tmp` then rename into
+      // place. `copyFile` handles cross-filesystem copies, so we don't need
+      // the EXDEV fallback dance that `writeLocalSnapshot` uses for a
+      // same-device rename.
+      const tempPath = `${outputPath}.tmp`;
+      await copyFile(localSnapshotPath, tempPath);
+      await rename(tempPath, outputPath);
+    }
+
+    const stats = await stat(outputPath);
+    return {
+      destination,
+      entry: {
+        path: outputPath,
+        filename,
+        createdAt: now,
+        sizeBytes: stats.size,
+        encrypted: destination.encrypt,
+      },
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { destination, entry: null, error: message };
+  }
+}
+
+/**
+ * Write a local snapshot to every configured offsite destination, in order.
+ *
+ * Sequential by design: parallelizing wouldn't save meaningful wall-clock
+ * time (the dominant cost is filesystem IO on potentially-slow network
+ * volumes) and sequential writes make per-destination failures trivially
+ * observable. Empty array returns `[]` immediately without any stat/mkdir.
+ *
+ * Returns one `OffsiteWriteResult` per input destination, in the same order
+ * as `destinations`. Callers can `filter` the result to extract successes
+ * (`entry != null`), skips (`skipped === "parent-missing"`), or errors
+ * (`error != null`).
+ */
+export async function writeOffsiteSnapshotToAll(
+  localSnapshotPath: string,
+  destinations: BackupDestination[],
+  key: Buffer | null,
+  now: Date,
+): Promise<OffsiteWriteResult[]> {
+  if (destinations.length === 0) return [];
+
+  const results: OffsiteWriteResult[] = [];
+  for (const destination of destinations) {
+    const result = await writeOffsiteSnapshotToOne(
+      localSnapshotPath,
+      destination,
+      key,
+      now,
+    );
+    results.push(result);
+  }
+  return results;
+}
+
+/**
+ * Apply retention to every configured offsite destination.
+ *
+ * Retention is applied **per destination** — each keeps its own newest
+ * `retention` snapshots independently. A `skipped: true` result means the
+ * destination's parent directory is missing (e.g. iCloud Drive disabled);
+ * callers should treat this as a transient unavailability rather than an
+ * empty directory.
+ *
+ * Mixed `.vbundle` and `.vbundle.enc` files in a single destination are
+ * treated as one pool ordered by parsed timestamp, so retention still holds
+ * if a destination's `encrypt` flag changes over its lifetime.
+ */
+export async function pruneOffsiteSnapshotsInAll(
+  destinations: BackupDestination[],
+  retention: number,
+): Promise<
+  Array<{
+    destination: BackupDestination;
+    kept: SnapshotEntry[];
+    deleted: SnapshotEntry[];
+    skipped?: boolean;
+  }>
+> {
+  const results: Array<{
+    destination: BackupDestination;
+    kept: SnapshotEntry[];
+    deleted: SnapshotEntry[];
+    skipped?: boolean;
+  }> = [];
+  for (const destination of destinations) {
+    const { kept, deleted, skipped } = await pruneDir(
+      destination.path,
+      retention,
+    );
+    results.push({ destination, kept, deleted, skipped });
+  }
+  return results;
+}