agy-cli-usage 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -10,6 +10,20 @@
 
 * 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.4](https://github.com/abruption/agy-cli-usage/compare/v0.4.3...v0.4.4) (2026-07-03)
+
+
+### Bug Fixes
+
+* PTY cleanup, duration parsing, email extraction, render clamping, test coverage ([#35](https://github.com/abruption/agy-cli-usage/issues/35)) ([de886a2](https://github.com/abruption/agy-cli-usage/commit/de886a2a5fdf9c7777f485fd94eab0f1a13d215f))
+
+## [0.4.3](https://github.com/abruption/agy-cli-usage/compare/v0.4.2...v0.4.3) (2026-07-02)
+
+
+### Bug Fixes
+
+* key the quota cache by source/channel, validate --source/--channel ([#33](https://github.com/abruption/agy-cli-usage/issues/33)) ([19e6860](https://github.com/abruption/agy-cli-usage/commit/19e6860bcf2aa8a547b880a4430027539b4343fb)), closes [#30](https://github.com/abruption/agy-cli-usage/issues/30)
+
 ## [0.4.2](https://github.com/abruption/agy-cli-usage/compare/v0.4.1...v0.4.2) (2026-06-30)
 
 

package/README.ko.md

@@ -131,6 +131,7 @@ npm test          # 빌드 후 node --test (자격증명·네트워크 불필요
 ## 주의
 
 - `v1internal:retrieveUserQuotaSummary`는 **비공개·비문서 내부 엔드포인트**입니다. 스키마/호스트가 예고 없이 바뀔 수 있으며, 그때의 안전망이 PTY 폴백입니다. 본인 계정의 사용량 조회 용도로만 사용하세요.
+- **최상위 티어 구독자는 API 경로에서 `account`가 `null`입니다.** API 경로는 `loadCodeAssist` 응답의 `currentTier.upgradeSubscriptionUri`에 붙은 `Email=` 파라미터에서 계정 이메일을 추출하는데, 이미 최상위 티어인 계정은 "업그레이드" URL 자체가 없어 추출할 대상이 없습니다. 이는 비공개 엔드포인트의 알려진 제약이며, `--source pty`(agy 자체가 렌더링한 `/usage` 패널에서 `Account: …`를 직접 읽어오므로 영향받지 않음) 외에는 다른 우회 플래그가 없습니다.
 - 자격증명은 OS 저장소에서 **읽기만** 하며, refresh 토큰을 되쓰지 않아 `agy` 세션과 충돌하지 않습니다.
 - 코드에 포함된 OAuth client_id/secret은 `agy` 바이너리의 **installed-app(public)** 값으로, [Google 문서](https://developers.google.com/identity/protocols/oauth2)상 기밀이 아닙니다. 사용자 식별은 각자의 키링 토큰으로 이뤄집니다.
 
@@ -198,6 +199,7 @@ npm test          # 빌드 후 node --test (자격증명·네트워크 불필요
 - `remainingFraction`(잔여 비율 0–1)을 우선 사용. `available`이 `true`면 풀 쿼타로 간주(패널은 "Quota available" 표시).
 - `resetsInSeconds`는 `fetchedAt` 기준 상대값, `resetAt`은 절대값. 둘 다 `null` 가능.
 - `kind`는 인식 시 `weekly`/`5h`로 정규화, 아니면 원본 window/label 문자열.
+- `"source": "api"`로 성공한 응답에서도 `account`가 `null`일 수 있습니다 — 위 주의 섹션 참고(최상위 티어 구독자는 API 경로에 이메일 소스가 없음). 계정 이메일이 반드시 필요하면 `--source pty` 또는 PTY 기반 스냅샷을 사용하세요.
 
 ## HTTP API (`npm run serve` / `dist/src/server.js`)
 

package/README.md

@@ -131,6 +131,7 @@ npm test          # build, then node --test (no credentials/network; pure logic)
 ## Caveats
 
 - `v1internal:retrieveUserQuotaSummary` is a **private, undocumented endpoint**. Its schema/host may change without notice; the PTY fallback is the safety net. Use it only to check your own account's usage.
+- **`account` is `null` via the API path for top-tier subscribers.** The API path derives the account email from the `Email=` param on `currentTier.upgradeSubscriptionUri` in the `loadCodeAssist` response — accounts already on the top tier have no "upgrade" URL, so there's nothing to extract from. This is a known limitation of the undocumented endpoint, not a bug you can work around via flags other than `--source pty`, which reads `Account: …` straight off agy's own rendered `/usage` panel and isn't affected.
 - Credentials are **read-only** from the OS store; the refresh token is never written back, so it never conflicts with `agy`'s own session.
 - The OAuth client_id/secret embedded in the code are `agy`'s **installed-app (public)** values — per [Google's docs](https://developers.google.com/identity/protocols/oauth2) these are not treated as secret. Per-user identity comes from your keyring token, not the client_id.
 
@@ -198,6 +199,7 @@ Notes for parsing:
 - Prefer `remainingFraction` (fraction remaining, 0–1). When `available` is `true`, treat as full quota (the panel shows "Quota available").
 - `resetsInSeconds` is relative to `fetchedAt`; `resetAt` is absolute. Either may be `null`.
 - `kind` is normalized to `weekly` / `5h` where recognized, otherwise the raw window/label string.
+- `account` may be `null` even on a successful `"source": "api"` response — see the Caveats section above (top-tier subscribers have no email source in the API path). Use `--source pty` / a PTY-sourced snapshot if you need the account email reliably.
 
 ## HTTP API (`npm run serve` / `dist/src/server.js`)
 

package/dist/src/api.js

@@ -19,6 +19,16 @@ class ApiError extends Error {
         this.status = status;
     }
 }
+// Known limitation: this is the only email source `loadCodeAssist` exposes —
+// the `Email=` query param on `currentTier.upgradeSubscriptionUri`. Accounts
+// already on the top tier have nothing left to upgrade to, so that URI (and
+// therefore `account`) is `null` for them via the API path even though the
+// PTY path can still show `Account: …` (it reads it straight off agy's own
+// rendered panel, which has an in-app session it can draw on that this
+// unauthenticated-beyond-the-token API response doesn't provide). There is no
+// alternative email field in either `loadCodeAssist` or
+// `retrieveUserQuotaSummary` today — see README Caveats. Use `--source pty`
+// if you need the account email for a top-tier subscriber.
 function extractEmail(uri) {
     const m = uri?.match(/[?&]Email=([^&]+)/);
     if (!m)

package/dist/src/main.d.ts

@@ -11,10 +11,18 @@ export interface CliOptions {
     version?: boolean;
     help?: boolean;
 }
+/** Exported for direct unit testing (no process.argv/exit side effects). */
+export declare function parseArgs(argv: string[]): CliOptions;
+/** Exported for direct unit testing via an injected `cacheFile` — not part of the CLI's public surface. */
+export declare function readCache(source: SnapshotOptions['source'], channel: SnapshotOptions['channel'], cacheFile?: string): Snapshot | null;
+/** Exported for direct unit testing via an injected `cacheFile` — not part of the CLI's public surface. */
+export declare function writeCache(snap: Snapshot, source: SnapshotOptions['source'], channel: SnapshotOptions['channel'], cacheFile?: string): void;
 /** Subset of options needed to produce a snapshot (also usable from server.ts). */
 export interface SnapshotOptions {
     source: 'auto' | 'api' | 'pty';
     channel: 'auto' | 'daily' | 'prod';
     cache: boolean;
+    /** Override the cache file path — for tests only; defaults to the real user cache. */
+    cacheFile?: string;
 }
 export declare function getSnapshot(opts: SnapshotOptions): Promise<Snapshot>;

package/dist/src/main.js

@@ -17,14 +17,18 @@ import { captureUsageViaPty } from './pty-fallback.js';
 import { fromApi, fromPty } from './quota.js';
 import { renderPanel } from './render.js';
 import { currentVersion, runUpdate } from './update.js';
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 const CACHE_DIR = join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'agy-usage');
 const CACHE_FILE = join(CACHE_DIR, 'quota.json');
 const CACHE_TTL_MS = 5 * 60 * 1000;
+const VALID_SOURCES = ['auto', 'api', 'pty'];
+const VALID_CHANNELS = ['auto', 'daily', 'prod'];
 const errMessage = (e) => (e instanceof Error ? e.message : String(e));
-function parseArgs(argv) {
+/** Exported for direct unit testing (no process.argv/exit side effects). */
+export function parseArgs(argv) {
     const o = {
         json: false, watch: null, source: 'auto', channel: 'auto', cache: true, command: null, check: false,
     };
@@ -43,10 +47,20 @@ function parseArgs(argv) {
             else
                 o.watch = 60;
         }
-        else if (a === '--source')
-            o.source = (argv[++i] ?? 'auto');
-        else if (a === '--channel')
-            o.channel = (argv[++i] ?? 'auto');
+        else if (a === '--source') {
+            const v = argv[++i];
+            if (!VALID_SOURCES.includes(v)) {
+                throw new Error(`invalid --source '${v}' — expected one of: ${VALID_SOURCES.join(', ')}`);
+            }
+            o.source = v;
+        }
+        else if (a === '--channel') {
+            const v = argv[++i];
+            if (!VALID_CHANNELS.includes(v)) {
+                throw new Error(`invalid --channel '${v}' — expected one of: ${VALID_CHANNELS.join(', ')}`);
+            }
+            o.channel = v;
+        }
         else if (a === '--no-cache' || a === '--refresh')
             o.cache = false;
         else if (a === '--check')
@@ -69,22 +83,25 @@ const HELP = `agy-cli-usage — Antigravity CLI (agy) usage/quota monitor
   agy-cli-usage update [--check]  self-update via npm (--check: report only)
   agy-cli-usage --version | -v
 `;
-// --- cache -------------------------------------------------------------------
-function readCache() {
+/** 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) {
     try {
-        const { ts, snap } = JSON.parse(readFileSync(CACHE_FILE, 'utf8'));
-        if (Date.now() - ts < CACHE_TTL_MS)
-            return snap;
+        const entry = JSON.parse(readFileSync(cacheFile, 'utf8'));
+        if (entry.source !== source || entry.channel !== channel)
+            return null;
+        if (Date.now() - entry.ts < CACHE_TTL_MS)
+            return entry.snap;
     }
     catch {
-        /* no/expired cache */
+        /* no/expired/incompatible-format cache */
     }
     return null;
 }
-function writeCache(snap) {
+/** Exported for direct unit testing via an injected `cacheFile` — not part of the CLI's public surface. */
+export function writeCache(snap, source, channel, cacheFile = CACHE_FILE) {
     try {
-        mkdirSync(CACHE_DIR, { recursive: true });
-        writeFileSync(CACHE_FILE, JSON.stringify({ ts: Date.now(), snap }));
+        mkdirSync(dirname(cacheFile), { recursive: true });
+        writeFileSync(cacheFile, JSON.stringify({ ts: Date.now(), source, channel, snap }));
     }
     catch {
         /* cache is best-effort */
@@ -92,7 +109,7 @@ function writeCache(snap) {
 }
 export async function getSnapshot(opts) {
     if (opts.cache && opts.source !== 'pty') {
-        const cached = readCache();
+        const cached = readCache(opts.source, opts.channel, opts.cacheFile);
         if (cached)
             return cached;
     }
@@ -114,7 +131,7 @@ export async function getSnapshot(opts) {
             snap = fromPty(await captureUsageViaPty());
         }
     }
-    writeCache(snap);
+    writeCache(snap, opts.source, opts.channel, opts.cacheFile);
     return snap;
 }
 // --- main --------------------------------------------------------------------
@@ -157,13 +174,31 @@ async function main() {
         await once(opts);
     }
 }
-main().catch((err) => {
-    if (err instanceof CredentialError) {
-        process.stderr.write(`credential error: ${err.message}\n`);
+// Only run the CLI when this file is executed directly (as the `bin` entry
+// point) — guarded so parseArgs/readCache/writeCache/etc. can be imported
+// for unit testing without triggering a full live CLI run (network calls,
+// process.exit()) as an import side effect. realpathSync resolves symlinks
+// on process.argv[1] (npm global `bin` entries are frequently symlinks);
+// import.meta.url is already symlink-resolved by Node's ESM loader.
+function isMainModule() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
     }
-    else {
-        process.stderr.write(`error: ${errMessage(err)}\n`);
+    catch {
+        return false;
     }
-    process.exit(1);
-});
+}
+if (isMainModule()) {
+    main().catch((err) => {
+        if (err instanceof CredentialError) {
+            process.stderr.write(`credential error: ${err.message}\n`);
+        }
+        else {
+            process.stderr.write(`error: ${errMessage(err)}\n`);
+        }
+        process.exit(1);
+    });
+}
 //# sourceMappingURL=main.js.map

package/dist/src/pty-fallback.js

@@ -12,7 +12,7 @@
 // Windows (ConPTY). agy shows a welcome screen first, so `/usage` is sent after
 // a delay and the session is held open long enough to render.
 import { spawn } from 'node:child_process';
-import { writeFileSync, readFileSync, mkdtempSync, existsSync } from 'node:fs';
+import { writeFileSync, readFileSync, mkdtempSync, existsSync, rmSync } from 'node:fs';
 import { tmpdir, homedir } from 'node:os';
 import { join, delimiter } from 'node:path';
 // Resolve the agy binary: explicit AGY_BIN, then PATH, then common install dir.
@@ -79,10 +79,14 @@ async function captureViaNodePty() {
 async function captureViaPython() {
     if (process.platform === 'win32')
         return null;
+    // Cleaned up in `finally` below regardless of success/failure so repeated
+    // `--watch` runs or repeated fallback triggers don't leak a directory per
+    // capture (each holds a helper script + the captured PTY bytes).
     const dir = mkdtempSync(join(tmpdir(), 'agy-usage-'));
-    const helper = join(dir, 'drive.py');
-    const outFile = join(dir, 'out.bin');
-    writeFileSync(helper, `import os, pty, time, select, signal, struct, fcntl, termios
+    try {
+        const helper = join(dir, 'drive.py');
+        const outFile = join(dir, 'out.bin');
+        writeFileSync(helper, `import os, pty, time, select, signal, struct, fcntl, termios
 AGY = ${JSON.stringify(AGY_BIN)}
 out = open(${JSON.stringify(outFile)}, "wb")
 pid, fd = pty.fork()
@@ -107,18 +111,25 @@ try: os.kill(pid, signal.SIGTERM)
 except Exception: pass
 out.close()
 `);
-    return new Promise((resolve) => {
-        const proc = spawn('python3', [helper], { stdio: 'ignore' });
-        proc.on('error', () => resolve(null));
-        proc.on('exit', () => {
-            try {
-                resolve(readFileSync(outFile));
-            }
-            catch {
-                resolve(null);
-            }
+        return await new Promise((resolve) => {
+            const proc = spawn('python3', [helper], { stdio: 'ignore' });
+            proc.on('error', () => resolve(null));
+            proc.on('exit', () => {
+                try {
+                    resolve(readFileSync(outFile));
+                }
+                catch {
+                    resolve(null);
+                }
+            });
         });
-    });
+    }
+    finally {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* best-effort cleanup */ }
+    }
 }
 // --- VT reconstruction --------------------------------------------------------
 async function reconstructScreen(raw) {
@@ -139,7 +150,11 @@ async function reconstructScreen(raw) {
 // --- parse --------------------------------------------------------------------
 function parseDuration(text) {
     let seconds = 0;
-    const d = text.match(/(\d+)\s*day/i);
+    // Matches both the spelled-out form ("3 days", "1 day") and the abbreviated
+    // form ("3d") that agy's panel may render instead — without the `\b`
+    // fallback, only "day"/"days" was recognized and a bare "3d 2h" silently
+    // dropped the day component.
+    const d = text.match(/(\d+)\s*d(?:ays?)?\b/i);
     const h = text.match(/(\d+)\s*h(?:our)?/i);
     const m = text.match(/(\d+)\s*m(?:in)?/i);
     if (d)

package/dist/src/render.js

@@ -16,8 +16,15 @@ function barColor(remaining) {
         return '33'; // yellow
     return '31'; // red
 }
+// Clamp to [0,1] — remainingFraction comes from an undocumented private
+// endpoint (or PTY-parsed text), so an out-of-range value must not be shown
+// as-is. Shared by the bar and the percentage text so they never disagree
+// (e.g. bar capped at 100% while the text next to it reads "150.00%").
+function clampFraction(remainingFraction) {
+    return remainingFraction == null ? null : Math.max(0, Math.min(1, remainingFraction));
+}
 function bar(remainingFraction) {
-    const frac = remainingFraction == null ? 0 : Math.max(0, Math.min(1, remainingFraction));
+    const frac = clampFraction(remainingFraction) ?? 0;
     const filled = Math.round(frac * BAR_WIDTH);
     const body = '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled);
     return useColor() ? `\x1b[${barColor(remainingFraction)}m${body}\x1b[0m` : body;
@@ -29,8 +36,9 @@ function bucketLine(b) {
         lines.push(`    [${bar(1)}] ${c('32', 'Quota available')}`);
     }
     else {
-        const pct = b.remainingFraction == null ? '—' : `${(b.remainingFraction * 100).toFixed(2)}%`;
-        const remainPct = b.remainingFraction == null ? '' : `${Math.round(b.remainingFraction * 100)}% remaining`;
+        const clamped = clampFraction(b.remainingFraction);
+        const pct = clamped == null ? '—' : `${(clamped * 100).toFixed(2)}%`;
+        const remainPct = clamped == null ? '' : `${Math.round(clamped * 100)}% remaining`;
         const dur = formatDuration(b.resetsInSeconds);
         const reset = dur ? ` · ${dim(`Refreshes in ${dur}`)}` : '';
         lines.push(`    [${bar(b.remainingFraction)}] ${pct}`);

package/dist/src/server.d.ts

@@ -1,2 +1,16 @@
 #!/usr/bin/env node
+import { type Server } from 'node:http';
+import type { Snapshot } from './types.js';
+type SnapshotFetcher = (opts: {
+    source: 'auto';
+    channel: 'auto';
+    cache: boolean;
+}) => Promise<Snapshot>;
+/**
+ * Builds the HTTP server without binding a port.
+ * `fetchSnapshot` defaults to the real `getSnapshot` (network/keyring/PTY) —
+ * exposed as a parameter purely so tests can inject a stub and exercise the
+ * routing/response-shape logic without live credentials or a PTY.
+ */
+export declare function createApp(fetchSnapshot?: SnapshotFetcher): Server;
 export {};

package/dist/src/server.js

@@ -7,37 +7,64 @@
 //   GET /quota   -> normalized snapshot JSON
 //   GET /healthz -> { ok: true }
 import { createServer } from 'node:http';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { getSnapshot } from './main.js';
 const PORT = Number(process.env.PORT) || 3007;
 const HOST = process.env.HOST || '127.0.0.1';
-const server = createServer(async (req, res) => {
-    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
-    if (url.pathname === '/healthz') {
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ ok: true }));
-        return;
-    }
-    if (url.pathname === '/quota') {
-        try {
-            const noCache = url.searchParams.get('refresh') === '1';
-            const snap = await getSnapshot({ source: 'auto', channel: 'auto', cache: !noCache });
-            res.writeHead(200, {
-                'Content-Type': 'application/json',
-                'Access-Control-Allow-Origin': '*',
-                'Cache-Control': 'public, max-age=300',
-            });
-            res.end(JSON.stringify(snap));
+/**
+ * Builds the HTTP server without binding a port.
+ * `fetchSnapshot` defaults to the real `getSnapshot` (network/keyring/PTY) —
+ * exposed as a parameter purely so tests can inject a stub and exercise the
+ * routing/response-shape logic without live credentials or a PTY.
+ */
+export function createApp(fetchSnapshot = getSnapshot) {
+    return createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        if (url.pathname === '/healthz') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true }));
+            return;
         }
-        catch (err) {
-            res.writeHead(502, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        if (url.pathname === '/quota') {
+            try {
+                const noCache = url.searchParams.get('refresh') === '1';
+                const snap = await fetchSnapshot({ source: 'auto', channel: 'auto', cache: !noCache });
+                res.writeHead(200, {
+                    'Content-Type': 'application/json',
+                    'Access-Control-Allow-Origin': '*',
+                    'Cache-Control': 'public, max-age=300',
+                });
+                res.end(JSON.stringify(snap));
+            }
+            catch (err) {
+                res.writeHead(502, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+            }
+            return;
         }
-        return;
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'not found' }));
+    });
+}
+// Only bind a real port when this file is executed directly (the `serve`
+// script's entry point) — guarded the same way as main.ts's isMainModule()
+// so `createApp` can be imported for unit testing without the import itself
+// starting a live server as a side effect.
+function isMainModule() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
+    }
+    catch {
+        return false;
     }
-    res.writeHead(404, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ error: 'not found' }));
-});
-server.listen(PORT, HOST, () => {
-    process.stdout.write(`agy-usage server on http://${HOST}:${PORT}  (GET /quota)\n`);
-});
+}
+if (isMainModule()) {
+    const server = createApp();
+    server.listen(PORT, HOST, () => {
+        process.stdout.write(`agy-usage server on http://${HOST}:${PORT}  (GET /quota)\n`);
+    });
+}
 //# sourceMappingURL=server.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-cli-usage",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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",
@@ -11,6 +11,7 @@
   "scripts": {
     "build": "tsc",
     "check": "tsc --noEmit",
+    "lint": "eslint .",
     "pretest": "tsc",
     "test": "node --test dist/test/unit.test.js",
     "start": "tsc && node dist/src/main.js",
@@ -55,7 +56,10 @@
   },
   "license": "MIT",
   "devDependencies": {
+    "@eslint/js": "^9.39.4",
     "@types/node": "^26.0.0",
-    "typescript": "^6.0.3"
+    "eslint": "^9.39.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.1"
   }
 }