@marcfargas/go-easy 0.0.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# @marcfargas/go-easy
+
+## 0.3.0
+
+### Minor Changes
+
+- [`8cf8524`](https://github.com/marcfargas/go-easy/commit/8cf85243659e1151b896a69f5405534062a82899) Thanks [@marcfargas](https://github.com/marcfargas)! - Beta release — own auth system, Google Tasks, reply CLI, file-based body flags, Markdown emails.
+
+  ### Auth (BREAKING)
+
+  go-easy now owns its own OAuth2 tokens at `~/.go-easy/` instead of reading from legacy CLI stores (`~/.gmcli`, `~/.gdcli`, `~/.gccli`).
+
+  - `npx go-easy auth add <email>` — agent-compatible two-phase OAuth flow (start → poll)
+  - `npx go-easy auth list` — list configured accounts and scopes
+  - `npx go-easy auth remove <email> --confirm` — remove an account
+  - One combined token per account covers Gmail + Drive + Calendar + Tasks
+  - Specific error codes with `fix` field: `AUTH_NO_ACCOUNT`, `AUTH_MISSING_SCOPE`, `AUTH_TOKEN_REVOKED`, `AUTH_NO_CREDENTIALS`
+
+  ### Google Tasks (NEW)
+
+  New service module and CLI for Google Tasks API:
+
+  - `npx go-tasks <account> lists` — list task lists
+  - `npx go-tasks <account> tasks <listId>` — list tasks with pagination
+  - `npx go-tasks <account> get/add/update/complete/move/delete` — full CRUD
+  - `npx go-tasks <account> create-list/delete-list/clear` — list management
+  - Subtask support via `--parent` flag
+  - Library: `@marcfargas/go-easy/tasks` export
+  - Requires re-auth for existing accounts (`npx go-easy auth add <email>`)
+
+  ### Gmail CLI
+
+  - Add `reply` command — reply and reply-all with `--reply-all` flag (DESTRUCTIVE, requires `--confirm`)
+  - Add `--in-reply-to` flag for `draft` command (thread association)
+  - Add `--cc` and `--bcc` flags for `draft` and `send` commands
+  - Add `--page-token` for `search` and `drafts` pagination
+
+  ### Body Flags (BREAKING)
+
+  Replace inline `--body`, `--html`, `--md` flags with file-based alternatives:
+
+  - `--body-text-file=<path>` — read plain text body from UTF-8 file
+  - `--body-html-file=<path>` — read HTML body from UTF-8 file
+  - `--body-md-file=<path>` — read Markdown body from file (auto-converted to HTML)
+
+  This eliminates shell escaping, encoding, and multiline issues for agent use.
+
+  ### Markdown Email Support
+
+  - New `markdown` option on `send`, `reply`, `forward`, and `createDraft`
+  - Auto-converts Markdown to email-safe HTML with inline styles
+  - GFM support: tables, strikethrough, code blocks, links, lists
+  - `markdownToHtml()` helper exported from `@marcfargas/go-easy/gmail`
+
+  ### Forward Improvements
+
+  - Forward creates a draft by default (WRITE, no safety gate)
+  - `--send-now --confirm` to send immediately (DESTRUCTIVE)
+  - Attachment filtering: `--include=name` and `--exclude=name` (substring match)
+  - `--no-thread` to break out of the original thread
+  - Body content appears above the forwarded message
+
+  ### Calendar
+
+  - Support all event types: working location, out-of-office, focus time, birthday
+  - `--page-token` for events pagination
+  - Fix `update` command: use PATCH instead of PUT to prevent data loss on partial updates
+
+  ### Drive
+
+  - `--page-token` for `ls` and `search` pagination
+
+  ### Fixes
+
+  - RFC 2047 encode Subject headers with non-ASCII characters
+  - Fix forward threading (keep in original thread by default)
+  - Fix auth HTML pages: add `<meta charset="utf-8">` for emoji rendering
+
+## 0.2.0
+
+### Minor Changes
+
+- [`5f424e1`](https://github.com/marcfargas/go-easy/commit/5f424e16c3c9971c2be196725a5d9c1d7e88633b) Thanks [@marcfargas](https://github.com/marcfargas)! - Initial release — Gmail, Drive & Calendar APIs for AI agents and humans.
+
+  - Gmail: search, getMessage, getThread, send, reply, forward, createDraft, sendDraft, listDrafts, listLabels, batchModifyLabels, getAttachmentContent, getProfile
+  - Drive: listFiles, searchFiles, getFile, downloadFile, exportFile, uploadFile, createFolder, moveFile, renameFile, copyFile, trashFile, listPermissions, shareFile, unshareFile
+  - Calendar: listCalendars, listEvents, getEvent, createEvent, updateEvent, deleteEvent, queryFreeBusy
+  - Gateway CLIs: go-gmail, go-drive, go-calendar (JSON output, --confirm safety)
+  - Safety model: READ/WRITE/DESTRUCTIVE operation classification
+  - Auth: multi-account OAuth2 with per-service token stores

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marc Fargas
+
+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,224 @@
+# go-easy 🟢
+
+> Google APIs made easy — Gmail, Drive & Calendar. For AI agents and humans.
+
+Thin TypeScript wrappers over Google's individual `@googleapis/*` packages with:
+- **Own auth** — unified OAuth2 with combined tokens, agent-compatible two-phase flow
+- **Agent-friendly types** — structured `GmailMessage`, `DriveFile`, `CalendarEvent`
+- **Safety guards** — destructive operations (send, share, delete) require explicit confirmation
+- **JSON gateways** — CLI tools that always output structured JSON
+- **File-based body** — email bodies read from files, not CLI args (no shell escaping issues)
+
+## Installation
+
+```bash
+# As a library
+npm install @marcfargas/go-easy
+
+# As CLI tools (no install needed)
+npx go-gmail you@example.com search "is:unread"
+npx go-drive you@example.com ls
+npx go-calendar you@example.com events primary
+```
+
+Requires **Node.js ≥ 20**.
+
+## Auth Setup
+
+go-easy manages its own OAuth2 tokens in `~/.go-easy/`.
+
+### Prerequisites
+
+1. Create a project in [Google Cloud Console](https://console.cloud.google.com/)
+2. Enable the Gmail, Drive, and Calendar APIs
+3. Create OAuth2 credentials (Desktop application type)
+4. Save credentials to `~/.go-easy/credentials.json`:
+
+```json
+{
+  "clientId": "YOUR_CLIENT_ID.apps.googleusercontent.com",
+  "clientSecret": "YOUR_CLIENT_SECRET"
+}
+```
+
+### Add an account
+
+```bash
+npx go-easy auth add you@example.com
+# → { "status": "started", "authUrl": "https://accounts.google.com/..." }
+# Open the URL, authorize, then poll:
+npx go-easy auth add you@example.com
+# → { "status": "complete", "email": "you@example.com", "scopes": ["gmail", "drive", "calendar"] }
+```
+
+One combined token covers Gmail + Drive + Calendar. The flow is agent-compatible — two separate CLI calls (start + poll), no streaming stdout needed.
+
+### Manage accounts
+
+```bash
+npx go-easy auth list                         # List configured accounts
+npx go-easy auth add you@example.com          # Add or upgrade account
+npx go-easy auth remove you@example.com --confirm  # Remove account
+```
+
+## Quick Start
+
+```ts
+import { getAuth } from '@marcfargas/go-easy/auth';
+import { search, send } from '@marcfargas/go-easy/gmail';
+import { setSafetyContext } from '@marcfargas/go-easy';
+
+const auth = await getAuth('gmail', 'you@example.com');
+
+// Search (READ — no safety gate)
+const results = await search(auth, { query: 'is:unread from:client' });
+console.log(results.items);
+
+// Send (DESTRUCTIVE — requires safety context)
+setSafetyContext({
+  confirm: async (op) => {
+    console.log(`⚠️ ${op.description}`);
+    return true; // or prompt the user
+  },
+});
+
+await send(auth, {
+  to: 'client@example.com',
+  subject: 'Invoice attached',
+  markdown: '# Invoice\n\nPlease find attached.',
+  attachments: ['./invoice.pdf'],
+});
+```
+
+## Gateway CLIs
+
+All gateway CLIs output JSON to stdout and work via `npx`:
+
+```bash
+# Gmail
+npx go-gmail you@example.com search "is:unread" --max=10
+npx go-gmail you@example.com get <messageId>
+npx go-gmail you@example.com reply <messageId> --body-text-file=reply.txt --confirm
+npx go-gmail you@example.com send --to=x@y.com --subject="Hi" --body-text-file=body.txt --confirm
+
+# Drive
+npx go-drive you@example.com ls
+npx go-drive you@example.com search "quarterly report"
+npx go-drive you@example.com upload ./file.pdf --folder=<folderId>
+
+# Calendar
+npx go-calendar you@example.com events primary --from=2026-02-01T00:00:00Z
+npx go-calendar you@example.com create primary --summary="Meeting" --start=... --end=...
+npx go-calendar you@example.com freebusy primary --from=... --to=...
+```
+
+Body content is always read from files (`--body-text-file`, `--body-html-file`, `--body-md-file`), never passed inline.
+
+Destructive operations require `--confirm`. Without it, they show what *would* happen and exit with code 2.
+
+## Services
+
+| Service | Module | Gateway | Status |
+|---------|--------|---------|--------|
+| Gmail | `@marcfargas/go-easy/gmail` | `npx go-gmail` | ✅ Ready |
+| Drive | `@marcfargas/go-easy/drive` | `npx go-drive` | ✅ Ready |
+| Calendar | `@marcfargas/go-easy/calendar` | `npx go-calendar` | ✅ Ready |
+
+### Gmail
+
+| Function | Safety | Description |
+|---|---|---|
+| `search` | READ | Search messages by Gmail query |
+| `getMessage` | READ | Get a single message with parsed fields |
+| `getThread` | READ | Get a full conversation thread |
+| `listLabels` | READ | List all labels |
+| `getAttachmentContent` | READ | Download an attachment as Buffer |
+| `getProfile` | READ | Get the authenticated email address |
+| `createDraft` | WRITE | Create a draft (no send) |
+| `listDrafts` | READ | List existing drafts |
+| `batchModifyLabels` | WRITE | Add/remove labels on multiple messages |
+| `markdownToHtml` | — | Convert Markdown to email-safe HTML |
+| `send` | ⚠️ DESTRUCTIVE | Send a new email (supports `markdown` option) |
+| `reply` | ⚠️ DESTRUCTIVE | Reply / reply-all to a message |
+| `forward` | WRITE / ⚠️ DESTRUCTIVE | Forward as draft (default) or send (`sendNow`). Attachment filtering. |
+| `sendDraft` | ⚠️ DESTRUCTIVE | Send an existing draft |
+
+### Drive
+
+| Function | Safety | Description |
+|---|---|---|
+| `listFiles` | READ | List folder contents or query by metadata |
+| `searchFiles` | READ | Full-text search inside file contents |
+| `getFile` | READ | Get file metadata by ID |
+| `downloadFile` | READ | Download binary files as Buffer |
+| `exportFile` | READ | Export Workspace files (Docs → pdf/docx, Sheets → xlsx/csv, etc.) |
+| `listPermissions` | READ | List sharing permissions on a file |
+| `uploadFile` | WRITE | Upload a local file |
+| `createFolder` | WRITE | Create a folder |
+| `moveFile` | WRITE | Move a file to a different folder |
+| `renameFile` | WRITE | Rename a file |
+| `copyFile` | WRITE | Copy a file |
+| `trashFile` | ⚠️ DESTRUCTIVE | Trash a file |
+| `shareFile` | ⚠️ DESTRUCTIVE* | Share a file (*public sharing only; user/group is WRITE) |
+| `unshareFile` | ⚠️ DESTRUCTIVE | Remove a sharing permission |
+
+### Calendar
+
+| Function | Safety | Description |
+|---|---|---|
+| `listCalendars` | READ | List all calendars for the account |
+| `listEvents` | READ | List events with time range, search, pagination |
+| `getEvent` | READ | Get a single event by ID |
+| `queryFreeBusy` | READ | Check availability across calendars |
+| `createEvent` | WRITE | Create an event (with attendees, all-day, location, OOO, focus time) |
+| `updateEvent` | WRITE | Update an existing event (full replace) |
+| `deleteEvent` | ⚠️ DESTRUCTIVE | Delete an event (warns about attendee cancellation) |
+
+## Safety Model
+
+Operations are classified into three levels:
+
+| Level | Gate | Examples |
+|-------|------|----------|
+| **READ** | None | search, getMessage, listLabels |
+| **WRITE** | Logged | createDraft, batchModifyLabels, upload |
+| **DESTRUCTIVE** | Blocked unless confirmed | send, reply, forward, share, delete |
+
+Set up a `SafetyContext` at startup to handle confirmation prompts.
+Without one, all destructive operations are blocked by default.
+
+## Module Structure
+
+go-easy uses **subpath exports** — import only what you need:
+
+```ts
+import { getAuth } from '@marcfargas/go-easy/auth';
+import { search, send } from '@marcfargas/go-easy/gmail';
+import { listFiles, uploadFile } from '@marcfargas/go-easy/drive';
+import { listEvents, createEvent } from '@marcfargas/go-easy/calendar';
+import { setSafetyContext } from '@marcfargas/go-easy';
+```
+
+| Import path | What's in it |
+|---|---|
+| `@marcfargas/go-easy` | Safety context, errors, plus `gmail`/`drive`/`calendar` as namespaces |
+| `@marcfargas/go-easy/auth` | `getAuth`, `listAccounts`, `listAllAccounts`, `clearAuthCache` |
+| `@marcfargas/go-easy/auth-store` | `readAccountStore`, `writeAccountStore`, `findAccount`, etc. |
+| `@marcfargas/go-easy/scopes` | `SCOPES`, `ALL_SCOPES`, `scopeToService` |
+| `@marcfargas/go-easy/gmail` | All Gmail operations |
+| `@marcfargas/go-easy/drive` | All Drive operations |
+| `@marcfargas/go-easy/calendar` | All Calendar operations |
+
+## Development
+
+```bash
+npm install        # install deps
+npm run build      # compile TypeScript
+npm test           # run tests (vitest)
+npm run lint       # type-check without emitting
+npm run dev        # watch mode
+```
+
+## License
+
+MIT

package/dist/auth-flow.d.ts

@@ -0,0 +1,50 @@
+/**
+ * auth-flow — Two-phase OAuth flow for agent-compatible auth.
+ *
+ * Phase 1 (start): Spawn background auth server, return URL.
+ * Phase 2 (poll): Check pending file for completion status.
+ *
+ * The agent calls `npx go-easy auth add <email>` which:
+ *   - On first call: starts the server, returns { status: "started", authUrl }
+ *   - On subsequent calls: polls and returns current status
+ *   - When user completes auth: returns { status: "complete" }
+ */
+export type AuthFlowStatus = {
+    status: 'started';
+    authUrl: string;
+    expiresIn: number;
+} | {
+    status: 'waiting';
+    authUrl: string;
+    expiresIn: number;
+} | {
+    status: 'complete';
+    email: string;
+    scopes: string[];
+} | {
+    status: 'partial';
+    email: string;
+    grantedScopes: string[];
+    missingScopes: string[];
+    message: string;
+} | {
+    status: 'denied';
+    message: string;
+} | {
+    status: 'expired';
+    message: string;
+} | {
+    status: 'error';
+    message: string;
+};
+/**
+ * Start or poll the auth flow for an email.
+ *
+ * This is the single entry point — handles all states:
+ * - No session → start new auth server
+ * - Pending session with live server → return waiting/started
+ * - Completed session → return result, clean up
+ * - Stale session (dead pid) → clean up, restart
+ */
+export declare function authAdd(email: string): Promise<AuthFlowStatus>;
+//# sourceMappingURL=auth-flow.d.ts.map

package/dist/auth-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-flow.d.ts","sourceRoot":"","sources":["../src/auth-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAiBH,MAAM,MAAM,cAAc,GACtB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GACvD;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvG;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAmBzC;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAyGpE"}

package/dist/auth-flow.js

@@ -0,0 +1,219 @@
+/**
+ * auth-flow — Two-phase OAuth flow for agent-compatible auth.
+ *
+ * Phase 1 (start): Spawn background auth server, return URL.
+ * Phase 2 (poll): Check pending file for completion status.
+ *
+ * The agent calls `npx go-easy auth add <email>` which:
+ *   - On first call: starts the server, returns { status: "started", authUrl }
+ *   - On subsequent calls: polls and returns current status
+ *   - When user completes auth: returns { status: "complete" }
+ */
+import { readFile, unlink, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { getPendingDir, readAccountStore, readCredentials, findAccount, } from './auth-store.js';
+import { ALL_SCOPES, scopeToService } from './scopes.js';
+import { AuthError } from './errors.js';
+// ─── Public API ────────────────────────────────────────────
+/**
+ * Start or poll the auth flow for an email.
+ *
+ * This is the single entry point — handles all states:
+ * - No session → start new auth server
+ * - Pending session with live server → return waiting/started
+ * - Completed session → return result, clean up
+ * - Stale session (dead pid) → clean up, restart
+ */
+export async function authAdd(email) {
+    // Check if already fully configured
+    const store = await readAccountStore();
+    if (store) {
+        const account = findAccount(store, email);
+        if (account?.tokens.combined) {
+            const hasAll = ALL_SCOPES.every((s) => account.tokens.combined.scopes.includes(s));
+            if (hasAll) {
+                // Clean up any stale pending file
+                await cleanupPending(email);
+                return {
+                    status: 'complete',
+                    email: account.email,
+                    scopes: account.tokens.combined.scopes.map((s) => scopeToService(s) ?? s),
+                };
+            }
+        }
+    }
+    // Check credentials exist
+    const creds = await readCredentials();
+    if (!creds) {
+        throw new AuthError('AUTH_NO_CREDENTIALS', {
+            message: 'OAuth client credentials not found at ~/.go-easy/credentials.json',
+        });
+    }
+    // Check for pending session
+    const pending = await readPending(email);
+    if (pending) {
+        // Terminal states: return and clean up
+        if (pending.status === 'complete') {
+            await cleanupPending(email);
+            return {
+                status: 'complete',
+                email: pending.email ?? email,
+                scopes: pending.scopes ?? [],
+            };
+        }
+        if (pending.status === 'partial') {
+            await cleanupPending(email);
+            return {
+                status: 'partial',
+                email: pending.email ?? email,
+                grantedScopes: pending.grantedScopes ?? [],
+                missingScopes: pending.missingScopes ?? [],
+                message: pending.message ?? 'Partial authorization',
+            };
+        }
+        if (pending.status === 'denied') {
+            await cleanupPending(email);
+            return {
+                status: 'denied',
+                message: pending.message ?? 'User declined authorization',
+            };
+        }
+        if (pending.status === 'expired') {
+            await cleanupPending(email);
+            return {
+                status: 'expired',
+                message: pending.message ?? 'Authorization timed out',
+            };
+        }
+        if (pending.status === 'error') {
+            await cleanupPending(email);
+            return {
+                status: 'error',
+                message: pending.message ?? 'Unknown error during authorization',
+            };
+        }
+        // Active session (waiting/started)
+        if (pending.status === 'waiting' || pending.status === 'started') {
+            // Check if the server process is still alive
+            if (pending.pid && isProcessAlive(pending.pid)) {
+                // Check if expired by time
+                if (pending.expiresAt && new Date(pending.expiresAt) < new Date()) {
+                    await cleanupPending(email);
+                    return {
+                        status: 'expired',
+                        message: 'Authorization timed out',
+                    };
+                }
+                // Still waiting — return current state
+                const expiresIn = pending.expiresAt
+                    ? Math.max(0, Math.floor((new Date(pending.expiresAt).getTime() - Date.now()) / 1000))
+                    : 300;
+                return {
+                    status: 'waiting',
+                    authUrl: pending.authUrl ?? '',
+                    expiresIn,
+                };
+            }
+            // PID is dead — stale session, clean up and restart
+            await cleanupPending(email);
+        }
+    }
+    // Start new auth flow
+    return startAuthServer(email);
+}
+// ─── Internal ──────────────────────────────────────────────
+function pendingFilePath(email) {
+    return join(getPendingDir(), `${email.toLowerCase().trim()}.json`);
+}
+async function readPending(email) {
+    try {
+        const raw = await readFile(pendingFilePath(email), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function cleanupPending(email) {
+    try {
+        await unlink(pendingFilePath(email));
+    }
+    catch {
+        // Already deleted or never existed
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0); // Signal 0 = just check existence
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Spawn the auth-server as a fully detached background process.
+ *
+ * Uses stdio: 'ignore' so the child has no pipe ties to the parent.
+ * The child writes its startup info to the pending/<email>.json file.
+ * We poll that file briefly to get the authUrl.
+ */
+async function startAuthServer(email) {
+    // Resolve the auth-server script path
+    const thisDir = typeof __dirname !== 'undefined'
+        ? __dirname
+        : fileURLToPath(new URL('.', import.meta.url));
+    const serverScript = join(thisDir, 'auth-server.js');
+    // Verify the script exists
+    try {
+        await stat(serverScript);
+    }
+    catch {
+        throw new AuthError('AUTH_ERROR', {
+            message: `Auth server script not found: ${serverScript}`,
+        });
+    }
+    // Clean up any old pending file first
+    await cleanupPending(email);
+    // Spawn fully detached — no pipes, child survives parent exit
+    const child = spawn(process.execPath, // node.exe
+    [serverScript, email.toLowerCase().trim(), '0'], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    child.unref();
+    // Poll the pending file for the server's startup info
+    const maxWait = 10_000; // 10s
+    const pollInterval = 100; // 100ms
+    const start = Date.now();
+    while (Date.now() - start < maxWait) {
+        await sleep(pollInterval);
+        const pending = await readPending(email);
+        if (pending && pending.authUrl) {
+            return {
+                status: 'started',
+                authUrl: pending.authUrl,
+                expiresIn: pending.expiresAt
+                    ? Math.max(0, Math.floor((new Date(pending.expiresAt).getTime() - Date.now()) / 1000))
+                    : 300,
+            };
+        }
+        // If the server wrote an error/terminal state, return it
+        if (pending && pending.status === 'error') {
+            return {
+                status: 'error',
+                message: pending.message ?? 'Auth server failed to start',
+            };
+        }
+    }
+    throw new AuthError('AUTH_ERROR', {
+        message: 'Auth server did not start within 10 seconds',
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=auth-flow.js.map

package/dist/auth-flow.js.map

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

package/dist/auth-server.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * auth-server — Background loopback OAuth callback server.
+ *
+ * Spawned as a detached child by auth-flow.ts.
+ * Listens on 127.0.0.1:<port>, waits for Google OAuth callback,
+ * exchanges code for token, writes result to pending/<email>.json,
+ * updates accounts.json.
+ *
+ * Communicates with parent via:
+ *   1. stdout: JSON line with { port, pid, authUrl } (parent reads this, then detaches)
+ *   2. pending/<email>.json file (poll target for subsequent CLI calls)
+ *
+ * Usage (not meant to be called directly):
+ *   node auth-server.js <email> <port>
+ */
+export {};
+//# sourceMappingURL=auth-server.d.ts.map

package/dist/auth-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-server.d.ts","sourceRoot":"","sources":["../src/auth-server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG"}