@bitmagic/cli 0.1.12 → 0.1.13

package/README.md

@@ -132,6 +132,17 @@ build` stops with a message naming `bitmagic upgrade`, which vendors the file wi
 your game code. Run the printed install command afterwards if `upgrade` reports missing
 dependencies too.
 
+## Staying current
+
+Two nudges, both advisory — nothing is ever blocked because something is out of date.
+
+- **The CLI itself.** Commands print a line when a newer `@bitmagic/cli` is on npm. The check reads
+  a cache written by an earlier run, so it costs no time; the cache refreshes in the background at
+  most once a day. An unreachable registry, a prerelease build, or a first-ever run all stay quiet.
+- **The vendored engine.** `bitmagic dev` and `bitmagic publish` say when a newer engine exists and
+  suggest `bitmagic upgrade`. Publishing is never refused for an old engine — the prompt belongs
+  where rebuilding is cheap, not at the moment you ship.
+
 ## Development
 
 ```bash

package/dist/bin.js

@@ -1,13 +1,42 @@
 #!/usr/bin/env node
 import { runMain } from 'citty';
+import { createRequire } from 'module';
 import { main } from './cli.js';
 import { CliError } from './errors.js';
+import { pendingUpdateNotice, refreshUpdateCacheInBackground } from './update/check.js';
+/**
+ * This file, not cli.ts, because cli.ts must stay free of side effects — cli.test.ts imports it
+ * for `subCommands` and would otherwise trigger a version check against the test runner.
+ */
+function currentCliVersion() {
+    try {
+        // dist/bin.js -> ../package.json is this package's own manifest.
+        const pkg = createRequire(import.meta.url)('../package.json');
+        return typeof pkg.version === 'string' ? pkg.version : '';
+    }
+    catch {
+        return '';
+    }
+}
+// Printed BEFORE the command runs, and read purely from a cache written by a previous run — so it
+// costs no network and no measurable time here. A command that exits early (or via process.exit
+// on a CliError) has still shown it, which printing afterwards could not guarantee.
+const version = currentCliVersion();
+const notice = pendingUpdateNotice(version);
+if (notice !== null)
+    console.error(notice);
+// Deliberately NOT awaited: this is for the next invocation, not this one. Bounded by its own
+// short timeout so a sulking registry cannot hold a finished command open.
+void refreshUpdateCacheInBackground();
 // The actual executable entrypoint — this is what package.json's `bin` points at. It is
 // deliberately the only place that calls `runMain`, and it does so unconditionally: unlike the
 // old path-comparison guard in cli.ts (which broke when invoked through a symlink, e.g. every
 // `npm i -g` install), there is no heuristic here to get wrong. Importing `./cli.js` never runs
 // the CLI by itself, so this file is the sole source of the "actually run it" side effect.
-runMain(main).catch((error) => {
+// The version is attached HERE rather than in cli.ts's `meta`, because that module is imported by
+// cli.test.ts for `subCommands` and is deliberately free of side effects — reading package.json at
+// its module scope would break that. citty renders `meta.version` for `--version` and in usage.
+runMain({ ...main, meta: { ...main.meta, version } }).catch((error) => {
     if (error instanceof CliError) {
         console.error(error.message);
         process.exit(error.exitCode);

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,wFAAwF;AACxF,+FAA+F;AAC/F,8FAA8F;AAC9F,gGAAgG;AAChG,2FAA2F;AAC3F,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IACrC,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AAExF;;;GAGG;AACH,SAAS,iBAAiB;IACxB,IAAI,CAAC;QACH,iEAAiE;QACjE,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAA0B,CAAC;QACvF,OAAO,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,kGAAkG;AAClG,gGAAgG;AAChG,oFAAoF;AACpF,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;AACpC,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC5C,IAAI,MAAM,KAAK,IAAI;IAAE,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAE3C,8FAA8F;AAC9F,2EAA2E;AAC3E,KAAK,8BAA8B,EAAE,CAAC;AAEtC,wFAAwF;AACxF,+FAA+F;AAC/F,8FAA8F;AAC9F,gGAAgG;AAChG,2FAA2F;AAC3F,kGAAkG;AAClG,mGAAmG;AACnG,gGAAgG;AAChG,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,EAAE,GAAI,IAAI,CAAC,IAAgC,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC1G,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/project/engine-update.js

@@ -9,6 +9,7 @@
  * So the prompt lives where acting on it is cheap — during development, before there is anything
  * to lose by rebuilding.
  */
+import { isOlderDottedVersion } from './version-compare.js';
 /**
  * Compare two `3.<build>` engine versions.
  *
@@ -17,23 +18,7 @@
  * fires on every run is a nudge people learn to ignore.
  */
 export function isOlderEngine(projectVersion, currentVersion) {
-    const parse = (v) => {
-        const parts = v.trim().split('.');
-        if (parts.length === 0 || parts.some((p) => !/^\d+$/.test(p)))
-            return null;
-        return parts.map(Number);
-    };
-    const a = parse(projectVersion);
-    const b = parse(currentVersion);
-    if (a === null || b === null)
-        return null;
-    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
-        const left = a[i] ?? 0;
-        const right = b[i] ?? 0;
-        if (left !== right)
-            return left < right;
-    }
-    return false;
+    return isOlderDottedVersion(projectVersion, currentVersion);
 }
 /**
  * The line to print, or null to stay quiet.

package/dist/project/engine-update.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine-update.js","sourceRoot":"","sources":["../../src/project/engine-update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,cAAsB,EAAE,cAAsB;IAC1E,MAAM,KAAK,GAAG,CAAC,CAAS,EAAmB,EAAE;QAC3C,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3E,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC,CAAC;IACF,MAAM,CAAC,GAAG,KAAK,CAAC,cAAc,CAAC,CAAC;IAChC,MAAM,CAAC,GAAG,KAAK,CAAC,cAAc,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACvB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,IAAI,KAAK,KAAK;YAAE,OAAO,IAAI,GAAG,KAAK,CAAC;IAC1C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,cAAsB;AACtB,gGAAgG;AAChG,8EAA8E;AAC9E,cAAyC;IAEzC,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7E,IAAI,OAAO,cAAc,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACpD,IAAI,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACxE,OAAO,gCAAgC,cAAc,wBAAwB,cAAc,2CAA2C,CAAC;AACzI,CAAC"}
+{"version":3,"file":"engine-update.js","sourceRoot":"","sources":["../../src/project/engine-update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAK5D;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,cAAsB,EAAE,cAAsB;IAC1E,OAAO,oBAAoB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,cAAsB;AACtB,gGAAgG;AAChG,8EAA8E;AAC9E,cAAyC;IAEzC,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7E,IAAI,OAAO,cAAc,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACpD,IAAI,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACxE,OAAO,gCAAgC,cAAc,wBAAwB,cAAc,2CAA2C,CAAC;AACzI,CAAC"}

package/dist/project/version-compare.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Numeric comparison of dot-separated versions, shared by the engine nudge and the CLI-update
+ * nudge.
+ *
+ * Shared rather than copied because both compare the same shape for the same purpose, and two
+ * copies of a comparison is how `3.1009` ends up ranked below `3.980` in one place and not the
+ * other. Every part must be all digits — `0.1.12`, `3.1009` — which is what both version streams
+ * actually produce.
+ *
+ * Returns null when either side is unparseable (a prerelease tag, a locally-built `worktree`
+ * engine, a git describe string). Callers treat null as "say nothing": an unrecognised version is
+ * not evidence that anything is out of date, and a nudge that fires on every run is one people
+ * learn to ignore.
+ */
+export declare function isOlderDottedVersion(candidate: string, reference: string): boolean | null;

package/dist/project/version-compare.js

@@ -0,0 +1,37 @@
+/**
+ * Numeric comparison of dot-separated versions, shared by the engine nudge and the CLI-update
+ * nudge.
+ *
+ * Shared rather than copied because both compare the same shape for the same purpose, and two
+ * copies of a comparison is how `3.1009` ends up ranked below `3.980` in one place and not the
+ * other. Every part must be all digits — `0.1.12`, `3.1009` — which is what both version streams
+ * actually produce.
+ *
+ * Returns null when either side is unparseable (a prerelease tag, a locally-built `worktree`
+ * engine, a git describe string). Callers treat null as "say nothing": an unrecognised version is
+ * not evidence that anything is out of date, and a nudge that fires on every run is one people
+ * learn to ignore.
+ */
+export function isOlderDottedVersion(candidate, reference) {
+    const parse = (value) => {
+        if (typeof value !== 'string')
+            return null;
+        const parts = value.trim().split('.');
+        if (parts.length === 0 || parts.some((part) => !/^\d+$/.test(part)))
+            return null;
+        return parts.map(Number);
+    };
+    const a = parse(candidate);
+    const b = parse(reference);
+    if (a === null || b === null)
+        return null;
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        // A missing trailing part reads as 0, so `3.1` is older than `3.1.1` rather than unparseable.
+        const left = a[i] ?? 0;
+        const right = b[i] ?? 0;
+        if (left !== right)
+            return left < right;
+    }
+    return false;
+}
+//# sourceMappingURL=version-compare.js.map

package/dist/project/version-compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-compare.js","sourceRoot":"","sources":["../../src/project/version-compare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB,EAAE,SAAiB;IACvE,MAAM,KAAK,GAAG,CAAC,KAAa,EAAmB,EAAE;QAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACjF,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC,CAAC;IAEF,MAAM,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;IAC3B,MAAM,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;IAC3B,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAE1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzD,8FAA8F;QAC9F,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACvB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,IAAI,KAAK,KAAK;YAAE,OAAO,IAAI,GAAG,KAAK,CAAC;IAC1C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/update/check.d.ts

@@ -0,0 +1,28 @@
+import { type UpdateCheckCache } from './notice.js';
+export declare function updateCachePath(baseDir?: string): string;
+/**
+ * The last recorded answer, or null if there is none to trust.
+ *
+ * Missing, unreadable and malformed all collapse to null on purpose: the caller's next move is
+ * identical in every case — say nothing now, refresh in the background — and this is a hint, not
+ * a thing worth failing a command over.
+ */
+export declare function readUpdateCache(baseDir?: string): UpdateCheckCache | null;
+export declare function writeUpdateCache(cache: UpdateCheckCache, baseDir?: string): void;
+/** Ask npm what the newest published version is. Null on any failure. */
+export declare function fetchLatestVersion(fetchImpl?: typeof globalThis.fetch): Promise<string | null>;
+/**
+ * The notice to print right now, decided entirely from the cache.
+ *
+ * Nothing here awaits the network. A stale cache is refreshed by `refreshUpdateCacheInBackground`
+ * for the NEXT run, which is why a first-ever invocation is silent — the alternative is making
+ * every command wait on npm to be told something it could just as well be told tomorrow.
+ */
+export declare function pendingUpdateNotice(currentVersion: string, baseDir?: string): string | null;
+/**
+ * Refresh the cache if it is stale. Fire-and-forget: callers must not await this.
+ *
+ * Returns a promise only so tests can. In production the process may well exit first, which is
+ * fine — the next run reads whatever was written, and an unwritten cache simply stays stale.
+ */
+export declare function refreshUpdateCacheInBackground(now?: number, baseDir?: string, fetchImpl?: typeof globalThis.fetch): Promise<void>;

package/dist/update/check.js

@@ -0,0 +1,92 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { defaultBaseDir } from '../config/credentials.js';
+import { cliUpdateNotice, isCacheStale } from './notice.js';
+/** Public registry metadata for the published `latest` tag. No auth, no scope needed. */
+const NPM_LATEST_URL = 'https://registry.npmjs.org/@bitmagic/cli/latest';
+/**
+ * Cap on the background refresh.
+ *
+ * A pending fetch keeps Node alive, so an unbounded request would hold a finished command open
+ * for as long as the network sulks. Two seconds is generous for a registry metadata read and
+ * short enough that nobody notices when it is not.
+ */
+const REFRESH_TIMEOUT_MS = 2000;
+export function updateCachePath(baseDir = defaultBaseDir()) {
+    return path.join(baseDir, 'update-check.json');
+}
+function isCache(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const c = value;
+    return (c.latest === null || typeof c.latest === 'string') && typeof c.checkedAt === 'number';
+}
+/**
+ * The last recorded answer, or null if there is none to trust.
+ *
+ * Missing, unreadable and malformed all collapse to null on purpose: the caller's next move is
+ * identical in every case — say nothing now, refresh in the background — and this is a hint, not
+ * a thing worth failing a command over.
+ */
+export function readUpdateCache(baseDir = defaultBaseDir()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(updateCachePath(baseDir), 'utf-8'));
+        return isCache(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeUpdateCache(cache, baseDir = defaultBaseDir()) {
+    try {
+        fs.mkdirSync(baseDir, { recursive: true });
+        fs.writeFileSync(updateCachePath(baseDir), `${JSON.stringify(cache)}\n`);
+    }
+    catch {
+        // An unwritable home directory costs a cached hint, nothing else. The command proceeds.
+    }
+}
+/** Ask npm what the newest published version is. Null on any failure. */
+export async function fetchLatestVersion(fetchImpl = globalThis.fetch) {
+    try {
+        const response = await fetchImpl(NPM_LATEST_URL, {
+            signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS),
+            headers: { accept: 'application/json' },
+        });
+        if (!response.ok)
+            return null;
+        const body = await response.json();
+        if (typeof body !== 'object' || body === null)
+            return null;
+        const version = body.version;
+        return typeof version === 'string' ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The notice to print right now, decided entirely from the cache.
+ *
+ * Nothing here awaits the network. A stale cache is refreshed by `refreshUpdateCacheInBackground`
+ * for the NEXT run, which is why a first-ever invocation is silent — the alternative is making
+ * every command wait on npm to be told something it could just as well be told tomorrow.
+ */
+export function pendingUpdateNotice(currentVersion, baseDir) {
+    return cliUpdateNotice(currentVersion, readUpdateCache(baseDir)?.latest ?? null);
+}
+/**
+ * Refresh the cache if it is stale. Fire-and-forget: callers must not await this.
+ *
+ * Returns a promise only so tests can. In production the process may well exit first, which is
+ * fine — the next run reads whatever was written, and an unwritten cache simply stays stale.
+ */
+export async function refreshUpdateCacheInBackground(now = Date.now(), baseDir, fetchImpl = globalThis.fetch) {
+    if (!isCacheStale(readUpdateCache(baseDir), now))
+        return;
+    const latest = await fetchLatestVersion(fetchImpl);
+    // Recorded even when the fetch failed, so an offline machine backs off for a day rather than
+    // retrying npm on every single command.
+    writeUpdateCache({ latest, checkedAt: now }, baseDir);
+}
+//# sourceMappingURL=check.js.map

package/dist/update/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/update/check.ts"],"names":[],"mappings":"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"}

package/dist/update/notice.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How stale a cached npm answer may be before it is refreshed.
+ *
+ * The check never blocks a command: the notice is printed from the cache, and a stale cache is
+ * refreshed in the background for next time. So this is only "how far behind the notice can be",
+ * not "how long a command waits".
+ */
+export declare const UPDATE_CHECK_INTERVAL_MS: number;
+/** What is remembered between runs, so no command pays for the network. */
+export interface UpdateCheckCache {
+    /** The newest version npm reported, or null if the last check could not reach it. */
+    latest: string | null;
+    /** Epoch ms of that check. */
+    checkedAt: number;
+}
+export declare function isCacheStale(cache: UpdateCheckCache | null, now: number): boolean;
+/**
+ * The line to print, or null to stay quiet.
+ *
+ * Quiet for everything except a confirmed newer release: an unreachable npm, an unparseable
+ * version on either side, and a CLI somehow ahead of the registry all produce nothing.
+ */
+export declare function cliUpdateNotice(currentVersion: string, latestVersion: string | null | undefined): string | null;

package/dist/update/notice.js

@@ -0,0 +1,34 @@
+import { isOlderDottedVersion } from '../project/version-compare.js';
+/**
+ * How stale a cached npm answer may be before it is refreshed.
+ *
+ * The check never blocks a command: the notice is printed from the cache, and a stale cache is
+ * refreshed in the background for next time. So this is only "how far behind the notice can be",
+ * not "how long a command waits".
+ */
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export function isCacheStale(cache, now) {
+    if (cache === null)
+        return true;
+    // A clock that moved backwards (a resumed VM, a corrected clock) would otherwise pin the cache
+    // as fresh forever.
+    if (cache.checkedAt > now)
+        return true;
+    return now - cache.checkedAt >= UPDATE_CHECK_INTERVAL_MS;
+}
+/**
+ * The line to print, or null to stay quiet.
+ *
+ * Quiet for everything except a confirmed newer release: an unreachable npm, an unparseable
+ * version on either side, and a CLI somehow ahead of the registry all produce nothing.
+ */
+export function cliUpdateNotice(currentVersion, latestVersion) {
+    if (typeof latestVersion !== 'string' || latestVersion === '')
+        return null;
+    if (typeof currentVersion !== 'string' || currentVersion === '')
+        return null;
+    if (isOlderDottedVersion(currentVersion, latestVersion) !== true)
+        return null;
+    return `A newer bitmagic CLI is available: ${latestVersion} (you have ${currentVersion}). Run \`npm i -g @bitmagic/cli\` to update.`;
+}
+//# sourceMappingURL=notice.js.map

package/dist/update/notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notice.js","sourceRoot":"","sources":["../../src/update/notice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAU5D,MAAM,UAAU,YAAY,CAAC,KAA8B,EAAE,GAAW;IACtE,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,+FAA+F;IAC/F,oBAAoB;IACpB,IAAI,KAAK,CAAC,SAAS,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,GAAG,GAAG,KAAK,CAAC,SAAS,IAAI,wBAAwB,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,cAAsB,EAAE,aAAwC;IAC9F,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC3E,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7E,IAAI,oBAAoB,CAAC,cAAc,EAAE,aAAa,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9E,OAAO,sCAAsC,aAAa,cAAc,cAAc,8CAA8C,CAAC;AACvI,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitmagic/cli",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Build Bitmagic games from your own agent tool",
   "type": "module",
   "bin": {