agy-cli-usage 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -10,6 +10,14 @@
 
 * use plain v* tags in release-please ([#12](https://github.com/abruption/agy-cli-usage/issues/12)) ([74b648d](https://github.com/abruption/agy-cli-usage/commit/74b648df24967f71a43095a80e7340a6b5ac2e39)), closes [#9](https://github.com/abruption/agy-cli-usage/issues/9)
 
+## [0.4.5](https://github.com/abruption/agy-cli-usage/compare/v0.4.4...v0.4.5) (2026-07-03)
+
+
+### Bug Fixes
+
+* derive UA from package version, name error classes, bound update-check timeouts, document env vars in --help, show cache freshness in watch mode ([62becdc](https://github.com/abruption/agy-cli-usage/commit/62becdcf4175d2cda3cec8dc3f5bba13005c0d59)), closes [#32](https://github.com/abruption/agy-cli-usage/issues/32)
+* UA version, error class names, update-check timeouts, --help env vars, watch/cache indicator ([#37](https://github.com/abruption/agy-cli-usage/issues/37)) ([62becdc](https://github.com/abruption/agy-cli-usage/commit/62becdcf4175d2cda3cec8dc3f5bba13005c0d59))
+
 ## [0.4.4](https://github.com/abruption/agy-cli-usage/compare/v0.4.3...v0.4.4) (2026-07-03)
 
 

package/dist/src/api.d.ts

@@ -1,4 +1,6 @@
 import type { FetchResult } from './types.js';
+/** Exported for direct unit testing — keeps the UA tied to the real package name/version. */
+export declare function buildUserAgent(): string;
 declare class ApiError extends Error {
     status: number;
     constructor(message: string, status: number);

package/dist/src/api.js

@@ -8,7 +8,12 @@
 //
 // Captured from live agy traffic (mitmproxy). The internal endpoint is undocumented;
 // the PTY fallback exists for when it changes.
-const UA = `antigravity-usage-monitor/0.1 ${process.platform}/${process.arch}`;
+import { currentVersion } from './update.js';
+/** Exported for direct unit testing — keeps the UA tied to the real package name/version. */
+export function buildUserAgent() {
+    return `agy-cli-usage/${currentVersion()} ${process.platform}/${process.arch}`;
+}
+const UA = buildUserAgent();
 // Antigravity ships against the "daily" Cloud Code host; stable builds use the
 // plain host. Try daily first (matches current CLI), fall back to prod.
 const HOSTS = ['daily-cloudcode-pa.googleapis.com', 'cloudcode-pa.googleapis.com'];
@@ -16,6 +21,7 @@ class ApiError extends Error {
     status;
     constructor(message, status) {
         super(message);
+        this.name = 'ApiError';
         this.status = status;
     }
 }

package/dist/src/credentials.d.ts

@@ -1,4 +1,5 @@
 declare class CredentialError extends Error {
+    constructor(message: string);
 }
 interface Cred {
     accessToken: string;

package/dist/src/credentials.js

@@ -35,6 +35,10 @@ const KEYRING_SERVICE = 'gemini';
 const KEYRING_ACCOUNT = 'antigravity';
 const B64_PREFIX = 'go-keyring-base64:';
 class CredentialError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CredentialError';
+    }
 }
 // --- raw keyring read --------------------------------------------------------
 async function readViaNapiEsm() {

package/dist/src/main.js

@@ -82,6 +82,15 @@ const HELP = `agy-cli-usage — Antigravity CLI (agy) usage/quota monitor
   agy-cli-usage --no-cache | --refresh
   agy-cli-usage update [--check]  self-update via npm (--check: report only)
   agy-cli-usage --version | -v
+
+Environment variables:
+  AGY_OAUTH_TOKEN_FILE  Override the token file path (headless fallback).
+  AGY_BIN               Path to the agy binary (PTY source). Else resolved from
+                        PATH, then ~/.local/bin.
+  XDG_CACHE_HOME        Cache base dir (cache lives at
+                        <base>/agy-usage/quota.json; default ~/.cache).
+  NO_COLOR              Disable ANSI color in the rendered panel.
+  PORT / HOST           HTTP server bind (server mode only).
 `;
 /** Exported for direct unit testing via an injected `cacheFile` — not part of the CLI's public surface. */
 export function readCache(source, channel, cacheFile = CACHE_FILE) {

package/dist/src/render.d.ts

@@ -1,3 +1,3 @@
 import type { Snapshot } from './types.js';
-/** Returns the full panel as a string. */
-export declare function renderPanel(snap: Snapshot): string;
+/** Returns the full panel as a string. `nowMs` is injectable for testing. */
+export declare function renderPanel(snap: Snapshot, nowMs?: number): string;

package/dist/src/render.js

@@ -46,14 +46,40 @@ function bucketLine(b) {
     }
     return lines.join('\n');
 }
-/** Returns the full panel as a string. */
-export function renderPanel(snap) {
+// `--watch`'s default interval (60s) is faster than the 5-minute quota cache
+// TTL, so most refreshes just re-render a cached snapshot with no visual
+// sign the fetch didn't actually happen. `fetchedAt` is set once, when the
+// data was truly fetched (see quota.ts), and carried through untouched on a
+// cache hit — so comparing it to "now" at render time is enough to tell the
+// two cases apart without threading extra state through Snapshot/the cache.
+// A small skew is tolerated so a genuinely fresh fetch isn't mislabeled
+// "cached" just because rendering happened slightly after fetching.
+const FRESHNESS_SKEW_MS = 3_000;
+function formatAge(totalSeconds) {
+    const s = Math.max(0, Math.round(totalSeconds));
+    if (s < 60)
+        return `${s}s`;
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    if (h > 0)
+        return `${h}h ${m}m`;
+    return `${m}m ${s % 60}s`;
+}
+function freshnessSuffix(fetchedAt, nowMs) {
+    const ageMs = nowMs - new Date(fetchedAt).getTime();
+    if (!Number.isFinite(ageMs) || ageMs < FRESHNESS_SKEW_MS)
+        return '';
+    return dim(` (cached, refreshed ${formatAge(ageMs / 1000)} ago)`);
+}
+/** Returns the full panel as a string. `nowMs` is injectable for testing. */
+export function renderPanel(snap, nowMs = Date.now()) {
     const out = [];
     out.push('');
     out.push(bold('  Models & Quota'));
     if (snap.account)
         out.push(`  ${dim('Account:')} ${snap.account}`);
-    out.push(`  ${dim(`source: ${snap.source}${snap.host ? ` · ${snap.host}` : ''} · ${snap.fetchedAt}`)}`);
+    out.push(`  ${dim(`source: ${snap.source}${snap.host ? ` · ${snap.host}` : ''} · ${snap.fetchedAt}`)}` +
+        freshnessSuffix(snap.fetchedAt, nowMs));
     out.push('');
     for (const g of snap.groups) {
         out.push(bold(`  ${g.name.toUpperCase()}`));

package/dist/src/update.d.ts

@@ -9,8 +9,15 @@ export declare function currentVersion(): string;
  * Returns negative if a<b, 0 if equal, positive if a>b.
  */
 export declare function semverCompare(a: string, b: string): number;
+export declare const NPM_VIEW_TIMEOUT_MS = 8000;
+export declare const REGISTRY_FETCH_TIMEOUT_MS = 8000;
+/** Exported for direct unit testing via injection — not part of the public surface. */
+export interface LatestVersionDeps {
+    execNpmView?: (pkgName: string, timeoutMs: number) => string;
+    fetchRegistry?: (pkgName: string, timeoutMs: number) => Promise<Response>;
+}
 /** Latest published version: prefer the user's configured registry (npm view), fall back to public. */
-export declare function latestVersion(): Promise<string | null>;
+export declare function latestVersion(deps?: LatestVersionDeps): Promise<string | null>;
 /** Run the update flow. Returns the intended process exit code. */
 export declare function runUpdate({ checkOnly }?: {
     checkOnly?: boolean;

package/dist/src/update.js

@@ -34,26 +34,42 @@ export function semverCompare(a, b) {
     }
     return 0;
 }
+// Both the `npm view` child process and the registry fetch fallback are
+// bounded so a slow/unreachable registry can't hang the update check
+// indefinitely — a timed-out attempt is treated the same as "unavailable"
+// and falls through to the next strategy (or to `latestVersion` returning
+// null, which `runUpdate` reports as "could not determine the latest version").
+export const NPM_VIEW_TIMEOUT_MS = 8_000;
+export const REGISTRY_FETCH_TIMEOUT_MS = 8_000;
+function defaultExecNpmView(pkgName, timeoutMs) {
+    return execFileSync('npm', ['view', pkgName, 'version'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: timeoutMs,
+    });
+}
+function defaultFetchRegistry(pkgName, timeoutMs) {
+    return fetch(`https://registry.npmjs.org/${pkgName}/latest`, { signal: AbortSignal.timeout(timeoutMs) });
+}
 /** Latest published version: prefer the user's configured registry (npm view), fall back to public. */
-export async function latestVersion() {
+export async function latestVersion(deps = {}) {
+    const execNpmView = deps.execNpmView ?? defaultExecNpmView;
+    const fetchRegistry = deps.fetchRegistry ?? defaultFetchRegistry;
     try {
-        const out = execFileSync('npm', ['view', PKG_NAME, 'version'], {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim();
+        const out = execNpmView(PKG_NAME, NPM_VIEW_TIMEOUT_MS).trim();
         if (out)
             return out;
     }
     catch {
-        // npm missing or offline — try the public registry directly
+        // npm missing, offline, or timed out — try the public registry directly
     }
     try {
-        const res = await fetch(`https://registry.npmjs.org/${PKG_NAME}/latest`);
+        const res = await fetchRegistry(PKG_NAME, REGISTRY_FETCH_TIMEOUT_MS);
         if (res.ok)
             return (await res.json()).version;
     }
     catch {
-        // offline
+        // offline or timed out
     }
     return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-cli-usage",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Headless usage/quota monitor for the Antigravity CLI (agy) — reads Cloud Code quota directly, with a PTY fallback. No IDE required.",
   "type": "module",
   "types": "dist/src/main.d.ts",
@@ -57,7 +57,7 @@
   "license": "MIT",
   "devDependencies": {
     "@eslint/js": "^9.39.4",
-    "@types/node": "^26.0.0",
+    "@types/node": "^18.19.0",
     "eslint": "^9.39.4",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.62.1"