@vincentt-xr/cli 0.20.0 → 0.21.0

package/dist/preview/runner.js

@@ -26,6 +26,7 @@ import { withoutCliCredentials } from "../shared/config.js";
 import { ProjectUnreachableError } from "../lib/backend.js";
 import { AuthExpiredError } from "../shared/authError.js";
 import { apiFetch } from "../shared/http.js";
+import { UpgradeRequiredError, parseDeclared, parseMinimum, } from "../shared/upgradeError.js";
 import { terminalSafe } from "../lib/terminalText.js";
 /** The path a 404 advisory names: the request's own path, without its query. */
 export function requestPathOf(url) {
@@ -63,6 +64,17 @@ export async function startPreview(opts) {
     let heartbeat;
     let minted;
     let stopped = false;
+    // Set once the platform refuses this CLI's version: every later platform
+    // call would be refused too, so none is made.
+    let versionRefused = false;
+    const ended = (reason, refusal) => {
+        if (reason === "upgrade_required") {
+            versionRefused = true;
+            if (heartbeat !== undefined)
+                clearInterval(heartbeat);
+        }
+        opts.onEnded?.(reason, refusal);
+    };
     const stop = async () => {
         if (stopped)
             return;
@@ -84,8 +96,9 @@ export async function startPreview(opts) {
         // best-effort in intent even though it is in effect: the 12-hour ceiling
         // and the edge's 60-second fail-closed deadline both reap a session whose
         // DELETE never landed.
-        if (minted)
+        if (minted && !versionRefused) {
             await endPreviewSession(config, minted.sessionId, fetchImpl);
+        }
     };
     try {
         // The MINT comes first. Everything below it costs the creator a dev-server
@@ -231,7 +244,7 @@ export async function startPreview(opts) {
                     opts.onExpiring?.();
                     return;
                 }
-                opts.onEnded?.(reason);
+                ended(reason);
             },
             onOriginError: opts.onOriginError,
             onStateChange: opts.onTunnelState,
@@ -241,8 +254,12 @@ export async function startPreview(opts) {
             onReconnectRefused: (status) => {
                 const reason = refusalToReason(status);
                 if (reason !== null)
-                    opts.onEnded?.(reason);
+                    ended(reason);
             },
+            onRefused: (_reason, minimum, declared) => ended("upgrade_required", {
+                minimum: parseMinimum(minimum),
+                declared: parseDeclared(declared),
+            }),
         });
         tunnel.start();
         // The heartbeat is keepalive AND re-authorization: every beat re-runs
@@ -252,10 +269,10 @@ export async function startPreview(opts) {
         // One beat in flight at a time: a slow api must not stack up requests.
         let beating = false;
         heartbeat = setInterval(() => {
-            if (beating)
+            if (beating || versionRefused)
                 return;
             beating = true;
-            void runHeartbeat(config, minted.sessionId, fetchImpl, opts.onEnded).finally(() => {
+            void runHeartbeat(config, minted.sessionId, fetchImpl, ended).finally(() => {
                 beating = false;
             });
         }, minted.heartbeatSec * 1000);
@@ -284,18 +301,24 @@ export async function startPreview(opts) {
     }
 }
 /**
- * Two of the three CONTROL kinds are endings. `expiring` is NOT: it is the
- * hard-max warning, and it arrives on the same channel. Mapping it to an ending
- * would take away a link that has half an hour left, at exactly the moment the
- * creator is being warned to plan around it — so it returns null and the caller
- * renders the warning instead.
+ * Three of the four kinds that reach onControl are endings. `expiring` is NOT:
+ * it is the hard-max warning, and it arrives on the same channel. Mapping it to
+ * an ending would take away a link that has half an hour left, at exactly the
+ * moment the creator is being warned to plan around it, so it returns null and
+ * the caller renders the warning instead. (`viewer_gone` never reaches here.)
  */
 export function controlToReason(kind) {
-    if (kind === "superseded")
-        return "superseded";
-    if (kind === "revoke")
-        return "authz_revoked";
-    return null;
+    switch (kind) {
+        case "superseded":
+            return "superseded";
+        case "revoke":
+            return "authz_revoked";
+        case "authz_expired":
+            return "authz_lapsed";
+        case "expiring":
+        case "viewer_gone":
+            return null;
+    }
 }
 /**
  * A refused RECONNECT dial → the ending screen it means.
@@ -346,6 +369,10 @@ export async function runHeartbeat(config, sessionId, fetchImpl, onEnded) {
         await heartbeatPreviewSession(config, sessionId, fetchImpl);
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError) {
+            onEnded?.("upgrade_required", { minimum: err.minimum, declared: err.declared });
+            return;
+        }
         if (err instanceof AuthExpiredError) {
             onEnded?.("auth_expired");
             return;

package/dist/publish/api.js

@@ -5,9 +5,9 @@
 //
 // The bytes do NOT transit the API. Open returns one presigned PUT per file,
 // each signed for one exact key; the CLI PUTs direct to S3 and then commits.
-import { clientHeaders } from "../shared/clientHeader.js";
 import { rejectAuthExpired } from "../shared/authError.js";
-import { apiFetch } from "../shared/http.js";
+import { apiFetch, apiRequest } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 /**
  * The api's publish states, `domain.PublishState*`. apiPublishStates.test.ts
  * checks this list against the committed api capture, so a state the api adds
@@ -82,8 +82,12 @@ export class PublishApiError extends Error {
         this.name = "PublishApiError";
     }
 }
-/** Rejects with AuthExpiredError on a 401; every other status becomes a PublishApiError. */
+/**
+ * Rejects with UpgradeRequiredError on a 426 and AuthExpiredError on a 401;
+ * every other status becomes a PublishApiError.
+ */
 async function readError(res) {
+    await rejectUpgradeRequired(res);
     rejectAuthExpired(res);
     let body = {};
     try {
@@ -95,14 +99,10 @@ async function readError(res) {
     const retryAfter = res.headers.get("retry-after");
     return new PublishApiError(res.status, body.code ?? `http_${res.status}`, body.message ?? `request failed (${res.status})`, body.detail ?? {}, retryAfter ? Number(retryAfter) : undefined);
 }
-function authHeaders(cfg) {
-    return { ...clientHeaders(), authorization: `Bearer ${cfg.pat}` };
-}
+const AUTHENTICATED = { authenticated: true };
 /** The ONE call before the checklist. liveVersion + livePublishedAt ride it, by design. */
 export async function readProject(cfg, projectId, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}`, {
-        headers: authHeaders(cfg),
-    });
+    const res = await apiRequest(cfg, `/projects/${encodeURIComponent(projectId)}`, {}, AUTHENTICATED, fetchImpl);
     if (!res.ok)
         throw await readError(res);
     const raw = (await res.json());
@@ -137,15 +137,15 @@ export async function readProject(cfg, projectId, fetchImpl = apiFetch) {
  * and specific fact.
  */
 export async function openUpload(cfg, projectId, files, note, fetchImpl = apiFetch, builtWith) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/publishes`, {
+    const res = await apiRequest(cfg, `/projects/${encodeURIComponent(projectId)}/publishes`, {
         method: "POST",
-        headers: { ...authHeaders(cfg), "content-type": "application/json" },
+        headers: { "content-type": "application/json" },
         body: JSON.stringify({
             files,
             ...(note ? { note } : {}),
             ...(builtWith ? { builtWith } : {}),
         }),
-    });
+    }, AUTHENTICATED, fetchImpl);
     if (!res.ok)
         throw await readError(res);
     const body = (await res.json());
@@ -159,7 +159,7 @@ export async function openUpload(cfg, projectId, files, note, fetchImpl = apiFet
     };
 }
 export async function commitUpload(cfg, projectId, uploadId, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/publishes/${encodeURIComponent(uploadId)}/commit`, { method: "POST", headers: authHeaders(cfg) });
+    const res = await apiRequest(cfg, `/projects/${encodeURIComponent(projectId)}/publishes/${encodeURIComponent(uploadId)}/commit`, { method: "POST" }, AUTHENTICATED, fetchImpl);
     if (!res.ok)
         throw await readError(res);
     let raw;
@@ -174,7 +174,7 @@ export async function commitUpload(cfg, projectId, uploadId, fetchImpl = apiFetc
 /** Abandon an open upload. Idempotent server-side; a failure here must never mask the real error. */
 export async function abandonUpload(cfg, projectId, uploadId, fetchImpl = apiFetch) {
     try {
-        await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/publishes/${encodeURIComponent(uploadId)}`, { method: "DELETE", headers: authHeaders(cfg) });
+        await apiRequest(cfg, `/projects/${encodeURIComponent(projectId)}/publishes/${encodeURIComponent(uploadId)}`, { method: "DELETE" }, AUTHENTICATED, fetchImpl);
     }
     catch {
         // Best-effort cleanup: the TTL reaps the row either way.

package/dist/publish/command.d.ts

@@ -3,6 +3,7 @@ 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";
+import { type ReadHead } from "./weight.js";
 export interface PublishDeps {
     print: (line: string) => void;
     /** Raw write, for the redrawn progress line only. */
@@ -42,6 +43,8 @@ export interface PublishDeps {
     probeFetch?: typeof fetch;
     /** Where the --json document goes (stdout). Defaults to print. */
     emit?: (line: string) => void;
+    /** The Heavy files section's image read, by output-relative path. Injected for tests; defaults to a read under the output folder. */
+    readHead?: ReadHead;
 }
 export interface PublishOptions {
     distDir?: string;

package/dist/publish/command.js

@@ -15,19 +15,22 @@ import { buildManifest, ManifestError } from "./manifest.js";
 import { checkBounds } from "./bounds.js";
 import { classifyDist } from "./classify.js";
 import { createProgress } from "./progress.js";
-import { UploadExpired, UploadFailed, uploadAll } from "./upload.js";
+import { UploadExpired, UploadFailed, UploadTargetRejected, uploadAll, } from "./upload.js";
+import { escapeTerminal } from "../lib/terminalText.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";
 import { AuthExpiredError, authExpiredLines } from "../shared/authError.js";
+import { UpgradeRequiredError, upgradeRefusalLines, } from "../shared/upgradeError.js";
 import { EXIT } from "../lib/exitCodes.js";
 import { apiFetch, isTransportError } from "../shared/http.js";
 import { resolveBuiltWith } from "../platform/resolve.js";
 import { readSettings, resolveSettings, SettingsError, TEMPLATE_DEFAULTS, } from "../lib/settings.js";
 import { settingsRefusal } from "../lib/settingsCopy.js";
 import { rootAbsoluteFindings } from "./fit.js";
+import { heavyFileFindings } from "./weight.js";
 const COMMIT_RETRIES = 3;
 const COMMIT_RETRY_DELAY_MS = 2000;
 export async function publishCommand(deps, opts = {}) {
@@ -91,13 +94,11 @@ async function runPublish(deps, opts, onCommitted) {
     }
     catch (err) {
         if (err instanceof ManifestError) {
-            if (err.reason === "secret_path" || err.reason === "lfs_pointer") {
+            const block = outputRefusal(err, output, buildCommand);
+            if (block !== undefined) {
                 deps.print(copy.headerLine(await projectLabel(deps, binding.slug), await orgOf(deps)));
                 deps.print(copy.readingLine(err.stats?.files ?? 0, err.stats?.bytes ?? 0, output));
-                const lines = err.reason === "secret_path"
-                    ? copy.secretFiles(err.paths, output)
-                    : copy.lfsPointers(err.paths, output, buildCommand ?? undefined);
-                for (const l of lines)
+                for (const l of block)
                     deps.print(l);
                 return 1;
             }
@@ -129,6 +130,11 @@ async function runPublish(deps, opts, onCommitted) {
         project = await readProject(cfg, binding.projectId, fetchImpl);
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError) {
+            deps.print(copy.headerLine(await projectLabel(deps, binding.slug), await orgOf(deps)));
+            deps.print(copy.readingLine(manifest.files.length, manifest.totalBytes, output));
+            return refusedVersion(deps, err, { kind: "publish" });
+        }
         if (err instanceof AuthExpiredError)
             return authExpired(deps);
         if (err instanceof PublishApiError && err.status === 404) {
@@ -172,6 +178,8 @@ async function runPublish(deps, opts, onCommitted) {
     const manifestPaths = new Set(manifest.files.map((f) => f.path));
     const findings = await classifyDist(distDir, manifestPaths, (abs) => fs.readFile(abs, "utf8"), (dir, rel) => path.join(dir, ...rel.split("/")), { expectedHost: address });
     const rootAbsolute = rootAbsoluteFindings(await readHtmlFiles(distDir, manifest), manifestPaths);
+    // Warning-only: a fault in this section never changes the exit code.
+    const heavy = await heavyFileFindings(manifest.files, deps.readHead ?? ((rel, n) => readFileHead(path.join(distDir, ...rel.split("/")), n))).catch(() => []);
     const checklistInput = {
         projectName: project.name,
         orgName,
@@ -182,6 +190,7 @@ async function runPublish(deps, opts, onCommitted) {
         findings,
         output,
         rootAbsolute,
+        heavy,
     };
     let promptLine;
     let defaultYes;
@@ -261,6 +270,9 @@ async function runPublish(deps, opts, onCommitted) {
 async function runUpload(deps, cfg, i) {
     const open = () => openUpload(cfg, i.projectId, i.manifest.files, i.note, i.fetchImpl, i.builtWith);
     const openFailed = (err) => {
+        if (err instanceof UpgradeRequiredError) {
+            return refusedVersion(deps, err, { kind: "publish", address: i.address });
+        }
         if (err instanceof AuthExpiredError)
             return authExpired(deps);
         for (const l of openErrorLines(err, i.address, i.liveVersion, i.org))
@@ -328,7 +340,11 @@ async function runUpload(deps, cfg, i) {
                 deps.print(l);
             return 1;
         }
-        const failedPath = err instanceof UploadFailed || err instanceof UploadExpired ? err.path : "a file";
+        const failedPath = err instanceof UploadFailed ||
+            err instanceof UploadExpired ||
+            err instanceof UploadTargetRejected
+            ? escapeTerminal(err.path)
+            : "a file";
         deps.print("");
         deps.print(`✗ Uploading ${failedPath} failed.`);
         deps.print("");
@@ -365,6 +381,15 @@ async function commitWithHealing(deps, cfg, i, uploadId) {
             return 0;
         }
         catch (err) {
+            // A version refusal is final: COMMIT_RETRIES is for transient failures,
+            // and each retry would be one more refused call.
+            if (err instanceof UpgradeRequiredError) {
+                return refusedVersion(deps, err, {
+                    kind: "publish",
+                    address: i.address,
+                    stillServing: i.liveVersion,
+                });
+            }
             // The token can lapse during a long upload. The files are stored and the
             // live address is unchanged, so signing in and publishing again is safe.
             if (err instanceof AuthExpiredError)
@@ -533,6 +558,21 @@ function openErrorLines(err, address, liveVersion, org) {
 function numericLimit(limit) {
     return typeof limit === "number" ? limit : 0;
 }
+/** The refusals about what the output holds, printed after the header and reading line. */
+function outputRefusal(err, output, buildCommand) {
+    switch (err.reason) {
+        case "secret_path":
+            return copy.secretFiles(err.paths, output);
+        case "credential_file":
+            return copy.credentialFiles(err.paths, output);
+        case "file_unreadable":
+            return copy.fileUnreadable(err.offendingPath, output);
+        case "lfs_pointer":
+            return copy.lfsPointers(err.paths, output, buildCommand ?? undefined);
+        default:
+            return undefined;
+    }
+}
 function manifestErrorLines(err, distDir, ctx) {
     if (err.reason === "no_dist")
         return copy.noDist(distDir, ctx.buildCommand);
@@ -559,6 +599,24 @@ function outputLabelOf(root, distDir, source) {
             : "";
     return { folder, sourceNote };
 }
+/** The first `n` bytes of a file, or fewer if it is shorter. */
+async function readFileHead(abs, n) {
+    const handle = await fs.open(abs, "r");
+    try {
+        const buf = Buffer.alloc(n);
+        let got = 0;
+        while (got < n) {
+            const { bytesRead } = await handle.read(buf, got, n - got, got);
+            if (bytesRead === 0)
+                break;
+            got += bytesRead;
+        }
+        return buf.subarray(0, got);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
 /** Every `.html` in the manifest, for the root-absolute reference check. */
 async function readHtmlFiles(distDir, manifest) {
     const out = [];
@@ -588,6 +646,12 @@ function addressOf(project) {
         return project.liveUrl.replace(/^https?:\/\//, "").replace(/\/$/, "");
     }
 }
+/** The platform refused this CLI's version. Nothing further is sent. */
+function refusedVersion(deps, err, arm) {
+    for (const l of upgradeRefusalLines(err, arm))
+        deps.print(l);
+    return EXIT.UPGRADE_REQUIRED;
+}
 /** The api refused the token: the sign-in remedy, and the not-signed-in exit code. */
 function authExpired(deps) {
     for (const l of authExpiredLines())

package/dist/publish/copy.d.ts

@@ -1,6 +1,7 @@
 import type { FileFindings } from "./classify.js";
 import type { BoundViolation } from "./bounds.js";
 import type { RootAbsoluteFinding } from "./fit.js";
+import type { HeavyFinding } from "./weight.js";
 import type { Offender } from "./manifest.js";
 export declare function truncate(value: string, max?: number): string;
 /** Bytes as the creator reads them. Decimal MB, matching what a build tool prints. */
@@ -46,6 +47,8 @@ export interface ChecklistInput {
     output?: OutputLabel;
     /** Root-absolute references that do not resolve. The section is absent when empty. */
     rootAbsolute?: RootAbsoluteFinding[];
+    /** Models and images over the weight limits. The section is absent when empty. */
+    heavy?: HeavyFinding[];
 }
 /**
  * The `Paths from the root` section: a second section of the checklist, same
@@ -53,6 +56,8 @@ export interface ChecklistInput {
  * empty heading. One explanation for the whole section.
  */
 export declare function pathsFromRootLines(findings: RootAbsoluteFinding[] | undefined, folder?: string): string[];
+/** The `Heavy files` section: warning-only, absent when there are no findings. */
+export declare function heavyFileLines(findings: HeavyFinding[] | undefined): string[];
 /**
  * The output folder as the creator reads it, `dist/` for the template. The
  * source is appended only when it is not the default, so the template's
@@ -171,6 +176,10 @@ export declare function outputOutside(shown: string): string[];
 export declare function outputInHidden(shown: string, hidden: string): string[];
 /** Flow U1 — hidden names or symlinks that would leak. After the header and reading line. */
 export declare function secretFiles(paths: Offender[], output?: OutputLabel): string[];
+/** Flow U1 — credential files, from the early checks or the hash step. After the header and reading line. */
+export declare function credentialFiles(paths: Offender[], output?: OutputLabel): string[];
+/** Flow U1 — a file that changed, became a link, or could not be read while checked or hashed. */
+export declare function fileUnreadable(filePath: string, output?: OutputLabel): string[];
 /** Flow U1 — Git LFS pointer files. The recorded build.command, verbatim, when there is one. */
 export declare function lfsPointers(paths: Offender[], output?: OutputLabel, buildCommand?: string): string[];
 /** A local path rule the creator's own build broke. Local, before any request. */

package/dist/publish/copy.js

@@ -12,7 +12,7 @@
 // NEVER PRINTED, at any point, in any state: the project id, the org id, the
 // uploadId, the PAT, any presigned URL or fragment of one, the bucket, any S3
 // key, or a per-file upload log.
-import { escapeControl } from "../lib/terminalText.js";
+import { escapeTerminal } from "../lib/terminalText.js";
 /** The only horizontal rules in any f4 output. They exist here and nowhere else. */
 const RULE = "  ─────────────────────────────────────────────────────────────────────";
 const LABELS = {
@@ -166,11 +166,33 @@ export function pathsFromRootLines(findings, folder = "dist/") {
     out.push("", "    Vincentt serves this app at the root of its address. A missing path that", "    starts with / usually means the build was made for a subpath, such as a", "    GitHub Pages project site. Nothing here blocks you.", "");
     return out;
 }
+/** The `Heavy files` section: warning-only, absent when there are no findings. */
+export function heavyFileLines(findings) {
+    if (!findings || findings.length === 0)
+        return [];
+    const out = ["  Heavy files  (each one downloads to the phone before it can show)", ""];
+    for (const f of findings.slice(0, FINDINGS_SHOWN)) {
+        const name = escapeTerminal(f.path);
+        if (f.kind === "model") {
+            out.push(`    !  ${name} is ${formatBytes(f.bytes)}`);
+            out.push(`${" ".repeat(21)}a model over 10 MB`);
+        }
+        else {
+            out.push(`    !  ${name} is ${f.width} x ${f.height} px`);
+            out.push(`${" ".repeat(21)}an image over 2048 px on its long side`);
+        }
+    }
+    if (findings.length > FINDINGS_SHOWN) {
+        out.push(`    and ${findings.length - FINDINGS_SHOWN} more`);
+    }
+    out.push("", "    Every phone that opens this app downloads these files over its own", "    connection. Compress the model or shrink the image, then build again.", "    Nothing here blocks you.", "");
+    return out;
+}
 const DEFAULT_OUTPUT = { folder: "dist/", sourceNote: "" };
 export function readingLine(fileCount, totalBytes, output = DEFAULT_OUTPUT) {
     const note = output.sourceNote ? ` ${output.sourceNote}` : "";
     // The folder is the creator's build.output or --dist, so it is escaped.
-    return `→ Reading ${escapeControl(output.folder)}${note} … ${fileCount} files · ${formatBytes(totalBytes)}`;
+    return `→ Reading ${escapeTerminal(output.folder)}${note} … ${fileCount} files · ${formatBytes(totalBytes)}`;
 }
 export function headerLine(projectName, orgName) {
     return orgName ? `→ ${projectName} · ${orgName}` : `→ ${projectName}`;
@@ -211,6 +233,7 @@ export function firstPublishChecklist(i) {
         ...findingLines(i.findings, true, i.output?.folder),
         ...nothingBlocksYou(),
         ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
+        ...heavyFileLines(i.heavy),
         `  Publishing v${i.nextVersion} · ${i.fileCount} files · ${formatBytes(i.totalBytes)}`,
         "",
     ];
@@ -255,6 +278,7 @@ export function republishChecklist(i) {
         "",
         ...findingLines(i.findings, false, i.output?.folder),
         ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
+        ...heavyFileLines(i.heavy),
     ];
 }
 /** `[Y/n]` — on a republish an accidental Enter does the thing the creator typed the command to do. */
@@ -279,6 +303,7 @@ export function offlineChecklist(i) {
         "",
         ...findingLines(i.findings, false, i.output?.folder),
         ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
+        ...heavyFileLines(i.heavy),
     ];
 }
 export function offlinePrompt(version) {
@@ -303,6 +328,7 @@ export function notServingChecklist(i, stateKnown) {
         "",
         ...findingLines(i.findings, false, i.output?.folder),
         ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
+        ...heavyFileLines(i.heavy),
     ];
 }
 /** `[y/N]`: the CLI cannot say what this publish changes, so Enter does nothing. */
@@ -455,7 +481,7 @@ export function noDist(distDir, buildCommand) {
         "",
         "  Nothing was uploaded.",
         "",
-    ].map(escapeControl);
+    ].map(escapeTerminal);
 }
 export function noIndexHtml(distDir, buildCommand) {
     return [
@@ -469,7 +495,7 @@ export function noIndexHtml(distDir, buildCommand) {
         "",
         "  Nothing was uploaded.",
         "",
-    ].map(escapeControl);
+    ].map(escapeTerminal);
 }
 /** Flow U1 — the output is the project folder itself. */
 export function outputIsRoot(o) {
@@ -487,13 +513,13 @@ export function outputIsRoot(o) {
         "",
         "  Nothing was uploaded.",
         "",
-    ].map(escapeControl);
+    ].map(escapeTerminal);
 }
 /** Flow U1 — the output lies outside the project. `shown` is project-relative. */
 export function outputOutside(shown) {
     return [
         "",
-        `✗ The build output ${escapeControl(shown)} is outside this project.`,
+        `✗ The build output ${escapeTerminal(shown)} is outside this project.`,
         "",
         "  Publish uploads a folder inside the project. Set --dist, or build.output in",
         "  vincentt.json, to the folder your build writes.",
@@ -506,7 +532,7 @@ export function outputOutside(shown) {
 export function outputInHidden(shown, hidden) {
     return [
         "",
-        `✗ The build output ${escapeControl(shown)} is inside ${hidden}/, not a build.`,
+        `✗ The build output ${escapeTerminal(shown)} is inside ${hidden}/, not a build.`,
         "",
         "  Publishing it would put your repository's history or its Vincentt link at a",
         "  public address. Set --dist, or build.output in vincentt.json, to the folder",
@@ -516,18 +542,30 @@ export function outputInHidden(shown, hidden) {
         "",
     ];
 }
+/** Where a credential reason starts, unless a longer path pushes it right. */
+const WHY_COLUMN = 40;
+const CREDENTIAL_WHY = {
+    name: "named like a credential",
+    private_key: "holds a private key",
+    service_account: "holds a service-account key",
+    authorized_user: "holds a Google sign-in credential",
+};
 function offenderList(paths, folder) {
     // File names and the folder prefix come from the build and the creator's
     // settings, and may carry control characters.
-    folder = escapeControl(folder);
+    folder = escapeTerminal(folder);
     const shown = paths.slice(0, FINDINGS_SHOWN).map((p) => ({
-        path: escapeControl(p.path),
-        target: p.target === undefined ? undefined : escapeControl(p.target),
+        path: escapeTerminal(p.path),
+        target: p.target === undefined ? undefined : escapeTerminal(p.target),
+        why: p.why,
     }));
     const width = Math.max(...shown.map((p) => folder.length + p.path.length));
+    const whyColumn = Math.max(WHY_COLUMN, width + 3);
     const out = shown.map((p) => p.target !== undefined
         ? `    ${(folder + p.path).padEnd(width)}   links to ${p.target}`
-        : `    ${folder}${p.path}`);
+        : p.why !== undefined
+            ? `    ${(folder + p.path).padEnd(whyColumn)}${CREDENTIAL_WHY[p.why]}`
+            : `    ${folder}${p.path}`);
     if (paths.length > FINDINGS_SHOWN)
         out.push(`    and ${paths.length - FINDINGS_SHOWN} more`);
     return out;
@@ -540,13 +578,44 @@ export function secretFiles(paths, output = DEFAULT_OUTPUT) {
         "",
         ...offenderList(paths, output.folder),
         "",
-        `  Everything in ${escapeControl(output.folder)} becomes public at your address. Remove these from the build`,
+        `  Everything in ${escapeTerminal(output.folder)} becomes public at your address. Remove these from the build`,
         "  output, rebuild, then publish.",
         "",
         "  Nothing was uploaded.",
         "",
     ];
 }
+/** Flow U1 — credential files, from the early checks or the hash step. After the header and reading line. */
+export function credentialFiles(paths, output = DEFAULT_OUTPUT) {
+    return [
+        "",
+        "✗ This build holds files that look like private keys.",
+        "",
+        ...offenderList(paths, output.folder),
+        "",
+        `  Everything in ${escapeTerminal(output.folder)} becomes public at your address, and a published version`,
+        "  cannot be taken back. Move these out of the build output, rebuild, then",
+        "  publish. A file only named like a key, such as a Keynote .key, needs a new",
+        "  name.",
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
+/** Flow U1 — a file that changed, became a link, or could not be read while checked or hashed. */
+export function fileUnreadable(filePath, output = DEFAULT_OUTPUT) {
+    return [
+        "",
+        `✗ ${escapeTerminal(output.folder + filePath)} changed while publish was reading it.`,
+        "",
+        "  It became a link or a different file, or could not be read, so publish",
+        "  cannot vouch for what it would upload. Let your build finish, then publish",
+        "  again.",
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
 /** Flow U1 — Git LFS pointer files. The recorded build.command, verbatim, when there is one. */
 export function lfsPointers(paths, output = DEFAULT_OUTPUT, buildCommand) {
     return [
@@ -560,7 +629,7 @@ export function lfsPointers(paths, output = DEFAULT_OUTPUT, buildCommand) {
         "",
         "    git lfs pull",
         buildCommand !== undefined
-            ? `    ${escapeControl(buildCommand)}`
+            ? `    ${escapeTerminal(buildCommand)}`
             : "    then run your build again",
         "",
         "  Nothing was uploaded.",
@@ -581,7 +650,7 @@ export function badPath(reason, offending) {
         "",
         `✗ This build ${why[reason] ?? "has a path we can't publish"}.`,
         "",
-        `    ${escapeControl(offending)}`,
+        `    ${escapeTerminal(offending)}`,
         "",
         "  Rename it in your source, rebuild, then publish again.",
         "",

package/dist/publish/keyScan.d.ts

@@ -0,0 +1,25 @@
+/** The label is bounded to 40 characters so the carried tail stays finite. */
+export declare const KEY_HEADER: RegExp;
+/**
+ * A newline (real, or the two-character `\n` or four-character `\r\n` of a
+ * string literal), then a base64 line.
+ */
+export declare const KEY_BODY: RegExp;
+/** Below this offset a header alone is a match. */
+export declare const HEAD_BYTES = 4096;
+/** How far past a header its key body may sit. */
+export declare const BODY_WINDOW = 256;
+export interface KeyScanner {
+    /** Feed the next chunk, as latin1. */
+    push(chunk: string): void;
+    /** Judge any header still waiting on its body window. True when a key was seen. */
+    end(): boolean;
+    readonly matched: boolean;
+}
+export declare function createKeyScanner(): KeyScanner;
+export type CredentialJsonType = "service_account" | "authorized_user";
+/**
+ * The top-level `type` of a Google credential JSON, or undefined. A parse
+ * failure is "not a match" and its message is discarded: it echoes the input.
+ */
+export declare function credentialJson(bytes: Uint8Array): CredentialJsonType | undefined;