@vincentt-xr/cli 0.11.0 → 0.12.1

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/dist/lib/backend.js

@@ -6,6 +6,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { clientHeaders } from "../shared/clientHeader.js";
 import { authFailureMessage } from "../shared/authError.js";
 const execFileAsync = promisify(execFile);
 export class BackendError extends Error {
@@ -19,7 +20,11 @@ export class BackendError extends Error {
 async function authFetch(cfg, pathname, init = {}) {
     return fetch(`${cfg.apiUrl}${pathname}`, {
         ...init,
-        headers: { ...(init.headers ?? {}), authorization: `Bearer ${cfg.pat}` },
+        headers: {
+            ...(init.headers ?? {}),
+            ...clientHeaders(),
+            authorization: `Bearer ${cfg.pat}`,
+        },
     });
 }
 async function safeText(res) {

package/dist/library/client.js

@@ -12,6 +12,7 @@
 // CLI-supplied URL reaches a fetch. That is a security control, not a style choice
 // (D-add-prints-urls degraded the no-invented-URLs rule from prevention to
 // detection, and this is the one arm that stayed prevention).
+import { clientHeaders } from "../shared/clientHeader.js";
 import { parseBatchResponse, parseFetchResponse, parseSearchResponse, } from "./wire.js";
 /** The API said no, with a code we can act on. */
 export class LibraryError extends Error {
@@ -61,7 +62,7 @@ async function readJson(res) {
  */
 export function httpLibraryClient(cfg) {
     const base = cfg.apiUrl.replace(/\/$/, "");
-    const auth = { authorization: `Bearer ${cfg.pat}` };
+    const auth = { ...clientHeaders(), authorization: `Bearer ${cfg.pat}` };
     const call = async (pathname, init) => {
         try {
             return await fetch(`${base}${pathname}`, {

package/dist/login/authBackend.js

@@ -7,6 +7,7 @@
 //   POST /access-tokens/exchange {code, code_verifier} → {token}   (raw PAT, once, in body)
 //   GET  /me            Bearer <PAT>                    → identity + orgs (confirm)
 import { authFailureMessage } from "../shared/authError.js";
+import { clientHeaders } from "../shared/clientHeader.js";
 class AuthError extends Error {
     status;
     constructor(message, status) {
@@ -30,7 +31,7 @@ export function httpAuthBackend(apiBase) {
         async exchange(code, codeVerifier) {
             const res = await fetch(`${base}/access-tokens/exchange`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: { ...clientHeaders(), "content-type": "application/json" },
                 body: JSON.stringify({ code, code_verifier: codeVerifier }),
             });
             if (!res.ok) {
@@ -43,7 +44,7 @@ export function httpAuthBackend(apiBase) {
         },
         async me(pat) {
             const res = await fetch(`${base}/me`, {
-                headers: { authorization: `Bearer ${pat}` },
+                headers: { ...clientHeaders(), authorization: `Bearer ${pat}` },
             });
             if (!res.ok) {
                 throw new AuthError(authFailureMessage("Identity check failed", res.status, await safeText(res)), res.status);

package/dist/publish/api.js

@@ -5,6 +5,7 @@
 //
 // The bytes do NOT transit the API. Open returns one presigned PUT per file,
 // each signed for one exact key; the CLI PUTs direct to S3 and then commits.
+import { clientHeaders } from "../shared/clientHeader.js";
 export class PublishApiError extends Error {
     status;
     code;
@@ -31,7 +32,7 @@ async function readError(res) {
     return new PublishApiError(res.status, body.code ?? `http_${res.status}`, body.message ?? `request failed (${res.status})`, body.detail ?? {}, retryAfter ? Number(retryAfter) : undefined);
 }
 function authHeaders(cfg) {
-    return { authorization: `Bearer ${cfg.pat}` };
+    return { ...clientHeaders(), authorization: `Bearer ${cfg.pat}` };
 }
 /** The ONE call before the checklist. liveVersion + livePublishedAt ride it, by design. */
 export async function readProject(cfg, projectId, fetchImpl = fetch) {

package/dist/shared/clientHeader.d.ts

@@ -0,0 +1,19 @@
+/** The header name. Canonical casing; HTTP header matching is case-insensitive. */
+export declare const CLIENT_HEADER = "X-Vincentt-Client";
+export declare function clientVersion(): string;
+/**
+ * The header value: `cli/<version>`.
+ *
+ * The `cli/` prefix is what keeps the field readable when a second first-party
+ * client (the harness, a future console agent) starts reporting on the same
+ * header — a bare version would be ambiguous the moment it is not alone.
+ */
+export declare function clientHeaderValue(): string;
+/**
+ * The header, as a spreadable object. Callers merge this into their existing
+ * headers rather than assembling the name themselves, so the format stays in one
+ * place.
+ */
+export declare function clientHeaders(): Record<string, string>;
+/** Reset the memo. Test seam only. */
+export declare function resetClientVersionCache(): void;

package/dist/shared/clientHeader.js

@@ -0,0 +1,72 @@
+/**
+ * The client-identity header every API request carries.
+ *
+ * The platform could not previously tell which CLI was calling it. That makes
+ * two ordinary questions unanswerable: how far behind the installed base
+ * actually is, and whether a wire change is safe to make yet. Both are questions
+ * about a population, and no amount of reading one creator's terminal answers
+ * them.
+ *
+ * It is also the seam a minimum-version refusal would need. That is deliberately
+ * NOT built here — a floor that strands someone mid-publish is worth having only
+ * once a contract has actually broken, and it needs this measurement first to
+ * know where to sit.
+ *
+ * `X-Vincentt-Client` is the platform's namespace, which the EDGE strips from
+ * viewer traffic (see isViewerRoutingHeader in the api repo): a device must not
+ * be able to forge what a creator's tooling reports about itself. This is the
+ * other side of that rule — the CLI is a first-party client talking to the API
+ * directly, not a viewer, so it is the legitimate origin of the value rather
+ * than something to be filtered out.
+ */
+import { createRequire } from "node:module";
+/** The header name. Canonical casing; HTTP header matching is case-insensitive. */
+export const CLIENT_HEADER = "X-Vincentt-Client";
+/**
+ * The running package's version, read from the manifest rather than baked in by
+ * the build — a hardcoded string is one forgotten edit away from a CLI that
+ * misreports itself, which is worse than reporting nothing. `src/shared/` and
+ * the emitted `dist/shared/` sit at the same depth, so one relative path serves
+ * both.
+ */
+function readVersion() {
+    try {
+        const manifest = createRequire(import.meta.url)("../../package.json");
+        return manifest.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Cached: the manifest cannot change within a process, and this is read on every
+ * outbound request.
+ */
+let cached;
+export function clientVersion() {
+    if (cached === undefined)
+        cached = readVersion();
+    return cached;
+}
+/**
+ * The header value: `cli/<version>`.
+ *
+ * The `cli/` prefix is what keeps the field readable when a second first-party
+ * client (the harness, a future console agent) starts reporting on the same
+ * header — a bare version would be ambiguous the moment it is not alone.
+ */
+export function clientHeaderValue() {
+    return `cli/${clientVersion()}`;
+}
+/**
+ * The header, as a spreadable object. Callers merge this into their existing
+ * headers rather than assembling the name themselves, so the format stays in one
+ * place.
+ */
+export function clientHeaders() {
+    return { [CLIENT_HEADER]: clientHeaderValue() };
+}
+/** Reset the memo. Test seam only. */
+export function resetClientVersionCache() {
+    cached = undefined;
+}

package/package.json

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