feat(docs): add advanced document tools#278
feat(docs): add advanced document tools#278oskarcode wants to merge 4 commits intogemini-cli-extensions:mainfrom
Conversation
…eateHeaderFooter, addComment)
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly expands the Google Docs integration by introducing a suite of advanced document manipulation tools. These additions empower users to programmatically insert images and tables, manage headers and footers, and add comments within Google Docs, thereby enhancing automation and content generation workflows. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces four new tools for advanced document manipulation in Google Docs: insertImage, insertTable, createHeaderFooter, and addComment. The implementation is solid, but I've identified a few areas for improvement. Specifically, there's a high-severity issue with image resizing that could cause distortion, some code duplication that affects maintainability, and a minor inconsistency in calculating insertion points. My review includes suggestions to address these points.
| if (widthPt || heightPt) { | ||
| imageRequest.insertInlineImage!.objectSize = { | ||
| width: widthPt | ||
| ? { magnitude: widthPt, unit: 'PT' } | ||
| : { magnitude: 300, unit: 'PT' }, | ||
| height: heightPt | ||
| ? { magnitude: heightPt, unit: 'PT' } | ||
| : { magnitude: 200, unit: 'PT' }, | ||
| }; | ||
| } |
There was a problem hiding this comment.
The current logic for setting the image size can lead to distorted images. If only widthPt is provided, a default heightPt of 200 is used, and vice-versa. This will not preserve the image's aspect ratio. The code should only set the dimensions that are explicitly provided by the user, allowing the Docs API to scale the other dimension to maintain the aspect ratio.
| if (widthPt || heightPt) { | |
| imageRequest.insertInlineImage!.objectSize = { | |
| width: widthPt | |
| ? { magnitude: widthPt, unit: 'PT' } | |
| : { magnitude: 300, unit: 'PT' }, | |
| height: heightPt | |
| ? { magnitude: heightPt, unit: 'PT' } | |
| : { magnitude: 200, unit: 'PT' }, | |
| }; | |
| } | |
| if (widthPt || heightPt) { | |
| const objectSize: docs_v1.Schema$Size = {}; | |
| if (widthPt) { | |
| objectSize.width = { magnitude: widthPt, unit: 'PT' }; | |
| } | |
| if (heightPt) { | |
| objectSize.height = { magnitude: heightPt, unit: 'PT' }; | |
| } | |
| imageRequest.insertInlineImage!.objectSize = objectSize; | |
| } |
| if (!insertIndex) { | ||
| const res = await docs.documents.get({ | ||
| documentId: id, | ||
| fields: 'tabs', | ||
| includeTabsContent: true, | ||
| }); | ||
| const tabs = res.data.tabs || []; | ||
| let content: docs_v1.Schema$StructuralElement[] | undefined; | ||
| if (tabId) { | ||
| const tab = tabs.find((t) => t.tabProperties?.tabId === tabId); | ||
| if (!tab) { | ||
| throw new Error(`Tab with ID ${tabId} not found.`); | ||
| } | ||
| content = tab.documentTab?.body?.content; | ||
| } else if (tabs.length > 0) { | ||
| content = tabs[0].documentTab?.body?.content; | ||
| } | ||
| const lastElement = content?.[content.length - 1]; | ||
| const endIndex = lastElement?.endIndex || 2; | ||
| insertIndex = Math.max(1, endIndex - 1); | ||
| } |
There was a problem hiding this comment.
This logic to determine the insertIndex when it's not provided is duplicated in the insertTable function (lines 778-798). To improve maintainability and avoid future inconsistencies, consider extracting this logic into a private helper method. This will make the code more DRY (Don't Repeat Yourself).
| content = tabs[0].documentTab?.body?.content; | ||
| } | ||
| const lastElement = content?.[content.length - 1]; | ||
| const endIndex = lastElement?.endIndex || 2; |
There was a problem hiding this comment.
There's an inconsistency in how the default endIndex is calculated here compared to the existing writeText function. This line uses || 2, while writeText uses || 1 (see line 330 in the full file). To ensure predictable behavior and maintain consistency, it would be best to align this with the existing pattern.
| const endIndex = lastElement?.endIndex || 2; | |
| const endIndex = lastElement?.endIndex || 1; |
| content = tabs[0].documentTab?.body?.content; | ||
| } | ||
| const lastElement = content?.[content.length - 1]; | ||
| const endIndex = lastElement?.endIndex || 2; |
There was a problem hiding this comment.
Similar to the insertImage function, there's an inconsistency here in calculating the default endIndex (|| 2) compared to the existing writeText function (|| 1 on line 330). Please align this for consistency.
| const endIndex = lastElement?.endIndex || 2; | |
| const endIndex = lastElement?.endIndex || 1; |
- Add detailed logging for image dimension handling to preserve aspect ratio - Extract duplicate insertIndex calculation logic into reusable helper method - Consolidate identical logic between insertImage and insertTable methods - Add comprehensive documentation for aspect ratio preservation behavior - Improve code maintainability and reduce duplication
| */ | ||
|
|
||
| import { google, docs_v1 } from 'googleapis'; | ||
| import { google, docs_v1, drive_v3 } from 'googleapis'; |
There was a problem hiding this comment.
See #255 we are keeping a strict seperation of concerns for oauth scopes. All of our commenting features (which require the drive scope and api) are in the drive.* namespace. Please move commenting features there.
There was a problem hiding this comment.
Thanks for the feedback.
- Removed Drive/comment-specific pieces from DocsService
allenhutchison
left a comment
allenhutchison
left a comment
There was a problem hiding this comment.
Thanks for this PR! These are great additions to the Docs toolset. I did a review and have some feedback — mostly small things, with a couple of items worth addressing before merge.
Must Fix
1. _calculateInsertionIndex should flatten nested tabs
The new helper searches res.data.tabs directly without calling this._flattenTabs(), but every other tab-aware method in the class (writeText, getText, replaceText) flattens the tab tree first. This means insertImage and insertTable will throw "Tab not found" for any nested/child tab.
- const tabs = res.data.tabs || [];
+ const tabs = this._flattenTabs(res.data.tabs || []);2. createHeaderFooter silently drops text when segmentId is missing
If the API doesn't return a headerId/footerId for some reason, the if (text && segmentId) check silently skips text insertion and reports success. The user asked for a header with text but gets one without — and no indication anything went wrong.
Could we surface this as an error instead?
if (text && !segmentId) {
throw new Error(
`Created ${type} but could not retrieve its ID from the API response. The provided text was not inserted.`,
);
}Should Fix
3. Consider adding isError: true to error responses
The existing getSuggestions method includes isError: true in its error return, which is the MCP-correct way to signal tool failures to clients. The new methods omit it. Worth adding for consistency (or removing from getSuggestions if the project intentionally omits it — but including it everywhere is the better practice).
4. Aspect ratio comment may be misleading
The comment at line 725 says "Google Docs API will automatically preserve aspect ratio" when only one dimension is provided, and the log messages repeat this claim. I don't believe this is a documented API guarantee — the behavior when only one dimension is specified isn't well-defined. Maybe soften to something like:
// Only set explicit dimensions if provided. If only one dimension is given,
// the API behavior for the missing dimension is not well-documented.5. imageUrl could use .url() validation
Small one — z.string() for imageUrl could be z.string().url() to catch invalid URLs at the schema level instead of producing a confusing API error downstream.
Nits (take or leave)
rows/columnsschema could benefit from a.max()to prevent opaque API failures with huge tableswidthPt || heightPton line 727 treats0as "not provided" —!== undefinedwould be more precise- The
_calculateInsertionIndexJSDoc doesn't mention thetabIdparameter - Line 150 uses
|| 1where?? 1would be more semantically correct (handlesendIndex: 0)
Overall this is solid work — the _calculateInsertionIndex extraction is a nice cleanup, and the createHeaderFooter approach with endOfSegmentLocation is well done. Looking forward to getting these tools in! 🎉
2 participants
Summary
Adds four new Google Docs tools for advanced document manipulation.
New Tools
docs.insertImageInserts an image into a Google Doc at a specified position or at the end of the document.
documentId,imageUrl,positionIndex(optional),tabId(optional),widthPt(optional),heightPt(optional)docs.insertTableInserts a table into a Google Doc at a specified position or at the end of the document.
documentId,rows,columns,tabId(optional),positionIndex(optional)docs.createHeaderFooterCreates a header or footer in a Google Doc with optional initial text.
documentId,type("header" or "footer"),text(optional)docs.addCommentAdds a comment to a Google Doc's comment thread.
documentId,contentChanges
insertImage,insertTable,createHeaderFooter,addCommentmethods toDocsService.tsgetDriveClienthelper method for Drive API access (needed byaddComment)index.tsTesting
Tested locally with Google Docs documents.