@shardflux/cli 0.4.0 → 0.5.0

package/dist/update-check.js

@@ -0,0 +1,128 @@
+/**
+ * `shard` tells its user when it is outdated or no longer supported (0.5.0+; contracts §30.4). The API's
+ * GET /v1/client-versions names the latest published version of every client and the oldest one it still serves.
+ *
+ * - At most one request per 24 hours per API URL and package: the answer is cached in
+ *   <config dir>/update-check.json (`checked_at`, `latest`, `minimum_supported`, `upgrade_command`). The attempt is
+ *   recorded before the request, so an unreachable API is not asked again for a day either.
+ * - Started in parallel with the command (the SDK's checkClientVersion: one request, 3 s timeout, never throws) and
+ *   printed on stderr after it. When the command ends first, `shard` waits at most ~300 ms and otherwise skips the
+ *   notice (the next run uses what this one cached). Never changes the exit code; never printed after a command that
+ *   failed with --json (the error document stays the only stderr content).
+ * - Identity: `@shardflux/cli` at CLI_VERSION, or the distribution that runs the CLI (the `shardflux` npm bundle passes
+ *   its own name and version to main()).
+ * - Off with SHARDFLUX_NO_UPDATE_CHECK=1 (also true/yes/on) or NO_UPDATE_NOTIFIER (the SDK's rules);
+ *   `shard version --check` still asks.
+ */
+import { checkClientVersion, clientVersionStatus, versionCheckDisabledByEnv } from '@shardflux/sdk';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CLI_VERSION } from "./args.js";
+import { writePrivateFile } from "./credentials.js";
+export const UPDATE_CHECK_FILE = 'update-check.json';
+export const CHECK_INTERVAL_MS = 24 * 3600 * 1000;
+/** How long the end of a command waits for a check that is still running. */
+export const NOTICE_WAIT_MS = 300;
+export const CLI_DISTRIBUTION = { package: '@shardflux/cli', version: CLI_VERSION };
+export function updateCheckDisabled(env) {
+    return versionCheckDisabledByEnv(env);
+}
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const strOrNull = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
+function readCache(file) {
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        if (isObj(raw) && raw.version === 1 && isObj(raw.checks))
+            return raw;
+    }
+    catch {
+        // Missing or unreadable: a cache, so start over.
+    }
+    return { version: 1, checks: {} };
+}
+function entryOf(doc, apiUrl, pkg) {
+    const e = doc.checks[apiUrl]?.[pkg];
+    if (!isObj(e) || typeof e.checked_at !== 'string' || Number.isNaN(Date.parse(e.checked_at)))
+        return null;
+    return { checked_at: e.checked_at, latest: strOrNull(e.latest), minimum_supported: strOrNull(e.minimum_supported), upgrade_command: strOrNull(e.upgrade_command), release_notes_url: strOrNull(e.release_notes_url) };
+}
+/** The status the cached answer gives this distribution (the same rules as the SDK; no request). */
+export function statusFromEntry(entry, d) {
+    const clients = entry && (entry.latest !== null || entry.minimum_supported !== null) ? [{ package: d.package, ecosystem: 'npm', ...entry }] : [];
+    return clientVersionStatus({ clients }, { package: d.package, version: d.version, ecosystem: 'npm' });
+}
+export function updateView(s, checkedAt) {
+    return { package: s.package, current: s.current, status: s.status, latest: s.latest, minimum_supported: s.minimumSupported, upgrade_command: s.upgradeCommand, checked_at: checkedAt };
+}
+/**
+ * One command's check: `start()` returns at once (a fresh cache answers without a request); `result(waitMs)` is the
+ * status, or null when the request has not finished within `waitMs`.
+ */
+export class UpdateCheck {
+    #o;
+    #file;
+    #pending = null;
+    constructor(opts) {
+        this.#o = opts;
+        this.#file = join(opts.dir, UPDATE_CHECK_FILE);
+    }
+    /** The cached answer, whatever its age (no request). */
+    peek() {
+        const cached = entryOf(readCache(this.#file), this.#o.apiUrl, this.#o.distribution.package);
+        return cached ? { status: statusFromEntry(cached, this.#o.distribution), checkedAt: cached.checked_at } : null;
+    }
+    /** Starts the check: from the cache when it is younger than 24 h (unless `force`), else one request. */
+    start(force = false) {
+        const { apiUrl, distribution: d } = this.#o;
+        const now = (this.#o.now ?? Date.now)();
+        const doc = readCache(this.#file);
+        const cached = entryOf(doc, apiUrl, d.package);
+        if (!force && cached && now - Date.parse(cached.checked_at) < CHECK_INTERVAL_MS && Date.parse(cached.checked_at) <= now + 60_000) {
+            this.#pending = Promise.resolve({ status: statusFromEntry(cached, d), checkedAt: cached.checked_at });
+            return;
+        }
+        const checkedAt = new Date(now).toISOString();
+        // Record the attempt first: a request that never finishes (the command ended, the API is unreachable) still
+        // counts, and the previous answer stays until a new one arrives.
+        this.#write(doc, { ...(cached ?? { latest: null, minimum_supported: null, upgrade_command: null, release_notes_url: null }), checked_at: checkedAt });
+        this.#pending = checkClientVersion({ baseUrl: apiUrl, fetch: this.#o.fetch, package: d.package, version: d.version, ecosystem: 'npm', userAgent: this.#o.userAgent }).then((status) => {
+            const answered = status.latest !== null || status.minimumSupported !== null;
+            if (!answered)
+                return { status: cached ? statusFromEntry(cached, d) : status, checkedAt: cached ? cached.checked_at : null };
+            this.#write(readCache(this.#file), { checked_at: checkedAt, latest: status.latest, minimum_supported: status.minimumSupported, upgrade_command: status.upgradeCommand, release_notes_url: status.releaseNotesUrl });
+            return { status, checkedAt };
+        });
+    }
+    /** The status (with when it was fetched), or null when not started or still running after `waitMs`. */
+    async result(waitMs) {
+        if (!this.#pending)
+            return null;
+        let timer;
+        const late = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), waitMs);
+            timer.unref();
+        });
+        try {
+            return await Promise.race([this.#pending.catch(() => null), late]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    #write(doc, entry) {
+        try {
+            const { apiUrl, distribution: d } = this.#o;
+            doc.checks[apiUrl] = { ...(doc.checks[apiUrl] ?? {}), [d.package]: entry };
+            writePrivateFile(this.#o.dir, this.#file, `${JSON.stringify(doc, null, 2)}\n`);
+        }
+        catch {
+            // A cache: a read-only or missing config directory only means the next run asks again.
+        }
+    }
+}
+/** The one-line notice for stderr, or null when there is nothing to say. */
+export function noticeOf(s) {
+    if (!s || (s.status !== 'outdated' && s.status !== 'unsupported') || !s.message)
+        return null;
+    return `${s.message}\n`;
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
-  "description": "shard: the Shardflux command line. Open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
+  "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
   "license": "Apache-2.0",
   "homepage": "https://shardflux.dev",
   "keywords": [
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.7.0"
+    "@shardflux/sdk": "^0.9.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",