@vincentt-xr/cli 0.15.2 → 0.17.0

package/dist/platform/notice.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The unbidden behind-notice: one fact, printed after a run the creator asked
+ * for, on stderr, into a stream that is a coding agent's input.
+ *
+ * STATES A FACT, NEVER AN INSTRUCTION — the same rule the dx nudge and the CLI
+ * update notice already carry, for the same reason, and here with a stronger
+ * mechanism: the input struct carries no command string, no URL and no note
+ * body, so there is nothing to instruct WITH. An agent reading an imperative
+ * here would perform an upgrade nobody asked for, in a creator's repository, in
+ * the middle of a preview session.
+ *
+ * NO URL on any line. A URL in unbidden output is an instruction wearing a
+ * fact's clothes; the endpoint's address is printed by `outdated`, which was
+ * asked for.
+ *
+ * Notes are COUNTED, never quoted. The struct holds a boolean per row, so the
+ * body cannot appear.
+ */
+import type { BehindNotice } from "./behind.js";
+/**
+ * The notice's lines, or `[]` when there is nothing to say.
+ *
+ * The shape is the post-run footer's, borrowed rather than invented: a blank
+ * line, `  ! ` and the fact, then indented continuation lines. `!` and not `✓`
+ * or `✗` — something the creator should know, and the command proceeded anyway.
+ * It sits below the success line because it is a footnote about the world rather
+ * than a finding about the run.
+ */
+export declare function renderBehindNotice(notice: BehindNotice | undefined): string[];

package/dist/platform/notice.js

@@ -0,0 +1,66 @@
+const COUNT_WORDS = [
+    "",
+    "One",
+    "Two",
+    "Three",
+    "Four",
+    "Five",
+    "Six",
+    "Seven",
+    "Eight",
+    "Nine",
+    "Ten",
+];
+/**
+ * The notice's lines, or `[]` when there is nothing to say.
+ *
+ * The shape is the post-run footer's, borrowed rather than invented: a blank
+ * line, `  ! ` and the fact, then indented continuation lines. `!` and not `✓`
+ * or `✗` — something the creator should know, and the command proceeded anyway.
+ * It sits below the success line because it is a footnote about the world rather
+ * than a finding about the run.
+ */
+export function renderBehindNotice(notice) {
+    if (notice === undefined || notice.rows.length === 0)
+        return [];
+    // The comparison is STACKED and column-aligned, never inline: two values a
+    // creator has to judge go on their own aligned lines. Padding is computed
+    // from the actual names and versions so a long package identity cannot push
+    // the `current` column out of alignment on one row only.
+    const nameWidth = Math.max(...notice.rows.map((r) => r.name.length));
+    const installedWidth = Math.max(...notice.rows.map((r) => r.installed.length));
+    const rows = notice.rows.map((r) => {
+        const name = r.name.padEnd(nameWidth);
+        const installed = r.installed.padEnd(installedWidth);
+        return `    ${name}  ${installed}  ·  current ${r.current}`;
+    });
+    return [
+        "",
+        `  ! This project is behind the current Vincentt release (${notice.release}).`,
+        ...rows,
+        `    ${noteLine(notice)}`,
+    ];
+}
+/**
+ * The note line. Singular collapses to its own sentence rather than rendering
+ * "1 of 1 carries a migration note", which is a template showing through.
+ *
+ * "No migration note is attached to this one." is the rendered form of an
+ * AUTHORED "no action required" and never of an unauthored one — the platform's
+ * write path refuses to publish a moved version carrying no note, so this line
+ * always means someone decided nothing is needed.
+ */
+function noteLine(notice) {
+    const { noteCount, rows } = notice;
+    if (rows.length === 1) {
+        return noteCount === 1
+            ? "This one carries a migration note."
+            : "No migration note is attached to this one.";
+    }
+    if (noteCount === 0)
+        return "None of these carries a migration note.";
+    return `${countWord(noteCount)} of these carry a migration note.`;
+}
+function countWord(n) {
+    return COUNT_WORDS[n] ?? String(n);
+}

package/dist/platform/offSwitch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `VINCENTT_PLATFORM_CHECK=0` — off means NOT FETCHED, NOT READ, and NOT
+ * WRITTEN.
+ *
+ * The predicate lives in one module and is consulted at THREE sites, all
+ * agreeing: the refresh, the notice's call site BEFORE the cache loader is
+ * invoked, and `outdated`'s read. Three, not two, and the third is named
+ * because f7 shipped its equivalent gate at two of three sites and its own
+ * unbidden read path was missed — that case is still failing on purpose.
+ *
+ * A gate placed AFTER the load still reads the file, which is why the notice
+ * gates at its call site rather than relying on the loader's own check: "off"
+ * that still opens the file is a promise the filesystem can contradict.
+ *
+ * Read from `process.env` on every call rather than memoized at import: a
+ * memo captures whatever the environment was when the module first loaded,
+ * which in a test process is whatever an earlier test left behind.
+ */
+export declare function platformCheckEnabled(): boolean;

package/dist/platform/offSwitch.js

@@ -0,0 +1,21 @@
+/**
+ * `VINCENTT_PLATFORM_CHECK=0` — off means NOT FETCHED, NOT READ, and NOT
+ * WRITTEN.
+ *
+ * The predicate lives in one module and is consulted at THREE sites, all
+ * agreeing: the refresh, the notice's call site BEFORE the cache loader is
+ * invoked, and `outdated`'s read. Three, not two, and the third is named
+ * because f7 shipped its equivalent gate at two of three sites and its own
+ * unbidden read path was missed — that case is still failing on purpose.
+ *
+ * A gate placed AFTER the load still reads the file, which is why the notice
+ * gates at its call site rather than relying on the loader's own check: "off"
+ * that still opens the file is a promise the filesystem can contradict.
+ *
+ * Read from `process.env` on every call rather than memoized at import: a
+ * memo captures whatever the environment was when the module first loaded,
+ * which in a test process is whatever an earlier test left behind.
+ */
+export function platformCheckEnabled() {
+    return process.env.VINCENTT_PLATFORM_CHECK !== "0";
+}

package/dist/platform/outdated.d.ts

@@ -0,0 +1,25 @@
+import type { PlatformRelease } from "./releaseCache.js";
+import type { InstalledSet } from "./behind.js";
+export interface OutdatedView {
+    /** `Name · Workspace`, when this folder is a project. */
+    projectLine?: string;
+    installed: InstalledSet;
+    /** Undefined = there is no current set to compare against; `absentBecause` says why. */
+    current?: PlatformRelease;
+    /**
+     * Why `current` is absent. Two DIFFERENT facts, and one state for both was a
+     * defect: with the check switched off the platform was never contacted, so
+     * "could not reach" is wrong about the cause and "try again when you have a
+     * connection" is advice for a problem the person does not have.
+     */
+    absentBecause?: "unreachable" | "switched_off";
+    /** Human phrase for the release's age, e.g. `3 days ago`. */
+    releasedAgo?: string;
+    /** True when this folder holds no Vincentt project. */
+    outsideProject: boolean;
+    /** The endpoint's address, printed labelled public. */
+    endpointUrl: string;
+}
+export declare function renderOutdated(view: OutdatedView): string[];
+/** A rough human phrase for a release's age. Never a "days behind" count. */
+export declare function releasedAgo(releasedAt: string | undefined, now: number): string | undefined;

package/dist/platform/outdated.js

@@ -0,0 +1,246 @@
+/**
+ * `vincentt outdated` — the whole neutral door.
+ *
+ * NOT `update` and NOT `upgrade`. A verb named after the act implies the CLI
+ * performs it, which it must not, and an agent reading `vincentt update` in any
+ * text will run it. Never name a verb after the act the platform must not
+ * perform.
+ *
+ * SOLICITED output, which is what separates this file from `notice.ts`. It may
+ * instruct, it prints the endpoint's address, and it prints a migration note IN
+ * FULL — a version number tells an agent something changed and only the note
+ * tells it WHAT, which is the load-bearing half of the whole feature.
+ *
+ * It carries the no-plugin population: a creator with no plugin and no agent
+ * reaches every fact this feature produces through this one command. It is also
+ * a security control — it ships named in every scaffolded project's agent
+ * contract and in `--help`, so reaching for it is ordinary population behavior
+ * rather than a signal that a plugin is installed. The copy has to earn that,
+ * which means answering "what is my situation" COMPLETELY rather than reading as
+ * step one of a procedure.
+ *
+ * The vocabulary is fixed and deliberate: "behind" and never "outdated",
+ * "stale", or "out of date" in the COPY (the verb is `outdated` because a
+ * creator types the word they know — two audiences, one deliberate split);
+ * "installed" and never "declared"; "this project came from" for the template,
+ * because it was copied rather than installed; and the word `zone` appears
+ * nowhere, on any surface.
+ */
+import { PLATFORM_PACKAGES, TEMPLATE_COMPONENT } from "./allowlist.js";
+/**
+ * The template's pinning convention, carried here because `place` must print the
+ * string as it appears in the manifest and the two differ ON PURPOSE: the SDK is
+ * pinned EXACTLY and the harness carries a CARET. One renderer serves both the
+ * plugin path and the bare-shell path, so neither invents a range form.
+ */
+const CARET_PINNED = new Set(["@vincentt-xr/harness", "@vincentt-xr/analytics"]);
+export function renderOutdated(view) {
+    const lines = [""];
+    if (view.projectLine !== undefined)
+        lines.push(`  ${view.projectLine}`);
+    // The platform unreachable with a cold cache. This is THE ONE PLACE a fetch
+    // failure is spoken about, and only because it was asked for: the unbidden
+    // notice is silent on failure forever, but a command whose entire subject is
+    // "am I behind" cannot silently print nothing.
+    if (view.current === undefined && view.absentBecause === "switched_off") {
+        // Stating the cause, not diagnosing a fault. The person set this; the only
+        // useful facts are that nothing was checked and what their own versions are.
+        lines.push("", "  · The version check is switched off, so nothing was compared.", "", "    installed on this machine:", ...installedFlat(view.installed, 6), "", "    These are your own versions, read from this folder.", "", "  What is current is readable in a browser, from any machine:", `    ${view.endpointUrl}`);
+        return lines;
+    }
+    if (view.current === undefined) {
+        lines.push("", "  ✗ Could not reach the platform to find out what is current.", "", "    installed on this machine:", ...installedFlat(view.installed, 6), "", "    Nothing was compared. These are your own versions, read from this folder.", "    Run `vincentt outdated` again when you have a connection.", "", "  This is also readable in a browser, from any machine:", `    ${view.endpointUrl}`);
+        return lines;
+    }
+    lines.push(`  Current Vincentt release: ${view.current.release}${view.releasedAgo === undefined ? "" : `   (released ${view.releasedAgo})`}`);
+    // Outside a project the command STILL ANSWERS: "what is current" is a question
+    // whose answer needs no project, and refusing here would make the neutral door
+    // narrower than the endpoint it fronts. No BEHIND/UP TO DATE split, because
+    // there is nothing to be behind — and NO GLYPH, because an absence the command
+    // was not asked to fix is not an advisory.
+    if (view.outsideProject) {
+        lines.push("", ...currentFlat(view.current, 4), "");
+        lines.push("  This folder holds no Vincentt project, so there is nothing to compare against.", "  The versions above are what the platform currently publishes.");
+        lines.push("", ...whereFrom(view.endpointUrl));
+        return lines;
+    }
+    const behind = [];
+    const upToDate = [];
+    for (const pkg of PLATFORM_PACKAGES) {
+        const have = view.installed.packages[pkg.name];
+        if (have === undefined)
+            continue;
+        const component = view.current.components[pkg.name];
+        // A component the composed set does not mention is neither behind nor up to
+        // date: nothing is known about it, so it is omitted rather than described.
+        if (component === undefined)
+            continue;
+        if (component.version === have)
+            upToDate.push({ name: pkg.name, version: have });
+        else
+            behind.push({ name: pkg.name, installed: have, component });
+    }
+    // BEHIND is first, because it answers the question that was asked. The heading
+    // is ABSENT rather than empty when nothing is behind — the absence IS the
+    // answer, and there is no "Everything is current!" line.
+    if (behind.length > 0) {
+        lines.push("", "  BEHIND");
+        for (const row of behind) {
+            lines.push("", `    ${row.name}`, `      installed  ${row.installed}`, `      current    ${row.component.version}`, `      place      ${placeString(row.name, row.component.version)}`, ...noteLines(row.component));
+        }
+    }
+    // UP TO DATE is PRINTED, not omitted: it is the difference between "the
+    // platform checked and this is current" and "the platform did not look", and
+    // it is what makes the answer complete rather than a list of problems.
+    if (upToDate.length > 0) {
+        const width = Math.max(...upToDate.map((r) => r.name.length));
+        lines.push("", "  UP TO DATE", "");
+        for (const row of upToDate) {
+            lines.push(`    ${row.name.padEnd(width)}   ${row.version}`);
+        }
+    }
+    lines.push("", ...templateBlock(view));
+    lines.push("", ...whereFrom(view.endpointUrl));
+    if (behind.length > 0) {
+        // The closing line names the ACT and both actors, and no command. It prints
+        // no install command — the creator's package manager is theirs and we do not
+        // know which — and it does not print `vincentt update`, because no such verb
+        // exists and must not appear to.
+        lines.push("", "  Editing package.json and installing is the whole dependency upgrade. Ask your", "  agent, or do it by hand — the strings to place are above.");
+    }
+    return lines;
+}
+/** The exact string to put in the manifest, quoted as it appears there. */
+function placeString(name, version) {
+    const range = CARET_PINNED.has(name) ? `^${version}` : version;
+    return `"${name}": "${range}"`;
+}
+/**
+ * The note, in full, in the author's words, indented under the component it
+ * belongs to — never in a trailing NOTES section, so the agent editing the SDK
+ * line reads the SDK's note without holding a cross-reference.
+ *
+ * An AUTHORED "no action required" prints as prose in the SAME SLOT. Not
+ * omitted, not `—`, not `(none)`: an agent cannot tell blank from forgotten, so
+ * the platform says which one it is, every time, in the same place.
+ */
+function noteLines(component) {
+    const note = component.migration;
+    if (note === undefined)
+        return [];
+    const out = [];
+    if (note.summary !== "")
+        out.push(...wrap(note.summary, 6));
+    for (const n of note.notes)
+        out.push(...wrap(n, 6));
+    return out;
+}
+/**
+ * The template block. It never says `zone`, names three examples from the
+ * creator's own file tree, and claims NOTHING about `Scene.tsx` except that it
+ * is theirs — no drift count, no diff, no "3 files changed", because this
+ * command does not read the creator's source and the copy must not imply it did.
+ */
+function templateBlock(view) {
+    const current = view.current?.components[TEMPLATE_COMPONENT];
+    const lines = ["  TEMPLATE", ""];
+    const from = view.installed.template;
+    if (from === undefined) {
+        // "not recorded", printed AS A VALUE. Not blank, not `unknown` (a
+        // valid-looking version string), not `latest` (a moving pointer that can be
+        // diffed against nothing). And it names BOTH candidate causes, guessing at
+        // neither — no fingerprinting, no "probably 1.4.x".
+        lines.push("    this project came from  not recorded");
+        if (current !== undefined)
+            lines.push(`    current                 ${current.version}`);
+        lines.push("    This project has no recorded template version, so template drift cannot be", "    stated. Projects created before this was recorded, and projects whose", "    .vincentt/project.json has been replaced, read this way.");
+        return lines;
+    }
+    lines.push(`    this project came from  ${from}`);
+    if (current === undefined) {
+        lines.push("    The platform has not published a current template version, so there is", "    nothing to compare this against.");
+        return lines;
+    }
+    // Both numbers print EVEN WHEN THEY MATCH: "came from 1.5.0, current 1.5.0" is
+    // a stronger statement than silence and costs two lines.
+    lines.push(`    current                 ${current.version}`);
+    if (from !== current.version) {
+        lines.push("    The template is source that was copied into this repository when the project", "    was created. Some of it is platform plumbing you never wrote — the app shell,", "    the helpers, the build config. `src/Scene.tsx` and everything you added is", "    yours, and nothing reports on it but this line.");
+    }
+    return lines;
+}
+/** The endpoint's address, labelled public — the line that makes the fallback real. */
+function whereFrom(url) {
+    return ["  Where these facts come from:", `    ${url}   (public, no account needed)`];
+}
+function installedFlat(set, indent) {
+    const rows = [];
+    for (const pkg of PLATFORM_PACKAGES) {
+        const v = set.packages[pkg.name];
+        if (v !== undefined)
+            rows.push([pkg.name, v]);
+    }
+    if (set.template !== undefined) {
+        rows.push([TEMPLATE_COMPONENT, `${set.template}   (recorded when this project was created)`]);
+    }
+    if (rows.length === 0)
+        return [];
+    const width = Math.max(...rows.map(([n]) => n.length));
+    const pad = " ".repeat(indent);
+    return rows.map(([n, v]) => `${pad}${n.padEnd(width)}   ${v}`);
+}
+function currentFlat(release, indent) {
+    const rows = [];
+    for (const pkg of PLATFORM_PACKAGES) {
+        const c = release.components[pkg.name];
+        if (c !== undefined)
+            rows.push([pkg.name, c.version]);
+    }
+    const template = release.components[TEMPLATE_COMPONENT];
+    if (template !== undefined)
+        rows.push([TEMPLATE_COMPONENT, template.version]);
+    if (rows.length === 0)
+        return [];
+    const width = Math.max(...rows.map(([n]) => n.length));
+    const pad = " ".repeat(indent);
+    return rows.map(([n, v]) => `${pad}${n.padEnd(width)}   ${v}`);
+}
+/** Wrap prose to a terminal-friendly width at the given indent. */
+function wrap(text, indent) {
+    const width = 78 - indent;
+    const pad = " ".repeat(indent);
+    const words = text.split(/\s+/).filter((w) => w !== "");
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        if (current === "")
+            current = word;
+        else if (`${current} ${word}`.length <= width)
+            current += ` ${word}`;
+        else {
+            lines.push(`${pad}${current}`);
+            current = word;
+        }
+    }
+    if (current !== "")
+        lines.push(`${pad}${current}`);
+    return lines;
+}
+/** A rough human phrase for a release's age. Never a "days behind" count. */
+export function releasedAgo(releasedAt, now) {
+    if (releasedAt === undefined)
+        return undefined;
+    const at = Date.parse(releasedAt);
+    if (!Number.isFinite(at))
+        return undefined;
+    const ms = now - at;
+    if (ms < 0)
+        return undefined;
+    const hours = Math.floor(ms / 3_600_000);
+    if (hours < 1)
+        return "less than an hour ago";
+    if (hours < 24)
+        return `${hours} ${hours === 1 ? "hour" : "hours"} ago`;
+    const days = Math.floor(hours / 24);
+    return `${days} ${days === 1 ? "day" : "days"} ago`;
+}

package/dist/platform/releaseCache.d.ts

@@ -0,0 +1,69 @@
+/** One component's current version, as the platform publishes it. */
+export interface ReleaseComponent {
+    version: string;
+    /**
+     * ABSENT means unauthored — a different fact from `{required: false}`, which
+     * is the AUTHORED "no action required". Collapsing them silently defeats the
+     * argument that a note is accurate or absent and never speculative: an agent
+     * cannot tell blank from forgotten, so the platform must say which one it is.
+     */
+    migration?: ReleaseMigration;
+}
+export interface ReleaseMigration {
+    required: boolean;
+    summary: string;
+    notes: string[];
+}
+export interface PlatformRelease {
+    /**
+     * `"2026.09.3"` — an IDENTIFIER, never semver, never version-compared. It is
+     * compared for EQUALITY only, which is what makes the notice fire once per
+     * changed release rather than once per interval.
+     */
+    release: string;
+    releasedAt?: string;
+    /** Keyed by package identity (`@vincentt-xr/sdk`), never repo shorthand. */
+    components: Record<string, ReleaseComponent>;
+}
+export interface ReleaseCache {
+    release: PlatformRelease;
+    /** When it was fetched (epoch ms). */
+    at: number;
+    /** The release identifier this machine has already announced, if any. */
+    announcedRelease?: string;
+    etag?: string;
+}
+/**
+ * Freshness, with a clock that moved backwards treated as STALE rather than as
+ * fresh forever. Same rule and same TTL as the CLI update check — reused rather
+ * than re-chosen, because two "how often do we ask" constants drift and the
+ * second one is always the one nobody knows about.
+ */
+export declare function isReleaseFresh(cache: ReleaseCache | undefined, now: number): boolean;
+/**
+ * Parse defensively and STRICTLY. A hand-edited or half-written file must
+ * degrade to "no cache" rather than to a bogus comparison — a partially-parsed
+ * release would produce a notice about versions nobody publishes.
+ */
+export declare function readReleaseCache(raw: unknown): ReleaseCache | undefined;
+/**
+ * Parse the endpoint's body. A component whose version is not a non-empty string
+ * is DROPPED rather than failing the whole document: the platform composes the
+ * set from one row per component, so a single malformed component is not a
+ * reason to know nothing about the others. A MALFORMED MIGRATION NOTE IS TREATED
+ * AS ABSENT and never partially parsed — half a note is worse than none, because
+ * the half that survives reads as complete.
+ */
+export declare function readPlatformRelease(raw: unknown): PlatformRelease | undefined;
+export declare function releaseCachePath(): string;
+/**
+ * Read the cache. Any fault reads as "no cache".
+ *
+ * OFF-SWITCH SITE: with the check off this returns undefined WITHOUT touching
+ * the file. Callers also gate before calling (see `notice.ts`), because a gate
+ * placed only here still means the loader was invoked — and the requirement is
+ * that off means not read at all.
+ */
+export declare function loadReleaseCache(): ReleaseCache | undefined;
+/** Write the cache. Best-effort: a cache that cannot be written asks again. */
+export declare function saveReleaseCache(cache: ReleaseCache): void;

package/dist/platform/releaseCache.js

@@ -0,0 +1,140 @@
+/**
+ * `~/.vincentt/platform-release.json` — the machine-wide answer to "what does
+ * the platform currently publish", plus the record of what this machine has
+ * already said out loud.
+ *
+ * `announcedRelease` is STORED rather than derived, and that is the whole reason
+ * this file holds more than the fetched payload. Derived, "we already told them"
+ * is unfalsifiable: a creator who says they were never told about the new SDK
+ * cannot be answered, and the platform cannot know either. Stored, it is a fact
+ * on disk with the creator's cooperation.
+ *
+ * Nothing here is a secret and nothing here is state a creator would miss, so
+ * the write is best-effort and non-atomic, unlike the machine config. A torn
+ * write costs one extra fetch.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CHECK_TTL_MS } from "../dx/updateCheck.js";
+import { platformCheckEnabled } from "./offSwitch.js";
+const CACHE_FILE = "platform-release.json";
+/**
+ * Freshness, with a clock that moved backwards treated as STALE rather than as
+ * fresh forever. Same rule and same TTL as the CLI update check — reused rather
+ * than re-chosen, because two "how often do we ask" constants drift and the
+ * second one is always the one nobody knows about.
+ */
+export function isReleaseFresh(cache, now) {
+    if (cache === undefined)
+        return false;
+    if (!Number.isFinite(cache.at))
+        return false;
+    const age = now - cache.at;
+    return age >= 0 && age < CHECK_TTL_MS;
+}
+/**
+ * Parse defensively and STRICTLY. A hand-edited or half-written file must
+ * degrade to "no cache" rather than to a bogus comparison — a partially-parsed
+ * release would produce a notice about versions nobody publishes.
+ */
+export function readReleaseCache(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const { release, at, announcedRelease, etag } = raw;
+    const parsed = readPlatformRelease(release);
+    if (parsed === undefined)
+        return undefined;
+    if (typeof at !== "number" || !Number.isFinite(at))
+        return undefined;
+    const cache = { release: parsed, at };
+    if (typeof announcedRelease === "string" && announcedRelease !== "") {
+        cache.announcedRelease = announcedRelease;
+    }
+    if (typeof etag === "string" && etag !== "")
+        cache.etag = etag;
+    return cache;
+}
+/**
+ * Parse the endpoint's body. A component whose version is not a non-empty string
+ * is DROPPED rather than failing the whole document: the platform composes the
+ * set from one row per component, so a single malformed component is not a
+ * reason to know nothing about the others. A MALFORMED MIGRATION NOTE IS TREATED
+ * AS ABSENT and never partially parsed — half a note is worse than none, because
+ * the half that survives reads as complete.
+ */
+export function readPlatformRelease(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const { release, releasedAt, components } = raw;
+    if (typeof release !== "string" || release === "")
+        return undefined;
+    if (typeof components !== "object" || components === null)
+        return undefined;
+    const out = {};
+    for (const [name, value] of Object.entries(components)) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const { version, migration } = value;
+        if (typeof version !== "string" || version === "")
+            continue;
+        const component = { version };
+        const note = readMigration(migration);
+        if (note !== undefined)
+            component.migration = note;
+        out[name] = component;
+    }
+    const parsed = { release, components: out };
+    if (typeof releasedAt === "string" && releasedAt !== "")
+        parsed.releasedAt = releasedAt;
+    return parsed;
+}
+function readMigration(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const { required, summary, notes } = raw;
+    // `required` is MANDATORY and boolean. Absent or non-boolean is an unauthored
+    // note, not a defaulted one: defaulting it to false would manufacture the
+    // authored "no action required" out of a parse failure.
+    if (typeof required !== "boolean")
+        return undefined;
+    if (typeof summary !== "string")
+        return undefined;
+    const list = Array.isArray(notes)
+        ? notes.filter((n) => typeof n === "string")
+        : [];
+    return { required, summary, notes: list };
+}
+export function releaseCachePath() {
+    return path.join(os.homedir(), ".vincentt", CACHE_FILE);
+}
+/**
+ * Read the cache. Any fault reads as "no cache".
+ *
+ * OFF-SWITCH SITE: with the check off this returns undefined WITHOUT touching
+ * the file. Callers also gate before calling (see `notice.ts`), because a gate
+ * placed only here still means the loader was invoked — and the requirement is
+ * that off means not read at all.
+ */
+export function loadReleaseCache() {
+    if (!platformCheckEnabled())
+        return undefined;
+    try {
+        return readReleaseCache(JSON.parse(fs.readFileSync(releaseCachePath(), "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Write the cache. Best-effort: a cache that cannot be written asks again. */
+export function saveReleaseCache(cache) {
+    if (!platformCheckEnabled())
+        return;
+    try {
+        fs.mkdirSync(path.dirname(releaseCachePath()), { recursive: true });
+        fs.writeFileSync(releaseCachePath(), JSON.stringify(cache) + "\n", "utf8");
+    }
+    catch {
+        // Nothing here is worth failing a verb over.
+    }
+}

package/dist/platform/releaseFetch.d.ts

@@ -0,0 +1,51 @@
+import { type PlatformRelease } from "./releaseCache.js";
+export declare const VERSIONS_PATH = "/platform/versions";
+export interface FetchReleaseResult {
+    release: PlatformRelease;
+    etag?: string;
+}
+export interface FetchReleaseOptions {
+    /** The API origin. */
+    apiUrl: string;
+    /** Sent as `If-None-Match`. The only request header that changes the response. */
+    etag?: string;
+    signal?: AbortSignal;
+    /** Test seam. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Fetch the current set. `undefined` means nothing to say, including on a `304`
+ * — the caller already holds that answer in its cache and a 304 is not new
+ * information.
+ *
+ * OFF-SWITCH SITE (the refresh): with the check off no request is made at all.
+ */
+export declare function fetchRelease(opts: FetchReleaseOptions): Promise<FetchReleaseResult | undefined>;
+/**
+ * The same read, on an UNREF'D SOCKET, for the unbidden path only.
+ *
+ * WHY THIS EXISTS AND IS NOT `fetch`. The design's performance guarantee is
+ * structural: `preview`'s time-to-URL must not move, and the mechanism named for
+ * it is an `unref`'d refresh. Measured, `unref`'ing the TIMERS is not sufficient
+ * — a pending `fetch` keeps its SOCKET as an active handle, and the platform
+ * exposes no way to unref it, so a verb run against an endpoint that accepts the
+ * connection and never answers waits the full budget before exiting. Against a
+ * healthy endpoint nobody notices; against a hung one every command appears to
+ * hang, and the delay lands on `preview`, where someone is waiting to open a URL
+ * on a phone. That is the exact failure the guarantee was written to exclude.
+ *
+ * `node:http` with `socket.unref()` exits immediately (measured: 2ms against the
+ * same hung endpoint), so the unbidden path uses it and the guarantee holds as a
+ * property rather than as an aspiration. `fetchRelease` above keeps `fetch` and
+ * its injectable seam for `outdated`, which was ASKED for and may legitimately
+ * wait.
+ *
+ * Best-effort throughout, and `undefined` on every fault — including a body that
+ * arrives after the process has already exited, which is the normal case here
+ * and is why this writes through a callback rather than returning a promise the
+ * caller could await.
+ */
+export declare function fetchReleaseDetached(opts: {
+    apiUrl: string;
+    etag?: string;
+}, onResult: (result: FetchReleaseResult) => void): void;