@vincentt-xr/cli 0.20.0 → 0.21.0

package/MIGRATION.md

@@ -3,6 +3,21 @@
 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.21.0
+
+required: false
+No action required unless a build output holds a credential file. Behaviour that changed:
+- `vincentt publish` refuses a build output that holds a file or folder named like a credential (`credentials.json`, `service-account*.json`, `*firebase-adminsdk*.json`, `*.key`, `*.p12`, `*.pfx`, `*.p8`, `*.ppk`, `id_rsa*`, `id_dsa*`, `id_ed25519*`, `id_ecdsa*`, `*.jks`, `*.keystore`, `*.env`, `*.tfstate`, `*.tfvars`, and their `~`, `.bak`, `.gz`, `.br` or `.zst` copies, in any letter case).
+- `vincentt publish` also refuses a build output holding a file with a private key (including one a bundler inlined into JavaScript from an environment variable), or a Google service-account or user credential JSON.
+- A file that changes or becomes a link while publish reads it is also refused.
+- A publish that worked before can now be refused, with no override: move the file out of the build output (or rename an asset such as a Keynote `.key`) and rebuild. Public `.pem` certificates are still published.
+- `vincentt publish` can print a new "Heavy files" warning section in the checklist (a model over 10 MB, or an image over 2048 px on its long side); exit codes and prompts are unchanged.
+- Every request the CLI makes to the platform, including a preview's start, check-in and stop, and every preview tunnel connection, now says which CLI version is calling (`X-Vincentt-Client: cli/<version>`).
+- A new exit code, 5: the platform refused this CLI's version and nothing was changed on the platform. `create` may already have written the project, and its screen says where. No minimum version is set by this release, so nothing is refused yet.
+- On exit 5 the screen names this CLI's version, the minimum it needs and how to upgrade; `publish --json` prints `{"state":"failed","exitCode":5}`; the newer-version notice is not printed after it. When the platform received no version at all, the screen asks for a report instead of an upgrade.
+- `vincentt preview` has two new endings: the CLI is too old (exit 5), and "Vincentt stopped confirming it" when the platform stops confirming a running preview (exit 1, and no new preview is started on its own). The "Couldn't confirm your access to this project." ending is gone.
+- A request body sent to a preview with no declared length (chunked, or HTTP/2 without Content-Length) now reaches the dev server whole, sent with `Transfer-Encoding: chunked`, and a request with no body completes at once. Against a platform edge that predates this release the previous behaviour stays. Each forwarded request uses its own connection to the dev server, and a request whose Content-Length disagrees with its body is reset on its own without ending the preview.
+
 ## 0.20.0
 
 required: false

package/dist/cli/index.js

@@ -24,6 +24,7 @@ import { fileLocationStore } from "../shared/locationStore.js";
 import { getMe, listProjects, ProjectUnreachableError } from "../lib/backend.js";
 import { EXIT } from "../lib/exitCodes.js";
 import { AuthExpiredError, authExpiredLines, isAuthRefused, NOT_SIGNED_IN_LINES, NotSignedInError, } from "../shared/authError.js";
+import { UpgradeRequiredError, upgradeRefusalLines, } from "../shared/upgradeError.js";
 import { listProjectsCommand } from "../lib/listProjects.js";
 import { initCommand } from "../lib/initCommand.js";
 import { linkCommand, printUnreachable, unlinkCommand } from "../lib/projects.js";
@@ -340,6 +341,7 @@ async function create() {
         dir = safe;
     }
     const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+    const consoleUrl = (await resolveAuthUrls()).consoleUrl;
     const result = await projectCreate(projectDir(), {
         name: flag("--name"),
         slug: flag("--slug"),
@@ -354,8 +356,18 @@ async function create() {
             await login();
         },
         orgSource,
-        consoleUrl: (await resolveAuthUrls()).consoleUrl,
+        consoleUrl,
         onLine: (l) => console.log(l),
+    }).catch((err) => {
+        // Registration is refused after the source is already on disk, so the
+        // screen says where it is.
+        if (!(err instanceof UpgradeRequiredError))
+            throw err;
+        const where = dir === undefined ? undefined : `./${dir}`;
+        for (const l of upgradeRefusalLines(err, { kind: "create", dir: where })) {
+            console.log(l);
+        }
+        return { message: "", exitCode: EXIT.UPGRADE_REQUIRED };
     });
     if (result.exitCode !== 0) {
         process.exitCode = result.exitCode;
@@ -627,7 +639,18 @@ async function preview() {
         }
     }
     let ending = null;
+    let endingRefusal;
     let resolveDone;
+    const refusedAtStart = (facts) => {
+        for (const l of upgradeRefusalLines(facts, {
+            kind: "preview_start",
+            devCommand,
+            localUrl: handRunUrl,
+        })) {
+            console.log(l);
+        }
+        process.exitCode = EXIT.UPGRADE_REQUIRED;
+    };
     const done = new Promise((r) => {
         resolveDone = r;
     });
@@ -656,8 +679,9 @@ async function preview() {
             onOriginError: () => ui.originError(),
             onOriginRecovered: () => ui.originRecovered(),
             onExpiring: () => ui.checkHardMax(running?.expiresAt ?? ""),
-            onEnded: (reason) => {
+            onEnded: (reason, refusal) => {
                 ending = reason;
+                endingRefusal = refusal;
                 resolveDone?.();
             },
         });
@@ -669,6 +693,11 @@ async function preview() {
         }
     }
     catch (err) {
+        // Refused by the mint, before the dev server was spawned: nothing to stop.
+        if (err instanceof UpgradeRequiredError) {
+            refusedAtStart(err);
+            return;
+        }
         // The local org is the FALLBACK only. A count refusal names the org that
         // owns this project, and the wire's name wins over this one wherever both
         // exist — see resolveCountLimit.
@@ -678,6 +707,13 @@ async function preview() {
         process.exitCode = err instanceof AuthExpiredError ? EXIT.NOT_AUTHENTICATED : 1;
         return;
     }
+    // A first dial refused before the start block printed: the creator never saw
+    // a link, so this is the start-time screen, not the running preview's ending.
+    if (ending === "upgrade_required") {
+        await previewStop();
+        refusedAtStart(endingRefusal ?? {});
+        return;
+    }
     const qr = shouldRenderQr({
         isTTY: Boolean(process.stdout.isTTY),
         noQr: has("--no-qr"),
@@ -714,11 +750,19 @@ async function preview() {
     await done;
     clearInterval(ceiling);
     if (ending !== null) {
-        ui.endedBy(ending, (await activeOrgName()) || "your workspace");
+        ui.endedBy(ending, (await activeOrgName()) || "your workspace", endingRefusal);
         await previewStop();
-        process.exitCode = ending === "auth_expired" ? EXIT.NOT_AUTHENTICATED : 1;
+        process.exitCode = previewExitCode(ending);
     }
 }
+/** A preview's ending → its exit: 5 for a version refusal, 4 for a refused token, else 1. */
+function previewExitCode(ending) {
+    if (ending === "upgrade_required")
+        return EXIT.UPGRADE_REQUIRED;
+    if (ending === "auth_expired")
+        return EXIT.NOT_AUTHENTICATED;
+    return EXIT.FAILED;
+}
 /** A `--port` or `--dev-command` value the schema refuses, before anything runs. */
 function previewFlagRefusal(port, devCommand) {
     const portMessage = port === undefined
@@ -1530,8 +1574,12 @@ function journal(exitCode, error) {
     // a notice is worth nothing if it costs a second on every publish.
     try {
         const cached = loadCache();
-        for (const l of updateNotice(cliVersion(), cached?.latest))
-            console.error(l);
+        // Suppressed on a version refusal: the ending already names the number that
+        // matters, and a stale cache could name a `latest` below the floor.
+        if (exitCode !== EXIT.UPGRADE_REQUIRED) {
+            for (const l of updateNotice(cliVersion(), cached?.latest))
+                console.error(l);
+        }
         if (!isFresh(cached, Date.now()))
             refreshUpdateCache();
     }
@@ -1623,6 +1671,15 @@ main()
         journal(EXIT.NOT_AUTHENTICATED, err);
         process.exit(EXIT.NOT_AUTHENTICATED);
     }
+    // L22's generic screen, for every verb without its own arm. Prose on the
+    // verb's usual channel, or stderr under --json so stdout stays a document.
+    if (err instanceof UpgradeRequiredError) {
+        const say = has("--json") ? console.error : console.log;
+        for (const l of upgradeRefusalLines(err))
+            say(l);
+        journal(EXIT.UPGRADE_REQUIRED, err);
+        process.exit(EXIT.UPGRADE_REQUIRED);
+    }
     if (isAuthRefused(err)) {
         for (const l of authExpiredLines())
             console.error(l);

package/dist/domain/api.js

@@ -12,9 +12,9 @@
 // ordinary indistinguishable 404 before the hostname is read at all. The CLI
 // therefore cannot distinguish "no such project" from "not your project" — and
 // must not try.
-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";
 import { parseDomain, parseDomainList, } from "./wire.js";
 export class DomainApiError extends Error {
     status;
@@ -30,8 +30,12 @@ export class DomainApiError extends Error {
         this.name = "DomainApiError";
     }
 }
-/** Rejects with AuthExpiredError on a 401; every other status becomes a DomainApiError. */
+/**
+ * Rejects with UpgradeRequiredError on a 426 and AuthExpiredError on a 401;
+ * every other status becomes a DomainApiError.
+ */
 async function readError(res) {
+    await rejectUpgradeRequired(res);
     rejectAuthExpired(res);
     let body = {};
     try {
@@ -44,8 +48,8 @@ async function readError(res) {
     const retryAfter = res.headers.get("retry-after");
     return new DomainApiError(res.status, body.code ?? `http_${res.status}`, body.message ?? `request failed (${res.status})`, { attached: num(body.attached), entitled: num(body.entitled) }, retryAfter ? Number(retryAfter) : undefined);
 }
-function authHeaders(cfg) {
-    return { ...clientHeaders(), authorization: `Bearer ${cfg.pat}` };
+function call(cfg, path, init, fetchImpl) {
+    return apiRequest(cfg, path, init, { authenticated: true }, fetchImpl);
 }
 function rolesOf(raw) {
     const o = typeof raw === "object" && raw !== null ? raw : {};
@@ -57,11 +61,11 @@ function rolesOf(raw) {
 }
 /** POST /projects/{id}/domains — returns the records to publish. Rate-limited. */
 export async function attachDomain(cfg, projectId, domain, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains`, {
+    const res = await call(cfg, `/projects/${encodeURIComponent(projectId)}/domains`, {
         method: "POST",
-        headers: { ...authHeaders(cfg), "content-type": "application/json" },
+        headers: { "content-type": "application/json" },
         body: JSON.stringify({ domain }),
-    });
+    }, fetchImpl);
     if (!res.ok)
         throw await readError(res);
     const raw = await res.json();
@@ -82,7 +86,7 @@ export async function attachDomain(cfg, projectId, domain, fetchImpl = apiFetch)
  * a defect, and its copy names no limit family.
  */
 export async function verifyDomain(cfg, projectId, domain, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(domain)}/verify`, { method: "POST", headers: authHeaders(cfg) });
+    const res = await call(cfg, `/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(domain)}/verify`, { method: "POST" }, fetchImpl);
     if (!res.ok)
         throw await readError(res);
     const raw = await res.json();
@@ -98,7 +102,7 @@ export async function verifyDomain(cfg, projectId, domain, fetchImpl = apiFetch)
 }
 /** GET /projects/{id}/domains — this project's domains with state + findings. */
 export async function listProjectDomains(cfg, projectId, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains`, { headers: authHeaders(cfg) });
+    const res = await call(cfg, `/projects/${encodeURIComponent(projectId)}/domains`, {}, fetchImpl);
     if (!res.ok)
         throw await readError(res);
     return parseDomainList(await res.json());
@@ -112,14 +116,14 @@ export async function listProjectDomains(cfg, projectId, fetchImpl = apiFetch) {
  * here, and this route only ever returns their own.
  */
 export async function listOrgDomains(cfg, orgSlug, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/orgs/${encodeURIComponent(orgSlug)}/domains`, { headers: authHeaders(cfg) });
+    const res = await call(cfg, `/orgs/${encodeURIComponent(orgSlug)}/domains`, {}, fetchImpl);
     if (!res.ok)
         throw await readError(res);
     return parseDomainList(await res.json());
 }
 /** DELETE /projects/{id}/domains/{domain} — detach. The row is never deleted server-side. */
 export async function detachDomain(cfg, projectId, domain, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(domain)}`, { method: "DELETE", headers: authHeaders(cfg) });
+    const res = await call(cfg, `/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(domain)}`, { method: "DELETE" }, fetchImpl);
     // 404 is a SILENT RESOLVE on detach: the creator asked for a state the world is
     // already in. It is not distinguishable from "not your project", and it does
     // not need to be — either way this project is not serving that name.

package/dist/domain/command.js

@@ -22,6 +22,7 @@ import { EXIT } from "../lib/exitCodes.js";
 import { VALIDATION_RECORD_GONE } from "./wire.js";
 import { DomainApiError } from "./api.js";
 import { AuthExpiredError, authExpiredLines } from "../shared/authError.js";
+import { UpgradeRequiredError } from "../shared/upgradeError.js";
 import { localRefusal, normalizeArgument } from "./hostname.js";
 import * as copy from "./copy.js";
 /** The canonical subcommands. */
@@ -178,6 +179,8 @@ function authExpired(deps) {
     return EXIT.NOT_AUTHENTICATED;
 }
 function printAttachError(deps, err, hostname) {
+    if (err instanceof UpgradeRequiredError)
+        throw err;
     if (err instanceof AuthExpiredError)
         return authExpired(deps);
     if (!(err instanceof DomainApiError)) {
@@ -239,6 +242,8 @@ async function listVerb(deps, cfg, opts) {
         view = await deps.listOrg(cfg, org.org.slug);
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError)
+            throw err;
         if (err instanceof AuthExpiredError)
             return authExpired(deps);
         deps.print("");
@@ -293,6 +298,8 @@ async function verifyVerb(deps, cfg, opts) {
         result = await deps.verify(cfg, binding.projectId, hostname);
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError)
+            throw err;
         if (err instanceof AuthExpiredError)
             return authExpired(deps);
         if (err instanceof DomainApiError && err.status === 404) {
@@ -459,6 +466,8 @@ async function detachVerb(deps, cfg, opts) {
         await deps.detach(cfg, binding.projectId, hostname);
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError)
+            throw err;
         if (err instanceof AuthExpiredError)
             return authExpired(deps);
         deps.print("");

package/dist/dx/command.js

@@ -4,6 +4,7 @@ import { journalEnabled, journalPath, readJournal } from "./journal.js";
 import { buildReport, renderPayload } from "./send.js";
 import { resolveBuiltWith } from "../platform/resolve.js";
 import { EXIT } from "../lib/exitCodes.js";
+import { UpgradeRequiredError } from "../shared/upgradeError.js";
 const MINUTE_MS = 60 * 1000;
 const HOUR_MS = 60 * MINUTE_MS;
 const DAY_MS = 24 * HOUR_MS;
@@ -526,6 +527,8 @@ export async function dxSendCommand(deps, options) {
         return 0;
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError)
+            throw err;
         deps.print("");
         deps.print(`✗ ${err instanceof Error ? err.message : String(err)}`);
         return 1;

package/dist/dx/consent.js

@@ -22,8 +22,8 @@ import { browserPage } from "../login/pkceLogin.js";
 import { stateMatches } from "../login/pkce.js";
 import { getFreePort } from "../preview/net.js";
 import { authFailureMessage } from "../shared/authError.js";
-import { clientHeaders } from "../shared/clientHeader.js";
-import { apiFetch } from "../shared/http.js";
+import { apiRequest } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 import { readAccountConsent } from "./enablement.js";
 async function safeText(res) {
     try {
@@ -48,32 +48,28 @@ function unwrapMe(raw) {
 }
 /** The real HTTP-backed ConsentBackend, pointed at a Vincentt API base URL. */
 export function httpConsentBackend() {
-    const strip = (u) => u.replace(/\/$/, "");
+    const call = async (apiUrl, pat, path, init) => {
+        const res = await apiRequest({ apiUrl, pat }, path, init, { authenticated: true });
+        await rejectUpgradeRequired(res);
+        return res;
+    };
     return {
         async read(apiUrl, pat, now) {
-            const res = await apiFetch(`${strip(apiUrl)}/me`, {
-                headers: { ...clientHeaders(), authorization: `Bearer ${pat}` },
-            });
+            const res = await call(apiUrl, pat, "/me", {});
             if (!res.ok) {
                 throw new Error(authFailureMessage("Could not read your account", res.status, await safeText(res)));
             }
             return readAccountConsent(unwrapMe(await res.json()), now);
         },
         async grant(apiUrl, pat, now) {
-            const res = await apiFetch(`${strip(apiUrl)}/me/dx-consent`, {
-                method: "POST",
-                headers: { ...clientHeaders(), authorization: `Bearer ${pat}` },
-            });
+            const res = await call(apiUrl, pat, "/me/dx-consent", { method: "POST" });
             if (!res.ok) {
                 throw new Error(authFailureMessage("Could not record consent", res.status, await safeText(res)));
             }
             return readAccountConsent(unwrapMe(await res.json()), now);
         },
         async revoke(apiUrl, pat) {
-            const res = await apiFetch(`${strip(apiUrl)}/me/dx-consent`, {
-                method: "DELETE",
-                headers: { ...clientHeaders(), authorization: `Bearer ${pat}` },
-            });
+            const res = await call(apiUrl, pat, "/me/dx-consent", { method: "DELETE" });
             if (!res.ok) {
                 throw new Error(authFailureMessage("Could not revoke consent", res.status, await safeText(res)));
             }

package/dist/dx/reportIo.js

@@ -1,13 +1,15 @@
 import { DXSendError } from "./send.js";
 import { AUTH_EXPIRED_MESSAGE } from "../shared/authError.js";
-import { apiFetch } from "../shared/http.js";
+import { apiFetch, apiRequest } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 export async function postObservationReport(apiUrl, pat, report, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${apiUrl}/dx-reports`, {
+    const res = await apiRequest({ apiUrl, pat }, "/dx-reports", {
         method: "POST",
-        headers: { "content-type": "application/json", authorization: `Bearer ${pat}` },
+        headers: { "content-type": "application/json" },
         body: JSON.stringify(report),
-    });
+    }, { authenticated: true }, fetchImpl);
     if (!res.ok) {
+        await rejectUpgradeRequired(res);
         let detail = "";
         try {
             const body = (await res.json());

package/dist/dx/send.js

@@ -1,5 +1,6 @@
 import { AUTH_EXPIRED_MESSAGE } from "../shared/authError.js";
-import { apiFetch } from "../shared/http.js";
+import { apiFetch, apiRequest } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 import { renderPayloadWithVersionSummary, summarizeBuiltWith, versionDisclosureLines, } from "../platform/versionSummary.js";
 /**
  * The server bounds a report at 50 findings and refuses the whole thing past
@@ -105,12 +106,13 @@ export class DXSendError extends Error {
  * POST the report. The caller has already shown the payload and had it accepted.
  */
 export async function postReport(apiUrl, pat, report, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${apiUrl}/dx-reports`, {
+    const res = await apiRequest({ apiUrl, pat }, "/dx-reports", {
         method: "POST",
-        headers: { "content-type": "application/json", authorization: `Bearer ${pat}` },
+        headers: { "content-type": "application/json" },
         body: JSON.stringify(report),
-    });
+    }, { authenticated: true }, fetchImpl);
     if (!res.ok) {
+        await rejectUpgradeRequired(res);
         let detail = "";
         try {
             const body = (await res.json());

package/dist/lib/backend.js

@@ -6,9 +6,9 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { clientHeaders } from "../shared/clientHeader.js";
 import { authFailureMessage } from "../shared/authError.js";
-import { apiFetch } from "../shared/http.js";
+import { apiRequest } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 const execFileAsync = promisify(execFile);
 export class BackendError extends Error {
     status;
@@ -19,14 +19,9 @@ export class BackendError extends Error {
     }
 }
 async function authFetch(cfg, pathname, init = {}) {
-    return apiFetch(`${cfg.apiUrl}${pathname}`, {
-        ...init,
-        headers: {
-            ...(init.headers ?? {}),
-            ...clientHeaders(),
-            authorization: `Bearer ${cfg.pat}`,
-        },
-    });
+    const res = await apiRequest(cfg, pathname, init, { authenticated: true });
+    await rejectUpgradeRequired(res);
+    return res;
 }
 async function safeText(res) {
     try {

package/dist/lib/exitCodes.d.ts

@@ -17,6 +17,12 @@ export declare const EXIT: {
     readonly DELIVERED_NOT_REGISTERED: 3;
     /** A platform call needed an account and the command did not answer for it. */
     readonly NOT_AUTHENTICATED: 4;
+    /**
+     * The platform refused this CLI's version, and nothing was changed on the
+     * platform. A verb such as `create` may have written local source; its screen
+     * says where.
+     */
+    readonly UPGRADE_REQUIRED: 5;
     /** A bounded wait elapsed with nothing handed over. */
     readonly WINDOW_ELAPSED: 64;
     /** The channel ended before anything was handed over. */

package/dist/lib/exitCodes.js

@@ -17,6 +17,12 @@ export const EXIT = {
     DELIVERED_NOT_REGISTERED: 3,
     /** A platform call needed an account and the command did not answer for it. */
     NOT_AUTHENTICATED: 4,
+    /**
+     * The platform refused this CLI's version, and nothing was changed on the
+     * platform. A verb such as `create` may have written local source; its screen
+     * says where.
+     */
+    UPGRADE_REQUIRED: 5,
     /** A bounded wait elapsed with nothing handed over. */
     WINDOW_ELAPSED: 64,
     /** The channel ended before anything was handed over. */

package/dist/lib/terminalText.d.ts

@@ -1,5 +1,11 @@
 export declare const CONTROL_CHARS: RegExp;
 /** Each C0/C1 control character as a visible `\uXXXX`, so nothing is hidden or redrawn. */
 export declare function escapeControl(text: string): string;
+/**
+ * Each C0/C1 control, bidi embedding, override or isolate, and direction mark
+ * as a visible `\uXXXX`: a file name cannot reorder the line, and the creator
+ * can still find the file.
+ */
+export declare function escapeTerminal(text: string): string;
 /** Text with every C0/C1 control and bidi override or isolate removed. */
 export declare function terminalSafe(text: string): string;

package/dist/lib/terminalText.js

@@ -11,6 +11,16 @@ export function escapeControl(text) {
 // U+202A..U+202E (embeddings, overrides) and U+2066..U+2069 (isolates) can
 // reorder a terminal line, so a crafted name could disguise what it says.
 const BIDI_CONTROLS_G = /[\u202a-\u202e\u2066-\u2069]/g;
+// The above, plus the direction marks U+200E, U+200F and U+061C.
+const TERMINAL_UNSAFE_G = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+/**
+ * Each C0/C1 control, bidi embedding, override or isolate, and direction mark
+ * as a visible `\uXXXX`: a file name cannot reorder the line, and the creator
+ * can still find the file.
+ */
+export function escapeTerminal(text) {
+    return text.replace(TERMINAL_UNSAFE_G, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
 /** Text with every C0/C1 control and bidi override or isolate removed. */
 export function terminalSafe(text) {
     return text.replace(CONTROL_CHARS_G, "").replace(BIDI_CONTROLS_G, "");

package/dist/lib/whoami.js

@@ -7,6 +7,7 @@
 // f2's hardest copy rather than cosmetic.
 import { resolveActiveOrg } from "./org.js";
 import { authExpiredLines, isAuthRefused } from "../shared/authError.js";
+import { UpgradeRequiredError } from "../shared/upgradeError.js";
 import { EXIT } from "./exitCodes.js";
 export async function whoamiCommand(deps) {
     const cfg = await deps.config();
@@ -19,6 +20,8 @@ export async function whoamiCommand(deps) {
         me = await deps.getMe(cfg);
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError)
+            throw err;
         if (isAuthRefused(err)) {
             for (const l of authExpiredLines())
                 deps.print(l);

package/dist/library/assetsCommand.js

@@ -18,6 +18,7 @@ import { DOWNLOAD_DIR, downloadPath, exists, overwriteRefusalLines, writeAsset,
 import { dedupeForDisplay, parseIdArgs, parseSearchFlags } from "./parse.js";
 import { addLines, humanBytes, searchLines, showLines, unknownBlockLines, unreachableLines, } from "./render.js";
 import { isLibraryId } from "./wire.js";
+import { UpgradeRequiredError } from "../shared/upgradeError.js";
 /**
  * Map a thrown client error onto the exit-4 screen it deserves.
  *
@@ -28,6 +29,9 @@ import { isLibraryId } from "./wire.js";
  * corpus failed to load.
  */
 function failureScreen(err, retry) {
+    // Rethrown so main() renders the one refusal screen and exits 5.
+    if (err instanceof UpgradeRequiredError)
+        throw err;
     if (err instanceof LibraryUnreachableError) {
         return { lines: unreachableLines("transport", retry), code: 4 };
     }

package/dist/library/client.js

@@ -12,9 +12,9 @@
 // CLI-supplied URL reaches a fetch. That is a security control, not a style choice
 // (D-add-prints-urls degraded the no-invented-URLs rule from prevention to
 // detection, and this is the one arm that stayed prevention).
-import { clientHeaders } from "../shared/clientHeader.js";
 import { authFailureMessage } from "../shared/authError.js";
-import { apiFetch, withDeadline } from "../shared/http.js";
+import { apiRequest, withDeadline } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 import { parseBatchResponse, parseFetchResponse, parseSearchResponse, } from "./wire.js";
 // An asset file can be tens of megabytes, so its download gets longer than an api call.
 const downloadFetch = withDeadline((input, init) => globalThis.fetch(input, init), 5 * 60_000);
@@ -65,18 +65,16 @@ async function readJson(res) {
  * correct recovery differs between them (retry later vs re-search).
  */
 export function httpLibraryClient(cfg) {
-    const base = cfg.apiUrl.replace(/\/$/, "");
-    const auth = { ...clientHeaders(), authorization: `Bearer ${cfg.pat}` };
     const call = async (pathname, init) => {
+        let res;
         try {
-            return await apiFetch(`${base}${pathname}`, {
-                ...init,
-                headers: { ...(init?.headers ?? {}), ...auth },
-            });
+            res = await apiRequest(cfg, pathname, init, { authenticated: true });
         }
         catch (err) {
             throw new LibraryUnreachableError(err);
         }
+        await rejectUpgradeRequired(res);
+        return res;
     };
     const fail = async (res, what) => {
         // A 401 keeps its status: assetsCommand maps it to the sign-in screen and exit 4.

package/dist/login/authBackend.js

@@ -9,8 +9,8 @@
 //   GET  /me            Bearer <PAT> → identity + orgs (confirm)
 // and, to end this machine's own sign-in, DELETE /access-tokens/current Bearer <PAT>.
 import { authFailureMessage } from "../shared/authError.js";
-import { clientHeaders } from "../shared/clientHeader.js";
-import { apiFetch, withDeadline } from "../shared/http.js";
+import { apiRequest, withDeadline } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 /** DELETE /access-tokens/current gives up after this long: sign-out never hangs on the api. */
 export const REVOKE_CURRENT_TIMEOUT_MS = 5_000;
 class AuthError extends Error {
@@ -52,12 +52,18 @@ function readEvicted(raw) {
 }
 /** The real HTTP-backed AuthBackend, pointed at a Vincentt API base URL. */
 export function httpAuthBackend(apiBase) {
-    const base = apiBase.replace(/\/$/, "");
-    const post = (body) => apiFetch(`${base}/access-tokens/exchange`, {
-        method: "POST",
-        headers: { ...clientHeaders(), "content-type": "application/json" },
-        body: JSON.stringify(body),
-    });
+    const target = { apiUrl: apiBase };
+    // The exchange is unauthenticated but judged by the CLI floor, so it carries
+    // the tag like every other api request and its 426 is read before any arm.
+    const post = async (body) => {
+        const res = await apiRequest(target, "/access-tokens/exchange", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        }, { authenticated: false });
+        await rejectUpgradeRequired(res);
+        return res;
+    };
     return {
         async exchange(code, codeVerifier, label) {
             const body = { code, code_verifier: codeVerifier };
@@ -89,9 +95,10 @@ export function httpAuthBackend(apiBase) {
             };
         },
         async me(pat) {
-            const res = await apiFetch(`${base}/me`, {
-                headers: { ...clientHeaders(), authorization: `Bearer ${pat}` },
+            const res = await apiRequest({ apiUrl: apiBase, pat }, "/me", {}, {
+                authenticated: true,
             });
+            await rejectUpgradeRequired(res);
             if (!res.ok) {
                 throw new AuthError(authFailureMessage("Identity check failed", res.status, await safeText(res)), res.status);
             }
@@ -106,12 +113,8 @@ export function httpAuthBackend(apiBase) {
  * failure, a timeout or a 5xx is "unreachable".
  */
 export async function revokeCurrent(apiBase, pat, fetchImpl = (input, init) => globalThis.fetch(input, init), timeoutMs = REVOKE_CURRENT_TIMEOUT_MS) {
-    const base = apiBase.replace(/\/$/, "");
     try {
-        const res = await withDeadline(fetchImpl, timeoutMs)(`${base}/access-tokens/current`, {
-            method: "DELETE",
-            headers: { ...clientHeaders(), authorization: `Bearer ${pat}` },
-        });
+        const res = await apiRequest({ apiUrl: apiBase, pat }, "/access-tokens/current", { method: "DELETE" }, { authenticated: true }, withDeadline(fetchImpl, timeoutMs));
         if (res.ok || [400, 401, 403, 404, 405].includes(res.status))
             return "done";
         return "unreachable";