@leemour/cli-core 0.3.0 → 0.4.0

package/README.md

@@ -7,7 +7,7 @@ keyring behind a testable seam, and injectable clocks.
 Extracted from [`brazecli`](https://github.com/leemour/brazecli), where each piece earned its
 shape, and shared with [`max-cli`](https://github.com/leemour/max-cli).
 
-**Status: 0.3.0.** Published on npm, used by `max-cli`. Both extraction steps have landed: the
+**Status: 0.4.0.** Published on npm, used by `max-cli`. Both extraction steps have landed: the
 files that move unchanged, and the ones that needed a parameter threaded through. 75 tests.
 
 ## The rule this package exists to keep
@@ -45,6 +45,7 @@ streams.stderr // []
 | `/testing` | `captureStreams`, `memoryKeyring`, `brokenKeyring`, `fakeClock` |
 | `/commands` | the command registry: `describeProgram`, `annotate`, `flatten` — see below |
 | `/completion` | shell completion over the registry: `suggest`, `formatSuggestions` — see below |
+| `/update` | keeping an install current: `installerOf`, `updateCommand`, `latestVersion`, `mayNotify` — see below |
 
 **Nothing in the root export is HTTP.** Status classification, `Retry-After` parsing and the fetch
 seam live in `@leemour/cli-core/http`, so a CLI that speaks a socket never depends on a stack it
@@ -98,6 +99,14 @@ second line of defence, not the first.
 no ambient clock. That is what makes a timeout test finish instantly and a keyring test incapable
 of reaching a real keychain.
 
+**Keeping an install current is `@leemour/cli-core/update`.** `installerOf(realpath(script))` says
+which package manager put the CLI there — pnpm, npm or bun, measured on real installs — and
+`updateCommand` gives the argv that updates it; a checkout or `npx` gets none. `latestVersion` asks
+npm with a timeout and answers `undefined` on any failure. `mayNotify` says whether a person is at a
+terminal to be told: never in JSON, a pipe, `--quiet`, `CI` or with `NO_UPDATE_NOTIFIER`. Nothing
+here updates or prints by itself — a CLI holding somebody's credentials must not change itself
+unasked.
+
 ## Where secrets actually go, per platform
 
 The keyring is real on every desktop and absent on most servers, so the fallback is not an edge

package/dist/update/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Keeping an installed CLI current: which package manager put it here, what command updates it,
+ * whether npm has something newer, and whether a person should be told.
+ *
+ * Nothing here updates anything by itself, and nothing here decides to print: a CLI that holds
+ * somebody's credentials must not change itself unasked, and a line on the terminal is for a
+ * person, never for a script or an agent reading JSON. The CLI asks and decides.
+ */
+import * as v from "valibot";
+import type { FetchLike } from "../http/index.js";
+export type Installer = "pnpm" | "npm" | "bun" | "npx" | "checkout" | "unknown";
+/**
+ * Read from where the running file really lives — `realpath` of the script, not `which`: the
+ * command on `PATH` is a shim or a link, and only its target says who installed it. Paths measured
+ * on 2026-09-24 by installing into throwaway prefixes.
+ */
+export declare const installerOf: (scriptPath: string) => Installer;
+/** The argv that updates a global install, or `undefined` where there is nothing to run. */
+export declare const updateCommand: (installer: Installer, packageName: string) => string[] | undefined;
+/** Plain `x.y.z` only: a pre-release is never offered, so it never counts as newer. */
+export declare const isNewer: (candidate: string, current: string) => boolean;
+/** The `latest` version on npm, or `undefined` on any failure — a hint may never fail a command. */
+export declare const latestVersion: (packageName: string, fetch: FetchLike, { timeoutMs }?: {
+    timeoutMs?: number;
+}) => Promise<string | undefined>;
+export declare const CHECK_EVERY_MS: number;
+export interface NotifyContext {
+    /** `pretty`, `json` or `jsonl` — the line exists only for the first. */
+    format: string;
+    stderrIsTTY: boolean;
+    quiet: boolean;
+    /** The setting; `false` turns the check off. */
+    enabled: boolean;
+    installer: Installer;
+    env: Readonly<Record<string, string | undefined>>;
+    /** Extra variables that turn it off, for the CLI's own prefix: `MAX_NO_UPDATE_CHECK`. */
+    offVariables?: readonly string[];
+}
+/** Whether a person is at a terminal who could be told — the only case a check is worth making. */
+export declare const mayNotify: ({ format, stderrIsTTY, quiet, enabled, installer, env, offVariables, }: NotifyContext) => boolean;
+declare const updateState: v.ObjectSchema<{
+    readonly checkedAt: v.NumberSchema<undefined>;
+    readonly latest: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type UpdateState = v.InferOutput<typeof updateState>;
+/** What the last check found. A missing or unreadable file is "never checked", not an error. */
+export declare const readUpdateState: (path: string) => UpdateState | undefined;
+export declare const writeUpdateState: (path: string, state: UpdateState) => void;
+export declare const checkIsDue: (state: UpdateState | undefined, now: number) => boolean;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/update/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/update/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,UAAU,GAAG,SAAS,CAAA;AAE/E;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,MAAM,KAAG,SAOhD,CAAA;AAED,4FAA4F;AAC5F,eAAO,MAAM,aAAa,GAAI,WAAW,SAAS,EAAE,aAAa,MAAM,KAAG,MAAM,EAAE,GAAG,SAYpF,CAAA;AAED,uFAAuF;AACvF,eAAO,MAAM,OAAO,GAAI,WAAW,MAAM,EAAE,SAAS,MAAM,KAAG,OAS5D,CAAA;AAED,oGAAoG;AACpG,eAAO,MAAM,aAAa,GACxB,aAAa,MAAM,EACnB,OAAO,SAAS,EAChB,gBAAsB;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,KAChD,OAAO,CAAC,MAAM,GAAG,SAAS,CAY5B,CAAA;AAED,eAAO,MAAM,cAAc,QAAsB,CAAA;AAEjD,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,OAAO,CAAA;IACpB,KAAK,EAAE,OAAO,CAAA;IACd,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,SAAS,CAAA;IACpB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IACjD,yFAAyF;IACzF,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAED,mGAAmG;AACnG,eAAO,MAAM,SAAS,GAAI,wEAQvB,aAAa,KAAG,OAQuB,CAAA;AAE1C,QAAA,MAAM,WAAW;;;aAAsE,CAAA;AACvF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,WAAW,CAAC,CAAA;AAE3D,gGAAgG;AAChG,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,WAAW,GAAG,SAO5D,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,EAAE,OAAO,WAAW,KAAG,IAMnE,CAAA;AAED,eAAO,MAAM,UAAU,GAAI,OAAO,WAAW,GAAG,SAAS,EAAE,KAAK,MAAM,KAAG,OACT,CAAA"}

package/dist/update/index.js

@@ -0,0 +1,101 @@
+/**
+ * Keeping an installed CLI current: which package manager put it here, what command updates it,
+ * whether npm has something newer, and whether a person should be told.
+ *
+ * Nothing here updates anything by itself, and nothing here decides to print: a CLI that holds
+ * somebody's credentials must not change itself unasked, and a line on the terminal is for a
+ * person, never for a script or an agent reading JSON. The CLI asks and decides.
+ */
+import * as v from "valibot";
+import { loadConfigFile, saveConfigFile } from "../config.js";
+/**
+ * Read from where the running file really lives — `realpath` of the script, not `which`: the
+ * command on `PATH` is a shim or a link, and only its target says who installed it. Paths measured
+ * on 2026-09-24 by installing into throwaway prefixes.
+ */
+export const installerOf = (scriptPath) => {
+    const path = scriptPath.replaceAll("\\", "/");
+    if (path.includes("/_npx/"))
+        return "npx";
+    if (path.includes("/install/global/node_modules/"))
+        return "bun";
+    if (/\/\.?pnpm\//.test(path))
+        return "pnpm";
+    if (path.includes("/node_modules/"))
+        return "npm";
+    return path.includes("/dist/") ? "checkout" : "unknown";
+};
+/** The argv that updates a global install, or `undefined` where there is nothing to run. */
+export const updateCommand = (installer, packageName) => {
+    const target = `${packageName}@latest`;
+    switch (installer) {
+        case "pnpm":
+            return ["pnpm", "add", "-g", target];
+        case "npm":
+            return ["npm", "install", "-g", target];
+        case "bun":
+            return ["bun", "add", "-g", target];
+        default:
+            return undefined;
+    }
+};
+/** Plain `x.y.z` only: a pre-release is never offered, so it never counts as newer. */
+export const isNewer = (candidate, current) => {
+    const parse = (version) => (/^\d+\.\d+\.\d+$/.test(version) ? version.split(".").map(Number) : undefined);
+    const a = parse(candidate);
+    const b = parse(current);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return false;
+};
+/** The `latest` version on npm, or `undefined` on any failure — a hint may never fail a command. */
+export const latestVersion = async (packageName, fetch, { timeoutMs = 1000 } = {}) => {
+    try {
+        const response = await fetch(`https://registry.npmjs.org/${packageName}/latest`, {
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { accept: "application/json" },
+        });
+        if (!response.ok)
+            return undefined;
+        const { version } = (await response.json());
+        return typeof version === "string" ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+/** Whether a person is at a terminal who could be told — the only case a check is worth making. */
+export const mayNotify = ({ format, stderrIsTTY, quiet, enabled, installer, env, offVariables = [], }) => enabled &&
+    format === "pretty" &&
+    stderrIsTTY &&
+    !quiet &&
+    updateCommand(installer, "any") !== undefined &&
+    !env.CI &&
+    !env.NO_UPDATE_NOTIFIER &&
+    offVariables.every((name) => !env[name]);
+const updateState = v.object({ checkedAt: v.number(), latest: v.optional(v.string()) });
+/** What the last check found. A missing or unreadable file is "never checked", not an error. */
+export const readUpdateState = (path) => {
+    try {
+        const state = loadConfigFile(path, updateState, () => ({ checkedAt: 0 }));
+        return state.checkedAt > 0 ? state : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const writeUpdateState = (path, state) => {
+    try {
+        saveConfigFile(path, state);
+    }
+    catch {
+        // A state file that cannot be written means asking npm again tomorrow, nothing worse.
+    }
+};
+export const checkIsDue = (state, now) => state === undefined || now - state.checkedAt >= CHECK_EVERY_MS;
+//# sourceMappingURL=index.js.map

package/dist/update/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leemour/cli-core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "MIT",
   "author": "Viacheslav Ptsarev",
@@ -38,6 +38,10 @@
     "./completion": {
       "types": "./dist/completion/index.d.ts",
       "default": "./dist/completion/index.js"
+    },
+    "./update": {
+      "types": "./dist/update/index.d.ts",
+      "default": "./dist/update/index.js"
     }
   },
   "scripts": {