feat(docs): add find-range command

Author: steipete

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Added
 
 - Chat: add repeatable `--attach` to `chat messages send` for sending local files with Google Chat messages. (#694) — thanks @omothm.
+- Docs: add `docs find-range` to map matched text to Docs API UTF-16 index ranges. (#682) — thanks @sebsnyk.
 - Docs: add `--link` and `--no-link` to `docs format` for setting or clearing hyperlinks on matched text. (#684) — thanks @sebsnyk.
 - Slides: add `slides insert-image` to place a positioned, sized local image on an existing slide. (#695) — thanks @Czaruno.
 

docs/commands.generated.md

@@ -237,6 +237,7 @@ Generated from `gog schema --json`.
     - [`gog docs (doc) delete-tab <docId> [flags]`](commands/gog-docs-delete-tab.md) - Delete a tab from a Google Doc
     - [`gog docs (doc) edit <docId> <find> <replace> [flags]`](commands/gog-docs-edit.md) - Find and replace text in a Google Doc
     - [`gog docs (doc) export (download,dl) <docId> [flags]`](commands/gog-docs-export.md) - Export a Google Doc (pdf|docx|txt|md|html)
+    - [`gog docs (doc) find-range <docId> <text> [flags]`](commands/gog-docs-find-range.md) - Find text and print Docs API UTF-16 index ranges
     - [`gog docs (doc) find-replace <docId> <find> [<replace>] [flags]`](commands/gog-docs-find-replace.md) - Find and replace text. Supports plain text or markdown with images; use --first for a single occurrence.
     - [`gog docs (doc) format <docId> [flags]`](commands/gog-docs-format.md) - Apply text or paragraph formatting to a Google Doc
     - [`gog docs (doc) info (get,show) <docId>`](commands/gog-docs-info.md) - Get Google Doc metadata

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: 584.
+Generated pages: 585.
 
 ## Top-level Commands
 
@@ -289,6 +289,7 @@ Generated pages: 584.
     - [gog docs delete-tab](gog-docs-delete-tab.md) - Delete a tab from a Google Doc
     - [gog docs edit](gog-docs-edit.md) - Find and replace text in a Google Doc
     - [gog docs export](gog-docs-export.md) - Export a Google Doc (pdf|docx|txt|md|html)
+    - [gog docs find-range](gog-docs-find-range.md) - Find text and print Docs API UTF-16 index ranges
     - [gog docs find-replace](gog-docs-find-replace.md) - Find and replace text. Supports plain text or markdown with images; use --first for a single occurrence.
     - [gog docs format](gog-docs-format.md) - Apply text or paragraph formatting to a Google Doc
     - [gog docs info](gog-docs-info.md) - Get Google Doc metadata

docs/commands/gog-docs-find-range.md

@@ -0,0 +1,51 @@
+# `gog docs find-range`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Find text and print Docs API UTF-16 index ranges
+
+## Usage
+
+```bash
+gog docs (doc) find-range <docId> <text> [flags]
+```
+
+## Parent
+
+- [gog docs](gog-docs.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/drivelabels/docs/slides/contacts/tasks/people/sheets/forms/sites/appscript/analytics/searchconsole/youtube/photos) |
+| `--all` | `bool` |  | Return all matches |
+| `--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 command prefixes; dot paths allowed (restricts CLI) |
+| `--enable-commands-exact` | `string` |  | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
+| `--fail-empty`<br>`--non-empty`<br>`--require-results` | `bool` |  | Exit with code 3 if no matches |
+| `-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. |
+| `--home` | `string` |  | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
+| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
+| `--match-case` | `bool` |  | Use case-sensitive matching |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `--normalize-whitespace` | `bool` | true | Collapse whitespace while matching |
+| `--occurrence` | `*int` |  | Return the Nth occurrence (1-based; default first) |
+| `-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. |
+| `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
+| `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
+| `--version` | `kong.VersionFlag` |  | Print version and exit |
+| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
+
+## See Also
+
+- [gog docs](gog-docs.md)
+- [Command index](README.md)

docs/commands/gog-docs.md

@@ -28,6 +28,7 @@ gog docs (doc) <command> [flags]
 - [gog docs delete-tab](gog-docs-delete-tab.md) - Delete a tab from a Google Doc
 - [gog docs edit](gog-docs-edit.md) - Find and replace text in a Google Doc
 - [gog docs export](gog-docs-export.md) - Export a Google Doc (pdf|docx|txt|md|html)
+- [gog docs find-range](gog-docs-find-range.md) - Find text and print Docs API UTF-16 index ranges
 - [gog docs find-replace](gog-docs-find-replace.md) - Find and replace text. Supports plain text or markdown with images; use --first for a single occurrence.
 - [gog docs format](gog-docs-format.md) - Apply text or paragraph formatting to a Google Doc
 - [gog docs info](gog-docs-info.md) - Get Google Doc metadata

internal/cmd/docs.go

@@ -41,6 +41,7 @@ type DocsCmd struct {
 	InsertDateChip   DocsInsertDateChipCmd   `cmd:"" name:"insert-date-chip" help:"Insert a native date smart chip"`
 	InsertPageBreak  DocsInsertPageBreakCmd  `cmd:"" name:"insert-page-break" aliases:"page-break,pb" help:"Insert a page break at a specific position (or end-of-doc with --at-end)"`
 	Delete           DocsDeleteCmd           `cmd:"" name:"delete" help:"Delete text range from document"`
+	FindRange        DocsFindRangeCmd        `cmd:"" name:"find-range" help:"Find text and print Docs API UTF-16 index ranges"`
 	FindReplace      DocsFindReplaceCmd      `cmd:"" name:"find-replace" help:"Find and replace text. Supports plain text or markdown with images; use --first for a single occurrence."`
 	Update           DocsUpdateCmd           `cmd:"" name:"update" help:"Insert or replace text at a specific index or range in a Google Doc"`
 	Edit             DocsEditCmd             `cmd:"" name:"edit" help:"Find and replace text in a Google Doc"`