@vincentt-xr/cli 0.15.1 → 0.16.0

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);
+}

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`;
+}