heinzel-google 0.9.1__tar.gz

heinzel_google-0.9.1/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+.tools/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.pyright/
+.coverage*
+htmlcov/
+node_modules/
+dist/
+release-dist/
+*.egg-info/
+.acceptance/
+.preview/
+.candidates/

heinzel_google-0.9.1/.hypothesis/.gitignore

@@ -0,0 +1,9 @@
+# This .gitignore file was automatically created by Hypothesis. Hypothesis gitignores
+# .hypothesis by default, because we generally recommend that .hypothesis not be checked
+# into version control.
+#
+# If you *would* like to check .hypothesis into version control, you should delete this
+# file. Hypothesis will not re-create this .gitignore unless .hypothesis is deleted (and
+# if it does, that's a bug - please report it!)
+
+*

heinzel_google-0.9.1/.hypothesis/constants/037c2f619c5f5ee0

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/src/heinzel_google/_calendar.py
+# hypothesis_version: 6.170.13
+
+[250, 300, 100000, '#', '(no title)', '+00:00', '.webex.com', '.zoom.us', '?', '@', 'Google Calendar', 'Json', 'Z', '\\', '^[a-z0-9.-]+$', 'accepted', 'all', 'attendees', 'attendeesOmitted', 'busy', 'calendar', 'calendarId', 'calendars', 'cancelled', 'conferenceData', 'conferenceId', 'confirmed', 'createRequest', 'date', 'dateTime', 'declined', 'delete', 'description', 'displayName', 'email', 'end', 'entryPointType', 'entryPoints', 'errors', 'eventId', 'events', 'free and busy times', 'freebusy', 'get', 'guestsCanModify', 'hangoutLink', 'hangoutsMeet', 'htmlLink', 'https', 'id', 'insert', 'items', 'list', 'list[object]', 'location', 'maxResults', 'meet.google.com', 'needsAction', 'none', 'organizer', 'originalStartTime', 'patch', 'pending', 'primary', 'query', 'recurrence', 'requestId', 'resource', 'responseStatus', 'self', 'sendUpdates', 'showDeleted', 'singleEvents', 'start', 'status', 'summary', 'teams.live.com', 'teams.microsoft.com', 'tentative', 'timeMax', 'timeMin', 'timeZone', 'type', 'uri', 'video', 'zoom.us']

heinzel_google-0.9.1/.hypothesis/constants/32d6ed43e73e9c4d

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/src/heinzel_google/_docs.py
+# hypothesis_version: 6.170.13
+
+[1000000, 20000000, '\n---\n', ' --- |', ' |', ' | ', '#', '(', ')', '-', 'Json', 'NONE', 'TITLE', 'Untitled tab', '[', '[ \\t]+', '\\n{3,}', '\\|', ']', 'body', 'bold', 'bullet', 'childTabs', 'content', 'documentTab', 'elements', 'glyphSymbol', 'glyphType', 'horizontalRule', 'http://', 'https://', 'italic', 'link', 'listId', 'listProperties', 'list[object]', 'lists', 'name', 'namedStyleType', 'nestingLevel', 'nestingLevels', 'paragraph', 'paragraphStyle', 'person', 'personProperties', 'richLink', 'richLinkProperties', 'someone', 'tabProperties', 'table', 'tableCells', 'tableRows', 'tabs', 'textRun', 'textStyle', 'title', 'uri', 'url', '|', '| ']

heinzel_google-0.9.1/.hypothesis/constants/4ed33d3d987f61a4

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/.venv/bin/coverage
+# hypothesis_version: 6.170.13
+
+['-script.pyw', '.exe', '__main__']

heinzel_google-0.9.1/.hypothesis/constants/67b0a8ccf18bf5d2

@@ -0,0 +1,4 @@
+# file: /usr/lib/python3.12/sitecustomize.py
+# hypothesis_version: 6.170.13
+
+[]

heinzel_google-0.9.1/.hypothesis/constants/68ca2fef151a93d8

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/src/heinzel_google/_module.py
+# hypothesis_version: 6.170.13
+
+['google']

heinzel_google-0.9.1/.hypothesis/constants/6da411fe19b8f4f4

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/src/heinzel_google/__init__.py
+# hypothesis_version: 6.170.13
+
+[366, 'CALENDAR_HOSTS', 'CALENDAR_WRITE_SCOPE', 'DOCUMENT_HOSTS', 'Drive', 'DriveFile', 'Gmail', 'GoogleAbout', 'GoogleCalendar', 'GoogleDocuments', 'GoogleService', 'GoogleSession', 'GoogleSettings', 'Gws', 'LOGIN', 'LOGIN_WITH_MAIL', 'MAIL_HOSTS', 'MAIL_SCOPE', 'MAIL_WRITE_SCOPE', 'Process', 'SCOPES', 'calendar', 'docs.googleapis.com', 'documents', 'gmail.googleapis.com', 'login_command', 'mail', 'module', 'read', 'write', 'www.googleapis.com']

heinzel_google-0.9.1/.hypothesis/constants/6dcaadd2e5dfed7e

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/src/heinzel_google/_sheets.py
+# hypothesis_version: 6.170.13
+
+[1000000, ' --- |', ' |', ' | ', '(a chart, not read)', '(empty)', 'Json', 'OBJECT', 'Untitled sheet', '\\|', 'data', 'formattedValue', 'list[object]', 'properties', 'rowData', 'sheetType', 'sheets', 'title', 'values', '|', '| ']

heinzel_google-0.9.1/.hypothesis/constants/b17d0304d74d3014

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/src/heinzel_google/_service.py
+# hypothesis_version: 6.170.13
+
+[15.0, '0.0.0', 'Google Drive', 'about', 'bindings', 'calendar', 'dict[str, Any]', 'documents', 'drive', 'drive about get', 'emailAddress', 'fields', 'get', 'google', 'google.com', 'gws', 'heinzel-google', 'mail', 'user', 'your account']

heinzel_google-0.9.1/.hypothesis/constants/b4107e19f0c382e0

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/src/heinzel_google/_models.py
+# hypothesis_version: 6.170.13
+
+[60.0, 600, 'Google Workspace CLI', 'Time limit', 'format', 'gws_path', 'path', 'seconds', 'timeout', 'x-expert', 'x-unit']

heinzel_google-0.9.1/.hypothesis/constants/bbfc298edfa6d48e

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/src/heinzel_google/_mail.py
+# hypothesis_version: 6.170.13
+
+[b'-_', 300.0, 100, 200, 500, 1000, 10000, 2000000, '"', ', ', '-', '-->', '/', '<', '<!--', '=', '>', '@', 'CATEGORY_', 'Cc', 'Content-Type', 'DRAFT', 'From', 'Gmail', 'IMPORTANT', 'INBOX', 'In-Reply-To', 'Json', 'Message-ID', 'References', 'Reply-To', 'STARRED', 'Subject', 'To', 'UNREAD', '\\', '\\n{3,}', '_', '_is_text_encoding', 'addLabelIds', 'ascii', 'blockquote', 'body', 'br', 'cc', 'content-type', 'conversation', 'create', 'data', 'div', 'draft', 'drafts', 'emailAddress', 'filename', 'format', 'from', 'full', 'get', 'getProfile', 'gmail', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'headers', 'hr', 'id', 'internalDate', 'labelIds', 'labels', 'li', 'list', 'list[object]', 'maxResults', 'me', 'message', 'message-id', 'messages', 'metadata', 'metadataHeaders', 'mimeType', 'modify', 'name', 'p', 'parts', 'payload', 'q', 'raw', 'raw_unicode_escape', 're:', 'references', 'removeLabelIds', 'replace', 'reply-to', 'script', 'send', 'spam', 'style', 'subject', 'table', 'template', 'text/html', 'text/plain', 'the labels', 'the new draft', 'threadId', 'threads', 'title', 'to', 'tr', 'trash', 'unicode_escape', 'userId', 'users', 'utf-8', 'value', 'your address']

heinzel_google-0.9.1/.hypothesis/constants/be6ec7ab5c779a4a

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/src/heinzel_google/_gws.py
+# hypothesis_version: 6.170.13
+
+[2.0, 10.0, 100, 300, 400, 401, 403, 404, 409, 429, 500, 65536, 10000000, 25000000, ' google.timeout.', '***', ',', '--format', '--json', '--params', '--version', '.', '.config', '/', ':', 'Gmail', 'HOME', 'HTTPS_PROXY', 'HTTP_PROXY', 'IO[bytes]', 'LANG', 'LC_', 'LOGNAME', 'NODE_EXTRA_CA_CERTS', 'NO_PROXY', 'PATH', 'RATE_LIMIT_EXCEEDED', 'SERVICE_DISABLED', 'SSL_CERT_DIR', 'SSL_CERT_FILE', 'SYSTEMROOT', 'TERM', 'TMPDIR', 'USER', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_RUNTIME_DIR', 'accessNotConfigured', 'calendar', 'client_secret.json', 'code', 'credentials.enc', 'credentials.json', 'details', 'dict[str, Any]', 'error', 'errors', 'gws', 'http_proxy', 'https_proxy', 'hz setup google', 'json', 'list[object]', 'mail', 'message', 'nextPageToken', 'no details', 'no_proxy', 'object', 'pageToken', 'quotaExceeded', 'rateLimitExceeded', 'reason', 'replace', 'retry, or raise']

heinzel_google-0.9.1/.hypothesis/constants/bf69a526b8fa5d9c

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/src/heinzel_google/_documents.py
+# hypothesis_version: 6.170.13
+
+[100, 200, " and name contains '", ' or ', "'", '/open', 'Google Docs', 'Google Drive', 'Google Sheets', '\\', "\\'", '\\\\', 'dict[str, Any]', 'docs', 'docs.google.com', 'document', 'documentId', 'documents', 'drive', 'drive.google.com', 'fields', 'fileId', 'files', 'get', 'https', 'id', 'includeGridData', 'includeTabsContent', 'list', 'mimeType', 'modifiedTime', 'modifiedTime desc', 'name', 'orderBy', 'pageSize', 'properties', 'q', 'revisionId', 'sheets', 'shortcutDetails', 'spreadsheet', 'spreadsheetId', 'spreadsheets', 'supportsAllDrives', 'targetId', 'title', 'version']

heinzel_google-0.9.1/.hypothesis/constants/ca673ccd04b58ff7

@@ -0,0 +1,4 @@
+# file: /home/runner/work/heinzel-plugins/heinzel-plugins/plugins/heinzel-google/src/heinzel_google/_setup.py
+# hypothesis_version: 6.170.13
+
+[900.0, ' only', '?', 'OAuth client', 'automatic', 'calendar', 'configured', 'default', 'documents', 'google', 'gws is signed in.', 'gws_path', 'mail', 'read-only access']

heinzel_google-0.9.1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.9.1
+
+Move this plugin to its independent repository project for the Heinzel 0.9.1 plugin contract.
+Own its dependencies, tests and artifacts; consume public contracts without concrete provider dependencies.
+
+Earlier history is preserved in the source repository named in README.md.

heinzel_google-0.9.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Helmut Hoffer von Ankershoffen
+
+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.

heinzel_google-0.9.1/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.5
+Name: heinzel-google
+Version: 0.9.1
+Summary: Google Docs, Sheets, Drive, Calendar and Gmail: the documents, calendar and mail capabilities.
+Project-URL: Source, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/tree/main/plugins/heinzel-google
+Project-URL: Changelog, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/blob/main/plugins/heinzel-google/CHANGELOG.md
+Project-URL: Issues, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: heinzel<0.10,>=0.9.1
+Description-Content-Type: text/markdown
+
+# heinzel-google
+
+Google Docs, Sheets, Drive, Calendar and Gmail: the `documents` (read), `calendar` and `mail` (read and write)
+capabilities ([ADR 0028](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0028-integrations-are-capability-adapters.md)): a first-party
+[Heinzelmännchen](https://github.com/helmut-hoffer-von-ankershoffen/heinzel) plugin. It is independently released and installed explicitly:
+
+```bash
+hz system plugin add google --confirm             # a compatible plugin release; run it again to upgrade
+hz system plugin remove heinzel-google
+```
+
+It is the **default provider** for Google Workspace, not the only possible one: workflows ask for `documents`,
+`calendar` and `mail`, and any other plugin that provides those capabilities can be bound instead, in configuration.
+
+## How it reaches Google
+
+Through the open-source [Google Workspace CLI](https://github.com/googleworkspace/cli), `gws` (0.22 or newer): it
+signs in with Google, keeps its own credentials (encrypted, with the key in the OS keychain, by default) and calls
+Google's APIs. This plugin never sees a token. It runs `gws <service> <resource> <method> --params <JSON> --format
+json` as an argument list (never through a shell), with the executable resolved to an absolute path, from the root
+directory (so no project's `.env` reaches `gws`), with an allowlisted environment (never Heinzelmännchen's own
+credentials or other secrets; of gws's own variables only `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`, `_KEYRING_BACKEND`,
+`_CLIENT_ID`, `_CLIENT_SECRET` and `GOOGLE_WORKSPACE_PROJECT_ID`, not its token, credentials-file, sanitizing or log
+variables), a
+timeout that stops `gws` and anything it started, and at most 10 MB of output read. Why `gws`:
+[ADR 0042](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0042-google-workspace-through-the-gws-cli.md).
+
+What leaves this machine, and where to: file ids, the Drive query (the modified-time window and the `--name` text)
+the calendar window and the mail search, to Google's API hosts (`www.googleapis.com` for Drive and Calendar,
+`docs.googleapis.com`, `sheets.googleapis.com`, `gmail.googleapis.com`); `gws` also fetches API descriptions from Google and refreshes its sign-in at
+`oauth2.googleapis.com`. Nothing goes anywhere else: gws 0.22 documents no telemetry or update check, and none was
+found in it.
+
+## Set up
+
+Install `gws` (it needs Node.js), give it an OAuth client once (`gws auth setup`, which needs `gcloud`, or a Desktop
+OAuth client as its README describes), then let setup do the rest:
+
+```bash
+npm install -g @googleworkspace/cli
+hz setup google         # finds gws, signs it in, binds documents, calendar and (if you say so) mail
+hz system doctor        # finds gws, checks its version and its stored sign-in, from files; Google isn't contacted
+```
+
+By hand, setup is:
+
+```bash
+gws auth login --scopes https://www.googleapis.com/auth/documents.readonly,https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/drive.metadata.readonly,https://www.googleapis.com/auth/calendar.readonly
+hz system config set capabilities.documents google
+hz system config set capabilities.calendar google
+```
+
+Mail is opt-in: setup asks, defaulting to no, and then signs in again with Gmail's read-only scope added
+(`,https://www.googleapis.com/auth/gmail.readonly`), which lets the plugin read all of your mail; then
+`hz system config set capabilities.mail google`.
+
+Writes are opt-in too. Setup asks whether hz may change your calendar and your mail, defaulting to no; only then does
+the sign-in ask for `https://www.googleapis.com/auth/calendar.events` (create, move, cancel and answer events) and
+`https://www.googleapis.com/auth/gmail.modify` (keep drafts, send them, file conversations; it reads too, so it
+replaces `gmail.readonly`, and it can't delete mail for good). Heinzelmännchen writes only from publish operations
+that show you what they will do and run after you confirm; a chat's agent only proposes them
+([ADR 0059](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0059-the-calendar-and-the-mail-write-through-hz-after-a-confirmation.md)). Without the
+scope, a write fails with the `gws auth login` that adds it.
+
+These are the narrowest read-only scopes for what the adapters do; `drive.metadata.readonly` lists and identifies files
+and never reads their contents (Google classes it as restricted, which matters only for published OAuth clients).
+Bindings go in your user configuration, never in a project `hz.toml`, which Heinzelmännchen ignores for them.
+
+Optional settings, in `[google]` or `HZ_GOOGLE__<FIELD>`: `gws_path`, the absolute path of `gws` when it isn't on
+`PATH` (only absolute `PATH` entries are searched; both are ignored in a project `hz.toml`: a repository someone else
+controls must not choose the program that reads your data), and `timeout`, the seconds each `gws` run may take
+(default 60, also ignored in a project `hz.toml`).
+
+### Is it connected?
+
+Bound automatically to documents and calendar while it is the only installed adapter of them, [ADR
+0055](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0055-connectors-show-their-sign-in-test-live-on-demand-and-bind-themselves-when-alone.md); mail
+never is, so Gmail stays opt-in: `hz setup google` asks. `hz system connector
+list` shows whether gws has a sign-in, from its files alone; `hz system connector
+test google` asks Drive who is signed in (`gws drive about get`, 15 s at most), and only when you run it.
+
+## Use
+
+Workflows ask for `documents` and `calendar`, never for Google:
+
+```python
+from pydantic import AwareDatetime
+
+from heinzel import Calendar, Document, Documents, Event, Module, Window
+
+module = Module("prep", "One-on-one preparation.", requires=["documents:read", "calendar:read"])
+
+
+@module.operation
+def week(calendar: Calendar, since: AwareDatetime, until: AwareDatetime) -> list[Event]:
+    """This week's events."""
+    return calendar.events(Window(since=since, until=until))
+
+
+@module.operation
+def notes(documents: Documents) -> Document:
+    """The running notes, as Markdown."""
+    return documents.read("https://docs.google.com/document/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/edit")
+```
+
+| Method | Capability | `gws` command |
+| --- | --- | --- |
+| `read(ref)` | `documents:read` | `drive files get` (metadata), then `docs documents get` with `includeTabsContent` or `sheets spreadsheets get` with `includeGridData` |
+| `events(window)` | `calendar:read` | `calendar events list` on `primary`, `singleEvents`, `showDeleted`, paged by `pageToken` |
+| `messages(query, window)` | `mail:read` | `gmail users messages list` with Gmail's search, then `messages get` (metadata) for each |
+| `read(message)` | `mail:read` | `gmail users messages get` (full) |
+| `free_busy(people, window)` | `calendar:read` | `calendar freebusy query` for `primary` and each address |
+| `create_event(event)` | `calendar:write` | `calendar events insert` on `primary` with an id of hz's own (no duplicate on a retry), `sendUpdates` as the draft says, a Meet link when asked |
+| `update_event(event, change)` | `calendar:write` | `calendar events get`, then `patch` (only your events, or ones whose guests may change them) |
+| `cancel_event(event, notify)` | `calendar:write` | `calendar events get`, then `delete` (only your events; decline others') |
+| `respond(event, response)` | `calendar:write` | `calendar events get`, then `patch` of your own attendee entry |
+| `thread(thread)` | `mail:read` | `gmail users threads get` (full), without drafts, Spam and Trash |
+| `draft(draft)` | `mail:read` | `gmail users drafts get` (full) |
+| `create_draft(draft)` | `mail:write` | `gmail users drafts create` with a plain-text MIME message; a reply with `threadId`, `In-Reply-To` and `References` |
+| `send_draft(draft, seen)` | `mail:write` | `gmail users drafts get`, then `send` if its message is still the one you saw |
+| `relabel(thread, add, remove)` | `mail:write` | `gmail users threads modify` with label ids; not Spam, Trash, Drafts or Sent |
+
+- **Documents** are a Docs, Sheets or Drive link (`https://docs.google.com/document/d/<id>/...`,
+  `.../spreadsheets/d/<id>/...`, `https://drive.google.com/file/d/<id>/...`, `.../open?id=<id>`) or a bare file id;
+  links to any other host are refused before `gws` runs, and a Drive shortcut is followed once. A Doc comes back as
+  Markdown-flavoured text, every tab under its title: headings, lists, bold and italic, links, tables; person chips by
+  name, never their email, and mail links by their text; titles and link targets can't start a line of their own;
+  images and drawings are left out. A Sheet comes back as one `## <sheet>` table per sheet
+  with the values as people see them. `revision` is the Doc's revision id or the Sheet's Drive version. Uploaded Word
+  or Excel files are refused: open them as a Google Doc or Sheet first.
+- **Events** are your primary calendar's, every occurrence of a recurring event, cancelled ones included, by start.
+  Attendees are display names and emails, without meeting rooms; the workflow packet builder drops the emails before
+  anything reaches an agent's prompt. `conference_id` is the Zoom meeting number when the event has a Zoom link (in
+  its conferencing data, location or description), else the Meet code, so the `meetings` capability can find the
+  event's meeting; conference links are kept only on the conferencing services' own hosts (Meet, Zoom, Teams, Webex),
+  without their query, where passcodes live. A display name that is an address is dropped.
+- **Mail** is your Gmail: `messages` takes the shared query syntax (`from:<address or domain> subject:<text>
+  label:<name>`) and a window. The window and the sender go into Gmail's search and the label as its id; the subject
+  is matched by the plugin, because Gmail's `subject:` matches whole words only. Results come oldest first, at most
+  200 messages a window (one `gws` run each). `read` gives the text part, or the HTML part as text, in the part's own
+  charset, without attachments, and only the headers that carry no addresses. Senders and recipients are names and
+  emails, parsed before any encoded name is decoded, so a display name can't pose as an address; the workflow packet
+  builder drops the addresses before anything reaches an agent's prompt. A message longer than 2 million characters,
+  or with more than 500 MIME parts or 2 million characters of HTML, is refused, not cut; Spam and Trash are not
+  read; reading one window's messages may take at most five minutes.
+- **Writes** change only what the person confirmed, through publish operations. Ids are checked before they reach
+  `gws`; a write that times out or fails without Google refusing it is not retried and says to look in Google first;
+  a rate-limited one is retried. A recurring series' own id is refused: one occurrence changes at a time. Drafts are built with
+  Python's `email` package from plain addresses and one-line subjects, so nothing can add a header.
+- **Text is data.** Every string returned passes `heinzel.clean_text` (no control, invisible or bidirectional
+  characters).
+- **Bounds.** One `gws` run prints at most 10 MB, one call reads at most 100 pages or 25 MB, a Doc's text at most four
+  times its JSON, tables and tabs nest at most 8 deep, a Sheet at most a million cells; past that, an error says to
+  narrow the window or that the file is too large. Rate limits are honoured: a rate-limited call is retried after 1, 2
+  and 4 seconds, then fails saying when to retry.
+
+```bash
+hz google info                  # this plugin, its version, the gws it uses, the scopes and APIs
+hz google files --days 3        # Docs and Sheets you can open that changed in the last three days
+hz system capability list       # who reads what, through which adapter and hosts
+```
+
+Errors say what to do: no `gws` names the install; not signed in or an expired sign-in names the exact
+`gws auth login` command above (doctor names `hz setup google`); a missing scope or a disabled API says which; a file the account can't see says so.
+Token-shaped strings in anything `gws` says are redacted before it is shortened.
+
+Development and release commands: [repository guide](../../README.md).
+
+Migration provenance: heinzel, before the 0.9 plugin-boundary migration.

heinzel_google-0.9.1/README.md

@@ -0,0 +1,169 @@
+# heinzel-google
+
+Google Docs, Sheets, Drive, Calendar and Gmail: the `documents` (read), `calendar` and `mail` (read and write)
+capabilities ([ADR 0028](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0028-integrations-are-capability-adapters.md)): a first-party
+[Heinzelmännchen](https://github.com/helmut-hoffer-von-ankershoffen/heinzel) plugin. It is independently released and installed explicitly:
+
+```bash
+hz system plugin add google --confirm             # a compatible plugin release; run it again to upgrade
+hz system plugin remove heinzel-google
+```
+
+It is the **default provider** for Google Workspace, not the only possible one: workflows ask for `documents`,
+`calendar` and `mail`, and any other plugin that provides those capabilities can be bound instead, in configuration.
+
+## How it reaches Google
+
+Through the open-source [Google Workspace CLI](https://github.com/googleworkspace/cli), `gws` (0.22 or newer): it
+signs in with Google, keeps its own credentials (encrypted, with the key in the OS keychain, by default) and calls
+Google's APIs. This plugin never sees a token. It runs `gws <service> <resource> <method> --params <JSON> --format
+json` as an argument list (never through a shell), with the executable resolved to an absolute path, from the root
+directory (so no project's `.env` reaches `gws`), with an allowlisted environment (never Heinzelmännchen's own
+credentials or other secrets; of gws's own variables only `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`, `_KEYRING_BACKEND`,
+`_CLIENT_ID`, `_CLIENT_SECRET` and `GOOGLE_WORKSPACE_PROJECT_ID`, not its token, credentials-file, sanitizing or log
+variables), a
+timeout that stops `gws` and anything it started, and at most 10 MB of output read. Why `gws`:
+[ADR 0042](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0042-google-workspace-through-the-gws-cli.md).
+
+What leaves this machine, and where to: file ids, the Drive query (the modified-time window and the `--name` text)
+the calendar window and the mail search, to Google's API hosts (`www.googleapis.com` for Drive and Calendar,
+`docs.googleapis.com`, `sheets.googleapis.com`, `gmail.googleapis.com`); `gws` also fetches API descriptions from Google and refreshes its sign-in at
+`oauth2.googleapis.com`. Nothing goes anywhere else: gws 0.22 documents no telemetry or update check, and none was
+found in it.
+
+## Set up
+
+Install `gws` (it needs Node.js), give it an OAuth client once (`gws auth setup`, which needs `gcloud`, or a Desktop
+OAuth client as its README describes), then let setup do the rest:
+
+```bash
+npm install -g @googleworkspace/cli
+hz setup google         # finds gws, signs it in, binds documents, calendar and (if you say so) mail
+hz system doctor        # finds gws, checks its version and its stored sign-in, from files; Google isn't contacted
+```
+
+By hand, setup is:
+
+```bash
+gws auth login --scopes https://www.googleapis.com/auth/documents.readonly,https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/drive.metadata.readonly,https://www.googleapis.com/auth/calendar.readonly
+hz system config set capabilities.documents google
+hz system config set capabilities.calendar google
+```
+
+Mail is opt-in: setup asks, defaulting to no, and then signs in again with Gmail's read-only scope added
+(`,https://www.googleapis.com/auth/gmail.readonly`), which lets the plugin read all of your mail; then
+`hz system config set capabilities.mail google`.
+
+Writes are opt-in too. Setup asks whether hz may change your calendar and your mail, defaulting to no; only then does
+the sign-in ask for `https://www.googleapis.com/auth/calendar.events` (create, move, cancel and answer events) and
+`https://www.googleapis.com/auth/gmail.modify` (keep drafts, send them, file conversations; it reads too, so it
+replaces `gmail.readonly`, and it can't delete mail for good). Heinzelmännchen writes only from publish operations
+that show you what they will do and run after you confirm; a chat's agent only proposes them
+([ADR 0059](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0059-the-calendar-and-the-mail-write-through-hz-after-a-confirmation.md)). Without the
+scope, a write fails with the `gws auth login` that adds it.
+
+These are the narrowest read-only scopes for what the adapters do; `drive.metadata.readonly` lists and identifies files
+and never reads their contents (Google classes it as restricted, which matters only for published OAuth clients).
+Bindings go in your user configuration, never in a project `hz.toml`, which Heinzelmännchen ignores for them.
+
+Optional settings, in `[google]` or `HZ_GOOGLE__<FIELD>`: `gws_path`, the absolute path of `gws` when it isn't on
+`PATH` (only absolute `PATH` entries are searched; both are ignored in a project `hz.toml`: a repository someone else
+controls must not choose the program that reads your data), and `timeout`, the seconds each `gws` run may take
+(default 60, also ignored in a project `hz.toml`).
+
+### Is it connected?
+
+Bound automatically to documents and calendar while it is the only installed adapter of them, [ADR
+0055](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0055-connectors-show-their-sign-in-test-live-on-demand-and-bind-themselves-when-alone.md); mail
+never is, so Gmail stays opt-in: `hz setup google` asks. `hz system connector
+list` shows whether gws has a sign-in, from its files alone; `hz system connector
+test google` asks Drive who is signed in (`gws drive about get`, 15 s at most), and only when you run it.
+
+## Use
+
+Workflows ask for `documents` and `calendar`, never for Google:
+
+```python
+from pydantic import AwareDatetime
+
+from heinzel import Calendar, Document, Documents, Event, Module, Window
+
+module = Module("prep", "One-on-one preparation.", requires=["documents:read", "calendar:read"])
+
+
+@module.operation
+def week(calendar: Calendar, since: AwareDatetime, until: AwareDatetime) -> list[Event]:
+    """This week's events."""
+    return calendar.events(Window(since=since, until=until))
+
+
+@module.operation
+def notes(documents: Documents) -> Document:
+    """The running notes, as Markdown."""
+    return documents.read("https://docs.google.com/document/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/edit")
+```
+
+| Method | Capability | `gws` command |
+| --- | --- | --- |
+| `read(ref)` | `documents:read` | `drive files get` (metadata), then `docs documents get` with `includeTabsContent` or `sheets spreadsheets get` with `includeGridData` |
+| `events(window)` | `calendar:read` | `calendar events list` on `primary`, `singleEvents`, `showDeleted`, paged by `pageToken` |
+| `messages(query, window)` | `mail:read` | `gmail users messages list` with Gmail's search, then `messages get` (metadata) for each |
+| `read(message)` | `mail:read` | `gmail users messages get` (full) |
+| `free_busy(people, window)` | `calendar:read` | `calendar freebusy query` for `primary` and each address |
+| `create_event(event)` | `calendar:write` | `calendar events insert` on `primary` with an id of hz's own (no duplicate on a retry), `sendUpdates` as the draft says, a Meet link when asked |
+| `update_event(event, change)` | `calendar:write` | `calendar events get`, then `patch` (only your events, or ones whose guests may change them) |
+| `cancel_event(event, notify)` | `calendar:write` | `calendar events get`, then `delete` (only your events; decline others') |
+| `respond(event, response)` | `calendar:write` | `calendar events get`, then `patch` of your own attendee entry |
+| `thread(thread)` | `mail:read` | `gmail users threads get` (full), without drafts, Spam and Trash |
+| `draft(draft)` | `mail:read` | `gmail users drafts get` (full) |
+| `create_draft(draft)` | `mail:write` | `gmail users drafts create` with a plain-text MIME message; a reply with `threadId`, `In-Reply-To` and `References` |
+| `send_draft(draft, seen)` | `mail:write` | `gmail users drafts get`, then `send` if its message is still the one you saw |
+| `relabel(thread, add, remove)` | `mail:write` | `gmail users threads modify` with label ids; not Spam, Trash, Drafts or Sent |
+
+- **Documents** are a Docs, Sheets or Drive link (`https://docs.google.com/document/d/<id>/...`,
+  `.../spreadsheets/d/<id>/...`, `https://drive.google.com/file/d/<id>/...`, `.../open?id=<id>`) or a bare file id;
+  links to any other host are refused before `gws` runs, and a Drive shortcut is followed once. A Doc comes back as
+  Markdown-flavoured text, every tab under its title: headings, lists, bold and italic, links, tables; person chips by
+  name, never their email, and mail links by their text; titles and link targets can't start a line of their own;
+  images and drawings are left out. A Sheet comes back as one `## <sheet>` table per sheet
+  with the values as people see them. `revision` is the Doc's revision id or the Sheet's Drive version. Uploaded Word
+  or Excel files are refused: open them as a Google Doc or Sheet first.
+- **Events** are your primary calendar's, every occurrence of a recurring event, cancelled ones included, by start.
+  Attendees are display names and emails, without meeting rooms; the workflow packet builder drops the emails before
+  anything reaches an agent's prompt. `conference_id` is the Zoom meeting number when the event has a Zoom link (in
+  its conferencing data, location or description), else the Meet code, so the `meetings` capability can find the
+  event's meeting; conference links are kept only on the conferencing services' own hosts (Meet, Zoom, Teams, Webex),
+  without their query, where passcodes live. A display name that is an address is dropped.
+- **Mail** is your Gmail: `messages` takes the shared query syntax (`from:<address or domain> subject:<text>
+  label:<name>`) and a window. The window and the sender go into Gmail's search and the label as its id; the subject
+  is matched by the plugin, because Gmail's `subject:` matches whole words only. Results come oldest first, at most
+  200 messages a window (one `gws` run each). `read` gives the text part, or the HTML part as text, in the part's own
+  charset, without attachments, and only the headers that carry no addresses. Senders and recipients are names and
+  emails, parsed before any encoded name is decoded, so a display name can't pose as an address; the workflow packet
+  builder drops the addresses before anything reaches an agent's prompt. A message longer than 2 million characters,
+  or with more than 500 MIME parts or 2 million characters of HTML, is refused, not cut; Spam and Trash are not
+  read; reading one window's messages may take at most five minutes.
+- **Writes** change only what the person confirmed, through publish operations. Ids are checked before they reach
+  `gws`; a write that times out or fails without Google refusing it is not retried and says to look in Google first;
+  a rate-limited one is retried. A recurring series' own id is refused: one occurrence changes at a time. Drafts are built with
+  Python's `email` package from plain addresses and one-line subjects, so nothing can add a header.
+- **Text is data.** Every string returned passes `heinzel.clean_text` (no control, invisible or bidirectional
+  characters).
+- **Bounds.** One `gws` run prints at most 10 MB, one call reads at most 100 pages or 25 MB, a Doc's text at most four
+  times its JSON, tables and tabs nest at most 8 deep, a Sheet at most a million cells; past that, an error says to
+  narrow the window or that the file is too large. Rate limits are honoured: a rate-limited call is retried after 1, 2
+  and 4 seconds, then fails saying when to retry.
+
+```bash
+hz google info                  # this plugin, its version, the gws it uses, the scopes and APIs
+hz google files --days 3        # Docs and Sheets you can open that changed in the last three days
+hz system capability list       # who reads what, through which adapter and hosts
+```
+
+Errors say what to do: no `gws` names the install; not signed in or an expired sign-in names the exact
+`gws auth login` command above (doctor names `hz setup google`); a missing scope or a disabled API says which; a file the account can't see says so.
+Token-shaped strings in anything `gws` says are redacted before it is shortened.
+
+Development and release commands: [repository guide](../../README.md).
+
+Migration provenance: heinzel, before the 0.9 plugin-boundary migration.

heinzel_google-0.9.1/plugin-lock.json

@@ -0,0 +1,41 @@
+{
+  "format": 1,
+  "sdk": 1,
+  "inputs": [
+    "coverage>=7.12",
+    "editables>=0.5",
+    "hatchling>=1.29.0",
+    "heinzel>=0.9.1,<0.10",
+    "hypothesis>=6.150,<7",
+    "mypy>=1.19.0,<3",
+    "pyright[nodejs]==1.1.414",
+    "pytest-timeout>=2.4.0,<3",
+    "pytest-xdist>=3.8",
+    "pytest>=9.0.3,<10",
+    "ruff==0.17.2"
+  ],
+  "core": {
+    "version": "0.9.1",
+    "dependencies": [
+      "croniter>=6.2.4",
+      "fastapi>=0.161",
+      "keyring>=25.6",
+      "mcp>=2.3",
+      "packaging>=25.0",
+      "platformdirs>=4.5",
+      "pluggy<2,>=1.6.0",
+      "psutil==7.2.2",
+      "pydantic-ai-slim==2.61.0",
+      "pydantic-ai-slim[anthropic]==2.61.0; extra == \"anthropic\"",
+      "pydantic-ai-slim[openai]==2.61.0; extra == \"openai\"",
+      "pydantic-settings<3,>=2.11.0",
+      "pydantic<3,>=2.12.0",
+      "pyyaml<7,>=6.0.2",
+      "rich>=14.2.0",
+      "tomlkit>=0.13",
+      "typer>=0.23.0",
+      "uvicorn>=0.54",
+      "wsproto>=1.3"
+    ]
+  }
+}