@ze-norm/cli 0.4.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/auth/device-flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"device-flow.d.ts","sourceRoot":"","sources":["../../src/auth/device-flow.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAuKpD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAkDpE"}
+{"version":3,"file":"device-flow.d.ts","sourceRoot":"","sources":["../../src/auth/device-flow.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA+RpD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAkDpE"}

package/dist/auth/device-flow.js

@@ -4,7 +4,7 @@ import { exec } from "node:child_process";
 import { platform } from "node:os";
 import { URL, URLSearchParams } from "node:url";
 import { log } from "../util/logger.js";
-import { CLI_CALLBACK_PORTS, PRODUCTION_CLERK_CLIENT_ID, PRODUCTION_CLERK_ISSUER, } from "../config/defaults.js";
+import { CLI_CALLBACK_PORTS, PRODUCTION_CLERK_CLIENT_ID, PRODUCTION_CLERK_ISSUER, PRODUCTION_WEB_URL, } from "../config/defaults.js";
 /**
  * Find the first pre-registered callback port that is free to bind. Clerk
  * matches redirect_uris exactly, so the local listener must use one of the
@@ -28,6 +28,19 @@ async function pickFreeCallbackPort() {
 function getClerkIssuer() {
     return process.env["ZENORM_CLERK_ISSUER"] ?? PRODUCTION_CLERK_ISSUER;
 }
+/** Where the browser tab lands after a successful login. */
+function getWebUrl() {
+    return process.env["ZENORM_WEB_URL"] ?? PRODUCTION_WEB_URL;
+}
+/** Escape user-influenced text before interpolating into the result page HTML. */
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
 function getClerkClientId() {
     return (process.env["ZENORM_CLERK_CLIENT_ID"] ??
         process.env["VITE_CLERK_PUBLISHABLE_KEY"] ??
@@ -62,6 +75,100 @@ function tryOpenBrowser(url) {
         }
     });
 }
+/**
+ * Render a self-contained, branded error page for the localhost callback.
+ *
+ * Only the failure paths render a page — a successful login 302-redirects the
+ * browser into the app instead. Served by the raw `http` server (no
+ * React/bundler available), so the page is fully inline: dark theme, ZeNorm
+ * wordmark, and the same card framing the web app uses on /sign-in.
+ */
+function renderCallbackPage(heading, body) {
+    const accent = "#f87171";
+    const glyph = "&#33;";
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>ZeNorm CLI &middot; ${heading}</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    min-height: 100vh;
+    display: grid;
+    place-items: center;
+    padding: 24px;
+    background:
+      radial-gradient(ellipse 540px 360px at 50% 38%, rgba(99,102,241,0.16), transparent 70%),
+      #0a0a0b;
+    color: #ededee;
+    font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI",
+      Roboto, Helvetica, Arial, sans-serif;
+    -webkit-font-smoothing: antialiased;
+  }
+  .card {
+    position: relative;
+    width: 100%;
+    max-width: 380px;
+    border: 1px solid rgba(255,255,255,0.10);
+    border-radius: 12px;
+    background: rgba(20,20,22,0.72);
+    backdrop-filter: blur(6px);
+    box-shadow: 0 1px 0 rgba(255,255,255,0.04) inset,
+      0 28px 70px -32px rgba(0,0,0,0.6);
+    padding: 40px 28px 32px;
+    text-align: center;
+  }
+  .eyebrow {
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 10px;
+    letter-spacing: 0.22em;
+    text-transform: uppercase;
+    color: rgba(237,237,238,0.55);
+    margin-bottom: 22px;
+  }
+  .badge {
+    width: 48px; height: 48px;
+    margin: 0 auto 20px;
+    display: grid; place-items: center;
+    border-radius: 999px;
+    border: 1px solid ${accent}55;
+    background: ${accent}1a;
+    color: ${accent};
+    font-size: 22px; font-weight: 600;
+    line-height: 1;
+  }
+  h1 {
+    margin: 0 0 8px;
+    font-size: 1.5rem;
+    letter-spacing: -0.01em;
+    font-weight: 600;
+  }
+  p { margin: 0; color: rgba(237,237,238,0.62); font-size: 0.9rem; line-height: 1.5; }
+  .footer {
+    margin-top: 24px;
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 10px;
+    letter-spacing: 0.18em;
+    text-transform: uppercase;
+    color: rgba(237,237,238,0.4);
+  }
+</style>
+</head>
+<body>
+  <div class="card">
+    <div class="eyebrow">ZeNorm CLI</div>
+    <div class="badge">${glyph}</div>
+    <h1>${heading}</h1>
+    <p>${body}</p>
+    <div class="footer">Spec authoring, traced end-to-end</div>
+  </div>
+</body>
+</html>`;
+}
 /**
  * Start a localhost HTTP server and wait for the OAuth callback.
  * Resolves with the authorization code once the redirect arrives.
@@ -80,21 +187,26 @@ function waitForCallback(port, expectedState) {
             const error = url.searchParams.get("error");
             if (error) {
                 const desc = url.searchParams.get("error_description") ?? error;
-                res.writeHead(200, { "Content-Type": "text/html" });
-                res.end(`<html><body><h2>Login failed</h2><p>${desc}</p><p>You can close this tab.</p></body></html>`);
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(renderCallbackPage("Login failed", `${escapeHtml(desc)}. You can close this tab and try again.`));
                 server.close();
                 reject(new Error(`Authorization failed: ${desc}`));
                 return;
             }
             if (!code || state !== expectedState) {
-                res.writeHead(400, { "Content-Type": "text/html" });
-                res.end(`<html><body><h2>Invalid callback</h2><p>Missing code or state mismatch.</p></body></html>`);
+                res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(renderCallbackPage("Invalid callback", "Missing code or state mismatch. You can close this tab and try again."));
                 server.close();
                 reject(new Error("Invalid callback: missing code or state mismatch"));
                 return;
             }
-            res.writeHead(200, { "Content-Type": "text/html" });
-            res.end(`<html><body><h2>Login successful!</h2><p>You can close this tab and return to your terminal.</p></body></html>`);
+            // No standalone success page — send the browser straight into the app
+            // (the user is already signed in), so the tab lands on the real product
+            // instead of a "you can close this tab" interstitial. The CLI reports
+            // success in the terminal. Errors still render the branded page below,
+            // since those can't sensibly drop the user into the dashboard.
+            res.writeHead(302, { Location: `${getWebUrl()}/dashboard` });
+            res.end();
             server.close();
             resolve(code);
         });

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/config/defaults.d.ts

@@ -1,5 +1,6 @@
 export declare const PRODUCTION_API_URL = "https://api.zenorm.com";
 export declare const PRODUCTION_CLERK_ISSUER = "https://clerk.zenorm.com";
+export declare const PRODUCTION_WEB_URL = "https://zenorm.com";
 export declare const PRODUCTION_CLERK_CLIENT_ID = "nUFCpxIFWJ4YSB3A";
 export declare const CLI_CALLBACK_PORTS: readonly [4571, 4572, 4573];
 //# sourceMappingURL=defaults.d.ts.map

package/dist/config/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,2BAA2B,CAAC;AAC3D,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAKlE,eAAO,MAAM,0BAA0B,qBAAqB,CAAC;AAK7D,eAAO,MAAM,kBAAkB,6BAA8B,CAAC"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,2BAA2B,CAAC;AAC3D,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAIlE,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAWvD,eAAO,MAAM,0BAA0B,qBAAqB,CAAC;AAK7D,eAAO,MAAM,kBAAkB,6BAA8B,CAAC"}

package/dist/config/defaults.js

@@ -1,9 +1,19 @@
 export const PRODUCTION_API_URL = "https://api.zenorm.com";
 export const PRODUCTION_CLERK_ISSUER = "https://clerk.zenorm.com";
+// Prod web app. After a successful login the localhost callback 302-redirects
+// the browser here so the tab lands on the real product (already signed in)
+// instead of a standalone "you can close this tab" page.
+export const PRODUCTION_WEB_URL = "https://zenorm.com";
 // Clerk OAuth Application client id for the public CLI (prod instance
 // clerk.zenorm.com). NOT the publishable key — this is the OAuth 2.0 client id
 // from the "ZeNorm CLI" OAuth app. Its registered redirect_uris are the fixed
 // localhost callback ports in CLI_CALLBACK_PORTS below.
+//
+// NOTE: this OAuth app has `consent_screen_enabled` set to FALSE out-of-band on
+// the Clerk instance (via the Clerk Backend API, not tracked in this repo).
+// That is what lets an already-signed-in `zenorm login` skip Clerk's OAuth
+// consent screen and redirect straight to the localhost callback. To restore
+// the consent screen, PATCH the OAuth app back to `consent_screen_enabled:true`.
 export const PRODUCTION_CLERK_CLIENT_ID = "nUFCpxIFWJ4YSB3A";
 // Fixed localhost callback ports the device-auth flow binds, in order. Clerk
 // enforces exact redirect_uri matching, so these MUST stay in sync with the

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.4.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",