@vincentt-xr/cli 0.21.0 → 0.23.0

package/dist/editor/reads.d.ts

@@ -0,0 +1,47 @@
+import { type MacSystem } from "./app.js";
+import { type PidRecord } from "./localFiles.js";
+export declare const SELECTION_SCHEMA = "vincentt.editor-selection/1";
+export declare const STATE_SCHEMA = "vincentt.editor-state/1";
+export interface ReadParams {
+    system: Pick<MacSystem, "verifyPid" | "startTime">;
+    /** The designated requirement a running copy must meet. */
+    requirement: string;
+    isAlive?: (pid: number) => boolean;
+}
+/**
+ * True when the code `pid` is running meets the requirement, from any path. Checked on the
+ * running process itself, so no path the OS reports for it is trusted.
+ */
+export declare function isVerifiedEditor(pid: number, p: ReadParams): Promise<boolean>;
+/**
+ * True when the process now holding `pid` was already running when the record was written. A
+ * process that started after `startedAt` reused the pid of the editor that wrote it.
+ */
+export declare function startedBeforeRecord(processStart: number | undefined, rec: PidRecord): boolean;
+/** The editor recorded in `pid`, when that process is live, is that record's process, and is a verified editor. */
+export declare function runningEditor(root: string, p: ReadParams): Promise<PidRecord | undefined>;
+export type SchemaMajor = "known" | "foreign" | {
+    newer: string;
+};
+/** Whether `schema` is `<family>/1`, a later major of the family, or something else. */
+export declare function schemaMajor(schema: unknown, family: string): SchemaMajor;
+/** The selection as the agent may read it: an allowlist of fields, every string sanitised. */
+export declare function shapeSelection(sel: unknown): Record<string, unknown> | null;
+export interface ReadResult {
+    stdout: string[];
+    stderr: string[];
+    exitCode: number;
+    /** For the f7 journal: why the read exited 1. */
+    reason?: "not_running" | "too_new";
+}
+export declare function selectionRead(root: string, json: boolean, p: ReadParams): Promise<ReadResult>;
+export declare function humanSelection(sel: Record<string, unknown> | null): string[];
+/**
+ * `app` as the agent may read it: exactly `{version, lastOpen}`, each null unless it is one of
+ * the shapes the app writes. `trustLastOpen` false nulls `lastOpen` whatever the file says.
+ */
+export declare function shapeApp(app: unknown, trustLastOpen: boolean): {
+    version: string | null;
+    lastOpen: string | null;
+};
+export declare function statusRead(root: string, p: ReadParams): Promise<ReadResult>;

package/dist/editor/reads.js

@@ -0,0 +1,269 @@
+// `vincentt editor --selection [--json]` and `--status --json`: read the editor's local files
+// and print them. A read flag never talks to the running app; when none runs for the folder it
+// says so on stderr, still prints one JSON object on stdout, and exits 1. A file in a schema
+// major this CLI does not know is refused whole ("too new"), never printed in part.
+import { pidAlive } from "./app.js";
+import { NOT_RUNNING, tooNew } from "./copy.js";
+import { realpath } from "node:fs/promises";
+import { lastHandoff } from "./handoffs.js";
+import { parsePidFile, readLocalFile, readLocalFileStat, } from "./localFiles.js";
+import { agentSafe, agentSafeValue } from "./text.js";
+export const SELECTION_SCHEMA = "vincentt.editor-selection/1";
+export const STATE_SCHEMA = "vincentt.editor-state/1";
+/**
+ * True when the code `pid` is running meets the requirement, from any path. Checked on the
+ * running process itself, so no path the OS reports for it is trusted.
+ */
+export async function isVerifiedEditor(pid, p) {
+    const verdict = await p.system.verifyPid(pid, p.requirement).catch(() => undefined);
+    return verdict?.ok === true;
+}
+/** `ps` reports whole seconds and the app writes whole seconds. */
+const START_SLACK_MS = 1_000;
+/**
+ * True when the process now holding `pid` was already running when the record was written. A
+ * process that started after `startedAt` reused the pid of the editor that wrote it.
+ */
+export function startedBeforeRecord(processStart, rec) {
+    return processStart !== undefined && processStart <= rec.startedAt + START_SLACK_MS;
+}
+/** The editor recorded in `pid`, when that process is live, is that record's process, and is a verified editor. */
+export async function runningEditor(root, p) {
+    const text = await readLocalFile(root, "pid").catch(() => undefined);
+    const rec = text === undefined ? undefined : parsePidFile(text);
+    if (rec === undefined || !(p.isAlive ?? pidAlive)(rec.pid))
+        return undefined;
+    const start = await p.system.startTime(rec.pid).catch(() => undefined);
+    if (!startedBeforeRecord(start, rec))
+        return undefined;
+    return (await isVerifiedEditor(rec.pid, p)) ? rec : undefined;
+}
+/** Whether `schema` is `<family>/1`, a later major of the family, or something else. */
+export function schemaMajor(schema, family) {
+    if (typeof schema !== "string")
+        return "foreign";
+    const m = /^(.+)\/(\d+)$/.exec(schema);
+    if (m === null || m[1] !== family)
+        return "foreign";
+    const major = Number(m[2]);
+    if (major === 1)
+        return "known";
+    return major > 1 ? { newer: schema } : "foreign";
+}
+const SELECTION_FAMILY = "vincentt.editor-selection";
+const STATE_FAMILY = "vincentt.editor-state";
+async function readJson(root, name) {
+    return (await readJsonStat(root, name))?.value;
+}
+async function readJsonStat(root, name) {
+    const file = await readLocalFileStat(root, name).catch(() => undefined);
+    if (file === undefined)
+        return undefined;
+    try {
+        const v = JSON.parse(file.text);
+        return typeof v === "object" && v !== null && !Array.isArray(v)
+            ? { value: v, mtimeMs: file.mtimeMs }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A snapshot belongs to the running editor when it carries the pid record's session and, when it
+ * names a pid, that pid.
+ */
+function sameEditor(file, rec) {
+    if (typeof file.session !== "string" || file.session !== rec.session)
+        return false;
+    return typeof file.pid !== "number" || file.pid === rec.pid;
+}
+/** Fields the CLI states itself; file content never supplies them. */
+const RESERVED_STATE_KEYS = ["schema", "running", "pid", "session"];
+const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : undefined;
+/** A string field, sanitised; anything that is not a string reads as empty. */
+const str = (v, max) => typeof v === "string" ? agentSafe(v, max) : "";
+/** The selection as the agent may read it: an allowlist of fields, every string sanitised. */
+export function shapeSelection(sel) {
+    if (typeof sel !== "object" || sel === null)
+        return null;
+    const s = sel;
+    const src = (typeof s.source === "object" && s.source !== null ? s.source : {});
+    const values = Array.isArray(s.values) ? s.values : [];
+    return {
+        objectKey: str(s.objectKey, 400),
+        label: str(s.label, 200),
+        type: str(s.type, 80),
+        kind: str(s.kind, 20),
+        source: {
+            file: str(src.file, 400),
+            line: num(src.line) ?? null,
+            column: num(src.column) ?? null,
+        },
+        values: values.slice(0, 256).map((raw) => {
+            const v = (typeof raw === "object" && raw !== null ? raw : {});
+            const out = {
+                path: str(v.path, 200),
+                type: str(v.type, 20),
+                value: agentSafeValue(v.value),
+            };
+            if (typeof v.unit === "string")
+                out.unit = agentSafe(v.unit, 10);
+            out.editable =
+                v.editable === true
+                    ? true
+                    : agentSafeValue(v.editable ?? { readonly: "unsupported" }, 40);
+            if (typeof v.decl === "string")
+                out.decl = agentSafe(v.decl, 200);
+            if (num(v.sharedBy) !== undefined)
+                out.sharedBy = num(v.sharedBy);
+            return out;
+        }),
+    };
+}
+function tooNewResult(schema) {
+    return { stdout: [], stderr: tooNew(schema), exitCode: 1, reason: "too_new" };
+}
+export async function selectionRead(root, json, p) {
+    const file = await readJson(root, "selection.json");
+    const major = schemaMajor(file?.schema, SELECTION_FAMILY);
+    if (typeof major === "object")
+        return tooNewResult(major.newer);
+    const rec = await runningEditor(root, p);
+    if (rec === undefined) {
+        return {
+            stdout: json
+                ? [JSON.stringify({ schema: SELECTION_SCHEMA, running: false, selection: null })]
+                : [],
+            stderr: [NOT_RUNNING],
+            exitCode: 1,
+            reason: "not_running",
+        };
+    }
+    const selection = file && major === "known" && sameEditor(file, rec)
+        ? shapeSelection(file.selection)
+        : null;
+    if (json) {
+        return {
+            stdout: [JSON.stringify({ schema: SELECTION_SCHEMA, running: true, selection })],
+            stderr: [],
+            exitCode: 0,
+        };
+    }
+    return { stdout: humanSelection(selection), stderr: [], exitCode: 0 };
+}
+function display(v) {
+    if (Array.isArray(v))
+        return v.map(display).join(", ");
+    if (v !== null && typeof v === "object") {
+        return Object.entries(v)
+            .map(([k, x]) => `${k}: ${display(x)}`)
+            .join(", ");
+    }
+    return String(v);
+}
+export function humanSelection(sel) {
+    if (sel === null)
+        return ["Nothing is selected in the editor."];
+    const src = sel.source;
+    const kind = sel.kind === "sdk" ? " (Vincentt SDK)" : "";
+    const out = [
+        `${sel.label}  ${sel.type}${kind}  ${src.file}${src.line !== null ? `:${src.line}` : ""}`,
+    ];
+    for (const v of sel.values) {
+        const unit = typeof v.unit === "string" ? ` ${v.unit}` : "";
+        const ro = v.editable === true
+            ? ""
+            : `   (read-only: ${display(v.editable?.readonly ?? "unsupported")})`;
+        out.push(`  ${String(v.path).padEnd(26)} ${display(v.value)}${unit}${ro}`);
+    }
+    return out;
+}
+const APP_VERSION = /^\d+\.\d+\.\d+([-+][0-9A-Za-z.-]{1,32})?$/;
+const LAST_OPEN = /^(opened|awaiting_trust|cancelled|refused:[A-Za-z0-9_-]{1,16})$/;
+/**
+ * `app` as the agent may read it: exactly `{version, lastOpen}`, each null unless it is one of
+ * the shapes the app writes. `trustLastOpen` false nulls `lastOpen` whatever the file says.
+ */
+export function shapeApp(app, trustLastOpen) {
+    const a = (typeof app === "object" && app !== null ? app : {});
+    const version = typeof a.version === "string" && APP_VERSION.test(a.version) ? a.version : null;
+    const lastOpen = trustLastOpen && typeof a.lastOpen === "string" && LAST_OPEN.test(a.lastOpen)
+        ? a.lastOpen
+        : null;
+    return { version, lastOpen };
+}
+/**
+ * A state file no running editor vouches for is believed about the last open only when it
+ * changed after this machine's last hand-off of this folder: a committed or copied state.json
+ * predates it, and a folder never handed over has no open to report. A time in the future (an
+ * unpacked archive keeps whatever mtime it was given) is not after anything.
+ */
+async function lastOpenTrusted(root, mtimeMs) {
+    const project = await realpath(root).catch(() => undefined);
+    if (project === undefined)
+        return false;
+    const at = await lastHandoff(project).catch(() => undefined);
+    return at !== undefined && mtimeMs > at && mtimeMs <= Date.now() + 5_000;
+}
+function appField(file, trustLastOpen) {
+    return file !== undefined && file.app !== undefined
+        ? { app: shapeApp(file.app, trustLastOpen) }
+        : {};
+}
+export async function statusRead(root, p) {
+    const read = await readJsonStat(root, "state.json");
+    const file = read?.value;
+    const major = schemaMajor(file?.schema, STATE_FAMILY);
+    if (typeof major === "object")
+        return tooNewResult(major.newer);
+    const known = major === "known" ? file : undefined;
+    const rec = await runningEditor(root, p);
+    if (known && rec && known.running === true && sameEditor(known, rec)) {
+        // The running, verified editor wrote this file. Sanitised first, so a key that only
+        // becomes `pid` once its control characters are stripped is removed too.
+        const shaped = agentSafeValue(known, 400);
+        for (const k of RESERVED_STATE_KEYS)
+            delete shaped[k];
+        if (known.app !== undefined)
+            shaped.app = shapeApp(known.app, true);
+        return {
+            stdout: [
+                JSON.stringify({ schema: STATE_SCHEMA, running: true, pid: rec.pid, ...shaped }),
+            ],
+            stderr: [],
+            exitCode: 0,
+        };
+    }
+    const trusted = known !== undefined &&
+        read !== undefined &&
+        (await lastOpenTrusted(root, read.mtimeMs));
+    if (rec === undefined) {
+        // A refused or cancelled open leaves no running editor behind, so the outcome of the last
+        // hand-off is reported here too, when the file is believed.
+        return {
+            stdout: [
+                JSON.stringify({
+                    schema: STATE_SCHEMA,
+                    running: false,
+                    ...appField(known, trusted),
+                }),
+            ],
+            stderr: [NOT_RUNNING],
+            exitCode: 1,
+            reason: "not_running",
+        };
+    }
+    return {
+        stdout: [
+            JSON.stringify({
+                schema: STATE_SCHEMA,
+                running: true,
+                pid: rec.pid,
+                ...appField(known, trusted),
+            }),
+        ],
+        stderr: [],
+        exitCode: 0,
+    };
+}

package/dist/editor/text.d.ts

@@ -0,0 +1,7 @@
+export declare function isUnsafeChar(ch: string): boolean;
+/** Unsafe characters removed and the result capped at `max` code points. */
+export declare function agentSafe(s: string, max: number): string;
+/** Nesting kept in a value an agent reads; anything deeper is dropped (null). */
+export declare const MAX_DEPTH = 8;
+/** A JSON value with every string (keys included) made agent-safe, depth- and size-capped. */
+export declare function agentSafeValue(v: unknown, max?: number, depth?: number): unknown;

package/dist/editor/text.js

@@ -0,0 +1,58 @@
+// Text that reaches the creator's terminal or their agent from the editor's files. The app
+// already strips these characters (B-F21-8); the CLI strips them again because it is the last
+// step before a shell, and a stale or planted file never passed the app.
+// C0 and C1 controls, DEL, the Arabic letter mark, zero-width characters and direction marks,
+// line and paragraph separators, bidi embeddings, overrides and isolates, the word joiner,
+// invisible operators, the byte order mark, the soft hyphen, the combining grapheme joiner,
+// the Mongolian vowel separator, variation selectors and tag characters. Code points rather
+// than a character class, so no bidi character sits in source.
+const UNSAFE = [
+    [0x0000, 0x001f],
+    [0x007f, 0x009f],
+    [0x00ad, 0x00ad],
+    [0x034f, 0x034f],
+    [0x061c, 0x061c],
+    [0x180e, 0x180e],
+    [0x200b, 0x200f],
+    [0x2028, 0x2029],
+    [0x2060, 0x2064],
+    [0xfe00, 0xfe0f],
+    [0xfeff, 0xfeff],
+    [0x202a, 0x202e],
+    [0x2066, 0x2069],
+    [0xe0000, 0xe007f],
+    [0xe0100, 0xe01ef],
+];
+export function isUnsafeChar(ch) {
+    const cp = ch.codePointAt(0) ?? 0;
+    return UNSAFE.some(([lo, hi]) => cp >= lo && cp <= hi);
+}
+// CSI and OSC sequences, removed whole so no `[31m` residue is left behind.
+// eslint-disable-next-line no-control-regex
+const ANSI_G = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?|\u009b[0-?]*[ -/]*[@-~]/g;
+/** Unsafe characters removed and the result capped at `max` code points. */
+export function agentSafe(s, max) {
+    return Array.from(s.replace(ANSI_G, ""))
+        .filter((ch) => !isUnsafeChar(ch))
+        .slice(0, max)
+        .join("");
+}
+/** Nesting kept in a value an agent reads; anything deeper is dropped (null). */
+export const MAX_DEPTH = 8;
+/** A JSON value with every string (keys included) made agent-safe, depth- and size-capped. */
+export function agentSafeValue(v, max = 200, depth = 0) {
+    if (typeof v === "string")
+        return agentSafe(v, max);
+    if (depth >= MAX_DEPTH && v !== null && typeof v === "object")
+        return null;
+    if (Array.isArray(v))
+        return v.slice(0, 64).map((x) => agentSafeValue(x, max, depth + 1));
+    if (v !== null && typeof v === "object") {
+        const out = {};
+        for (const [k, x] of Object.entries(v).slice(0, 256)) {
+            out[agentSafe(k, 80)] = agentSafeValue(x, max, depth + 1);
+        }
+        return out;
+    }
+    return v;
+}

package/dist/editor/tools.d.ts

@@ -0,0 +1,5 @@
+export type Tool = "codesign" | "open" | "sw_vers" | "plutil" | "lsappinfo" | "ps";
+/** Where each tool lives, most likely first. Never a relative path; none off macOS. */
+export declare function toolCandidates(tool: Tool, platform?: NodeJS.Platform): string[];
+/** The tool's absolute path, or undefined when it is not where the OS keeps it. */
+export declare function toolPath(tool: Tool, platform?: NodeJS.Platform, exists?: (p: string) => boolean): string | undefined;

package/dist/editor/tools.js

@@ -0,0 +1,20 @@
+// The macOS tools the launcher runs, by absolute path only. A bare name would be resolved from
+// PATH, so a project (or anything earlier on PATH) could plant a `codesign` that answers "this
+// app is signed by Vincentt".
+import { existsSync } from "node:fs";
+const DARWIN = {
+    ps: ["/bin/ps"],
+    codesign: ["/usr/bin/codesign"],
+    open: ["/usr/bin/open"],
+    sw_vers: ["/usr/bin/sw_vers"],
+    plutil: ["/usr/bin/plutil"],
+    lsappinfo: ["/usr/bin/lsappinfo"],
+};
+/** Where each tool lives, most likely first. Never a relative path; none off macOS. */
+export function toolCandidates(tool, platform = process.platform) {
+    return platform === "darwin" ? DARWIN[tool] : [];
+}
+/** The tool's absolute path, or undefined when it is not where the OS keeps it. */
+export function toolPath(tool, platform = process.platform, exists = existsSync) {
+    return toolCandidates(tool, platform).find((p) => exists(p));
+}

package/dist/lib/version.d.ts

@@ -1,4 +1,4 @@
-import type { Enablement } from "../dx/enablement.js";
+import type { AccountRead, Enablement, EnablementSource, EnablementVia } from "../dx/enablement.js";
 export interface VersionReport {
     cliVersion: string;
     nodeVersion: string;
@@ -9,10 +9,13 @@ export interface VersionReport {
     ignoredBindingApiUrl?: string;
     /** True when the resolved host is the built-in fallback (nothing configured). */
     isDefault: boolean;
-    /** True when this machine may send DX reports unattended. */
+    /** True when DX reports may be sent unattended, from the account-first answer. */
     dxSendEnabled: boolean;
     /** ISO8601 UTC of the grant. Present only when enabled. */
     dxSendEnabledAt?: string;
+    /** Where that answer came from, and where the account grant was made. */
+    dxSource?: EnablementSource;
+    dxVia?: EnablementVia;
     /** The instant the age is computed against, so renderVersion stays pure. */
     dxAgeAsOf: number;
 }
@@ -50,4 +53,27 @@ export declare function renderVersion(r: VersionReport): string[];
 export declare function versionReport(cwd: string, opts: {
     cliVersion: string;
     allowCustomApi?: boolean;
+    /** The account read; absent reports this machine's flag only. */
+    consent?: VersionConsentDeps;
 }): Promise<VersionReport>;
+/** The account bound on `version` (f7 Scenario 3c). */
+export declare const VERSION_ACCOUNT_TIMEOUT_MS = 3000;
+export interface VersionConsentDeps {
+    auth: () => Promise<{
+        apiUrl: string;
+        pat: string;
+    } | undefined>;
+    readAccount: (auth: {
+        apiUrl: string;
+        pat: string;
+    }) => Promise<AccountRead>;
+    clearLocal: () => Promise<unknown>;
+    local?: () => Promise<Enablement>;
+    timeoutMs?: number;
+}
+/**
+ * The enablement `version` shows: the account's answer when it can be read within the
+ * bound, else this machine's flag. Never throws and never waits past the bound, because
+ * `version` is the command people run when something is already broken.
+ */
+export declare function versionEnablement(now: number, consent: VersionConsentDeps | undefined): Promise<Enablement>;

package/dist/lib/version.js

@@ -7,7 +7,7 @@
 // misconfiguration. So this reports the resolved host AND its provenance, using
 // the same decideApiUrl the real verbs use; a version command that re-derived
 // the URL could disagree with them.
-import { enablementLine, loadEnablement } from "../dx/enablement.js";
+import { enablementLine, loadEnablement, resolveConsentView } from "../dx/enablement.js";
 import { decideApiUrl, loadMachineConfig, locateProjectBinding, } from "../shared/config.js";
 /**
  * Decide what to report. Pure, so the transcript is testable without a home
@@ -45,6 +45,8 @@ export function buildVersionReport(env) {
         isDefault,
         dxSendEnabled: enablement.enabled,
         dxSendEnabledAt: enablement.enabled ? enablement.at : undefined,
+        dxSource: enablement.enabled ? enablement.source : undefined,
+        dxVia: enablement.enabled ? enablement.via : undefined,
         dxAgeAsOf: env.now ?? Date.now(),
     };
 }
@@ -68,7 +70,7 @@ export function renderVersion(r) {
     // exactly when a forgotten enablement is most likely to be discovered. Printed
     // only when enabled — see the note in dx/enablement.ts on why there is no `off`
     // counterpart.
-    const dx = enablementLine({ enabled: r.dxSendEnabled, at: r.dxSendEnabledAt }, r.dxAgeAsOf);
+    const dx = enablementLine({ enabled: r.dxSendEnabled, at: r.dxSendEnabledAt, source: r.dxSource, via: r.dxVia }, r.dxAgeAsOf);
     if (dx !== undefined)
         out.push("", `  ${dx}`);
     out.push("");
@@ -106,7 +108,32 @@ export async function versionReport(cwd, opts) {
         allowCustomApi: opts.allowCustomApi,
         nodeVersion: process.version,
         cliVersion: opts.cliVersion,
-        enablement: await loadEnablement(now),
+        enablement: await versionEnablement(now, opts.consent),
         now,
     });
 }
+/** The account bound on `version` (f7 Scenario 3c). */
+export const VERSION_ACCOUNT_TIMEOUT_MS = 3_000;
+/**
+ * The enablement `version` shows: the account's answer when it can be read within the
+ * bound, else this machine's flag. Never throws and never waits past the bound, because
+ * `version` is the command people run when something is already broken.
+ */
+export async function versionEnablement(now, consent) {
+    const local = consent?.local ?? (() => loadEnablement(now));
+    if (consent === undefined)
+        return local();
+    try {
+        const view = await resolveConsentView({
+            auth: await consent.auth().catch(() => undefined),
+            readAccount: consent.readAccount,
+            local,
+            clearLocal: consent.clearLocal,
+            timeoutMs: consent.timeoutMs ?? VERSION_ACCOUNT_TIMEOUT_MS,
+        });
+        return view.shown;
+    }
+    catch {
+        return local().catch(() => ({ enabled: false }));
+    }
+}

package/dist/preview/command.js

@@ -338,6 +338,8 @@ export function endingLines(reason, orgName, refusal = {}) {
             return previewTooOldLines(refusal);
         case "auth_expired":
             return copy.endedAuthExpired();
+        case "protocol_violation":
+            return copy.endedProtocolViolation();
         case "egress_cap":
             return copy.egressHard();
         case "stopped":

package/dist/preview/copy.d.ts

@@ -219,6 +219,11 @@ export declare function endedAuthExpired(): string[];
  * link, and a silent re-mint would break every link already shared.
  */
 export declare function endedAuthzLapsed(): string[];
+/**
+ * The edge broke the agreed tunnel wire. Only an edge bug causes it, so the
+ * remedy is a newer CLI or a later attempt, never anything in the project.
+ */
+export declare function endedProtocolViolation(): string[];
 /**
  * e. Abandoned — this machine stopped checking in (the 30-minute heartbeat-
  * silence flip, `D-Abandoned-sessions-are-judged-on-heartbeat-silence-alone`).

package/dist/preview/copy.js

@@ -18,6 +18,7 @@
 // product, so f1's "a token is never printed" extends to it verbatim.
 /** Flow L13 — the start block. */
 import { escapeControl, terminalSafe } from "../lib/terminalText.js";
+import { INSTALL_COMMAND } from "../shared/upgradeError.js";
 export function startBlock(i) {
     const out = [
         "",
@@ -477,6 +478,20 @@ export function endedAuthzLapsed() {
         "",
     ];
 }
+/**
+ * The edge broke the agreed tunnel wire. Only an edge bug causes it, so the
+ * remedy is a newer CLI or a later attempt, never anything in the project.
+ */
+export function endedProtocolViolation() {
+    return [
+        "",
+        "✗ Preview stopped: the preview server sent an invalid reply. Update the CLI or try again later.",
+        "",
+        `  Upgrade:  ${INSTALL_COMMAND}`,
+        "  Then try again:  vincentt preview",
+        "",
+    ];
+}
 /**
  * e. Abandoned — this machine stopped checking in (the 30-minute heartbeat-
  * silence flip, `D-Abandoned-sessions-are-judged-on-heartbeat-silence-alone`).

package/dist/preview/runner.d.ts

@@ -45,6 +45,12 @@ export type PreviewEndReason = "stopped"
  * both. No further platform call is made, the DELETE included.
  */
  | "upgrade_required"
+/**
+ * The edge broke the agreed tunnel wire (a malformed 101 caps header, a
+ * CONTROL frame this connection cannot read, or a fatal OPEN). Final: a redial reaches the
+ * same edge, so the tunnel client has already stopped dialling.
+ */
+ | "protocol_violation"
 /**
  * The 30-minute heartbeat-silence flip. NEVER reported as `hard_max`: a
  * session ended at minute 30 has not reached its 12-hour ceiling, and saying

package/dist/preview/runner.js

@@ -256,6 +256,7 @@ export async function startPreview(opts) {
                 if (reason !== null)
                     ended(reason);
             },
+            onProtocolViolation: () => ended("protocol_violation"),
             onRefused: (_reason, minimum, declared) => ended("upgrade_required", {
                 minimum: parseMinimum(minimum),
                 declared: parseDeclared(declared),

package/dist/publish/command.js

@@ -15,7 +15,7 @@ import { buildManifest, ManifestError } from "./manifest.js";
 import { checkBounds } from "./bounds.js";
 import { classifyDist } from "./classify.js";
 import { createProgress } from "./progress.js";
-import { UploadExpired, UploadFailed, UploadTargetRejected, uploadAll, } from "./upload.js";
+import { UploadExpired, UploadFailed, UploadTargetRejected, UploadChecksumMismatch, 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;
@@ -342,7 +342,8 @@ async function runUpload(deps, cfg, i) {
         }
         const failedPath = err instanceof UploadFailed ||
             err instanceof UploadExpired ||
-            err instanceof UploadTargetRejected
+            err instanceof UploadTargetRejected ||
+            err instanceof UploadChecksumMismatch
             ? escapeTerminal(err.path)
             : "a file";
         deps.print("");
@@ -563,6 +564,8 @@ function outputRefusal(err, output, buildCommand) {
     switch (err.reason) {
         case "secret_path":
             return copy.secretFiles(err.paths, output);
+        case "path_escaped":
+            return copy.escapedFiles(err.paths, output);
         case "credential_file":
             return copy.credentialFiles(err.paths, output);
         case "file_unreadable":

package/dist/publish/copy.d.ts

@@ -176,6 +176,12 @@ 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 — files whose folder resolved outside the output after the walk: a
+ * folder was swapped for a link while publish read it. The whole publish is
+ * refused, never just the file. After the header and reading line.
+ */
+export declare function escapedFiles(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. */