@vincentt-xr/cli 0.1.5 → 0.3.0

package/dist/publish/manifest.d.ts

@@ -0,0 +1,27 @@
+import { type PathRejection } from "./paths.js";
+export interface ManifestEntry {
+    /** dist-relative, forward slashes, no leading `/`, normalized. */
+    path: string;
+    size: number;
+    /** base64 std. */
+    sha256: string;
+}
+export interface Manifest {
+    files: ManifestEntry[];
+    totalBytes: number;
+}
+export declare class ManifestError extends Error {
+    readonly reason: PathRejection | "no_dist";
+    readonly offendingPath: string;
+    constructor(reason: PathRejection | "no_dist", offendingPath: string, message: string);
+}
+/** Recursively list files under `dir` as dir-relative POSIX paths. Symlinks are not followed. */
+export declare function walkDist(dir: string, base?: string): Promise<string[]>;
+/** sha256 of a file, base64 std — the exact form `x-amz-checksum-sha256` wants. */
+export declare function hashFile(absPath: string): Promise<string>;
+/**
+ * Build the manifest for a dist directory. Every path is normalized before it is
+ * hashed, so the string this returns is the string the API validates, signs, and
+ * later lists — there is no second form anywhere.
+ */
+export declare function buildManifest(distDir: string): Promise<Manifest>;

package/dist/publish/manifest.js

@@ -0,0 +1,81 @@
+// The local manifest: one {path, size, sha256} per file under dist/.
+//
+// sha256 IS BASE64-STD, NOT HEX. It is fed verbatim into the presigned PUT's
+// signed `x-amz-checksum-sha256` header, and hex there produces a BadDigest on
+// every single PUT while both repos' unit suites stay green (§2.7's first
+// contract trap).
+import { createHash } from "node:crypto";
+import { createReadStream, promises as fs } from "node:fs";
+import path from "node:path";
+import { normalizePath, validatePathSet } from "./paths.js";
+export class ManifestError extends Error {
+    reason;
+    offendingPath;
+    constructor(reason, offendingPath, message) {
+        super(message);
+        this.reason = reason;
+        this.offendingPath = offendingPath;
+        this.name = "ManifestError";
+    }
+}
+/** Recursively list files under `dir` as dir-relative POSIX paths. Symlinks are not followed. */
+export async function walkDist(dir, base = dir) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new ManifestError("no_dist", dir, `no dist at ${dir}`);
+        }
+        throw err;
+    }
+    const out = [];
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await walkDist(full, base)));
+        else if (entry.isFile()) {
+            out.push(path.relative(base, full).split(path.sep).join("/"));
+        }
+    }
+    return out;
+}
+/** sha256 of a file, base64 std — the exact form `x-amz-checksum-sha256` wants. */
+export async function hashFile(absPath) {
+    const hash = createHash("sha256");
+    const stream = createReadStream(absPath);
+    for await (const chunk of stream)
+        hash.update(chunk);
+    return hash.digest("base64");
+}
+/**
+ * Build the manifest for a dist directory. Every path is normalized before it is
+ * hashed, so the string this returns is the string the API validates, signs, and
+ * later lists — there is no second form anywhere.
+ */
+export async function buildManifest(distDir) {
+    const raw = await walkDist(distDir);
+    const normalized = [];
+    for (const rel of raw) {
+        const result = normalizePath(rel);
+        if (!result.ok) {
+            throw new ManifestError(result.reason, rel, `${rel}: ${result.reason}`);
+        }
+        normalized.push({ rel, norm: result.path });
+    }
+    const pathError = validatePathSet(normalized.map((n) => n.norm));
+    if (pathError) {
+        throw new ManifestError(pathError.reason, pathError.path, `${pathError.path}: ${pathError.reason}`);
+    }
+    const files = [];
+    let totalBytes = 0;
+    for (const { rel, norm } of normalized) {
+        const abs = path.join(distDir, rel);
+        const stat = await fs.stat(abs);
+        files.push({ path: norm, size: stat.size, sha256: await hashFile(abs) });
+        totalBytes += stat.size;
+    }
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return { files, totalBytes };
+}

package/dist/publish/paths.d.ts

@@ -0,0 +1,25 @@
+/** The closed reason enum the API also emits. Shared so both surfaces name a rejection identically. */
+export type PathRejection = "path_traversal" | "absolute_path" | "duplicate_path" | "case_duplicate" | "no_index_html" | "bad_encoding" | "reserved_path";
+export interface PathError {
+    reason: PathRejection;
+    path: string;
+}
+export interface NormalizedPath {
+    ok: true;
+    path: string;
+}
+export type NormalizeResult = NormalizedPath | {
+    ok: false;
+    reason: PathRejection;
+};
+/**
+ * Normalize a dist-relative path, then check it. `a/./b.js` normalizes to
+ * `a/b.js` and is legal; `a/../../b.js` normalizes out of the tree and is not.
+ */
+export declare function normalizePath(raw: string): NormalizeResult;
+/**
+ * Validate a whole set of normalized paths. The manifest is rejected as a WHOLE
+ * — never a subset — because a partial accept would publish a tree the creator
+ * did not build.
+ */
+export declare function validatePathSet(paths: string[]): PathError | undefined;

package/dist/publish/paths.js

@@ -0,0 +1,78 @@
+// The dist-relative path rules, mirrored LOCALLY from the API's validator
+// (implementation.md §2.4.1) so the creator fails fast and local rather than
+// hashing 600 MB and learning from a 400.
+//
+// NORMALIZE THEN CHECK. A validator that checks the submitted string and stores a
+// different one has a seam between what it approved and what it signed; here the
+// normalized form is the only form that leaves this module.
+const MAX_PATH_BYTES = 1024;
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/;
+const LONE_SURROGATE = /[\ud800-\udfff]/;
+const SURROGATE_PAIR = /[\ud800-\udbff][\udc00-\udfff]/g;
+/**
+ * Normalize a dist-relative path, then check it. `a/./b.js` normalizes to
+ * `a/b.js` and is legal; `a/../../b.js` normalizes out of the tree and is not.
+ */
+export function normalizePath(raw) {
+    if (raw.includes("\\"))
+        return { ok: false, reason: "path_traversal" };
+    if (raw.startsWith("/"))
+        return { ok: false, reason: "absolute_path" };
+    if (/^[a-zA-Z]:/.test(raw))
+        return { ok: false, reason: "absolute_path" };
+    // The signed canonical key and the key the CLI PUTs come from two different
+    // encoders, and a literal `%` makes them ambiguous.
+    if (raw.includes("%"))
+        return { ok: false, reason: "bad_encoding" };
+    if (CONTROL_CHARS.test(raw))
+        return { ok: false, reason: "path_traversal" };
+    if (Buffer.byteLength(raw, "utf8") > MAX_PATH_BYTES) {
+        return { ok: false, reason: "path_traversal" };
+    }
+    // A lone surrogate survives a JS string but is not encodable UTF-8, so the API
+    // would see different bytes than the CLI hashed.
+    if (LONE_SURROGATE.test(raw.replace(SURROGATE_PAIR, ""))) {
+        return { ok: false, reason: "bad_encoding" };
+    }
+    const out = [];
+    for (const seg of raw.split("/")) {
+        // An empty segment is `a//b.js`; a `.` segment is noise. Both are rejected as
+        // whole segments rather than collapsed, per §2.4.1's MF-6 closure.
+        if (seg === "" || seg === "." || seg === "..") {
+            return { ok: false, reason: "path_traversal" };
+        }
+        out.push(seg);
+    }
+    if (out.length === 0)
+        return { ok: false, reason: "path_traversal" };
+    // Broader than `_platform` on purpose: a future platform prefix then needs no
+    // validator change, and Vite emits no leading-underscore top-level directory.
+    // Non-first segments are unaffected — `a/_b.js` is legal.
+    if (out[0].startsWith("_"))
+        return { ok: false, reason: "reserved_path" };
+    return { ok: true, path: out.join("/") };
+}
+/**
+ * Validate a whole set of normalized paths. The manifest is rejected as a WHOLE
+ * — never a subset — because a partial accept would publish a tree the creator
+ * did not build.
+ */
+export function validatePathSet(paths) {
+    const seen = new Set();
+    const seenLower = new Set();
+    for (const p of paths) {
+        if (seen.has(p))
+            return { reason: "duplicate_path", path: p };
+        seen.add(p);
+        // S3 is case-sensitive and macOS/Windows are not, so `Logo.png` + `logo.png`
+        // in one manifest means the creator's machine and the CDN disagree about
+        // what shipped.
+        const lower = p.toLowerCase();
+        if (seenLower.has(lower))
+            return { reason: "case_duplicate", path: p };
+        seenLower.add(lower);
+    }
+    if (!seen.has("index.html"))
+        return { reason: "no_index_html", path: "index.html" };
+    return undefined;
+}

package/dist/publish/progress.d.ts

@@ -0,0 +1,17 @@
+import type { UploadProgress } from "./upload.js";
+export interface ProgressSink {
+    update: (p: UploadProgress) => void;
+    /** Clear the redrawn line so the completion lines start clean. */
+    finish: () => void;
+}
+export interface ProgressDeps {
+    isTTY: boolean;
+    /** Raw write for the redraw path (no trailing newline). */
+    write: (s: string) => void;
+    /** Whole-line print for the degraded path. */
+    print: (line: string) => void;
+    now: () => number;
+    /** The degraded cadence ceiling. */
+    minIntervalMs?: number;
+}
+export declare function createProgress(deps: ProgressDeps): ProgressSink;

package/dist/publish/progress.js

@@ -0,0 +1,45 @@
+// The one redrawn line in f4 (Flow L27), and its non-TTY degrade.
+//
+// f3 forbade redrawing A STREAM, because scrollback and piping must stay true. A
+// bounded progress bar with a known total is not a stream, so this is a
+// legitimate exception to that rule — but only on a TTY. On a non-TTY it
+// degrades to periodic plain lines at MOST one per 2 seconds, so a piped log and
+// an agent transcript stay readable and finite.
+import { progressBar, progressPlain } from "./copy.js";
+// Carriage return + erase-line. Built from a code point so no literal control
+// byte lives in the source.
+const CLEAR_LINE = String.fromCharCode(13) + String.fromCharCode(27) + "[2K";
+export function createProgress(deps) {
+    const minInterval = deps.minIntervalMs ?? 2000;
+    let lastEmit = -Infinity;
+    let dirty = false;
+    if (!deps.isTTY) {
+        return {
+            update(p) {
+                const done = p.filesDone === p.filesTotal;
+                const t = deps.now();
+                // The last update always lands, so a piped log never stops short of the
+                // real total; everything else is rate-limited.
+                if (!done && t - lastEmit < minInterval)
+                    return;
+                if (done)
+                    return;
+                lastEmit = t;
+                deps.print(progressPlain(p.filesDone, p.filesTotal, p.bytesDone));
+            },
+            finish() {
+                // Nothing to clear: the degraded path emitted whole lines.
+            },
+        };
+    }
+    return {
+        update(p) {
+            dirty = true;
+            deps.write(CLEAR_LINE + progressBar(p.filesDone, p.filesTotal, p.bytesDone, p.bytesTotal));
+        },
+        finish() {
+            if (dirty)
+                deps.write(CLEAR_LINE);
+        },
+    };
+}

package/dist/publish/prompt.d.ts

@@ -0,0 +1,4 @@
+export type Confirm = (prompt: string, defaultYes: boolean) => Promise<boolean>;
+/** Reads one line from stdin. Anything that is not an explicit answer takes the default. */
+export declare function stdinConfirm(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Confirm;
+export declare function interpretAnswer(answer: string, defaultYes: boolean): boolean;

package/dist/publish/prompt.js

@@ -0,0 +1,31 @@
+// The one question in the product whose answer cannot be undone.
+//
+// `defaultYes` is what a bare Enter means, and the two stakes are genuinely
+// different: on a first publish an accidental Enter must do nothing; on a
+// republish it does the thing the creator typed the command to do.
+import readline from "node:readline";
+/** Reads one line from stdin. Anything that is not an explicit answer takes the default. */
+export function stdinConfirm(input = process.stdin, output = process.stdout) {
+    return async (prompt, defaultYes) => {
+        const rl = readline.createInterface({ input, output });
+        try {
+            const answer = await new Promise((resolve) => rl.question(prompt, resolve));
+            return interpretAnswer(answer, defaultYes);
+        }
+        finally {
+            rl.close();
+        }
+    };
+}
+export function interpretAnswer(answer, defaultYes) {
+    const normalized = answer.trim().toLowerCase();
+    if (normalized === "")
+        return defaultYes;
+    if (normalized === "y" || normalized === "yes")
+        return true;
+    if (normalized === "n" || normalized === "no")
+        return false;
+    // An answer we cannot read is not consent on a [y/N], and is not a refusal on
+    // a [Y/n] the creator meant to accept.
+    return defaultYes;
+}

package/dist/publish/qa.f4.fixtures.d.ts

@@ -0,0 +1,25 @@
+export type DistFixtureName = "CLEAN" | "TEMPLATE" | "MISSING_META" | "DEAD_IMAGE" | "MULTI_HTML" | "ADVERSARIAL" | "NO_DIST" | "OVERSIZE";
+/** The template defaults corpus the CLI ships, used verbatim by TEMPLATE. */
+export declare const TEMPLATE_TITLE = "Vite + React";
+export declare const TEMPLATE_DESCRIPTION = "Vite + React + TypeScript starter";
+/**
+ * distFixture materializes one named tree under a fresh temp dir and returns
+ * its cwd. The caller removes it.
+ */
+export declare function distFixture(name: DistFixtureName): Promise<string>;
+export declare function removeFixture(cwd: string): Promise<void>;
+/**
+ * The SHARED ADVERSARIAL ROWS. This list is the fixture the API's Go table test
+ * and this suite both read; row-count parity is asserted in both runners.
+ *
+ * `reason` is the closed-enum value the API answers with. A row whose reason
+ * differs between the two runners is a validator that disagrees with itself
+ * across a repo boundary, which shows up only as a publish that cannot succeed.
+ */
+export interface AdversarialRow {
+    name: string;
+    path: string;
+    /** "" means the row must be ACCEPTED. */
+    reason: string;
+}
+export declare function adversarialRows(): AdversarialRow[];

package/dist/publish/qa.f4.fixtures.js

@@ -0,0 +1,140 @@
+// QA f4 · the eight on-disk `dist/` trees the catalog names (4C / 4E).
+//
+// A distFixture is a REAL DIRECTORY, not a mock: the checklist parses HTML off
+// disk and the manifest hashes bytes off disk, so a fixture that stubbed either
+// would be asserting against a shape the product never reads.
+//
+// `ADVERSARIAL` is shared BYTE-FOR-BYTE with the API's validateManifest table —
+// one set of rows, read by both the Go table test and this vitest suite. A row
+// present in one runner and absent in the other fails the parity assertion, or
+// the shared fixture degrades into two fixtures with one name (f3's QA-F3-G11
+// lesson).
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** The template defaults corpus the CLI ships, used verbatim by TEMPLATE. */
+export const TEMPLATE_TITLE = "Vite + React";
+export const TEMPLATE_DESCRIPTION = "Vite + React + TypeScript starter";
+function html(opts) {
+    const parts = ["<!doctype html><html><head>"];
+    if (opts.title !== undefined)
+        parts.push(`<title>${opts.title}</title>`);
+    if (opts.ogTitle !== undefined) {
+        parts.push(`<meta property="og:title" content="${opts.ogTitle}">`);
+    }
+    if (opts.description !== undefined) {
+        parts.push(`<meta name="description" content="${opts.description}">`);
+    }
+    if (opts.ogImage !== undefined) {
+        parts.push(`<meta property="og:image" content="${opts.ogImage}">`);
+    }
+    parts.push("</head><body><div id=\"root\"></div></body></html>");
+    return parts.join("");
+}
+/**
+ * distFixture materializes one named tree under a fresh temp dir and returns
+ * its cwd. The caller removes it.
+ */
+export async function distFixture(name) {
+    const cwd = await fs.mkdtemp(path.join(os.tmpdir(), `vct-f4-${name.toLowerCase()}-`));
+    const dist = path.join(cwd, "dist");
+    if (name === "NO_DIST") {
+        // The ABSENCE of a dist/ directory IS the fixture.
+        return cwd;
+    }
+    await fs.mkdir(dist, { recursive: true });
+    switch (name) {
+        case "CLEAN": {
+            // A real title, description and og:image; og.png PRESENT; 6 files.
+            await fs.writeFile(path.join(dist, "index.html"), html({
+                title: "Harbour Wing — an AR walk",
+                description: "A guided AR tour of the Harbour Wing collection.",
+                ogImage: "/og.png",
+            }));
+            await fs.writeFile(path.join(dist, "og.png"), "png-bytes-clean");
+            await fs.mkdir(path.join(dist, "assets"), { recursive: true });
+            await fs.writeFile(path.join(dist, "assets", "app-a1b2c3.js"), "export const a=1;");
+            await fs.writeFile(path.join(dist, "assets", "app-d4e5f6.css"), "body{margin:0}");
+            await fs.writeFile(path.join(dist, "favicon.ico"), "ico-bytes");
+            await fs.writeFile(path.join(dist, "model.glb"), "glb-bytes");
+            return cwd;
+        }
+        case "TEMPLATE": {
+            // The template's own strings, untouched.
+            await fs.writeFile(path.join(dist, "index.html"), html({
+                title: TEMPLATE_TITLE,
+                description: TEMPLATE_DESCRIPTION,
+                ogImage: "/og.png",
+            }));
+            await fs.writeFile(path.join(dist, "og.png"), "png-bytes-template");
+            return cwd;
+        }
+        case "MISSING_META": {
+            // A title ONLY — no description, no og:image.
+            await fs.writeFile(path.join(dist, "index.html"), html({ title: "Harbour Wing — an AR walk" }));
+            return cwd;
+        }
+        case "DEAD_IMAGE": {
+            // og:image references /og.png, which is ABSENT from the tree. This is the
+            // ONLY fixture that produces a ✗.
+            await fs.writeFile(path.join(dist, "index.html"), html({
+                title: "Harbour Wing — an AR walk",
+                description: "A guided AR tour of the Harbour Wing collection.",
+                ogImage: "/og.png",
+            }));
+            return cwd;
+        }
+        case "MULTI_HTML": {
+            await fs.writeFile(path.join(dist, "index.html"), html({
+                title: "Harbour Wing — an AR walk",
+                description: "A guided AR tour of the Harbour Wing collection.",
+                ogImage: "/og.png",
+            }));
+            await fs.writeFile(path.join(dist, "og.png"), "png-bytes-multi");
+            // gallery.html has its OWN, DIFFERING findings.
+            await fs.writeFile(path.join(dist, "gallery.html"), html({ title: TEMPLATE_TITLE }));
+            return cwd;
+        }
+        case "ADVERSARIAL": {
+            // Paths only, and NO index.html at the root. The tree cannot literally
+            // contain "../escape.js" — the ROWS are the fixture, and they are shared
+            // with the Go table test through adversarialRows() below.
+            await fs.mkdir(path.join(dist, "sub"), { recursive: true });
+            await fs.writeFile(path.join(dist, "sub", "index.html"), html({ title: "nested" }));
+            return cwd;
+        }
+        case "OVERSIZE": {
+            // The bound variants are driven by SYNTHETIC MANIFEST ROWS rather than
+            // real bytes: writing 612 MB to a temp dir on every run would make the
+            // suite unusable, and the bound is checked against declared sizes before
+            // a byte moves — which is exactly the property under test.
+            await fs.writeFile(path.join(dist, "index.html"), html({ title: "big" }));
+            return cwd;
+        }
+    }
+    return cwd;
+}
+export async function removeFixture(cwd) {
+    await fs.rm(cwd, { recursive: true, force: true });
+}
+export function adversarialRows() {
+    return [
+        { name: "absolute", path: "/a.js", reason: "absolute_path" },
+        { name: "traversal", path: "../a.js", reason: "path_traversal" },
+        { name: "traversal_after_normalize", path: "a/../../b.js", reason: "path_traversal" },
+        { name: "backslash", path: "a\\b.js", reason: "backslash" },
+        { name: "empty_segment", path: "a//b.js", reason: "empty_segment" },
+        { name: "over_1024_bytes", path: `${"a".repeat(1025)}.js`, reason: "path_too_long" },
+        { name: "control_char", path: `a${String.fromCharCode(7)}b.js`, reason: "control_char" },
+        { name: "percent", path: "a%20b.js", reason: "bad_encoding" },
+        { name: "percent_2e2e", path: "a%2e%2e/b.js", reason: "bad_encoding" },
+        { name: "reserved_platform", path: "_platform/x.js", reason: "reserved_path" },
+        { name: "reserved_platform2", path: "_platform2/x.js", reason: "reserved_path" },
+        { name: "reserved_leading_underscore", path: "_anything/x.js", reason: "reserved_path" },
+        { name: "dot_segment", path: ".", reason: "path_traversal" },
+        { name: "dotdot_segment", path: "..", reason: "path_traversal" },
+        // THE ACCEPTED ROW. Without one the table passes on a validator that
+        // rejects everything.
+        { name: "nested_leading_underscore_is_ALLOWED", path: "a/_b.js", reason: "" },
+    ];
+}

package/dist/publish/upload.d.ts

@@ -0,0 +1,30 @@
+import type { UploadTarget } from "./api.js";
+import type { ManifestEntry } from "./manifest.js";
+export declare class UploadFailed extends Error {
+    readonly path: string;
+    readonly status: number;
+    readonly badDigest: boolean;
+    constructor(path: string, status: number, badDigest: boolean);
+}
+export interface UploadProgress {
+    filesDone: number;
+    filesTotal: number;
+    bytesDone: number;
+    bytesTotal: number;
+}
+export interface UploadOptions {
+    distDir: string;
+    targets: UploadTarget[];
+    manifest: ManifestEntry[];
+    concurrency?: number;
+    onProgress?: (p: UploadProgress) => void;
+    fetchImpl?: typeof fetch;
+    /** Per-file retries for a transient network/5xx failure. A BadDigest is retried once. */
+    maxAttempts?: number;
+}
+/**
+ * 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.
+ */
+export declare function uploadAll(opts: UploadOptions): Promise<void>;

package/dist/publish/upload.js

@@ -0,0 +1,93 @@
+// The S3 leg: one presigned PUT per file, bounded concurrency, resumable.
+//
+// THE HEADERS MAP IS FORWARDED VERBATIM — every key, including Content-Type and
+// x-amz-checksum-sha256. Both are covered by the SigV4 signature, so dropping
+// either yields SignatureDoesNotMatch. That reads as an auth bug and gets
+// "fixed" by deleting the header, which deletes the cost control in one case and
+// 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";
+import path from "node:path";
+export class UploadFailed extends Error {
+    path;
+    status;
+    badDigest;
+    constructor(path, status, badDigest) {
+        super(`upload failed for ${path} (${status})`);
+        this.path = path;
+        this.status = status;
+        this.badDigest = badDigest;
+        this.name = "UploadFailed";
+    }
+}
+const DEFAULT_CONCURRENCY = 6;
+/**
+ * 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.
+ */
+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 queue = [...opts.targets];
+    const maxAttempts = opts.maxAttempts ?? 3;
+    let filesDone = 0;
+    let bytesDone = 0;
+    const report = () => opts.onProgress?.({
+        filesDone,
+        filesTotal: opts.targets.length,
+        bytesDone,
+        bytesTotal,
+    });
+    report();
+    const worker = async () => {
+        for (;;) {
+            const target = queue.shift();
+            if (!target)
+                return;
+            await putOne(target, opts.distDir, fetchImpl, maxAttempts);
+            filesDone += 1;
+            bytesDone += sizes.get(target.path) ?? 0;
+            report();
+        }
+    };
+    const workers = Array.from({ length: Math.min(opts.concurrency ?? DEFAULT_CONCURRENCY, queue.length || 1) }, () => worker());
+    await Promise.all(workers);
+}
+async function putOne(target, distDir, fetchImpl, maxAttempts) {
+    const abs = path.join(distDir, ...target.path.split("/"));
+    const body = await fs.readFile(abs);
+    let lastStatus = 0;
+    let sawBadDigest = false;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        let res;
+        try {
+            res = await fetchImpl(target.url, {
+                method: "PUT",
+                // VERBATIM. No key dropped, no key added, no key renamed.
+                headers: { ...target.headers },
+                body: new Uint8Array(body),
+            });
+        }
+        catch {
+            lastStatus = 0;
+            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;
+        }
+    }
+    throw new UploadFailed(target.path, lastStatus, sawBadDigest);
+}

package/dist/relay/server.d.ts

@@ -1,6 +1,8 @@
 import { EventStore } from "./store.js";
+import { TesterRegistry } from "./testers.js";
 import { AnnotationStore } from "./annotations.js";
 import { type Dispatcher } from "./injectors.js";
+import type { DiagEvent } from "@vincentt-xr/harness/events";
 export interface RelayOptions {
     port?: number;
     /** WS path the client connects to (default matches HarnessProvider). */
@@ -15,10 +17,40 @@ export interface RelayOptions {
     dispatcher?: Dispatcher;
     /** Injected for tests. */
     makeId?: () => string;
+    /**
+     * Live tap for the CLI's terminal stream. It fires per batch as events land,
+     * so the creator sees a line the moment the phone produces it rather than on
+     * a poll. The relay still buffers everything — this is an addition, not a
+     * replacement, and a missing handler changes nothing.
+     */
+    onEvents?: (events: DiagEvent[], tags: EventTags) => void;
+    /**
+     * Fires ONCE per refused session when the tester cap is reached, so the CLI
+     * can print the one warning line. Once per session rather than once per batch:
+     * the registry holds a tombstone precisely so a chatty refused client cannot
+     * repaint the warning on every flush.
+     */
+    onCapReached?: () => void;
+    /** Injected for tests, so cap behavior is drivable without 64 real clients. */
+    testerRegistry?: TesterRegistry;
+}
+/** Who produced a batch: the connection's viewer label and its resolved tester. */
+export interface EventTags {
+    viewer?: string;
+    tester?: string;
 }
 export interface RelayHandle {
     store: EventStore;
     annotations?: AnnotationStore;
+    /** The run's tester registry — read-only to callers; the relay owns writes. */
+    testers: TesterRegistry;
     close: () => Promise<void>;
 }
 export declare function startRelay(opts?: RelayOptions): RelayHandle;
+/**
+ * readViewerLabel accepts ONLY `^viewer-[0-9]{1,4}$` and returns undefined for
+ * everything else — an array-valued header (a duplicate), a forged class, an
+ * ANSI escape, a newline. There is no "sanitize and keep" branch: a label that
+ * does not match is not a label, and the events simply carry no viewer.
+ */
+export declare function readViewerLabel(raw: string | string[] | undefined): string | undefined;