@zeroxyz/cli 0.0.34 → 0.0.36

package/dist/index.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 
-// src/app.ts
-import { Command as Command12 } from "commander";
+// src/index.ts
+import { homedir as homedir7 } from "os";
+import { join as join8 } from "path";
 
 // package.json
 var package_default = {
   name: "@zeroxyz/cli",
-  version: "0.0.34",
+  version: "0.0.36",
   type: "module",
   bin: {
     zero: "dist/index.js",
@@ -59,6 +60,9 @@ var package_default = {
   }
 };
 
+// src/app.ts
+import { Command as Command12 } from "commander";
+
 // src/commands/bug-report-command.ts
 import { createHash as createHash2 } from "crypto";
 import { readFileSync } from "fs";
@@ -77,6 +81,7 @@ var searchResultSchema = z.object({
   description: z.string(),
   whatItDoes: z.string().nullable().optional(),
   url: z.string(),
+  urlTemplate: z.string().nullable().optional(),
   cost: z.object({ amount: z.string(), asset: z.string() }),
   rating: z.object({
     score: z.string(),
@@ -103,6 +108,7 @@ var capabilityResponseSchema = z.object({
   name: z.string(),
   description: z.string(),
   url: z.string(),
+  urlTemplate: z.string().nullable().optional(),
   method: z.string(),
   headers: z.record(z.string(), z.string()).nullable(),
   bodySchema: z.record(z.string(), z.unknown()).nullable(),
@@ -617,6 +623,7 @@ var configCommand = (_appContext) => new Command2("config").description("View or
 });
 
 // src/commands/fetch-command.ts
+import { createHash as createHash3 } from "crypto";
 import { readFileSync as readFileSync3 } from "fs";
 import { resolve as resolvePath } from "path";
 import { Command as Command3 } from "commander";
@@ -740,6 +747,7 @@ var pickSessionCloseAmount = (receipt, openTimeCumulative) => {
   const accepted = BigInt(receipt.acceptedCumulative);
   const spent = BigInt(receipt.spent);
   const fromReceipt = accepted > spent ? accepted : spent;
+  if (receipt.metered === true) return fromReceipt;
   return fromReceipt > openTimeCumulative ? fromReceipt : openTimeCumulative;
 };
 var PaymentService = class {
@@ -1206,6 +1214,22 @@ var truncateQuery = (raw) => raw.length > QUERY_MAX ? `${raw.slice(0, QUERY_MAX)
 var truncateError = (raw) => raw.length > ERROR_MAX ? `${raw.slice(0, ERROR_MAX)}\u2026` : raw;
 
 // src/commands/fetch-command.ts
+var sniffJsonShape = (buf) => {
+  let i = 0;
+  if (buf.length >= 3 && buf[0] === 239 && buf[1] === 187 && buf[2] === 191) {
+    i = 3;
+  }
+  while (i < buf.length && (buf[i] === 32 || buf[i] === 9 || buf[i] === 10 || buf[i] === 13)) {
+    i++;
+  }
+  if (i >= buf.length) return false;
+  return buf[i] === 123 || buf[i] === 91;
+};
+var urlMatchesTemplate = (url, template) => {
+  const escaped = template.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const withCaptures = escaped.replace(/\\\{[^/\\}]+\\\}/g, "[^/]+");
+  return new RegExp(`^${withCaptures}$`).test(url);
+};
 var isTextContentType = (contentType) => {
   if (!contentType) return true;
   const ct = contentType.toLowerCase().split(";")[0]?.trim() ?? "";
@@ -1325,6 +1349,7 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
       const startTime = Date.now();
       let resolvedUrl;
       let resolvedMethodFromCapability;
+      let resolvedCapabilityName;
       if (!url) {
         if (!options.capability) {
           console.error(
@@ -1337,6 +1362,7 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
           const cap = await apiService.getCapability(options.capability);
           resolvedUrl = cap.url;
           resolvedMethodFromCapability = cap.method;
+          resolvedCapabilityName = cap.name;
         } catch (err) {
           console.error(
             `Failed to resolve --capability ${options.capability}: ${err instanceof Error ? err.message : String(err)}`
@@ -1347,6 +1373,47 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
       } else {
         resolvedUrl = url;
       }
+      if (!url && options.capability && !stateService.findSearchContextByCapability(options.capability)) {
+        try {
+          let capName = resolvedCapabilityName;
+          if (capName === void 0) {
+            const cap = await apiService.getCapability(options.capability);
+            capName = cap.name;
+          }
+          const searchResult = await apiService.search({ query: capName });
+          const slugFoundInResults = searchResult.capabilities.some(
+            (c) => c.slug === options.capability || c.id === options.capability
+          );
+          stateService.saveLastSearch({
+            searchId: searchResult.searchId,
+            capabilities: searchResult.capabilities.map((c) => ({
+              position: c.position,
+              id: c.id,
+              url: c.url,
+              urlTemplate: c.urlTemplate ?? null,
+              displayCostAmount: c.cost.amount
+            }))
+          });
+          analyticsService.capture("search_executed", {
+            query: truncateQuery(capName),
+            queryLength: capName.length,
+            resultCount: searchResult.capabilities.length,
+            searchId: searchResult.searchId,
+            total: searchResult.total,
+            hasMore: searchResult.hasMore,
+            json: false,
+            triggeredBy: "slug_handoff",
+            slugFoundInResults
+          });
+          analyticsService.capture("capability_viewed", {
+            capabilityId: options.capability,
+            fromLastSearch: false,
+            searchId: searchResult.searchId,
+            triggeredBy: "slug_handoff"
+          });
+        } catch {
+        }
+      }
       let resolvedBody;
       try {
         resolvedBody = resolveRequestBody(
@@ -1354,9 +1421,13 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
           options.dataStdin ?? false
         );
       } catch (err) {
-        console.error(
-          err instanceof Error ? err.message : "Failed to read request body"
-        );
+        const message = err instanceof Error ? err.message : "Failed to read request body";
+        analyticsService.capture("fetch_error", {
+          cliErrorClass: /exceeds the .* byte limit/.test(message) ? "payload_too_large" : "schema_validation_failed",
+          url: redactUrl(resolvedUrl),
+          error: truncateError(message)
+        });
+        console.error(message);
         process.exitCode = 1;
         return;
       }
@@ -1373,7 +1444,7 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         (k) => k.toLowerCase() === "content-type"
       );
       if (resolvedBody && !hasContentType) {
-        headers["content-type"] = Buffer.isBuffer(resolvedBody) ? "application/octet-stream" : "application/json";
+        headers["content-type"] = Buffer.isBuffer(resolvedBody) ? sniffJsonShape(resolvedBody) ? "application/json" : "application/octet-stream" : "application/json";
       }
       const log = (msg) => console.error(`  ${msg}`);
       const method = options.method ? options.method.toUpperCase() : resolvedMethodFromCapability && !resolvedBody ? resolvedMethodFromCapability.toUpperCase() : resolvedBody ? "POST" : "GET";
@@ -1382,12 +1453,21 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         headers,
         body: resolvedBody
       };
-      const lastSearch = stateService.loadLastSearch();
-      const matchedCapability = lastSearch?.capabilities.find(
-        (c) => resolvedUrl.startsWith(c.url)
-      );
-      const capabilityId = options.capability ?? matchedCapability?.id ?? null;
-      const searchId = matchedCapability ? lastSearch?.searchId : void 0;
+      const explicitCapabilityCtx = options.capability ? stateService.findSearchContextByCapability(options.capability) : null;
+      const urlCtx = stateService.findSearchContextByUrl(resolvedUrl, {
+        matchTemplate: (template) => {
+          try {
+            return urlMatchesTemplate(resolvedUrl, template);
+          } catch {
+            return false;
+          }
+        }
+      });
+      const matchCtx = explicitCapabilityCtx ?? urlCtx;
+      const capabilityId = options.capability ?? matchCtx?.capabilityId ?? null;
+      const searchId = matchCtx?.searchId;
+      const resultRank = matchCtx?.resultRank;
+      const matchedDisplayCostAmount = matchCtx?.displayCostAmount;
       const skipReasons = [];
       if (!apiService.walletAddress) {
         skipReasons.push(
@@ -1398,6 +1478,19 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         skipReasons.push(
           "no capability resolved \u2014 pass --capability <uid|slug> or run `zero search` first so the URL can be matched"
         );
+        if (!options.capability) {
+          const lastSearch = stateService.loadLastSearch();
+          const cached = lastSearch?.capabilities ?? [];
+          analyticsService.capture("capability_resolution_missed", {
+            url: redactUrl(resolvedUrl),
+            method,
+            hasLastSearch: lastSearch !== null,
+            lastSearchSize: cached.length,
+            lastSearchHasTemplates: cached.some(
+              (c) => Boolean(c.urlTemplate)
+            )
+          });
+        }
       }
       let finalResponse;
       let bodyBytes;
@@ -1420,7 +1513,7 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
             paymentReq,
             options.maxPay,
             log,
-            matchedCapability?.displayCostAmount
+            matchedDisplayCostAmount
           );
           finalResponse = result.response;
           paymentMeta = {
@@ -1517,6 +1610,15 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         } catch {
         }
       }
+      const status = finalResponse?.status;
+      const isFailure = !finalResponse || typeof status === "number" && (status < 200 || status >= 300);
+      let errorSnippetHash;
+      let errorSnippetLength;
+      if (isFailure && body && !bodyIsBinary) {
+        const snippet = body.slice(0, 500);
+        errorSnippetHash = createHash3("sha256").update(snippet).digest("hex");
+        errorSnippetLength = snippet.length;
+      }
       let runId = null;
       if (capabilityId && apiService.walletAddress) {
         let requestSchema;
@@ -1541,6 +1643,8 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
             latencyMs,
             requestSchema,
             responseSchema,
+            errorSnippetHash,
+            errorSnippetLength,
             ...paymentMeta && {
               costAmount: paymentMeta.amount,
               costAsset: paymentMeta.asset,
@@ -1557,7 +1661,6 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
           );
         }
       }
-      const status = finalResponse?.status;
       const outcome = !finalResponse ? "network_error" : status === 402 && !paymentMeta ? "payment_failed" : status !== void 0 && status >= 400 && status !== 402 ? "server_error" : "success";
       analyticsService.capture("fetch_executed", {
         url: redactUrl(resolvedUrl),
@@ -1569,10 +1672,26 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         paymentAmount: paymentMeta?.amount,
         capabilityId: capabilityId ?? void 0,
         searchId: searchId ?? void 0,
+        resultRank: resultRank ?? void 0,
         runId: runId ?? void 0,
         runTracked: !!runId,
         ...fetchError && { error: truncateError(fetchError.message) }
       });
+      const isFetchFailure = Boolean(fetchError) || !finalResponse || typeof status === "number" && (status < 200 || status >= 300);
+      if (isFetchFailure) {
+        const cliErrorClass = fetchError || !finalResponse ? "network" : !apiService.walletAddress ? "auth_missing" : "unknown";
+        analyticsService.capture("fetch_error", {
+          cliErrorClass,
+          capabilityId: capabilityId ?? void 0,
+          searchId: searchId ?? void 0,
+          resultRank: resultRank ?? void 0,
+          url: redactUrl(resolvedUrl),
+          error: truncateError(
+            fetchError?.message ?? skipReasons.join("; ")
+          ),
+          skippedRun: !runId && skipReasons.length > 0
+        });
+      }
       if (fetchError && !options.json) {
         console.error(`  Fetch failed: ${fetchError.message}`);
       }
@@ -1639,7 +1758,16 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         process.exitCode = 1;
       }
     } catch (err) {
-      console.error(err instanceof Error ? err.message : "Fetch failed");
+      const message = err instanceof Error ? err.message : "Fetch failed";
+      try {
+        appContext.services.analyticsService.capture("fetch_error", {
+          cliErrorClass: "unknown",
+          url: url ? redactUrl(url) : "unknown",
+          error: truncateError(message)
+        });
+      } catch {
+      }
+      console.error(message);
       process.exitCode = 1;
     }
   }
@@ -1855,6 +1983,8 @@ var getCommand = (appContext) => new Command4("get").description(
       searchId = lastSearch.searchId;
     } else {
       capabilityId = identifier;
+      const ctx = stateService.findSearchContextByCapability(identifier);
+      if (ctx) searchId = ctx.searchId;
     }
     const capability = await apiService.getCapability(
       capabilityId,
@@ -1878,7 +2008,7 @@ var getCommand = (appContext) => new Command4("get").description(
 });
 
 // src/commands/init-command.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import {
   chmodSync as chmodSync2,
   existsSync as existsSync2,
@@ -1952,10 +2082,12 @@ var color = {
   magenta: (s) => wrap("35", s),
   green: (s) => wrap("32", s),
   yellow: (s) => wrap("33", s),
+  red: (s) => wrap("31", s),
   gray: (s) => wrap("90", s),
   boldCyan: (s) => wrap("1;36", s),
   boldMagenta: (s) => wrap("1;35", s),
-  boldGreen: (s) => wrap("1;32", s)
+  boldGreen: (s) => wrap("1;32", s),
+  boldRed: (s) => wrap("1;31", s)
 };
 var printZeroBanner = () => {
   console.log("");
@@ -1998,12 +2130,16 @@ var printReadyFooter = () => {
   const lines = [
     "",
     `  ${color.boldGreen("Zero is ready!")} Zero works best with an AI agent.`,
-    "  Open Claude Code, Codex, Cursor, Blackbox, or your agent of choice",
-    "  and try one of these commands to get started:",
+    `  Open ${color.boldRed("Claude Code")}, Codex, Cursor, Blackbox, or your agent of choice`,
+    "  and try this prompt to get started:",
     "",
-    `    ${color.cyan('zero search "translate text to Spanish"')}`,
-    `    ${color.cyan('zero search "generate an image"')}`,
-    `    ${color.cyan('zero search "weather forecast"')}`,
+    `    ${color.cyan("What is zero and how do I use it?")}`,
+    "",
+    "  You can also just tell your agent examples of what you are trying to do:",
+    "",
+    `    ${color.cyan("Can you use zero to deploy an NYC weather website")}`,
+    `    ${color.cyan("Email me an image of a crystalline rocket ship with zero")}`,
+    `    ${color.cyan("Create a demo video with real voiceover for my project using zero")}`,
     "",
     `  ${color.dim("By using Zero, you agree to our Terms of Service:")}`,
     `    ${color.dim("https://zero.xyz/terms-of-service")}`,
@@ -2059,7 +2195,7 @@ var getCliModuleDir = () => {
   }
   return __dirname;
 };
-var sha256File = (filePath) => createHash3("sha256").update(readFileSync4(filePath)).digest("hex");
+var sha256File = (filePath) => createHash4("sha256").update(readFileSync4(filePath)).digest("hex");
 var verifyFileCopy = (src, dest) => {
   if (!existsSync2(dest)) return false;
   return sha256File(src) === sha256File(dest);
@@ -2913,6 +3049,7 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
           position: c.position,
           id: c.id,
           url: c.url,
+          urlTemplate: c.urlTemplate ?? null,
           displayCostAmount: c.cost.amount
         }))
       });
@@ -3287,7 +3424,11 @@ var AnalyticsService = class {
     this.posthog = new PostHog(POSTHOG_API_KEY, {
       host: POSTHOG_HOST,
       flushAt: 1,
-      flushInterval: 0
+      flushInterval: 0,
+      // Vitest spins up many AnalyticsService instances per process; each
+      // autocapture listener adds to process.{uncaughtException,unhandledRejection}
+      // and trips Node's MaxListeners warning. Real CLI is one instance per process.
+      enableExceptionAutocapture: !process.env.VITEST
     });
     this.posthog.on("error", () => {
     });
@@ -3346,6 +3487,22 @@ var AnalyticsService = class {
       }
     });
   }
+  captureException(error, properties) {
+    if (!this.posthog) return;
+    this.posthog.captureException(error, this.distinctId, {
+      source: "cli",
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      cli_version: this.cliVersion,
+      environment: this.environment,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      wallet_address: this.walletAddress,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      request_id: this.requestId,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      agent_host: this.agentHost,
+      ...properties
+    });
+  }
   async shutdown() {
     if (!this.posthog) return;
     try {
@@ -3358,15 +3515,27 @@ var AnalyticsService = class {
 // src/services/state-service.ts
 import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "fs";
 import { join as join5 } from "path";
+var RECENT_SEARCH_LIMIT = 10;
 var StateService = class {
   constructor(zeroDir) {
     this.zeroDir = zeroDir;
     this.lastSearchPath = join5(zeroDir, "last_search.json");
+    this.recentSearchesPath = join5(zeroDir, "recent_searches.json");
   }
   lastSearchPath;
+  recentSearchesPath;
   saveLastSearch = (data) => {
     mkdirSync5(this.zeroDir, { recursive: true });
     writeFileSync5(this.lastSearchPath, JSON.stringify(data, null, 2));
+    const recent = this.loadRecentSearches();
+    const filtered = recent.searches.filter(
+      (s) => s.searchId !== data.searchId
+    );
+    const next = [data, ...filtered].slice(0, RECENT_SEARCH_LIMIT);
+    writeFileSync5(
+      this.recentSearchesPath,
+      JSON.stringify({ searches: next }, null, 2)
+    );
   };
   loadLastSearch = () => {
     try {
@@ -3377,6 +3546,63 @@ var StateService = class {
       return null;
     }
   };
+  loadRecentSearches = () => {
+    try {
+      if (!existsSync6(this.recentSearchesPath)) {
+        const last = this.loadLastSearch();
+        return { searches: last ? [last] : [] };
+      }
+      const raw = readFileSync9(this.recentSearchesPath, "utf8");
+      const parsed = JSON.parse(raw);
+      return { searches: parsed.searches ?? [] };
+    } catch {
+      return { searches: [] };
+    }
+  };
+  // Walk recent searches newest-first, returning the first one whose
+  // results contain `capabilityId` (uid or slug match). Preferred over
+  // "loadLastSearch" for attributing rank — handles the parallel-search
+  // case where the most recent search isn't the one being fetched.
+  findSearchContextByCapability = (capabilityId) => {
+    const recent = this.loadRecentSearches();
+    for (const search of recent.searches) {
+      const entry = search.capabilities.find((c) => c.id === capabilityId);
+      if (entry) {
+        return {
+          searchId: search.searchId,
+          resultRank: entry.position,
+          capabilityId: entry.id,
+          url: entry.url,
+          displayCostAmount: entry.displayCostAmount
+        };
+      }
+    }
+    return null;
+  };
+  // URL-based attribution for `zero fetch <url>`. Matches by URL prefix
+  // (some capabilities accept query params or path tails the agent appends)
+  // across the recent ring, newest match wins. Falls back to a caller-
+  // supplied urlTemplate matcher (ADS-509 path-parameterized URLs).
+  findSearchContextByUrl = (url, options) => {
+    const recent = this.loadRecentSearches();
+    for (const search of recent.searches) {
+      const prefixHit = search.capabilities.find((c) => url.startsWith(c.url));
+      const templateHit = prefixHit ?? search.capabilities.find(
+        (c) => c.urlTemplate && options?.matchTemplate ? options.matchTemplate(c.urlTemplate) : false
+      );
+      const entry = templateHit;
+      if (entry) {
+        return {
+          searchId: search.searchId,
+          resultRank: entry.position,
+          capabilityId: entry.id,
+          url: entry.url,
+          displayCostAmount: entry.displayCostAmount
+        };
+      }
+    }
+    return null;
+  };
 };
 
 // src/services/wallet-service.ts
@@ -3483,6 +3709,155 @@ var createAppContext = () => {
   };
 };
 
+// src/util/update-check.ts
+import {
+  existsSync as existsSync8,
+  lstatSync,
+  mkdirSync as mkdirSync6,
+  readFileSync as readFileSync11,
+  readlinkSync,
+  writeFileSync as writeFileSync6
+} from "fs";
+import { homedir as homedir6 } from "os";
+import { dirname as dirname3, join as join7, resolve } from "path";
+var CACHE_FILENAME = "update_check.json";
+var NPM_REGISTRY_URL = "https://registry.npmjs.org/@zeroxyz/cli/latest";
+var CHECK_INTERVAL_MS = 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 3e3;
+var emptyCache = {
+  lastCheckedMs: 0,
+  latestVersion: null,
+  lastShownMs: 0
+};
+var resolveExecPath = (execPath) => {
+  try {
+    const stat = lstatSync(execPath);
+    if (stat.isSymbolicLink()) {
+      const target = readlinkSync(execPath);
+      return resolve(dirname3(execPath), target);
+    }
+  } catch {
+  }
+  return execPath;
+};
+var detectInstallMethod = (opts = {}) => {
+  const execPath = opts.execPath ?? process.execPath;
+  const pkg = opts.pkg ?? process.pkg;
+  const home = opts.home ?? homedir6();
+  if (pkg) return "binary";
+  const resolved = resolveExecPath(execPath);
+  const zeroBin = join7(home, ".zero", "bin");
+  if (resolved.startsWith(zeroBin)) return "binary";
+  return "npm";
+};
+var compareVersions = (a, b) => {
+  const parse = (v) => {
+    const dashIdx = v.indexOf("-");
+    const base2 = dashIdx === -1 ? v : v.slice(0, dashIdx);
+    const pre = dashIdx === -1 ? null : v.slice(dashIdx + 1);
+    const nums = base2.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    while (nums.length < 3) nums.push(0);
+    return { nums, pre };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const na = pa.nums[i] ?? 0;
+    const nb = pb.nums[i] ?? 0;
+    if (na !== nb) return na - nb;
+  }
+  if (pa.pre === pb.pre) return 0;
+  if (pa.pre === null) return 1;
+  if (pb.pre === null) return -1;
+  return pa.pre < pb.pre ? -1 : 1;
+};
+var cachePath = (zeroDir) => join7(zeroDir, CACHE_FILENAME);
+var readCache = (zeroDir) => {
+  try {
+    const path = cachePath(zeroDir);
+    if (!existsSync8(path)) return emptyCache;
+    const raw = readFileSync11(path, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      lastCheckedMs: typeof parsed.lastCheckedMs === "number" ? parsed.lastCheckedMs : 0,
+      latestVersion: typeof parsed.latestVersion === "string" ? parsed.latestVersion : null,
+      lastShownMs: typeof parsed.lastShownMs === "number" ? parsed.lastShownMs : 0
+    };
+  } catch {
+    return emptyCache;
+  }
+};
+var writeCache = (zeroDir, cache) => {
+  try {
+    mkdirSync6(zeroDir, { recursive: true });
+    writeFileSync6(cachePath(zeroDir), JSON.stringify(cache, null, 2));
+  } catch {
+  }
+};
+var fetchLatestVersion = async (url = NPM_REGISTRY_URL) => {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: { accept: "application/json" }
+    });
+    clearTimeout(timeout);
+    if (!response.ok) return null;
+    const json = await response.json();
+    return typeof json.version === "string" ? json.version : null;
+  } catch {
+    return null;
+  }
+};
+var refreshUpdateCache = async (zeroDir, opts = {}) => {
+  const now = opts.now ?? Date.now();
+  const fetcher = opts.fetchLatest ?? fetchLatestVersion;
+  const cache = readCache(zeroDir);
+  if (cache.lastCheckedMs > 0 && now - cache.lastCheckedMs < CHECK_INTERVAL_MS) {
+    return;
+  }
+  const latest = await fetcher();
+  if (!latest) {
+    writeCache(zeroDir, { ...cache, lastCheckedMs: now });
+    return;
+  }
+  writeCache(zeroDir, {
+    ...cache,
+    lastCheckedMs: now,
+    latestVersion: latest
+  });
+};
+var updateCommandFor = (method) => method === "binary" ? "curl -fsSL https://zero.xyz/install.sh | bash" : "npm install -g @zeroxyz/cli";
+var formatBanner = (currentVersion, latestVersion, method) => {
+  const arrow = `${currentVersion} \u2192 ${latestVersion}`;
+  const cmd = updateCommandFor(method);
+  const lines = [
+    "",
+    `  ${color.yellow("\u26A1 Update available")}  ${color.dim(arrow)}`,
+    `  ${color.dim("Run:")} ${color.cyan(cmd)}`,
+    ""
+  ];
+  return lines.join("\n");
+};
+var consumeBannerIfDue = (zeroDir, currentVersion, opts = {}) => {
+  const now = opts.now ?? Date.now();
+  const method = opts.method ?? detectInstallMethod();
+  const cache = readCache(zeroDir);
+  if (!cache.latestVersion) return null;
+  if (compareVersions(currentVersion, cache.latestVersion) >= 0) return null;
+  if (cache.lastShownMs > 0 && now - cache.lastShownMs < CHECK_INTERVAL_MS) {
+    return null;
+  }
+  writeCache(zeroDir, { ...cache, lastShownMs: now });
+  return formatBanner(currentVersion, cache.latestVersion, method);
+};
+var maybePrintUpdateBanner = (zeroDir, currentVersion) => {
+  if (!process.stderr.isTTY) return;
+  const banner = consumeBannerIfDue(zeroDir, currentVersion);
+  if (banner) process.stderr.write(banner);
+};
+
 // src/index.ts
 var main = async () => {
   const appContext = createAppContext();
@@ -3490,6 +3865,8 @@ var main = async () => {
     console.error("Failed to create app context");
     process.exit(1);
   }
+  const zeroDir = join8(homedir7(), ".zero");
+  maybePrintUpdateBanner(zeroDir, package_default.version);
   const app = createApp(appContext);
   let caughtError = null;
   try {
@@ -3500,6 +3877,9 @@ var main = async () => {
       caughtError = err instanceof Error ? err : new Error(String(err));
       console.error(caughtError.message);
       process.exitCode = 1;
+      appContext.services.analyticsService.captureException(caughtError, {
+        command: appContext.invocation.current?.command
+      });
     }
   } finally {
     const invocation = appContext.invocation.current;
@@ -3513,6 +3893,7 @@ var main = async () => {
       });
     }
     await appContext.services.analyticsService.shutdown();
+    await refreshUpdateCache(zeroDir);
   }
 };
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zeroxyz/cli",
-	"version": "0.0.34",
+	"version": "0.0.36",
 	"type": "module",
 	"bin": {
 		"zero": "dist/index.js",