@duyquangnvx/create-agent-cli 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.23.0 (2026-11-03)
+
+### Added
+
+- A Global install of a CLI with several Commands runs a Release check: at most once a day a run asks the Install registry, in a detached process, for the latest release, and later runs give the Notice ``<cli> X.Y.Z is out, this is A.B.C; run `<cli> update` `` while the CLI is behind. No run waits on it. `CI`, or `<NAME>_NO_RELEASE_CHECK=1` for one CLI, turns it off; it keeps its answer in `$XDG_CACHE_HOME/<name>/release-check.json`, by default under `~/.cache`.
+
 ## v0.22.0 (2026-11-02)
 
 ### Added

package/dist/bin.js

@@ -5959,8 +5959,12 @@ async function orMissing(pending) {
 function isNothingThere(error) {
 	return isMissingFile(error) || errnoOf(error) === "ENOTDIR";
 }
+/** The CLI's own environment variable, such as `TOOL_DEBUG` for `cliVariable("tool", "DEBUG")`. */
+function cliVariable(cliName, suffix) {
+	return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_${suffix}`;
+}
 function debugVariable(cliName) {
-	return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_DEBUG`;
+	return cliVariable(cliName, "DEBUG");
 }
 function messageOf(error) {
 	return error instanceof Error ? error.message : String(error);
@@ -7081,9 +7085,9 @@ function secretRows(secrets, commands) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "4664298",
+		"sha": "71583a7",
 		"dirty": false,
-		"builtAt": "2026-11-02T04:03:08.000Z"
+		"builtAt": "2026-11-03T06:40:47.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -7361,15 +7365,18 @@ async function installGlobally(version, ctx) {
 		...ctx.registry.flags
 	], ctx, null);
 }
-async function latestVersion(ctx) {
-	const { package: name, label: registry, flags } = ctx.registry;
-	const answer = await runNpm("view", [
+function latestViewArgs({ package: name, flags }) {
+	return [
 		"view",
 		`${name}@latest`,
 		"version",
 		"--json",
 		...flags
-	], ctx);
+	];
+}
+async function latestVersion(ctx) {
+	const { package: name, label: registry } = ctx.registry;
+	const answer = await runNpm("view", latestViewArgs(ctx.registry), ctx);
 	const version = versionInViewAnswer(answer);
 	if (version === void 0) throw noLatest(ctx, `npm answered no version for ${name}@latest on ${registry}: ${answer.trim()}`);
 	return version;
@@ -7611,7 +7618,8 @@ function dependencyInstall(cli, install) {
 		runAs,
 		builtIns: () => ({}),
 		exitClasses: [],
-		check: (launch) => checkOf$1(cli, install, runAs, launch)
+		check: (launch) => checkOf$1(cli, install, runAs, launch),
+		notice: async () => {}
 	};
 }
 //#endregion
@@ -8688,6 +8696,127 @@ function updateCommand(cli, install, skill, { bin, node }) {
 	});
 }
 //#endregion
+//#region ../agent-cli/dist/built-ins/install/release-check.js
+const CHECK_INTERVAL_MS = 864e5;
+const checkSchema = object({
+	checkedAt: number(),
+	latest: string().optional(),
+	error: string().optional()
+});
+const CHECK_SCRIPT = `
+const { spawnSync } = require("node:child_process");
+const { mkdtempSync, renameSync, rmSync, writeFileSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+const [file, checkedAt, previous, npm, ...args] = process.argv.slice(1);
+const windows = process.platform === "win32";
+const cache = mkdtempSync(join(tmpdir(), "release-check-"));
+const write = (check) => {
+  const temp = file + "." + process.pid + ".tmp";
+  writeFileSync(temp, JSON.stringify({ checkedAt: Number(checkedAt), ...check }));
+  renameSync(temp, file);
+};
+const latestOf = (stdout) => {
+  try {
+    const parsed = JSON.parse(stdout);
+    const latest = Array.isArray(parsed) ? parsed.at(-1) : parsed;
+    return typeof latest === "string" && /^\\d+\\.\\d+\\.\\d+/.test(latest) ? latest : undefined;
+  } catch {
+    return undefined;
+  }
+};
+try {
+  const answer = spawnSync(windows ? '"' + npm + '"' : npm, args, {
+    encoding: "utf8",
+    shell: windows,
+    windowsHide: true,
+    env: { ...process.env, npm_config_cache: join(cache, "cache"), npm_config_logs_max: "0" },
+  });
+  const latest = answer.status === 0 ? latestOf(answer.stdout) : undefined;
+  if (latest !== undefined) {
+    write({ latest });
+  } else {
+    const said = (answer.stderr || "").trim().split(/\\r?\\n/).slice(0, 5).join("; ");
+    const error = answer.error ? answer.error.message : said || "npm answered " + answer.stdout.trim();
+    write({ latest: previous || undefined, error });
+  }
+} finally {
+  rmSync(cache, { recursive: true, force: true });
+}
+`;
+function isOff(cliName, env) {
+	return Boolean(env[cliVariable(cliName, "NO_RELEASE_CHECK")] || env.CI);
+}
+function cacheFileOf(cliName, env) {
+	const cache = env.XDG_CACHE_HOME || join(env.HOME || env.USERPROFILE || homedir(), ".cache");
+	return join(cache, cliName, "release-check.json");
+}
+function parsedCheck(text) {
+	try {
+		return checkSchema.safeParse(JSON.parse(text)).data;
+	} catch {
+		return;
+	}
+}
+async function lastCheck(file) {
+	const text = await orMissing(readFile(file, "utf8"));
+	return text === void 0 ? void 0 : parsedCheck(text);
+}
+async function writeCheck(file, check) {
+	await mkdir(dirname(file), { recursive: true });
+	const temp = tempPathOf(file);
+	await writeFile(temp, JSON.stringify(check));
+	await rename(temp, file);
+}
+async function startCheck(cli, install, file, last, { node }, ctx) {
+	const checkedAt = ctx.clock.now();
+	const previous = last?.latest ?? "";
+	await writeCheck(file, {
+		checkedAt,
+		latest: last?.latest
+	});
+	const npm = globalNpm(cli, install, ctx, node);
+	const { path, env } = npmOf(npm, process.platform === "win32");
+	await ctx.spawnDetached(process.execPath, [
+		"-e",
+		CHECK_SCRIPT,
+		file,
+		String(checkedAt),
+		previous,
+		path,
+		...latestViewArgs(npm.registry)
+	], { env });
+}
+function debugLine(cli, ctx, text) {
+	if (isDebug({
+		env: ctx.env,
+		cliName: cli.name
+	})) ctx.progress(`release check failed: ${text}`);
+}
+/**
+* Tells the caller of a newer release that an earlier Release check found, and starts the next
+* check once the last is a day old.
+*/
+async function releaseCheck(cli, install, runAs, launch, ctx) {
+	if (launch.builtIn || launch.bin === void 0 || cli.commands === void 0) return;
+	if (isOff(cli.name, ctx.env)) return;
+	try {
+		await checkAndTell(cli, install, runAs, launch, ctx);
+	} catch (error) {
+		if (errnoOf(error) === void 0 && !(error instanceof CliError)) throw error;
+		debugLine(cli, ctx, messageOf(error));
+	}
+}
+async function checkAndTell(cli, install, runAs, launch, ctx) {
+	const file = cacheFileOf(cli.name, ctx.env);
+	const last = await lastCheck(file);
+	if (last?.error !== void 0) debugLine(cli, ctx, last.error);
+	if (last === void 0 || ctx.clock.now() - last.checkedAt >= CHECK_INTERVAL_MS) await startCheck(cli, install, file, last, launch, ctx);
+	const latest = last?.latest;
+	if (latest === void 0 || !isVersion(latest) || compareVersions(latest, cli.version) <= 0) return;
+	ctx.notice(`${cli.name} ${latest} is out, this is ${cli.version}; run \`${runAs} update\``);
+}
+//#endregion
 //#region ../agent-cli/dist/built-ins/install/global.js
 function checkOf(cli, install, { bin, node }) {
 	return {
@@ -8722,12 +8851,14 @@ function globalInstall(cli, install) {
 		runAs: runAsOf(cli),
 		builtIns: (launch) => ({ update: updateCommand(cli, install, skillOf$1(cli, adapter), launch) }),
 		exitClasses: ["source"],
-		check: (launch) => checkOf(cli, install, launch)
+		check: (launch) => checkOf(cli, install, launch),
+		notice: (launch, ctx) => releaseCheck(cli, install, adapter.runAs, launch, ctx)
 	};
 	return adapter;
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/install/install.js
+const noNotice = async () => {};
 function noInstall(cli) {
 	const skipped = async () => ({
 		state: "skipped",
@@ -8740,7 +8871,8 @@ function noInstall(cli) {
 		check: () => ({
 			install: skipped,
 			release: async () => ({ skipped: await skipped() })
-		})
+		}),
+		notice: noNotice
 	};
 }
 function installOf(cli) {
@@ -11178,9 +11310,10 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	let served = false;
 	let settled;
 	try {
-		const outcome = await control.settle(skillOf$1(cli, installOf(cli)).notice({
+		const outcome = await control.settle(noticesOf(cli, {
 			builtIn,
-			bin: options.bin
+			bin: options.bin,
+			node: options.node
 		}, ctx).then(() => execute(command, input, ctx, {
 			dryRun: flags.dryRun,
 			confirm: flags.confirm,
@@ -11240,6 +11373,11 @@ function once(build) {
 		throw outcome.error;
 	};
 }
+async function noticesOf(cli, launch, ctx) {
+	const install = installOf(cli);
+	await skillOf$1(cli, install).notice(launch, ctx);
+	await install.notice(launch, ctx);
+}
 //#endregion
 //#region ../agent-cli/dist/style.js
 function colourEnabled(env, stdoutIsTTY) {
@@ -11394,7 +11532,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.22.0",
+	version: "0.23.0",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
   "type": "module",
   "engines": {
@@ -21,7 +21,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@duyquangnvx/agent-cli": "0.22.0",
+    "@duyquangnvx/agent-cli": "0.23.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },