@coderook/cli 0.22.1 → 0.22.2

package/dist/cli/src/cli.js

@@ -265,7 +265,18 @@ async function commandProjects() {
 }
 async function commandStatus(parsed) {
     const folder = folderFor(parsed);
-    const { link, baseline } = await reconcile(folder);
+    let link;
+    let baseline;
+    try {
+        ({ link, baseline } = await reconcile(folder));
+    }
+    catch (error) {
+        link = await (0, config_js_1.readLink)(folder);
+        if (!link?.manifest)
+            throw error;
+        baseline = new Map(Object.entries(link.local ?? link.manifest));
+        console.log(dim("Offline — comparing with the last Version cached for this folder."));
+    }
     const rules = await (0, worktree_js_1.readRules)(folder);
     const files = await (0, worktree_js_1.changedFiles)(folder, rules, baseline);
     console.log(bold(node_path_1.default.basename(folder)) + dim(`  ${folder}`));
@@ -463,12 +474,6 @@ Pass ${accent("--allow-secrets")} if these are not real keys.`);
         }
         console.log(dim("Sending them anyway, because --allow-secrets was given."));
     }
-    if (hasFlag(parsed, "dry-run", "n")) {
-        console.log(`${files.length} file${files.length === 1 ? "" : "s"} would be sent:`);
-        for (const file of files)
-            console.log(`  ${file.path}`);
-        return 0;
-    }
     if (added) {
         console.log(`${accent("Added an MIT licence")}, so other people may use this.`);
         console.log(dim(`  Change it with `) +
@@ -480,42 +485,46 @@ Pass ${accent("--allow-secrets")} if these are not real keys.`);
     }
     const line = progressLine();
     const uploader = new upload_js_1.Uploader(config_js_1.credentials);
+    const uploadRequest = {
+        localPath: folder,
+        include: files.map((file) => file.path),
+        deletions: files.filter((file) => file.deleted).map((file) => file.path),
+        message,
+        projectName: link?.slug ?? node_path_1.default.basename(folder),
+        repositoryId: link?.repositoryId ?? null,
+        // Every current CLI publish states its ancestry. A brand-new project is
+        // explicitly based on an empty Track; a linked folder names the immutable
+        // Version it was last reconciled with.
+        baseVersionId: link?.baseVersionId ?? null,
+        track: flagText(parsed, "track") ?? (await (0, track_commands_js_1.trackFor)(folder)),
+        ...(link?.baseVersionId
+            ? { expectedHeadVersionId: link.baseVersionId }
+            : {}),
+        ...(link ? { known: link.local ?? link.manifest ?? {} } : {}),
+    };
     let result;
     try {
-        result = await uploader.run({
-            localPath: folder,
-            include: files.map((file) => file.path),
-            deletions: files.filter((file) => file.deleted).map((file) => file.path),
-            message,
-            projectName: link?.slug ?? node_path_1.default.basename(folder),
-            repositoryId: link?.repositoryId ?? null,
-            // Every current CLI publish states its ancestry. A brand-new project
-            // is explicitly based on an empty Track; a linked folder names the
-            // immutable Version it was last reconciled with.
-            baseVersionId: link?.baseVersionId ?? null,
-            /*
-              The line this save belongs on: named on the command, or whichever one
-              the folder is set to. Sent by name rather than resolved here, because
-              the service owns the rules about which names exist and which may be
-              written to — a rule enforced in two places is one that will disagree
-              with itself.
-            */
-            track: flagText(parsed, "track") ?? (await (0, track_commands_js_1.trackFor)(folder)),
-            /*
-              Only claimed when this folder has actually been reconciled with a
-              known version. A folder linked before versions were recorded says
-              nothing rather than guessing, and publishes as it always did.
-            */
-            ...(link?.baseVersionId
-                ? { expectedHeadVersionId: link.baseVersionId }
-                : {}),
-            /*
-              What this folder believed the project held. It is how the service
-              tells a file this person deleted from one they never had, and
-              without it somebody else's work disappears at the next save.
-            */
-            ...(link ? { known: link.local ?? link.manifest ?? {} } : {}),
-        }, (progress) => {
+        const plan = await uploader.plan(uploadRequest, (progress) => {
+            line(`  ${track(progress.percent)} ${String(progress.percent).padStart(3)}%  ` +
+                `${"plan".padEnd(7)} ${progress.files}/${progress.totalFiles}  ` +
+                dim(progress.path.slice(-40)));
+        });
+        done(line);
+        console.log(`${accent("Upload plan")}  ${bytes(plan.sourceBytes)} selected → ` +
+            `${bytes(plan.compactedBytes)} compacted; ${bytes(plan.chargeableBytes)} new storage.`);
+        console.log(plan.allowance.exempt
+            ? dim("Annual plan: the monthly staged upload allowance does not apply.")
+            : dim(`Monthly stage ${plan.allowance.stage}: ${plan.allowance.unlockedPercent}% unlocked, ` +
+                `${bytes(plan.allowance.remainingBytes)} remains after this reservation.`));
+        if (hasFlag(parsed, "dry-run", "n")) {
+            await uploader.cancelPlan(plan, true);
+            console.log(`${files.length} file${files.length === 1 ? "" : "s"} would be sent or reused:`);
+            for (const file of files)
+                console.log(`  ${file.path}`);
+            console.log("Nothing was uploaded and no Version was created.");
+            return 0;
+        }
+        result = await uploader.execute(uploadRequest, plan, (progress) => {
             line(`  ${track(progress.percent)} ${String(progress.percent).padStart(3)}%  ` +
                 `${progress.stage.padEnd(7)} ${progress.files}/${progress.totalFiles}  ` +
                 dim(progress.path.slice(-40)));

package/dist/cli/src/offline.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queueOfflineCandidate = queueOfflineCandidate;
+exports.readOfflineCandidate = readOfflineCandidate;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+async function queueOfflineCandidate(folder, candidate) {
+    const directory = node_path_1.default.join(folder, ".coderook", "outbox");
+    await (0, promises_1.mkdir)(directory, { recursive: true });
+    const body = {
+        format: "coderook-offline-candidate-v1",
+        createdAt: new Date().toISOString(),
+        ...candidate,
+    };
+    const name = `${Date.now()}-${crypto.randomUUID()}.json`;
+    const destination = node_path_1.default.join(directory, name);
+    await (0, promises_1.writeFile)(destination, JSON.stringify(body, null, 2), { encoding: "utf8", mode: 0o600 });
+    return destination;
+}
+async function readOfflineCandidate(file) {
+    const value = JSON.parse(await (0, promises_1.readFile)(file, "utf8"));
+    if (value.format !== "coderook-offline-candidate-v1")
+        throw new Error("Unsupported offline candidate");
+    return value;
+}

package/dist/desktop-app/src/main/compress.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.looksCompressed = looksCompressed;
+exports.looksCompressed = void 0;
 exports.encodeForUpload = encodeForUpload;
 /**
  * Compressing an object before it is sent.
@@ -29,6 +29,9 @@ exports.encodeForUpload = encodeForUpload;
 const node_crypto_1 = require("node:crypto");
 const node_zlib_1 = require("node:zlib");
 const node_util_1 = require("node:util");
+const compression_policy_1 = require("../shared/compression_policy");
+var compression_policy_2 = require("../shared/compression_policy");
+Object.defineProperty(exports, "looksCompressed", { enumerable: true, get: function () { return compression_policy_2.looksCompressed; } });
 const deflate = (0, node_util_1.promisify)(node_zlib_1.gzip);
 /*
   Extensions whose contents are already compressed. Matching on the name is a
@@ -36,30 +39,6 @@ const deflate = (0, node_util_1.promisify)(node_zlib_1.gzip);
   is measured rather than guessed, so a wrong entry here costs a little time
   and never a wrong result.
 */
-const ALREADY_COMPRESSED = new Set([
-    ".7z", ".aac", ".avi", ".br", ".bz2", ".cbx", ".docx", ".flac", ".gif",
-    ".gz", ".heic", ".jpeg", ".jpg", ".jxl", ".m4a", ".m4v", ".mkv", ".mov",
-    ".mp3", ".mp4", ".odp", ".ods", ".odt", ".ogg", ".opus", ".pdf", ".png",
-    ".pptx", ".rar", ".safetensors", ".webm", ".webp", ".xlsx", ".xz", ".zip",
-    ".zst",
-]);
-/**
- * Below this, compression is not worth the round trip through zlib — the
- * saving is measured in bytes and every file pays the CPU.
- */
-const SMALLEST_WORTH_TRYING = 4 * 1024;
-/**
- * Keep the compressed form only if it saved something worth having. A file
- * that shrinks by two percent is not worth the service decompressing it on
- * every read for the rest of its life.
- */
-const WORTHWHILE = 0.95;
-function looksCompressed(relativePath) {
-    const dot = relativePath.lastIndexOf(".");
-    if (dot < 0)
-        return false;
-    return ALREADY_COMPRESSED.has(relativePath.slice(dot).toLowerCase());
-}
 /**
  * Decide how one object should travel.
  *
@@ -73,15 +52,11 @@ async function encodeForUpload(original, relativePath, allowGzip) {
         encoding: "identity",
         storedSha256: "",
     };
-    if (!allowGzip)
-        return plain;
-    if (original.byteLength < SMALLEST_WORTH_TRYING)
-        return plain;
-    if (looksCompressed(relativePath))
+    if (!(0, compression_policy_1.shouldTryGzip)(relativePath, original.byteLength, allowGzip))
         return plain;
     try {
         const packed = await deflate(original, { level: 6 });
-        if (packed.byteLength >= original.byteLength * WORTHWHILE)
+        if (!(0, compression_policy_1.gzipIsWorthKeeping)(original.byteLength, packed.byteLength))
             return plain;
         return {
             body: new Uint8Array(packed),

package/dist/desktop-app/src/main/download.js

@@ -174,8 +174,39 @@ class Downloader {
         }
         return response;
     }
+    /**
+     * Read a complete JSON response under the same retry rule as the request.
+     *
+     * `fetch()` resolves as soon as the headers arrive. A connection can still
+     * disappear while `.json()` is consuming the body; treating the response
+     * object as success meant a large file list failed outside the retry loop.
+     * These routes are reads, so repeating the whole request is safe and is the
+     * only way to replace a truncated body.
+     */
+    async json(route) {
+        let wait = retry_js_1.RETRY_FIRST_WAIT_MS;
+        for (let attempt = 1;; attempt += 1) {
+            this.check();
+            try {
+                return await (await this.attempt(route)).json();
+            }
+            catch (error) {
+                if (error instanceof DownloadCancelled)
+                    throw error;
+                if (attempt >= retry_js_1.RETRY_ATTEMPTS || !(0, retry_js_1.worthRetrying)(error))
+                    throw error;
+                try {
+                    await (0, retry_js_1.pauseFor)(this.controller.signal, wait);
+                }
+                catch {
+                    throw new DownloadCancelled();
+                }
+                wait *= 2;
+            }
+        }
+    }
     async versions(repositoryId) {
-        const body = (await (await this.request(`/v1/repositories/${repositoryId}/versions`)).json());
+        const body = await this.json(`/v1/repositories/${repositoryId}/versions`);
         return (body.versions ?? []).map((row) => ({
             id: String(row.id ?? ""),
             sequence: Number(row.sequence ?? 0),
@@ -187,13 +218,26 @@ class Downloader {
         }));
     }
     async files(repositoryId, versionId) {
-        const body = (await (await this.request(`/v1/repositories/${repositoryId}/versions/${versionId}/files`)).json());
+        const body = await this.json(`/v1/repositories/${repositoryId}/versions/${versionId}/files`);
         return (body.files ?? []).map((row) => {
             const pieces = Array.isArray(row.chunks) ? row.chunks : null;
+            const packed = row.pack && typeof row.pack === "object"
+                ? row.pack
+                : null;
             return {
                 path: String(row.path ?? ""),
+                ...(row.objectId ? { objectId: String(row.objectId) } : {}),
                 sha256: String(row.sha256 ?? ""),
                 sourceSize: Number(row.sourceSize ?? 0),
+                ...(packed?.objectId
+                    ? {
+                        pack: {
+                            objectId: String(packed.objectId),
+                            offset: Number(packed.offset ?? 0),
+                            length: Number(packed.length ?? 0),
+                        },
+                    }
+                    : {}),
                 ...(pieces && pieces.length
                     ? {
                         chunks: pieces.map((piece) => {
@@ -240,6 +284,92 @@ class Downloader {
         await (0, promises_1.mkdir)(node_path_1.default.dirname(target), { recursive: true });
         return this.fetchInto(repositoryId, versionId, file, target);
     }
+    /**
+     * Reconstruct and verify every file in a Version without materialising the
+     * whole project at once. Solid packs are fetched once and large files use a
+     * single reusable scratch path, so the disk requirement is bounded by the
+     * largest individual file rather than the complete snapshot.
+     */
+    async verify(repositoryId, versionId, scratch, report) {
+        const files = await this.files(repositoryId, versionId);
+        if (!files.length)
+            throw new Error("That version has no files");
+        const totalBytes = files.reduce((total, file) => total + file.sourceSize, 0);
+        const packed = new Map();
+        for (const file of files) {
+            const id = file.pack?.objectId;
+            if (!id)
+                continue;
+            const group = packed.get(id) ?? [];
+            group.push(file);
+            packed.set(id, group);
+        }
+        await (0, promises_1.rm)(scratch, { recursive: true, force: true });
+        await (0, promises_1.mkdir)(scratch, { recursive: true });
+        const temporary = node_path_1.default.join(scratch, "current-file.partial");
+        const restoredPacks = new Set();
+        const manifest = {};
+        let written = 0;
+        let bytes = 0;
+        const progress = (filePath) => report({
+            files: written,
+            totalFiles: files.length,
+            bytes,
+            totalBytes,
+            path: filePath,
+            percent: underway(bytes, totalBytes),
+        });
+        try {
+            for (const file of files) {
+                this.check();
+                progress(file.path);
+                const packId = file.pack?.objectId;
+                if (packId && restoredPacks.has(packId))
+                    continue;
+                if (packId) {
+                    const reply = await this.request(`/v1/repositories/${repositoryId}/objects/${packId}`);
+                    const body = Buffer.from(await reply.arrayBuffer());
+                    const packDigest = (0, node_crypto_1.createHash)("sha256").update(body).digest("hex");
+                    const expectedPackDigest = reply.headers.get("x-coderook-sha256");
+                    if (expectedPackDigest && packDigest !== expectedPackDigest) {
+                        throw new Error("A solid pack did not arrive intact");
+                    }
+                    for (const member of packed.get(packId) ?? []) {
+                        const offset = member.pack.offset;
+                        const length = member.pack.length;
+                        if (offset < 0 || length < 0 || offset + length > body.byteLength) {
+                            throw new Error(`${member.path} points outside its solid pack`);
+                        }
+                        const digest = (0, node_crypto_1.createHash)("sha256")
+                            .update(body.subarray(offset, offset + length))
+                            .digest("hex");
+                        if (member.sha256 && digest !== member.sha256) {
+                            throw new Error(`${member.path} did not arrive intact`);
+                        }
+                        manifest[member.path] = digest;
+                        written += 1;
+                        bytes += member.sourceSize;
+                        progress(member.path);
+                    }
+                    restoredPacks.add(packId);
+                    continue;
+                }
+                const digest = await this.fetchInto(repositoryId, versionId, file, temporary);
+                if (file.sha256 && digest !== file.sha256) {
+                    throw new Error(`${file.path} did not arrive intact`);
+                }
+                manifest[file.path] = digest;
+                written += 1;
+                bytes += file.sourceSize;
+                await (0, promises_1.rm)(temporary, { force: true });
+            }
+            progress("Done");
+            return { files: written, bytes, manifest };
+        }
+        finally {
+            await (0, promises_1.rm)(scratch, { recursive: true, force: true });
+        }
+    }
     async fetchInto(repositoryId, versionId, file, target) {
         const whole = (0, node_crypto_1.createHash)("sha256");
         const pieces = file.chunks ?? [];
@@ -269,8 +399,10 @@ class Downloader {
                 }
             })()
             : (async function* () {
-                const reply = await request(`/v1/repositories/${repositoryId}/versions/${versionId}/file` +
-                    `?path=${encodeURIComponent(file.path)}`);
+                const reply = await request(file.objectId
+                    ? `/v1/repositories/${repositoryId}/objects/${file.objectId}`
+                    : `/v1/repositories/${repositoryId}/versions/${versionId}/file` +
+                        `?path=${encodeURIComponent(file.path)}`);
                 if (!reply.body)
                     return;
                 for await (const block of node_stream_1.Readable.fromWeb(reply.body)) {
@@ -322,6 +454,16 @@ class Downloader {
         try {
             let written = 0;
             let bytes = 0;
+            const packed = new Map();
+            for (const file of files) {
+                const id = file.pack?.objectId;
+                if (!id)
+                    continue;
+                const group = packed.get(id) ?? [];
+                group.push(file);
+                packed.set(id, group);
+            }
+            const restoredPacks = new Set();
             for (const file of files) {
                 this.check();
                 report({
@@ -337,6 +479,60 @@ class Downloader {
                 if (parts.some((part) => part === ".." || part.includes("\0"))) {
                     throw new Error(`That version contains an unsafe path: ${file.path}`);
                 }
+                const packId = file.pack?.objectId;
+                if (packId && restoredPacks.has(packId))
+                    continue;
+                if (packId) {
+                    /*
+                      A solid pack is one compressed object containing many small files.
+          
+                      Asking the single-file route for every member made a large restore
+                      fetch and decompress the same pack thousands of times. The files
+                      listing already gives us the pack id and each member's exact
+                      window, so fetch the decoded pack once, verify it, and materialise
+                      every member before releasing the bounded section-sized buffer.
+                    */
+                    const reply = await this.request(`/v1/repositories/${repositoryId}/objects/${packId}`);
+                    const body = Buffer.from(await reply.arrayBuffer());
+                    const packDigest = (0, node_crypto_1.createHash)("sha256").update(body).digest("hex");
+                    const expectedPackDigest = reply.headers.get("x-coderook-sha256");
+                    if (expectedPackDigest && packDigest !== expectedPackDigest) {
+                        throw new Error("A solid pack did not arrive intact");
+                    }
+                    for (const member of packed.get(packId) ?? []) {
+                        this.check();
+                        const memberParts = member.path.split("/").filter(Boolean);
+                        if (memberParts.some((part) => part === ".." || part.includes("\0"))) {
+                            throw new Error(`That version contains an unsafe path: ${member.path}`);
+                        }
+                        const offset = member.pack.offset;
+                        const length = member.pack.length;
+                        if (offset < 0 || length < 0 || offset + length > body.byteLength) {
+                            throw new Error(`${member.path} points outside its solid pack`);
+                        }
+                        const contents = body.subarray(offset, offset + length);
+                        const digest = (0, node_crypto_1.createHash)("sha256").update(contents).digest("hex");
+                        if (member.sha256 && digest !== member.sha256) {
+                            throw new Error(`${member.path} did not arrive intact`);
+                        }
+                        const full = node_path_1.default.join(staging, ...memberParts);
+                        await (0, promises_1.mkdir)(node_path_1.default.dirname(full), { recursive: true });
+                        await (0, promises_1.writeFile)(full, contents);
+                        manifest[member.path] = digest;
+                        written += 1;
+                        bytes += member.sourceSize;
+                        report({
+                            files: written,
+                            totalFiles: files.length,
+                            bytes,
+                            totalBytes,
+                            path: member.path,
+                            percent: underway(bytes, totalBytes),
+                        });
+                    }
+                    restoredPacks.add(packId);
+                    continue;
+                }
                 const full = node_path_1.default.join(staging, ...parts);
                 await (0, promises_1.mkdir)(node_path_1.default.dirname(full), { recursive: true });
                 const digest = await this.fetchInto(repositoryId, versionId, file, full);

package/dist/desktop-app/src/main/upload.js

@@ -28,6 +28,7 @@ const solid_js_1 = require("./solid.js");
 const retry_js_1 = require("./retry.js");
 const staging_js_1 = require("./staging.js");
 const delta_js_1 = require("../shared/delta.js");
+const telemetry_js_1 = require("../shared/telemetry.js");
 /** Above this the API insists on a multipart session. */
 const DIRECT_LIMIT = 95 * 1024 * 1024;
 /*
@@ -110,6 +111,17 @@ class Uploader {
     deltaProtocol = null;
     /** Batch delta is separate so V2 single-file support remains compatible. */
     deltaBatchSupported = null;
+    microchunkSupported = null;
+    /** One shared preflight, so parallel upload lanes cannot race /health. */
+    capabilityRequest = null;
+    telemetry = new telemetry_js_1.RepositoryTelemetry();
+    /** Planning runs the real partition/compression choices without body I/O. */
+    planning = false;
+    plannedObjects = new Map();
+    plannedQuote = null;
+    planningCreatedRepositoryId = null;
+    /** Attached to every object write after the server admits the exact plan. */
+    activeQuoteId = null;
     constructor(credentials) {
         this.credentials = credentials;
     }
@@ -143,8 +155,13 @@ class Uploader {
                 // Its own cancellation first: `worthRetrying` knows nothing of it.
                 if (error instanceof UploadCancelled)
                     throw error;
+                // Completing a multipart upload changes server state. Repeating it can
+                // replace the useful first failure with "upload is not active".
+                if (init.retryable === false)
+                    throw error;
                 if (attempt >= retry_js_1.RETRY_ATTEMPTS || !(0, retry_js_1.worthRetrying)(error))
                     throw error;
+                this.telemetry.retry();
                 await this.pause(wait);
                 wait *= 2;
             }
@@ -169,6 +186,7 @@ class Uploader {
     }
     /** A single attempt. Everything about repeating it lives in `call`. */
     async attempt(route, init) {
+        const started = performance.now();
         const token = await this.credentials.token();
         if (!token)
             throw new Error("Sign in again before uploading");
@@ -179,12 +197,17 @@ class Uploader {
                 authorization: `Bearer ${token}`,
                 "user-agent": "CodeRook/0.1",
                 ...(0, identify_js_1.clientHeaders)(),
+                ...(this.activeQuoteId
+                    ? { "x-coderook-upload-quote": this.activeQuoteId }
+                    : {}),
                 ...(init.contentType ? { "content-type": init.contentType } : {}),
             },
             body: init.body,
             signal: this.controller.signal,
         });
         const text = await response.text();
+        this.telemetry.request(route.split("?")[0] ?? route, init.body, new TextEncoder().encode(text).byteLength, performance.now() - started);
+        this.telemetry.memory(process.memoryUsage().rss);
         if (!response.ok) {
             /*
               Parsed only when it looks like JSON. An edge failure serves an HTML
@@ -229,7 +252,78 @@ class Uploader {
             throw new Error(`${route} returned a malformed reply`);
         }
     }
+    /**
+     * Perform the complete local compaction pass and ask the service whether its
+     * exact physical result fits. No object body is sent by this method.
+     */
+    async plan(request, report) {
+        this.planning = true;
+        this.activeQuoteId = null;
+        this.plannedQuote = null;
+        this.planningCreatedRepositoryId = null;
+        this.plannedObjects.clear();
+        try {
+            await this.runPass(request, report);
+            const quote = this.plannedQuote;
+            if (!quote)
+                throw new Error("Upload planning did not finish");
+            return {
+                ...quote,
+                repositoryCreated: this.planningCreatedRepositoryId === quote.repositoryId,
+            };
+        }
+        catch (error) {
+            if (this.planningCreatedRepositoryId) {
+                await this.call(`/v1/repositories/${this.planningCreatedRepositoryId}`, { method: "DELETE" }).catch(() => undefined);
+            }
+            throw error;
+        }
+        finally {
+            this.planning = false;
+        }
+    }
+    /** Release a review quote, and optionally its newly-created empty project. */
+    async cancelPlan(plan, removeCreatedRepository = false) {
+        await this.call(`/v1/repositories/${plan.repositoryId}/uploads/preflight/${plan.quoteId}`, { method: "DELETE" });
+        if (removeCreatedRepository && plan.repositoryCreated) {
+            await this.call(`/v1/repositories/${plan.repositoryId}`, { method: "DELETE" });
+        }
+    }
+    /** Plan first, then execute only the admitted immutable object set. */
     async run(request, report) {
+        const plan = await this.plan(request, report);
+        return this.execute(request, plan, report);
+    }
+    /** Execute a still-active quote produced by {@link plan}. */
+    async execute(request, plan, report) {
+        this.activeQuoteId = plan.quoteId;
+        try {
+            return await this.runPass({ ...request, repositoryId: plan.repositoryId }, report);
+        }
+        finally {
+            this.activeQuoteId = null;
+        }
+    }
+    rememberObject(definition) {
+        this.plannedObjects.set(definition.sha256, definition);
+        // Only used to let the planning pass build an in-memory candidate. It is
+        // never published or sent to the service.
+        return `00000000-0000-4000-8000-${definition.sha256.slice(0, 12)}`;
+    }
+    definition(sha256, size, mediaType, encoded, kind = "chunk", repositoryRole = "chunk") {
+        return {
+            sha256,
+            size,
+            storedSize: encoded.body.byteLength,
+            storedSha256: encoded.encoding === "gzip" ? encoded.storedSha256 : sha256,
+            mediaType,
+            kind,
+            repositoryRole,
+            encoding: encoded.encoding,
+        };
+    }
+    async runPass(request, report) {
+        this.telemetry = new telemetry_js_1.RepositoryTelemetry();
         // A version is a snapshot, not a delta, so it has to name every file in
         // the project — not merely the ones being sent this time. Anything
         // unchanged keeps the object the previous version already pointed at.
@@ -293,7 +387,23 @@ class Uploader {
         */
         const onDisk = new Set(everything.map((file) => file.path));
         const deletions = new Set(request.deletions ?? []);
+        const readFailures = new Map();
         const vanished = [...ticked].filter((chosen) => !onDisk.has(chosen) && !deletions.has(chosen));
+        /*
+          A caller may still hold a selection drawn before the rules changed. If
+          the file is on disk but absent from the filtered survey, it is excluded,
+          not unreadable. Naming that distinction matters: closing applications
+          cannot fix an ignore rule, while changing or removing the rule can.
+        */
+        for (const chosen of vanished) {
+            try {
+                await (0, promises_1.stat)(node_path_1.default.join(request.localPath, chosen));
+                readFailures.set(chosen, "excluded by the project's ignore rules");
+            }
+            catch (error) {
+                readFailures.set(chosen, error instanceof Error ? error.message : String(error));
+            }
+        }
         // 1. Measure and hash. This is what makes an unchanged file free.
         const declarations = [];
         let totalBytes = 0;
@@ -304,10 +414,11 @@ class Uploader {
             try {
                 size = (await (0, promises_1.stat)(full)).size;
             }
-            catch {
+            catch (error) {
                 // Unreadable now, though it was listed a moment ago. Skipping it
                 // would publish a version quietly missing a file the person chose.
                 vanished.push(file.path);
+                readFailures.set(file.path, error instanceof Error ? error.message : String(error));
                 continue;
             }
             report({
@@ -337,8 +448,9 @@ class Uploader {
             try {
                 digest = await (0, profile_js_1.timed)("hash files", () => digestOf(full));
             }
-            catch {
+            catch (error) {
                 vanished.push(file.path);
+                readFailures.set(file.path, error instanceof Error ? error.message : String(error));
                 continue;
             }
             declarations.push({
@@ -380,6 +492,8 @@ class Uploader {
                     }),
                 });
                 repositoryId = created.id;
+                if (this.planning)
+                    this.planningCreatedRepositoryId = created.id;
             }
             catch (error) {
                 // The account already has a project of this name — which happens
@@ -391,6 +505,10 @@ class Uploader {
                 repositoryId = existing;
             }
         }
+        // Learn the wire contract once, before the two section pipelines begin.
+        // Otherwise their first feature questions race each other and a busy
+        // service can make one lane cache a false "unsupported" answer.
+        await this.serviceCapabilities();
         /*
           Sent in sections, not in one attempt.
     
@@ -766,7 +884,9 @@ class Uploader {
                       whole: cutting it up would trade one request for several and save
                       nothing.
                     */
-                    const chunkProfile = (0, chunking_js_1.profileForFileSize)(declaration.size);
+                    const chunkProfile = (await this.microchunkAllowed())
+                        ? (0, chunking_js_1.microchunkProfileForFileSize)(declaration.size)
+                        : (0, chunking_js_1.profileForFileSize)(declaration.size);
                     if (chunkProfile &&
                         declaration.size >= CHUNK_THRESHOLD &&
                         (await this.chunkingAllowed())) {
@@ -880,6 +1000,41 @@ class Uploader {
             }
         };
         await Promise.all([pipeline(batchy), pipeline(heavy)]);
+        if (this.planning) {
+            report({
+                stage: "publish",
+                files: declarations.length,
+                totalFiles: declarations.length,
+                bytes: sentBytes,
+                totalBytes,
+                path: "Checking storage and monthly allowance",
+                percent: 96,
+                bytesPerSecond: 0,
+            });
+            this.plannedQuote = await this.call(`/v1/repositories/${repositoryId}/uploads/preflight`, {
+                method: "POST",
+                contentType: "application/json",
+                body: JSON.stringify({
+                    sourceBytes: totalBytes,
+                    excludedBytes: 0,
+                    objects: [...this.plannedObjects.values()],
+                }),
+            });
+            return {
+                repositoryId,
+                versionId: "",
+                sequence: 0,
+                sourceBytes: totalBytes,
+                storedBytes: this.plannedQuote.compactedBytes,
+                sentBytes: this.plannedQuote.chargeableBytes,
+                sentFiles: Object.values(this.plannedQuote.objects).filter((object) => object.needsUpload).length,
+                reusedFiles: reused.length,
+                alreadyStoredFiles: 0,
+                manifest: {},
+                local: {},
+                telemetry: this.telemetry.snapshot(),
+            };
+        }
         // 4. Name the version, which is what makes the upload visible.
         this.check();
         report({
@@ -952,6 +1107,11 @@ class Uploader {
         if (dropped.length) {
             const shown = dropped.slice(0, 5).join(", ");
             const rest = dropped.length > 5 ? ` and ${dropped.length - 5} more` : "";
+            const details = dropped
+                .map((name) => readFailures.get(name) ? `${name}: ${readFailures.get(name)}` : "")
+                .filter(Boolean)
+                .slice(0, 3)
+                .join("; ");
             /*
               Say what to do about it. Refusing is right — a version quietly missing
               a file somebody chose is the one failure a backup tool must never have
@@ -960,10 +1120,14 @@ class Uploader {
               holds them or unticking them. Almost every case is a file another
               program has open, so that is what it says.
             */
-            throw new Error(`${dropped.length} selected file${dropped.length === 1 ? "" : "s"} could not be read, ` +
-                `so nothing was saved: ${shown}${rest}. This usually means another program ` +
-                `has them open. Close it and try again, or untick them in the file list. ` +
-                `Nothing was changed on your account.`);
+            const excluded = dropped.some((name) => readFailures.get(name)?.includes("ignore rules"));
+            throw new Error(`${dropped.length} selected file${dropped.length === 1 ? "" : "s"} could not be included, ` +
+                `so nothing was saved: ${shown}${rest}. ` +
+                (excluded
+                    ? `At least one is excluded by the project's ignore rules. Change the rules or untick it and try again. `
+                    : `Another program may have a file open. Close it or untick the file and try again. `) +
+                `Nothing was changed on your account.` +
+                (details ? ` Details: ${details}` : ""));
         }
         const sourceBytes = contents.reduce((total, item) => total + item.sourceSize, 0);
         const storedBytes = contents.reduce((total, item) => total + item.storedSize, 0);
@@ -1067,6 +1231,7 @@ class Uploader {
             reusedFiles: reused.length,
             /** Selected, but the service already held the content. */
             alreadyStoredFiles: alreadyOnAccount,
+            telemetry: this.telemetry.snapshot(),
             // A file that kept its old object records the digest of *that* copy,
             // not of the file on disk, so an unticked edit is still pending next
             // time rather than looking as though it had been saved.
@@ -1203,6 +1368,30 @@ class Uploader {
         if (!built)
             return null;
         const packed = this.frameSolidPack(built);
+        if (this.planning) {
+            const objectId = this.rememberObject({
+                sha256: built.sha256,
+                size: built.size,
+                storedSize: built.body.byteLength,
+                storedSha256: built.storedSha256,
+                mediaType: "application/octet-stream",
+                kind: "solid_pack",
+                repositoryRole: "bundle",
+                encoding: "gzip",
+            });
+            const placed = new Map();
+            for (const member of built.members) {
+                placed.set(member.sha256, {
+                    packObjectId: objectId,
+                    offset: member.offset,
+                    length: member.length,
+                    storedSize: built.size
+                        ? Math.round((member.length / built.size) * built.body.byteLength)
+                        : 0,
+                });
+            }
+            return placed;
+        }
         const answer = await this.call(`/v1/repositories/${repositoryId}/objects/pack`, {
             method: "POST",
             contentType: "application/octet-stream",
@@ -1319,6 +1508,17 @@ class Uploader {
             const wireBytes = signatureBytes.byteLength + framed.byteLength;
             if (wireBytes >= solidPackBytes * 0.8)
                 return null;
+            if (this.planning) {
+                const objects = new Map();
+                for (const item of items) {
+                    const definition = this.definition(item.declaration.sha256, item.body.byteLength, item.declaration.mediaType, item.encoded);
+                    objects.set(item.declaration.sha256, {
+                        objectId: this.rememberObject(definition),
+                        size: definition.storedSize,
+                    });
+                }
+                return { objects, sentBytes: wireBytes };
+            }
             const answer = await this.call(`/v1/repositories/${repositoryId}/objects/delta/batch`, {
                 method: "POST",
                 contentType: "application/octet-stream",
@@ -1404,6 +1604,14 @@ class Uploader {
             const wireBytes = signatureBytes.byteLength + framed.byteLength;
             if (wireBytes >= ordinary.body.byteLength * 0.8)
                 return null;
+            if (this.planning) {
+                const definition = this.definition(declaration.sha256, target.byteLength, declaration.mediaType, ordinary);
+                return {
+                    objectId: this.rememberObject(definition),
+                    storedSize: definition.storedSize,
+                    sentBytes: wireBytes,
+                };
+            }
             const answer = await this.call(`/v1/repositories/${repositoryId}/objects/delta`, {
                 method: "POST",
                 contentType: "application/octet-stream",
@@ -1477,6 +1685,16 @@ class Uploader {
             packed.set(item.encoded.body, at);
             at += item.encoded.body.byteLength;
         }
+        if (this.planning) {
+            for (const item of items) {
+                const definition = this.definition(item.declaration.sha256, item.body.byteLength, item.declaration.mediaType, item.encoded);
+                landed.set(item.declaration.sha256, {
+                    objectId: this.rememberObject(definition),
+                    size: definition.storedSize,
+                });
+            }
+            return landed;
+        }
         const answer = await this.call(`/v1/repositories/${repositoryId}/objects/batch`, {
             method: "POST",
             contentType: "application/octet-stream",
@@ -1687,6 +1905,16 @@ class Uploader {
                     `&logicalSize=${piece.length}` +
                     `&storedSha256=${encoded.storedSha256}`
                 : `?kind=chunk&role=chunk`;
+            if (this.planning) {
+                const definition = this.definition(digest, piece.length, declaration.mediaType, encoded);
+                note("sent", encoded.body.byteLength);
+                chunks[at] = {
+                    objectId: this.rememberObject(definition),
+                    sourceSize: piece.length,
+                    storedSize: definition.storedSize,
+                };
+                return;
+            }
             const stored = await this.call(`/v1/repositories/${repositoryId}/objects/${digest}${query}`, {
                 method: "PUT",
                 contentType: "application/octet-stream",
@@ -1728,6 +1956,13 @@ class Uploader {
                 `&logicalSize=${body.length}` +
                 `&storedSha256=${encoded.storedSha256}`
             : `?kind=chunk&role=chunk`;
+        if (this.planning) {
+            const definition = this.definition(digest, body.length, declaration.mediaType, encoded);
+            return {
+                objectId: this.rememberObject(definition),
+                size: definition.storedSize,
+            };
+        }
         /*
           The answer carries both sizes and they are not the same thing: `size` is
           the file's own length, `storedSize` is what the service actually keeps.
@@ -1768,6 +2003,12 @@ class Uploader {
         this.packingSupported = (await this.serviceFeatures()).includes("solid-packs");
         return this.packingSupported;
     }
+    async microchunkAllowed() {
+        if (this.microchunkSupported !== null)
+            return this.microchunkSupported;
+        this.microchunkSupported = (await this.serviceFeatures()).includes("microchunk-map-v1");
+        return this.microchunkSupported;
+    }
     async deltaVersion() {
         if (this.deltaProtocol !== null)
             return this.deltaProtocol;
@@ -1791,40 +2032,57 @@ class Uploader {
         this.chunkingSupported = (await this.serviceFeatures()).includes("chunked-files");
         return this.chunkingSupported;
     }
-    /** What /health says this deployment accepts. Fetched once. */
+    /** What /health says this deployment accepts. One request per uploader. */
+    async serviceCapabilities() {
+        if (this.capabilityRequest)
+            return this.capabilityRequest;
+        this.capabilityRequest = (async () => {
+            try {
+                const response = await fetch(`${this.credentials.origin()}/health`, {
+                    headers: { accept: "application/json", ...(0, identify_js_1.clientHeaders)() },
+                    signal: AbortSignal.timeout(8000),
+                });
+                if (!response.ok)
+                    throw new Error(`health failed (${response.status})`);
+                const body = (await response.json());
+                return {
+                    features: body.features ?? [],
+                    contentEncodings: body.contentEncodings ?? ["identity"],
+                };
+            }
+            catch {
+                /* Unknown is treated as unsupported: never risk a refused upload. */
+                return { features: [], contentEncodings: ["identity"] };
+            }
+        })();
+        return this.capabilityRequest;
+    }
     async serviceFeatures() {
-        try {
-            const response = await fetch(`${this.credentials.origin()}/health`, {
-                headers: { accept: "application/json", ...(0, identify_js_1.clientHeaders)() },
-                signal: AbortSignal.timeout(8000),
-            });
-            const body = (await response.json());
-            return body.features ?? [];
-        }
-        catch {
-            /* Unknown is treated as unsupported: never risk a refused upload. */
-            return [];
-        }
+        return (await this.serviceCapabilities()).features;
     }
     async gzipAllowed() {
         if (this.gzipSupported !== null)
             return this.gzipSupported;
-        try {
-            const response = await fetch(`${this.credentials.origin()}/health`, {
-                headers: { accept: "application/json", ...(0, identify_js_1.clientHeaders)() },
-                signal: AbortSignal.timeout(8000),
-            });
-            const body = (await response.json());
-            this.gzipSupported = Boolean(body.contentEncodings?.includes("gzip"));
-        }
-        catch {
-            /* Unknown is treated as unsupported: never risk a refused upload. */
-            this.gzipSupported = false;
-        }
+        const body = await this.serviceCapabilities();
+        this.gzipSupported = body.contentEncodings.includes("gzip");
         return this.gzipSupported;
     }
     /** Files past the direct limit go up in parts under an upload session. */
     async putMultipart(repositoryId, declaration, onOffset) {
+        if (this.planning) {
+            const objectId = this.rememberObject({
+                sha256: declaration.sha256,
+                size: declaration.size,
+                storedSize: declaration.size,
+                storedSha256: declaration.sha256,
+                mediaType: declaration.mediaType,
+                kind: "chunk",
+                repositoryRole: "chunk",
+                encoding: "identity",
+            });
+            onOffset(declaration.size);
+            return { objectId, size: declaration.size };
+        }
         const session = await this.call(`/v1/repositories/${repositoryId}/uploads`, {
             method: "POST",
             contentType: "application/json",
@@ -1852,7 +2110,12 @@ class Uploader {
                 partNumber += 1;
                 onOffset(offset);
             }
-            return await this.call(`/v1/uploads/${session.uploadSessionId}/complete`, { method: "POST", contentType: "application/json", body: "{}" });
+            return await this.call(`/v1/uploads/${session.uploadSessionId}/complete`, {
+                method: "POST",
+                contentType: "application/json",
+                body: "{}",
+                retryable: false,
+            });
         }
         catch (error) {
             // A half-finished session would hold storage forever.

package/dist/desktop-app/src/shared/chunking.js

@@ -8,8 +8,9 @@
  * means adding a new id, never changing the meaning of an existing one.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_CHUNK_PROFILE = exports.HUGE_CHUNK_PROFILE = exports.LARGE_CHUNK_PROFILE = exports.MEDIUM_CHUNK_PROFILE = exports.LEGACY_CHUNK_PROFILE = void 0;
+exports.MICRO_CHUNK_PROFILE = exports.DEFAULT_CHUNK_PROFILE = exports.HUGE_CHUNK_PROFILE = exports.LARGE_CHUNK_PROFILE = exports.MEDIUM_CHUNK_PROFILE = exports.LEGACY_CHUNK_PROFILE = void 0;
 exports.profileForFileSize = profileForFileSize;
+exports.microchunkProfileForFileSize = microchunkProfileForFileSize;
 exports.cutPoints = cutPoints;
 exports.chunkBoundaries = chunkBoundaries;
 exports.manifestChunking = manifestChunking;
@@ -63,6 +64,20 @@ exports.HUGE_CHUNK_PROFILE = Object.freeze({
     looseMask: 0x003f_ffff,
 });
 exports.DEFAULT_CHUNK_PROFILE = exports.HUGE_CHUNK_PROFILE;
+/**
+ * Fine-grained large-file transport. It uses the same portable FastCDC
+ * boundary function but keeps edit amplification near one MiB instead of
+ * four to eight MiB. Existing Versions retain their recorded chunk objects.
+ */
+exports.MICRO_CHUNK_PROFILE = Object.freeze({
+    id: "fastcdc-v3-micro",
+    algorithm: "fastcdc-v2",
+    minSize: 256 * KIB,
+    targetSize: 1 * MIB,
+    maxSize: 4 * MIB,
+    strictMask: 0x001f_ffff,
+    looseMask: 0x0007_ffff,
+});
 /** The profile repository uploads use for a file of `size` bytes. */
 function profileForFileSize(size) {
     if (!Number.isFinite(size) || size < 0) {
@@ -76,6 +91,11 @@ function profileForFileSize(size) {
         return exports.LARGE_CHUNK_PROFILE;
     return exports.HUGE_CHUNK_PROFILE;
 }
+/** New-write profile when the service advertises the microchunk map. */
+function microchunkProfileForFileSize(size) {
+    const legacy = profileForFileSize(size);
+    return legacy ? exports.MICRO_CHUNK_PROFILE : null;
+}
 const GEAR = (() => {
     const table = new Uint32Array(256);
     let seed = 0x9e3779b9;

package/dist/desktop-app/src/shared/compression_policy.js

@@ -0,0 +1,35 @@
+"use strict";
+/*
+ * The storage representation decision is a protocol rule, not a desktop UI
+ * preference. Keep the cheap, deterministic part of it in a runtime-neutral
+ * module so Desktop, CLI (through Desktop's uploader), Website and the Worker
+ * make the same decision for the same object.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORTHWHILE_COMPRESSION_RATIO = exports.SMALLEST_WORTH_COMPRESSING = void 0;
+exports.looksCompressed = looksCompressed;
+exports.shouldTryGzip = shouldTryGzip;
+exports.gzipIsWorthKeeping = gzipIsWorthKeeping;
+const ALREADY_COMPRESSED = new Set([
+    ".7z", ".aac", ".avi", ".br", ".bz2", ".cbx", ".docx", ".flac", ".gif",
+    ".gz", ".heic", ".jpeg", ".jpg", ".jxl", ".m4a", ".m4v", ".mkv", ".mov",
+    ".mp3", ".mp4", ".odp", ".ods", ".odt", ".ogg", ".opus", ".pdf", ".png",
+    ".pptx", ".rar", ".safetensors", ".webm", ".webp", ".xlsx", ".xz", ".zip",
+    ".zst",
+]);
+exports.SMALLEST_WORTH_COMPRESSING = 4 * 1024;
+exports.WORTHWHILE_COMPRESSION_RATIO = 0.95;
+function looksCompressed(relativePath) {
+    const dot = relativePath.lastIndexOf(".");
+    if (dot < 0)
+        return false;
+    return ALREADY_COMPRESSED.has(relativePath.slice(dot).toLowerCase());
+}
+function shouldTryGzip(relativePath, sourceBytes, allowGzip) {
+    return (allowGzip &&
+        sourceBytes >= exports.SMALLEST_WORTH_COMPRESSING &&
+        !looksCompressed(relativePath));
+}
+function gzipIsWorthKeeping(sourceBytes, compressedBytes) {
+    return compressedBytes < sourceBytes * exports.WORTHWHILE_COMPRESSION_RATIO;
+}

package/dist/desktop-app/src/shared/telemetry.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RepositoryTelemetry = void 0;
+const byteLength = (body) => typeof body === "string" ? new TextEncoder().encode(body).byteLength : body?.byteLength ?? 0;
+class RepositoryTelemetry {
+    started = performance.now();
+    requests = 0;
+    retries = 0;
+    requestBodyBytes = 0;
+    responseBodyBytes = 0;
+    peakMemoryBytes = null;
+    routes = new Map();
+    retry() {
+        this.retries += 1;
+    }
+    request(route, body, responseBytes, elapsedMs) {
+        this.requestBytes(route, byteLength(body), responseBytes, elapsedMs);
+    }
+    requestBytes(route, sentBytes, responseBytes, elapsedMs) {
+        this.requests += 1;
+        this.requestBodyBytes += sentBytes;
+        this.responseBodyBytes += responseBytes;
+        const prior = this.routes.get(route) ?? { requests: 0, sentBytes: 0, receivedBytes: 0, elapsedMs: 0 };
+        prior.requests += 1;
+        prior.sentBytes += sentBytes;
+        prior.receivedBytes += responseBytes;
+        prior.elapsedMs += elapsedMs;
+        this.routes.set(route, prior);
+    }
+    memory(bytes) {
+        if (bytes === null || bytes === undefined || !Number.isFinite(bytes) || bytes < 0)
+            return;
+        this.peakMemoryBytes = Math.max(this.peakMemoryBytes ?? 0, bytes);
+    }
+    snapshot() {
+        return {
+            elapsedMs: performance.now() - this.started,
+            requests: this.requests,
+            retries: this.retries,
+            requestBodyBytes: this.requestBodyBytes,
+            responseBodyBytes: this.responseBodyBytes,
+            peakMemoryBytes: this.peakMemoryBytes,
+            routes: Object.fromEntries([...this.routes.entries()].sort(([left], [right]) => left.localeCompare(right))),
+        };
+    }
+}
+exports.RepositoryTelemetry = RepositoryTelemetry;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderook/cli",
-  "version": "0.22.1",
+  "version": "0.22.2",
   "description": "CodeRook from the command line, on any operating system",
   "license": "SEE LICENSE IN LICENSE.txt",
   "homepage": "https://coderook.com",