feat(contacts): add dedupe preview (#555)

Adds a read-only contacts dedupe preview command with JSON/table output, generated command docs, README/spec docs, and changelog credit for the extracted idea from #116.\n\nCo-authored-by: Rohan Patnaik <rohan-patnaik@users.noreply.github.com>

Author: steipete

CHANGELOG.md

@@ -9,6 +9,7 @@
 - Docs: add `docs format` and plain-text `docs write` formatting flags for fonts, colors, bold/italic/underline/strikethrough, alignment, and line spacing. (#479) — thanks @mmaghsoodnia.
 - Drive: add `--fields` to `drive ls` and `drive get` so callers can pass Drive API field masks for fields beyond the default JSON set. (#495) — thanks @karbassi.
 - Drive: add read-only `drive tree`, `drive du`, and `drive inventory` reports for auditing folder contents and sizes. (#116) — thanks @rohan-patnaik.
+- Contacts: add preview-only `contacts dedupe` to find likely duplicate contacts by email/phone, with opt-in name matching and JSON/table merge plans. (#116) — thanks @rohan-patnaik.
 - Sheets: add `sheets table` list/get/create/delete commands for Google Sheets structured tables. (#470) — thanks @Pedrohgv.
 - Agent safety: add baked safety-profile builds for fail-closed agent binaries, with `agent-safe`, `readonly`, and `full` profiles, filtered help/schema output, docs, and build tooling. (#366, #239) — thanks @drewburchfield.
 - Calendar: add `--with-meet` to `calendar update` for adding Google Meet conferencing to existing events. (#538) — thanks @alexisperumal.

README.md

@@ -1324,6 +1324,10 @@ gog contacts get people/<resourceName> --json | \
 
 gog contacts delete people/<resourceName>
 
+# Dedupe preview (read-only)
+gog contacts dedupe
+gog contacts dedupe --match email,phone,name --json
+
 # Workspace directory (requires Google Workspace)
 gog contacts directory list --max 50
 gog contacts directory search "Jane" --max 50

docs/commands.generated.md

@@ -190,6 +190,7 @@ Generated from `gog schema --json`.
     - [`gog config unset (rm,del,remove) <key>`](commands/gog-config-unset.md) - Unset a config value
   - [`gog contacts (contact) <command> [flags]`](commands/gog-contacts.md) - Google Contacts
     - [`gog contacts (contact) create (add,new) [flags]`](commands/gog-contacts-create.md) - Create a contact
+    - [`gog contacts (contact) dedupe [flags]`](commands/gog-contacts-dedupe.md) - Find likely duplicate contacts (preview only)
     - [`gog contacts (contact) delete (rm,del,remove) <resourceName>`](commands/gog-contacts-delete.md) - Delete a contact
     - [`gog contacts (contact) directory <command>`](commands/gog-contacts-directory.md) - Directory contacts
       - [`gog contacts (contact) directory list [flags]`](commands/gog-contacts-directory-list.md) - List people from the Workspace directory

docs/commands/README.md

@@ -2,7 +2,7 @@
 
 Every `gog` command has a generated docs page. The source of truth is the live CLI schema; run `make docs-commands` after changing command names, flags, help text, aliases, or arguments.
 
-Generated pages: 469.
+Generated pages: 470.
 
 ## Top-level Commands
 
@@ -233,6 +233,7 @@ Generated pages: 469.
     - [gog config unset](gog-config-unset.md) - Unset a config value
   - [gog contacts](gog-contacts.md) - Google Contacts
     - [gog contacts create](gog-contacts-create.md) - Create a contact
+    - [gog contacts dedupe](gog-contacts-dedupe.md) - Find likely duplicate contacts (preview only)
     - [gog contacts delete](gog-contacts-delete.md) - Delete a contact
     - [gog contacts directory](gog-contacts-directory.md) - Directory contacts
       - [gog contacts directory list](gog-contacts-directory-list.md) - List people from the Workspace directory

docs/commands/gog-contacts-dedupe.md

@@ -0,0 +1,45 @@
+# `gog contacts dedupe`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Find likely duplicate contacts (preview only)
+
+## Usage
+
+```bash
+gog contacts (contact) dedupe [flags]
+```
+
+## Parent
+
+- [gog contacts](gog-contacts.md)
+
+## Flags
+
+| Flag | Type | Default | Help |
+| --- | --- | --- | --- |
+| `--access-token` | `string` |  | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
+| `-a`<br>`--account`<br>`--acct` | `string` |  | Account email for API commands (gmail/calendar/chat/classroom/drive/docs/slides/contacts/tasks/people/sheets/forms/appscript/ads) |
+| `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
+| `--color` | `string` | auto | Color output: auto\|always\|never |
+| `--disable-commands` | `string` |  | Comma-separated list of disabled commands; dot paths allowed |
+| `-n`<br>`--dry-run`<br>`--dryrun`<br>`--noop`<br>`--preview` | `bool` |  | Do not make changes; print intended actions and exit successfully |
+| `--enable-commands` | `string` |  | Comma-separated list of enabled commands; dot paths allowed (restricts CLI) |
+| `--fail-empty`<br>`--non-empty`<br>`--require-results` | `bool` |  | Exit with code 3 if no duplicates |
+| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` |  | Skip confirmations for destructive commands |
+| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
+| `-h`<br>`--help` | `kong.helpFlag` |  | Show context-sensitive help. |
+| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
+| `--match` | `string` | email,phone | Match fields: email,phone,name |
+| `--max`<br>`--limit` | `int64` | 0 | Max contacts to scan (0 = all) |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
+| `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
+| `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
+| `--version` | `kong.VersionFlag` |  | Print version and exit |
+
+## See Also
+
+- [gog contacts](gog-contacts.md)
+- [Command index](README.md)

docs/commands/gog-contacts.md

@@ -17,6 +17,7 @@ gog contacts (contact) <command> [flags]
 ## Subcommands
 
 - [gog contacts create](gog-contacts-create.md) - Create a contact
+- [gog contacts dedupe](gog-contacts-dedupe.md) - Find likely duplicate contacts (preview only)
 - [gog contacts delete](gog-contacts-delete.md) - Delete a contact
 - [gog contacts directory](gog-contacts-directory.md) - Directory contacts
 - [gog contacts export](gog-contacts-export.md) - Export contacts as vCard (.vcf)

docs/spec.md

@@ -278,6 +278,7 @@ Flag aliases:
 - `gog classroom guardian-invitations get <studentId> <invitationId>`
 - `gog classroom guardian-invitations create <studentId> --email EMAIL`
 - `gog classroom profile [userId]`
+- `gog contacts dedupe [--match email,phone,name] [--max N]`
 - `gog gmail search <query> [--max N] [--page TOKEN]`
 - `gog gmail messages search <query> [--max N] [--page TOKEN] [--include-body] [--body-format text|html] [--full]`
 - `gog gmail autoreply <query> [--max N] [--subject S] [--body B|--body-file PATH|--body-html HTML] [--from addr] [--reply-to addr] [--label L] [--archive] [--mark-read] [--skip-bulk] [--allow-self]`

internal/cmd/contacts.go

@@ -17,6 +17,7 @@ type ContactsCmd struct {
 	List      ContactsListCmd      `cmd:"" name:"list" aliases:"ls" help:"List contacts"`
 	Get       ContactsGetCmd       `cmd:"" name:"get" aliases:"info,show" help:"Get a contact"`
 	Export    ContactsExportCmd    `cmd:"" name:"export" help:"Export contacts as vCard (.vcf)"`
+	Dedupe    ContactsDedupeCmd    `cmd:"" name:"dedupe" help:"Find likely duplicate contacts (preview only)"`
 	Create    ContactsCreateCmd    `cmd:"" name:"create" aliases:"add,new" help:"Create a contact"`
 	Update    ContactsUpdateCmd    `cmd:"" name:"update" aliases:"edit,set" help:"Update a contact"`
 	Delete    ContactsDeleteCmd    `cmd:"" name:"delete" aliases:"rm,del,remove" help:"Delete a contact"`