@vincentt-xr/cli 0.10.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";
@@ -540,7 +542,7 @@ async function preview() {
         orgName: await activeOrgName(),
         targetUrl: `http://localhost:${running.appPort}`,
         url: running.url,
-        consoleUrl: await projectConsoleUrl(cwd),
+        consoleUrl: await projectConsoleUrl(cwd, running.sessionId),
         qr,
         expiresInHours: 12,
     })) {
@@ -657,14 +659,26 @@ async function projectDisplayName(cwd) {
  * `consoleVerbCommand` deep-links to. The console redirects it to the org-scoped
  * address, so the CLI does not need the org slug and cannot print a stale one — a
  * folder can outlive the org binding the machine config happens to hold.
+ *
+ * `sessionId` deep-links PAST the project's default tab to the running preview
+ * itself (`?tab=preview&session=<id>`), which is the surface the creator is being
+ * handed this link to watch. Omitted when there is no session — the bare project
+ * page is right for `link`/`create`, and a session parameter naming nothing would
+ * land on an empty workspace.
  */
-async function projectConsoleUrl(cwd) {
+async function projectConsoleUrl(cwd, sessionId) {
     const located = await locateProjectBinding(cwd);
     if (!located)
         return undefined;
     const cfg = await loadMachineConfig();
     const base = (cfg.consoleUrl ?? DEFAULT_CONSOLE_URL).replace(/\/$/, "");
-    return `${base}/projects/${located.binding.projectId}`;
+    const url = `${base}/projects/${located.binding.projectId}`;
+    if (!sessionId)
+        return url;
+    // encodeURIComponent on BOTH: the ids are server-minted and hex today, and a
+    // future id shape carrying a reserved character must not become a second
+    // parameter.
+    return `${url}?tab=preview&session=${encodeURIComponent(sessionId)}`;
 }
 /**
  * Map a mint failure to its screen. Each cause has a DISTINCT first line so the
@@ -1161,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/preview/copy.d.ts

@@ -99,9 +99,18 @@ export declare function stopped(ranMs: number, totalConnections: number): string
  *
  * The claim is exactly what the wire supports: `stopped` is produced by one
  * route, authorized by the compound key {_id, userId}, so the actor is ALWAYS
- * the same account as the reader. Never a teammate, never an admin. It does not
- * say WHICH window, because another terminal, another machine and a future
- * console control are all the same 410.
+ * the same account as the reader. Never a teammate, never an admin.
+ *
+ * IT NAMES NO SURFACE, and that is the whole design of this screen. `endReason`
+ * carries ONE value for every actor on that route — this CLI's own stop, another
+ * terminal, another machine, the console's Stop control, and any surface added
+ * later. The API does not learn which one called and must not: deriving it would
+ * mean guessing a surface from a credential kind (a PAT-driven script is not "a
+ * terminal") and reporting the guess to the creator as fact. That is the
+ * over-claim class that produced the abandoned→hard_max defect.
+ *
+ * So the headline states only the event, and the second line describes the actor
+ * exactly as far as the compound key supports: the same account, not this window.
  *
  * `✓`, not `✗`: someone with the authority to stop it stopped it.
  */

package/dist/preview/copy.js

@@ -205,16 +205,25 @@ export function stopped(ranMs, totalConnections) {
  *
  * The claim is exactly what the wire supports: `stopped` is produced by one
  * route, authorized by the compound key {_id, userId}, so the actor is ALWAYS
- * the same account as the reader. Never a teammate, never an admin. It does not
- * say WHICH window, because another terminal, another machine and a future
- * console control are all the same 410.
+ * the same account as the reader. Never a teammate, never an admin.
+ *
+ * IT NAMES NO SURFACE, and that is the whole design of this screen. `endReason`
+ * carries ONE value for every actor on that route — this CLI's own stop, another
+ * terminal, another machine, the console's Stop control, and any surface added
+ * later. The API does not learn which one called and must not: deriving it would
+ * mean guessing a surface from a credential kind (a PAT-driven script is not "a
+ * terminal") and reporting the guess to the creator as fact. That is the
+ * over-claim class that produced the abandoned→hard_max defect.
+ *
+ * So the headline states only the event, and the second line describes the actor
+ * exactly as far as the compound key supports: the same account, not this window.
  *
  * `✓`, not `✗`: someone with the authority to stop it stopped it.
  */
 export function stoppedElsewhere() {
     return [
         "",
-        "✓ Preview stopped from another terminal. The link no longer works.",
+        "✓ Preview stopped. The link no longer works.",
         "",
         "  It was stopped on your account, not by this window. Nothing is wrong here.",
         "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.10.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",