@marcfargas/go-easy 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @marcfargas/go-easy
+
+## 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,220 @@
+# go-easy 🟢
+
+> Google APIs made easy — Gmail, Drive & Calendar. For AI agents and humans.
+
+Thin TypeScript wrappers over Google's individual `@googleapis/*` packages with:
+- **Simple auth** — multi-account OAuth2 with token import from existing tools
+- **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
+- **Progressive skills** — designed for AI agent consumption (pi coding agent)
+
+## 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 uses OAuth2 tokens stored per-service. Each service reads from its own token store:
+
+| Service | Token store |
+|---|---|
+| Gmail | `~/.gmcli/accounts.json` |
+| Drive | `~/.gdcli/accounts.json` |
+| Calendar | `~/.gccli/accounts.json` |
+
+Each `accounts.json` file contains an array of accounts:
+
+```json
+[
+  {
+    "email": "you@example.com",
+    "oauth2": {
+      "clientId": "YOUR_CLIENT_ID.apps.googleusercontent.com",
+      "clientSecret": "YOUR_CLIENT_SECRET",
+      "refreshToken": "YOUR_REFRESH_TOKEN"
+    }
+  }
+]
+```
+
+To obtain credentials:
+1. Create a project in [Google Cloud Console](https://console.cloud.google.com/)
+2. Enable the Gmail, Drive, and/or Calendar APIs
+3. Create OAuth2 credentials (Desktop application)
+4. Use the OAuth2 playground or a local flow to obtain a refresh token
+5. Place the token in the appropriate `accounts.json` file
+
+## Quick Start
+
+```ts
+import { getAuth } from '@marcfargas/go-easy/auth';
+import { search, send } from '@marcfargas/go-easy/gmail';
+
+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)
+import { setSafetyContext } from '@marcfargas/go-easy';
+
+setSafetyContext({
+  confirm: async (op) => {
+    console.log(`⚠️ ${op.description}`);
+    return true; // or prompt the user
+  },
+});
+
+await send(auth, {
+  to: 'client@example.com',
+  subject: 'Invoice attached',
+  html: '<h1>Invoice</h1><p>Please find attached.</p>',
+  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 send --to=x@y.com --subject="Hi" --body="Hello" --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=...
+```
+
+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 |
+| `send` | ⚠️ DESTRUCTIVE | Send a new email |
+| `reply` | ⚠️ DESTRUCTIVE | Reply to a message (preserves thread) |
+| `forward` | ⚠️ DESTRUCTIVE | Forward a message with attachments |
+| `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) |
+| `updateEvent` | WRITE | Update an existing event |
+| `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
+// Subpath imports (recommended)
+import { getAuth } from '@marcfargas/go-easy/auth';
+import { search, send } from '@marcfargas/go-easy/gmail';
+import { listFiles, upload } from '@marcfargas/go-easy/drive';
+import { listEvents, createEvent } from '@marcfargas/go-easy/calendar';
+import { setSafetyContext } from '@marcfargas/go-easy';         // root: safety, errors, shared utils
+```
+
+| Import path | What's in it |
+|---|---|
+| `@marcfargas/go-easy` | Safety context, errors, plus `gmail`/`drive`/`calendar` as namespaces |
+| `@marcfargas/go-easy/auth` | `getAuth`, `listAccounts`, `clearAuthCache` |
+| `@marcfargas/go-easy/gmail` | All Gmail operations |
+| `@marcfargas/go-easy/drive` | All Drive operations |
+| `@marcfargas/go-easy/calendar` | All Calendar operations |
+
+The root export also re-exports each service as a namespace, so `import { gmail } from '@marcfargas/go-easy'` works if you prefer a single import.
+
+## 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
+```
+
+## Contributing
+
+Found a bug or have a feature request? [Open an issue](https://github.com/marcfargas/go-easy/issues).
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Auth module — OAuth2 client factory with multi-account support.
+ *
+ * Phase 1 (MVP): Import tokens from existing CLI stores:
+ *   ~/.gmcli/accounts.json  → Gmail tokens
+ *   ~/.gdcli/accounts.json  → Drive tokens
+ *   ~/.gccli/accounts.json  → Calendar tokens
+ *
+ * Phase 2 (post-migration): Unified token store at ~/.go-easy/
+ *   with combined scopes per account (single OAuth consent).
+ *
+ * Each CLI token only works for its service's scopes. The library
+ * routes internally — callers specify account (email), and each
+ * service module gets the right OAuth2Client.
+ */
+import { OAuth2Client } from 'google-auth-library';
+/** Services we can load tokens for */
+export type GoogleService = 'gmail' | 'drive' | 'calendar';
+/**
+ * Get an OAuth2Client for a specific service and account.
+ *
+ * @param service - Which Google service (determines which CLI token to use)
+ * @param account - Email address (defaults to first account in the store)
+ * @returns Configured OAuth2Client with refresh token set
+ *
+ * @example
+ * ```ts
+ * import { getAuth } from 'go-easy/auth';
+ * const auth = await getAuth('gmail', 'marc@blegal.eu');
+ * ```
+ */
+export declare function getAuth(service: GoogleService, account?: string): Promise<OAuth2Client>;
+/**
+ * List available accounts for a service.
+ */
+export declare function listAccounts(service: GoogleService): Promise<string[]>;
+/**
+ * Clear the client cache. Useful for tests or token rotation.
+ */
+export declare function clearAuthCache(): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,sCAAsC;AACtC,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,CAAC;AAwC3D;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CA+BvB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAG5E;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist/auth.js

@@ -0,0 +1,91 @@
+/**
+ * Auth module — OAuth2 client factory with multi-account support.
+ *
+ * Phase 1 (MVP): Import tokens from existing CLI stores:
+ *   ~/.gmcli/accounts.json  → Gmail tokens
+ *   ~/.gdcli/accounts.json  → Drive tokens
+ *   ~/.gccli/accounts.json  → Calendar tokens
+ *
+ * Phase 2 (post-migration): Unified token store at ~/.go-easy/
+ *   with combined scopes per account (single OAuth consent).
+ *
+ * Each CLI token only works for its service's scopes. The library
+ * routes internally — callers specify account (email), and each
+ * service module gets the right OAuth2Client.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { OAuth2Client } from 'google-auth-library';
+import { AuthError } from './errors.js';
+/** Map service → CLI config directory name */
+const CLI_DIRS = {
+    gmail: '.gmcli',
+    drive: '.gdcli',
+    calendar: '.gccli',
+};
+/** Cache: "service:email" → OAuth2Client */
+const clientCache = new Map();
+/**
+ * Load accounts from a CLI's accounts.json file.
+ */
+async function loadCliAccounts(service) {
+    const dir = CLI_DIRS[service];
+    const accountsPath = join(homedir(), dir, 'accounts.json');
+    try {
+        const raw = await readFile(accountsPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new AuthError(`Cannot read ${service} accounts from ${accountsPath}. Is the CLI configured?`, err);
+    }
+}
+/**
+ * Get an OAuth2Client for a specific service and account.
+ *
+ * @param service - Which Google service (determines which CLI token to use)
+ * @param account - Email address (defaults to first account in the store)
+ * @returns Configured OAuth2Client with refresh token set
+ *
+ * @example
+ * ```ts
+ * import { getAuth } from 'go-easy/auth';
+ * const auth = await getAuth('gmail', 'marc@blegal.eu');
+ * ```
+ */
+export async function getAuth(service, account) {
+    const accounts = await loadCliAccounts(service);
+    const entry = account
+        ? accounts.find((a) => a.email === account)
+        : accounts[0];
+    if (!entry) {
+        const available = accounts.map((a) => a.email).join(', ');
+        throw new AuthError(account
+            ? `Account "${account}" not found for ${service}. Available: ${available}`
+            : `No accounts configured for ${service}`);
+    }
+    const cacheKey = `${service}:${entry.email}`;
+    const cached = clientCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const oauth2 = new OAuth2Client(entry.oauth2.clientId, entry.oauth2.clientSecret);
+    oauth2.setCredentials({
+        refresh_token: entry.oauth2.refreshToken,
+    });
+    clientCache.set(cacheKey, oauth2);
+    return oauth2;
+}
+/**
+ * List available accounts for a service.
+ */
+export async function listAccounts(service) {
+    const accounts = await loadCliAccounts(service);
+    return accounts.map((a) => a.email);
+}
+/**
+ * Clear the client cache. Useful for tests or token rotation.
+ */
+export function clearAuthCache() {
+    clientCache.clear();
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/bin/calendar.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * go-calendar — Gateway CLI for Google Calendar operations.
+ *
+ * Always outputs JSON. Designed for agent consumption.
+ *
+ * Usage:
+ *   go-calendar <account> <command> [args...]
+ *   go-calendar marc@blegal.eu calendars
+ *   go-calendar marc@blegal.eu events primary --from=2026-02-01T00:00:00Z
+ *   go-calendar marc@blegal.eu create primary --summary="Meeting" --start=... --end=...
+ *
+ * Safety:
+ *   Destructive operations (delete) require --confirm flag.
+ */
+export {};
+//# sourceMappingURL=calendar.d.ts.map

package/dist/bin/calendar.d.ts.map

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

package/dist/bin/calendar.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * go-calendar — Gateway CLI for Google Calendar operations.
+ *
+ * Always outputs JSON. Designed for agent consumption.
+ *
+ * Usage:
+ *   go-calendar <account> <command> [args...]
+ *   go-calendar marc@blegal.eu calendars
+ *   go-calendar marc@blegal.eu events primary --from=2026-02-01T00:00:00Z
+ *   go-calendar marc@blegal.eu create primary --summary="Meeting" --start=... --end=...
+ *
+ * Safety:
+ *   Destructive operations (delete) require --confirm flag.
+ */
+import { getAuth } from '../auth.js';
+import { setSafetyContext } from '../safety.js';
+import * as calendar from '../calendar/index.js';
+const args = process.argv.slice(2);
+function usage() {
+    console.log(JSON.stringify({
+        error: 'USAGE',
+        message: 'go-calendar <account> <command> [args...]',
+        commands: {
+            calendars: 'go-calendar <account> calendars',
+            events: 'go-calendar <account> events <calendarId> [--from=<dt>] [--to=<dt>] [--max=N] [--query="..."]',
+            event: 'go-calendar <account> event <calendarId> <eventId>',
+            create: 'go-calendar <account> create <calendarId> --summary="..." --start=<dt> --end=<dt> [--description="..."] [--location="..."] [--attendees=a@b,c@d] [--all-day] [--tz=<tz>]',
+            update: 'go-calendar <account> update <calendarId> <eventId> --summary="..." --start=<dt> --end=<dt> [--description="..."] [--location="..."] [--attendees=a@b,c@d] [--all-day] [--tz=<tz>]',
+            delete: 'go-calendar <account> delete <calendarId> <eventId> [--confirm]',
+            freebusy: 'go-calendar <account> freebusy <calendarId1,calendarId2> --from=<dt> --to=<dt>',
+        },
+    }, null, 2));
+    process.exit(1);
+}
+/** Parse --key=value flags from args */
+function parseFlags(args) {
+    const flags = {};
+    for (const arg of args) {
+        const match = arg.match(/^--([^=]+)(?:=(.*))?$/);
+        if (match) {
+            flags[match[1]] = match[2] ?? 'true';
+        }
+    }
+    return flags;
+}
+/** Get positional args (non-flag) */
+function positional(args) {
+    return args.filter((a) => !a.startsWith('--'));
+}
+async function main() {
+    if (args.length < 2)
+        usage();
+    const account = args[0];
+    const command = args[1];
+    const rest = args.slice(2);
+    const flags = parseFlags(rest);
+    const pos = positional(rest);
+    // Set up safety context: --confirm flag allows destructive ops
+    const hasConfirm = 'confirm' in flags;
+    setSafetyContext({
+        confirm: async (op) => {
+            if (!hasConfirm) {
+                console.log(JSON.stringify({
+                    blocked: true,
+                    operation: op.name,
+                    description: op.description,
+                    details: op.details,
+                    hint: 'Add --confirm to execute this operation',
+                }, null, 2));
+                process.exit(2);
+            }
+            return true;
+        },
+    });
+    const auth = await getAuth('calendar', account);
+    try {
+        let result;
+        switch (command) {
+            case 'calendars':
+                result = await calendar.listCalendars(auth);
+                break;
+            case 'events':
+                if (!pos[0])
+                    usage();
+                result = await calendar.listEvents(auth, pos[0], {
+                    timeMin: flags.from,
+                    timeMax: flags.to,
+                    maxResults: flags.max ? parseInt(flags.max) : undefined,
+                    query: flags.query,
+                });
+                break;
+            case 'event':
+                if (!pos[0] || !pos[1])
+                    usage();
+                result = await calendar.getEvent(auth, pos[0], pos[1]);
+                break;
+            case 'create': {
+                if (!pos[0])
+                    usage();
+                const createOpts = {
+                    summary: flags.summary ?? '',
+                    description: flags.description,
+                    start: flags.start ?? '',
+                    end: flags.end ?? '',
+                    timeZone: flags.tz,
+                    location: flags.location,
+                    attendees: flags.attendees?.split(','),
+                    allDay: 'all-day' in flags,
+                };
+                result = await calendar.createEvent(auth, pos[0], createOpts);
+                break;
+            }
+            case 'update': {
+                if (!pos[0] || !pos[1])
+                    usage();
+                const updateOpts = {
+                    summary: flags.summary ?? '',
+                    description: flags.description,
+                    start: flags.start ?? '',
+                    end: flags.end ?? '',
+                    timeZone: flags.tz,
+                    location: flags.location,
+                    attendees: flags.attendees?.split(','),
+                    allDay: 'all-day' in flags,
+                };
+                result = await calendar.updateEvent(auth, pos[0], pos[1], updateOpts);
+                break;
+            }
+            case 'delete':
+                if (!pos[0] || !pos[1])
+                    usage();
+                result = await calendar.deleteEvent(auth, pos[0], pos[1]);
+                break;
+            case 'freebusy': {
+                if (!pos[0] || !flags.from || !flags.to)
+                    usage();
+                const calIds = pos[0].split(',');
+                result = await calendar.queryFreeBusy(auth, calIds, flags.from, flags.to);
+                break;
+            }
+            default:
+                usage();
+        }
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        const e = err;
+        if (typeof e.toJSON === 'function') {
+            console.error(JSON.stringify(e.toJSON(), null, 2));
+        }
+        else {
+            console.error(JSON.stringify({
+                error: e.code ?? 'UNKNOWN',
+                message: e.message ?? String(err),
+            }, null, 2));
+        }
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=calendar.js.map

package/dist/bin/calendar.js.map

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

package/dist/bin/drive.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * go-drive — Gateway CLI for Google Drive operations.
+ *
+ * Always outputs JSON. Designed for agent consumption.
+ *
+ * Usage:
+ *   go-drive <account> <command> [args...]
+ *   go-drive marc@blegal.eu ls
+ *   go-drive marc@blegal.eu search "quarterly report"
+ *   go-drive marc@blegal.eu download <fileId>
+ *   go-drive marc@blegal.eu upload ./file.pdf --folder=<folderId>
+ *
+ * Safety:
+ *   Destructive operations (trash, share --anyone, unshare) require --confirm flag.
+ */
+export {};
+//# sourceMappingURL=drive.d.ts.map

package/dist/bin/drive.d.ts.map

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