@vincentt-xr/cli 0.11.0 → 0.12.0

package/dist/cli/index.js

@@ -45,6 +45,8 @@ import { DX_UNATTENDED_SUNSET, loadEnablement } from "../dx/enablement.js";
 import { journalEnabled, journalPath, readJournal } from "../dx/journal.js";
 import { postReport } from "../dx/send.js";
 import { nudgeFor } from "../dx/nudge.js";
+import { FETCH_TIMEOUT_MS, isFresh, updateNotice } from "../dx/updateCheck.js";
+import { fetchLatest, loadCache, saveCache } from "../dx/updateCheckIo.js";
 import { verbOf } from "../dx/skeleton.js";
 import { createSourceFlagRefusal, fromFlagConflict, isHelpInvocation, isVersionInvocation, positionalArgs, refusedFlag, } from "./args.js";
 import { parseSourceRef } from "../lib/sourceRef.js";
@@ -1173,6 +1175,41 @@ function journal(exitCode, error) {
     catch {
         // A hint that can break a publish is not worth having.
     }
+    // The update notice prints from the LAST run's cached answer and never waits
+    // on the registry, so no verb pays for this. The consequence is that a fresh
+    // install stays quiet on its first run and speaks on the next one — which is
+    // the right trade: a creator who just installed is by definition current, and
+    // a notice is worth nothing if it costs a second on every publish.
+    try {
+        const cached = loadCache();
+        for (const l of updateNotice(cliVersion(), cached?.latest))
+            console.error(l);
+        if (!isFresh(cached, Date.now()))
+            refreshUpdateCache();
+    }
+    catch {
+        // Same rule as the nudge: never break a run over a footnote.
+    }
+}
+/**
+ * Refresh the cached `latest` without holding the process open.
+ *
+ * `unref` is the load-bearing call. Without it a 2s registry request keeps the
+ * event loop alive after the verb is done, so every command appears to hang for
+ * up to two seconds — a CLI that feels slower in exchange for an occasional
+ * notice is a bad trade, and the delay would land on `preview`, where someone is
+ * waiting to open a URL on a phone.
+ */
+function refreshUpdateCache() {
+    const timer = setTimeout(() => { }, FETCH_TIMEOUT_MS + 500);
+    timer.unref?.();
+    void fetchLatest()
+        .then((latest) => {
+        if (latest !== undefined)
+            saveCache({ latest, at: Date.now() });
+    })
+        .catch(() => { })
+        .finally(() => clearTimeout(timer));
 }
 main()
     .then(() => {

package/dist/dx/updateCheck.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The update notice: a one-line fact, printed after a run, saying a newer CLI
+ * exists.
+ *
+ * The CLI is installed globally (`npm install -g @vincentt-xr/cli`), so there is
+ * one copy per machine and nothing about a project ever updates it. The install
+ * instruction in the scaffolded contract fires only when the binary is MISSING,
+ * which makes it a first-install path and never an upgrade path: a creator who
+ * installed in July keeps running July's CLI indefinitely, and the failures that
+ * follow a wire change read as platform bugs.
+ *
+ * STATES A FACT, NEVER AN INSTRUCTION — the same rule as the dx nudge, for the
+ * same reason. This line lands in an agent's transcript, where the CLI's stdout
+ * is the agent's input, and `npm install -g ...@latest` is a directive an
+ * autonomous caller will simply obey. An agent that updates the binary mid-run
+ * has swapped the tool underneath itself and may need a sudo the human never
+ * approved. Naming that a newer version exists is information the caller can act
+ * on; telling it to install is a decision that is not the CLI's to make.
+ */
+/** How long a registry answer is trusted. One notice a day, not one per run. */
+export declare const CHECK_TTL_MS: number;
+/** Registry request budget. A slow npm must never slow a verb down. */
+export declare const FETCH_TIMEOUT_MS = 2000;
+export interface UpdateCache {
+    /** The `latest` dist-tag as last seen. */
+    latest: string;
+    /** When it was fetched (epoch ms). */
+    at: number;
+}
+/**
+ * True when `latest` is strictly newer than `current`.
+ *
+ * Prerelease suffixes are deliberately ignored beyond the numeric core: the
+ * comparison only decides whether to print one line, and a creator running
+ * `0.11.0-rc.1` against a `0.11.0` latest is not someone to nag.
+ */
+export declare function isNewer(current: string, latest: string): boolean;
+/**
+ * Decide whether a cached answer is still usable. A cache written in the future
+ * (a clock that moved) is treated as stale rather than trusted forever.
+ */
+export declare function isFresh(cache: UpdateCache | undefined, now: number): boolean;
+/**
+ * Read a cache object defensively. STRICT about types for the same reason the
+ * enablement reader is: a hand-edited or half-written file must degrade to "no
+ * cache" rather than to a bogus comparison.
+ */
+export declare function readCache(raw: unknown): UpdateCache | undefined;
+/**
+ * The notice. Empty when there is nothing to say.
+ *
+ * Pure, so the transcript is testable without a network, a home directory, or a
+ * published package.
+ */
+export declare function updateNotice(current: string, latest: string | undefined): string[];

package/dist/dx/updateCheck.js

@@ -0,0 +1,98 @@
+/**
+ * The update notice: a one-line fact, printed after a run, saying a newer CLI
+ * exists.
+ *
+ * The CLI is installed globally (`npm install -g @vincentt-xr/cli`), so there is
+ * one copy per machine and nothing about a project ever updates it. The install
+ * instruction in the scaffolded contract fires only when the binary is MISSING,
+ * which makes it a first-install path and never an upgrade path: a creator who
+ * installed in July keeps running July's CLI indefinitely, and the failures that
+ * follow a wire change read as platform bugs.
+ *
+ * STATES A FACT, NEVER AN INSTRUCTION — the same rule as the dx nudge, for the
+ * same reason. This line lands in an agent's transcript, where the CLI's stdout
+ * is the agent's input, and `npm install -g ...@latest` is a directive an
+ * autonomous caller will simply obey. An agent that updates the binary mid-run
+ * has swapped the tool underneath itself and may need a sudo the human never
+ * approved. Naming that a newer version exists is information the caller can act
+ * on; telling it to install is a decision that is not the CLI's to make.
+ */
+/** How long a registry answer is trusted. One notice a day, not one per run. */
+export const CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+/** Registry request budget. A slow npm must never slow a verb down. */
+export const FETCH_TIMEOUT_MS = 2000;
+/**
+ * Parse a semver-ish version into comparable parts. Returns undefined for
+ * anything unrecognized, which callers treat as "cannot compare" rather than as
+ * zero — a version that failed to parse must not read as older than everything.
+ */
+function parts(v) {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+    if (m === null)
+        return undefined;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/**
+ * True when `latest` is strictly newer than `current`.
+ *
+ * Prerelease suffixes are deliberately ignored beyond the numeric core: the
+ * comparison only decides whether to print one line, and a creator running
+ * `0.11.0-rc.1` against a `0.11.0` latest is not someone to nag.
+ */
+export function isNewer(current, latest) {
+    const c = parts(current);
+    const l = parts(latest);
+    if (c === undefined || l === undefined)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (l[i] > c[i])
+            return true;
+        if (l[i] < c[i])
+            return false;
+    }
+    return false;
+}
+/**
+ * Decide whether a cached answer is still usable. A cache written in the future
+ * (a clock that moved) is treated as stale rather than trusted forever.
+ */
+export function isFresh(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;
+}
+/**
+ * Read a cache object defensively. STRICT about types for the same reason the
+ * enablement reader is: a hand-edited or half-written file must degrade to "no
+ * cache" rather than to a bogus comparison.
+ */
+export function readCache(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const { latest, at } = raw;
+    if (typeof latest !== "string" || latest === "")
+        return undefined;
+    if (typeof at !== "number" || !Number.isFinite(at))
+        return undefined;
+    return { latest, at };
+}
+/**
+ * The notice. Empty when there is nothing to say.
+ *
+ * Pure, so the transcript is testable without a network, a home directory, or a
+ * published package.
+ */
+export function updateNotice(current, latest) {
+    if (latest === undefined)
+        return [];
+    if (!isNewer(current, latest))
+        return [];
+    return [
+        "",
+        `  ! A newer vincentt is available (${current} → ${latest}).`,
+        "    Installed globally as @vincentt-xr/cli.",
+    ];
+}

package/dist/dx/updateCheckIo.d.ts

@@ -0,0 +1,18 @@
+import { type UpdateCache } from "./updateCheck.js";
+export declare function cachePath(): string;
+/** Read the cached answer. Any fault reads as "no cache". */
+export declare function loadCache(): UpdateCache | undefined;
+/**
+ * Write the cached answer. Best-effort and non-atomic, unlike the machine
+ * config: this file holds no secret and no state a creator would miss, so a
+ * torn write costs one extra registry call rather than a lost token.
+ */
+export declare function saveCache(cache: UpdateCache): void;
+/**
+ * Ask the registry for the `latest` dist-tag. Undefined on any fault.
+ *
+ * The Accept header requests npm's abbreviated document, which is a fraction of
+ * the full package metadata — the full one for a package with many versions is
+ * megabytes, and this runs on someone's laptop after every verb.
+ */
+export declare function fetchLatest(signal?: AbortSignal): Promise<string | undefined>;

package/dist/dx/updateCheckIo.js

@@ -0,0 +1,78 @@
+/**
+ * The I/O half of the update notice: the cache file and the registry fetch.
+ *
+ * Split from the decision logic in updateCheck.ts so the transcript and the
+ * comparison stay testable without a network or a home directory.
+ *
+ * Every operation here is best-effort. A creator's `publish` must not fail, slow
+ * down, or print a stack trace because the npm registry was unreachable or
+ * ~/.vincentt was read-only — the worst outcome of this whole feature going dark
+ * is that nobody is told about an update, which is exactly where they were
+ * before it existed.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { FETCH_TIMEOUT_MS, readCache } from "./updateCheck.js";
+const CACHE_FILE = "update-check.json";
+/** The npm registry's package document, filtered to the dist-tags it serves. */
+const REGISTRY_URL = "https://registry.npmjs.org/@vincentt-xr%2Fcli";
+export function cachePath() {
+    return path.join(os.homedir(), ".vincentt", CACHE_FILE);
+}
+/** Read the cached answer. Any fault reads as "no cache". */
+export function loadCache() {
+    try {
+        return readCache(JSON.parse(fs.readFileSync(cachePath(), "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Write the cached answer. Best-effort and non-atomic, unlike the machine
+ * config: this file holds no secret and no state a creator would miss, so a
+ * torn write costs one extra registry call rather than a lost token.
+ */
+export function saveCache(cache) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath()), { recursive: true });
+        fs.writeFileSync(cachePath(), JSON.stringify(cache) + "\n", "utf8");
+    }
+    catch {
+        // A cache that cannot be written just means the next run asks again.
+    }
+}
+/**
+ * Ask the registry for the `latest` dist-tag. Undefined on any fault.
+ *
+ * The Accept header requests npm's abbreviated document, which is a fraction of
+ * the full package metadata — the full one for a package with many versions is
+ * megabytes, and this runs on someone's laptop after every verb.
+ */
+export async function fetchLatest(signal) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    const onAbort = () => controller.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        const res = await fetch(REGISTRY_URL, {
+            signal: controller.signal,
+            headers: {
+                Accept: "application/vnd.npm.install-v1+json",
+            },
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        const latest = body["dist-tags"]?.latest;
+        return typeof latest === "string" && latest !== "" ? latest : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",