@ze-norm/cli 0.8.0 → 0.10.0

package/README.md

@@ -12,6 +12,17 @@ The CLI includes the ZeNorm agent skills in the npm package. `zenorm install-ski
 installs those bundled skills through the `skills` package; it does not require
 a separate skills repository.
 
+## Staying up to date
+
+The CLI keeps itself current. When a newer version is on npm and your global
+install location is writable (the common case for nvm/fnm/volta or a
+`~/.npm-global` prefix), it upgrades in the background — the new version takes
+effect on your next command. If the install location needs root (system or
+Homebrew node, or a `sudo`-installed global), it prints the upgrade command
+instead of escalating privileges. Set `ZENORM_NO_AUTO_UPDATE=1` to disable the
+background upgrade entirely. Auto-update is skipped in CI and non-interactive
+shells.
+
 Examples:
 
 ```sh

package/dist/commands/install-skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install-skills.d.ts","sourceRoot":"","sources":["../../src/commands/install-skills.ts"],"names":[],"mappings":"AA4MA,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCxE"}
+{"version":3,"file":"install-skills.d.ts","sourceRoot":"","sources":["../../src/commands/install-skills.ts"],"names":[],"mappings":"AAqOA,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCxE"}

package/dist/commands/install-skills.js

@@ -93,6 +93,21 @@ function installToTargetDir(targetDir, force) {
     }
     log.success(`Installed ${skillNames.length} ZeNorm skill(s): ${targetDir}`);
 }
+// `skills list` ignores its `--agent` flag and returns every agent's skills, so
+// we scope by the displayName entries in each skill's `agents` array instead.
+// Match on alphanumeric-lowercase normalization: "claude-code" <-> "Claude Code",
+// "github-copilot" <-> "GitHub Copilot", "gemini-cli" <-> "Gemini CLI", etc.
+function normalizeAgentLabel(label) {
+    return label.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function skillBelongsToAgent(skill, agent) {
+    if (agent === "*")
+        return true;
+    if (!Array.isArray(skill.agents))
+        return false;
+    const wanted = normalizeAgentLabel(agent);
+    return skill.agents.some((label) => typeof label === "string" && normalizeAgentLabel(label) === wanted);
+}
 function listInstalledSkills(agent, project) {
     const scopeArgs = project ? [] : ["--global"];
     const agentArgs = agent === "*" ? [] : ["--agent", agent];
@@ -116,13 +131,19 @@ function assertNoInstalledZeNormSkills(agent, project, force) {
     if (force)
         return;
     const bundledSkillNames = new Set(listSkillDirs(getBundledSkillsRoot()));
-    const existing = listInstalledSkills(agent, project).filter((skill) => typeof skill.name === "string" && bundledSkillNames.has(skill.name));
+    const existing = listInstalledSkills(agent, project).filter((skill) => typeof skill.name === "string" &&
+        bundledSkillNames.has(skill.name) &&
+        skillBelongsToAgent(skill, agent));
     if (existing.length === 0)
         return;
-    const details = existing
-        .map((skill) => typeof skill.path === "string" ? `${String(skill.name)} (${skill.path})` : String(skill.name))
-        .join(", ");
-    throw new CliError(`Refusing to overwrite existing ZeNorm skills: ${details}. Re-run with --force if this is intentional.`);
+    const agentLabel = agent === "*" ? "your agents" : agent;
+    const skillLines = existing
+        .map((skill) => typeof skill.path === "string"
+        ? `  • ${String(skill.name)}  (${skill.path})`
+        : `  • ${String(skill.name)}`)
+        .join("\n");
+    throw new CliError(`ZeNorm skills are already installed for ${agentLabel}:\n${skillLines}\n\n` +
+        `Leaving them as-is. To reinstall the bundled versions, re-run with --force.`);
 }
 function runSkillsInstaller(agent, project, force) {
     assertNoInstalledZeNormSkills(agent, project, force);

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 { maybeNotifyUpdate } from "./util/update-check.js";
+import { maybeSelfUpdate } from "./util/self-update.js";
 const helpText = `zenorm - ZeNorm CLI
 
 Usage:
@@ -73,8 +73,9 @@ async function main() {
     // speaks the Claude Code Stop-hook protocol on stdout/stderr and must emit
     // nothing else.
     if (commandName !== "session-check") {
-        // Fire-and-forget: never block or fail the command on the update check.
-        void maybeNotifyUpdate();
+        // 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

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

@@ -0,0 +1,25 @@
+/**
+ * Auto-upgrade the CLI in the background when a newer version is on npm.
+ *
+ * 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.
+ *
+ * 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.
+ *   - Not writable (system/Homebrew node, or a sudo-installed global) -> never
+ *     sudo; fall back to printing the manual upgrade command.
+ *
+ * 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`).
+ *
+ * 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).
+ */
+export declare function maybeSelfUpdate(): Promise<void>;
+//# sourceMappingURL=self-update.d.ts.map

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

@@ -0,0 +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"}

package/dist/util/self-update.js

@@ -0,0 +1,89 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+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";
+/**
+ * Auto-upgrade the CLI in the background when a newer version is on npm.
+ *
+ * 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.
+ *
+ * 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.
+ *   - Not writable (system/Homebrew node, or a sudo-installed global) -> never
+ *     sudo; fall back to printing the manual upgrade command.
+ *
+ * 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`).
+ *
+ * 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).
+ */
+export async function maybeSelfUpdate() {
+    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)
+            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,
+        });
+        // `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);
+            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);
+            return;
+        }
+        // Detached, non-blocking. Outlives this process; the upgrade lands for the
+        // next invocation. stdio ignored so it can't corrupt this command's output.
+        const child = spawn("npm", ["install", "-g", `${PACKAGE_NAME}@${update.latest}`], {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+        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.
+    }
+}
+function isWritable(dir) {
+    try {
+        accessSync(dir, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function printManualUpgrade(current, latest) {
+    log.warn(`A newer ZeNorm CLI is available (${current} -> ${latest}). Upgrade with: ${UPGRADE_COMMAND}`);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ze-norm/cli",
   "private": false,
-  "version": "0.8.0",
+  "version": "0.10.0",
   "license": "SEE LICENSE IN README.md",
   "type": "module",
   "repository": {
@@ -30,6 +30,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "global-directory": "^4.0.1",
+    "is-installed-globally": "^1.0.0",
     "skills": "1.5.10",
     "update-notifier": "^7.3.1"
   },

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

@@ -1,27 +0,0 @@
-/**
- * Passively check npm for a newer @ze-norm/cli and print a boxed notice when
- * one exists. This is the offline-from-the-API nudge layer: it works even
- * before `zenorm login` and on commands that never call the API. The
- * server-side gate (a 426 or the `x-zenorm-cli-upgrade` header) covers the
- * authenticated request path.
- *
- * update-notifier checks at most once per `updateCheckInterval`, runs the
- * actual registry lookup in a detached process (never blocking the command),
- * caches result in the user's XDG config dir, and self-suppresses in CI and
- * non-TTY environments. `notify()` writes to stderr, so it never corrupts a
- * command's stdout.
- *
- * Skipped for `session-check`: that command speaks the Claude Code Stop-hook
- * protocol on stdout, and a deferred boxen notice (printed via an exit hook) is
- * unwanted noise mid-hook. (stderr itself is safe there — session-check logs
- * diagnostics to stderr — but the notifier adds nothing useful in that path.)
- *
- * `update-notifier` is imported lazily (dynamic `import()`), not at module top.
- * The npm package ships only `dist`; its runtime deps live in node_modules of a
- * real install. A static top-level import would crash *every* invocation — even
- * `--help` — if the dep is ever absent (e.g. the published-tarball smoke test
- * runs `dist/index.js` with no node_modules). Lazy-loading inside the try/catch
- * keeps a missing or broken notifier strictly non-fatal.
- */
-export declare function maybeNotifyUpdate(): Promise<void>;
-//# sourceMappingURL=update-check.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../../src/util/update-check.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkBvD"}

package/dist/util/update-check.js

@@ -1,46 +0,0 @@
-import { getCliVersion } from "./package.js";
-const PACKAGE_NAME = "@ze-norm/cli";
-/**
- * Passively check npm for a newer @ze-norm/cli and print a boxed notice when
- * one exists. This is the offline-from-the-API nudge layer: it works even
- * before `zenorm login` and on commands that never call the API. The
- * server-side gate (a 426 or the `x-zenorm-cli-upgrade` header) covers the
- * authenticated request path.
- *
- * update-notifier checks at most once per `updateCheckInterval`, runs the
- * actual registry lookup in a detached process (never blocking the command),
- * caches result in the user's XDG config dir, and self-suppresses in CI and
- * non-TTY environments. `notify()` writes to stderr, so it never corrupts a
- * command's stdout.
- *
- * Skipped for `session-check`: that command speaks the Claude Code Stop-hook
- * protocol on stdout, and a deferred boxen notice (printed via an exit hook) is
- * unwanted noise mid-hook. (stderr itself is safe there — session-check logs
- * diagnostics to stderr — but the notifier adds nothing useful in that path.)
- *
- * `update-notifier` is imported lazily (dynamic `import()`), not at module top.
- * The npm package ships only `dist`; its runtime deps live in node_modules of a
- * real install. A static top-level import would crash *every* invocation — even
- * `--help` — if the dep is ever absent (e.g. the published-tarball smoke test
- * runs `dist/index.js` with no node_modules). Lazy-loading inside the try/catch
- * keeps a missing or broken notifier strictly non-fatal.
- */
-export async function maybeNotifyUpdate() {
-    try {
-        const { default: updateNotifier } = await import("update-notifier");
-        const notifier = updateNotifier({
-            pkg: { name: PACKAGE_NAME, version: getCliVersion() },
-            // Once per day is plenty for a CLI; the lookup is detached regardless.
-            updateCheckInterval: 1000 * 60 * 60 * 24,
-        });
-        notifier.notify({
-            defer: true,
-            message: "Update available {currentVersion} → {latestVersion}\nRun npm i -g " +
-                PACKAGE_NAME + "@latest to update",
-        });
-    }
-    catch {
-        // An update check must never break a real command — swallow any failure
-        // (offline, unwritable config dir, missing optional dep, etc.).
-    }
-}