Merge branch 'origin/main' into fix/issue-126-iso-2022-jpr

Author: Peter Steinberger

AGENTS.md

@@ -19,6 +19,7 @@
 
 - Formatting: `make fmt` (`goimports` local prefix `github.com/steipete/gogcli` + `gofumpt`).
 - Output: keep stdout parseable (`--json` / `--plain`); send human hints/progress to stderr.
+- Gmail labels: treat label IDs as case-sensitive opaque tokens; only case-fold label names for name lookup.
 
 ## Testing Guidelines
 

README.md

@@ -106,5 +106,4 @@ gog --help
 ```
 
 ## Notes
-- `gog` currently does not print a version string; use tags + changelog as the source of truth.
-- If you later add `gog version`, update this doc to validate `gog version` post-install.
+- `gog --version` / `gog version` should report the release version post-install.

docs/RELEASING.md

@@ -0,0 +1,56 @@
+# Update Contacts From JSON
+
+`gog contacts update` supports JSON input via `--from-file`, so you can update People API fields without adding new CLI flags.
+
+## Usage
+
+Update from a file:
+
+```bash
+gog contacts get people/c123456 --json > contact.json
+
+# Edit contact.json (see notes below)
+gog contacts update people/c123456 --from-file contact.json
+```
+
+Update from stdin:
+
+```bash
+gog contacts get people/c123456 --json | \
+  jq '(.contact.urls //= []) | (.contact.urls += [{"value":"https://example.com","type":"profile"}])' | \
+  gog contacts update people/c123456 --from-file -
+```
+
+## Input Formats
+
+The command accepts:
+
+- Wrapped (from `gog contacts get --json`): `{"contact": { ...person... }}`
+- Direct Person object: `{ ...person... }`
+
+## What Can Be Updated
+
+`--from-file` updates only fields that the People API allows via `people.updateContact` `updatePersonFields`.
+
+Practical rule: include only fields you want to change, at the top level of the JSON object (for example `urls`, `biographies`, `names`, `emailAddresses`, `phoneNumbers`, `addresses`, `organizations`, ...).
+
+If the JSON contains unsupported fields (for `updateContact`), gog errors instead of silently ignoring them.
+
+Notes:
+
+- Some fields are “singleton” for contact sources. Don’t include more than one value for `biographies`, `birthdays`, `genders`, or `names`.
+- If you update `memberships`, the Person must include contact group memberships or the API will error.
+
+## Clearing Fields
+
+Clearing list fields is supported by including the key with an empty value:
+
+- Use `[]` to clear a list field (example: `"urls": []`)
+- Use `null` to clear a list field (example: `"biographies": null`)
+
+## Concurrency (ETags)
+
+To avoid overwriting concurrent contact edits, gog compares the JSON etag with the current contact etag:
+
+- If they mismatch, update fails with an etag error.
+- Use `--ignore-etag` to apply your JSON changes to the latest version anyway.

docs/contacts-json-update.md

@@ -0,0 +1,38 @@
+# Date and Time Input Formats
+
+Use one parsing contract across commands.
+
+## Canonical choices
+
+- Prefer `RFC3339` in automation: `2026-02-13T15:04:05Z`
+- Use `YYYY-MM-DD` for date-only fields (birthdays, date-only due values)
+- Keep timezone explicit when time matters
+
+## Accepted input formats
+
+- Date-only: `YYYY-MM-DD`
+- Datetime: `RFC3339` / `RFC3339Nano`
+- ISO offset without colon: `YYYY-MM-DDTHH:MM:SS-0800`
+- Local datetime (no timezone):
+  - `YYYY-MM-DDTHH:MM[:SS]`
+  - `YYYY-MM-DD HH:MM[:SS]`
+
+## Relative forms
+
+Calendar range flags (`--from` / `--to`) also accept:
+
+- `now`, `today`, `tomorrow`, `yesterday`
+- Weekday names: `monday`, `next friday`
+
+## Duration forms
+
+Tracking `--since` also accepts `time.ParseDuration` values such as:
+
+- `24h`
+- `15m`
+
+## Agent guidance
+
+- Generate RFC3339 for all datetime fields by default.
+- Use date-only for fields explicitly documented as dates.
+- For local scheduling, pass an explicit offset (or timezone-aware RFC3339) to avoid ambiguity.

docs/dates.md

@@ -27,3 +27,13 @@ Use `internal/cmd/output_helpers.go:printNextPageHint(u, token)`:
 
 - prints to stderr
 - exact format (tests depend on it): `# Next page: --page <token>`
+
+## Result (Key-Value) Output
+
+Use `internal/cmd/output_helpers.go:writeResult(ctx, u, ...)` for simple command results (especially destructive operations).
+
+Rules:
+
+- Same keys in `--plain` and `--json` (no snake_case vs camelCase split).
+- Prefer explicit booleans for flags (e.g. `deleted`, `removed`, `trashed`).
+- Include primary identifiers (`id`, `fileId`, etc) as separate keys.

docs/refactor/output.md

@@ -6,9 +6,17 @@ Build a single, clean, modern Go CLI that talks to:
 
 - Gmail API
 - Google Calendar API
+- Google Chat API
 - Google Classroom API
 - Google Drive API
+- Google Docs API
+- Google Sheets API
+- Google Forms API
+- Apps Script API
+- Google Tasks API
+- Cloud Identity API (Groups)
 - Google People API (Contacts + directory)
+- Google Keep API (Workspace-only, service account)
 
 This replaces the existing separate CLIs (`gmcli`, `gccli`, `gdcli`) and the Python contacts server conceptually, but:
 
@@ -99,6 +107,9 @@ Implementation: `internal/secrets/store.go`.
 
 - Desktop OAuth 2.0 flow using local HTTP redirect on an ephemeral port.
 - Supports a browserless/manual flow (paste redirect URL) for headless environments.
+- Supports a remote/server-friendly 2-step manual flow:
+  - Step 1 prints an auth URL (`gog auth add ... --remote --step 1`)
+  - Step 2 exchanges the pasted redirect URL and requires `state` validation (`--remote --step 2 --auth-url ...`)
 - Refresh token issuance:
   - requests `access_type=offline`
   - supports `--force-consent` to force the consent prompt when Google doesn't return a refresh token
@@ -119,6 +130,7 @@ Scope selection note:
   - `credentials-<client>.json` (OAuth client id/secret; named clients)
 - State:
   - `state/gmail-watch/<account>.json` (Gmail watch state)
+  - `oauth-manual-state-<state>.json` (temporary manual OAuth state cache; expires quickly; no tokens)
 - Secrets:
   - refresh tokens in keyring
 
@@ -148,7 +160,7 @@ Flag aliases:
 - `gog auth credentials <credentials.json|->`
 - `gog auth credentials list`
 - `gog --client <name> auth credentials <credentials.json|->`
-- `gog auth add <email> [--services user|all|gmail,calendar,classroom,drive,docs,contacts,tasks,sheets,people,groups] [--readonly] [--drive-scope full|readonly|file] [--manual] [--force-consent]`
+- `gog auth add <email> [--services user|all|gmail,calendar,classroom,drive,docs,contacts,tasks,sheets,people,groups] [--readonly] [--drive-scope full|readonly|file] [--manual] [--remote] [--step 1|2] [--auth-url URL] [--timeout DURATION] [--force-consent]`
 - `gog auth services [--markdown]`
 - `gog auth keep <email> --key <service-account.json>` (Google Keep; Workspace only)
 - `gog auth list`
@@ -165,16 +177,17 @@ Flag aliases:
 - `gog config path`
 - `gog config set <key> <value>`
 - `gog config unset <key>`
-- `gog drive ls [--parent ID] [--max N] [--page TOKEN] [--query Q]`
-- `gog drive search <text> [--max N] [--page TOKEN]`
+- `gog version`
+- `gog drive ls [--parent ID] [--max N] [--page TOKEN] [--query Q] [--[no-]all-drives]`
+- `gog drive search <text> [--raw-query] [--max N] [--page TOKEN] [--[no-]all-drives]`
 - `gog drive get <fileId>`
-- `gog drive download <fileId> [--out PATH]`
-- `gog drive upload <localPath> [--name N] [--parent ID]`
+- `gog drive download <fileId> [--out PATH] [--format F]` (`--format` only applies to Google Workspace files)
+- `gog drive upload <localPath> [--name N] [--parent ID] [--convert] [--convert-to doc|sheet|slides]`
 - `gog drive mkdir <name> [--parent ID]`
-- `gog drive delete <fileId>`
+- `gog drive delete <fileId> [--permanent]`
 - `gog drive move <fileId> --parent ID`
 - `gog drive rename <fileId> <newName>`
-- `gog drive share <fileId> [--anyone | --email addr] [--role reader|writer] [--discoverable]`
+- `gog drive share <fileId> --to anyone|user|domain [--email addr] [--domain example.com] [--role reader|writer] [--discoverable]`
 - `gog drive permissions <fileId> [--max N] [--page TOKEN]`
 - `gog drive unshare <fileId> <permissionId>`
 - `gog drive url <fileIds...>`
@@ -291,7 +304,7 @@ Flag aliases:
 - `gog contacts list [--max N] [--page TOKEN]`
 - `gog contacts get <people/...|email>`
 - `gog contacts create --given NAME [--family NAME] [--email addr] [--phone num]`
-- `gog contacts update <people/...> [--given NAME] [--family NAME] [--email addr] [--phone num]`
+- `gog contacts update <people/...> [--given NAME] [--family NAME] [--email addr] [--phone num] [--birthday YYYY-MM-DD] [--notes TEXT] [--from-file PATH|-] [--ignore-etag]`
 - `gog contacts delete <people/...>`
 - `gog contacts directory list [--max N] [--page TOKEN]`
 - `gog contacts directory search <query> [--max N] [--page TOKEN]`
@@ -302,6 +315,14 @@ Flag aliases:
 - `gog people search <query> [--max N] [--page TOKEN]`
 - `gog people relations [<people/...|userId>] [--type TYPE]`
 
+Date/time input conventions (shared parser):
+
+- Date-only: `YYYY-MM-DD`
+- Datetime: `RFC3339` / `RFC3339Nano` / `YYYY-MM-DDTHH:MM[:SS]` / `YYYY-MM-DD HH:MM[:SS]`
+- Numeric timezone offset accepted: `YYYY-MM-DDTHH:MM:SS-0800`
+- Calendar range flags also accept relatives: `now`, `today`, `tomorrow`, `yesterday`, weekday names (`monday`, `next friday`)
+- Tracking `--since` also accepts durations like `24h`
+
 ### Planned high-level command tree
 
 - `gog auth …`

docs/spec.md

@@ -48,7 +48,8 @@ gog gmail watch serve \
   [--verify-oidc] [--oidc-email <svc@...>] [--oidc-audience <aud>] \
   [--token <shared>] \
   [--hook-url <url>] [--hook-token <token>] \
-  [--include-body] [--max-bytes <n>] [--save-hook]
+  [--include-body] [--max-bytes <n>] [--exclude-labels <id,id,...>] \
+  [--history-types <type>...] [--save-hook]
 
 gog gmail history --since <historyId> [--max <n>] [--page <token>]
 ```
@@ -58,6 +59,10 @@ Notes:
 - `watch renew` reuses stored topic/labels.
 - `watch stop` calls Gmail stop + clears state.
 - `watch serve` uses stored hook if `--hook-url` not provided.
+- `watch serve --exclude-labels` defaults to `SPAM,TRASH`; set to an empty string to disable.
+- Exclude label IDs are matched exactly (case-sensitive opaque IDs).
+- `watch serve --history-types` accepts `messageAdded`, `messageDeleted`, `labelAdded`, `labelRemoved` (repeatable or comma-separated). Default: `messageAdded` (for backward compatibility).
+- `watch serve --history-types` must include at least one non-empty type.
 
 ## State
 
@@ -95,6 +100,7 @@ Schema (v1):
   "source": "gmail",
   "account": "you@gmail.com",
   "historyId": "...",
+  "deletedMessageIds": ["..."],
   "messages": [
     {
       "id": "...",

docs/watch.md

@@ -1,12 +1,13 @@
 module github.com/steipete/gogcli
 
-go 1.25
+go 1.24.0
 
 require (
 	github.com/99designs/keyring v1.2.2
 	github.com/alecthomas/kong v1.13.0
 	github.com/muesli/termenv v0.16.0
 	github.com/yosuke-furukawa/json5 v0.1.1
+	golang.org/x/net v0.49.0
 	golang.org/x/oauth2 v0.34.0
 	golang.org/x/term v0.39.0
 	google.golang.org/api v0.260.0
@@ -40,7 +41,6 @@ require (
 	go.opentelemetry.io/otel/metric v1.39.0 // indirect
 	go.opentelemetry.io/otel/trace v1.39.0 // indirect
 	golang.org/x/crypto v0.47.0 // indirect
-	golang.org/x/net v0.49.0 // indirect
 	golang.org/x/sys v0.40.0 // indirect
 	golang.org/x/text v0.33.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260114163908-3f89685c29c3 // indirect

go.mod

@@ -0,0 +1,6 @@
+package cmd
+
+// AgentCmd contains helper commands intended to make gog easier to consume from LLM agents.
+type AgentCmd struct {
+	ExitCodes AgentExitCodesCmd `cmd:"" name:"exit-codes" aliases:"exitcodes,exit-code" help:"Print stable exit codes for automation"`
+}