when-does-my-quota-refresh 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 when-does-my-quota-refresh contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,704 @@
+# when-does-my-quota-refresh
+
+**Cross-platform CLI + SDK for tracking Antigravity AI model quotas across all your accounts.**
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  when-does-my-quota-refresh — Full Dashboard              14:32:07  ║
+╠══════════════════════════════════════════════════════════════╣
+║  📧 user@gmail.com (Personal — Ultra)             ● Active ║
+║  ┌─ Gemini Models ───────────────────────────────────────┐  ║
+║  │ 5-Hour  [██████████████░░░░░░░░░░░░░░░░] 72%  2h31m  │  ║
+║  │ Weekly  [████████████████████████░░░░░░░] 85%  3d12h  │  ║
+║  └────────────────────────────────────────────────────────┘  ║
+║  ┌─ Claude + GPT Models ──────────────────────────────────┐  ║
+║  │ 5-Hour  [████████████████░░░░░░░░░░░░░░] 56%  2h31m   │  ║
+║  │ Weekly  [████████████████████████████░░░] 93%  3d12h   │  ║
+║  └────────────────────────────────────────────────────────┘  ║
+║  📈 Recent ▁▂▃▄▅▆▇█▇▆▅▄▃▂▁▂▃▄▅▆▇█▇▆▅▄▃                    ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Table of Contents
+
+- [Why when-does-my-quota-refresh?](#why-when-does-my-quota-refresh)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Commands Reference](#commands-reference)
+- [SDK Usage](#sdk-usage)
+- [Data Sources](#data-sources)
+- [Configuration](#configuration)
+- [Plugin System](#plugin-system)
+- [Platform Support](#platform-support)
+- [Development](#development)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Why when-does-my-quota-refresh?
+
+**antigravity-usage** (the original tool) has significant shortcomings:
+
+| | antigravity-usage | when-does-my-quota-refresh |
+|---|---|---|
+| Windows support | ❌ Broken | ✅ Full support |
+| Data completeness | ❌ 5-hour session only | ✅ 5-hour + weekly limits |
+| SDK / library use | ❌ CLI only | ✅ Import as library |
+| Plugin system | ❌ None | ✅ Extensible |
+| Usage history | ❌ None | ✅ SQLite-backed trends |
+| Development | ❌ Stalled (6+ months) | ✅ Active |
+
+**when-does-my-quota-refresh** provides:
+
+- ✅ **Cross-platform** — Windows, macOS, and Linux
+- ✅ **Complete quota data** — both 5-hour and weekly limits for all model groups
+- ✅ **Full dashboard** — `aq --full` for a complete overview
+- ✅ **SDK-first** — import as a library in your own tools
+- ✅ **Plugin system** — notifications, webhooks, and community plugins
+- ✅ **Usage history** — track and visualize quota trends over time
+- ✅ **Smart auto-wakeup** — maximize daily quota usage via system scheduler
+
+---
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g when-does-my-quota-refresh
+
+# Check quota (uses local IDE connection — no login needed)
+aq
+
+# Full dashboard with all accounts
+aq --full
+```
+
+> **No login required** for the default mode. when-does-my-quota-refresh connects directly to Antigravity's language server running in your IDE.
+
+---
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g when-does-my-quota-refresh
+```
+
+### From source
+
+```bash
+git clone https://github.com/your-username/when-does-my-quota-refresh.git
+cd when-does-my-quota-refresh
+npm install
+npm run build
+npm link
+```
+
+### Verify installation
+
+```bash
+aq --version
+aq doctor
+```
+
+---
+
+## Commands Reference
+
+### Default Command (no subcommand)
+
+| Command | Description |
+|---------|-------------|
+| `aq` | Show compact quota for the active account |
+| `aq --full` | Show full dashboard with all accounts, groups, and sparklines |
+| `aq --full --watch` | Live-refreshing full dashboard (30s interval) |
+| `aq --json` | Output default command as JSON |
+| `aq --verbose` | Enable debug logging |
+
+---
+
+### `aq quota` — Display Current Quota
+
+```bash
+aq quota                    # Compact view for active account
+aq quota --all              # Side-by-side comparison of all accounts
+aq quota --refresh          # Force fresh fetch (bypass cache)
+aq quota --method local     # Force a specific data source (local, cli, oauth)
+aq quota --json             # Machine-readable JSON output
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-a, --all` | Fetch and display all accounts side-by-side |
+| `-r, --refresh` | Skip cache, fetch fresh data |
+| `-m, --method <method>` | Force a specific data source |
+| `--json` | Output as JSON |
+
+---
+
+### `aq accounts` — Manage Accounts
+
+```bash
+aq accounts list                    # List all configured accounts
+aq accounts add                     # Login a new Google account (browser flow)
+aq accounts add --manual            # Manual login (headless/SSH — shows URL)
+aq accounts switch <email>          # Set the active account
+aq accounts remove <email>          # Remove an account (with confirmation)
+```
+
+**Subcommands:**
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List all managed accounts with status |
+| `add` | Start OAuth login flow for a new Google account |
+| `add --manual` | Get a URL for manual login (for headless environments) |
+| `switch <email>` | Set a different account as active |
+| `remove <email>` | Remove an account (prompts for confirmation) |
+
+---
+
+### `aq history` — Usage History & Analytics
+
+```bash
+aq history                          # Last 7 days for active account
+aq history --days 30                # Last 30 days
+aq history --email user@gmail.com   # Specific account
+aq history --group gemini           # Filter: gemini, claude, or all
+aq history --compare                # Compare all accounts
+aq history --json                   # Machine-readable output
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-e, --email <email>` | Account to show (default: active account) |
+| `-d, --days <days>` | Number of days (default: 7) |
+| `--group <group>` | Filter: `gemini`, `claude`, or `all` (default: `all`) |
+| `--compare` | Show side-by-side comparison of all accounts |
+| `--json` | Output as JSON |
+
+---
+
+### `aq wakeup` — Auto-Trigger Quota Refresh
+
+Automatically trigger quota refreshes to maximize your daily usage limits. Uses your system's native scheduler (cron on macOS/Linux, Task Scheduler on Windows).
+
+```bash
+aq wakeup config            # Interactive setup
+aq wakeup install           # Install to system scheduler
+aq wakeup uninstall         # Remove from system scheduler
+aq wakeup status            # Check if wakeup is installed
+aq wakeup test              # Manually test the wakeup trigger
+```
+
+**Subcommands:**
+
+| Subcommand | Description |
+|------------|-------------|
+| `config` | Interactive wizard to configure trigger mode, schedule, and accounts |
+| `install` | Register the wakeup job with the system scheduler |
+| `uninstall` | Remove the wakeup job from the system scheduler |
+| `status` | Show current wakeup configuration and scheduler status |
+| `test` | Manually trigger a quota refresh to verify it works |
+
+**Trigger Modes:**
+
+| Mode | Description |
+|------|-------------|
+| `smart` | Trigger when quota resets are detected (Recommended) |
+| `interval` | Trigger every N hours |
+| `daily` | Trigger at specific times of day |
+
+---
+
+### `aq watch` — Real-Time Monitoring
+
+```bash
+aq watch start                     # Start monitoring (foreground)
+aq watch start --interval 30       # Custom poll interval (seconds)
+aq watch status                    # Check daemon status
+```
+
+---
+
+### `aq doctor` — Diagnose Setup Issues
+
+```bash
+aq doctor
+```
+
+Runs a comprehensive health check:
+
+- Platform and Node.js version
+- Config directory and file
+- Account configuration and token validity
+- Antigravity process detection
+- Live quota fetch test
+
+---
+
+### `aq config` — Manage Settings
+
+```bash
+aq config show                     # Display all configuration
+aq config set <key> <value>        # Update a setting
+aq config get <key>                # Read a single setting
+aq config path                     # Show config directory path
+```
+
+**Common settings:**
+
+```bash
+aq config set defaultMode oauth         # Change default data source
+aq config set cacheTtlMs 300000         # Cache TTL: 5 minutes
+aq config set notifications false       # Disable desktop notifications
+aq config set daemon.pollIntervalMs 30000  # Watch interval: 30 seconds
+```
+
+**Supported config keys:**
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `defaultMode` | `string` | `local` | Default data source (`local`, `cli`, `oauth`) |
+| `cacheTtlMs` | `number` | `300000` | Cache time-to-live in milliseconds |
+| `refreshIntervalMs` | `number` | `300000` | Auto-refresh interval |
+| `notifications` | `boolean` | `true` | Desktop notifications |
+| `plugins` | `string[]` | `[]` | Installed plugin names |
+| `wakeupModels` | `string[]` | `[...]` | Models to track in wakeup |
+| `wakeupAccounts` | `string[]` | `[]` | Accounts for wakeup (empty = all) |
+| `daemon.pollIntervalMs` | `number` | `60000` | Watch mode poll interval |
+| `daemon.enabled` | `boolean` | `false` | Enable background daemon |
+
+---
+
+### `aq plugin` — Plugin Management
+
+```bash
+aq plugin list                     # List installed plugins
+aq plugin install <name>           # Install a plugin
+aq plugin remove <name>            # Remove a plugin
+```
+
+---
+
+### Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `-V, --version` | Show version number |
+| `-h, --help` | Show help |
+| `--verbose` | Enable debug output |
+| `--json` | Output as JSON (where applicable) |
+| `--full` | Show full dashboard |
+| `--no-history` | Skip history sparkline in full dashboard |
+| `--watch` | Auto-refresh mode (with `--full`) |
+
+---
+
+## SDK Usage
+
+when-does-my-quota-refresh ships as an importable SDK for building your own tools and extensions.
+
+### Installation
+
+```bash
+npm install when-does-my-quota-refresh
+```
+
+### Basic Usage
+
+```typescript
+import { createClient } from 'when-does-my-quota-refresh'
+
+const client = createClient()
+
+// Fetch quota for active account
+const snapshot = await client.fetchQuota()
+console.log(snapshot.groups)
+// => [{ displayName: 'Gemini Models', buckets: [...] }, ...]
+
+// Fetch all accounts
+const snapshots = await client.fetchQuota({ allAccounts: true })
+for (const s of snapshots) {
+  console.log(`${s.email}: ${s.groups.length} groups`)
+}
+
+// Force refresh (bypass cache)
+const fresh = await client.fetchQuota({ refresh: true })
+
+// Force a specific data source
+const fromLocal = await client.fetchQuota({ source: 'local' })
+```
+
+### Full Dashboard
+
+```typescript
+const { snapshots, history, dailySummary } = await client.getFullDashboard()
+
+// snapshots: QuotaSnapshot[]     — current state for each account
+// history: Record<string, UsageRecord[]>  — recent readings per account
+// dailySummary: Record<string, DailySummary[]>  — aggregated daily stats
+```
+
+### Usage History
+
+```typescript
+// Last 30 days for a specific account
+const history = client.getHistory('user@gmail.com', 30)
+
+// Daily summary
+const summary = client.getDailySummary('user@gmail.com', 7)
+```
+
+### Types
+
+All types are exported for TypeScript consumers:
+
+```typescript
+import type {
+  QuotaSnapshot,
+  QuotaGroup,
+  QuotaBucket,
+  PromptCreditsInfo,
+  DataSource,
+  ModelQuotaInfo,
+  AccountInfo,
+  Plugin,
+  UsageRecord,
+  ClientOptions,
+} from 'when-does-my-quota-refresh'
+```
+
+### Error Handling
+
+```typescript
+import {
+  SourceUnavailableError,
+  AuthError,
+  QuotaFetchError,
+} from 'when-does-my-quota-refresh'
+
+try {
+  const snapshot = await client.fetchQuota()
+} catch (err) {
+  if (err instanceof SourceUnavailableError) {
+    console.log(`Source ${err.message} is not available`)
+  } else if (err instanceof AuthError) {
+    console.log('Authentication failed — run `aq accounts add`')
+  } else if (err instanceof QuotaFetchError) {
+    console.log(`Fetch failed: ${err.message}`)
+  }
+}
+```
+
+### Configuration
+
+```typescript
+import { loadConfig, saveConfig, getConfigDirPath } from 'when-does-my-quota-refresh'
+
+// Read current config
+const config = loadConfig()
+
+// Update and save
+config.cacheTtlMs = 10 * 60 * 1000  // 10 minutes
+saveConfig(config)
+
+// Find where config is stored
+console.log(getConfigDirPath())
+```
+
+---
+
+## Data Sources
+
+when-does-my-quota-refresh uses a smart fallback chain to fetch quota data:
+
+### 1. Local (highest priority)
+
+Connects directly to Antigravity's language server running in your IDE (VS Code, Cursor, etc.). This is the **default and recommended** source — no login required.
+
+**How it works:**
+1. Detects running Antigravity processes on your system
+2. Discovers the language server's local port
+3. Sends an HTTP request to fetch quota data
+
+### 2. CLI Bridge
+
+Uses the `agy` CLI's embedded HTTPS server. Useful when the local connection isn't available.
+
+### 3. OAuth (Google Cloud Code API)
+
+Fetches quota data via Google's Cloud Code API using OAuth2 tokens. Requires account login via `aq accounts add`.
+
+**When to use:**
+- Running on a remote server without IDE access
+- Need historical data from the cloud
+- Local/CLI sources are unavailable
+
+### Source Selection
+
+```bash
+# Auto-select best source (default)
+aq quota
+
+# Force specific source
+aq quota --method local
+aq quota --method oauth
+
+# Bypass cache
+aq quota --refresh
+```
+
+---
+
+## Configuration
+
+Configuration is stored in your platform's standard location:
+
+| Platform | Path |
+|----------|------|
+| **macOS** | `~/Library/Application Support/when-does-my-quota-refresh/` |
+| **Linux** | `~/.config/when-does-my-quota-refresh/` |
+| **Windows** | `%APPDATA%/when-does-my-quota-refresh/` |
+
+### Config File
+
+Located at `<config-dir>/config.json`:
+
+```json
+{
+  "defaultMode": "local",
+  "cacheTtlMs": 300000,
+  "refreshIntervalMs": 300000,
+  "wakeupModels": ["claude-sonnet-4-5", "gemini-3-flash", "gemini-3-pro-low"],
+  "wakeupAccounts": [],
+  "notifications": true,
+  "plugins": [],
+  "daemon": {
+    "pollIntervalMs": 60000,
+    "enabled": false
+  }
+}
+```
+
+### Data Directory
+
+Usage history and snapshots are stored in `<config-dir>/data/` using SQLite (`better-sqlite3`).
+
+---
+
+## Plugin System
+
+when-does-my-quota-refresh has a built-in plugin system for extending functionality.
+
+### Built-in Plugins
+
+| Plugin | Description |
+|--------|-------------|
+| `notifications` | Desktop notifications when quota drops below threshold |
+| `webhook` | Send quota updates to a webhook URL |
+
+### Creating a Plugin
+
+```typescript
+import type { Plugin } from 'when-does-my-quota-refresh'
+
+const myPlugin: Plugin = {
+  name: 'my-plugin',
+  version: '1.0.0',
+
+  // Called when plugin loads
+  onInit: async (ctx) => {
+    ctx.log('Plugin initialized')
+  },
+
+  // Called on every quota update
+  onQuotaUpdate: async (snapshot, ctx) => {
+    ctx.log(`Quota updated for ${snapshot.email}`)
+    ctx.notify('Quota Update', `${snapshot.groups.length} groups`)
+  },
+
+  // Called when any bucket drops below threshold
+  onQuotaLow: async (group, bucket, remaining, ctx) => {
+    ctx.notify('Low Quota!', `${group} ${bucket}: ${remaining * 100}% remaining`)
+  },
+
+  // Called when a bucket resets
+  onReset: async (group, nextReset, ctx) => {
+    ctx.log(`${group} resets at ${nextReset.toISOString()}`)
+  },
+
+  // Called when plugin unloads
+  onDestroy: async () => {
+    // Cleanup
+  },
+}
+
+export default myPlugin
+```
+
+### Plugin Hooks
+
+| Hook | When | Parameters |
+|------|------|------------|
+| `onInit` | Plugin loaded | `ctx: PluginContext` |
+| `onQuotaUpdate` | Quota data fetched | `snapshot, ctx` |
+| `onQuotaLow` | Bucket below threshold | `group, bucket, remaining, ctx` |
+| `onReset` | Bucket resets | `group, nextReset, ctx` |
+| `onDestroy` | Plugin unloaded | — |
+
+### Plugin Context
+
+```typescript
+interface PluginContext {
+  /** Show a desktop notification */
+  notify(title: string, message: string): void
+  /** Log a debug message */
+  log(message: string): void
+}
+```
+
+---
+
+## Platform Support
+
+### Windows
+
+when-does-my-quota-refresh provides full Windows support, unlike antigravity-usage:
+
+- **Process detection** — `wmic` + PowerShell + `netstat`
+- **Port discovery** — `Get-NetTCPConnection` + command-line flag extraction
+- **System scheduler** — Windows Task Scheduler (via `schtasks`)
+- **All commands** — full dashboard, watch, wakeup, history, etc.
+
+### macOS & Linux
+
+- **Process detection** — `ps` + `/proc` filesystem
+- **Port discovery** — `lsof` / `/proc/net/tcp`
+- **System scheduler** — `crontab`
+- **Full feature support**
+
+---
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 18
+- npm >= 9
+
+### Getting Started
+
+```bash
+git clone https://github.com/your-username/when-does-my-quota-refresh.git
+cd when-does-my-quota-refresh
+npm install
+npm run dev -- quota    # Run CLI in development mode
+```
+
+### Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Build SDK + CLI with tsup |
+| `npm run dev` | Run CLI via tsx (no build step) |
+| `npm test` | Run test suite |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run typecheck` | Type-check without emitting |
+
+### Build Output
+
+The build produces:
+
+```
+dist/
+├── cli/
+│   ├── index.js          # CLI entry point (with shebang)
+│   └── index.js.map
+├── sdk/
+│   ├── index.js          # SDK entry point (importable)
+│   ├── index.d.ts        # TypeScript declarations
+│   └── index.js.map
+├── auth-*.js             # OAuth chunk
+├── auth-*.js.map
+├── chunk-*.js            # Shared chunks
+└── chunk-*.js.map
+```
+
+---
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Watch mode (re-runs on file changes)
+npm run test:watch
+
+# Run a specific test file
+npx vitest run tests/sdk/cache.test.ts
+```
+
+### Test Structure
+
+```
+tests/
+├── sdk/
+│   ├── cache.test.ts         # Cache behavior tests
+│   └── types.test.ts         # Type validation tests
+└── sources/
+    └── local/
+        ├── parser.test.ts        # Response parser tests
+        └── process-detector.test.ts  # Process detection tests
+```
+
+### Writing Tests
+
+Tests use [Vitest](https://vitest.dev/) with globals enabled:
+
+```typescript
+import { describe, it, expect } from 'vitest'
+
+describe('MyFeature', () => {
+  it('should do something', () => {
+    expect(result).toBe(expected)
+  })
+})
+```
+
+### Testing Before Publishing
+
+See [docs/PUBLISHING.md](docs/PUBLISHING.md) for a complete guide on testing before npm publish.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+**Quick version:**
+
+1. Fork and clone the repo
+2. Install dependencies: `npm install`
+3. Create a feature branch: `git checkout -b feat/my-feature`
+4. Make changes + add tests
+5. Verify: `npm run typecheck && npm test && npm run build`
+6. Commit and open a PR
+
+---
+
+## License
+
+[MIT](LICENSE) — see the LICENSE file for details.