@ze-norm/cli 0.10.0 → 0.11.0

package/dist/index.js

@@ -10,7 +10,7 @@ import { initCommand } from "./commands/init.js";
 import { installSkillsCommand } from "./commands/install-skills.js";
 import { sessionCheckCommand } from "./commands/session-check.js";
 import { getCliVersion } from "./util/package.js";
-import { maybeSelfUpdate } from "./util/self-update.js";
+import { armSelfUpdate } from "./util/self-update.js";
 const helpText = `zenorm - ZeNorm CLI
 
 Usage:
@@ -57,6 +57,14 @@ async function main() {
     const args = rawArgs.filter((a) => !VERBOSE_FLAGS.has(a));
     // Only parse top-level flags (--help, --version). Don't parse subcommand flags.
     const commandName = args.find((a) => !a.startsWith("-"));
+    // Fire-and-forget background auto-upgrade. Armed on EVERY path — including
+    // --version/--help and the non-interactive `session-check` stop hook, which
+    // is the highest-frequency call for an active customer and previously never
+    // armed an update. The actual `npm i -g` is detached and never blocks this
+    // command. The interactive notice (stderr) is suppressed for `session-check`
+    // (reserves stdout for the hook protocol) and only shown when stdout is a TTY.
+    const notifyUpdate = commandName !== "session-check" && process.stdout.isTTY === true;
+    void armSelfUpdate(notifyUpdate);
     if (args.includes("--version") || args.includes("-v")) {
         log.plain(`zenorm ${getCliVersion()}`);
         return;
@@ -69,14 +77,6 @@ async function main() {
     if (!handler) {
         throw new CliError(`Unknown command: ${commandName}\n\nRun \`zenorm --help\` for usage.`);
     }
-    // Passive "newer version on npm" nudge. Skipped for `session-check`, which
-    // speaks the Claude Code Stop-hook protocol on stdout/stderr and must emit
-    // nothing else.
-    if (commandName !== "session-check") {
-        // Fire-and-forget: auto-upgrade in the background when possible, else nudge.
-        // Never blocks or fails the command.
-        void maybeSelfUpdate();
-    }
     // Pass everything after the command name to the handler.
     // Routed to stderr (debugErr): `session-check` reserves stdout for the
     // Claude Code hook protocol, and this dispatch line runs for every command.

package/dist/util/self-update.d.ts

@@ -1,25 +1,43 @@
 /**
- * Auto-upgrade the CLI in the background when a newer version is on npm.
+ * Arm the background CLI auto-upgrade. Silent and safe on EVERY invocation
+ * path — including non-interactive ones (the Claude Code `session-check` stop
+ * hook), which is the highest-frequency call for an active customer and the
+ * path that previously never armed an update.
  *
  * Distribution is `npm install -g`, so there is no safe way to hot-swap the
- * running process. The workable model (used by codex, qwen-code, pi, etc.) is
- * apply-on-next-run: detect a newer version, spawn a *detached* `npm i -g`
- * that outlives this process, let the current command finish on the current
- * version, and the upgrade is live next invocation.
+ * running process. The model is apply-on-next-run: detect a newer version,
+ * spawn a *detached* `npm i -g` that outlives this process, let the current
+ * command finish on the current version, and the upgrade is live next
+ * invocation. npm `-g` cannot hot-swap a running process — that one-run floor
+ * is irreducible regardless of mechanism.
+ *
+ * `updateCheckInterval: 0` makes update-notifier refresh its cached registry
+ * result on every call, so a publish is detected within one or two
+ * invocations rather than waiting out a daily cache. For an active user whose
+ * stop hook fires many times an hour, that lands a new version within
+ * minutes-to-an-hour.
  *
  * The load-bearing constraint is whether the npm global prefix is writable:
  *   - Writable (user-owned prefix: nvm/fnm/volta, or `npm config set prefix`
- *     to a home dir) -> spawn the background upgrade. This is the silent path.
+ *     to a home dir) -> spawn the background upgrade.
  *   - Not writable (system/Homebrew node, or a sudo-installed global) -> never
- *     sudo; fall back to printing the manual upgrade command.
+ *     sudo; surface a manual-upgrade nudge to interactive callers instead.
+ *
+ * A single-flight marker (keyed to the target version, with a staleness TTL)
+ * prevents the high-frequency paths from spawning concurrent `npm i -g`
+ * processes in the window between detecting an update and the install
+ * finishing.
  *
  * All of this is best-effort and never blocks or fails a real command. Every
  * dependency is lazy-imported so a missing optional dep can't crash startup
- * (the published package ships only `dist`).
+ * (the published package ships only `dist`). Opt out with
+ * ZENORM_NO_AUTO_UPDATE=1; skipped in CI and for non-global installs.
  *
- * Opt out with ZENORM_NO_AUTO_UPDATE=1. Skipped in CI and non-interactive
- * shells, and for non-global installs (a local dep / npx invocation — updating
- * someone's project dependency from under them would be wrong).
+ * @param notify when true (interactive, non-`session-check` commands), emit a
+ *   one-line stderr notice about the in-progress upgrade or the manual command
+ *   for non-writable prefixes. When false, stay completely silent — required
+ *   for the stop-hook path, which reserves stdout for the hook protocol
+ *   (notices go to stderr, but silence keeps the high-frequency path clean).
  */
-export declare function maybeSelfUpdate(): Promise<void>;
+export declare function armSelfUpdate(notify: boolean): Promise<void>;
 //# sourceMappingURL=self-update.d.ts.map

package/dist/util/self-update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"self-update.d.ts","sourceRoot":"","sources":["../../src/util/self-update.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAiDrD"}
+{"version":3,"file":"self-update.d.ts","sourceRoot":"","sources":["../../src/util/self-update.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA+DlE"}

package/dist/util/self-update.js

@@ -1,64 +1,99 @@
 import { spawn } from "node:child_process";
-import { accessSync, constants } from "node:fs";
+import { accessSync, constants, statSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { log } from "./logger.js";
 import { getCliVersion } from "./package.js";
 const PACKAGE_NAME = "@ze-norm/cli";
 const UPGRADE_COMMAND = `npm install -g ${PACKAGE_NAME}@latest`;
 const OPT_OUT_ENV = "ZENORM_NO_AUTO_UPDATE";
+// How long a single-flight marker is honored before we assume the prior
+// background install crashed/stalled and allow a fresh attempt. Bounds the
+// blast radius of a wedged install without permanently blocking updates.
+const SINGLE_FLIGHT_TTL_MS = 10 * 60 * 1000;
 /**
- * Auto-upgrade the CLI in the background when a newer version is on npm.
+ * Arm the background CLI auto-upgrade. Silent and safe on EVERY invocation
+ * path — including non-interactive ones (the Claude Code `session-check` stop
+ * hook), which is the highest-frequency call for an active customer and the
+ * path that previously never armed an update.
  *
  * Distribution is `npm install -g`, so there is no safe way to hot-swap the
- * running process. The workable model (used by codex, qwen-code, pi, etc.) is
- * apply-on-next-run: detect a newer version, spawn a *detached* `npm i -g`
- * that outlives this process, let the current command finish on the current
- * version, and the upgrade is live next invocation.
+ * running process. The model is apply-on-next-run: detect a newer version,
+ * spawn a *detached* `npm i -g` that outlives this process, let the current
+ * command finish on the current version, and the upgrade is live next
+ * invocation. npm `-g` cannot hot-swap a running process — that one-run floor
+ * is irreducible regardless of mechanism.
+ *
+ * `updateCheckInterval: 0` makes update-notifier refresh its cached registry
+ * result on every call, so a publish is detected within one or two
+ * invocations rather than waiting out a daily cache. For an active user whose
+ * stop hook fires many times an hour, that lands a new version within
+ * minutes-to-an-hour.
  *
  * The load-bearing constraint is whether the npm global prefix is writable:
  *   - Writable (user-owned prefix: nvm/fnm/volta, or `npm config set prefix`
- *     to a home dir) -> spawn the background upgrade. This is the silent path.
+ *     to a home dir) -> spawn the background upgrade.
  *   - Not writable (system/Homebrew node, or a sudo-installed global) -> never
- *     sudo; fall back to printing the manual upgrade command.
+ *     sudo; surface a manual-upgrade nudge to interactive callers instead.
+ *
+ * A single-flight marker (keyed to the target version, with a staleness TTL)
+ * prevents the high-frequency paths from spawning concurrent `npm i -g`
+ * processes in the window between detecting an update and the install
+ * finishing.
  *
  * All of this is best-effort and never blocks or fails a real command. Every
  * dependency is lazy-imported so a missing optional dep can't crash startup
- * (the published package ships only `dist`).
+ * (the published package ships only `dist`). Opt out with
+ * ZENORM_NO_AUTO_UPDATE=1; skipped in CI and for non-global installs.
  *
- * Opt out with ZENORM_NO_AUTO_UPDATE=1. Skipped in CI and non-interactive
- * shells, and for non-global installs (a local dep / npx invocation — updating
- * someone's project dependency from under them would be wrong).
+ * @param notify when true (interactive, non-`session-check` commands), emit a
+ *   one-line stderr notice about the in-progress upgrade or the manual command
+ *   for non-writable prefixes. When false, stay completely silent — required
+ *   for the stop-hook path, which reserves stdout for the hook protocol
+ *   (notices go to stderr, but silence keeps the high-frequency path clean).
  */
-export async function maybeSelfUpdate() {
+export async function armSelfUpdate(notify) {
     try {
         if (process.env[OPT_OUT_ENV])
             return;
-        // CI and non-TTY: don't mutate the environment behind an automated caller.
-        if (process.env["CI"] || !process.stdout.isTTY)
+        // CI: don't mutate the environment behind an automated caller. (No isTTY
+        // gate here — the stop-hook path is non-TTY and MUST still arm.)
+        if (process.env["CI"])
             return;
         const current = getCliVersion();
         const { default: updateNotifier } = await import("update-notifier");
         const notifier = updateNotifier({
             pkg: { name: PACKAGE_NAME, version: current },
-            updateCheckInterval: 1000 * 60 * 60 * 24,
+            // Refresh the cached check on every call so a fresh publish is seen
+            // within one invocation instead of waiting out a daily interval.
+            updateCheckInterval: 0,
         });
-        // `update` is populated from update-notifier's cached daily check; null
-        // when no newer version is known yet. Reusing it avoids a second registry
-        // round-trip.
         const update = notifier.update;
         if (!update || update.latest === current)
             return;
         const { default: isInstalledGlobally } = await import("is-installed-globally");
         if (!isInstalledGlobally) {
             // Local dep or npx: just nudge, never touch it.
-            printManualUpgrade(current, update.latest);
+            if (notify)
+                printManualUpgrade(current, update.latest);
             return;
         }
         const { default: globalDirectory } = await import("global-directory");
         const prefix = globalDirectory.npm.prefix;
         if (!prefix || !isWritable(prefix)) {
             // System/Homebrew/sudo install — can't write without root, and we never
-            // sudo. Tell the user how to upgrade themselves.
-            printManualUpgrade(current, update.latest);
+            // sudo. Tell interactive callers how to upgrade themselves.
+            if (notify)
+                printManualUpgrade(current, update.latest);
+            return;
+        }
+        // Single-flight: if another invocation already started installing this
+        // target version recently, don't spawn a duplicate `npm i -g`.
+        if (!claimSingleFlight(update.latest)) {
+            if (notify) {
+                log.warn(`ZeNorm CLI ${update.latest} is installing in the background. ` +
+                    `It takes effect on your next command.`);
+            }
             return;
         }
         // Detached, non-blocking. Outlives this process; the upgrade lands for the
@@ -68,13 +103,51 @@ export async function maybeSelfUpdate() {
             stdio: "ignore",
         });
         child.unref();
-        log.warn(`Updating ZeNorm CLI ${current} -> ${update.latest} in the background. ` +
-            `The new version takes effect on your next command.`);
+        if (notify) {
+            log.warn(`Updating ZeNorm CLI ${current} -> ${update.latest} in the background. ` +
+                `The new version takes effect on your next command.`);
+        }
     }
     catch {
         // Never break a real command on an update attempt.
     }
 }
+/**
+ * Claim the single-flight slot for installing `targetVersion`. Returns true if
+ * this process should spawn the install, false if a recent install of the same
+ * target is already in flight.
+ *
+ * Implemented as a per-target marker file in the OS temp dir. A marker older
+ * than SINGLE_FLIGHT_TTL_MS is treated as stale (a crashed/stalled prior
+ * attempt) and reclaimed, so a failed install can't permanently wedge updates.
+ */
+function claimSingleFlight(targetVersion) {
+    // Sanitize the version into a safe filename component (registry versions are
+    // semver, but defend against anything odd from the registry response).
+    const safe = targetVersion.replace(/[^A-Za-z0-9._-]/g, "_");
+    const marker = join(tmpdir(), `zenorm-cli-update-${safe}.lock`);
+    try {
+        const age = Date.now() - statSync(marker).mtimeMs;
+        if (age < SINGLE_FLIGHT_TTL_MS) {
+            return false; // fresh marker: an install is already in flight.
+        }
+        // Stale marker: refresh its mtime to re-claim and proceed.
+        utimesSync(marker, new Date(), new Date());
+        return true;
+    }
+    catch {
+        // No marker yet (or stat failed): create it and claim.
+        try {
+            writeFileSync(marker, String(Date.now()));
+            return true;
+        }
+        catch {
+            // Can't write a marker — fail open and allow the install rather than
+            // blocking updates on a temp-dir hiccup.
+            return true;
+        }
+    }
+}
 function isWritable(dir) {
     try {
         accessSync(dir, constants.W_OK);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ze-norm/cli",
   "private": false,
-  "version": "0.10.0",
+  "version": "0.11.0",
   "license": "SEE LICENSE IN README.md",
   "type": "module",
   "repository": {