@vincentt-xr/cli 0.15.1 → 0.16.0

package/dist/dx/skeleton.js

@@ -20,9 +20,24 @@ const ELIDED = "<v>";
  * on-disk journal and any report built from it. Lowercase kebab-case is exactly
  * what slugs and project names are made of, so no character-class check catches
  * this — only a list of the verbs that actually exist.
+ *
+ * THIS SET MUST COVER EVERY DISPATCHED VERB, and a missing one is not a leak but
+ * a mis-bucketing: `journal.ts` records `verbOf(argv)`, which answers `<verb>`
+ * for anything absent here, so every invocation of a missing verb clusters under
+ * the placeholder and its friction is invisible. That also broke `lastContext()`
+ * — `report.ts` skips entries whose verb is `report`, which never matched while
+ * `report` was absent, so the context line a creator consents to could be the
+ * skeleton of their own `report` invocation rather than the command before it.
+ *
+ * Adding a verb CANNOT widen what a positional carries: `skeleton()` consults
+ * this set only when `out.length === 0`, so it reaches the FIRST token only, and
+ * every later positional is elided regardless. The historical leak lived in the
+ * first token.
  */
 const KNOWN_VERBS = new Set([
+    "assets",
     "create",
+    "domain",
     "dx",
     "feedback",
     "init",
@@ -31,9 +46,12 @@ const KNOWN_VERBS = new Set([
     "logout",
     "logs",
     "network",
+    "outdated",
     "preview",
+    "projects",
     "publish",
     "relay",
+    "report",
     "trace",
     "unlink",
     "version",
@@ -56,6 +74,7 @@ const KNOWN_FLAGS = new Set([
     "--json",
     "--limit",
     "--name",
+    "--no-context",
     "--no-install",
     "--no-qr",
     "--note",

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/exitCodes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Every exit code the CLI returns. B-F12-1: APPEND-ONLY — a code may be added,
+ * an existing code's meaning never changes. Removing or repurposing one breaks
+ * grounding that already shipped into a creator's repository and is never read
+ * back, so the platform cannot warn about it or repair it.
+ */
+export declare const EXIT: {
+    /** The command did what it was asked. */
+    readonly OK: 0;
+    /** The command failed and nothing lasting was produced. */
+    readonly FAILED: 1;
+    /**
+     * The project source was written by this invocation, but no address was
+     * reserved: no account on this machine, and no browser to get one. The
+     * creator holds a working local project; only registration is deferred.
+     */
+    readonly DELIVERED_NOT_REGISTERED: 3;
+    /** A platform call needed an account and the command did not answer for it. */
+    readonly NOT_AUTHENTICATED: 4;
+    /** A bounded wait elapsed with nothing handed over. */
+    readonly WINDOW_ELAPSED: 64;
+    /** The channel ended before anything was handed over. */
+    readonly CHANNEL_ENDED: 65;
+};

package/dist/lib/exitCodes.js

@@ -0,0 +1,28 @@
+/**
+ * Every exit code the CLI returns. B-F12-1: APPEND-ONLY — a code may be added,
+ * an existing code's meaning never changes. Removing or repurposing one breaks
+ * grounding that already shipped into a creator's repository and is never read
+ * back, so the platform cannot warn about it or repair it.
+ */
+export const EXIT = {
+    /** The command did what it was asked. */
+    OK: 0,
+    /** The command failed and nothing lasting was produced. */
+    FAILED: 1,
+    /**
+     * The project source was written by this invocation, but no address was
+     * reserved: no account on this machine, and no browser to get one. The
+     * creator holds a working local project; only registration is deferred.
+     */
+    DELIVERED_NOT_REGISTERED: 3,
+    /** A platform call needed an account and the command did not answer for it. */
+    NOT_AUTHENTICATED: 4,
+    /** A bounded wait elapsed with nothing handed over. */
+    WINDOW_ELAPSED: 64,
+    /** The channel ended before anything was handed over. */
+    CHANNEL_ENDED: 65,
+};
+// 2 is deliberately unallocated. Shells conventionally use 2 for misuse of a
+// builtin, and a CLI that returns it invites a caller to misread a shell error
+// as ours. The gap is recorded here so a later change does not fill it by
+// looking for the lowest free number.

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/initFrom.js

@@ -10,6 +10,7 @@
 // be wrong.
 import path from "node:path";
 import { SlugTakenError } from "./backend.js";
+import { EXIT } from "./exitCodes.js";
 import { slugify } from "./slug.js";
 import { formatSourceRef } from "./sourceRef.js";
 /** How many times the address prompt re-asks before falling back to the printed block. */
@@ -70,7 +71,9 @@ export async function registerAfterScaffold(deps, opts = {}) {
     if (!token) {
         if (!deps.ask) {
             deps.print("");
-            deps.print("✗ Not signed in, and signing in needs a browser.");
+            deps.print(scaffolded
+                ? "→ Not signed in, so no address is reserved yet."
+                : "✗ Not signed in, and signing in needs a browser.");
             deps.print("");
             if (scaffolded)
                 reassure(deps.print, deps.dirLabel);
@@ -81,9 +84,16 @@ export async function registerAfterScaffold(deps, opts = {}) {
             deps.print("");
             deps.print("  Then finish:");
             resume(deps.print, deps.dirLabel, resumeCommand, needsCd);
+            if (scaffolded) {
+                deps.print("");
+                // B-F2-9(a): the open route must be named in something the creator's
+                // agent reads. On a non-TTY this output IS that artifact — the TTY
+                // branch's login prompt, which carries the same line, is unreachable here.
+                deps.print("  Or don't — the local dev loop needs no account.");
+            }
             deps.print("");
             deps.print(closing);
-            return 1;
+            return scaffolded ? EXIT.DELIVERED_NOT_REGISTERED : EXIT.FAILED;
         }
         deps.print("");
         deps.print("→ Now registering the project so it gets an address.");

package/dist/lib/lifecycle.d.ts

@@ -36,7 +36,11 @@ export interface CreateOptions {
 export interface CreateResult {
     /** The full transcript, exactly as the CLI prints it. */
     message: string;
-    /** Non-zero when nothing was created (already linked, address taken, no org). */
+    /**
+     * Non-zero when the address was not reserved. Code 1 means nothing was created
+     * (already linked, address taken, no org); code 3 means the project source was
+     * written but registration was deferred for want of an account.
+     */
     exitCode: number;
 }
 /**

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

@@ -8,6 +8,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { BackendError, SlugTakenError, createProject, getProject, } from "./backend.js";
 import { classifyTarget } from "./classifyTarget.js";
+import { EXIT } from "./exitCodes.js";
 import { registerAfterScaffold } from "./initFrom.js";
 import { slugify } from "./slug.js";
 import { detectPackageManager, installDependencies, scaffoldFromTemplate, } from "../scaffold/index.js";
@@ -85,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)
@@ -92,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
@@ -156,6 +162,7 @@ export async function createCommand(deps, opts = {}) {
             dir: opts.dir,
             name,
             slug,
+            templateVersion,
             rethrowSlugTaken: true,
         }),
     }, 
@@ -169,7 +176,10 @@ export async function createCommand(deps, opts = {}) {
             name: opts.name ?? path.basename(target),
             slug: opts.slug ?? slugify(opts.name ?? path.basename(target)),
         });
-    if (code !== 0)
+    // The gate is DELIVERY, not zero. A run that wrote the source and deferred
+    // only the address still delivered a project, so it still prints how to run
+    // it. The endings that stay exit 1 delivered nothing and correctly skip this.
+    if (code !== 0 && code !== EXIT.DELIVERED_NOT_REGISTERED)
         return code;
     if (scaffolded) {
         // This reader has never run the dev server, so the block that fits is the one
@@ -187,7 +197,10 @@ export async function createCommand(deps, opts = {}) {
         for (const line of alignedSteps(steps))
             deps.print(line);
     }
-    return 0;
+    // Printing the steps must not launder the ending: a delivered-not-registered
+    // run still reports 3, so a caller never reads success for an unregistered
+    // project.
+    return code;
 }
 /** Two columns, aligned on the widest command, so the block reads as a table. */
 function alignedSteps(steps) {
@@ -273,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
@@ -300,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
@@ -348,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;