agy-cli-usage 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+## [0.3.0](https://github.com/abruption/agy-cli-usage/compare/v0.2.0...v0.3.0) (2026-06-24)
+
+
+### Features
+
+* add --version flag and self-update command ([#8](https://github.com/abruption/agy-cli-usage/issues/8)) ([811e82f](https://github.com/abruption/agy-cli-usage/commit/811e82f057e709b92b7a7665b01c54dde913b0d4)), closes [#7](https://github.com/abruption/agy-cli-usage/issues/7)
+
+
+### Bug Fixes
+
+* 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.2.0](https://github.com/abruption/agy-cli-usage/compare/v0.1.0...v0.2.0) (2026-06-24)
+
+### Features
+
+* **credentials:** read agy token file for headless Linux (no keyring) ([5914e6c](https://github.com/abruption/agy-cli-usage/commit/5914e6cc3cf3977bb6c6f974f68bd40209bc376e))
+
+## [0.1.0](https://github.com/abruption/agy-cli-usage/compare/e1d582dd618fe06fd607d00846f5b7a66acf924d...v0.1.0) (2026-06-24)
+
+### Features
+
+* headless usage/quota monitor for Antigravity CLI (agy) ([e1d582d](https://github.com/abruption/agy-cli-usage/commit/e1d582dd618fe06fd607d00846f5b7a66acf924d))

package/README.md

@@ -39,20 +39,23 @@ agy-usage --no-cache               # 5분 캐시 무시하고 강제 조회
 
 `agy`는 OAuth 토큰을 OS 키링(zalando/go-keyring 규약, service=`gemini`/account=`antigravity`)에 저장한다.
 
-1. **직접 API (기본)** — 키링에서 토큰을 읽고(만료 시 자동 refresh), `agy`와 동일하게:
+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`
-2. **PTY 폴백** — 키링을 읽을 수 없거나(헤드리스 등) 내부 API가 바뀌면, `agy`를 가상 터미널로 띄워 `/usage`를 보내고, `@xterm/headless`로 alt-screen을 재구성해 패널을 파싱한다.
+   - 토큰 소스: **키링 → 토큰 파일 → (실패 시) PTY** 순으로 자동 시도
+2. **PTY 폴백** — 위 토큰 소스를 모두 읽을 수 없거나 내부 API가 바뀌면, `agy`를 가상 터미널로 띄워 `/usage`를 보내고, `@xterm/headless`로 alt-screen을 재구성해 패널을 파싱한다.
 
 ### 크로스플랫폼 자격증명
 
-| OS | 키링 백엔드 | 비고 |
+| OS | 토큰 소스 | 비고 |
 |----|-----------|------|
 | macOS | Keychain | `@napi-rs/keyring`, CLI 폴백 `security` |
 | Windows | Credential Manager | `@napi-rs/keyring` |
 | Linux (데스크톱) | Secret Service | `@napi-rs/keyring`, CLI 폴백 `secret-tool` |
-| Linux (헤드리스) | — | Secret Service 부재 시 `--source pty`로 우회 (python3 필요) |
+| Linux (헤드리스) | **토큰 파일** | 키링 부재 시 `~/.gemini/antigravity-cli/antigravity-oauth-token`(순수 JSON) 읽음 → **API 경로 동작**. `AGY_OAUTH_TOKEN_FILE`로 경로 override |
+
+> 헤드리스 서버에서도 토큰 파일을 읽어 빠른 API 경로를 쓴다. 파일조차 없으면 `--source pty`로 우회(python3 필요).
 
 ## HTTP 엔드포인트 (선택)
 
@@ -70,12 +73,14 @@ npm run check     # 구문 검사
 ```
 
 - **CI** (`.github/workflows/ci.yml`): push/PR마다 ubuntu(Node 18/20/22) + macOS/Windows(Node 22)에서 테스트.
-- **Release** (`.github/workflows/release.yml`): `v*` 태그 push 시 빌드·테스트 후 npm publish(provenance) + GitHub Release 생성. `NPM_TOKEN` 시크릿 필요.
+- **Release** ([release-please](https://github.com/googleapis/release-please), `.github/workflows/release-please.yml`): Conventional Commits 기반 **완전 자동화**. `NPM_TOKEN` 시크릿 필요.
 
-```bash
-npm version patch        # package.json 버전 +0.0.1 & v* 태그 생성
-git push --follow-tags   # → Release 워크플로 실행 → npm 자동 배포
-```
+릴리스 절차 — 수동 버전 범프 없음:
+
+1. `feat:`/`fix:` 등 Conventional Commits를 main에 머지하면, release-please가 **Release PR**(버전 범프 + CHANGELOG 갱신)을 자동 생성·유지.
+2. 그 **Release PR을 머지**하면 → GitHub Release + 태그 생성 → 같은 워크플로가 `npm publish --provenance` 실행.
+
+> 즉 "Release PR 머지" 한 번이 전체 배포다.
 
 ## 주의
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-cli-usage",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Headless usage/quota monitor for the Antigravity CLI (agy) — reads Cloud Code quota directly, with a PTY fallback. No IDE required.",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
     "src/",
     "server.js",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "keywords": [

package/src/credentials.js

@@ -10,10 +10,15 @@
 // Read backends, tried in order:
 //   1. @napi-rs/keyring native module  (macOS / Windows / Linux Secret Service)
 //   2. OS CLI fallback                  (`security` on macOS, `secret-tool` on Linux)
-// If every backend fails (e.g. a headless Linux box with no Secret Service),
-// the caller falls back to the PTY path which drives `agy` itself.
+//   3. File fallback                    (headless Linux: agy can't reach a keyring
+//                                        and writes the token to a plain-JSON file)
+// If every backend fails, the caller falls back to the PTY path which drives
+// `agy` itself.
 
 import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 
 // OAuth client for the Antigravity CLI. This is an installed/desktop ("public")
 // OAuth client: per Google's own docs the client secret of an installed app is
@@ -68,17 +73,39 @@ function readViaCli() {
   return null;
 }
 
+// On headless Linux (no Secret Service) agy persists the token to a plain-JSON
+// file instead of the keyring. Same payload shape, no `go-keyring-base64:` prefix.
+function readViaFile() {
+  const candidates = [
+    process.env.AGY_OAUTH_TOKEN_FILE,
+    join(homedir(), '.gemini', 'antigravity-cli', 'antigravity-oauth-token'),
+  ].filter(Boolean);
+  for (const path of candidates) {
+    try {
+      if (existsSync(path)) {
+        const content = readFileSync(path, 'utf8').trim();
+        if (content) return content;
+      }
+    } catch {
+      // unreadable (perms) — try next candidate
+    }
+  }
+  return null;
+}
+
 async function readRawSecret() {
   const fromNapi = await readViaNapiEsm();
   if (fromNapi) return fromNapi;
   const fromCli = readViaCli();
   if (fromCli) return fromCli;
+  const fromFile = readViaFile();
+  if (fromFile) return fromFile;
   return null;
 }
 
 // --- decode ------------------------------------------------------------------
 
-function decodeSecret(raw) {
+export function decodeSecret(raw) {
   const payload = raw.startsWith(B64_PREFIX)
     ? Buffer.from(raw.slice(B64_PREFIX.length), 'base64').toString('utf8')
     : raw;
@@ -138,8 +165,9 @@ export async function getAccessToken() {
   const raw = await readRawSecret();
   if (!raw) {
     throw new CredentialError(
-      'Could not read agy credential from the OS keyring. ' +
-        'Is agy logged in on this machine? (headless servers may lack a keyring — use --source pty)',
+      'Could not read agy credential from the OS keyring or token file. ' +
+        'Is agy logged in on this machine? (set AGY_OAUTH_TOKEN_FILE to override the path, ' +
+        'or use --source pty)',
     );
   }
   const cred = decodeSecret(raw);

package/src/main.js

@@ -9,12 +9,15 @@
 //   agy-usage --channel daily|prod    Cloud Code host (default: auto-detect)
 //   agy-usage --no-cache      bypass the 5-minute cache
 //   agy-usage --refresh       force a fresh fetch (alias for --no-cache)
+//   agy-usage update [--check]  self-update via npm
+//   agy-usage --version | -v  print the installed version
 
 import { getAccessToken, CredentialError } from './credentials.js';
 import { fetchQuotaSummary } from './api.js';
 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 { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -24,16 +27,19 @@ const CACHE_FILE = join(CACHE_DIR, 'quota.json');
 const CACHE_TTL_MS = 5 * 60 * 1000;
 
 function parseArgs(argv) {
-  const o = { json: false, watch: null, source: 'auto', channel: 'auto', cache: true };
+  const o = { json: false, watch: null, source: 'auto', channel: 'auto', cache: true, command: null, check: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--json') o.json = true;
+    if (a === 'update' && o.command == null) o.command = 'update';
+    else if (a === '--json') o.json = true;
     else if (a === '--watch') {
       const n = Number(argv[i + 1]);
       if (Number.isFinite(n)) { o.watch = n; i++; } else o.watch = 60;
     } else if (a === '--source') o.source = argv[++i];
     else if (a === '--channel') o.channel = argv[++i];
     else if (a === '--no-cache' || a === '--refresh') o.cache = false;
+    else if (a === '--check') o.check = true;
+    else if (a === '-v' || a === '--version') o.version = true;
     else if (a === '-h' || a === '--help') o.help = true;
   }
   return o;
@@ -47,6 +53,8 @@ const HELP = `agy-usage — Antigravity CLI (agy) usage/quota monitor
   agy-usage --source <auto|api|pty>
   agy-usage --channel <auto|daily|prod>
   agy-usage --no-cache | --refresh
+  agy-usage update [--check]  self-update via npm (--check: report only)
+  agy-usage --version | -v
 `;
 
 // --- cache -------------------------------------------------------------------
@@ -104,6 +112,8 @@ async function once(opts) {
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) { process.stdout.write(HELP); return; }
+  if (opts.version) { process.stdout.write(currentVersion() + '\n'); return; }
+  if (opts.command === 'update') { process.exit(await runUpdate({ checkOnly: opts.check })); }
 
   if (opts.watch != null) {
     const intervalMs = Math.max(5, opts.watch) * 1000;

package/src/update.js

@@ -0,0 +1,87 @@
+// Self-update + version helpers for the CLI.
+//
+// `agy-cli-usage update`        check the registry and `npm install -g` if newer
+// `agy-cli-usage update --check` report only, don't install
+// `agy-cli-usage --version`     print the installed version
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+const PKG_NAME = 'agy-cli-usage';
+
+/** Installed version, read from this package's package.json. */
+export function currentVersion() {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  return pkg.version;
+}
+
+/**
+ * Compare two dotted versions numerically (prerelease tags ignored).
+ * @returns negative if a<b, 0 if equal, positive if a>b
+ */
+export function semverCompare(a, b) {
+  const norm = (v) =>
+    String(v)
+      .replace(/^v/, '')
+      .split('-')[0]
+      .split('.')
+      .map((n) => parseInt(n, 10) || 0);
+  const pa = norm(a);
+  const pb = norm(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+/** Latest published version: prefer the user's configured registry (npm view), fall back to public. */
+export async function latestVersion() {
+  try {
+    const out = execFileSync('npm', ['view', PKG_NAME, 'version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (out) return out;
+  } catch {
+    // npm missing or offline — try the public registry directly
+  }
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PKG_NAME}/latest`);
+    if (res.ok) return (await res.json()).version;
+  } catch {
+    // offline
+  }
+  return null;
+}
+
+/**
+ * Run the update flow.
+ * @param {{ checkOnly?: boolean }} opts
+ * @returns {Promise<number>} process exit code
+ */
+export async function runUpdate({ checkOnly = false } = {}) {
+  const current = currentVersion();
+  const latest = await latestVersion();
+  if (!latest) {
+    process.stderr.write('Could not determine the latest version (offline or npm unavailable).\n');
+    return 1;
+  }
+  if (semverCompare(latest, current) <= 0) {
+    process.stdout.write(`agy-cli-usage is up to date (${current}).\n`);
+    return 0;
+  }
+  process.stdout.write(`Update available: ${current} -> ${latest}\n`);
+  if (checkOnly) {
+    process.stdout.write('Run `agy-cli-usage update` to install it.\n');
+    return 0;
+  }
+  process.stdout.write(`Installing ${PKG_NAME}@${latest} globally…\n`);
+  const r = spawnSync('npm', ['install', '-g', `${PKG_NAME}@${latest}`], { stdio: 'inherit' });
+  if (r.error) {
+    process.stderr.write(`Failed to run npm: ${r.error.message}\nInstall manually: npm install -g ${PKG_NAME}@latest\n`);
+    return 1;
+  }
+  if (r.status === 0) process.stdout.write(`Updated to ${latest}.\n`);
+  return r.status ?? 0;
+}