@ze-norm/cli 0.5.0 → 0.7.0

package/dist/api/client.d.ts

@@ -1,3 +1,5 @@
+/** Suppress the soft "upgrade recommended" nudge for the rest of this process. */
+export declare function setQuietUpgradeNudges(): void;
 export interface ApiClientOptions {
     baseUrl?: string;
     token?: string;

package/dist/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA0BD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAgB;gBAEjB,IAAI,CAAC,EAAE,gBAAgB;IAKnC,OAAO,CAAC,UAAU;IAqBlB,OAAO,CAAC,cAAc;IAStB,2EAA2E;IAC3E,gBAAgB,IAAI,OAAO;YAIb,OAAO;IAwCf,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIjD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhD,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIlD,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIzC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;CAG7C"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAqBA,kFAAkF;AAClF,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA0BD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAgB;gBAEjB,IAAI,CAAC,EAAE,gBAAgB;IAKnC,OAAO,CAAC,UAAU;IA0BlB,OAAO,CAAC,cAAc;IAStB,2EAA2E;IAC3E,gBAAgB,IAAI,OAAO;YAIb,OAAO;IAsEf,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIjD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhD,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIlD,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIzC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;CAG7C"}

package/dist/api/client.js

@@ -1,8 +1,24 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { ApiError, AuthError } from "../util/errors.js";
+import { ApiError, AuthError, UpgradeRequiredError } from "../util/errors.js";
 import { resolveToken } from "../auth/store.js";
 import { PRODUCTION_API_URL } from "../config/defaults.js";
+import { getCliVersion } from "../util/package.js";
+import { log } from "../util/logger.js";
+const UPGRADE_COMMAND = "npm install -g @ze-norm/cli@latest";
+// Print the "an upgrade is recommended" nudge at most once per process, even
+// when a single command makes several API calls. The server sets the
+// `x-zenorm-cli-upgrade: recommended` header on success when this CLI is below
+// the recommended (but at/above the supported) version.
+let recommendedNudgeShown = false;
+// `session-check` runs as a Claude Code Stop hook; an unsolicited upgrade
+// warning mid-hook is noise. It calls this to suppress the soft nudge (the
+// 426 hard-block still applies — a truly unsupported CLI must not run).
+let quietUpgradeNudges = false;
+/** Suppress the soft "upgrade recommended" nudge for the rest of this process. */
+export function setQuietUpgradeNudges() {
+    quietUpgradeNudges = true;
+}
 function resolveBaseUrl(explicit) {
     // 1. Explicit option
     if (explicit)
@@ -32,6 +48,11 @@ export class ZenormClient {
     getHeaders() {
         const headers = {
             "Content-Type": "application/json",
+            // Always advertise the CLI version so the API can gate stale clients
+            // (426 below the supported floor) and nudge near-stale ones (a warning
+            // header below the recommended version). Sent on every request,
+            // authenticated or dev-bypassed.
+            "x-zenorm-cli-version": getCliVersion(),
         };
         if (this.token) {
             headers["Authorization"] = `Bearer ${this.token}`;
@@ -81,6 +102,31 @@ export class ZenormClient {
         if (res.status === 401) {
             throw new AuthError("Authentication required. Run `zenorm login` first.");
         }
+        // 426 Upgrade Required: this CLI is below the API's supported version
+        // floor. Surface the server's reason (if any) plus the upgrade command and
+        // stop — retrying the same binary cannot succeed.
+        if (res.status === 426) {
+            let serverMessage = null;
+            try {
+                const body = (await res.json());
+                if (typeof body.message === "string")
+                    serverMessage = body.message;
+            }
+            catch {
+                // body may not be JSON
+            }
+            const reason = serverMessage ??
+                `Your ZeNorm CLI (${getCliVersion()}) is no longer supported by the server.`;
+            throw new UpgradeRequiredError(`${reason}\n\nUpgrade with:\n  ${UPGRADE_COMMAND}`);
+        }
+        // A successful response may still carry a soft upgrade nudge: the CLI is
+        // below the recommended version but at/above the supported floor.
+        if (res.headers.get("x-zenorm-cli-upgrade") === "recommended" &&
+            !recommendedNudgeShown &&
+            !quietUpgradeNudges) {
+            recommendedNudgeShown = true;
+            log.warn(`A newer ZeNorm CLI is available (you have ${getCliVersion()}). Upgrade with: ${UPGRADE_COMMAND}`);
+        }
         if (!res.ok) {
             let responseBody = null;
             try {

package/dist/commands/session-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-check.d.ts","sourceRoot":"","sources":["../../src/commands/session-check.ts"],"names":[],"mappings":"AA2CA;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqFxE"}
+{"version":3,"file":"session-check.d.ts","sourceRoot":"","sources":["../../src/commands/session-check.ts"],"names":[],"mappings":"AA2CA;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFxE"}

package/dist/commands/session-check.js

@@ -1,6 +1,6 @@
 import { readFileSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { ZenormClient } from "../api/client.js";
+import { ZenormClient, setQuietUpgradeNudges } from "../api/client.js";
 import { log } from "../util/logger.js";
 /**
  * Checks whether the session transcript references zenorm task work.
@@ -82,6 +82,8 @@ export async function sessionCheckCommand(_argv) {
         process.exit(0);
     }
     try {
+        // Stop-hook context: keep the soft upgrade nudge quiet (a 426 still blocks).
+        setQuietUpgradeNudges();
         const client = new ZenormClient();
         const { tasks } = await client.get(`/v1/specs/${config.specId}/tasks`);
         const activeTasks = tasks.filter((t) => t.status === "active");

package/dist/index.js

@@ -10,6 +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";
 const helpText = `zenorm - ZeNorm CLI
 
 Usage:
@@ -68,6 +69,13 @@ 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: never block or fail the command on the update check.
+        void maybeNotifyUpdate();
+    }
     // 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/errors.d.ts

@@ -10,4 +10,12 @@ export declare class ApiError extends CliError {
 export declare class AuthError extends CliError {
     constructor(message: string);
 }
+/**
+ * The API rejected this CLI with 426 Upgrade Required: the installed version is
+ * below the server's supported floor. The message carries the upgrade command;
+ * retrying the same binary cannot succeed.
+ */
+export declare class UpgradeRequiredError extends CliError {
+    constructor(message: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/util/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/util/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,QAAS,SAAQ,KAAK;IAGxB,QAAQ,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACR,QAAQ,GAAE,MAAU;CAK9B;AAED,qBAAa,QAAS,SAAQ,QAAQ;IAG3B,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,OAAO;gBAFpB,OAAO,EAAE,MAAM,EACR,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO;CAKvB;AAED,qBAAa,SAAU,SAAQ,QAAQ;gBACzB,OAAO,EAAE,MAAM;CAI5B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/util/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,QAAS,SAAQ,KAAK;IAGxB,QAAQ,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACR,QAAQ,GAAE,MAAU;CAK9B;AAED,qBAAa,QAAS,SAAQ,QAAQ;IAG3B,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,OAAO;gBAFpB,OAAO,EAAE,MAAM,EACR,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO;CAKvB;AAED,qBAAa,SAAU,SAAQ,QAAQ;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;gBACpC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/util/errors.js

@@ -22,3 +22,14 @@ export class AuthError extends CliError {
         this.name = "AuthError";
     }
 }
+/**
+ * The API rejected this CLI with 426 Upgrade Required: the installed version is
+ * below the server's supported floor. The message carries the upgrade command;
+ * retrying the same binary cannot succeed.
+ */
+export class UpgradeRequiredError extends CliError {
+    constructor(message) {
+        super(message, 1);
+        this.name = "UpgradeRequiredError";
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * 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

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

@@ -0,0 +1,46 @@
+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.).
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ze-norm/cli",
   "private": false,
-  "version": "0.5.0",
+  "version": "0.7.0",
   "license": "SEE LICENSE IN README.md",
   "type": "module",
   "repository": {
@@ -30,10 +30,12 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "skills": "1.5.10"
+    "skills": "1.5.10",
+    "update-notifier": "^7.3.1"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",
+    "@types/update-notifier": "^6.0.8",
     "@zenorm/eslint-config": "workspace:*",
     "@zenorm/tsconfig": "workspace:*",
     "eslint": "^9.25.1",