agy-cli-usage 0.3.1 → 0.4.0

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.0](https://github.com/abruption/agy-cli-usage/compare/v0.3.1...v0.4.0) (2026-06-24)
+
+
+### Features
+
+* ship as a compiled TypeScript build with bundled type declarations ([0e253ea](https://github.com/abruption/agy-cli-usage/commit/0e253ea353e99efe5bfd176f5b6775d76718b3a9))
+* ship compiled TypeScript build with type declarations ([#20](https://github.com/abruption/agy-cli-usage/issues/20)) ([0e253ea](https://github.com/abruption/agy-cli-usage/commit/0e253ea353e99efe5bfd176f5b6775d76718b3a9))
+
 ## [0.3.1](https://github.com/abruption/agy-cli-usage/compare/v0.3.0...v0.3.1) (2026-06-24)
 
 

package/README.md

@@ -1,89 +1,124 @@
+<div align="center">
+
 # agy-cli-usage
 
+[![npm version](https://img.shields.io/npm/v/agy-cli-usage?color=cb3837&logo=npm)](https://www.npmjs.com/package/agy-cli-usage)
+[![npm downloads](https://img.shields.io/npm/dm/agy-cli-usage?color=cb3837&logo=npm)](https://www.npmjs.com/package/agy-cli-usage)
 [![CI](https://github.com/abruption/agy-cli-usage/actions/workflows/ci.yml/badge.svg)](https://github.com/abruption/agy-cli-usage/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/agy-cli-usage.svg)](https://www.npmjs.com/package/agy-cli-usage)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![node](https://img.shields.io/node/v/agy-cli-usage?color=339933&logo=node.js)](https://www.npmjs.com/package/agy-cli-usage)
+[![license](https://img.shields.io/npm/l/agy-cli-usage?color=blue)](LICENSE)
 
-Headless usage/quota monitor for the Antigravity CLI (`agy`). `agy`의 인터랙티브 `/usage` 패널과 동일한 정보(모델 그룹별 주간·5시간 한도, 잔여율, 리프레시 시각)를 **headless로** 조회한다. IDE 불필요.
+**Headless usage & quota monitor for the Antigravity CLI (`agy`).**
 
-`agy -p "<prompt>"`(headless)는 `/usage` 같은 TUI 슬래시 커맨드를 렌더링하지 않으므로 자동화가 불가능하다. 이 도구는 `agy`가 내부적으로 호출하는 Cloud Code API를 직접 호출하거나, 불가능할 때 `agy`를 PTY로 구동해 패널을 파싱한다.
+`agy`의 `/usage` 패널(모델 그룹별 주간·5시간 한도, 잔여율, 리프레시 시각)을 **헤드리스로** 조회합니다 — IDE 불필요, macOS · Linux · Windows · 헤드리스 서버 지원.
 
-## 설치
+<sub>Inspired by <a href="https://github.com/skainguyen1412/antigravity-usage">skainguyen1412/antigravity-usage</a> — which targets the Antigravity <b>IDE</b>; this targets the <b>CLI</b> (<code>agy</code>).</sub>
 
-```bash
-# npm 레지스트리에서
-npm install -g agy-cli-usage
+</div>
+
+---
 
-# 또는 GitHub에서 직접
-npm install -g github:abruption/agy-cli-usage
-npx github:abruption/agy-cli-usage
+```text
+  Models & Quota
+  Account: you@gmail.com
 
-# 또는 소스에서
-git clone https://github.com/abruption/agy-cli-usage && cd agy-cli-usage
-npm install && npm link
+  GEMINI MODELS
+    Weekly Limit
+    [██████████████████████████████████████████████░░░░] 91.72%
+    92% remaining · Refreshes in 73h 23m
+    Five Hour Limit
+    [███████████████████████████████████████████████░░░] 94.63%
+    95% remaining · Refreshes in 2h 2m
+
+  CLAUDE AND GPT MODELS
+    Weekly Limit
+    [█████████████████████████████████████████████████░] 97.78%
+    98% remaining · Refreshes in 26h 17m
+    Five Hour Limit
+    [██████████████████████████████████████████████████] Quota available
 ```
 
-전역 명령은 `agy-cli-usage` (별칭 `agy-usage`)로 등록된다. Node.js >= 18 (전역 `fetch` 필요). 사전 조건: 같은 머신에서 `agy`에 로그인되어 있을 것.
+## 🚀 빠른 시작
 
-## 사용법
+```bash
+# 설치 없이 한 번 실행
+npx agy-cli-usage
+
+# 전역 설치 → 어디서나 `agy-cli-usage`
+npm install -g agy-cli-usage
+agy-cli-usage
+```
+
+> 사전 조건: 같은 머신에서 `agy`에 로그인되어 있을 것. Node.js >= 18.
+
+## ⚡ 사용법
 
 ```bash
-agy-usage                  # /usage 와 동일한 패널 출력 (1회성)
-agy-usage --json           # 머신 리더블 JSON
-agy-usage --watch 60       # 60초 간격 자동 갱신 (5분 캐시 경유)
-agy-usage --source api|pty|auto   # 데이터 소스 (기본 auto: API → 실패 시 PTY)
-agy-usage --channel daily|prod    # Cloud Code 호스트 (기본 auto: daily→prod 탐지)
-agy-usage --no-cache               # 5분 캐시 무시하고 강제 조회
+agy-cli-usage                  # /usage 와 동일한 패널 (1회성)
+agy-cli-usage --json           # 머신 리더블 JSON
+agy-cli-usage --watch 60       # 60초 간격 자동 갱신 (5분 캐시 경유)
+agy-cli-usage update [--check] # 자기 업데이트 (--check: 알림만)
+agy-cli-usage --version        # 버전 출력
 ```
 
-## 동작 방식
+| 플래그 | 설명 |
+|--------|------|
+| `--json` | 정규화 JSON 출력 (스크립트/대시보드 연동) |
+| `--watch [초]` | N초 간격 갱신 (기본 60) |
+| `--source <auto\|api\|pty>` | 데이터 소스 (기본 `auto`: API → 실패 시 PTY) |
+| `--channel <auto\|daily\|prod>` | Cloud Code 호스트 |
+| `--no-cache` / `--refresh` | 5분 캐시 무시하고 강제 조회 |
+
+## 🤔 왜 필요한가
 
-`agy`는 OAuth 토큰을 OS 키링(zalando/go-keyring 규약, service=`gemini`/account=`antigravity`)에 저장한다.
+`agy -p "<prompt>"`(headless)는 LLM 프롬프트 전용이라 `/usage` 같은 TUI 슬래시 커맨드를 렌더링하지 않습니다. 그래서 사용량을 자동화·폴링할 수 없습니다. 이 도구는 그 공백을 메웁니다.
 
-1. **직접 API (기본)** — 토큰을 읽고(만료 시 자동 refresh), `agy`와 동일하게:
-   - `POST https://<host>/v1internal:loadCodeAssist` → `cloudaicompanionProject` 획득
-   - `POST https://<host>/v1internal:retrieveUserQuotaSummary {project}` → 쿼타
-   - 호스트: `daily-cloudcode-pa.googleapis.com`(현재 CLI) 또는 `cloudcode-pa.googleapis.com`
-   - 토큰 소스: **키링 → 토큰 파일 → (실패 시) PTY** 순으로 자동 시도
-2. **PTY 폴백** — 위 토큰 소스를 모두 읽을 수 없거나 내부 API가 바뀌면, `agy`를 가상 터미널로 띄워 `/usage`를 보내고, `@xterm/headless`로 alt-screen을 재구성해 패널을 파싱한다.
+## 🔍 동작 방식
 
-### 크로스플랫폼 자격증명
+1. **직접 API (기본 · 빠름)** — OS에서 `agy`의 OAuth 토큰을 읽어, `agy`가 시작 시 호출하는 것과 동일한 Cloud Code 내부 API를 직접 호출합니다.
+   - `POST /v1internal:loadCodeAssist` → `cloudaicompanionProject` 획득
+   - `POST /v1internal:retrieveUserQuotaSummary {project}` → 쿼타
+   - 만료 시 OAuth refresh 자동 처리.
+2. **PTY 폴백 (안전망)** — 위 토큰을 못 읽거나 내부 API가 바뀌면, `agy`를 가상 터미널로 띄워 `/usage`를 보내고 `@xterm/headless`로 화면을 재구성해 파싱합니다.
 
-| OS | 토큰 소스 | 비고 |
-|----|-----------|------|
-| macOS | Keychain | `@napi-rs/keyring`, CLI 폴백 `security` |
-| Windows | Credential Manager | `@napi-rs/keyring` |
-| Linux (데스크톱) | Secret Service | `@napi-rs/keyring`, CLI 폴백 `secret-tool` |
-| Linux (헤드리스) | **토큰 파일** | 키링 부재 시 `~/.gemini/antigravity-cli/antigravity-oauth-token`(순수 JSON) 읽음 → **API 경로 동작**. `AGY_OAUTH_TOKEN_FILE`로 경로 override |
+## 🔐 크로스플랫폼 자격증명
 
-> 헤드리스 서버에서도 토큰 파일을 읽어 빠른 API 경로를 쓴다. 파일조차 없으면 `--source pty`로 우회(python3 필요).
+토큰은 `agy`가 저장한 위치에서 **읽기만** 합니다. 플랫폼별로 자동 처리:
 
-## HTTP 엔드포인트 (선택)
+| OS / 환경 | 저장 위치 | 읽는 방법 |
+|-----------|----------|----------|
+| macOS | Keychain | `@napi-rs/keyring` (폴백 `security`) |
+| Linux 데스크톱 | Secret Service | `@napi-rs/keyring` (폴백 `secret-tool`) |
+| **Windows** | Credential Manager | 내장 `powershell.exe`로 Win32 `CredRead` 호출 |
+| **헤드리스 Linux** | 토큰 파일 | `~/.gemini/antigravity-cli/antigravity-oauth-token` |
+
+읽기 체인: `키링 → OS CLI → Windows credman → 토큰 파일 → PTY`. `AGY_OAUTH_TOKEN_FILE`로 파일 경로 override.
+
+## 🔌 HTTP 엔드포인트 (선택)
 
 ```bash
 PORT=3007 node server.js     # GET /quota → 정규화 JSON (5분 캐시), GET /healthz
 ```
 
-외부 대시보드/스크립트에서 `GET /quota`로 소비하거나, `agy-usage --json`을 subprocess로 호출한다.
+외부 대시보드/스크립트에서 `GET /quota`로 소비하거나 `agy-cli-usage --json`을 subprocess로 호출하세요.
 
-## 개발 / 릴리스
+## 🛠️ 개발 / 릴리스
 
 ```bash
 npm test          # node --test (자격증명·네트워크 불필요, 순수 로직)
 npm run check     # 구문 검사
 ```
 
-- **CI** (`.github/workflows/ci.yml`): push/PR마다 ubuntu(Node 18/20/22) + macOS/Windows(Node 22)에서 테스트.
-- **Release** ([release-please](https://github.com/googleapis/release-please), `.github/workflows/release-please.yml`): Conventional Commits 기반 **완전 자동화**. `NPM_TOKEN` 시크릿 필요.
-
-릴리스 절차 — 수동 버전 범프 없음:
+- **CI**: push/PR마다 ubuntu(Node 18/20/22) + macOS/Windows(Node 22)에서 테스트.
+- **Release**: [release-please](https://github.com/googleapis/release-please) — Conventional Commits 기반 완전 자동화. main에 머지된 커밋으로 release-please가 **Release PR**(버전 범프 + CHANGELOG)을 유지하고, 그 PR을 머지하면 태그·GitHub Release·`npm publish --provenance`가 자동 실행됩니다.
 
-1. `feat:`/`fix:` 등 Conventional Commits를 main에 머지하면, release-please가 **Release PR**(버전 범프 + CHANGELOG 갱신)을 자동 생성·유지.
-2. 그 **Release PR을 머지**하면 → GitHub Release + 태그 생성 → 같은 워크플로가 `npm publish --provenance` 실행.
+## ⚠️ 주의
 
-> 즉 "Release PR 머지" 한 번이 전체 배포다.
+- `v1internal:retrieveUserQuotaSummary`는 **비공개 내부 엔드포인트**입니다. 스키마/호스트가 예고 없이 바뀔 수 있으며, 그때의 안전망이 PTY 폴백입니다. 본인 계정의 사용량 조회 용도로만 사용하세요.
+- 자격증명은 OS 저장소에서 **읽기만** 하며, refresh 토큰을 되쓰지 않아 `agy` 세션과 충돌하지 않습니다.
+- 코드에 포함된 OAuth client_id/secret은 `agy` 바이너리에 들어 있는 **installed-app(public) 값**으로, [Google 문서](https://developers.google.com/identity/protocols/oauth2)상 기밀이 아닙니다. 사용자 식별은 각자의 키링 토큰으로 이뤄집니다.
 
-## 주의
+## 📄 License
 
-- `v1internal:retrieveUserQuotaSummary`는 **비공개 내부 엔드포인트**다. 스키마/호스트가 예고 없이 바뀔 수 있으며, 그때를 위한 안전망이 PTY 폴백이다.
-- 본인 계정의 키링 토큰만 읽으며(읽기 전용), refresh 토큰을 키링에 되쓰지 않는다.
-- OAuth client_secret은 데스크톱(공개) 클라이언트 값이라 비밀이 아니다.
+[MIT](LICENSE) © abruption

package/dist/src/api.d.ts

@@ -0,0 +1,12 @@
+import type { FetchResult } from './types.js';
+declare class ApiError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+export interface FetchOptions {
+    host?: string;
+    channel?: 'daily' | 'prod';
+}
+/** Fetch the raw quota summary from the Cloud Code API. */
+export declare function fetchQuotaSummary(accessToken: string, opts?: FetchOptions): Promise<FetchResult>;
+export { ApiError };

package/dist/src/api.js

@@ -0,0 +1,84 @@
+// Direct client for the Antigravity / Gemini Code Assist "Cloud Code" internal API.
+//
+// Reproduces exactly what `agy` does on startup to populate its /usage panel:
+//   1. POST /v1internal:loadCodeAssist  {metadata:{ideType:"ANTIGRAVITY"}}
+//        -> { cloudaicompanionProject, currentTier, ... }
+//   2. POST /v1internal:retrieveUserQuotaSummary  {project:<cloudaicompanionProject>}
+//        -> { groups:[...], description }
+//
+// 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}`;
+// 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'];
+class ApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+function extractEmail(uri) {
+    const m = uri?.match(/[?&]Email=([^&]+)/);
+    if (!m)
+        return null;
+    try {
+        return decodeURIComponent(m[1]);
+    }
+    catch {
+        return m[1];
+    }
+}
+async function postInternal(host, accessToken, method, body) {
+    const res = await fetch(`https://${host}/v1internal:${method}`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            'Content-Type': 'application/json',
+            'User-Agent': UA,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        throw new ApiError(`${method} -> HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`, res.status);
+    }
+    return (await res.json());
+}
+/** Fetch the raw quota summary from the Cloud Code API. */
+export async function fetchQuotaSummary(accessToken, opts = {}) {
+    const candidates = opts.host
+        ? [opts.host]
+        : opts.channel === 'prod'
+            ? ['cloudcode-pa.googleapis.com']
+            : opts.channel === 'daily'
+                ? ['daily-cloudcode-pa.googleapis.com']
+                : HOSTS;
+    let lastErr;
+    for (const host of candidates) {
+        try {
+            const lca = await postInternal(host, accessToken, 'loadCodeAssist', {
+                metadata: { ideType: 'ANTIGRAVITY' },
+            });
+            const project = lca.cloudaicompanionProject;
+            if (!project)
+                throw new ApiError('loadCodeAssist returned no cloudaicompanionProject', 0);
+            const raw = await postInternal(host, accessToken, 'retrieveUserQuotaSummary', { project });
+            return {
+                raw,
+                host,
+                tier: lca.currentTier?.id ?? null,
+                account: extractEmail(lca.currentTier?.upgradeSubscriptionUri),
+            };
+        }
+        catch (err) {
+            lastErr = err;
+            // 404 / wrong-host -> try next candidate; auth errors -> stop early.
+            if (err instanceof ApiError && (err.status === 401 || err.status === 403))
+                throw err;
+        }
+    }
+    throw lastErr ?? new ApiError('No Cloud Code host responded', 0);
+}
+export { ApiError };
+//# sourceMappingURL=api.js.map

package/dist/src/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"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"}

package/dist/src/credentials.d.ts

@@ -0,0 +1,22 @@
+declare class CredentialError extends Error {
+}
+interface Cred {
+    accessToken: string;
+    refreshToken: string | null;
+    expiry: Date | null;
+    authMethod: string | null;
+}
+export declare function decodeSecret(raw: string): Cred;
+export interface AccessToken {
+    accessToken: string;
+    authMethod: string | null;
+}
+/**
+ * Returns a valid access token for the Cloud Code API, refreshing if needed.
+ * Throws CredentialError if no credential can be read from any keyring backend
+ * (the caller should then consider the PTY fallback).
+ */
+export declare function getAccessToken(): Promise<AccessToken>;
+/** Whether a keyring-based credential is readable at all (no refresh attempted). */
+export declare function hasCredential(): Promise<boolean>;
+export { CredentialError };