@nasebanal/cli 0.5.0 → 0.6.0

package/README.md

@@ -117,6 +117,20 @@ needed for a registry install.
 > `api-specs-*` packages), it captures this package too. Install with
 > `npm install -g @nasebanal/cli --@nasebanal:registry=https://registry.npmjs.org/`.
 
+### Upgrading
+
+```bash
+nb upgrade           # install the latest published version
+nb upgrade --check   # only report whether a newer version exists
+```
+
+When a newer version is out, interactive runs print a one-line notice on stderr
+(`Update available: 0.5.0 -> 0.6.0`). The registry is checked at most once a day
+and the result is cached in `~/.config/nasebanal/update-check.json`. Nothing is
+printed when stderr is not a terminal or `CI` is set; `NB_NO_UPDATE_NOTIFIER=1`
+turns the notice off. A dev link to a source checkout is never overwritten:
+`nb upgrade` tells you to `git pull && npm run build` instead.
+
 ### Versioning and releases
 
 Versions follow SemVer (0.x until 1.0: breaking changes bump the minor). Each

package/dist/config.js

@@ -12,7 +12,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { mkdirSync, readFileSync, writeFileSync, chmodSync, existsSync } from "node:fs";
 import { refreshTokens } from "./oauth.js";
-function configDir() {
+export function configDir() {
     const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
     return join(base, "nasebanal");
 }

package/dist/index.js

@@ -14,6 +14,7 @@ import { buildAuthCommand } from "./auth.js";
 import { specExists } from "./spec/loader.js";
 import { printError } from "./output.js";
 import { buildReportUploadCommand } from "./reports/upload.js";
+import { buildUpgradeCommand, startUpdateNotifier } from "./update.js";
 // Single source of truth for the version: package.json (dist/ and src/ both sit
 // next to it). A hard-coded string here drifts from the release tag.
 const { version } = createRequire(import.meta.url)("../package.json");
@@ -26,6 +27,7 @@ program
     .option("--token <token>", "override the stored PAT for this invocation")
     .showHelpAfterError();
 program.addCommand(buildAuthCommand());
+program.addCommand(buildUpgradeCommand(version));
 for (const api of API_CATALOG) {
     if (!specExists(api.spec)) {
         // Spec not synced yet — register a stub that explains how to fix it rather
@@ -50,8 +52,10 @@ for (const api of API_CATALOG) {
     program.addCommand(group);
 }
 async function main() {
+    const notifier = startUpdateNotifier(version, process.argv);
     try {
         await program.parseAsync(process.argv);
+        await notifier.refresh();
     }
     catch (err) {
         printError(err);

package/dist/update.js

@@ -0,0 +1,127 @@
+/**
+ * Self-update: a passive "new version available" notice and `nb upgrade`.
+ *
+ * Follows the usual CLI convention (npm, gh, gcloud): the notice is a single
+ * line on stderr, shown at most once a day from a cached registry lookup, and
+ * silent for non-interactive use (pipes, CI) so scripted output never changes.
+ * `NB_NO_UPDATE_NOTIFIER=1` turns it off.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Command } from "commander";
+import { configDir } from "./config.js";
+const PACKAGE = "@nasebanal/cli";
+const REGISTRY = "https://registry.npmjs.org";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 1500;
+/** 1 if a > b, -1 if a < b, 0 if equal (plain `x.y.z`; pre-release tags are ignored). */
+export function compareVersions(a, b) {
+    const pa = a.split("-")[0].split(".").map(Number);
+    const pb = b.split("-")[0].split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const d = (pa[i] || 0) - (pb[i] || 0);
+        if (d !== 0)
+            return d > 0 ? 1 : -1;
+    }
+    return 0;
+}
+function cachePath() {
+    return join(configDir(), "update-check.json");
+}
+function readCache() {
+    try {
+        return JSON.parse(readFileSync(cachePath(), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCache(cache) {
+    try {
+        mkdirSync(configDir(), { recursive: true });
+        writeFileSync(cachePath(), JSON.stringify(cache) + "\n");
+    }
+    catch {
+        /* best effort */
+    }
+}
+/** Latest published version. Goes to the public registry directly, so a `~/.npmrc` scope mapping cannot hide it. */
+export async function fetchLatest(timeoutMs = FETCH_TIMEOUT_MS) {
+    try {
+        const res = await fetch(`${REGISTRY}/${PACKAGE.replace("/", "%2F")}/latest`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return undefined;
+        return (await res.json()).version;
+    }
+    catch {
+        return undefined;
+    }
+}
+function notifierEnabled() {
+    return !process.env.NB_NO_UPDATE_NOTIFIER && !process.env.CI && !!process.stderr.isTTY;
+}
+/**
+ * Arrange for the update notice to print when the process exits. Reads the
+ * cache synchronously; when it is older than a day, refreshes it afterwards
+ * (bounded by a short timeout) so the notice appears from the next run on.
+ */
+export function startUpdateNotifier(current, argv) {
+    const noop = { refresh: async () => { } };
+    if (!notifierEnabled() || argv.slice(2).some((a) => a === "upgrade" || a === "--version" || a === "-V"))
+        return noop;
+    const cache = readCache();
+    if (cache?.latest && compareVersions(cache.latest, current) > 0) {
+        const latest = cache.latest;
+        process.on("exit", () => {
+            process.stderr.write(`\nUpdate available: ${current} -> ${latest}. Run \`nb upgrade\` to install it.\n`);
+        });
+    }
+    const stale = !cache || Date.now() - cache.checkedAt > CHECK_INTERVAL_MS;
+    return {
+        refresh: async () => {
+            if (!stale)
+                return;
+            const latest = await fetchLatest();
+            // Record the attempt even on failure so an offline machine is not retried on every command.
+            writeCache({ checkedAt: Date.now(), latest: latest ?? cache?.latest });
+        },
+    };
+}
+/** True when `nb` is a dev link to a checkout rather than an npm-installed copy. */
+function isLinkedCheckout() {
+    try {
+        return !realpathSync(process.argv[1]).includes("node_modules");
+    }
+    catch {
+        return false;
+    }
+}
+export function buildUpgradeCommand(current) {
+    return new Command("upgrade")
+        .description("Upgrade nb to the latest published version")
+        .option("--check", "only report whether a newer version exists")
+        .action(async (opts) => {
+        const latest = await fetchLatest(5000);
+        if (!latest)
+            throw new Error("Could not reach the npm registry to look up the latest version.");
+        writeCache({ checkedAt: Date.now(), latest });
+        if (compareVersions(latest, current) <= 0) {
+            process.stdout.write(`nb ${current} is up to date.\n`);
+            return;
+        }
+        process.stdout.write(`Update available: ${current} -> ${latest}\n`);
+        if (opts.check)
+            return;
+        if (isLinkedCheckout()) {
+            process.stdout.write("This nb is linked to a source checkout: `git pull && npm run build` there instead.\n");
+            return;
+        }
+        const r = spawnSync("npm", ["install", "-g", `${PACKAGE}@${latest}`, `--@nasebanal:registry=${REGISTRY}/`], { stdio: "inherit" });
+        if (r.status !== 0) {
+            throw new Error(`npm install failed. Run it yourself: npm install -g ${PACKAGE}@latest --@nasebanal:registry=${REGISTRY}/`);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nasebanal/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "gcloud-style command-line interface for NASEBANAL APIs, generated from nb-api-specs OpenAPI contracts.",
   "license": "MIT",
   "type": "module",