@vincentt-xr/cli 0.18.0 → 0.18.1

package/MIGRATION.md

@@ -3,6 +3,13 @@
 Per version, newest first. Read by the platform's own version surface and served to
 creators' agents. Accurate or absent, never speculative (B-F5-2).
 
+## 0.18.1
+
+required: false
+No action required. Behaviour that changed:
+- `publish` re-opens the upload when an upload link expires (at most twice) instead of failing. Network errors and S3 5xx are retried with backoff. A refused upload reports "changed while uploading" only when S3 says the bytes do not match; other refusals name the failed file.
+- A publish that fails on the network leaves its upload open, so running `vincentt publish` again sends only the files that have not landed yet (on an API that supports it). Files stream from disk instead of being read into memory.
+
 ## 0.18.0
 
 required: false

package/dist/publish/command.d.ts

@@ -1,3 +1,5 @@
+/** Re-opens after an expired upload link, per publish, before giving up. */
+export declare const MAX_REOPENS = 2;
 import type { ResolvedConfig } from "../shared/config.js";
 import { type BuiltWith } from "../platform/resolve.js";
 import { type VincenttJson } from "../lib/settings.js";

package/dist/publish/command.js

@@ -15,7 +15,9 @@ import { buildManifest, ManifestError } from "./manifest.js";
 import { checkBounds } from "./bounds.js";
 import { classifyDist } from "./classify.js";
 import { createProgress } from "./progress.js";
-import { UploadFailed, uploadAll } from "./upload.js";
+import { UploadExpired, UploadFailed, uploadAll } from "./upload.js";
+/** Re-opens after an expired upload link, per publish, before giving up. */
+export const MAX_REOPENS = 2;
 import { waitUntilServing } from "./visibility.js";
 import * as copy from "./copy.js";
 import { publishedLimitRefused, resolveCountLimit, storageCeilingRefused, } from "../shared/countLimit.js";
@@ -257,16 +259,20 @@ async function runPublish(deps, opts, onCommitted) {
     });
 }
 async function runUpload(deps, cfg, i) {
-    let opened;
-    try {
-        opened = await openUpload(cfg, i.projectId, i.manifest.files, i.note, i.fetchImpl, i.builtWith);
-    }
-    catch (err) {
+    const open = () => openUpload(cfg, i.projectId, i.manifest.files, i.note, i.fetchImpl, i.builtWith);
+    const openFailed = (err) => {
         if (err instanceof AuthExpiredError)
             return authExpired(deps);
         for (const l of openErrorLines(err, i.address, i.liveVersion, i.org))
             deps.print(l);
         return 1;
+    };
+    let opened;
+    try {
+        opened = await open();
+    }
+    catch (err) {
+        return openFailed(err);
     }
     deps.print(copy.uploadStart(i.manifest.files.length));
     const progress = createProgress({
@@ -276,24 +282,53 @@ async function runUpload(deps, cfg, i) {
         now: deps.now,
     });
     const startedAt = deps.now();
-    try {
-        await uploadAll({
-            distDir: i.distDir,
-            targets: opened.uploads,
-            manifest: i.manifest.files,
-            onProgress: (p) => progress.update(p),
-            fetchImpl: i.uploadFetch,
-        });
+    let reopens = 0;
+    let uploadErr;
+    for (;;) {
+        try {
+            await uploadAll({
+                distDir: i.distDir,
+                targets: opened.uploads,
+                manifest: i.manifest.files,
+                onProgress: (p) => progress.update(p),
+                fetchImpl: i.uploadFetch,
+                sleep: deps.sleep,
+            });
+            break;
+        }
+        catch (err) {
+            if (!(err instanceof UploadExpired) || reopens >= MAX_REOPENS) {
+                uploadErr = err;
+                break;
+            }
+        }
+        // An expired link: re-open for fresh URLs. An api that resumes returns the
+        // same upload with only the files still missing; one that does not returns
+        // a new upload and every file is sent again.
+        reopens += 1;
+        try {
+            opened = await open();
+        }
+        catch (err) {
+            progress.finish();
+            return openFailed(err);
+        }
     }
-    catch (err) {
+    if (uploadErr !== undefined) {
+        const err = uploadErr;
         progress.finish();
-        await abandonUpload(cfg, i.projectId, opened.uploadId, i.fetchImpl);
+        // A retryable failure (the network, S3 5xx, links that kept expiring) keeps
+        // the upload open so the next `vincentt publish` resumes it and sends only
+        // what is missing. Anything else is abandoned.
+        const resumable = err instanceof UploadExpired || (err instanceof UploadFailed && err.retryable);
+        if (!resumable)
+            await abandonUpload(cfg, i.projectId, opened.uploadId, i.fetchImpl);
         if (err instanceof UploadFailed && err.badDigest) {
             for (const l of copy.badDigest(err.path, i.address, i.liveVersion))
                 deps.print(l);
             return 1;
         }
-        const failedPath = err instanceof UploadFailed ? err.path : "a file";
+        const failedPath = err instanceof UploadFailed || err instanceof UploadExpired ? err.path : "a file";
         deps.print("");
         deps.print(`✗ Uploading ${failedPath} failed.`);
         deps.print("");

package/dist/publish/upload.d.ts

@@ -4,7 +4,23 @@ export declare class UploadFailed extends Error {
     readonly path: string;
     readonly status: number;
     readonly badDigest: boolean;
-    constructor(path: string, status: number, badDigest: boolean);
+    /** S3's own error code, when the response carried one. */
+    readonly s3Code?: string | undefined;
+    /** A transport error or 5xx outlasted every retry: re-running is the remedy. */
+    readonly retryable: boolean;
+    constructor(path: string, status: number, badDigest: boolean, 
+    /** S3's own error code, when the response carried one. */
+    s3Code?: string | undefined, 
+    /** A transport error or 5xx outlasted every retry: re-running is the remedy. */
+    retryable?: boolean);
+}
+/**
+ * A presigned URL was refused because it expired. The upload has to be
+ * re-opened for fresh URLs; nothing about the file is wrong.
+ */
+export declare class UploadExpired extends Error {
+    readonly path: string;
+    constructor(path: string);
 }
 export interface UploadProgress {
     filesDone: number;
@@ -19,18 +35,50 @@ export interface UploadOptions {
     concurrency?: number;
     onProgress?: (p: UploadProgress) => void;
     fetchImpl?: typeof fetch;
-    /** Per-file retries for a transient network/5xx failure. A BadDigest is retried once. */
+    /** Attempts per file for a transport error or 5xx. A BadDigest is retried once. */
     maxAttempts?: number;
+    /** Test seams for the backoff. */
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
 }
 /**
  * One PUT's deadline: a minute, plus the time the file takes at 64 KB/s. A fixed
  * deadline would fail every large file on a slow uplink; none at all lets a
- * stalled connection hang the publish forever.
+ * stalled connection hang the publish forever. The api sizes the upload window
+ * at the same rate, so a PUT this deadline still waits for is never refused by
+ * an expired link.
  */
 export declare function putDeadlineMs(bytes: number): number;
+/** Exponential backoff with full jitter: uniform in [0, min(cap, base * 2^(n-1))). */
+export declare function backoffMs(attempt: number, random?: () => number): number;
+export type S3Outcome = {
+    kind: "ok";
+} | {
+    kind: "expired";
+} | {
+    kind: "bad_digest";
+    code: string;
+} | {
+    kind: "retry";
+    code?: string;
+} | {
+    kind: "fatal";
+    code?: string;
+};
+/**
+ * What a PUT's response means, read from S3's own error code rather than the
+ * status alone. A 400 is many things — S3 answers a stalled body with 400
+ * RequestTimeout — and only BadDigest means the bytes on disk are not the bytes
+ * that were hashed.
+ */
+export declare function classifyS3Response(status: number, body: string): S3Outcome;
 /**
- * PUT every file. A re-run that finds files already landed simply uploads
- * fewer — resumption is silent, because the creator did not ask for a resume,
- * they asked to publish.
+ * PUT every target. The api returns targets only for files not yet landed when
+ * it resumes an open upload, so a re-run simply uploads fewer — resumption is
+ * silent, because the creator did not ask for a resume, they asked to publish.
+ *
+ * On the first file that cannot land, no new PUT starts; the ones in flight
+ * finish, and the first failure is thrown (UploadExpired only when nothing
+ * worse happened, since re-opening cannot fix a changed file).
  */
 export declare function uploadAll(opts: UploadOptions): Promise<void>;

package/dist/publish/upload.js

@@ -7,44 +7,109 @@
 // makes every published index.html download instead of render in the other
 // (§2.7's contract traps 3 and 4).
 //
-// The CLI never synthesizes a MIME type and never parses the presigned URL.
-import { promises as fs } from "node:fs";
+// The CLI never synthesizes a MIME type and never parses the presigned URL. The
+// one header it adds is Content-Length, which S3 requires on a PUT and which a
+// streamed body does not carry on its own.
+import { createReadStream, promises as fs } from "node:fs";
 import path from "node:path";
+import { Readable } from "node:stream";
 import { withDeadline } from "../shared/http.js";
 export class UploadFailed extends Error {
     path;
     status;
     badDigest;
-    constructor(path, status, badDigest) {
-        super(`upload failed for ${path} (${status})`);
+    s3Code;
+    retryable;
+    constructor(path, status, badDigest, 
+    /** S3's own error code, when the response carried one. */
+    s3Code, 
+    /** A transport error or 5xx outlasted every retry: re-running is the remedy. */
+    retryable = false) {
+        super(`upload failed for ${path} (${status}${s3Code ? ` ${s3Code}` : ""})`);
         this.path = path;
         this.status = status;
         this.badDigest = badDigest;
+        this.s3Code = s3Code;
+        this.retryable = retryable;
         this.name = "UploadFailed";
     }
 }
+/**
+ * A presigned URL was refused because it expired. The upload has to be
+ * re-opened for fresh URLs; nothing about the file is wrong.
+ */
+export class UploadExpired extends Error {
+    path;
+    constructor(path) {
+        super(`the upload link for ${path} expired`);
+        this.path = path;
+        this.name = "UploadExpired";
+    }
+}
 const DEFAULT_CONCURRENCY = 6;
+const DEFAULT_MAX_ATTEMPTS = 5;
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_CAP_MS = 15_000;
 /**
  * One PUT's deadline: a minute, plus the time the file takes at 64 KB/s. A fixed
  * deadline would fail every large file on a slow uplink; none at all lets a
- * stalled connection hang the publish forever.
+ * stalled connection hang the publish forever. The api sizes the upload window
+ * at the same rate, so a PUT this deadline still waits for is never refused by
+ * an expired link.
  */
 export function putDeadlineMs(bytes) {
     return 60_000 + Math.ceil(bytes / 64_000) * 1000;
 }
+/** Exponential backoff with full jitter: uniform in [0, min(cap, base * 2^(n-1))). */
+export function backoffMs(attempt, random = Math.random) {
+    const ceiling = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** Math.max(0, attempt - 1));
+    return Math.floor(random() * ceiling);
+}
+/**
+ * What a PUT's response means, read from S3's own error code rather than the
+ * status alone. A 400 is many things — S3 answers a stalled body with 400
+ * RequestTimeout — and only BadDigest means the bytes on disk are not the bytes
+ * that were hashed.
+ */
+export function classifyS3Response(status, body) {
+    if (status >= 200 && status < 300)
+        return { kind: "ok" };
+    const code = /<Code>([^<]+)<\/Code>/.exec(body)?.[1];
+    const message = /<Message>([^<]*)<\/Message>/.exec(body)?.[1] ?? "";
+    if (status === 403 && code === "AccessDenied" && /request has expired/i.test(message)) {
+        return { kind: "expired" };
+    }
+    if (code === "BadDigest")
+        return { kind: "bad_digest", code };
+    if (code === "RequestTimeout" || code === "IncompleteBody")
+        return { kind: "retry", code };
+    if (status >= 500 || status === 408 || status === 429)
+        return { kind: "retry", code };
+    return { kind: "fatal", code };
+}
 /**
- * PUT every file. A re-run that finds files already landed simply uploads
- * fewer — resumption is silent, because the creator did not ask for a resume,
- * they asked to publish.
+ * PUT every target. The api returns targets only for files not yet landed when
+ * it resumes an open upload, so a re-run simply uploads fewer — resumption is
+ * silent, because the creator did not ask for a resume, they asked to publish.
+ *
+ * On the first file that cannot land, no new PUT starts; the ones in flight
+ * finish, and the first failure is thrown (UploadExpired only when nothing
+ * worse happened, since re-opening cannot fix a changed file).
  */
 export async function uploadAll(opts) {
     const fetchImpl = opts.fetchImpl ?? fetch;
     const sizes = new Map(opts.manifest.map((f) => [f.path, f.size]));
-    const bytesTotal = opts.manifest.reduce((n, f) => n + f.size, 0);
+    const bytesTotal = opts.targets.reduce((n, t) => n + (sizes.get(t.path) ?? 0), 0);
     const queue = [...opts.targets];
-    const maxAttempts = opts.maxAttempts ?? 3;
+    const retry = {
+        maxAttempts: opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+        sleep: opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+        random: opts.random ?? Math.random,
+    };
     let filesDone = 0;
     let bytesDone = 0;
+    let failed = false;
+    let failure;
     const report = () => opts.onProgress?.({
         filesDone,
         filesTotal: opts.targets.length,
@@ -53,11 +118,19 @@ export async function uploadAll(opts) {
     });
     report();
     const worker = async () => {
-        for (;;) {
+        while (!failed) {
             const target = queue.shift();
             if (!target)
                 return;
-            await putOne(target, opts.distDir, fetchImpl, maxAttempts);
+            try {
+                await putOne(target, opts.distDir, fetchImpl, retry);
+            }
+            catch (err) {
+                if (!failed || failure instanceof UploadExpired)
+                    failure = err;
+                failed = true;
+                return;
+            }
             filesDone += 1;
             bytesDone += sizes.get(target.path) ?? 0;
             report();
@@ -65,39 +138,64 @@ export async function uploadAll(opts) {
     };
     const workers = Array.from({ length: Math.min(opts.concurrency ?? DEFAULT_CONCURRENCY, queue.length || 1) }, () => worker());
     await Promise.all(workers);
+    if (failed)
+        throw failure;
 }
-async function putOne(target, distDir, fetchImpl, maxAttempts) {
+async function putOne(target, distDir, fetchImpl, retry) {
     const abs = path.join(distDir, ...target.path.split("/"));
-    const body = await fs.readFile(abs);
-    const put = withDeadline(fetchImpl, putDeadlineMs(body.byteLength));
+    const { size } = await fs.stat(abs);
+    const put = withDeadline(fetchImpl, putDeadlineMs(size));
     let lastStatus = 0;
+    let lastCode;
     let sawBadDigest = false;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    for (let attempt = 1; attempt <= retry.maxAttempts; attempt++) {
+        if (attempt > 1)
+            await retry.sleep(backoffMs(attempt - 1, retry.random));
+        // A fresh stream per attempt: a body cannot be replayed once read.
+        const stream = createReadStream(abs);
         let res;
+        let text;
         try {
             res = await put(target.url, {
                 method: "PUT",
-                // VERBATIM. No key dropped, no key added, no key renamed.
-                headers: { ...target.headers },
-                body: new Uint8Array(body),
+                // VERBATIM. No key dropped, no key renamed; Content-Length is the one
+                // addition, required by S3 and absent from a streamed body.
+                headers: { ...target.headers, "content-length": String(size) },
+                body: Readable.toWeb(stream),
+                duplex: "half",
             });
+            text = res.ok ? "" : await res.text().catch(() => "");
         }
         catch {
             lastStatus = 0;
+            lastCode = undefined;
             continue;
         }
-        if (res.ok)
-            return;
-        lastStatus = res.status;
-        const text = await res.text().catch(() => "");
-        if (text.includes("BadDigest") || res.status === 400) {
-            // The bytes on disk differ from what was hashed. One silent re-PUT covers
-            // a torn read; a repeat means the file genuinely changed under us.
-            if (sawBadDigest)
-                throw new UploadFailed(target.path, res.status, true);
-            sawBadDigest = true;
-            continue;
+        finally {
+            stream.destroy();
+        }
+        const outcome = classifyS3Response(res.status, text);
+        switch (outcome.kind) {
+            case "ok":
+                return;
+            case "expired":
+                throw new UploadExpired(target.path);
+            case "bad_digest":
+                // The bytes on disk differ from what was hashed. One re-PUT covers a
+                // torn read; a repeat means the file genuinely changed under us.
+                if (sawBadDigest)
+                    throw new UploadFailed(target.path, res.status, true, outcome.code);
+                sawBadDigest = true;
+                lastStatus = res.status;
+                lastCode = outcome.code;
+                continue;
+            case "retry":
+                lastStatus = res.status;
+                lastCode = outcome.code;
+                continue;
+            case "fatal":
+                throw new UploadFailed(target.path, res.status, false, outcome.code);
         }
     }
-    throw new UploadFailed(target.path, lastStatus, sawBadDigest);
+    throw new UploadFailed(target.path, lastStatus, sawBadDigest, lastCode, !sawBadDigest);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",
@@ -28,7 +28,7 @@
     "qrcode": "^1.5.4",
     "ws": "^8.18.0",
     "zod": "^3.23.8",
-    "@vincentt-xr/harness": "1.6.0"
+    "@vincentt-xr/harness": "1.6.1"
   },
   "devDependencies": {
     "@types/qrcode": "^1.5.5",