@leemour/cli-core 0.2.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.2.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
@@ -44,6 +44,8 @@ streams.stderr // []
 | `retry` | full-jitter backoff, and the distinction between "no answer came" and "safe to repeat" |
 | `/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
@@ -72,6 +74,21 @@ Each option says whether it `takesValue` and, separately, whether it is `mandato
 Commander's `required`, which means "takes a value when given" — plus its choices, default,
 environment variable, the options it `conflicts` with and the values it `implies`.
 
+**Shell completion is `@leemour/cli-core/completion`**, built on the registry. `suggest` takes the
+words typed so far and answers what may come next: a command, an action, an option, one of its
+values, or an argument's values from a source the CLI hands in — a local cache, never the network,
+because a shell calls it on every Tab. `formatSuggestions` writes the answer in the protocol of the
+shell scripts [`@bomb.sh/tab`](https://github.com/bombshell-dev/tab) generates, so the CLI prints
+those scripts with tab and answers `<cli> complete -- <words>` with this; cli-core itself does not
+depend on tab.
+
+```ts
+import { formatSuggestions, suggest } from "@leemour/cli-core/completion"
+
+const words = argv.slice(argv.indexOf("--") + 1)
+streams.data(formatSuggestions(suggest({ commands, globalOptions, words, sources: { arguments: { chat: chatNames } } })))
+```
+
 **Two traps worth knowing before you use the credential store.** The OS keyring is global: an entry
 is addressed by service and account and knows nothing about which config directory asked for it, so
 a throwaway config directory silently overwrites the real secret unless you pass `isolated: true`.
@@ -82,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/commands/index.js

@@ -5,7 +5,7 @@ export const annotate = (command, meta) => {
     return command;
 };
 export const metaOf = (command) => labels.get(command) ?? {};
-export const describeProgram = (root) => root.commands.map((child) => describe(child, root.name(), []));
+export const describeProgram = (root) => visible(root).map((child) => describe(child, root.name(), []));
 export const describeOptions = (command) => command.options.filter((option) => !option.hidden).map(describeOption);
 export const flatten = (commands) => commands.flatMap((command) => [command, ...flatten(command.commands)]);
 const describe = (command, cli, parents) => {
@@ -31,9 +31,11 @@ const describe = (command, cli, parents) => {
         ...meta,
         arguments: args,
         options,
-        commands: command.commands.map((child) => describe(child, cli, path)),
+        commands: visible(command).map((child) => describe(child, cli, path)),
     };
 };
+// `addCommand(command, { hidden: true })` sets only this; Commander has no public getter for it.
+const visible = (command) => command.commands.filter((child) => !child._hidden);
 const describeArgument = (argument) => ({
     name: argument.name(),
     required: argument.required,

package/dist/commands/index.js.map

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

package/dist/completion/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shell completion over the command registry: which word may come next, as data.
+ *
+ * It speaks the protocol of the shell scripts `@bomb.sh/tab` generates — the shell runs
+ * `<cli> complete -- <words>` and reads `value<TAB>description` lines ending in `:<directive>` —
+ * so a CLI prints those scripts with tab and answers the requests with this. Nothing here reads a
+ * terminal, a file or the network: the words come in, the suggestions go out, and where values come
+ * from (a local cache, a config file) is the CLI's business, handed in as `sources`.
+ */
+import type { CommandInfo, OptionInfo } from "../commands/index.js";
+export interface Suggestion {
+    value: string;
+    description: string;
+}
+/** Values for one argument or option. Called on every Tab, so it must be cheap and must not connect anywhere. */
+export type Values = () => readonly (string | Suggestion)[];
+export interface CompletionSources {
+    /** By argument name, as registered: `chat`, `person`. */
+    arguments?: Readonly<Record<string, Values>>;
+    /** By long option name without dashes: `chat` for `--chat <id>`. */
+    options?: Readonly<Record<string, Values>>;
+    /** Offered alongside the top-level commands — a profile name that may come first, say. */
+    firstWord?: Values;
+}
+export interface CompletionRequest {
+    commands: readonly CommandInfo[];
+    globalOptions?: readonly OptionInfo[];
+    /** Everything after `complete --`; the last word is the one being typed, `""` for a fresh one. */
+    words: readonly string[];
+    sources?: CompletionSources;
+}
+/** Tells the shell not to fall back to file names when nothing matched. */
+export declare const NO_FILE_COMPLETION = 4;
+export declare const suggest: ({ commands, globalOptions, words, sources }: CompletionRequest) => Suggestion[];
+/** The answer in the form the shell script reads. */
+export declare const formatSuggestions: (suggestions: readonly Suggestion[]) => string;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/completion/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAgB,WAAW,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEjF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,iHAAiH;AACjH,MAAM,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,CAAA;AAE3D,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC5C,oEAAoE;IACpE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC1C,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;IAChC,aAAa,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IACrC,kGAAkG;IAClG,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,OAAO,CAAC,EAAE,iBAAiB,CAAA;CAC5B;AAED,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,eAAO,MAAM,OAAO,GAAI,6CAAuD,iBAAiB,KAAG,UAAU,EA2C5G,CAAA;AAED,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,GAAI,aAAa,SAAS,UAAU,EAAE,KAAG,MAC4C,CAAA"}

package/dist/completion/index.js

@@ -0,0 +1,87 @@
+/** Tells the shell not to fall back to file names when nothing matched. */
+export const NO_FILE_COMPLETION = 4;
+export const suggest = ({ commands, globalOptions = [], words, sources = {} }) => {
+    const typed = words.at(-1) ?? "";
+    const before = words.slice(0, -1);
+    let level = commands;
+    let current;
+    let positional = 0;
+    let pending;
+    for (const word of before) {
+        if (pending) {
+            pending = undefined;
+            continue;
+        }
+        if (word.startsWith("-")) {
+            const option = findOption(word, current, globalOptions);
+            if (option?.takesValue && !word.includes("="))
+                pending = option;
+            continue;
+        }
+        const child = level.find((command) => command.name === word);
+        if (child) {
+            current = child;
+            level = child.commands;
+            positional = 0;
+        }
+        else {
+            positional += 1;
+        }
+    }
+    const candidates = pending
+        ? optionValues(pending, sources)
+        : typed.startsWith("-")
+            ? typed.includes("=")
+                ? valuesAfterEquals(typed, current, globalOptions, sources)
+                : optionNames(current, globalOptions)
+            : [
+                ...level.filter((command) => command.state !== "deprecated").map(asSuggestion),
+                ...(current ? argumentValues(current.arguments, positional, sources) : []),
+                ...(current ? [] : resolve(sources.firstWord)),
+            ];
+    const unique = new Map(candidates.map((candidate) => [candidate.value, candidate]));
+    return [...unique.values()].filter(({ value }) => value.startsWith(typed));
+};
+/** The answer in the form the shell script reads. */
+export const formatSuggestions = (suggestions) => [...suggestions.map(({ value, description }) => `${value}\t${description}`), `:${NO_FILE_COMPLETION}`].join("\n");
+const asSuggestion = (command) => ({
+    value: command.name,
+    description: command.summary ?? command.description,
+});
+const longName = (option) => option.flags.match(/--([\w-]+)/)?.[1];
+const findOption = (word, current, globals) => {
+    const name = word.replace(/^-+/, "").split("=")[0];
+    const matches = (option) => longName(option) === name || option.flags.split(/[ ,]+/).includes(`-${name}`);
+    return [...(current?.options ?? []), ...globals].find(matches);
+};
+const optionNames = (current, globals) => [...(current?.options ?? []), ...globals].flatMap((option) => {
+    const name = longName(option);
+    return name ? [{ value: `--${name}`, description: option.description }] : [];
+});
+/** `--kind <dialog|group|channel>`: Commander does not know these as choices, but the flags say them. */
+const inlineChoices = (flags) => flags.match(/<([^>]*\|[^>]*)>/)?.[1]?.split("|") ?? [];
+const optionValues = (option, sources) => {
+    const name = longName(option);
+    return [
+        ...[...(option.choices ?? []), ...inlineChoices(option.flags)].map((value) => ({ value, description: "" })),
+        ...resolve(name ? sources.options?.[name] : undefined),
+    ];
+};
+const valuesAfterEquals = (typed, current, globals, sources) => {
+    const [flag] = typed.split("=");
+    const option = findOption(flag ?? "", current, globals);
+    if (!option?.takesValue)
+        return [];
+    return optionValues(option, sources).map(({ value, description }) => ({ value: `${flag}=${value}`, description }));
+};
+const argumentValues = (args, position, sources) => {
+    const argument = args[position] ?? (args.at(-1)?.variadic ? args.at(-1) : undefined);
+    if (!argument)
+        return [];
+    return [
+        ...(argument.choices ?? []).map((value) => ({ value, description: "" })),
+        ...resolve(sources.arguments?.[argument.name]),
+    ];
+};
+const resolve = (values) => (values?.() ?? []).map((value) => (typeof value === "string" ? { value, description: "" } : value));
+//# sourceMappingURL=index.js.map

package/dist/completion/index.js.map

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

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.2.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",
@@ -34,6 +34,14 @@
     "./commands": {
       "types": "./dist/commands/index.d.ts",
       "default": "./dist/commands/index.js"
+    },
+    "./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": {