@vincentt-xr/cli 0.15.2 → 0.17.0

package/dist/dx/unbiddenVerbs.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The verbs unbidden output may not contain.
+ *
+ * Unbidden output lands in an agent's transcript, and an agent that reads an
+ * instruction will simply obey it. Naming that a command exists is information;
+ * telling a caller to transmit — or to grant itself permission to — is not. A
+ * REFUSAL may name both, because a refusal is solicited
+ * (D-A-refusal-is-solicited-output), so this list constrains only output the
+ * caller did not ask for.
+ *
+ * It is exported rather than restated at each site because every additional
+ * consumer is another chance for the lists to drift apart, and a guard that has
+ * quietly stopped matching its sibling still passes.
+ *
+ * `please`, `should` and `must` are not verbs. They are here because they are
+ * how an imperative gets smuggled past a verb-only list ("you should enable
+ * this"), and the guard is about directing rather than about grammar.
+ */
+export declare const UNBIDDEN_FORBIDDEN_VERBS: readonly ["run", "send", "report", "submit", "share", "try", "use", "execute", "enable", "please", "should", "must"];
+export type UnbiddenForbiddenVerb = (typeof UNBIDDEN_FORBIDDEN_VERBS)[number];
+/**
+ * Word-boundary, case-insensitive — the form every consumer needs, built here so
+ * a consumer cannot get the boundary or the flags subtly wrong.
+ */
+export declare function unbiddenVerbPattern(verb: string): RegExp;

package/dist/dx/unbiddenVerbs.js

@@ -0,0 +1,39 @@
+/**
+ * The verbs unbidden output may not contain.
+ *
+ * Unbidden output lands in an agent's transcript, and an agent that reads an
+ * instruction will simply obey it. Naming that a command exists is information;
+ * telling a caller to transmit — or to grant itself permission to — is not. A
+ * REFUSAL may name both, because a refusal is solicited
+ * (D-A-refusal-is-solicited-output), so this list constrains only output the
+ * caller did not ask for.
+ *
+ * It is exported rather than restated at each site because every additional
+ * consumer is another chance for the lists to drift apart, and a guard that has
+ * quietly stopped matching its sibling still passes.
+ *
+ * `please`, `should` and `must` are not verbs. They are here because they are
+ * how an imperative gets smuggled past a verb-only list ("you should enable
+ * this"), and the guard is about directing rather than about grammar.
+ */
+export const UNBIDDEN_FORBIDDEN_VERBS = Object.freeze([
+    "run",
+    "send",
+    "report",
+    "submit",
+    "share",
+    "try",
+    "use",
+    "execute",
+    "enable",
+    "please",
+    "should",
+    "must",
+]);
+/**
+ * Word-boundary, case-insensitive — the form every consumer needs, built here so
+ * a consumer cannot get the boundary or the flags subtly wrong.
+ */
+export function unbiddenVerbPattern(verb) {
+    return new RegExp(`\\b${verb}\\b`, "i");
+}

package/dist/lib/initCommand.d.ts

@@ -1,10 +1,11 @@
+import { type ScaffoldOutcome } from "../scaffold/index.js";
 import type { RegisterDeps } from "./initFrom.js";
 import { type SourceRef } from "./sourceRef.js";
 import type { Ask, Confirm } from "../publish/prompt.js";
 export interface InitDeps {
     print: (line: string) => void;
     cwd: string;
-    scaffold?: (targetDir: string, opts: ScaffoldCall) => Promise<void>;
+    scaffold?: (targetDir: string, opts: ScaffoldCall) => Promise<ScaffoldOutcome>;
     install?: (targetDir: string) => Promise<string>;
     isEmpty?: (targetDir: string) => Promise<boolean>;
     /** Free-text prompt. Absent → not a TTY, so nothing may be asked. */
@@ -20,6 +21,7 @@ export interface InitDeps {
     register?: (deps: Pick<RegisterDeps, "print" | "targetDir" | "dirLabel" | "ask">, opts: {
         name?: string;
         slug?: string;
+        templateVersion?: string;
     }) => Promise<number>;
 }
 /**

package/dist/lib/initCommand.js

@@ -93,6 +93,10 @@ export async function initCommand(deps, opts = {}) {
     const scaffold = deps.scaffold ??
         ((dir, o) => scaffoldFromTemplate(dir, o));
     try {
+        // The result is deliberately discarded here. `init` writes no
+        // `.vincentt/project.json` at all on the bare path (that is the whole
+        // no-account wedge), and its only registering path is `--from`, whose
+        // baseline is refused below for naming a different repository.
         await scaffold(target, opts.from
             ? { repo: templateCloneURL(opts.from.owner, opts.from.repo), ref: opts.from.tag }
             : { ref: opts.template });
@@ -164,6 +168,12 @@ export async function initCommand(deps, opts = {}) {
     const register = deps.register;
     if (!register)
         return 0;
+    // NO baseline on the `--from` path, and that is not an oversight. A gallery
+    // source is a different repository, so a version tag in it names that repo's
+    // release and not a v2-template version — recording it would hand a later
+    // upgrade a baseline that resolves against the wrong remote entirely, which is
+    // worse than the no-baseline path it takes instead. `register` is unreachable
+    // unless `--from` was given, so this call never carries one.
     const code = await register({ print: deps.print, targetDir: target, dirLabel: label, ask: deps.ask }, { name: opts.name, slug: opts.slug });
     if (code !== 0)
         return code;

package/dist/lib/projects.d.ts

@@ -1,6 +1,7 @@
 import { type FolderCase } from "./classifyTarget.js";
 import { type OrgSource } from "./initFrom.js";
 import type { ScaffoldCall } from "./initCommand.js";
+import { type ScaffoldOutcome } from "../scaffold/index.js";
 import type { Ask } from "../publish/prompt.js";
 import { type ResolvedConfig } from "../shared/config.js";
 export interface ProjectCommandDeps {
@@ -33,7 +34,7 @@ export interface CreateCommandDeps extends ProjectCommandDeps {
     mkdir?: (dir: string) => Promise<void>;
     /** Resolve a path through its symlinks, for the classify→write re-check. */
     realpath?: (dir: string) => Promise<string>;
-    scaffold?: (dir: string, opts: ScaffoldCall) => Promise<void>;
+    scaffold?: (dir: string, opts: ScaffoldCall) => Promise<ScaffoldOutcome>;
     install?: (dir: string) => Promise<string>;
     detectPm?: (dir: string) => Promise<string>;
     /** Free-text prompt. Absent → not a TTY, so nothing may be asked. */
@@ -60,6 +61,12 @@ export interface CreateCommandOptions {
      * bounded re-ask). See the throw site.
      */
     rethrowSlugTaken?: boolean;
+    /**
+     * The concrete template version the scaffold above this call resolved, recorded
+     * into the binding as the drift baseline. Absent when nothing was scaffolded
+     * (registering a folder that already holds an app) or when resolution failed.
+     */
+    templateVersion?: string;
 }
 /**
  * `vincentt create` — a TWO-HALF verb with one seam.

package/dist/lib/projects.js

@@ -86,6 +86,10 @@ export async function createCommand(deps, opts = {}) {
     let installed = true;
     let pm = "npm";
     let actedOn = dirLabel;
+    // Case 2 (an app already on disk) leaves this absent: this command did not
+    // scaffold that tree, so it knows nothing about which template version it came
+    // from, and inventing one is the wrong-baseline failure.
+    let templateVersion;
     if (folderCase === "empty") {
         const wrote = await scaffoldInto(deps, target, dirLabel, opts);
         if (!wrote.ok)
@@ -93,6 +97,7 @@ export async function createCommand(deps, opts = {}) {
         scaffolded = true;
         installed = wrote.installed;
         pm = wrote.pm;
+        templateVersion = wrote.templateVersion;
     }
     else {
         // Case 2 writes too — a binding and a .gitignore line — so it runs the same
@@ -157,6 +162,7 @@ export async function createCommand(deps, opts = {}) {
             dir: opts.dir,
             name,
             slug,
+            templateVersion,
             rethrowSlugTaken: true,
         }),
     }, 
@@ -280,8 +286,9 @@ async function scaffoldInto(deps, target, dirLabel, opts) {
     // which it could — which is exactly what `--template`/`--from` being refused at
     // the parser makes structurally true, and what the install below rests on.
     const scaffold = deps.scaffold ?? ((dir, o) => scaffoldFromTemplate(dir, o));
+    let scaffoldResult;
     try {
-        await scaffold(target, {});
+        scaffoldResult = await scaffold(target, {});
     }
     catch (err) {
         // No `✓ Created`, so no registration is attempted, and this arm carries
@@ -307,7 +314,7 @@ async function scaffoldInto(deps, target, dirLabel, opts) {
     const pm = await detect(target).catch(() => "npm");
     deps.print("");
     deps.print(`✓ Created ${dirLabel}`);
-    return { ok: true, installed, pm };
+    return { ok: true, installed, pm, templateVersion: scaffoldResult?.templateVersion };
 }
 /**
  * The registration half — the binding guard's remainder, the slug derivation, the
@@ -355,6 +362,9 @@ export async function registerProject(deps, opts = {}) {
     await writeProjectBinding(target, {
         projectId: created.projectId,
         slug: created.slug,
+        // Omitted, never `latest`: absence is the honest no-baseline state, and it is
+        // the one that makes a later upgrade report rather than overwrite.
+        ...(opts.templateVersion ? { template: { version: opts.templateVersion } } : {}),
     });
     deps.print(`✓ Created ${created.name} in ${org.org.name}`);
     deps.print(`  Address reserved:  ${created.liveUrl}`);

package/dist/platform/allowlist.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The packages the platform publishes, frozen.
+ *
+ * This list is what makes `B-F17-1` a structural property rather than a promise:
+ * the resolver ITERATES it and reads only the manifests it names, so a
+ * third-party package name is never in the CLI's memory — not read, not
+ * filtered, not dropped. "Filter the creator's dependency graph" produces the
+ * same wire payload today and leaks the whole graph the first time someone
+ * spreads the intermediate value into a log line or a report.
+ *
+ * ORDER IS PART OF THE CONTRACT. Every surface that renders a version set
+ * renders it in this order — the notice's rows, `outdated`'s sections, and the
+ * report's one-line summary — so two surfaces can never disagree about
+ * sequence, and the wire field's key order is stable for the byte-identity
+ * assertion across the publish and report payloads.
+ */
+export interface PlatformPackage {
+    /** The package identity — the string in the creator's own dependency manifest. */
+    name: string;
+    /**
+     * The short name used only where a person reads three names in one pass (the
+     * payload preview's summary line). The WIRE always carries `name`: an agent
+     * handed `sdk` cannot find it in a `package.json`.
+     */
+    short: string;
+}
+export declare const PLATFORM_PACKAGES: readonly PlatformPackage[];
+/**
+ * The template's short name. It is NOT a package: it has no `node_modules`
+ * entry, it was copied rather than installed, and its version comes from the
+ * project binding. It is named here so the surfaces that render it last are
+ * reading one constant rather than each spelling it.
+ */
+export declare const TEMPLATE_COMPONENT = "template";
+export declare function isPlatformPackage(name: string): boolean;
+export declare function shortNameOf(name: string): string;

package/dist/platform/allowlist.js

@@ -0,0 +1,34 @@
+/**
+ * The packages the platform publishes, frozen.
+ *
+ * This list is what makes `B-F17-1` a structural property rather than a promise:
+ * the resolver ITERATES it and reads only the manifests it names, so a
+ * third-party package name is never in the CLI's memory — not read, not
+ * filtered, not dropped. "Filter the creator's dependency graph" produces the
+ * same wire payload today and leaks the whole graph the first time someone
+ * spreads the intermediate value into a log line or a report.
+ *
+ * ORDER IS PART OF THE CONTRACT. Every surface that renders a version set
+ * renders it in this order — the notice's rows, `outdated`'s sections, and the
+ * report's one-line summary — so two surfaces can never disagree about
+ * sequence, and the wire field's key order is stable for the byte-identity
+ * assertion across the publish and report payloads.
+ */
+export const PLATFORM_PACKAGES = Object.freeze([
+    Object.freeze({ name: "@vincentt-xr/sdk", short: "sdk" }),
+    Object.freeze({ name: "@vincentt-xr/harness", short: "harness" }),
+    Object.freeze({ name: "@vincentt-xr/analytics", short: "analytics" }),
+]);
+/**
+ * The template's short name. It is NOT a package: it has no `node_modules`
+ * entry, it was copied rather than installed, and its version comes from the
+ * project binding. It is named here so the surfaces that render it last are
+ * reading one constant rather than each spelling it.
+ */
+export const TEMPLATE_COMPONENT = "template";
+export function isPlatformPackage(name) {
+    return PLATFORM_PACKAGES.some((p) => p.name === name);
+}
+export function shortNameOf(name) {
+    return PLATFORM_PACKAGES.find((p) => p.name === name)?.short ?? name;
+}

package/dist/platform/behind.d.ts

@@ -0,0 +1,41 @@
+import type { PlatformRelease } from "./releaseCache.js";
+export interface BehindRow {
+    /** The package identity — the string in the creator's own manifest. */
+    name: string;
+    installed: string;
+    current: string;
+    /** Whether the platform authored a note. NEVER the note itself. */
+    hasMigrationNote: boolean;
+}
+export interface BehindNotice {
+    /** The release identifier, stated because this is what the notice fires once per. */
+    release: string;
+    rows: BehindRow[];
+    /** How many rows carry an authored note. Counted, never quoted. */
+    noteCount: number;
+}
+export interface InstalledSet {
+    /** Keyed by package identity. */
+    packages: Record<string, string>;
+    /** The recorded template baseline. Absent = not recorded. */
+    template?: string;
+}
+/**
+ * Build the notice struct, or `undefined` when there is nothing to say.
+ *
+ * A component the composed set does not mention is NOT BEHIND and is not
+ * reported: on the day this ships every component is absent, which is neither
+ * behind nor up to date, and describing it would put a row of nothing in front
+ * of every creator. Absent is absent — never inferred, never rendered as a
+ * value, never dressed up as a state.
+ */
+export declare function behindFor(installed: InstalledSet, current: PlatformRelease | undefined): BehindNotice | undefined;
+/**
+ * Whether this machine has already announced this release.
+ *
+ * Equality on the identifier, and the announced value is READ FROM THE CACHE
+ * rather than derived. Time governs how often we ask; the fact governs whether
+ * we speak — so the second run today is silent, the fortieth is silent, and so
+ * is tomorrow's, until the identifier changes.
+ */
+export declare function alreadyAnnounced(announcedRelease: string | undefined, release: string): boolean;

package/dist/platform/behind.js

@@ -0,0 +1,82 @@
+/**
+ * The comparison: this project's versions against what the platform publishes.
+ *
+ * THE OUTPUT TYPE CARRIES NO COMMAND STRING, NO URL, AND NO NOTE BODY. That is
+ * the primary guard on the unbidden notice and it is structural: an instruction
+ * is UNRENDERABLE rather than merely unwritten, because the renderer is never
+ * handed anything it could instruct with. A prose guard over the rendered lines
+ * is the second layer, not the first — a single-regex guard on exactly this
+ * class shipped once and six phrasings walked past it.
+ *
+ * `hasMigrationNote` is a BOOLEAN for the same reason. A count says "there are
+ * instructions somewhere" and leaves the reader to ask for them; the body would
+ * say "here are the instructions", which is the sentence an autonomous caller
+ * acts on.
+ *
+ * NOTHING BRANCHES ON A VERSION. Equality decides behind-or-current, and the
+ * release identifier is compared for equality only. There is no ordering
+ * comparison anywhere in this module: `YYYY.MM.N` is an identifier, and an
+ * installed version is evidence rather than authorization.
+ */
+import { PLATFORM_PACKAGES, TEMPLATE_COMPONENT } from "./allowlist.js";
+/**
+ * Build the notice struct, or `undefined` when there is nothing to say.
+ *
+ * A component the composed set does not mention is NOT BEHIND and is not
+ * reported: on the day this ships every component is absent, which is neither
+ * behind nor up to date, and describing it would put a row of nothing in front
+ * of every creator. Absent is absent — never inferred, never rendered as a
+ * value, never dressed up as a state.
+ */
+export function behindFor(installed, current) {
+    if (current === undefined)
+        return undefined;
+    const rows = [];
+    // ALLOWLIST ORDER, not object order, so every surface renders the same
+    // sequence and two surfaces can never disagree.
+    for (const pkg of PLATFORM_PACKAGES) {
+        const have = installed.packages[pkg.name];
+        const component = current.components[pkg.name];
+        if (have === undefined || component === undefined)
+            continue;
+        if (have === component.version)
+            continue;
+        rows.push({
+            name: pkg.name,
+            installed: have,
+            current: component.version,
+            hasMigrationNote: component.migration !== undefined,
+        });
+    }
+    // The template last, and it is not a package: printed bare, which is also how
+    // it distinguishes itself as the one entry that is not a dependency.
+    const templateCurrent = current.components[TEMPLATE_COMPONENT];
+    if (installed.template !== undefined &&
+        templateCurrent !== undefined &&
+        installed.template !== templateCurrent.version) {
+        rows.push({
+            name: TEMPLATE_COMPONENT,
+            installed: installed.template,
+            current: templateCurrent.version,
+            hasMigrationNote: templateCurrent.migration !== undefined,
+        });
+    }
+    if (rows.length === 0)
+        return undefined;
+    return {
+        release: current.release,
+        rows,
+        noteCount: rows.filter((r) => r.hasMigrationNote).length,
+    };
+}
+/**
+ * Whether this machine has already announced this release.
+ *
+ * Equality on the identifier, and the announced value is READ FROM THE CACHE
+ * rather than derived. Time governs how often we ask; the fact governs whether
+ * we speak — so the second run today is silent, the fortieth is silent, and so
+ * is tomorrow's, until the identifier changes.
+ */
+export function alreadyAnnounced(announcedRelease, release) {
+    return announcedRelease === release;
+}

package/dist/platform/command.d.ts

@@ -0,0 +1,16 @@
+import type { InstalledSet } from "./behind.js";
+export interface OutdatedDeps {
+    print: (line: string) => void;
+    cwd: string;
+    now: () => number;
+    /** The API origin, and the base of the address printed to the creator. */
+    apiUrl: () => Promise<string>;
+    /** `Name · Workspace` when this folder is a project; undefined outside one. */
+    projectLine: () => Promise<string | undefined>;
+    /** Whether this folder resolves a project binding. */
+    inProject: () => Promise<boolean>;
+    fetchImpl?: typeof fetch;
+}
+export declare function outdatedCommand(deps: OutdatedDeps): Promise<number>;
+/** Nothing installed and no baseline → the flat "what is current" answer still prints. */
+export declare function hasAnyInstalled(installed: InstalledSet): boolean;

package/dist/platform/command.js

@@ -0,0 +1,90 @@
+/**
+ * `vincentt outdated`'s I/O half: resolve what this folder has, read or fetch
+ * what the platform publishes, and hand both to the renderer.
+ *
+ * This is the THIRD off-switch site. With `VINCENTT_PLATFORM_CHECK=0` it
+ * performs no fetch AND no cache read — off means not fetched, not read, and not
+ * written. The refresh is the first site and the notice's call site is the
+ * second; f7 shipped its equivalent gate at two of three and its unbidden read
+ * path was missed, which is why the third is named explicitly rather than
+ * assumed to follow.
+ *
+ * Unlike the notice, this verb MAY await the network: it was asked for, and a
+ * command whose whole subject is "am I behind" cannot answer from a cold cache
+ * by printing nothing.
+ */
+import { PLATFORM_PACKAGES } from "./allowlist.js";
+import { resolveBuiltWith } from "./resolve.js";
+import { isReleaseFresh, loadReleaseCache, saveReleaseCache, } from "./releaseCache.js";
+import { fetchRelease } from "./releaseFetch.js";
+import { renderOutdated, releasedAgo } from "./outdated.js";
+import { platformCheckEnabled } from "./offSwitch.js";
+export async function outdatedCommand(deps) {
+    const apiUrl = await deps.apiUrl();
+    const inProject = await deps.inProject();
+    const builtWith = await resolveBuiltWith(deps.cwd);
+    const installed = {
+        packages: builtWith?.packages ?? {},
+        template: builtWith?.template,
+    };
+    // Read the switch HERE as well as inside currentRelease, so the view can say
+    // WHY there is nothing to compare. "Could not reach" is wrong when the person
+    // switched the check off, and the retry advice is advice for a problem they do
+    // not have.
+    const switchedOff = !platformCheckEnabled();
+    const current = await currentRelease(deps, apiUrl);
+    const view = {
+        projectLine: inProject ? await deps.projectLine() : undefined,
+        installed,
+        current,
+        absentBecause: current !== undefined ? undefined : switchedOff ? "switched_off" : "unreachable",
+        releasedAgo: releasedAgo(current?.releasedAt, deps.now()),
+        outsideProject: !inProject,
+        endpointUrl: `${apiUrl.replace(/\/$/, "")}/platform/versions`,
+    };
+    for (const line of renderOutdated(view))
+        deps.print(line);
+    // Exit 0 on every path INCLUDING the unreachable one: nothing the creator
+    // asked for failed, and a listing verb that exits non-zero because the network
+    // was down teaches an agent to retry a read that will not change.
+    return 0;
+}
+/**
+ * The current set: a fresh cache, else a fetch, else the stale cache, else
+ * nothing.
+ *
+ * A STALE cache is still used when the fetch fails, because an older true
+ * statement beats no statement on a surface that was asked for — and the
+ * alternative is telling a creator on a train that nothing is known.
+ */
+async function currentRelease(deps, apiUrl) {
+    // OFF-SWITCH SITE 3, before any read.
+    if (!platformCheckEnabled())
+        return undefined;
+    const cached = loadReleaseCache();
+    if (isReleaseFresh(cached, deps.now()))
+        return cached?.release;
+    const fetched = await fetchRelease({
+        apiUrl,
+        etag: cached?.etag,
+        fetchImpl: deps.fetchImpl,
+    });
+    if (fetched !== undefined) {
+        saveReleaseCache({
+            release: fetched.release,
+            at: deps.now(),
+            // The announcement record is PRESERVED across a refresh: this verb is
+            // solicited and says nothing about whether the unbidden notice has
+            // spoken, so overwriting it here would silently re-arm the notice.
+            announcedRelease: cached?.announcedRelease,
+            etag: fetched.etag,
+        });
+        return fetched.release;
+    }
+    return cached?.release;
+}
+/** Nothing installed and no baseline → the flat "what is current" answer still prints. */
+export function hasAnyInstalled(installed) {
+    return (PLATFORM_PACKAGES.some((p) => installed.packages[p.name] !== undefined) ||
+        installed.template !== undefined);
+}

package/dist/platform/footer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The unbidden notice's call site, and the `unref`'d refresh behind it.
+ *
+ * DISCOVERY RIDES ON CREATOR-INITIATED COMMANDS ONLY. There is no timer, no
+ * daemon, no background poll, and no scheduled check anywhere in this feature —
+ * a "just check daily" implementation is the most likely way to break that, and
+ * it would be a transmission the creator did not initiate. What is time-bounded
+ * is how often we ASK; whether we SPEAK is governed by the fact changing.
+ *
+ * The line printed always comes from the PREVIOUS run's cache and the fetch is
+ * never awaited, so no verb pays for this. The consequence is accepted: a fresh
+ * install is quiet on its first run, and a creator who just installed is current
+ * by definition.
+ *
+ * OFF-SWITCH SITE 2 is `behindFooterLines`, and the gate is BEFORE
+ * `loadReleaseCache()` rather than inside it. A gate placed after the load still
+ * reads the file, and the requirement is that off means not read.
+ */
+import { type InstalledSet } from "./behind.js";
+import { type ReleaseCache } from "./releaseCache.js";
+export interface FooterDeps {
+    installed: InstalledSet;
+    now: () => number;
+    /** Injected so the notice's decision is testable without a home directory. */
+    loadCache?: () => ReleaseCache | undefined;
+    saveCache?: (cache: ReleaseCache) => void;
+}
+/**
+ * The notice's lines, and the announcement recorded when it fires.
+ *
+ * Firing WRITES `announcedRelease`, which is what closes the nag by mechanism
+ * rather than by tone: the second run on the same release finds them equal and
+ * the renderer is never called. The silence after the first announcement is
+ * byte-identical to the silence of a caller with nothing to say, so the line
+ * cannot degrade into a quieter nag.
+ */
+export declare function behindFooterLines(deps: FooterDeps): string[];
+/** Whether the cache is due a refresh. Separate so the caller can gate first. */
+export declare function needsRefresh(cache: ReleaseCache | undefined, now: number): boolean;
+/**
+ * Refresh the cached release without holding the process open.
+ *
+ * `unref` is the load-bearing call, and it is the reason `preview`'s
+ * time-to-URL does not move: without it a 2s request keeps the event loop alive
+ * after the verb is done, so every command appears to hang — and the delay would
+ * land on `preview`, where someone is waiting to open a URL on a phone.
+ *
+ * OFF-SWITCH SITE 1 is `fetchRelease` itself, plus the gate here so no timer is
+ * even created.
+ */
+export declare function refreshReleaseCache(opts: {
+    apiUrl: string;
+    now: () => number;
+    /**
+     * Test seam. When given, the awaitable `fetch`-based reader is used so a case
+     * can inject a hanging or failing implementation; production takes the
+     * detached path, whose whole purpose is not being awaitable.
+     */
+    fetchImpl?: typeof fetch;
+}): void;

package/dist/platform/footer.js

@@ -0,0 +1,101 @@
+/**
+ * The unbidden notice's call site, and the `unref`'d refresh behind it.
+ *
+ * DISCOVERY RIDES ON CREATOR-INITIATED COMMANDS ONLY. There is no timer, no
+ * daemon, no background poll, and no scheduled check anywhere in this feature —
+ * a "just check daily" implementation is the most likely way to break that, and
+ * it would be a transmission the creator did not initiate. What is time-bounded
+ * is how often we ASK; whether we SPEAK is governed by the fact changing.
+ *
+ * The line printed always comes from the PREVIOUS run's cache and the fetch is
+ * never awaited, so no verb pays for this. The consequence is accepted: a fresh
+ * install is quiet on its first run, and a creator who just installed is current
+ * by definition.
+ *
+ * OFF-SWITCH SITE 2 is `behindFooterLines`, and the gate is BEFORE
+ * `loadReleaseCache()` rather than inside it. A gate placed after the load still
+ * reads the file, and the requirement is that off means not read.
+ */
+import { alreadyAnnounced, behindFor } from "./behind.js";
+import { renderBehindNotice } from "./notice.js";
+import { FETCH_TIMEOUT_MS } from "../dx/updateCheck.js";
+import { isReleaseFresh, loadReleaseCache, saveReleaseCache, } from "./releaseCache.js";
+import { fetchRelease, fetchReleaseDetached } from "./releaseFetch.js";
+import { platformCheckEnabled } from "./offSwitch.js";
+/**
+ * The notice's lines, and the announcement recorded when it fires.
+ *
+ * Firing WRITES `announcedRelease`, which is what closes the nag by mechanism
+ * rather than by tone: the second run on the same release finds them equal and
+ * the renderer is never called. The silence after the first announcement is
+ * byte-identical to the silence of a caller with nothing to say, so the line
+ * cannot degrade into a quieter nag.
+ */
+export function behindFooterLines(deps) {
+    // OFF-SWITCH SITE 2 — before the loader is invoked at all.
+    if (!platformCheckEnabled())
+        return [];
+    const load = deps.loadCache ?? loadReleaseCache;
+    const cached = load();
+    if (cached === undefined)
+        return [];
+    const notice = behindFor(deps.installed, cached.release);
+    if (notice === undefined)
+        return [];
+    if (alreadyAnnounced(cached.announcedRelease, notice.release))
+        return [];
+    const lines = renderBehindNotice(notice);
+    if (lines.length === 0)
+        return [];
+    const save = deps.saveCache ?? saveReleaseCache;
+    save({ ...cached, announcedRelease: notice.release });
+    return lines;
+}
+/** Whether the cache is due a refresh. Separate so the caller can gate first. */
+export function needsRefresh(cache, now) {
+    return !isReleaseFresh(cache, now);
+}
+/**
+ * Refresh the cached release without holding the process open.
+ *
+ * `unref` is the load-bearing call, and it is the reason `preview`'s
+ * time-to-URL does not move: without it a 2s request keeps the event loop alive
+ * after the verb is done, so every command appears to hang — and the delay would
+ * land on `preview`, where someone is waiting to open a URL on a phone.
+ *
+ * OFF-SWITCH SITE 1 is `fetchRelease` itself, plus the gate here so no timer is
+ * even created.
+ */
+export function refreshReleaseCache(opts) {
+    if (!platformCheckEnabled())
+        return;
+    const previous = loadReleaseCache();
+    const store = (result) => {
+        saveReleaseCache({
+            release: result.release,
+            at: opts.now(),
+            // PRESERVED across a refresh. Dropping it would re-announce a release
+            // this machine has already spoken about, which is the nag the stored
+            // value exists to prevent.
+            announcedRelease: previous?.announcedRelease,
+            etag: result.etag,
+        });
+    };
+    if (opts.fetchImpl !== undefined) {
+        const timer = setTimeout(() => { }, FETCH_TIMEOUT_MS + 500);
+        timer.unref?.();
+        void fetchRelease({
+            apiUrl: opts.apiUrl,
+            etag: previous?.etag,
+            fetchImpl: opts.fetchImpl,
+        })
+            .then((result) => {
+            if (result !== undefined)
+                store(result);
+        })
+            .catch(() => { })
+            .finally(() => clearTimeout(timer));
+        return;
+    }
+    fetchReleaseDetached({ apiUrl: opts.apiUrl, etag: previous?.etag }, store);
+}