Mark the package private and declare engines and exports (closes #6)

quak is not published, so package.json is marked private and loses its
files field. engines.node is >=22, the major version script/bootstrap
and the Dockerfile use. The exports map makes "." and "./package.json"
the only importable paths, so the CLI-only modules stay internal.

Model: opus-5-5

README.md

@@ -214,11 +214,23 @@ quak/
         auth/           login flow (SRP + email OTP + TOTP), key unwrap
         model/          decrypted Collection, File, Metadata types + decrypt fns
         download/       streaming file/thumbnail download + decryption
+        library/        the cache-backed Library: metadata store, read
+                        surface, records, content cache, precache, ML data
+                        and search, request pools
         backup.ts       resilient full-account backup with dedup
+        metadata-backup.ts
+                        backup-metadata: all decrypted metadata as JSON
+        mldata-fetch.ts fetch + decrypt per-file ML data
+        filename.ts     safe file names from server metadata
         errors.ts       error types shared across layers
         retry.ts        retry classifier + exponential backoff with jitter
         thumbnails.ts   detect + regenerate missing thumbnails
         client.ts       high-level Client class assembled from the above
+        cli-commands.ts the CLI's commands as functions returning exit codes
+        cli-output.ts   how the CLI prints a file's title and time
+        cli-read.ts     fresh reads for the CLI's read commands
+        cli-run.ts      run a command, print its error, exit with its code
+        cli-session.ts  read the saved session file back into a Client
         index.ts        public library exports
     bin/
         quak.ts         CLI entrypoint (commander.js)
@@ -449,10 +461,13 @@ quak helper fix-missing-thumbnails [--file ids] generate + upload missing thumbn
 ```
 
 Every command runs on the same cache-backed library. The read commands —
-`collections`, `files`, `get`, and `get-thumb` — force a fresh server round-trip
+`collections`, `files`, `get`, `get-thumb`, `backup-metadata`,
-before they answer, so they report current account state rather than whatever
+`helper list-missing-thumbnails` and `helper fix-missing-thumbnails` — force a
-the cache last held. `--cache-dir` overrides where the cache lives; without it
+fresh server round-trip before they answer, so they report current account state
-each account gets its own directory under the per-user cache path.
+rather than whatever the cache last held. If that round-trip fails, the command
+prints the error on one line and exits 1. `--cache-dir` overrides where the
+cache lives; without it each account gets its own directory under the per-user
+cache path.
 
 `get` and `get-thumb` resolve the file by ID directly, so `--collection` is
 accepted for backward compatibility but ignored. `backup-metadata --exif` (alias
@@ -490,8 +505,15 @@ the smallest does not.
         <name>/
             <title> -> ../../originals/<fileID>.<ext>   (symlink)
         <name>.json             collection metadata + file list
+    failures.json               files that failed and have not yet succeeded
 ```
 
+`failures.json` records each failed file with the kind of failure, how many
+times it has been tried and when it was last tried. A file leaves it once it
+succeeds, or once it is no longer in the library or in the backup's scope. The
+library's `lib.backup({ includeThumbnails: true })` also writes
+`thumbnails/<fileID>.jpg` beside `originals/`; `quak backup` does not.
+
 A collection's directory and JSON are named after the collection, and a symlink
 after the file's title, both with unsafe characters replaced. When two
 collections would get the same name, or two files in one collection the same
@@ -507,22 +529,25 @@ symlink you put there stays, and a directory that still holds one after its
 symlinks are removed stays too, with its JSON.
 
 Each file is downloaded exactly once regardless of how many collections it
-appears in. On subsequent runs, existing originals are skipped. If a download
+appears in, and written once: straight into `originals/`, with no copy left in
-fails, the error is logged and the backup continues with the next file. The exit
+the cache. An original the cache already held is copied from there instead. On
-code is non-zero if any files failed.
+subsequent runs, existing originals are skipped. If a download fails, the error
+is logged and the backup continues with the next file. The exit code is non-zero
+if any files failed. `quak backup` opens its library with the thumbnail and
+originals precache off, so it fetches only what the backup stores.
 
-Each original is copied to a temporary file named
+Each original is written to a temporary file in the same directory, synced to
-`.quak-backup-<fileID>.<ext>-<pid>-<random>.tmp` in the same directory, synced
+disk, and renamed into place, so an original is either complete or absent, even
-to disk, and renamed into place, so an original is either complete or absent,
+after a power cut. A downloaded original's temporary file is named
-even after a power cut. A run that is killed can leave one of these temporary
+`.quak-<pid>-<random>.tmp`, one copied from the cache
-files behind; the next backup deletes those whose process is no longer running.
+`.quak-backup-<fileID>.<ext>-<pid>-<random>.tmp`. A run that is killed can leave
-Downloads and the content cache use the same scheme with
+one of these temporary files behind; the next backup deletes those whose process
-`.quak-<pid>-<random>.tmp` names, and opening a library deletes those in the
+is no longer running. The content cache uses the same scheme, and opening a
-cache whose process is no longer running, so a download another process has in
+library deletes the temporary files in the cache whose process is no longer
-progress in the same cache is left alone. The rename replaces whatever was at
+running, so a download another process has in progress in the same cache is left
-the destination rather than writing through it: a symlink there is replaced, not
+alone. The rename replaces whatever was at the destination rather than writing
-followed, and the new file has the temporary file's permissions, not those of
+through it: a symlink there is replaced, not followed, and the new file has the
-the file it replaced.
+temporary file's permissions, not those of the file it replaced.
 
 ## TODO
 
@@ -530,7 +555,12 @@ the file it replaced.
       errors
 - [x] Update the API reference section below to match the current implementation
 - [x] `make docker` green
-- [ ] Tag `v1.0.0`
+- [ ] Store live photos in a form a photo viewer can open
+      (https://git.eeqj.de/sneak/quak/issues/107), once sneak has chosen between
+      keeping the ZIP and unpacking it
+
+Tagging and releases are decided by sneak alone, and happen only when he
+declares one.
 
 Future (desktop client, separate repo):
 
@@ -550,10 +580,11 @@ test suite is the canonical, executable documentation — `test/library/` and
 ### Opening a library
 
 `Library.open(options)` loads the on-disk cache, starts the background refresh
-loop, and resolves to a `Library`. On an empty cache it awaits the first refresh
+loop, and resolves to a `Library`. On an empty cache it awaits the first
-so it never opens onto empty data; on an existing cache it returns immediately
+refresh, so it opens onto the account's data whenever the server is reachable;
-and refreshes in the background, so an unreachable server does not block
+if that refresh fails, it opens with no data and records the error in
-opening.
+`lib.status()`. On an existing cache it returns immediately and refreshes in the
+background, so an unreachable server does not block opening.
 
 `LibraryOptions`:
 
@@ -664,12 +695,15 @@ photos newest first). `lib.subscribe({ onChange })` delivers a `LibraryChange`
   default limit 20). quak bundles no text encoder, so `searchByEmbedding` takes
   a query vector the caller produced elsewhere.
 - `await lib.backup(opts?)` → `BackupResult`. It refreshes, fetches every
-  in-scope original (and, with `includeThumbnails`, thumbnails) through the
+  in-scope original not already in the backup (and, with `includeThumbnails`,
-  content cache, and rebuilds the on-disk backup tree with a durable failure
+  thumbnails) through the content cache, and rebuilds the on-disk backup tree
-  ledger. `BackupOptions`: `downloadDirectory` (falls back to the one `open()`
+  with a durable failure ledger. A fetched original is written straight into the
-  was given), `includeOriginals` (default `true`), `includeThumbnails` (default
+  backup's `originals/` and not into the cache, which then counts it as present;
-  `false`), `onlyAlbumNames`, and `onProgress`. See Backup layout above for the
+  one the cache already held is copied from there. `BackupOptions`:
-  tree it writes.
+  `downloadDirectory` (falls back to the one `open()` was given),
+  `includeOriginals` (default `true`), `includeThumbnails` (default `false`),
+  `onlyAlbumNames`, and `onProgress`. See Backup layout above for the tree it
+  writes.
 
 ### Request pools
 
@@ -766,8 +800,10 @@ documents:
   markdown. Use `make fmt` to format. Use `yarn` not `npm`.
 
 - **Testing:** vitest. Tests go in `test/` mirroring the `src/` structure.
-  `make test` must complete in under 20 seconds. Use `mkdtempSync` for temporary
+  `make test` must finish in under 60 seconds (the hard cap) and should finish
-  directories, never manual timestamp paths.
+  in under 20. The 90-second `timeout` in the `test` phase of the `Dockerfile`
+  is a backstop that catches a hung test, not the time limit. Use `mkdtempSync`
+  for temporary directories, never manual timestamp paths.
 
 - **Code style:** `const` for everything, `let` if reassignment is needed, never
   `var`. Avoid unnecessary comments. No hand-rolled crypto. The

TODO.md

@@ -14,10 +14,64 @@ pre-1.0
 
 # Next Step
 
-Tag v1.0.0.
+Store live photos in a form a photo viewer can open
+(https://git.eeqj.de/sneak/quak/issues/107). This waits on sneak's choice
+between keeping the ZIP and unpacking it into the image and the video.
+
+Tagging and releases are decided by sneak alone, and happen only when he
+declares one.
 
 # Completed Steps
 
+- 2026-09-23: Settled the package metadata (issue 6). quak is not published, so
+  `package.json` is marked `"private": true` and the `files` field is gone.
+  `engines.node` is `>=22`, the major version `script/bootstrap` and the
+  `Dockerfile` use. An `exports` map makes `.` and `./package.json` the only
+  importable paths; `runMetadataBackup`, the thumbnail helpers and their types
+  stay internal to the CLI.
+
+- 2026-09-23: Brought the README and this file in line with the tree (issue
+  111). The layout lists `src/library/` and the other source files, the backup
+  layout names `failures.json` and the optional `thumbnails/`, "Opening a
+  library" says what happens when the first refresh fails, the Testing section
+  gives the 60-second hard cap and 20-second target for `make test` and names
+  the 90-second `timeout` in the `Dockerfile` as the backstop for a hung test,
+  and "Tag v1.0.0" is no longer listed as the next step.
+
+- 2026-09-23: Tested `quak login` and `backup-metadata --exif` (issue 110).
+  `loginCommand` takes its login function and its prompts from `CliContext`, and
+  `bin/quak.ts` passes `Client.login` and the terminal prompts. Tests cover a
+  login from `QUAK_EMAIL` and `QUAK_PASSWORD` with no prompt, the TOTP prompt, a
+  failed login, and the saved session's modes, and show that `--exif` and
+  `--all` each turn on EXIF extraction and that it is off without them.
+
+- 2026-09-23: `quak backup` writes each original once and no longer fills the
+  cache (issue 106). An original fetched for a backup is written by the download
+  writer straight into the backup's `originals/`, and the content cache records
+  it there instead of keeping its own copy; one the cache already held is still
+  copied. `quak backup` opens its library with the thumbnail and originals
+  precache off.
+
+- 2026-09-23: `backup-metadata`, `helper list-missing-thumbnails` and
+  `helper fix-missing-thumbnails` refresh before they answer (issue 100). Each
+  awaits `lib.fresh()` before reading, so a file added since the cache was
+  written is included, and a failed refresh prints one line and exits 1 instead
+  of answering from a stale or empty cache. The README lists them among the
+  commands that refresh first.
+
+- 2026-09-23: `quak backup` waits for the server refresh and fails when it fails
+  (issue 99). `lib.backup()` joins a refresh already running or starts one, as
+  `fresh()` does, and rejects before touching any file when it fails, leaving
+  `failures.json` as it was, so `quak backup` prints the error as one line and
+  exits 1 instead of backing up the previous run's file list, or nothing, and
+  exiting 0.
+
+- 2026-09-23: CLI errors print a message instead of a stack trace (issue 102).
+  An error a command throws is printed as one `quak: MESSAGE` line on stderr and
+  the CLI exits 1 once output has drained. The wrapper that does this moved from
+  `bin/quak.ts` to `src/cli-run.ts`, and `bin/quak.ts` now awaits
+  `program.parseAsync()`.
+
 - 2026-09-23: Opening a library no longer deletes another process's download in
   progress (issue 105). The download writer's temp files are named
   `.quak-<pid>-<random>.tmp`, and `removeLeftoverTempFiles`, moved from the

bin/quak.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { stdout, stderr } from "node:process";
+import { input, password } from "@inquirer/prompts";
 import { Command } from "commander";
 import envPaths from "env-paths";
 import { init } from "../src/crypto/index.js";
@@ -18,7 +19,9 @@ import {
     listMissingThumbnailsCommand,
     fixMissingThumbnailsCommand,
 } from "../src/cli-commands.js";
+import { run as runCommand } from "../src/cli-run.js";
 import { loadSession } from "../src/cli-session.js";
+import { Client } from "../src/client.js";
 import { VERSION } from "../src/index.js";
 
 const paths = envPaths("quak", { suffix: "" });
@@ -41,25 +44,13 @@ const context = (): CliContext => ({
     sessionDir: paths.data,
     cacheDir: program.opts<{ cacheDir?: string }>().cacheDir,
     loadSession,
+    login: (opts) => Client.login(opts),
+    prompt: (message) => input({ message }),
+    promptSecret: (message) => password({ message, mask: true }),
 });
 
-// Run a command and exit with its code once stdout/stderr have drained.
+const run = (command: Promise<number>): Promise<void> =>
-// Exiting before the drain can truncate piped output, and the library can keep
+    runCommand(command, stdout, stderr, (code) => process.exit(code));
-// the event loop alive after a command returns, so a plain return could hang.
-const run = async (command: Promise<number>): Promise<void> => {
-    process.exitCode = await command;
-    const pending = [stdout, stderr].filter((s) => s.writableLength > 0);
-    if (pending.length === 0) {
-        process.exit();
-        return;
-    }
-    let remaining = pending.length;
-    for (const s of pending) {
-        s.once("drain", () => {
-            if (--remaining === 0) process.exit();
-        });
-    }
-};
 
 program
     .command("login")
@@ -169,4 +160,4 @@ helper
     );
 
 await init();
-program.parse();
+await program.parseAsync();

package.json

@@ -9,17 +9,23 @@
         "type": "git",
         "url": "https://git.eeqj.de/sneak/quak.git"
     },
+    "private": true,
     "type": "module",
+    "engines": {
+        "node": ">=22"
+    },
     "main": "./dist/src/index.js",
     "types": "./dist/src/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/src/index.d.ts",
+            "import": "./dist/src/index.js"
+        },
+        "./package.json": "./package.json"
+    },
     "bin": {
         "quak": "./dist/bin/quak.js"
     },
-    "files": [
-        "dist/",
-        "README.md",
-        "LICENSE"
-    ],
     "scripts": {
         "build": "script/build",
         "quak": "node ./dist/bin/quak.js",

src/backup.ts

@@ -1,9 +1,11 @@
 // The backup command, rebuilt on the library API (issue #51).
 //
-// `lib.backup()` refreshes the library, then, for every file in scope, gets its
+// `lib.backup()` waits for a completed refresh of the library (a failed one
-// original bytes onto disk under `downloadDirectory` and rebuilds the derived
+// fails the backup before any file is touched), then, for every file in scope,
-// views (per-file sidecars, per-collection symlink trees, per-collection JSON)
+// gets its original bytes onto disk under `downloadDirectory` and rebuilds the
-// from the model. The on-disk layout is the historical one, unchanged:
+// derived views (per-file sidecars, per-collection symlink trees,
+// per-collection JSON) from the model. The on-disk layout is the historical
+// one, unchanged:
 //
 //     <downloadDirectory>/
 //         originals/<fileID>.<ext>     the decrypted bytes
@@ -95,8 +97,9 @@ export interface BackupLibrary {
     listCollections(): Collection[];
     listFiles(collectionID: number): EnteFile[];
     // Get an original's bytes onto disk through the content cache/pools,
-    // returning where they landed (the cache, or a prior backup).
+    // returning where they landed: `destination` when they were fetched now,
-    original(fileID: number): Promise<{ path: string }>;
+    // otherwise wherever they already were (the cache, or a prior backup).
+    original(fileID: number, destination: string): Promise<{ path: string }>;
     thumbnail(fileID: number): Promise<{ path: string }>;
 }
 
@@ -423,7 +426,9 @@ export const runBackup = async (
             }
             try {
                 log(`Fetching original ${file.metadata.title} (${fileID})...`);
-                const { path } = await lib.original(fileID);
+                // A fetched original is written straight to `dest`; only one
+                // that was already cached elsewhere is copied.
+                const { path } = await lib.original(fileID, dest);
                 await copyAtomic(path, dest);
                 downloaded++;
             } catch (err) {

src/cli-commands.ts

@@ -2,11 +2,10 @@
 //
 // Each command takes its options and a `CliContext` and resolves to the exit
 // code; a thrown error is left to the caller. Nothing here calls
-// `process.exit`: `bin/quak.ts` wires these to the command line and exits with
+// `process.exit`: `bin/quak.ts` wires these to the command line, and `run` in
-// the returned code once output has drained. Output must stay byte-identical
+// `cli-run.ts` prints a thrown error as one line and exits once output has
-// (see `cli-output.ts`).
+// drained. Output must stay byte-identical (see `cli-output.ts`).
 
-import { input, password as passwordPrompt } from "@inquirer/prompts";
 import {
     copyFileSync,
     existsSync,
@@ -15,7 +14,11 @@ import {
     writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
-import { Client, type ClientSnapshot } from "./client.js";
+import {
+    type Client,
+    type ClientSnapshot,
+    type LoginOptions,
+} from "./client.js";
 import { init } from "./crypto/index.js";
 import {
     defaultCacheDirectory,
@@ -43,6 +46,12 @@ export interface CliContext {
     // Reads the session file into a client, or null when there is none. The
     // CLI passes `loadSession` from `cli-session.ts`; tests pass a fake client.
     loadSession: (path: string) => Client | null;
+    // Used by `login` only. The CLI passes `Client.login` and terminal
+    // prompts; tests pass fakes.
+    login: (opts: LoginOptions) => Promise<Client>;
+    prompt: (message: string) => Promise<string>;
+    // Like `prompt`, but the answer is masked as it is typed.
+    promptSecret: (message: string) => Promise<string>;
 }
 
 const sessionPath = (ctx: CliContext): string =>
@@ -108,24 +117,19 @@ const openReadLibrary = (ctx: CliContext, client: Client): Promise<Library> =>
         precacheOriginals: false,
     });
 
-const prompt = async (message: string): Promise<string> => input({ message });
-
-const promptSecret = async (message: string): Promise<string> =>
-    passwordPrompt({ message, mask: true });
-
 export const loginCommand = async (ctx: CliContext): Promise<number> => {
     await init();
-    const email = process.env.QUAK_EMAIL ?? (await prompt("Email"));
+    const email = process.env.QUAK_EMAIL ?? (await ctx.prompt("Email"));
     const password =
-        process.env.QUAK_PASSWORD ?? (await promptSecret("Password"));
+        process.env.QUAK_PASSWORD ?? (await ctx.promptSecret("Password"));
 
     ctx.stderr.write("Authenticating...\n");
     try {
-        const client = await Client.login({
+        const client = await ctx.login({
             email,
             password,
-            totp: async () => prompt("TOTP code: "),
+            totp: async () => ctx.prompt("TOTP code: "),
-            emailOTP: async () => prompt("Email verification code: "),
+            emailOTP: async () => ctx.prompt("Email verification code: "),
         });
 
         saveSession(ctx.sessionDir, client.toJSON());
@@ -356,6 +360,9 @@ export const backupMetadataCommand = async (
     if (!client) return 1;
     const lib = await openReadLibrary(ctx, client);
     try {
+        // Refresh first so the dump holds current account state, not what the
+        // cache last held; a failed refresh throws.
+        await lib.fresh();
         const { failedMLBatches } = await runMetadataBackup(lib, client, dir, {
             exif: opts.exif || opts.all,
             onProgress: (msg) => ctx.stderr.write(msg + "\n"),
@@ -376,10 +383,14 @@ export const backupCommand = async (
     if (!client) return 1;
 
     ctx.stderr.write("Starting backup...\n");
+    // The precache is off: the backup fetches what it needs, and must not
+    // also fill the cache with every thumbnail and the recent originals.
     const lib = await Library.open({
         client,
         downloadDirectory: dir,
         cacheDirectory: ctx.cacheDir,
+        precacheThumbnails: false,
+        precacheOriginals: false,
     });
     try {
         const result = await lib.backup({
@@ -422,6 +433,9 @@ export const listMissingThumbnailsCommand = async (
     if (!client) return 1;
     const lib = await openReadLibrary(ctx, client);
     try {
+        // Refresh first so files added since the cache was written are
+        // checked; a failed refresh throws.
+        await lib.fresh();
         const missing = await listMissingThumbnails(lib, client, (msg) => {
             if (!opts.json) ctx.stderr.write(msg + "\n");
         });
@@ -457,6 +471,9 @@ export const fixMissingThumbnailsCommand = async (
     if (!client) return 1;
     const lib = await openReadLibrary(ctx, client);
     try {
+        // Refresh first so files added since the cache was written are found;
+        // a failed refresh throws.
+        await lib.fresh();
         let fileIDs: number[];
         if (opts.file && opts.file.length > 0) {
             fileIDs = opts.file.map(Number).filter(Number.isFinite);

src/cli-run.ts

@@ -0,0 +1,36 @@
+// Runs one CLI command for `bin/quak.ts` and exits with its code.
+
+import type { Writable } from "node:stream";
+
+// Run a command and exit with its code once stdout/stderr have drained.
+// Exiting before the drain can truncate piped output, and the library can keep
+// the event loop alive after a command returns, so a plain return could hang.
+// An error the command throws is printed as one `quak: MESSAGE` line, without
+// the stack trace, and exits 1.
+export const run = async (
+    command: Promise<number>,
+    stdout: Writable,
+    stderr: Writable,
+    exit: (code: number) => void,
+): Promise<void> => {
+    let code: number;
+    try {
+        code = await command;
+    } catch (err) {
+        stderr.write(
+            `quak: ${err instanceof Error ? err.message : String(err)}\n`,
+        );
+        code = 1;
+    }
+    const pending = [stdout, stderr].filter((s) => s.writableLength > 0);
+    if (pending.length === 0) {
+        exit(code);
+        return;
+    }
+    let remaining = pending.length;
+    for (const s of pending) {
+        s.once("drain", () => {
+            if (--remaining === 0) exit(code);
+        });
+    }
+};

src/library/content.ts

@@ -321,6 +321,23 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
         return this.get(fileID, "thumbnail", "on-demand", opts?.onProgress);
     }
 
+    // Get an original for a backup. One not present anywhere is written
+    // straight to `destination` and recorded there, so no second copy lands
+    // in the cache; one already present is returned where it is.
+    async backupOriginal(
+        fileID: number,
+        destination: string,
+    ): Promise<ContentResult> {
+        const result = await this.acquire(
+            fileID,
+            "original",
+            "on-demand",
+            undefined,
+            { destination },
+        );
+        return { path: result.path, bytes: result.bytes };
+    }
+
     async ensure(args: EnsureOptions): Promise<EnsureResult[]> {
         return this.ensureThumbnails(args);
     }
@@ -422,13 +439,14 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
 
     // The core: return the cached path if present, else fetch through the pool,
     // store, and return it. `cached` distinguishes a present hit (no network,
-    // no download event) from a fresh fetch.
+    // no download event) from a fresh fetch. A fetched original is stored at
+    // `opts.destination` when given, instead of in `originalsDir`.
     private async acquire(
         fileID: number,
         kind: Kind,
         priority: Priority,
         signal: AbortSignal | undefined,
-        opts?: { onByte?: ProgressCallback },
+        opts?: { onByte?: ProgressCallback; destination?: string },
     ): Promise<{ path: string; bytes: number; cached: boolean }> {
         const file = this.getFile(fileID);
         if (!file) throw new Error(`content cache: unknown file ${fileID}`);
@@ -469,7 +487,7 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
             kind === "original" ? this.originalsDir : this.thumbnailsDir;
         const dest =
             kind === "original"
-                ? join(dir, originalName(file))
+                ? (opts?.destination ?? join(dir, originalName(file)))
                 : join(dir, `${fileID}${THUMBNAIL_EXT}`);
         const pool =
             kind === "original" ? this.pools.content : this.pools.thumbnails;

src/library/index.ts

@@ -538,11 +538,13 @@ export class Library {
     }
 
     // Back up every in-scope file to `downloadDirectory` in the historical
-    // on-disk layout, with a durable failure ledger (issue #51). Refreshes
+    // on-disk layout, with a durable failure ledger (issue #51). Waits for a
-    // first, fetches pending originals (and optional thumbnails) through the
+    // completed refresh first, as `fresh()` does, joining one already running,
-    // content cache and pools, then rebuilds the derived symlink/JSON views
+    // and rejects before touching any file when it fails. Then fetches pending
-    // from the model. Throws before any network work when no download directory
+    // originals (and optional thumbnails) through the content cache and pools,
-    // is available or no content cache backs the originals it must fetch.
+    // and rebuilds the derived symlink/JSON views from the model. Throws before
+    // any network work when no download directory is available or no content
+    // cache backs the originals it must fetch.
     backup(opts?: BackupOptions): Promise<BackupResult> {
         const downloadDirectory =
             opts?.downloadDirectory ?? this.downloadDirectory;
@@ -566,10 +568,11 @@ export class Library {
         const cache = this.cache;
         return runBackup(
             {
-                refresh: () => this.runRefresh(),
+                refresh: () => this.refreshNow(),
                 listCollections: () => this.store.listCollections(),
                 listFiles: (id) => this.store.listFiles(id),
-                original: (fileID) => cache!.original(fileID),
+                original: (fileID, destination) =>
+                    cache!.backupOriginal(fileID, destination),
                 thumbnail: (fileID) => cache!.thumbnail(fileID),
             },
             { ...opts, downloadDirectory },

src/metadata-backup.ts

@@ -140,8 +140,8 @@ const extractExif = async (
 // Dump every decrypted metadata layer the account holds into a directory tree
 // of plain JSON: account, per-collection, and per-file records including the
 // private and public magic metadata and (by default) the ML data. Collections
-// and files are enumerated from the library's cache rather than a fresh server
+// and files are enumerated from the library's cache, which the caller refreshes
-// scan. Returns how many ML data requests failed; their files are still
+// first. Returns how many ML data requests failed; their files are still
 // written, with `mlDataError` in place of `mlData`.
 export const runMetadataBackup = async (
     lib: Library,

test/cli/backup.test.ts

@@ -562,11 +562,39 @@ describe("lib.backup", () => {
         lib.close();
     });
 
-    it("fsyncs a copied original before the rename and its directory after", async () => {
+    it("fetches each original once and writes it only into the backup", async () => {
+        // A backup of a 500 GB account must write 500 GB, not a copy in the
+        // cache as well: an original fetched for the backup goes straight
+        // into its originals/, and the cache records it there.
+        const source = stubSource();
+        const lib = await openLibrary(source);
+        const outDir = join(root, "backup");
+
+        const result = await lib.backup({ downloadDirectory: outDir });
+
+        expect(result.downloaded).toBe(3);
+        expect(source.originalCalls).toBe(3);
+        expect(readdirSync(join(root, "cache", "originals"))).toEqual([]);
+        const stored = readdirSync(join(outDir, "originals")).filter(
+            (name) => !name.endsWith(".json"),
+        );
+        expect(stored.sort()).toEqual(["100.jpg", "101.jpg", "200.png"]);
+        // The cache counts the backup's copy as present: reading the
+        // original afterwards fetches nothing and answers with that copy.
+        const read = await lib.photos.byID({ fileID: 100 })!.original();
+        expect(read.path).toBe(join(outDir, "originals", "100.jpg"));
+        expect(source.originalCalls).toBe(3);
+        await lib.close();
+    });
+
+    it("fsyncs an original copied from the cache before the rename and its directory after", async () => {
         const lib = await openLibrary(stubSource());
         const outDir = join(root, "backup");
         const originals = join(outDir, "originals");
         const dest = join(originals, "100.jpg");
+        // Only an original already in the cache is copied into the backup;
+        // one fetched for the backup is written there by the download writer.
+        await lib.photos.byID({ fileID: 100 })!.original();
         fsEvents.length = 0;
 
         await lib.backup({ downloadDirectory: outDir });
@@ -625,6 +653,93 @@ describe("lib.backup", () => {
     });
 });
 
+// Every refresh fails, as with an expired session or no network.
+class FailingClient extends MockClient {
+    override async collectionsSince(): Promise<CollectionsPage> {
+        throw new Error("HTTP 401 from server");
+    }
+}
+
+// Holds its refresh open until `release()` is called, then reports a third
+// album, so a backup can be started while that refresh is still running.
+class HeldClient extends MockClient {
+    release!: () => void;
+    private held = new Promise<void>((resolve) => {
+        this.release = resolve;
+    });
+    override async collectionsSince(): Promise<CollectionsPage> {
+        await this.held;
+        return {
+            collections: [collection(3, "Later")],
+            deleted: [],
+            cursor: 2,
+        };
+    }
+    override async filesSince(args: {
+        collectionID: number;
+    }): Promise<FilesPage> {
+        if (args.collectionID !== 3) return super.filesSince(args);
+        return { files: [file(300, 3, "late.jpg")], deleted: [], cursor: 2 };
+    }
+}
+
+// Fill the library cache on disk, so the next open starts its refresh in the
+// background instead of waiting for it.
+const fillCache = async (): Promise<void> => {
+    const lib = await openLibrary(stubSource());
+    await lib.close();
+};
+
+describe("the refresh before a backup", () => {
+    it("waits for a refresh already running and backs up what it found", async () => {
+        await fillCache();
+        const client = new HeldClient();
+        const lib = await openLibrary(stubSource(), client);
+        const outDir = join(root, "backup");
+
+        const backup = lib.backup({ downloadDirectory: outDir });
+        client.release();
+        const result = await backup;
+
+        expect(result.totalFiles).toBe(4);
+        expect(existsSync(join(outDir, "originals", "300.jpg"))).toBe(true);
+        await lib.close();
+    });
+
+    it("fails before any download when the refresh fails, leaving failures.json as it was", async () => {
+        await fillCache();
+        const outDir = join(root, "backup");
+        seedLedger(outDir, 100, "beach.jpg");
+        const ledgerPath = join(outDir, "failures.json");
+        const ledgerBefore = readFileSync(ledgerPath, "utf-8");
+        const source = stubSource();
+        const lib = await openLibrary(source, new FailingClient());
+
+        await expect(lib.backup({ downloadDirectory: outDir })).rejects.toThrow(
+            "HTTP 401 from server",
+        );
+
+        expect(source.originalCalls).toBe(0);
+        expect(readFileSync(ledgerPath, "utf-8")).toBe(ledgerBefore);
+        expect(existsSync(join(outDir, "originals"))).toBe(false);
+        await lib.close();
+    });
+
+    it("fails when the refresh fails on an empty cache, instead of backing up nothing", async () => {
+        const source = stubSource();
+        const lib = await openLibrary(source, new FailingClient());
+        const outDir = join(root, "backup");
+
+        await expect(lib.backup({ downloadDirectory: outDir })).rejects.toThrow(
+            "HTTP 401 from server",
+        );
+
+        expect(source.originalCalls).toBe(0);
+        expect(existsSync(outDir)).toBe(false);
+        await lib.close();
+    });
+});
+
 // The album folders under collections/, driven through `runBackup` with a
 // stand-in library whose albums a test changes between runs.
 describe("backup album folders", () => {

test/cli/commands.test.ts

@@ -13,6 +13,7 @@
 import {
     existsSync,
     mkdtempSync,
+    readdirSync,
     readFileSync,
     rmSync,
     statSync,
@@ -20,11 +21,21 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { describe, it, expect, beforeAll, beforeEach, afterEach } from "vitest";
+import { PassThrough } from "node:stream";
+import {
+    describe,
+    it,
+    expect,
+    vi,
+    beforeAll,
+    beforeEach,
+    afterEach,
+} from "vitest";
 
 import {
     type CliContext,
     saveSession,
+    loginCommand,
     whoamiCommand,
     logoutCommand,
     collectionsCommand,
@@ -32,10 +43,13 @@ import {
     getCommand,
     getThumbCommand,
     backupCommand,
+    backupMetadataCommand,
     listMissingThumbnailsCommand,
+    fixMissingThumbnailsCommand,
 } from "../../src/cli-commands.js";
+import { run } from "../../src/cli-run.js";
 import { loadSession } from "../../src/cli-session.js";
-import type { Client, ClientSnapshot } from "../../src/client.js";
+import type { Client, ClientSnapshot, LoginOptions } from "../../src/client.js";
 import type { ContentSource } from "../../src/library/content.js";
 import type { Collection, EnteFile } from "../../src/model/types.js";
 import { init, toBase64 } from "../../src/crypto/index.js";
@@ -82,8 +96,26 @@ const FILES: Record<number, EnteFile[]> = {
 
 // An original is 7 bytes and a thumbnail 3. `failID` makes that file's
 // original fail; `emptyThumbID` makes the server report that file's
-// thumbnail as empty.
+// thumbnail as empty. `withNewFile` adds new.jpg (102) to Vacation, advancing
-const fakeClient = (opts: { failID?: number; emptyThumbID?: number } = {}) => {
+// the collection's updationTime as the server does, and `refreshError` makes
+// listing collections fail with that message.
+const fakeClient = (
+    opts: {
+        failID?: number;
+        emptyThumbID?: number;
+        withNewFile?: boolean;
+        refreshError?: string;
+    } = {},
+) => {
+    const collections = opts.withNewFile
+        ? [{ ...COLLECTIONS[0], updationTime: 2 }, COLLECTIONS[1]]
+        : COLLECTIONS;
+    const files = opts.withNewFile
+        ? {
+              ...FILES,
+              1: [...FILES[1], { ...file(102, 1, "new.jpg"), updationTime: 2 }],
+          }
+        : FILES;
     const source: ContentSource = {
         original: async ({ file: f, destination }) => {
             if (f.id === opts.failID) throw new Error("HTTP 500 from server");
@@ -97,18 +129,19 @@ const fakeClient = (opts: { failID?: number; emptyThumbID?: number } = {}) => {
     };
     const fake = {
         whoami: () => ({ email: "cli@example.com", userID: USER_ID }),
-        collectionsSince: async () => ({
+        collectionsSince: async () => {
-            collections: COLLECTIONS,
+            if (opts.refreshError) throw new Error(opts.refreshError);
-            deleted: [],
+            return { collections, deleted: [], cursor: 1 };
-            cursor: 1,
+        },
-        }),
         filesSince: async (args: { collectionID: number }) => ({
-            files: FILES[args.collectionID] ?? [],
+            files: files[args.collectionID] ?? [],
             deleted: [],
             cursor: 1,
         }),
         contentSource: () => source,
         getApiClient: () => ({
+            // The ML data request of `backup-metadata`: no file has any.
+            postJSON: async () => ({ data: [] }),
             getThumbnailStream: async (fileID: number) =>
                 new ReadableStream<Uint8Array>({
                     start(controller) {
@@ -142,6 +175,15 @@ const context = (client: Client | null = fakeClient()): CliContext => ({
     sessionDir: join(root, "session"),
     cacheDir: join(root, "cache"),
     loadSession: () => client,
+    login: async () => {
+        throw new Error("login not expected");
+    },
+    prompt: async () => {
+        throw new Error("prompt not expected");
+    },
+    promptSecret: async () => {
+        throw new Error("prompt not expected");
+    },
 });
 
 beforeAll(async () => {
@@ -199,6 +241,105 @@ describe("session file", () => {
     });
 });
 
+// The login function is a fake that hands back a client whose snapshot is
+// `snapshot`; each prompt is recorded and answered with "123456".
+describe("login", () => {
+    const snapshot: ClientSnapshot = {
+        email: "cli@example.com",
+        userID: USER_ID,
+        token: "token",
+        masterKey: "a",
+        secretKey: "b",
+        publicKey: "c",
+    };
+
+    const loggedIn = {
+        whoami: () => ({ email: "cli@example.com", userID: USER_ID }),
+        toJSON: () => snapshot,
+    } as unknown as Client;
+
+    let prompts: string[];
+
+    const loginContext = (
+        login: (opts: LoginOptions) => Promise<Client>,
+    ): CliContext => ({
+        ...context(),
+        login,
+        prompt: async (message) => {
+            prompts.push(message);
+            return "123456";
+        },
+        promptSecret: async (message) => {
+            prompts.push(message);
+            return "123456";
+        },
+    });
+
+    beforeEach(() => {
+        prompts = [];
+        vi.stubEnv("QUAK_EMAIL", "cli@example.com");
+        vi.stubEnv("QUAK_PASSWORD", "hunter2");
+    });
+
+    afterEach(() => {
+        vi.unstubAllEnvs();
+    });
+
+    it("takes the email and password from the environment without a prompt", async () => {
+        const calls: LoginOptions[] = [];
+        const ctx = loginContext(async (opts) => {
+            calls.push(opts);
+            return loggedIn;
+        });
+        expect(await loginCommand(ctx)).toBe(0);
+
+        expect(prompts).toEqual([]);
+        expect(calls).toHaveLength(1);
+        expect(calls[0]!.email).toBe("cli@example.com");
+        expect(calls[0]!.password).toBe("hunter2");
+        const path = join(ctx.sessionDir, "session.json");
+        expect(stderr.text).toBe(
+            "Authenticating...\n" +
+                `Logged in as cli@example.com (user ${USER_ID})\n` +
+                `Session saved to ${path}\n`,
+        );
+    });
+
+    it("saves the session with mode 0600 in a directory with mode 0700", async () => {
+        const ctx = loginContext(async () => loggedIn);
+        expect(await loginCommand(ctx)).toBe(0);
+
+        expect(statSync(ctx.sessionDir).mode & 0o777).toBe(0o700);
+        const path = join(ctx.sessionDir, "session.json");
+        expect(statSync(path).mode & 0o777).toBe(0o600);
+        expect(JSON.parse(readFileSync(path, "utf-8"))).toEqual(snapshot);
+    });
+
+    it("asks for the TOTP code when the account needs one", async () => {
+        let code: string | undefined;
+        const ctx = loginContext(async (opts) => {
+            code = await opts.totp!();
+            return loggedIn;
+        });
+        expect(await loginCommand(ctx)).toBe(0);
+
+        expect(prompts).toEqual(["TOTP code: "]);
+        expect(code).toBe("123456");
+    });
+
+    it("a failed login exits 1, says why and writes no session", async () => {
+        const ctx = loginContext(async () => {
+            throw new Error("HTTP 401 from server");
+        });
+        expect(await loginCommand(ctx)).toBe(1);
+
+        expect(stderr.text).toBe(
+            "Authenticating...\nLogin failed: HTTP 401 from server\n",
+        );
+        expect(existsSync(join(ctx.sessionDir, "session.json"))).toBe(false);
+    });
+});
+
 // These use a real client read from the session file, over a fake API that
 // records each request and answers with `status`.
 describe("logout", () => {
@@ -404,6 +545,16 @@ describe("backup", () => {
         expect(stdout.text).toBe("");
     });
 
+    // The backup opens its library with the precache off: it fetches the
+    // originals it needs into the backup, and must not also fetch every
+    // thumbnail in the account, or keep originals, in the per-user cache.
+    it("leaves nothing in the cache's originals and thumbnails", async () => {
+        const dir = join(root, "backup");
+        expect(await backupCommand(context(), dir, {})).toBe(0);
+        expect(readdirSync(join(root, "cache", "thumbnails"))).toEqual([]);
+        expect(readdirSync(join(root, "cache", "originals"))).toEqual([]);
+    });
+
     it("exits 1 and lists the file when one download fails", async () => {
         const ctx = context(fakeClient({ failID: 101 }));
         expect(await backupCommand(ctx, join(root, "backup"), {})).toBe(1);
@@ -430,6 +581,34 @@ describe("backup", () => {
         expect(result.errors[0].fileID).toBe(101);
         expect(stderr.text).toBe("Starting backup...\n");
     });
+
+    it("exits 1 with the error on one line when the refresh fails", async () => {
+        const client = {
+            ...fakeClient(),
+            collectionsSince: async () => {
+                throw new Error("HTTP 401 from server");
+            },
+        } as unknown as Client;
+        const dir = join(root, "backup");
+        // Through `run`, as `bin/quak.ts` does, which prints a thrown error.
+        const runStderr = new PassThrough();
+        let runText = "";
+        runStderr.on("data", (chunk: Buffer) => {
+            runText += chunk.toString();
+        });
+        const code = await new Promise<number>((resolve) => {
+            void run(
+                backupCommand(context(client), dir, {}),
+                new PassThrough(),
+                runStderr,
+                resolve,
+            );
+        });
+        expect(code).toBe(1);
+        expect(runText).toBe("quak: HTTP 401 from server\n");
+        expect(stderr.text).toBe("Starting backup...\nRefreshing library...\n");
+        expect(existsSync(join(dir, "originals"))).toBe(false);
+    });
 });
 
 describe("helper list-missing-thumbnails", () => {
@@ -462,3 +641,92 @@ describe("helper list-missing-thumbnails", () => {
         expect(stderr.text).toBe("");
     });
 });
+
+describe("backup-metadata --exif", () => {
+    // Runs the command and returns what it printed to stderr.
+    const backupMetadata = async (opts: { exif?: boolean; all?: boolean }) => {
+        expect(
+            await backupMetadataCommand(context(), join(root, "dump"), opts),
+        ).toBe(0);
+        return stderr.text;
+    };
+
+    it("--exif extracts EXIF", async () => {
+        expect(await backupMetadata({ exif: true })).toContain(
+            "[beach.jpg] Extracting EXIF...\n",
+        );
+    });
+
+    it("--all extracts EXIF", async () => {
+        expect(await backupMetadata({ all: true })).toContain(
+            "[beach.jpg] Extracting EXIF...\n",
+        );
+    });
+
+    it("without either flag extracts no EXIF", async () => {
+        expect(await backupMetadata({})).not.toContain("Extracting EXIF");
+    });
+});
+
+// Each test first runs `collections` so the cache holds the account as it was,
+// then changes the server under it.
+describe("backup-metadata and the thumbnail helpers refresh first", () => {
+    beforeEach(async () => {
+        expect(await collectionsCommand(context(), {})).toBe(0);
+        stdout.text = "";
+        stderr.text = "";
+    });
+
+    it("backup-metadata writes a file added since the cache was written", async () => {
+        const ctx = context(fakeClient({ withNewFile: true }));
+        const dir = join(root, "dump");
+        expect(await backupMetadataCommand(ctx, dir, {})).toBe(0);
+        expect(
+            existsSync(join(dir, "collections", "1-Vacation", "102.json")),
+        ).toBe(true);
+    });
+
+    it("list-missing-thumbnails checks a file added since the cache was written", async () => {
+        const ctx = context(
+            fakeClient({ withNewFile: true, emptyThumbID: 102 }),
+        );
+        expect(await listMissingThumbnailsCommand(ctx, {})).toBe(0);
+        expect(stdout.text).toBe(
+            "102\tnew.jpg\tVacation\tempty thumbnail (0 bytes)\n",
+        );
+    });
+
+    it("fix-missing-thumbnails finds a file added since the cache was written", async () => {
+        const ctx = context(fakeClient({ withNewFile: true }));
+        expect(
+            await fixMissingThumbnailsCommand(ctx, {
+                file: ["102"],
+                json: true,
+            }),
+        ).toBe(0);
+        // Found, then skipped because the server records no thumbnail size
+        // for it; a file missing from the cache would fail as not found.
+        expect(JSON.parse(stdout.text)).toMatchObject([
+            { fileID: 102, title: "new.jpg", status: "skipped" },
+        ]);
+    });
+
+    // `run` in `cli-run.ts` prints a thrown error as one line and exits 1.
+    it("all three throw when the refresh fails", async () => {
+        const ctx = context(
+            fakeClient({ refreshError: "HTTP 503 from server" }),
+        );
+        const dir = join(root, "dump");
+        await expect(backupMetadataCommand(ctx, dir, {})).rejects.toThrow(
+            "HTTP 503 from server",
+        );
+        expect(existsSync(dir)).toBe(false);
+        await expect(listMissingThumbnailsCommand(ctx, {})).rejects.toThrow(
+            "HTTP 503 from server",
+        );
+        await expect(
+            fixMissingThumbnailsCommand(ctx, { file: ["100"] }),
+        ).rejects.toThrow("HTTP 503 from server");
+        expect(stdout.text).toBe("");
+    });
+});

test/cli/run.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Tests for `run` in `src/cli-run.ts`, which every CLI command goes through.
+ */
+
+import { PassThrough } from "node:stream";
+import { describe, it, expect } from "vitest";
+
+import { run } from "../../src/cli-run.js";
+
+// A stream whose written text is kept in `text`; writes finish at once, so
+// nothing is left waiting to drain.
+const collector = (): { stream: PassThrough; text: () => string } => {
+    const stream = new PassThrough();
+    const chunks: string[] = [];
+    stream.on("data", (chunk: Buffer) => chunks.push(chunk.toString()));
+    return { stream, text: () => chunks.join("") };
+};
+
+const runToExit = async (
+    command: Promise<number>,
+): Promise<{ code: number; stdout: string; stderr: string }> => {
+    const stdout = collector();
+    const stderr = collector();
+    const code = await new Promise<number>((resolve) => {
+        void run(command, stdout.stream, stderr.stream, resolve);
+    });
+    return { code, stdout: stdout.text(), stderr: stderr.text() };
+};
+
+describe("run", () => {
+    it("exits with the code the command returns", async () => {
+        const result = await runToExit(Promise.resolve(3));
+        expect(result).toEqual({ code: 3, stdout: "", stderr: "" });
+    });
+
+    it("prints a thrown error as one line without a stack trace and exits 1", async () => {
+        const failing = async (): Promise<number> => {
+            throw new Error(
+                "ENOTDIR: not a directory, mkdir '/dev/null/x/originals'",
+            );
+        };
+        const result = await runToExit(failing());
+        expect(result.code).toBe(1);
+        expect(result.stdout).toBe("");
+        expect(result.stderr).toBe(
+            "quak: ENOTDIR: not a directory, mkdir '/dev/null/x/originals'\n",
+        );
+    });
+
+    it("prints a thrown value that is not an Error", async () => {
+        const result = await runToExit(Promise.reject("offline"));
+        expect(result).toEqual({
+            code: 1,
+            stdout: "",
+            stderr: "quak: offline\n",
+        });
+    });
+});