-v raises the CLI's log level per repeat; -q prints only fatal errors (closes #212)

Every line quak prints on stderr now goes through one log, in
src/cli-log.ts, at one of six levels. The default, info, prints what quak
printed before. -v adds each retry and the start and end of each refresh
and ML data fetch; -vv adds each request with its result. -q prints only
the line a failing command exits with, and is refused with -v. Both are
program options. withRetry reports retries through a new onRetry, and
ApiClient reports requests through a new onRequest; the CLI logs what
they report. --json now changes stdout only, so backup and --json runs
log their progress on stderr.

Model: opus-5-5

test/api/client.test.ts

@@ -1222,3 +1222,65 @@ describe("ApiClient non-idempotent requests", () => {
         }
     });
 });
+
+// `onRequest` hears of each request the client sends, as its response arrives
+// or as it fails. The CLI logs these with `-vv`. A retried request is reported
+// once for each attempt.
+describe("ApiClient onRequest", () => {
+    it("reports each request with its status, or with the error it failed with", async () => {
+        const refused = new TypeError("fetch failed");
+        const { fetch } = scriptedFetch(
+            refused,
+            textResponse("unavailable", 503),
+            jsonResponse({ collections: [] }),
+            jsonResponse({}),
+            streamResponse(new Uint8Array([1, 2, 3])),
+        );
+        const requests: unknown[] = [];
+        const client = new ApiClient({
+            fetch,
+            retry: noWait,
+            onRequest: (request) => requests.push(request),
+        });
+
+        await client.getJSON("/collections/v2", { sinceTime: 0 });
+        await client.postJSON("/users/logout", {});
+        await readAll(await client.getFileStream(7));
+
+        const collections = "https://api.ente.io/collections/v2?sinceTime=0";
+        expect(requests).toEqual([
+            { method: "GET", url: collections, error: refused },
+            { method: "GET", url: collections, status: 503 },
+            { method: "GET", url: collections, status: 200 },
+            {
+                method: "POST",
+                url: "https://api.ente.io/users/logout",
+                status: 200,
+            },
+            {
+                method: "GET",
+                url: "https://files.ente.io/?fileID=7",
+                status: 200,
+            },
+        ]);
+    });
+
+    it("reports a presigned upload without its query, which holds the upload's signature", async () => {
+        const { fetch } = scriptedFetch(new Response(null, { status: 200 }));
+        const requests: unknown[] = [];
+        const client = new ApiClient({
+            fetch,
+            retry: noWait,
+            onRequest: (request) => requests.push(request),
+        });
+
+        await client.putFile(
+            "https://s3.example/obj?X-Amz-Signature=abc",
+            new Uint8Array([1, 2]),
+        );
+
+        expect(requests).toEqual([
+            { method: "PUT", url: "https://s3.example/obj", status: 200 },
+        ]);
+    });
+});

test/cli/backup-end-to-end.test.ts

@@ -54,6 +54,7 @@ import {
     saveSession,
     type CliContext,
 } from "../../src/cli-commands.js";
+import { stderrLog } from "../../src/cli-log.js";
 import { run } from "../../src/cli-run.js";
 import { loadSession } from "../../src/cli-session.js";
 import { Client } from "../../src/client.js";
@@ -303,9 +304,10 @@ const backup = async (
     const prompted = async (): Promise<never> => {
         throw new Error("quak backup prompted");
     };
+    const log = stderrLog(stderr, "info");
     const ctx: CliContext = {
         stdout,
-        stderr,
+        log,
         sessionDir,
         cacheDir: `${dir}-cache`,
         loadSession: (path) =>
@@ -319,7 +321,7 @@ const backup = async (
         promptSecret: prompted,
     };
     const code = await new Promise<number>((resolve) => {
-        void run(backupCommand(ctx, dir, opts), stdout, stderr, resolve);
+        void run(backupCommand(ctx, dir, opts), stdout, stderr, log, resolve);
     });
     return { code, stderr: printed, stdout: output };
 };
@@ -1104,6 +1106,9 @@ describe("a backup whose lock is lost", () => {
         expect(code).toBe(1);
         expect(stderr).toBe(
             "Starting backup...\n" +
+                "Fetched the files of 1 of 3 collections\n" +
+                "Fetched the files of 2 of 3 collections\n" +
+                "Fetched the files of 3 of 3 collections\n" +
                 "Refreshing library...\n" +
                 "Fetching original beach.jpg (100)...\n" +
                 "Fetching original IMG_0002.HEIC (300)...\n" +

test/cli/backup-undecryptable.test.ts

@@ -42,6 +42,7 @@ import {
     saveSession,
     type CliContext,
 } from "../../src/cli-commands.js";
+import { stderrLog } from "../../src/cli-log.js";
 import { loadSession } from "../../src/cli-session.js";
 import { Client, type ClientSnapshot } from "../../src/client.js";
 import { encryptBlob, init, toBase64 } from "../../src/crypto/index.js";
@@ -304,7 +305,7 @@ const context = (ente: FakeEnte): CliContext => {
     saveSession(join(root, "session"), ente.snapshot());
     return {
         stdout,
-        stderr,
+        log: stderrLog(stderr, "info"),
         sessionDir: join(root, "session"),
         cacheDir: join(root, "cache"),
         loadSession: (path) =>

test/cli/bin.test.ts

@@ -1,7 +1,8 @@
 /**
  * Tests for the retry options `bin/quak.ts` loads the saved session with
  * (`quak backup` gets the unattended ones, every other command the default),
- * and for `quak files` taking its collection ID as an optional argument.
+ * each with the callbacks that log its requests and retries, and for
+ * `quak files` taking its collection ID as an optional argument.
  *
  * Each test runs `bin/quak.ts`, as the smoke test does, with its session loader
  * replaced by one that records the options it is given and reports no session,
@@ -65,14 +66,21 @@ describe("bin/quak.ts session loading", () => {
                     attempts,
                     baseDelayMs,
                     maxDelayMs,
+                    onRetry: expect.any(Function),
                 }),
+                onRequest: expect.any(Function),
             },
         ]);
     });
 
-    it("loads the session for another command with the default options", async () => {
+    it("loads the session for another command with the default retry options", async () => {
         await quak("collections");
-        expect(loaded).toEqual([undefined]);
+        expect(loaded).toEqual([
+            {
+                retry: { onRetry: expect.any(Function) },
+                onRequest: expect.any(Function),
+            },
+        ]);
     });
 });
 

test/cli/commands.test.ts

@@ -51,6 +51,7 @@ import {
     listMissingThumbnailsCommand,
     fixMissingThumbnailsCommand,
 } from "../../src/cli-commands.js";
+import { stderrLog } from "../../src/cli-log.js";
 import { run } from "../../src/cli-run.js";
 import { loadSession } from "../../src/cli-session.js";
 import {
@@ -208,9 +209,11 @@ let root: string;
 let stdout: Output;
 let stderr: Output;
 
+// The commands log at the default level, info, as `quak` without `-v` or `-q`
+// does; the levels have their own tests, in `log.test.ts`.
 const context = (client: Client | null = fakeClient()): CliContext => ({
     stdout,
-    stderr,
+    log: stderrLog(stderr, "info"),
     sessionDir: join(root, "session"),
     cacheDir: join(root, "cache"),
     loadSession: () => client,
@@ -566,7 +569,7 @@ describe("files", () => {
             [101, 1],
             [200, 2],
         ]);
-        expect(stderr.text).toBe("");
+        expect(stderr.text).toBe(FETCHED_BOTH_ALBUMS);
     });
 });
 
@@ -910,6 +913,8 @@ describe("backup", () => {
         );
     });
 
+    // `--json` shapes stdout only: the log lines stay on stderr, and the JSON
+    // takes the place of the summary.
     it("prints the result as JSON with --json, still exiting 1 on a failure", async () => {
         const ctx = context(fakeClient({ failID: 101 }));
         const code = await backupCommand(ctx, join(root, "backup"), {
@@ -924,7 +929,31 @@ describe("backup", () => {
             failed: 1,
         });
         expect(result.errors[0].fileID).toBe(101);
-        expect(stderr.text).toBe("Starting backup...\n");
+        expect(stderr.text).toContain(
+            "Fetching original sunset.jpg (101)...\n",
+        );
+        expect(stderr.text).not.toContain("Backup complete");
+    });
+
+    // On an empty cache the library's first refresh fetches the files of
+    // every album before the backup can start, which on a large account takes
+    // a while; each album it has fetched the files of is counted on stderr,
+    // with `--json` too.
+    it("counts on stderr each album whose files its first refresh fetched, with --json too", async () => {
+        const start =
+            "Starting backup...\n" +
+            FETCHED_BOTH_ALBUMS +
+            "Refreshing library...\n";
+        for (const json of [false, true]) {
+            stderr.text = "";
+            const dir = mkdtempSync(join(root, "backup-"));
+            const ctx = {
+                ...context(),
+                cacheDir: mkdtempSync(join(root, "cache-")),
+            };
+            expect(await backupCommand(ctx, dir, { json })).toBe(0);
+            expect(stderr.text.slice(0, start.length)).toBe(start);
+        }
     });
 
     it("--verify downloads again an original that does not match its hash, prints the counts, and exits 0", async () => {
@@ -1014,6 +1043,7 @@ describe("backup", () => {
                 backupCommand(ctx, dir, {}),
                 new PassThrough(),
                 runStderr,
+                stderrLog(runStderr, "info"),
                 resolve,
             );
         });
@@ -1254,7 +1284,9 @@ describe("helper list-missing-thumbnails", () => {
         expect(stderr.text).toContain("No missing thumbnails found.\n");
     });
 
-    it("prints a JSON array with --json and no progress", async () => {
+    // `--json` shapes stdout only: the progress stays on stderr, and the JSON
+    // takes the place of the count and the list.
+    it("prints a JSON array with --json, and its progress on stderr", async () => {
         const ctx = context(fakeClient({ emptyThumbID: 200 }));
         expect(await listMissingThumbnailsCommand(ctx, { json: true })).toBe(0);
         expect(JSON.parse(stdout.text)).toEqual([
@@ -1265,7 +1297,9 @@ describe("helper list-missing-thumbnails", () => {
                 reason: "empty thumbnail (0 bytes)",
             },
         ]);
-        expect(stderr.text).toBe("");
+        expect(stderr.text).toContain(FETCHED_BOTH_ALBUMS);
+        expect(stderr.text).toContain("[Work] Checking thumbnails...\n");
+        expect(stderr.text).not.toContain("with missing thumbnails");
     });
 });
 
@@ -1624,9 +1658,9 @@ describe("an account with many albums", () => {
         expect(stderr.text).toBe(progress);
     });
 
-    // With `--json` the refresh's progress is not printed, as `backup` and
-    // the thumbnail helpers print none of theirs.
-    it("files --json prints no progress", async () => {
+    // `--json` shapes stdout only, so the refresh's progress is still counted
+    // on stderr.
+    it("files --json counts on stderr each album whose files its refresh fetched", async () => {
         expect(await filesCommand(accountContext(), "7", { json: true })).toBe(
             0,
         );
@@ -1640,6 +1674,10 @@ describe("an account with many albums", () => {
                 collectionID: 7,
             },
         ]);
-        expect(stderr.text).toBe("");
+        let progress = "";
+        for (let n = 1; n <= ALBUMS; n++) {
+            progress += `Fetched the files of ${n} of ${ALBUMS} collections\n`;
+        }
+        expect(stderr.text).toBe(progress);
     });
 });

test/cli/log.test.ts

@@ -0,0 +1,354 @@
+/**
+ * Tests for the CLI's log levels, set with `-v`/`--verbose` and `-q`/`--quiet`
+ * (`src/cli-log.ts`, issue #212).
+ *
+ * Every line quak prints on stderr is a log line at one of six levels, from
+ * the quietest: fatal, error, warning, info, debug, trace. A run prints the
+ * lines at its own level and at every quieter one. The level is info unless
+ * asked otherwise: `-v` raises it to debug, `-vv` to trace, and more repeats
+ * stay at trace. `-q` lowers it to fatal, so a run prints only the line a
+ * command prints as it fails with a non-zero exit code. stdout holds the
+ * command's output at every level.
+ *
+ * Most tests run `bin/quak.ts`, as the smoke test does, against an account of
+ * one album holding one photo: the saved session is in a temporary directory,
+ * and `fetch` is a fake of the Ente server that serves the album and the photo
+ * encrypted as Ente's clients encrypt them. Each run has a cache directory of
+ * its own, so its refresh fetches the album's files, as on a first run.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import sodium from "libsodium-wrappers-sumo";
+import {
+    afterAll,
+    afterEach,
+    beforeAll,
+    describe,
+    expect,
+    it,
+    vi,
+} from "vitest";
+
+import { ApiClient } from "../../src/api/client.js";
+import { saveSession } from "../../src/cli-commands.js";
+import { logRefresh, logRequests, type Log } from "../../src/cli-log.js";
+import { init, toBase64 } from "../../src/crypto/index.js";
+import { encryptSecretbox, encryptStreamBlob } from "../ente-server.js";
+
+// `bin/quak.ts` reads the saved session from the data directory env-paths
+// gives it, which here is a temporary directory made before the first run.
+const paths = vi.hoisted(() => ({ data: "" }));
+vi.mock("env-paths", () => ({ default: () => paths }));
+
+const USER_ID = 42;
+const root = mkdtempSync(join(tmpdir(), "quak-log-test-"));
+const argv = process.argv;
+
+class ExitCalled extends Error {}
+
+// Run `quak <args>` to its exit, with a cache of its own, and return its exit
+// code and what it wrote on stdout and on stderr, which are kept off the
+// terminal. `process.exit` is stubbed to throw, so nothing runs after it, as
+// nothing does after a real exit.
+const quak = async (
+    ...args: string[]
+): Promise<{ code: number; stdout: string; stderr: string }> => {
+    let stdout = "";
+    let stderr = "";
+    let code = NaN;
+    vi.spyOn(process.stdout, "write").mockImplementation((text) => {
+        stdout += String(text);
+        return true;
+    });
+    vi.spyOn(process.stderr, "write").mockImplementation((text) => {
+        stderr += String(text);
+        return true;
+    });
+    vi.spyOn(process, "exit").mockImplementation((exitCode) => {
+        code = Number(exitCode ?? 0);
+        throw new ExitCalled();
+    });
+    const cache = mkdtempSync(join(root, "cache-"));
+    process.argv = ["node", "quak", "--cache-dir", cache, ...args];
+    vi.resetModules();
+    await expect(import("../../bin/quak.js")).rejects.toBeInstanceOf(
+        ExitCalled,
+    );
+    return { code, stdout, stderr };
+};
+
+// Album 1, "Trips", of user 42, holding photo 100, "beach.jpg". The album's
+// key is encrypted with the account's master key, the photo's key with the
+// album's, and the photo's metadata with its own key. Only the session and
+// these two records are needed: the tests never log in.
+beforeAll(async () => {
+    await init();
+    await sodium.ready;
+    const masterKey = sodium.crypto_secretbox_keygen();
+    const keyPair = sodium.crypto_box_keypair();
+    paths.data = join(root, "session");
+    saveSession(paths.data, {
+        email: "log@example.com",
+        userID: USER_ID,
+        token: "token",
+        masterKey: toBase64(masterKey),
+        secretKey: toBase64(keyPair.privateKey),
+        publicKey: toBase64(keyPair.publicKey),
+    });
+
+    const albumKey = sodium.crypto_secretbox_keygen();
+    const albumKeyBox = encryptSecretbox(albumKey, masterKey);
+    const name = encryptSecretbox(new TextEncoder().encode("Trips"), albumKey);
+    const album = {
+        id: 1,
+        owner: { id: USER_ID },
+        encryptedKey: toBase64(albumKeyBox.ciphertext),
+        keyDecryptionNonce: toBase64(albumKeyBox.nonce),
+        encryptedName: toBase64(name.ciphertext),
+        nameDecryptionNonce: toBase64(name.nonce),
+        type: "album",
+        updationTime: 1,
+    };
+    const photoKey = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+    const photoKeyBox = encryptSecretbox(photoKey, albumKey);
+    const metadata = encryptStreamBlob(
+        new TextEncoder().encode(
+            JSON.stringify({
+                title: "beach.jpg",
+                fileType: 0,
+                creationTime: 1000,
+                modificationTime: 1000,
+            }),
+        ),
+        photoKey,
+    );
+    const photo = {
+        id: 100,
+        collectionID: 1,
+        ownerID: USER_ID,
+        encryptedKey: toBase64(photoKeyBox.ciphertext),
+        keyDecryptionNonce: toBase64(photoKeyBox.nonce),
+        metadata: {
+            encryptedData: toBase64(metadata.ciphertext),
+            decryptionHeader: toBase64(metadata.header),
+        },
+        // These tests fetch no original and no thumbnail.
+        file: { decryptionHeader: "" },
+        thumbnail: { decryptionHeader: "" },
+        updationTime: 1,
+    };
+
+    const json = (body: unknown): Response =>
+        new Response(JSON.stringify(body), {
+            headers: { "content-type": "application/json" },
+        });
+    vi.stubGlobal("fetch", async (input: string) => {
+        const { pathname } = new URL(input);
+        if (pathname === "/collections/v2") {
+            return json({ collections: [album] });
+        }
+        if (pathname === "/collections/v2/diff") {
+            return json({ diff: [photo], hasMore: false });
+        }
+        return new Response("not found", { status: 404 });
+    });
+});
+
+afterEach(() => {
+    process.argv = argv;
+    vi.restoreAllMocks();
+});
+
+afterAll(() => {
+    vi.unstubAllGlobals();
+    rmSync(root, { recursive: true, force: true });
+});
+
+// What `quak files` writes on stdout at every level.
+const FILES = "100\timage\tbeach.jpg\n";
+
+// What it writes on stderr at each level. Info is the refresh's progress, one
+// line for the one album whose files it fetched. Debug adds the start and end
+// of the refresh, and trace each request with the status of its answer.
+const INFO = "Fetched the files of 1 of 1 collections\n";
+const DEBUG = "refresh started\n" + INFO + "refresh done\n";
+const TRACE =
+    "refresh started\n" +
+    "GET https://api.ente.io/collections/v2?sinceTime=0: HTTP 200\n" +
+    "GET https://api.ente.io/collections/v2/diff?collectionID=1&sinceTime=0: HTTP 200\n" +
+    INFO +
+    "refresh done\n";
+
+describe("the log level", () => {
+    it("is info by default", async () => {
+        expect(await quak("files")).toEqual({
+            code: 0,
+            stdout: FILES,
+            stderr: INFO,
+        });
+    });
+
+    it("is debug with -v", async () => {
+        expect(await quak("-v", "files")).toEqual({
+            code: 0,
+            stdout: FILES,
+            stderr: DEBUG,
+        });
+    });
+
+    it("is trace with -vv", async () => {
+        expect(await quak("-vv", "files")).toEqual({
+            code: 0,
+            stdout: FILES,
+            stderr: TRACE,
+        });
+    });
+
+    it("stays at trace with -vvv", async () => {
+        expect((await quak("-vvv", "files")).stderr).toBe(TRACE);
+    });
+
+    it("counts --verbose --verbose as -vv", async () => {
+        expect((await quak("--verbose", "--verbose", "files")).stderr).toBe(
+            TRACE,
+        );
+    });
+
+    // Both are options of the program, taken before or after the command's
+    // name, as `--cache-dir` is.
+    it("is set by an option after the command's name too", async () => {
+        expect((await quak("files", "-v")).stderr).toBe(DEBUG);
+        expect((await quak("files", "--json", "-vv")).stderr).toBe(TRACE);
+        expect((await quak("files", "-q")).stderr).toBe("");
+    });
+});
+
+describe("-q", () => {
+    it("prints nothing on stderr when the command works", async () => {
+        expect(await quak("-q", "files")).toEqual({
+            code: 0,
+            stdout: FILES,
+            stderr: "",
+        });
+    });
+
+    // The refresh's progress is left out; the line saying why the command
+    // failed is the fatal one, and it is printed.
+    it("prints only the line a failing command exits with", async () => {
+        expect(await quak("-q", "files", "9")).toEqual({
+            code: 1,
+            stdout: "",
+            stderr: "Collection 9 not found\n",
+        });
+    });
+
+    it("is refused with -v, in one line, before the command runs", async () => {
+        for (const args of [
+            ["-q", "-v", "files"],
+            ["files", "--verbose", "--quiet"],
+        ]) {
+            const { code, stdout, stderr } = await quak(...args);
+            expect(code).toBe(1);
+            expect(stdout).toBe("");
+            expect(stderr).toBe(
+                "error: option '-q, --quiet' cannot be used with option '-v, --verbose'\n",
+            );
+        }
+    });
+});
+
+// `--help` lists both options, and each command's help lists them too, since
+// each command takes them.
+describe("--help", () => {
+    it("lists -v and -q for the program and for each command", async () => {
+        for (const args of [["--help"], ["files", "--help"]]) {
+            const { stdout } = await quak(...args);
+            expect(stdout).toContain("-v, --verbose");
+            expect(stdout).toContain("-q, --quiet");
+        }
+    });
+});
+
+// The library writes no lines itself. Its layers report through callbacks,
+// and the CLI logs what they report.
+describe("what the library reports", () => {
+    const collect = (): { log: Log; lines: string[] } => {
+        const lines: string[] = [];
+        return { log: (level, line) => lines.push(`${level}: ${line}`), lines };
+    };
+
+    // A request answered 503 and retried: each attempt is a request, logged
+    // at trace with its status, and the retry is logged at debug with how
+    // long it waits and why.
+    it("logs each request at trace and each retry at debug", async () => {
+        const { log, lines } = collect();
+        const answers = [
+            new Response("unavailable", { status: 503 }),
+            new Response("{}", {
+                headers: { "content-type": "application/json" },
+            }),
+        ];
+        const client = new ApiClient({
+            ...logRequests(log, {
+                sleep: async () => {},
+                random: () => 0.5,
+            }),
+            fetch: async () => answers.shift()!,
+        });
+
+        await client.getJSON("/collections/v2", { sinceTime: 0 });
+
+        const url = "https://api.ente.io/collections/v2?sinceTime=0";
+        expect(lines).toEqual([
+            `trace: GET ${url}: HTTP 503`,
+            "debug: Attempt 1 failed, retrying in 250 ms: HTTP 503",
+            `trace: GET ${url}: HTTP 200`,
+        ]);
+    });
+
+    it("logs a request that failed with its error", async () => {
+        const { log, lines } = collect();
+        const client = new ApiClient({
+            ...logRequests(log, { attempts: 1 }),
+            fetch: async () => {
+                throw new TypeError("fetch failed", {
+                    cause: new Error("connect ECONNREFUSED 1.2.3.4:443"),
+                });
+            },
+        });
+
+        await expect(client.getJSON("/collections/v2")).rejects.toThrow();
+
+        expect(lines).toEqual([
+            "trace: GET https://api.ente.io/collections/v2: fetch failed: connect ECONNREFUSED 1.2.3.4:443",
+        ]);
+    });
+
+    it("logs a refresh's progress at info, and its start and end at debug", () => {
+        const { log, lines } = collect();
+        const onProgress = logRefresh(log);
+
+        onProgress({ operation: "refresh", status: "started" });
+        onProgress({
+            operation: "refresh",
+            status: "progress",
+            fetched: 1,
+            total: 2,
+        });
+        onProgress({
+            operation: "refresh",
+            status: "failed",
+            error: "HTTP 503",
+        });
+        onProgress({ operation: "fetchMLData", status: "done", fetched: 3 });
+
+        expect(lines).toEqual([
+            "debug: refresh started",
+            "info: Fetched the files of 1 of 2 collections",
+            "debug: refresh failed: HTTP 503",
+            "debug: fetchMLData done",
+        ]);
+    });
+});

test/cli/metadata-backup.test.ts

@@ -47,6 +47,7 @@ import {
     type MetadataBackupOptions,
 } from "../../src/metadata-backup.js";
 import { backupMetadataCommand } from "../../src/cli-commands.js";
+import { stderrLog } from "../../src/cli-log.js";
 import {
     buildAccount,
     buildMetaFetch,
@@ -506,7 +507,10 @@ describe("quak backup-metadata when a file's ML data cannot be read", () => {
         const code = await backupMetadataCommand(
             {
                 stdout: { write: () => true },
-                stderr: { write: (text: string) => (stderr += text) },
+                log: stderrLog(
+                    { write: (text: string) => (stderr += text) },
+                    "info",
+                ),
                 sessionDir: testDir,
                 cacheDir: mkdtempSync(join(testDir, "cache-")),
                 loadSession: () => client,

test/cli/run.test.ts

@@ -6,6 +6,7 @@ import { PassThrough } from "node:stream";
 import { describe, it, expect } from "vitest";
 
 import { ApiError } from "../../src/api/client.js";
+import { stderrLog } from "../../src/cli-log.js";
 import { run } from "../../src/cli-run.js";
 
 // A stream whose written text is kept in `text`; writes finish at once, so
@@ -23,7 +24,13 @@ const runToExit = async (
     const stdout = collector();
     const stderr = collector();
     const code = await new Promise<number>((resolve) => {
-        void run(command, stdout.stream, stderr.stream, resolve);
+        void run(
+            command,
+            stdout.stream,
+            stderr.stream,
+            stderrLog(stderr.stream, "info"),
+            resolve,
+        );
     });
     return { code, stdout: stdout.text(), stderr: stderr.text() };
 };

test/retry/retry.test.ts

@@ -555,6 +555,36 @@ describe("withRetry", () => {
         expect(delays).toHaveLength(2);
     });
 
+    it("tells `onRetry` of each attempt it retries, before the wait", async () => {
+        // A caller that logs retries, as the CLI does with `-v`, learns why
+        // each attempt failed and how long the next one is put off. The last
+        // attempt is not retried, so it is not reported.
+        const { sleep, delays } = recordingSleep();
+        const retries: [string, number, number][] = [];
+        let calls = 0;
+        const failure = withRetry(
+            () => {
+                calls++;
+                return Promise.reject(new ApiError(`attempt ${calls}`, 503));
+            },
+            {
+                attempts: 3,
+                sleep,
+                random: () => 0.5,
+                onRetry: (err, attempt, delayMs) => {
+                    retries.push([(err as Error).message, attempt, delayMs]);
+                },
+            },
+        );
+
+        await expect(failure).rejects.toThrow("attempt 3");
+        expect(retries).toEqual([
+            ["attempt 1", 1, 250],
+            ["attempt 2", 2, 500],
+        ]);
+        expect(delays).toEqual([250, 500]);
+    });
+
     it("does not retry at all when attempts is 1", async () => {
         const { sleep, delays } = recordingSleep();
         let calls = 0;
@@ -708,6 +738,7 @@ describe("retry defaults", () => {
         expect(resolved.maxDelayMs).toBe(DEFAULT_RETRY_OPTIONS.maxDelayMs);
         expect(typeof resolved.sleep).toBe("function");
         expect(typeof resolved.random).toBe("function");
+        expect(typeof resolved.onRetry).toBe("function");
     });
 
     it("resolves to the defaults when given nothing", () => {