Adom Google

@@ -0,0 +1,178 @@+---+name: adom-google+description: Programmatic read+write access to a user's WHOLE Google Workspace — Gmail, Contacts, Drive, Sheets, Docs, Slides, Calendar, Tasks, Google Chat — plus a generic `api` passthrough to hit ANY Google API. CLI + OAuth only (no browser automation). Public/open-source; used daily by the Adom team. Auth is the account-specific part: Adom employees use it out of the box; other orgs either self-host their own OAuth gateway or email [email protected] for a managed OAuth container (~$5/mo). On FIRST-RUN SETUP you MUST ask the user to pick safe mode (no delete) vs full mode (incl. delete) before authorizing. Use when setting up/installing adom-google, authorizing Google, reading Gmail attachments/.ics, creating/listing/searching Contacts, editing Sheets/Docs/Slides, Drive files, Calendar events, posting to Google Chat, or any Google Workspace automation. Trigger words — adom-google, install adom-google, set up adom-google, configure adom-google, google workspace cli, edit google sheet/doc/slides, drive upload, calendar event, post to google chat, gmail attachment, google contacts, people api, safe mode vs full mode, google oauth gateway broker, google api passthrough, self-host oauth, managed oauth container.+---++# adom-google++One CLI for a user's Google Workspace from inside an Adom container. **REST-direct** —+it calls the Google APIs straight, owns auth via the **Adom OAuth Gateway**, and stores a+long-lived refresh token `0600`. No browser automation, no per-user Google Cloud project.++```+adom OAuth layer   one shared Adom OAuth client + Gateway redirect → refresh token (0600)+adom-google        modular wrapper: gmail · contacts · (drive/calendar = +1 scope line)+Google REST APIs   called directly (gmail.googleapis.com, people.googleapis.com, …)+```++## Why REST-direct (not a base-CLI shim)++We evaluated wrapping a base CLI — Google's `googleworkspace/cli` (`gws`, Rust,+Discovery-driven, JSON, agent skills), `gog`/`gogcli` (Go), GAM/GAMADV-XTD3, the+Gemini CLI, and `gcloud`. Conclusion: **call the REST APIs directly.**++- **Auth is the part Adom must own anyway.** One shared internal OAuth client + the+  Gateway's static redirect + a long-lived refresh token is Adom-specific; no base CLI+  speaks it. Adopting one means reverse-engineering its keyring/credential format to+  inject our token — more work than one `requests.post` to the token endpoint.+- **The data surface we need is tiny and stable.** gmail.readonly attachment reads + a+  handful of People API calls. Each is one HTTPS request. A base CLI adds a process+  boundary, an install/version dependency, and output coupling for no benefit at this size.+- **No per-user GCP project.** REST-direct with the shared Adom client satisfies the hard+  constraint. `gws`/`gog`/GAM all push users toward their own OAuth client or `gcloud`.+- **Gemini CLI is the wrong layer** (an AI coding agent, not a Workspace data client) and+  **gcloud can't touch Workspace user data** (GCP-only). `gws` is the closest "official"+  Google Workspace CLI and is a reasonable **future accelerator** if we ever need broad+  Sheets/Docs/Chat coverage — but for Gmail+Contacts it's overkill.++The code is structured so a `gws` backend *could* be slotted behind the same subcommands+later; today the win is zero new runtime dependencies and a clean migration from adom-gmail.++## Install++`install.mjs` symlinks the CLI onto PATH automatically. Manual:++```bash+ln -sf <gallia>/skills/adom-google/bin/adom-google ~/.local/bin/adom-google+ln -sf <gallia>/skills/adom-google/bin/adom-gmail   ~/.local/bin/adom-gmail   # deprecation shim+```++Runtime: Python 3 + `requests` (already in the container). The Gateway WebSocket handshake+is implemented in the stdlib (no `ws`/`websockets` package).++## First-run setup — YOU MUST ASK THE USER which mode (REQUIRED)++When setting up adom-google on a user's container for the first time (it's unconfigured —+`adom-google setup` or any command prints a `Hint:` block saying so), **do NOT pick a mode+for them. Ask.** Use `AskUserQuestion` with these two options:++- **Safe mode (recommended default)** — read/organize Gmail, full Contacts, Calendar events,+  Tasks, post+read Google Chat, and only the Drive/Sheets/Docs/Slides files *this app+  creates*. Scopes: `gmail.modify, contacts, calendar.events, tasks, chat.messages,+  chat.spaces.readonly, drive.file`. The Google consent screen shows **no "see & delete ALL+  your files"** — nothing scary.+- **Full mode** — everything safe mode has, but the narrow Drive/Sheets/Docs/Slides/Calendar+  scopes are swapped for broad read/write/**delete** across **all** the user's existing+  files and calendars. Scopes add `drive, spreadsheets, documents, presentations, calendar`.+  Only if they explicitly want full control.++Both modes also expose the generic `adom-google api <url>` passthrough, which can hit **any**+Google API the granted scopes allow (Sheets/Docs/Slides/Drive/Calendar/Chat/Tasks/YouTube/…).++Then run exactly one:+```bash+adom-google auth          # safe mode  (user picked safe)+adom-google auth --full   # full mode  (user picked full — includes delete)+```+The CLI emits this same instruction as `Hint:` lines whenever it's unconfigured, so you'll+be reminded at the exact moment of need even if this skill has been compacted out of context.++## Auth — one consent, long-lived refresh token++```bash+adom-google auth            # SAFE mode (default): no "delete all" on the consent screen+adom-google auth --full     # FULL mode: broad access incl. delete (trusted users)+adom-google auth --manual   # fallback: desktop-client paste flow (combine with --full)+adom-google auth-code '<code>'   # finish --manual+adom-google status          # shows mode + what's authorised (never prints secrets)+```++### How Adom handles the OAuth (Gateway broker flow)++Google requires one fixed `redirect_uri`, but every container has a unique hostname. The+Adom OAuth Gateway gives one static callback for all containers **and** acts as a+confidential-client **token broker**, so the client secret never reaches user containers:++1. `adom-google auth` builds the Google consent URL with+   `redirect_uri = <your gateway>/callback` (from the resolved provider) and a random `state`,+   and opens a WebSocket to the Gateway registering `{state, app:"adom-google", exchange:true}`.+2. The user approves in their browser (their own Google Workspace account).+3. Google redirects to the Gateway `/callback`; the Gateway **does the code→token exchange+   itself** (using the secret it alone holds) and pushes `{type:"tokens", …}` over the WS.+4. The container stores only the **refresh token** `0600` — no client secret. Later refreshes+   go through the gateway's `POST /refresh`, so the secret stays on the gateway forever.++**The package ships NO provider** — no gateway URL, no client_id, nothing Adom-specific. The+provider (`{gateway_url, client_id, app}`) is resolved at runtime, later wins: bundled+`provider.json` → legacy `credentials.json` → `~/.config/adom-google/provider.json` → env+(`OAUTH_GATEWAY_URL`, `ADOM_GOOGLE_CLIENT_ID/SECRET/APP`). With none configured, every command+prints the NO_PROVIDER hint. Adom employees install the private **`adom-google-adom`** package,+which writes the Adom provider (gateway + Internal client_id) to `~/.config/adom-google/provider.json`;+self-hosters run `adom-google provider set --gateway <url> --client-id <id>`. The client secret is+never in any package — in broker mode it lives only on the gateway's `creds/<app>.json` (0600).++If the Gateway is down, `auth --manual` uses a desktop-client loopback paste flow (that one+exchanges locally and does need a client secret via `init`).++### Getting auth as a NON-Adom user (this tool is public)++The code is open source; the OAuth app + gateway are account-specific. If a user is **not**+on Adom's Workspace, the bundled Internal client won't let them sign in — Google blocks+non-adom.inc accounts at consent. Two options to surface to them:++1. **Managed by Adom (easiest):** email **[email protected]** — Adom stands up a dedicated+   OAuth gateway container for their org (~$5/mo) wired to a Google client for their domain;+   they then get the full adom-google capability set, same as the Adom team.+2. **Self-host (DIY):** fork the repo; create their own Google Cloud project + OAuth client+   (Internal to their Workspace), enable the APIs they need, run the open-source OAuth gateway+   (`john/service-oauth`) with their client secret in `creds/<app>.json`, then point the CLI at+   theirs: `adom-google provider set --gateway https://their-gateway --client-id <their-id>`+   (writes `~/.config/adom-google/provider.json`). Google **Chat** also needs a one-time+   Chat-app configuration (name/avatar/description) in the Cloud console's Chat API →+   Configuration tab, or `spaces.*` calls 404 with "Chat app not found".++## Commands++```bash+# Generic passthrough — ANY Google API, signed with the user's token. This is the workhorse:+# Sheets/Docs/Slides/Drive/Calendar/Chat/Tasks/YouTube all go through here, zero per-API code.+adom-google api <url> [-X METHOD] [-d '<json>'|@file] [-q key=val ...] [--raw]+#   e.g. create a sheet:   adom-google api -X POST https://sheets.googleapis.com/v4/spreadsheets -d '{"properties":{"title":"BOM"}}'+#        post to Chat:      adom-google api -X POST https://chat.googleapis.com/v1/spaces/<id>/messages -d '{"text":"shipped"}'+#        calendar event:    adom-google api -X POST https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all -d '{...}'++# Gmail (read; behaviour-compatible with old adom-gmail)+adom-google gmail attachments <messageId>+adom-google gmail read <messageId> <attachmentId> [-o file]+adom-google gmail ics  <messageId>++# Contacts (People API; read + write)+adom-google contacts create --name "First Last" [--org O] [--title T] \+    [--email [email protected] ...] [--phone +1... ...] [--notes "..."] [--json]+adom-google contacts list [--limit N] [--json]+adom-google contacts search <query> [-v] [--json]++adom-google status     # mode (safe/full) + what's authorized (never prints secrets)+```++We use Google Contacts to store **service identities** (portal/account metadata for an API+vendor), e.g. the JPMorgan Payments developer portal. Keep secrets (client secrets, portal+passwords) in a password manager — **never** in a contact's notes.++## Adding Drive / Calendar++Add the scope to `SCOPES` at the top of `bin/adom-google`, re-run `adom-google auth`, and+add a few REST calls against `www.googleapis.com/drive/v3` or `/calendar/v3`. Token refresh+and the `_request()` helper are already generic.++## Security++- Config `~/.config/adom-google/config.json` is created `0600`; the client secret and+  refresh token are never echoed to stdout/stderr or logs (`status` prints presence only).+- The Gateway only ever sees the short-lived auth `code`, never tokens or the client secret.++## Migration from adom-gmail++See [MIGRATION.md](MIGRATION.md). Short version: `adom-gmail` is now a forwarding shim;+its old `~/.config/adom-gmail/config.json` is auto-imported on first `adom-google` run+(gmail.readonly only — run `adom-google auth` once to add the `contacts` scope).