[ { "path": ".gemini/skills/code-reviewer/SKILL.md", "content": "---\nname: code-reviewer\ndescription:\n Use this skill to review code. It supports both local changes (staged or\n working tree) and remote Pull Requests (by ID or URL). It focuses on\n correctness, maintainability, and adherence to project standards.\n---\n\n# Code Reviewer\n\nThis skill guides the agent in conducting professional and thorough code reviews\nfor both local development and remote Pull Requests.\n\n## Workflow\n\n### 1. Determine Review Target\n\n- **Remote PR**: If the user provides a PR number or URL (e.g., \"Review PR\n #123\"), target that remote PR.\n- **Local Changes**: If no specific PR is mentioned, or if the user asks to\n \"review my changes\", target the current local file system states (staged and\n unstaged changes).\n\n### 2. Preparation\n\n#### For Remote PRs:\n\n1. **Checkout**: Use the GitHub CLI to checkout the PR.\n ```bash\n gh pr checkout \n ```\n2. **Verification**: Execute the workspace's verification suite to catch issues\n early. Capture the output of these commands to inform your review (e.g.,\n note any failed tests or linting errors).\n ```bash\n npm install\n npm run build\n npm run test\n npm run lint\n npm run format:check\n ```\n3. **Context**: Read the PR description and any existing comments to understand\n the goal and history.\n\n#### For Local Changes:\n\n1. **Identify Changes**:\n - Check status: `git status`\n - Read diffs: `git diff` (working tree) and/or `git diff --staged` (staged).\n2. **Verification**: Ask the user if they want to run the verification suite\n before reviewing. If yes, run the same commands as for remote PRs.\n\n### 3. In-Depth Analysis\n\nAnalyze the code changes based on the following pillars:\n\n- **Correctness**: Does the code achieve its stated purpose without bugs or\n logical errors?\n- **Maintainability**: Is the code clean, well-structured, and easy to\n understand and modify in the future? Consider factors like code clarity,\n modularity, and adherence to established design patterns.\n- **Readability**: Is the code well-commented (where necessary) and consistently\n formatted according to our project's coding style guidelines?\n- **Efficiency**: Are there any obvious performance bottlenecks or resource\n inefficiencies introduced by the changes?\n- **Security**: Are there any potential security vulnerabilities or insecure\n coding practices?\n- **Edge Cases and Error Handling**: Does the code appropriately handle edge\n cases and potential errors?\n- **Testability**: Is the new or modified code adequately covered by tests (even\n if preflight checks pass)? Suggest additional test cases that would improve\n coverage or robustness.\n\n### 4. Draft Feedback (DO NOT FIX)\n\n**IMPORTANT**: You are a reviewer, NOT a fixer. Do NOT attempt to fix the code\nyourself. Your goal is to provide high-quality feedback.\n\n#### Structure\n\n- **Summary**: A high-level overview of the review.\n- **Verification Results**: briefly summarize the results of the build, test,\n lint, and format checks.\n- **Findings**:\n - **Critical**: Bugs, security issues, test failures, lint errors, or breaking\n changes.\n - **Improvements**: Suggestions for better code quality or performance.\n - **Nitpicks**: Formatting or minor style issues (optional).\n- **Conclusion**: Clear recommendation (Approved / Request Changes).\n\n#### Tone\n\n- Be constructive, professional, and friendly.\n- Explain _why_ a change is requested.\n- For approvals, acknowledge the specific value of the contribution.\n\n### 5. Interactive Refinement\n\n1. **Present Draft**: Show the drafted review feedback to the user.\n2. **Solicit Input**: Ask the user for their thoughts.\n - \"Does this feedback look accurate?\"\n - \"Is the tone appropriate?\"\n - \"Did I miss any context?\"\n3. **Iterate**: If the user provides suggestions or corrections, update the\n draft feedback accordingly.\n4. **Finalize**: specific approval from the user is not strictly required if\n they don't have further comments, but ensure they have a chance to respond.\n\n### 6. Cleanup (Remote PRs only)\n\n- After the review is complete, ask the user if they want to switch back to the\n default branch (e.g., `main` or `master`).\n" }, { "path": ".github/dependabot.yml", "content": "version: 2\nupdates:\n - package-ecosystem: 'npm'\n directory: '/'\n schedule:\n interval: 'weekly'\n open-pull-requests-limit: 5\n groups:\n typescript:\n patterns:\n - 'typescript'\n npm-root:\n patterns:\n - '*'\n labels:\n - 'dependencies'\n - 'npm'\n commit-message:\n prefix: 'chore'\n include: 'scope'\n\n - package-ecosystem: 'npm'\n directory: '/workspace-server'\n schedule:\n interval: 'weekly'\n open-pull-requests-limit: 5\n groups:\n npm-workspace-server:\n patterns:\n - '*'\n labels:\n - 'dependencies'\n - 'npm'\n commit-message:\n prefix: 'chore'\n include: 'scope'\n\n - package-ecosystem: 'github-actions'\n directory: '/'\n schedule:\n interval: 'weekly'\n open-pull-requests-limit: 5\n groups:\n github-actions:\n patterns:\n - '*'\n labels:\n - 'dependencies'\n - 'github-actions'\n commit-message:\n prefix: 'chore'\n include: 'scope'\n" }, { "path": ".github/workflows/ci.yml", "content": "name: CI\n\non:\n push:\n branches: [main, develop]\n pull_request:\n branches: [main]\n\njobs:\n verify:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v6\n\n - name: Use Node.js 20.x\n uses: actions/setup-node@v6\n with:\n node-version: '20.x'\n cache: 'npm'\n cache-dependency-path: package-lock.json\n\n - name: Install dependencies\n run: npm ci\n\n - name: Run linter\n run: npm run lint\n\n - name: Run Prettier check\n run: npm run format:check\n\n - name: Run type checking\n run: npx tsc --noEmit --project workspace-server\n\n test:\n needs: verify\n runs-on: ${{ matrix.os }}\n\n strategy:\n matrix:\n node-version: [20.x, 22.x, 24.x]\n os: [ubuntu-latest, windows-latest, macos-latest]\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Use Node.js ${{ matrix.node-version }}\n uses: actions/setup-node@v6\n with:\n node-version: ${{ matrix.node-version }}\n cache: 'npm'\n cache-dependency-path: package-lock.json\n\n - name: Install libsecret (Linux)\n if: runner.os == 'Linux'\n run: sudo apt-get update && sudo apt-get install -y libsecret-1-0\n\n - name: Install dependencies\n run: npm ci\n\n - name: Run tests with coverage\n run: npm run test:ci\n\n - name: Upload coverage to Codecov\n uses: codecov/codecov-action@v6\n with:\n directory: ./workspace-server/coverage\n flags: unittests\n name: codecov-umbrella\n fail_ci_if_error: false\n\n build:\n runs-on: ubuntu-latest\n needs: test\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Use Node.js\n uses: actions/setup-node@v6\n with:\n node-version: '20.x'\n cache: 'npm'\n cache-dependency-path: package-lock.json\n\n - name: Install dependencies\n run: npm ci\n\n - name: Build\n run: npm run build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v7\n with:\n name: dist\n path: workspace-server/dist/\n\n security:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Run security audit\n run: npm audit --audit-level=moderate\n continue-on-error: true\n\n - name: Check for known vulnerabilities\n run: npx audit-ci --moderate\n continue-on-error: true\n" }, { "path": ".github/workflows/deploy-docs.yml", "content": "name: Deploy Docs to GitHub Pages\n\non:\n push:\n branches:\n - main\n\njobs:\n build:\n runs-on: ubuntu-latest\n permissions:\n contents: write # For actions/checkout to fetch code\n pages: write # For uploading the artifact\n id-token: write # For OIDC authentication\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n with:\n fetch-depth: 0 # Not strictly needed but good practice for some build tools\n\n - name: Setup Node\n uses: actions/setup-node@v6\n with:\n node-version: 20\n cache: npm # Cache npm dependencies\n\n - name: Install dependencies\n run: npm install\n\n - name: Build docs\n run: npm run docs:build\n\n - name: Upload artifact\n uses: actions/upload-pages-artifact@v5\n with:\n path: docs/.vitepress/dist # The directory where VitePress builds the docs\n\n deploy:\n environment:\n name: github-pages\n url: ${{ steps.deployment.outputs.page_url }}\n runs-on: ubuntu-latest\n needs: build\n permissions:\n pages: write\n id-token: write\n steps:\n - name: Deploy to GitHub Pages\n id: deployment\n uses: actions/deploy-pages@v5\n" }, { "path": ".github/workflows/release.yml", "content": "name: Release\n\non:\n push:\n tags:\n - 'v*'\n\njobs:\n release:\n strategy:\n matrix:\n include:\n - os: ubuntu-latest\n platform: linux\n - os: macos-latest\n platform: darwin\n - os: windows-latest\n platform: win32\n runs-on: ${{ matrix.os }}\n permissions:\n contents: write\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n with:\n fetch-depth: 0\n persist-credentials: false\n\n - name: Setup Node.js\n uses: actions/setup-node@v6\n with:\n node-version: '20'\n\n - name: Install dependencies\n run: npm ci\n\n - name: Build extension\n run: npm run build --workspace=workspace-server\n\n - name: Create release assets\n run: npm run release -- --platform=${{ matrix.platform }}\n\n - name: Release\n uses: softprops/action-gh-release@v3\n if: startsWith(github.ref, 'refs/tags/')\n with:\n files: release/${{ matrix.platform }}.google-workspace-extension.tar.gz\n" }, { "path": ".github/workflows/weekly-preview.yml", "content": "name: Weekly Preview Release\n\non:\n schedule:\n # Every Monday at 09:00 UTC\n - cron: '0 9 * * 1'\n workflow_dispatch:\n\njobs:\n prepare:\n runs-on: ubuntu-latest\n outputs:\n tag_name: ${{ steps.date.outputs.tag_name }}\n steps:\n - name: Get current date\n id: date\n run: echo \"tag_name=preview-$(date +'%Y-%m-%d')\" >> $GITHUB_OUTPUT\n\n create-release:\n needs: prepare\n runs-on: ubuntu-latest\n permissions:\n contents: write\n steps:\n - name: Create Release\n uses: softprops/action-gh-release@v3\n with:\n tag_name: ${{ needs.prepare.outputs.tag_name }}\n name: Weekly Preview ${{ needs.prepare.outputs.tag_name }}\n prerelease: true\n\n release:\n needs: [prepare, create-release]\n name: Build and Release\n strategy:\n matrix:\n include:\n - os: ubuntu-latest\n platform: linux\n - os: macos-latest\n platform: darwin\n - os: windows-latest\n platform: win32\n runs-on: ${{ matrix.os }}\n permissions:\n contents: write\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n with:\n fetch-depth: 0\n persist-credentials: false\n\n - name: Setup Node.js\n uses: actions/setup-node@v6\n with:\n node-version: '20'\n\n - name: Install dependencies\n run: npm ci\n\n - name: Build extension\n run: npm run build --workspace=workspace-server\n\n - name: Create release assets\n shell: bash\n env:\n GITHUB_REF_NAME: ${{ needs.prepare.outputs.tag_name }}\n run: npm run release -- --platform=${{ matrix.platform }}\n\n - name: Upload Release Assets\n uses: softprops/action-gh-release@v3\n with:\n tag_name: ${{ needs.prepare.outputs.tag_name }}\n files: release/${{ matrix.platform }}.google-workspace-extension.tar.gz\n" }, { "path": ".gitignore", "content": "# macOS\n.DS_Store\n\n# logs\nlogs\n\n# Dependencies\nnode_modules/\n\n# Build outputs\ndist/\n\n# Environment files\n.env\n.env.local\n\n# Logs\n*.log\n\n# Coverage\ncoverage/\n\n# Editor files\n*.swp\n*.swo\n*~\n.idea/\n.vscode/\n\n# Auth tokens\ntoken.json\ngemini-cli-workspace-token.json\n.gemini-cli-workspace-master-key\n\ncommit_message.txt\n\n# Release directory\nrelease/\n\n# VitePress\ndocs/.vitepress/dist\ndocs/.vitepress/cache" }, { "path": ".prettierignore", "content": "node_modules\ndist\ncoverage\n.vitepress/cache\n.vitepress/dist\npackage-lock.json\n" }, { "path": ".prettierrc.json", "content": "{\n \"semi\": true,\n \"trailingComma\": \"all\",\n \"singleQuote\": true,\n \"printWidth\": 80,\n \"tabWidth\": 2,\n \"overrides\": [\n {\n \"files\": [\"**/*.md\"],\n \"options\": {\n \"proseWrap\": \"always\"\n }\n }\n ]\n}\n" }, { "path": "CONTRIBUTING.md", "content": "# How to Contribute\n\nWe would love to accept your patches and contributions to this project.\n\n## Before you begin\n\n### Sign our Contributor License Agreement\n\nContributions to this project must be accompanied by a\n[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).\nYou (or your employer) retain the copyright to your contribution; this simply\ngives us permission to use and redistribute your contributions as part of the\nproject.\n\nIf you or your current employer have already signed the Google CLA (even if it\nwas for a different project), you probably don't need to do it again.\n\nVisit to see your current agreements or to\nsign a new one.\n\n### Review our Community Guidelines\n\nThis project follows\n[Google's Open Source Community Guidelines](https://opensource.google/conduct/).\n\n## Contribution Process\n\n### Code Reviews\n\nAll submissions, including submissions by project members, require review. We\nuse [GitHub pull requests](https://docs.github.com/articles/about-pull-requests)\nfor this purpose.\n\n### Self Assigning Issues\n\nIf you're looking for an issue to work on, check out our list of issues that are\nlabeled\n[\"help wanted\"](https://github.com/gemini-cli-extensions/workspace/issues?q=is%3Aissue+state%3Aopen+label%3A%22help+wanted%22).\n\nTo assign an issue to yourself, simply add a comment with the text `/assign`.\nThe comment must contain only that text and nothing else. This command will\nassign the issue to you, provided it is not already assigned.\n\nPlease note that you can have a maximum of 3 issues assigned to you at any given\ntime.\n\n### Pull Request Guidelines\n\nTo help us review and merge your PRs quickly, please follow these guidelines.\nPRs that do not meet these standards may be closed.\n\n#### 1. Link to an Existing Issue\n\nAll PRs should be linked to an existing issue in our tracker. This ensures that\nevery change has been discussed and is aligned with the project's goals before\nany code is written.\n\n- **For bug fixes:** The PR should be linked to the bug report issue.\n- **For features:** The PR should be linked to the feature request or proposal\n issue that has been approved by a maintainer.\n\nIf an issue for your change doesn't exist, please **open one first** and wait\nfor feedback before you start coding.\n\n#### 2. Keep It Small and Focused\n\nWe favor small, atomic PRs that address a single issue or add a single,\nself-contained feature.\n\n- **Do:** Create a PR that fixes one specific bug or adds one specific feature.\n- **Don't:** Bundle multiple unrelated changes (e.g., a bug fix, a new feature,\n and a refactor) into a single PR.\n\nLarge changes should be broken down into a series of smaller, logical PRs that\ncan be reviewed and merged independently.\n\n#### 3. Use Draft PRs for Work in Progress\n\nIf you'd like to get early feedback on your work, please use GitHub's **Draft\nPull Request** feature. This signals to the maintainers that the PR is not yet\nready for a formal review but is open for discussion and initial feedback.\n\n#### 4. Ensure All Checks Pass\n\nBefore submitting your PR, ensure that all automated checks are passing by\nrunning:\n\n```bash\nnpm run test && npm run lint && npm run format:check && npx tsc --noEmit --project workspace-server\n```\n\nThis command runs all tests, linting, formatting, and type checks.\n\n#### 5. Write Clear Commit Messages and a Good PR Description\n\nYour PR should have a clear, descriptive title and a detailed description of the\nchanges. Follow the [Conventional Commits](https://www.conventionalcommits.org/)\nstandard for your commit messages.\n\n- **Good PR Title:** `feat(cli): Add --json flag to 'config get' command`\n- **Bad PR Title:** `Made some changes`\n\nIn the PR description, explain the \"why\" behind your changes and link to the\nrelevant issue (e.g., `Fixes #123`).\n\n## Development Setup and Workflow\n\nFor information on how to build, modify, and understand the development setup of\nthis project, please see the [development documentation](docs/development.md).\n" }, { "path": "GEMINI.md", "content": "This is a Gemini extension that provides tools for interacting with Google\nWorkspace services like Google Docs.\n\n### Building and Running\n\n- **Install dependencies:** `npm install`\n- **Build the project:** `npm run build --prefix workspace-server`\n\n### Development Conventions\n\nThis project uses TypeScript and the Model Context Protocol (MCP) SDK to create\na Gemini extension. The main entry point is `src/index.ts`, which initializes\nthe MCP server and registers the available tools.\n\nThe business logic for each service is separated into its own file in the\n`src/services` directory. For example, `src/services/DocsService.ts` contains\nthe logic for interacting with the Google Docs API.\n\nAuthentication is handled by the `src/auth/AuthManager.ts` file, which uses the\n`@google-cloud/local-auth` library to obtain and refresh OAuth 2.0 credentials.\n\n### Adding New Tools\n\nTo add a new tool, you need to:\n\n1. Add a new method to the appropriate service file in `src/services`.\n2. In `src/index.ts`, register the new tool with the MCP server by calling\n `server.registerTool()`. You will need to provide a name for the tool, a\n description, and the input schema using the `zod` library.\n" }, { "path": "LICENSE", "content": "\n Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright [yyyy] [name of copyright owner]\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License." }, { "path": "README.md", "content": "# Google Workspace Extension for Gemini CLI\n\n[![Build Status](https://github.com/gemini-cli-extensions/workspace/actions/workflows/ci.yml/badge.svg)](https://github.com/gemini-cli-extensions/workspace/actions/workflows/ci.yml)\n\nThe Google Workspace extension for Gemini CLI brings the power of your Google\nWorkspace apps to your command line. Manage your documents, spreadsheets,\npresentations, emails, chat, and calendar events without leaving your terminal.\n\n## Prerequisites\n\nBefore using the Google Workspace extension, you need to be logged into your\nGoogle account.\n\n## Installation\n\nInstall the Google Workspace extension by running the following command from\nyour terminal:\n\n```bash\ngemini extensions install https://github.com/gemini-cli-extensions/workspace\n```\n\n## Usage\n\nOnce the extension is installed, you can use it to interact with your Google\nWorkspace apps. Here are a few examples:\n\n**Create a new Google Doc:**\n\n> \"Create a new Google Doc with the title 'My New Doc' and the content '# My New\n> Document\\n\\nThis is a new document created from the command line.'\"\n\n**List your upcoming calendar events:**\n\n> \"What's on my calendar for today?\"\n\n**Search for a file in Google Drive:**\n\n> \"Find the file named 'my-file.txt' in my Google Drive.\"\n\n## Commands\n\nThis extension provides a variety of commands. Here are a few examples:\n\n### Get Schedule\n\n**Command:** `/calendar:get-schedule [date]`\n\nShows your schedule for today or a specified date.\n\n### Search Drive\n\n**Command:** `/drive:search `\n\nSearches your Google Drive for files matching the given query.\n\n## Headless / Remote Environments\n\nIf you're using the extension over SSH, WSL, Cloud Shell, or another environment\nwithout a local browser, you can authenticate using the headless login tool:\n\n```bash\nnpm run auth-utils -- login\n```\n\nThis prints an OAuth URL you can open in any browser (local machine, phone,\netc.). After signing in, paste the credentials JSON into the CLI. Credentials\nare read securely from `/dev/tty` and are never exposed to the AI model. See the\n[development docs](docs/development.md#headless--remote-environments) for more\ndetails.\n\n## Deployment\n\nIf you want to host your own version of this extension's infrastructure, see the\n[GCP Recreation Guide](docs/GCP-RECREATION.md).\n\n## Resources\n\n- [Documentation](docs/index.md): Detailed documentation on all the available\n tools.\n- [GitHub Issues](https://github.com/gemini-cli-extensions/workspace/issues):\n Report bugs or request features.\n\n## Important security consideration: Indirect Prompt Injection Risk\n\nWhen exposing any language model to untrusted data, there's a risk of an\n[indirect prompt injection attack](https://en.wikipedia.org/wiki/Prompt_injection).\nAgentic tools like Gemini CLI, connected to MCP servers, have access to a wide\narray of tools and APIs.\n\nThis MCP server grants the agent the ability to read, modify, and delete your\nGoogle Account data, as well as other data shared with you.\n\n- Never use this with untrusted tools\n- Never include untrusted inputs into the model context. This includes asking\n Gemini CLI to process mail, documents, or other resources from unverified\n sources.\n- Untrusted inputs may contain hidden instructions that could hijack your CLI\n session. Attackers can then leverage this to modify, steal, or destroy your\n data.\n- Always carefully review actions taken by Gemini CLI on your behalf to ensure\n they are correct and align with your intentions.\n\n## Contributing\n\nContributions are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md)\nfile for details on how to contribute to this project.\n\n## 📄 Legal\n\n- **License**: [Apache License 2.0](LICENSE)\n- **Terms of Service**: [Terms of Service](https://policies.google.com/terms)\n- **Privacy Policy**: [Privacy Policy](https://policies.google.com/privacy)\n- **Security**: [Security Policy](SECURITY.md)\n" }, { "path": "SECURITY.md", "content": "# Reporting Security Issues\n\nTo report a security issue, please use [https://g.co/vulnz](https://g.co/vulnz).\nWe use g.co/vulnz for our intake, and do coordination and disclosure here on\nGitHub (including using GitHub Security Advisory). The Google Security Team will\nrespond within 5 working days of your report on g.co/vulnz.\n" }, { "path": "cloud_function/index.js", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\n// Import required packages\nconst functions = require('@google-cloud/functions-framework');\nconst { SecretManagerServiceClient } = require('@google-cloud/secret-manager');\nconst axios = require('axios');\nconst { URL } = require('node:url');\n\n// --- Configuration loaded from Environment Variables ---\n// These are set in the Google Cloud Function's configuration.\n// They may be absent on the initial deploy (before OAuth credentials exist)\n// and are set on the final deploy. Validation happens at request time.\nconst CLIENT_ID = process.env.CLIENT_ID;\nconst SECRET_NAME = process.env.SECRET_NAME;\nconst REDIRECT_URI = process.env.REDIRECT_URI;\n\n// --- Configuration for local storage (used in instructions) ---\nconst KEYCHAIN_SERVICE_NAME = 'gemini-cli-workspace-oauth';\nconst KEYCHAIN_ACCOUNT_NAME = 'main-account';\n// --- END CONFIGURATION ---\n\n// Initialize the Secret Manager client\nconst secretClient = new SecretManagerServiceClient();\n\n/**\n * Helper function to access a secret from Secret Manager.\n */\nasync function getClientSecret() {\n try {\n const [version] = await secretClient.accessSecretVersion({\n name: SECRET_NAME,\n });\n const payload = version.payload.data.toString('utf8');\n\n return payload;\n } catch (error) {\n console.error('Failed to access secret version:', error);\n throw new Error('Could not retrieve client secret.');\n }\n}\n\n/**\n * Handles the OAuth 2.0 callback.\n * @param {Object} req Express request object.\n * @param {Object} res Express response object.\n */\nasync function handleCallback(req, res) {\n const code = req.query.code;\n const state = req.query.state; // The state is the base64 encoded local redirect URI\n\n if (!code) {\n console.error('Missing authorization code in request query parameters.');\n return res.status(400).send('Error: Missing authorization code.');\n }\n\n try {\n const clientSecret = await getClientSecret();\n const tokenResponse = await axios.post(\n 'https://oauth2.googleapis.com/token',\n {\n client_id: CLIENT_ID,\n client_secret: clientSecret,\n code: code,\n grant_type: 'authorization_code',\n redirect_uri: REDIRECT_URI,\n },\n );\n\n const { access_token, refresh_token, expires_in, scope, token_type } =\n tokenResponse.data;\n\n // Calculate expiry_date (timestamp in milliseconds)\n const expiry_date = Date.now() + expires_in * 1000;\n\n // If state is present, decode it and decide whether to redirect or show manual page.\n if (state) {\n try {\n // SECURITY: Enforce a reasonable size limit on the state parameter to prevent DoS.\n if (state.length > 4096) {\n throw new Error('State parameter exceeds size limit of 4KB.');\n }\n\n const payload = JSON.parse(\n Buffer.from(state, 'base64').toString('utf8'),\n );\n\n // If not in manual mode and a URI is present, perform the redirect.\n if (payload && payload.manual === false && payload.uri) {\n const redirectUrl = new URL(payload.uri);\n\n // SECURITY: Validate the redirect URI to prevent open redirect attacks.\n if (\n redirectUrl.hostname !== 'localhost' &&\n redirectUrl.hostname !== '127.0.0.1'\n ) {\n throw new Error(\n `Invalid redirect hostname: ${redirectUrl.hostname}. Must be localhost or 127.0.0.1.`,\n );\n }\n\n const finalUrl = redirectUrl; // Use the validated URL object\n finalUrl.searchParams.append('access_token', access_token);\n if (refresh_token) {\n finalUrl.searchParams.append('refresh_token', refresh_token);\n }\n finalUrl.searchParams.append('scope', scope);\n finalUrl.searchParams.append('token_type', token_type);\n finalUrl.searchParams.append('expiry_date', expiry_date.toString());\n\n // SECURITY: Pass the CSRF token back to the client for validation.\n if (payload.csrf) {\n finalUrl.searchParams.append('state', payload.csrf);\n }\n\n return res.redirect(302, finalUrl.toString());\n }\n } catch (e) {\n console.error(\n 'Error processing state or redirect. Falling back to manual page.',\n e,\n );\n }\n }\n\n // --- Fallback to manual instructions ---\n\n const credentialsJson = JSON.stringify(\n {\n refresh_token: refresh_token,\n scope: scope,\n token_type: token_type,\n access_token: access_token,\n expiry_date: expiry_date,\n },\n null,\n 2,\n ); // Pretty print JSON\n\n // 4. Display the JSON and add a copy button + instructions\n res.set('Content-Type', 'text/html');\n res.status(200).send(`\n \n \n OAuth Token Generated\n \n \n \n
\n

Success! Credentials Ready

\n

Copy the JSON block below. You'll need to store this as the password/secret in your operating system's keychain.

\n\n

Credentials JSON

\n \n \n Copied!\n\n
\n

CLI Login (Recommended):

\n

In your terminal, run:

\n 
node dist/headless-login.js
\n

Then paste the JSON above when prompted. The CLI will securely store your credentials.

\n\n
\n Advanced: Manual Keychain Storage\n
\n
    \n
  1. Open your OS Keychain/Credential Manager.
    2. \n
  2. Create a new secure entry (e.g., a \"Generic Password\" on macOS, a \"Windows Credential\", or similar on Linux).
    3. \n
  3. Set the Service (or equivalent field) to: ${KEYCHAIN_SERVICE_NAME}
    4. \n
  4. Set the Account (or username field) to: ${KEYCHAIN_ACCOUNT_NAME}
    5. \n
  5. Paste the copied JSON into the Password/Secret field.
    6. \n
  6. Save the entry.
    7. \n
\n

(If keychain is unavailable, the server falls back to an encrypted file, but keychain is recommended.)

\n
\n
\n
\n
\n\n \n \n \n `);\n } catch (error) {\n if (axios.isAxiosError(error) && error.response) {\n console.error('Error during token exchange:', error.response.data);\n } else {\n console.error(\n 'Error during token exchange:',\n error instanceof Error ? error.message : error,\n );\n }\n res\n .status(500)\n .send(\n 'An error occurred during the token exchange. Check function logs for details.',\n );\n }\n}\n\n/**\n * Handles token refresh.\n * Accepts a refresh_token and returns a new access_token.\n * @param {Object} req Express request object.\n * @param {Object} res Express response object.\n */\nasync function handleRefreshToken(req, res) {\n // Only accept POST requests\n if (req.method !== 'POST') {\n console.error('Invalid method for refreshToken:', req.method);\n return res.status(405).send('Method Not Allowed');\n }\n\n const { refresh_token } = req.body;\n\n if (!refresh_token) {\n console.error('Missing refresh_token in request body');\n return res\n .status(400)\n .send('Error: Missing refresh_token in request body.');\n }\n\n try {\n const clientSecret = await getClientSecret();\n\n const tokenResponse = await axios.post(\n 'https://oauth2.googleapis.com/token',\n {\n client_id: CLIENT_ID,\n client_secret: clientSecret,\n refresh_token: refresh_token,\n grant_type: 'refresh_token',\n },\n );\n\n const { access_token, expires_in, scope, token_type } = tokenResponse.data;\n\n // Calculate expiry_date (timestamp in milliseconds)\n const expiry_date = Date.now() + expires_in * 1000;\n\n // Return the new credentials\n // Note: Google does NOT return a new refresh_token on refresh\n // The client must preserve the original refresh_token\n res.status(200).json({\n access_token,\n expiry_date,\n token_type,\n scope,\n });\n } catch (error) {\n if (axios.isAxiosError(error) && error.response) {\n console.error('Error during token refresh:', error.response.data);\n res.status(error.response.status).json(error.response.data);\n } else {\n console.error(\n 'Error during token refresh:',\n error instanceof Error ? error.message : error,\n );\n res.status(500).send('An error occurred during token refresh.');\n }\n }\n}\n\n/**\n * Main entry point for the Cloud Function.\n * Routes requests to either the callback handler or the refresh handler.\n */\nfunctions.http('oauthHandler', async (req, res) => {\n // Validate required environment variables at request time\n if (!CLIENT_ID || !SECRET_NAME || !REDIRECT_URI) {\n return res\n .status(503)\n .send(\n 'Function not yet configured. Missing required environment variables: CLIENT_ID, SECRET_NAME, REDIRECT_URI.',\n );\n }\n\n // Route to refresh handler if path ends with /refresh or /refreshToken or it's a POST with refresh_token\n if (\n ['/refresh', '/refreshToken'].includes(req.path) ||\n (req.method === 'POST' && req.body?.refresh_token)\n ) {\n return handleRefreshToken(req, res);\n }\n\n // Route to callback handler if path ends with /callback or /oauth2callback or has 'code' query param\n if (['/callback', '/oauth2callback'].includes(req.path) || req.query.code) {\n return handleCallback(req, res);\n }\n\n // Default/Error case\n res\n .status(400)\n .send(\n 'Unknown request type. Expected OAuth callback or token refresh request.',\n );\n});\n" }, { "path": "cloud_function/package.json", "content": "{\n \"name\": \"oauth-handler\",\n \"version\": \"1.0.0\",\n \"main\": \"index.js\",\n \"dependencies\": {\n \"@google-cloud/functions-framework\": \"^3.0.0\",\n \"@google-cloud/secret-manager\": \"^5.0.0\",\n \"axios\": \"^1.15.0\"\n }\n}\n" }, { "path": "commands/calendar/clear-schedule.toml", "content": "description = \"Clear all events for a specific date or range by deleting or declining them\"\nprompt = \"\"\"\nPlease help me clear my schedule for a specific date or date range. Follow these steps carefully:\n\n1. **Identify User & Context:**\n - Call `people.getMe` to get my email address and details.\n - Call `time.getTimeZone` to get my local time zone.\n\n2. **Determine Date Range:**\n - Parse the date or date range from the arguments: \"{{args}}\".\n - If no arguments are provided, use `time.getCurrentDate` to default to today.\n\n3. **Fetch Events:**\n - Call `calendar.listEvents` for the determined date range using my primary calendar.\n - **Important:** Include ALL events in the list, even those often filtered out like \"Commute Time\", \"DNS\", personal blocks, or events where I am the only attendee.\n\n4. **Review & Confirm (CRITICAL):**\n - List all the events found for that period in a clear, numbered list showing the Time and Title.\n - **Specifically call out any all-day events** and ask if I want to include those in the clear operation.\n - **STOP** and ask me for explicit confirmation before proceeding. Example: \"I found 5 events (including 1 all-day event). Do you want me to clear all of them?\"\n\n5. **Execute Clearing:**\n - Once I confirm, iterate through each event in the list:\n - **If I am the organizer** (check `organizer.self` is true or `organizer.email` matches mine):\n - Call `calendar.deleteEvent` to remove it.\n - **If I am NOT the organizer**:\n - Call `calendar.respondToEvent` with `responseStatus` set to \"declined\".\n\n6. **Final Report:**\n - Summarize the actions taken (e.g., \"Deleted 2 events and declined 3 events.\").\n\"\"\"\n" }, { "path": "commands/calendar/get-schedule.toml", "content": "description = \"Show your schedule for today, or the date specified\"\nprompt = \"\"\"\nPlease show me my schedule for today. To do that use the following steps:\n\n1) Use the people.getMe tool to get my information.\n2) Use the time.getTimeZone to get my local time zone.\n3) Either use the time.getCurrentDate or the user supplied date here: {{args}} to understand the current date.\n4) Call calendar.list to identify the calendar associated with me from step 1.\n5) Call calendar.listEvents to identify events on my calendar for the date we determined in step 3.\n6) Format the list of events in my local time zone from step 2 in the following format:\n\n> HH:MM - HH:MM: Event Title (attendance status) - Event Location\n> HH:MM - HH:MM: Event 2 Title (attendance status) - Event Location\n\nNote: If a calendar event has conflicting timezone information, prioritize the dateTime field over the timeZone field.\n\n\"\"\"\n" }, { "path": "commands/drive/search.toml", "content": "description = \"Searches Google Drive for files matching a query.\"\nprompt = \"\"\"\nYou are tasked with searching Google Drive for files.\n\n1) The user's search query is: {{args}}\n2) Call the `drive.search` tool, passing the user's query as the `query` argument.\n3) The `drive.search` tool returns a JSON object containing a list of files.\n4) Format the result into a clear, readable list, showing only the `name` and `id` for each file found.\n5) If no files are found, state that clearly.\n\nExample Output Format:\n> File Name: My Document (ID: 1a2b3c4d5e6f7g8h9i0j)\n> File Name: Project Report (ID: k1l2m3n4o5p6q7r8s9t0)\n\"\"\"\n" }, { "path": "commands/gmail/search.toml", "content": "description = \"Searches for emails in Gmail matching a query.\"\nprompt = \"\"\"\nYou are tasked with searching Gmail for emails.\n\n1) The user's search query is: {{args}}\n2) Call the `gmail.search` tool, passing the user's query as the `query` argument.\n3) The `gmail.search` tool returns a JSON object containing a list of emails (id and threadId).\n4) For each email found, you MUST call `gmail.get` with the `messageId` and `format='metadata'` to get the From, Subject, and Snippet.\n5) Format the result into a clear, readable list.\n6) If no emails are found, state that clearly.\n\nExample Output Format:\n> From: sender@example.com\n Subject: Meeting Reminder\n Snippet: Don't forget about the meeting tomorrow...\n ---\n> From: newsletter@example.com\n Subject: Weekly News\n Snippet: Here are the top stories for this week...\n\"\"\"\n" }, { "path": "docs/.vitepress/config.mts", "content": "import { defineConfig } from 'vitepress';\n\n// https://vitepress.dev/reference/site-config\nexport default defineConfig({\n base: '/workspace/',\n title: 'Gemini Workspace Extension',\n description: 'Documentation for the Google Workspace Server Extension',\n themeConfig: {\n // https://vitepress.dev/reference/default-theme-config\n nav: [\n { text: 'Home', link: '/' },\n { text: 'Configuration', link: '/feature-configuration' },\n { text: 'Development', link: '/development' },\n { text: 'Release', link: '/release' },\n { text: 'Release Notes', link: '/release_notes' },\n ],\n\n sidebar: [\n {\n text: 'Documentation',\n items: [\n { text: 'Overview', link: '/' },\n { text: 'Feature Configuration', link: '/feature-configuration' },\n { text: 'Development Guide', link: '/development' },\n { text: 'GCP Setup Guide', link: '/GCP-RECREATION' },\n { text: 'Release Guide', link: '/release' },\n { text: 'Release Notes', link: '/release_notes' },\n ],\n },\n ],\n\n socialLinks: [\n {\n icon: 'github',\n link: 'https://github.com/gemini-cli-extensions/workspace',\n },\n ],\n },\n});\n" }, { "path": "docs/GCP-RECREATION.md", "content": "# Recreating the GCP Project\n\nThis guide provides step-by-step instructions to recreate the Google Cloud\nPlatform (GCP) project and infrastructure required for the Google Workspace\nExtension.\n\n## Overview\n\nThe extension uses a \"Hybrid\" OAuth flow for security:\n\n1. **Local Client**: Requests authorization from the user.\n2. **Cloud Function**: Acts as a secure proxy to exchange the authorization code\n for tokens. It holds the `CLIENT_SECRET` securely in Secret Manager.\n3. **Secret Manager**: Stores the OAuth Client Secret.\n\n## Prerequisites\n\n- A Google Cloud Project with billing enabled.\n- [Google Cloud CLI (gcloud)](https://cloud.google.com/sdk/docs/install)\n installed and authenticated.\n- Node.js and npm installed.\n\n## Step 1: Run the Automated Setup Script\n\nThe setup script handles the full infrastructure setup in the correct order,\nincluding guided configuration of the OAuth consent screen.\n\n1. Set your project ID:\n ```bash\n gcloud config set project YOUR_PROJECT_ID\n ```\n2. Run the setup script:\n ```bash\n ./scripts/setup-gcp.sh\n ```\n\nThe script will:\n\n1. Enable all required GCP APIs.\n2. Guide you through configuring the **OAuth consent screen** with the required\n scopes and test users (opens the Cloud Console automatically).\n3. Deploy the Cloud Function and display its URL.\n4. Prompt you to create an **OAuth 2.0 Client ID** in the Google Cloud Console\n using the deployed function URL as the redirect URI.\n5. Collect your Client ID and Client Secret.\n6. Store the Client Secret in Secret Manager.\n7. Update the Cloud Function with the OAuth configuration.\n8. Grant the Cloud Function access to the secret.\n\n## Step 2: Local Configuration\n\nAfter running the script, set the following environment variables in your shell\n(e.g., in `.zshrc` or `.bashrc`):\n\n```bash\nexport WORKSPACE_CLIENT_ID=\"your-client-id\"\nexport WORKSPACE_CLOUD_FUNCTION_URL=\"https://your-cloud-function-url\"\n```\n\nThe script will display the exact values to use.\n\nAlternatively, you can modify the `DEFAULT_CONFIG` in\n`workspace-server/src/utils/config.ts`.\n\n## Why a Cloud Function?\n\nThe extension uses a Cloud Function to protect your `CLIENT_SECRET`.\n\n- If the `CLIENT_SECRET` were included in the local extension code, anyone with\n access to the extension could steal it.\n- By using a Cloud Function, the secret stays in your GCP project and is only\n used server-side during the token exchange.\n- The local client only ever sees the resulting tokens, never the secret.\n" }, { "path": "docs/development.md", "content": "# Development\n\nThis document provides instructions for developing the Google Workspace\nextension.\n\n## Development Setup and Workflow\n\nThis section guides contributors on how to build, modify, and understand the\ndevelopment setup of this project.\n\n### Setting Up the Development Environment\n\n**Prerequisites:**\n\n1. **Node.js**:\n - **Development:** Please use Node.js `~20.19.0`. This specific version is\n required due to an upstream development dependency issue. You can use a\n tool like [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions.\n - **Production:** For running the CLI in a production environment, any\n version of Node.js `>=20` is acceptable.\n2. **Git**\n\n### Build Process\n\nTo clone the repository:\n\n```bash\ngit clone https://github.com/gemini-cli-extensions/workspace.git # Or your fork's URL\ncd workspace\n```\n\nTo install dependencies defined in `package.json` as well as root dependencies:\n\n```bash\nnpm install\n```\n\nTo build the entire project (all packages):\n\n```bash\nnpm run build\n```\n\nThis command typically compiles TypeScript to JavaScript, bundles assets, and\nprepares the packages for execution. Refer to `scripts/build.js` and\n`package.json` scripts for more details on what happens during the build.\n\n### Running Tests\n\nThis project contains unit tests.\n\n#### Unit Tests\n\nTo execute the unit test suite for the project:\n\n```bash\nnpm run test\n```\n\nThis will run tests located in the `workspace-server/src/__tests__` directory.\nEnsure tests pass before submitting any changes. For a more comprehensive check,\nit is recommended to run `npm run test && npm run lint`.\n\nTo test a single file, you can pass its path from the project root as an\nargument. For example:\n\n````bash\nnpm run test -- workspace-server/src/__tests__/GmailService.test.ts\n```\n\n### Linting and Style Checks\n\nTo ensure code quality and formatting consistency, run the linter and tests:\n\n```bash\nnpm run test && npm run lint\n````\n\nThis command will run ESLint, Prettier, all tests, and other checks as defined\nin the project's `package.json`.\n\n> [!TIP] After cloning create a git pre-commit hook file to ensure your commits\n> are always clean.\n>\n> ```bash\n> cat <<'EOF' > .git/hooks/pre-commit\n> #!/bin/sh\n> # Run tests and linting before commit\n> if ! (npm run test && npm run lint); then\n> echo \"Pre-commit checks failed. Commit aborted.\"\n> exit 1\n> fi\n> EOF\n> chmod +x .git/hooks/pre-commit\n> ```\n\n#### Formatting\n\nTo separately format the code in this project by running the following command\nfrom the root directory:\n\n```bash\nnpm run format\n```\n\nThis command uses Prettier to format the code according to the project's style\nguidelines.\n\n#### Linting\n\nTo separately lint the code in this project, run the following command from the\nroot directory:\n\n```bash\nnpm run lint\n```\n\n#### Testing with Gemini CLI\n\nTo test your code changes with Gemini CLI you can run:\n\n```bash\ngemini extensions uninstall google-workspace\nnpm install && npm run build\ngemini extensions link .\ngemini extensions list\ngemini --debug\n# Prompt to test your feature/bug fix\n```\n\n### Coding Conventions\n\n- Please adhere to the coding style, patterns, and conventions used throughout\n the existing codebase.\n- Consult\n [GEMINI.md](https://github.com/gemini-cli-extensions/workspace/blob/main/GEMINI.md)\n (typically found in the project root) for specific instructions related to\n AI-assisted development, including conventions for comments, and Git usage.\n- **Imports:** Pay special attention to import paths. The project uses ESLint to\n enforce restrictions on relative imports between packages.\n\n### Tool Naming\n\nTool names in source use dot notation (e.g., `docs.create`) for logical\ngrouping. By default, these are normalized to underscores at runtime (e.g.,\n`docs_create`) for compatibility with a broader set of applications that use MCP\nincluding Google Antigravity.\n\nWhen the server is run as a Gemini CLI extension the `--use-dot-names` flag is\nused to maintain dot notation and avoid breaking existing configurations.\n\n### Project Structure\n\n- `workspace-server/`: The main workspace for the MCP server.\n - `src/`: Contains the source code for the server.\n - `__tests__/`: Contains all the tests.\n - `auth/`: Handles authentication.\n - `cli/`: CLI tools (e.g., headless OAuth login).\n - `features/`: Feature configuration registry and resolver. See the\n [Feature Configuration](feature-configuration.md) docs.\n - `services/`: Contains the business logic for each service.\n - `utils/`: Contains utility functions.\n - `config/`: Contains configuration files.\n- `scripts/`: Utility scripts for building, testing, and development tasks.\n\n## Authentication\n\nThe extension uses OAuth 2.0 to authenticate with Google Workspace APIs. The\n`scripts/auth-utils.js` script provides a command-line interface to manage\nauthentication credentials.\n\n### Usage\n\nTo use the script, run the following command:\n\n```bash\nnpm run auth-utils -- \n```\n\n### Commands\n\n- `login`: Authenticate via headless OAuth flow (for SSH/WSL/Cloud Shell). Reads\n credentials securely from `/dev/tty` so they are not visible to AI models.\n- `clear`: Clear all authentication credentials.\n- `expire`: Force the access token to expire (for testing refresh).\n- `status`: Show current authentication status.\n- `help`: Show the help message.\n\n### Headless / Remote Environments\n\nIf you are running the server in an environment without a browser (SSH, WSL,\nCloud Shell, VMs), authentication requires manual steps:\n\n1. Run the login tool:\n ```bash\n npm run auth-utils -- login\n ```\n Or, from the `workspace-server` directory:\n ```bash\n node dist/headless-login.js\n ```\n2. Open the printed OAuth URL in any browser (your local machine, phone, etc.).\n3. Complete Google sign-in. The browser will display a credentials JSON block.\n4. Copy the JSON and paste it into the CLI when prompted.\n\nThe CLI reads input from `/dev/tty` (Unix) or `CON` (Windows) rather than\nprocess stdin, so credentials are never exposed to an AI model that may have\nspawned the process.\n\nUse `--force` to re-authenticate if credentials already exist.\n\n### Token Storage\n\nThe extension uses a **hybrid storage strategy** for OAuth credentials. It first\nattempts to use the OS-level secure storage (via the\n[keytar](https://github.com/atom/node-keytar) library). If the keychain is\nunavailable, it falls back to AES-256-GCM encrypted file storage.\n\nCredentials are stored under the service name `gemini-cli-workspace-oauth` with\nthe account name `main-account`.\n\n#### OS Keychain (Primary)\n\n| Platform | Backend | How to find stored credentials |\n| ----------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| **macOS** | Keychain Access | Open **Keychain Access** → search for `gemini-cli-workspace-oauth` |\n| **Windows** | Windows Credential Manager | Start Menu → search **Credential Manager** → **Windows Credentials** → **Generic Credentials** → `gemini-cli-workspace-oauth` |\n| **Linux** | GNOME Keyring / KWallet (`libsecret`) | Use `secret-tool search service gemini-cli-workspace-oauth` or your desktop's keyring manager |\n\n#### Encrypted File Fallback\n\nWhen the OS keychain is not available (e.g., headless servers, containers, or CI\nenvironments), the extension stores credentials in an encrypted file within the\nextension's installation directory:\n\n| File | Purpose |\n| ---------------------------------- | ---------------------------------------------------- |\n| `gemini-cli-workspace-token.json` | AES-256-GCM encrypted token data |\n| `.gemini-cli-workspace-master-key` | 256-bit master key used to derive the encryption key |\n\nBoth files are created with restrictive permissions (`0o600`) and their\ncontaining directory with `0o700`. The encryption key is derived from the master\nkey using `scrypt` with a machine-specific salt.\n\n#### Forcing File Storage\n\nTo bypass the OS keychain and always use encrypted file storage, set the\nenvironment variable:\n\n```bash\nexport GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE=true\n```\n" }, { "path": "docs/feature-configuration.md", "content": "# Feature Configuration\n\nThe extension provides a feature configuration system that lets you control\nwhich services and scopes are enabled. Each Google Workspace service is split\ninto **read** and **write** feature groups, giving you granular control over\nwhat the extension can access.\n\n## Feature Groups\n\n| Service | Group | Scopes | Default |\n| ---------- | ----- | ----------------------------------------------------------------------------- | ------- |\n| `docs` | read | `documents` | ON |\n| `docs` | write | `documents` | ON |\n| `drive` | read | `drive.readonly` | ON |\n| `drive` | write | `drive` | ON |\n| `calendar` | read | `calendar.readonly` | ON |\n| `calendar` | write | `calendar` | ON |\n| `chat` | read | `chat.spaces.readonly`, `chat.messages.readonly`, `chat.memberships.readonly` | ON |\n| `chat` | write | `chat.spaces`, `chat.messages`, `chat.memberships` | ON |\n| `gmail` | read | `gmail.readonly` | ON |\n| `gmail` | write | `gmail.modify` | ON |\n| `people` | read | `userinfo.profile`, `directory.readonly` | ON |\n| `slides` | read | `presentations.readonly` | ON |\n| `slides` | write | `presentations` | **OFF** |\n| `sheets` | read | `spreadsheets.readonly` | ON |\n| `sheets` | write | `spreadsheets` | **OFF** |\n| `time` | read | _(none)_ | ON |\n| `tasks` | read | `tasks.readonly` | **OFF** |\n| `tasks` | write | `tasks` | **OFF** |\n\n**Read** groups contain tools with no side effects (search, get, list).\n**Write** groups contain tools that perform mutations (create, update, delete,\nsend).\n\nServices whose write scopes aren't in the published GCP project (Slides write,\nSheets write, Tasks) default to **OFF**. These can be enabled by contributors\nusing their own GCP projects.\n\n## Configuration via `WORKSPACE_FEATURE_OVERRIDES`\n\nUse the `WORKSPACE_FEATURE_OVERRIDES` environment variable to enable or disable\nfeature groups and individual tools.\n\n### Syntax\n\n```\nWORKSPACE_FEATURE_OVERRIDES=\"key:on|off,key:on|off,...\"\n```\n\nEach entry is a comma-separated `key:value` pair where:\n\n- `key` is a feature group (e.g., `gmail.write`) or a tool name (e.g.,\n `calendar.deleteEvent`)\n- `value` is `on` or `off`\n\n### Group-Level Overrides\n\nDisable or enable entire feature groups:\n\n```bash\n# Disable Gmail write tools (send, createDraft, modify, etc.)\nexport WORKSPACE_FEATURE_OVERRIDES=\"gmail.write:off\"\n\n# Disable all of Chat\nexport WORKSPACE_FEATURE_OVERRIDES=\"chat.read:off,chat.write:off\"\n\n# Enable experimental features (Slides write, Tasks)\nexport WORKSPACE_FEATURE_OVERRIDES=\"slides.write:on,tasks.read:on,tasks.write:on\"\n```\n\n### Tool-Level Overrides\n\nDisable specific tools within an enabled group (subtractive only):\n\n```bash\n# Keep calendar.write enabled but disable delete\nexport WORKSPACE_FEATURE_OVERRIDES=\"calendar.deleteEvent:off\"\n\n# Disable destructive Gmail tools while keeping modify/label tools\nexport WORKSPACE_FEATURE_OVERRIDES=\"gmail.send:off,gmail.sendDraft:off\"\n\n# Combine group and tool overrides\nexport WORKSPACE_FEATURE_OVERRIDES=\"gmail.write:off,calendar.deleteEvent:off,slides.write:on\"\n```\n\n::: warning Tool-level overrides are **subtractive only**. You cannot use\n`tool:on` to enable a tool whose feature group is disabled. To enable tools,\nenable their parent feature group. :::\n\n### Precedence\n\nThe configuration follows a three-layer precedence model:\n\n1. **Baked-in defaults** — Current services default ON; experimental services\n default OFF\n2. **Settings** — Future: overrides from the install-time settings UI\n3. **`WORKSPACE_FEATURE_OVERRIDES`** — Highest precedence; overrides everything\n\n### Effects\n\nWhen a feature group is disabled:\n\n- Its **tools are not registered** with the MCP server (clients won't see them)\n- Its **OAuth scopes are not requested** during authentication\n- If you re-enable a previously disabled feature, you may need to\n re-authenticate to grant the new scopes\n\n## Tools by Feature Group\n\n### `docs.read`\n\n- `docs.getSuggestions`\n- `docs.getText`\n\n### `docs.write`\n\n- `docs.create`\n- `docs.writeText`\n- `docs.replaceText`\n- `docs.formatText`\n\n### `drive.read`\n\n- `drive.getComments`\n- `drive.findFolder`\n- `drive.search`\n- `drive.downloadFile`\n\n### `drive.write`\n\n- `drive.createFolder`\n- `drive.moveFile`\n- `drive.trashFile`\n- `drive.renameFile`\n\n### `calendar.read`\n\n- `calendar.list`\n- `calendar.listEvents`\n- `calendar.getEvent`\n- `calendar.findFreeTime`\n\n### `calendar.write`\n\n- `calendar.createEvent`\n- `calendar.updateEvent`\n- `calendar.respondToEvent`\n- `calendar.deleteEvent`\n\n### `chat.read`\n\n- `chat.listSpaces`\n- `chat.findSpaceByName`\n- `chat.getMessages`\n- `chat.findDmByEmail`\n- `chat.listThreads`\n\n### `chat.write`\n\n- `chat.sendMessage`\n- `chat.sendDm`\n- `chat.setUpSpace`\n\n### `gmail.read`\n\n- `gmail.search`\n- `gmail.get`\n- `gmail.downloadAttachment`\n- `gmail.listLabels`\n\n### `gmail.write`\n\n- `gmail.modify`\n- `gmail.batchModify`\n- `gmail.modifyThread`\n- `gmail.send`\n- `gmail.createDraft`\n- `gmail.sendDraft`\n- `gmail.createLabel`\n\n### `people.read`\n\n- `people.getUserProfile`\n- `people.getMe`\n- `people.getUserRelations`\n\n### `slides.read`\n\n- `slides.getText`\n- `slides.getMetadata`\n- `slides.getImages`\n- `slides.getSlideThumbnail`\n\n### `sheets.read`\n\n- `sheets.getText`\n- `sheets.getRange`\n- `sheets.getMetadata`\n\n### `time.read`\n\n- `time.getCurrentDate`\n- `time.getCurrentTime`\n- `time.getTimeZone`\n\n## For Contributors\n\nWhen adding a new service or tools:\n\n1. Define read and write feature group entries in\n `workspace-server/src/features/feature-config.ts`\n2. Set the default state — **ON** for scopes in the published GCP project,\n **OFF** otherwise\n3. Register your tools in `index.ts` as usual — the feature config wrapper\n automatically skips disabled tools\n\nThis lets contributors develop and merge new features without being blocked by\nthe published GCP project's scope configuration. Contributors can test with\ntheir own GCP projects by enabling the feature via\n`WORKSPACE_FEATURE_OVERRIDES`.\n" }, { "path": "docs/index.md", "content": "# Google Workspace Extension Documentation\n\nThis document provides an overview of the Google Workspace extension for Gemini\nCLI.\n\n## Available Tools\n\nThe extension provides the following tools:\n\n### Authentication\n\n- `auth.clear`: Clears the authentication credentials, forcing a re-login on the\n next request.\n- `auth.refreshToken`: Manually triggers the token refresh process.\n\n### Google Docs\n\n- `docs.create`: Creates a new Google Doc.\n- `docs.getSuggestions`: Retrieves suggested edits from a Google Doc.\n- `docs.getComments`: Retrieves comments from a Google Doc.\n- `docs.writeText`: Writes text to a Google Doc at a specified position.\n- `docs.getText`: Retrieves the text content of a Google Doc.\n- `docs.replaceText`: Replaces all occurrences of a given text with new text in\n a Google Doc.\n- `docs.formatText`: Applies formatting (bold, italic, headings, etc.) to text\n ranges in a Google Doc.\n\n### Google Slides\n\n- `slides.getText`: Retrieves the text content of a Google Slides presentation.\n- `slides.getMetadata`: Gets metadata about a Google Slides presentation.\n- `slides.getImages`: Downloads all images embedded in a Google Slides\n presentation to a local directory.\n- `slides.getSlideThumbnail`: Downloads a thumbnail image for a specific slide\n in a Google Slides presentation to a local path.\n\n### Google Sheets\n\n- `sheets.getText`: Retrieves the content of a Google Sheets spreadsheet.\n- `sheets.getRange`: Gets values from a specific range in a Google Sheets\n spreadsheet.\n- `sheets.getMetadata`: Gets metadata about a Google Sheets spreadsheet.\n\n### Google Drive\n\n- `drive.search`: Searches for files and folders in Google Drive.\n- `drive.findFolder`: Finds a folder by name in Google Drive.\n- `drive.createFolder`: Creates a new folder in Google Drive.\n- `drive.downloadFile`: Downloads a file from Google Drive to a local path.\n- `drive.trashFile`: Moves a file or folder to the trash in Google Drive.\n- `drive.renameFile`: Renames a file or folder in Google Drive.\n\n### Google Calendar\n\n- `calendar.list`: Lists all of the user's calendars.\n- `calendar.createEvent`: Creates a new event in a calendar.\n- `calendar.listEvents`: Lists events from a calendar.\n- `calendar.getEvent`: Gets the details of a specific calendar event.\n- `calendar.findFreeTime`: Finds a free time slot for multiple people to meet.\n- `calendar.updateEvent`: Updates an existing event in a calendar.\n- `calendar.respondToEvent`: Responds to a meeting invitation (accept, decline,\n or tentative).\n- `calendar.deleteEvent`: Deletes an event from a calendar.\n\n### Google Chat\n\n- `chat.listSpaces`: Lists the spaces the user is a member of.\n- `chat.findSpaceByName`: Finds a Google Chat space by its display name.\n- `chat.sendMessage`: Sends a message to a Google Chat space.\n- `chat.getMessages`: Gets messages from a Google Chat space.\n- `chat.sendDm`: Sends a direct message to a user.\n- `chat.findDmByEmail`: Finds a Google Chat DM space by a user's email address.\n- `chat.listThreads`: Lists threads from a Google Chat space in reverse\n chronological order.\n- `chat.setUpSpace`: Sets up a new Google Chat space with a display name and a\n list of members.\n\n### Gmail\n\n- `gmail.search`: Search for emails in Gmail using query parameters.\n- `gmail.get`: Get the full content of a specific email message.\n- `gmail.downloadAttachment`: Downloads an attachment from a Gmail message to a\n local file.\n- `gmail.modify`: Modify a Gmail message.\n- `gmail.batchModify`: Bulk modify up to 1,000 Gmail messages at once.\n- `gmail.modifyThread`: Modify labels on all messages in a Gmail thread.\n- `gmail.send`: Send an email message.\n- `gmail.createDraft`: Create a draft email message.\n- `gmail.sendDraft`: Send a previously created draft email.\n- `gmail.listLabels`: List all Gmail labels in the user's mailbox.\n- `gmail.createLabel`: Create a new Gmail label.\n\n### Time\n\n- `time.getCurrentDate`: Gets the current date. Returns both UTC (for API use)\n and local time (for user display), along with the timezone.\n- `time.getCurrentTime`: Gets the current time. Returns both UTC (for API use)\n and local time (for user display), along with the timezone.\n- `time.getTimeZone`: Gets the local timezone.\n\n### People\n\n- `people.getUserProfile`: Gets a user's profile information.\n- `people.getMe`: Gets the profile information of the authenticated user.\n- `people.getUserRelations`: Gets a user's relations (e.g., manager, spouse,\n assistant). Defaults to the authenticated user and supports filtering by\n relation type.\n\n## Custom Commands\n\nThe extension includes several pre-configured commands for common tasks:\n\n- `/calendar/get-schedule`: Show your schedule for today, or a specified date.\n- `/calendar/clear-schedule`: Clear all events for a specific date or range by\n deleting or declining them.\n- `/drive/search`: Searches Google Drive for files matching a query and displays\n their name and ID.\n- `/gmail/search`: Searches for emails in Gmail matching a query and displays\n the sender, subject, and snippet.\n\n## Release Notes\n\nSee the [Release Notes](release_notes.md) for details on new features and\nchanges.\n" }, { "path": "docs/release.md", "content": "# Release Process\n\nThis project uses GitHub Actions to automate the release process.\n\n## Prerequisites\n\n- [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated.\n- Write permissions to the repository.\n\n## Creating a Release\n\nTo streamline the release process:\n\n1. **Update Version**: Run the `set-version` script to update the version in\n `package.json` files. The `workspace-server` will now dynamically read its\n version from its `package.json`.\n\n ```bash\n npm run set-version #0.0.x for example\n ```\n\n2. **Commit Changes**: Commit the version bump and push the changes to `main`\n (either directly or via a PR).\n\n ```bash\n git commit -am \"chore: bump version to \"\n git push origin main\n ```\n\n3. **Create Release**: Use the `gh release create` command. This will trigger\n the GitHub Actions workflow to build the extension and attach the artifacts\n to the release.\n\n ```bash\n # Syntax: gh release create --generate-notes\n gh release create v --generate-notes\n ```\n\n### What happens next?\n\n1. **GitHub Actions Trigger**: The `release.yml` workflow is triggered by the\n new tag.\n2. **Build**: The workflow builds the project using `npm run build`.\n3. **Package**: It creates a `workspace-server.tar.gz` file containing the\n extension.\n4. **Upload**: The workflow uploads the tarball to the release you just\n created.\n\n## Manual Release (Alternative)\n\nIf you prefer not to use the CLI, you can also push a tag manually:\n\n```bash\ngit tag v1.0.0\ngit push origin v1.0.0\n```\n\nThis pushes the tag to GitHub, which triggers the release workflow to create a\nrelease and upload the artifacts. However, using `gh release create` is\nrecommended as it allows you to easily generate release notes.\n" }, { "path": "docs/release_notes.md", "content": "# Release Notes\n\n## 0.0.8 (2026-05-01)\n\n### New Features\n\n- **Google Calendar**: Added support for `eventType` (Out of Office, Focus Time,\n Working Location) in Calendar Service.\n- **Feature Configuration**: Introduced a new feature configuration service for\n scope-based toggles, allowing more granular control over available tools.\n\n### Improvements\n\n- **Authentication**: Refactored OAuth scope management to use a single source\n of truth and deduplicate read scopes, improving security and consistency.\n- **Google Calendar**: Refactored validation logic to be independent of the\n service layer.\n- **Google Docs**: Improved `getText` and `getSuggestions` tools to include the\n document title in their output.\n\n### Fixes\n\n- **Google Docs**: Resolved API errors in `docs.getText`.\n- **Windows Support**: Fixed issues with `npm run clean` and handled `npm.cmd`\n correctly on Windows.\n- **Documentation**: Fixed various documentation links and improved clarity of\n API usage.\n\n### Chores\n\n- **Dependencies**: Major update to TypeScript 6.0.3 and various other\n dependency bumps (Vite 8, Hono 4.12, etc.).\n\n## 0.0.7 (2026-03-11)\n\n### Breaking Changes\n\n- **Google Sheets**: Removed `sheets.find` tool. Use `drive.search` with MIME\n type filter instead (e.g.,\n `mimeType='application/vnd.google-apps.spreadsheet'`).\n- **Google Slides**: Removed `slides.find` tool. Use `drive.search` with MIME\n type filter instead (e.g.,\n `mimeType='application/vnd.google-apps.presentation'`).\n\n### Improvements\n\n- **Skills**: Renamed all skill directories to `google-*` prefix (e.g.,\n `calendar` → `google-calendar`) to avoid slash command conflicts.\n- **Calendar Skill**: Added explicit `calendarId='primary'` mandate to prevent\n agents from omitting the required parameter.\n\n### Skills\n\n- **Sheets Skill**: New skill with `drive.search` guidance for finding\n spreadsheets.\n- **Slides Skill**: New skill with `drive.search` guidance for finding\n presentations.\n- **Docs Skill**: Updated with `drive.search` guidance and removed stale\n `docs.find`/`docs.move` references from skill and documentation.\n\n## 0.0.6 (2026-03-08)\n\n### New Features\n\n- **Google Docs**: Parse rich smart chips (person, date, rich link) in document\n text output.\n- **Google Docs**: Added `getSuggestions` and `getComments` tools for reading\n document suggestions and comments.\n- **Google Docs**: Added `formatText` tool for applying rich formatting (bold,\n italic, headings, etc.) to text ranges.\n- **Google Calendar**: Added Google Meet link generation and Google Drive file\n attachment support for `createEvent` and `updateEvent`.\n- **Google Calendar**: Added `sendUpdates` parameter to `createEvent` for\n controlling attendee notifications.\n- **Google Drive**: Added `trashFile` tool to move files and folders to trash.\n- **Google Drive**: Added `renameFile` tool to rename files and folders.\n- **Gmail**: Added `batchModify` tool for bulk modifying up to 1,000 messages at\n once.\n- **Gmail**: Added `modifyThread` tool for modifying all messages in a Gmail\n thread.\n- **Gmail**: Added `threadId` support in `createDraft` for creating reply\n drafts.\n- **Authentication**: Added headless OAuth login for SSH, WSL, and Cloud Shell\n environments.\n\n### Skills\n\n- **Gmail Skill**: Added rich HTML formatting guidance for email composition.\n- **Chat Skill**: Added Google Chat messaging and space management guidance.\n- **Docs Skill**: Added document formatting and simplified tool primitives.\n- **Calendar Skill**: Added consolidated calendar scheduling guidance.\n\n### Fixes\n\n- **Docs**: Fixed recursion into nested child tabs in DocsService.\n- **Docs**: Polished `getSuggestions` and `getComments` output formatting.\n- **Drive**: Fixed shared drive file downloads.\n\n### Documentation & Chores\n\n- Documented token storage locations (OS keychain and encrypted file fallback).\n- Updated tool reference documentation with latest features.\n- **Dependencies**: Updated MCP SDK, Hono, Google APIs, rollup, ajv, qs, and\n minimatch.\n\n## 0.0.5 (2026-02-11)\n\n### New Features\n\n- **Gmail**: Added `createLabel` tool to manage email labels.\n- **Slides**: Added `getImages` and `getSlideThumbnail` tools for better visual\n integration, and included slide IDs in `getMetadata` output.\n- **Drive**: Enhanced support for shared drives.\n- **Calendar**: Added support for event descriptions.\n- **GCP**: Added comprehensive documentation and automation for GCP project\n recreation.\n- **Logging**: Added authentication status updates via MCP logging for better\n observability.\n- **Tools**: Added annotations for read-only tools to improve agent interaction.\n\n### Fixes\n\n- **Security**: Resolved esbuild vulnerability via vite override.\n- **Compatibility**: Normalised tool names to underscores for better\n compatibility with other agents (e.g., Cursor).\n- **Config**: Removed unused arguments in extension configuration.\n\n### Documentation & Chores\n\n- **Formatting**: Updated context documentation with Chat-specific formatting\n instructions.\n- **Infrastructure**: Allowed `.gemini` directory in git and added Prettier to\n CI/CD pipeline.\n- **Dependencies**: Updated MCP SDK, Hono, Google APIs, and other core\n libraries.\n\n## 0.0.4 (2026-01-05)\n\n### New Features\n\n- **Google Drive**: Added `drive.createFolder` to create new folders.\n- **People**: Added `people.getUserRelations` to retrieve user relationships\n (manager, reports, etc.).\n- **Google Chat**: Added threading support to `chat.sendMessage` and\n `chat.sendDm`, and filtering by thread in `chat.getMessages`.\n- **Gmail**: Added `gmail.downloadAttachment` to download email attachments.\n- **Google Drive**: Added `drive.downloadFile` to download files from Google\n Drive.\n- **Calendar**: Added `calendar.deleteEvent` to delete calendar events.\n- **Google Docs**: Added support for Tabs in DocsService.\n\n### Improvements\n\n- **Dependencies**: Updated various dependencies including `@googleapis/drive`,\n `google-googleapis`, and `jsdom`.\n- **CI/CD**: Added a weekly preview release workflow and updated GitHub Actions\n versions.\n- **Testing**: Added documentation for the testing process with Gemini CLI.\n\n### Fixes\n\n- Fixed an issue where the `v` prefix was not stripped correctly in the release\n script.\n- Fixed an issue with invalid assignees in dependabot config.\n- Fixed log directory creation.\n\n## 0.0.3\n\n- Initial release with support for Google Docs, Sheets, Slides, Drive, Calendar,\n Gmail, Chat, Time, and People.\n" }, { "path": "eslint.config.js", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nconst tseslint = require('@typescript-eslint/eslint-plugin');\nconst tsParser = require('@typescript-eslint/parser');\nconst headers = require('eslint-plugin-headers');\nconst importPlugin = require('eslint-plugin-import');\n\nmodule.exports = [\n {\n ignores: [\n '**/dist/',\n '*.js',\n '**/node_modules/',\n '**/coverage/',\n '!eslint.config.js',\n '**/docs/.vitepress/cache/',\n '**/docs/.vitepress/dist/',\n ],\n },\n {\n files: ['workspace-server/src/**/*.ts'],\n ignores: ['**/*.test.ts', '**/*.spec.ts'],\n languageOptions: {\n parser: tsParser,\n parserOptions: {\n project: true,\n tsconfigRootDir: __dirname,\n ecmaVersion: 2020,\n sourceType: 'module',\n },\n },\n plugins: {\n '@typescript-eslint': tseslint,\n },\n rules: {\n ...tseslint.configs.recommended.rules,\n '@typescript-eslint/no-explicit-any': 'off',\n '@typescript-eslint/explicit-function-return-type': 'off',\n '@typescript-eslint/no-unused-vars': [\n 'warn',\n {\n argsIgnorePattern: '^_',\n varsIgnorePattern: '^_',\n caughtErrorsIgnorePattern: '^_',\n },\n ],\n 'prefer-const': 'warn',\n },\n },\n {\n files: [\n 'workspace-server/src/**/*.test.ts',\n 'workspace-server/src/**/*.spec.ts',\n ],\n languageOptions: {\n parser: tsParser,\n parserOptions: {\n ecmaVersion: 2020,\n sourceType: 'module',\n },\n },\n plugins: {\n '@typescript-eslint': tseslint,\n },\n rules: {\n ...tseslint.configs.recommended.rules,\n '@typescript-eslint/no-explicit-any': 'off',\n '@typescript-eslint/explicit-function-return-type': 'off',\n '@typescript-eslint/no-unused-vars': [\n 'warn',\n {\n argsIgnorePattern: '^_',\n varsIgnorePattern: '^_',\n },\n ],\n 'prefer-const': 'warn',\n },\n },\n {\n files: ['./**/*.{tsx,ts,js}'],\n ignores: ['workspace-server/src/index.ts'], // Has shebang which conflicts with license header\n plugins: {\n headers,\n import: importPlugin,\n },\n rules: {\n 'headers/header-format': [\n 'error',\n {\n source: 'string',\n content: [\n '@license',\n 'Copyright (year) Google LLC',\n 'SPDX-License-Identifier: Apache-2.0',\n ].join('\\n'),\n patterns: {\n year: {\n pattern: '202[5-6]',\n defaultValue: '2026',\n },\n },\n },\n ],\n 'import/enforce-node-protocol-usage': ['error', 'always'],\n },\n },\n {\n files: ['workspace-server/src/index.ts'],\n plugins: {\n import: importPlugin,\n },\n rules: {\n 'import/enforce-node-protocol-usage': ['error', 'always'],\n },\n },\n];\n" }, { "path": "gemini-extension.json", "content": "{\n \"name\": \"google-workspace\",\n \"version\": \"0.0.8\",\n \"contextFileName\": \"workspace-server${/}WORKSPACE-Context.md\",\n \"mcpServers\": {\n \"google-workspace\": {\n \"command\": \"node\",\n \"args\": [\"scripts${/}start.js\"],\n \"cwd\": \"${extensionPath}\"\n }\n }\n}\n" }, { "path": "jest.config.js", "content": "/** @type {import('jest').Config} */\nmodule.exports = {\n preset: 'ts-jest',\n testEnvironment: 'node',\n projects: [\n {\n displayName: 'workspace-server',\n testMatch: [\n '/workspace-server/src/**/*.test.ts',\n '/workspace-server/src/**/*.spec.ts',\n ],\n transform: {\n '^.+\\\\.ts$': [\n 'ts-jest',\n {\n tsconfig: {\n strict: false,\n types: ['jest', 'node'],\n },\n },\n ],\n },\n transformIgnorePatterns: ['node_modules/'],\n moduleNameMapper: {\n '^@/(.*)$': '/workspace-server/src/$1',\n '\\\\.wasm$': '/workspace-server/src/__tests__/mocks/wasm.js',\n },\n roots: ['/workspace-server/src'],\n setupFilesAfterEnv: ['/workspace-server/src/__tests__/setup.ts'],\n collectCoverageFrom: [\n '/workspace-server/src/**/*.ts',\n '!/workspace-server/src/**/*.d.ts',\n '!/workspace-server/src/**/*.test.ts',\n '!/workspace-server/src/**/*.spec.ts',\n '!/workspace-server/src/index.ts',\n ],\n coverageDirectory: '/coverage',\n coverageThreshold: {\n global: {\n branches: 45,\n functions: 65,\n lines: 60,\n statements: 60,\n },\n },\n },\n ],\n coverageReporters: ['text', 'lcov', 'html'],\n testTimeout: 10000,\n verbose: true,\n};\n" }, { "path": "package.json", "content": "{\n \"name\": \"gemini-workspace-extension\",\n \"version\": \"0.0.8\",\n \"description\": \"Google Workspace Server Extension\",\n \"private\": true,\n \"bin\": {\n \"gemini-workspace-server\": \"workspace-server/dist/index.js\"\n },\n \"workspaces\": [\n \"workspace-server\"\n ],\n \"scripts\": {\n \"prepare\": \"npm run build\",\n \"build\": \"npm run build --workspaces --if-present\",\n \"test\": \"npm run test --workspaces --if-present\",\n \"test:watch\": \"npm run test:watch --workspaces --if-present\",\n \"test:coverage\": \"npm run test:coverage --workspaces --if-present\",\n \"test:ci\": \"npm run test:ci --workspaces --if-present\",\n \"start\": \"npm run start --workspaces --if-present\",\n \"auth-utils\": \"npm run build:auth-utils -w workspace-server && node scripts/auth-utils.js\",\n \"clean\": \"node scripts/clean.js\",\n \"lint\": \"eslint .\",\n \"lint:fix\": \"eslint . --fix\",\n \"format:check\": \"prettier --check .\",\n \"format:fix\": \"prettier --write .\",\n \"release\": \"node scripts/release.js\",\n \"release:dev\": \"npm install && npm run build && node scripts/release.js\",\n \"set-version\": \"node scripts/set-version.js\",\n \"version\": \"node scripts/set-version.js && git add workspace-server/package.json\",\n \"docs:dev\": \"vitepress dev docs\",\n \"docs:build\": \"vitepress build docs\",\n \"docs:preview\": \"vitepress preview docs\"\n },\n \"dependencies\": {\n \"@google-apps/chat\": \"^0.23.0\",\n \"@google-cloud/local-auth\": \"^3.0.1\",\n \"@googleapis/docs\": \"^9.2.1\",\n \"@googleapis/drive\": \"^20.1.0\",\n \"@modelcontextprotocol/sdk\": \"^1.29.0\",\n \"google-auth-library\": \"^10.6.2\",\n \"googleapis\": \"^171.2.0\",\n \"keytar\": \"^7.9.0\"\n },\n \"devDependencies\": {\n \"@jest/globals\": \"^30.3.0\",\n \"@types/jest\": \"^30.0.0\",\n \"@types/node\": \"^25.6.0\",\n \"@typescript-eslint/eslint-plugin\": \"^8.59.1\",\n \"@typescript-eslint/parser\": \"^8.55.0\",\n \"@vercel/ncc\": \"^0.38.3\",\n \"archiver\": \"^7.0.1\",\n \"esbuild\": \"^0.28.0\",\n \"eslint\": \"^9.39.4\",\n \"eslint-plugin-headers\": \"^1.3.4\",\n \"eslint-plugin-import\": \"^2.32.0\",\n \"eslint-plugin-license-header\": \"^0.9.0\",\n \"jest\": \"^30.3.0\",\n \"minimist\": \"^1.2.8\",\n \"prettier\": \"^3.8.3\",\n \"ts-jest\": \"^29.4.9\",\n \"ts-node\": \"^10.9.2\",\n \"typescript\": \"^6.0.3\",\n \"vite\": \"^8.0.10\",\n \"vitepress\": \"^1.6.4\",\n \"vue\": \"^3.5.33\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/gemini-cli-extensions/workspace.git\"\n },\n \"keywords\": [\n \"google-workspace\",\n \"gmail\",\n \"google-docs\",\n \"google-drive\",\n \"google-calendar\",\n \"google-chat\",\n \"google-people\",\n \"google-sheets\",\n \"google-slides\",\n \"gemini-cli\"\n ],\n \"author\": \"Allen Hutchison\",\n \"license\": \"Apache-2.0\",\n \"overrides\": {\n \"vite\": \"$vite\"\n }\n}\n" }, { "path": "scripts/auth-utils.js", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nconst {\n OAuthCredentialStorage,\n} = require('../workspace-server/dist/auth-utils.js');\n\nasync function clearAuth() {\n try {\n await OAuthCredentialStorage.clearCredentials();\n console.log('✅ Authentication credentials cleared successfully.');\n } catch (error) {\n console.error('❌ Failed to clear authentication credentials:', error);\n process.exit(1);\n }\n}\n\nasync function expireToken() {\n try {\n const credentials = await OAuthCredentialStorage.loadCredentials();\n if (!credentials) {\n console.log('ℹ️ No credentials found to expire.');\n return;\n }\n\n // Set expiry to 1 second ago\n credentials.expiry_date = Date.now() - 1000;\n await OAuthCredentialStorage.saveCredentials(credentials);\n console.log('✅ Access token expired successfully.');\n console.log(' Next API call will trigger proactive refresh.');\n } catch (error) {\n console.error('❌ Failed to expire token:', error);\n process.exit(1);\n }\n}\n\nasync function showStatus() {\n try {\n const credentials = await OAuthCredentialStorage.loadCredentials();\n if (!credentials) {\n console.log('ℹ️ No credentials found.');\n return;\n }\n\n const now = Date.now();\n const expiry = credentials.expiry_date;\n const hasRefreshToken = !!credentials.refresh_token;\n const hasAccessToken = !!credentials.access_token;\n const isExpired = expiry ? expiry < now : false;\n\n console.log('📊 Auth Status:');\n console.log(\n ` Access Token: ${hasAccessToken ? '✅ Present' : '❌ Missing'}`,\n );\n console.log(\n ` Refresh Token: ${hasRefreshToken ? '✅ Present' : '❌ Missing'}`,\n );\n if (expiry) {\n console.log(` Expiry: ${new Date(expiry).toISOString()}`);\n console.log(` Status: ${isExpired ? '❌ EXPIRED' : '✅ Valid'}`);\n if (!isExpired) {\n const minutesLeft = Math.floor((expiry - now) / 1000 / 60);\n console.log(` Time left: ~${minutesLeft} minutes`);\n }\n } else {\n console.log(` Expiry: ⚠️ Unknown`);\n }\n } catch (error) {\n console.error('❌ Failed to get auth status:', error);\n process.exit(1);\n }\n}\n\nasync function login() {\n try {\n require('../workspace-server/dist/headless-login.js');\n } catch (error) {\n console.error(\n '❌ Failed to load headless-login module. Run \"npm run build:headless-login\" first.',\n );\n console.error(error.message);\n process.exit(1);\n }\n}\n\nfunction showHelp() {\n console.log(`\nAuth Management CLI\n\nUsage: npm run auth-utils -- \n\nCommands:\n login Authenticate via headless OAuth flow (for SSH/WSL/Cloud Shell)\n clear Clear all authentication credentials\n expire Force the access token to expire (for testing refresh)\n status Show current authentication status\n help Show this help message\n\nExamples:\n npm run auth-utils -- login\n npm run auth-utils -- clear\n npm run auth-utils -- expire\n npm run auth-utils -- status\n`);\n}\n\nasync function main() {\n const command = process.argv[2];\n\n switch (command) {\n case 'login':\n await login();\n break;\n case 'clear':\n await clearAuth();\n break;\n case 'expire':\n await expireToken();\n break;\n case 'status':\n await showStatus();\n break;\n case 'help':\n case '--help':\n case '-h':\n showHelp();\n break;\n default:\n if (!command) {\n console.error('❌ No command specified.');\n } else {\n console.error(`❌ Unknown command: ${command}`);\n }\n showHelp();\n process.exit(1);\n }\n}\n\nmain();\n" }, { "path": "scripts/clean.js", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nconst { rmSync, readFileSync } = require('node:fs');\nconst { join } = require('node:path');\n\nconst root = join(__dirname, '..');\nconst RMRF = { recursive: true, force: true };\n\nfunction rmrfSyncVerbose(path) {\n console.log(`Removing ${path}`);\n rmSync(path, RMRF);\n}\n\n// Clean up all workspaces.\nconst { workspaces } = JSON.parse(\n readFileSync(join(root, 'package.json'), 'utf-8'),\n);\nfor (const workspace of workspaces) {\n rmrfSyncVerbose(join(root, workspace, 'dist'));\n}\n\n// Root artifacts.\nrmrfSyncVerbose(join(root, 'node_modules'));\nrmrfSyncVerbose(join(root, 'release'));\nrmrfSyncVerbose(join(root, 'logs'));\nrmrfSyncVerbose(join(root, 'docs', '.vitepress', 'cache'));\nrmrfSyncVerbose(join(root, 'docs', '.vitepress', 'dist'));\n" }, { "path": "scripts/list-deps.js", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nconst path = require('node:path');\nconst { getTransitiveDependencies } = require('./utils/dependencies');\n\nconst root = path.join(__dirname, '..');\nconst targetPackages = process.argv.slice(2);\n\nif (targetPackages.length === 0) {\n console.log('Usage: node scripts/list-deps.js [package2...]');\n process.exit(1);\n}\n\nconsole.log(`Analyzing dependencies for: ${targetPackages.join(', ')}`);\n\nconst allDeps = getTransitiveDependencies(root, targetPackages);\n\nconsole.log('\\nTransitive Dependencies:');\nArray.from(allDeps)\n .sort()\n .forEach((dep) => {\n console.log(`- ${dep}`);\n });\n" }, { "path": "scripts/print-scopes.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\n/**\n * Prints the OAuth scopes that should be registered on the GCP consent\n * screen, one per line. Sourced from FEATURE_GROUPS so the registration\n * list and the runtime request list cannot drift.\n *\n * Used by scripts/setup-gcp.sh.\n */\n\nimport { getAllPossibleScopes } from '../workspace-server/src/features/feature-config';\n\nfor (const scope of getAllPossibleScopes()) {\n console.log(scope);\n}\n" }, { "path": "scripts/release.js", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nconst fs = require('node:fs');\nconst path = require('node:path');\nconst archiver = require('archiver');\nconst argv = require('minimist')(process.argv.slice(2));\n\nconst deleteFilesByExtension = (dir, ext) => {\n if (!fs.existsSync(dir)) {\n return;\n }\n\n const files = fs.readdirSync(dir);\n for (const file of files) {\n const filePath = path.join(dir, file);\n const stat = fs.lstatSync(filePath);\n if (stat.isDirectory()) {\n deleteFilesByExtension(filePath, ext);\n } else if (filePath.endsWith(ext)) {\n fs.unlinkSync(filePath);\n }\n }\n};\n\nconst main = async () => {\n const platform = argv.platform;\n if (platform && typeof platform !== 'string') {\n console.error(\n 'Error: The --platform argument must be a string (e.g., --platform=linux).',\n );\n process.exit(1);\n }\n const baseName = 'google-workspace-extension';\n const name = platform ? `${platform}.${baseName}` : baseName;\n const extension = 'tar.gz';\n\n const rootDir = path.join(__dirname, '..');\n const releaseDir = path.join(rootDir, 'release');\n fs.rmSync(releaseDir, { recursive: true, force: true });\n const archiveName = `${name}.${extension}`;\n const archiveDir = path.join(releaseDir, name);\n const workspaceMcpServerDir = path.join(rootDir, 'workspace-server');\n\n // Create the release directory\n fs.mkdirSync(releaseDir, { recursive: true });\n\n // Create the platform-specific directory\n fs.mkdirSync(archiveDir, { recursive: true });\n\n // Copy the dist directory\n fs.cpSync(\n path.join(workspaceMcpServerDir, 'dist'),\n path.join(archiveDir, 'dist'),\n { recursive: true },\n );\n\n // Clean up the dist directory\n const distDir = path.join(archiveDir, 'dist');\n deleteFilesByExtension(distDir, '.d.ts');\n deleteFilesByExtension(distDir, '.map');\n fs.rmSync(path.join(distDir, '__tests__'), { recursive: true, force: true });\n fs.rmSync(path.join(distDir, 'auth'), { recursive: true, force: true });\n fs.rmSync(path.join(distDir, 'services'), { recursive: true, force: true });\n fs.rmSync(path.join(distDir, 'utils'), { recursive: true, force: true });\n\n // Copy native modules and dependencies (keytar, jsdom)\n const nodeModulesDir = path.join(archiveDir, 'node_modules');\n fs.mkdirSync(nodeModulesDir, { recursive: true });\n\n const { getTransitiveDependencies } = require('./utils/dependencies');\n const visited = getTransitiveDependencies(rootDir, ['keytar', 'jsdom']);\n\n visited.forEach((pkg) => {\n const source = path.join(rootDir, 'node_modules', pkg);\n const dest = path.join(nodeModulesDir, pkg);\n if (fs.existsSync(source)) {\n fs.cpSync(source, dest, { recursive: true });\n }\n });\n\n const packageJson = require('../package.json');\n const version = (process.env.GITHUB_REF_NAME || packageJson.version).replace(\n /^v/,\n '',\n );\n\n // Generate the gemini-extension.json file\n const geminiExtensionJson = {\n name: 'google-workspace',\n version,\n contextFileName: 'WORKSPACE-Context.md',\n mcpServers: {\n 'google-workspace': {\n command: 'node',\n args: ['dist/index.js', '--use-dot-names'],\n cwd: '${extensionPath}',\n },\n },\n };\n fs.writeFileSync(\n path.join(archiveDir, 'gemini-extension.json'),\n JSON.stringify(geminiExtensionJson, null, 2),\n );\n\n // Copy the WORKSPACE-Context.md file\n fs.copyFileSync(\n path.join(workspaceMcpServerDir, 'WORKSPACE-Context.md'),\n path.join(archiveDir, 'WORKSPACE-Context.md'),\n );\n\n // Copy the commands directory\n const commandsDir = path.join(rootDir, 'commands');\n if (fs.existsSync(commandsDir)) {\n fs.cpSync(commandsDir, path.join(archiveDir, 'commands'), {\n recursive: true,\n });\n }\n\n // Copy the skills directory\n const skillsDir = path.join(rootDir, 'skills');\n if (fs.existsSync(skillsDir)) {\n fs.cpSync(skillsDir, path.join(archiveDir, 'skills'), {\n recursive: true,\n });\n }\n\n // Create the archive\n const output = fs.createWriteStream(path.join(releaseDir, archiveName));\n const archive = archiver('tar', {\n gzip: true,\n });\n\n const archivePromise = new Promise((resolve, reject) => {\n output.on('close', function () {\n console.log(archive.pointer() + ' total bytes');\n console.log(\n 'archiver has been finalized and the output file descriptor has closed.',\n );\n resolve();\n });\n\n archive.on('error', function (err) {\n reject(err);\n });\n });\n\n archive.pipe(output);\n archive.directory(archiveDir, false);\n archive.finalize();\n\n await archivePromise;\n};\n\nmain().catch((err) => {\n console.error(err);\n process.exit(1);\n});\n" }, { "path": "scripts/set-version.js", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nconst fs = require('node:fs');\nconst path = require('node:path');\n\nconst rootDir = path.join(__dirname, '..');\nconst packageJsonPath = path.join(rootDir, 'package.json');\nconst workspaceServerPackageJsonPath = path.join(\n rootDir,\n 'workspace-server',\n 'package.json',\n);\nconst geminiExtensionJsonPath = path.join(rootDir, 'gemini-extension.json');\nconst workspaceServerIndexPath = path.join(\n rootDir,\n 'workspace-server',\n 'src',\n 'index.ts',\n);\n\nconst updateJsonFile = (filePath, version) => {\n try {\n const content = JSON.parse(fs.readFileSync(filePath, 'utf8'));\n content.version = version;\n fs.writeFileSync(filePath, JSON.stringify(content, null, 2) + '\\n');\n console.log(\n `Updated ${path.relative(rootDir, filePath)} to version ${version}`,\n );\n } catch (error) {\n console.error(\n `Failed to update JSON file at ${path.relative(rootDir, filePath)}:`,\n error,\n );\n process.exit(1);\n }\n};\n\nconst main = () => {\n let version = process.argv[2];\n\n if (version) {\n // If version is provided as arg, update root package.json first\n updateJsonFile(packageJsonPath, version);\n } else {\n // Otherwise read from root package.json\n const packageJson = require(packageJsonPath);\n version = packageJson.version;\n console.log(`Using version from package.json: ${version}`);\n }\n\n if (!version) {\n console.error('No version specified and no version found in package.json');\n process.exit(1);\n }\n\n updateJsonFile(workspaceServerPackageJsonPath, version);\n updateJsonFile(geminiExtensionJsonPath, version);\n};\n\nmain();\n" }, { "path": "scripts/setup-gcp.sh", "content": "#!/bin/bash\n\n# GCP Setup Script for Google Workspace Extension\n# This script is idempotent — it can be safely re-run without breaking existing config.\n\nset -e\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nNC='\\033[0m' # No Color\n\n# Helper to open a URL in the default browser\nopen_url() {\n if command -v open &> /dev/null; then\n open \"$1\"\n elif command -v xdg-open &> /dev/null; then\n xdg-open \"$1\"\n else\n echo -e \"Could not open browser automatically.\"\n fi\n}\n\necho -e \"${YELLOW}Starting Google Cloud Platform setup...${NC}\"\n\n# Check if gcloud is installed\nif ! command -v gcloud &> /dev/null; then\n echo -e \"${RED}Error: gcloud CLI is not installed. Please install it first.${NC}\"\n exit 1\nfi\n\n# Get current project ID\nPROJECT_ID=$(gcloud config get-value project 2>/dev/null)\nif [ -z \"$PROJECT_ID\" ]; then\n echo -e \"${RED}Error: No Google Cloud project is currently set.${NC}\"\n echo \"Please run: gcloud config set project [PROJECT_ID]\"\n exit 1\nfi\n\necho -e \"Using project: ${GREEN}$PROJECT_ID${NC}\"\n\nSECRET_ID=\"workspace-oauth-client-secret\"\nFUNCTION_NAME=\"workspace-oauth-handler\"\n\n# 1. Enable Required APIs\necho -e \"\\n${YELLOW}Step 1: Enabling Required APIs...${NC}\"\nAPIS=(\n \"drive.googleapis.com\"\n \"docs.googleapis.com\"\n \"calendar-json.googleapis.com\"\n \"chat.googleapis.com\"\n \"gmail.googleapis.com\"\n \"people.googleapis.com\"\n \"slides.googleapis.com\"\n \"sheets.googleapis.com\"\n \"admin.googleapis.com\"\n \"secretmanager.googleapis.com\"\n \"cloudfunctions.googleapis.com\"\n \"cloudbuild.googleapis.com\"\n \"run.googleapis.com\"\n \"artifactregistry.googleapis.com\"\n)\n\nfor api in \"${APIS[@]}\"; do\n echo \"Enabling $api...\"\n gcloud services enable \"$api\"\ndone\n\necho -e \"${GREEN}APIs enabled successfully.${NC}\"\n\n# 2. Configure OAuth Consent Screen\necho -e \"\\n${YELLOW}Step 2: Configure OAuth Consent Screen${NC}\"\necho -e \"The OAuth consent screen must be configured before creating credentials.\"\necho \"\"\n\nCONSENT_URL=\"https://console.cloud.google.com/apis/credentials/consent?project=$PROJECT_ID\"\n\necho -e \"Opening the OAuth consent screen configuration page...\"\nopen_url \"$CONSENT_URL\"\n\necho \"\"\necho -e \"If the page did not open, go to:\"\necho -e \" ${GREEN}$CONSENT_URL${NC}\"\necho \"\"\necho -e \"Configure the consent screen with these settings:\"\necho -e \" 1. Select ${GREEN}Internal${NC} (Google Workspace) or ${GREEN}External${NC}\"\necho -e \" 2. Fill in the App name and Support email\"\necho -e \" 3. Add the following ${GREEN}scopes${NC} (listed below)\"\necho -e \" 4. Under ${GREEN}Test users${NC}, add the email addresses of anyone\"\necho -e \" who will use this extension (required while in Testing mode)\"\necho \"\"\n\n# Single source of truth: scopes are computed from FEATURE_GROUPS in\n# workspace-server/src/features/feature-config.ts. See issue #323.\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nREPO_ROOT=\"$(cd \"$SCRIPT_DIR/..\" && pwd)\"\nSCOPES_OUTPUT=$(cd \"$REPO_ROOT\" && npx --no-install ts-node --transpile-only --project scripts/tsconfig.json scripts/print-scopes.ts 2>&1)\nif [ $? -ne 0 ]; then\n echo -e \"${RED}Error: Failed to compute OAuth scopes from feature-config.ts.${NC}\"\n echo -e \"${RED}Did you run 'npm install' at the repo root?${NC}\"\n echo \"$SCOPES_OUTPUT\"\n exit 1\nfi\n\nSCOPES=()\n# Filter to https:// lines so any Node/ts-node warnings written to stderr\n# (captured via 2>&1 above so we can surface them on failure) don't end up\n# in the user-visible scope list.\nwhile IFS= read -r line; do\n [[ \"$line\" == https://* ]] && SCOPES+=(\"$line\")\ndone <<< \"$SCOPES_OUTPUT\"\n\nif [ ${#SCOPES[@]} -eq 0 ]; then\n echo -e \"${RED}Error: print-scopes.ts produced no scope output.${NC}\"\n echo \"$SCOPES_OUTPUT\"\n exit 1\nfi\n\nfor scope in \"${SCOPES[@]}\"; do\n echo -e \" ${GREEN}$scope${NC}\"\ndone\n\necho \"\"\necho -e \"${YELLOW}Have you finished configuring the OAuth consent screen? (y/n)${NC}\"\nread CONSENT_DONE\nif [ \"$CONSENT_DONE\" != \"y\" ] && [ \"$CONSENT_DONE\" != \"Y\" ]; then\n echo -e \"${RED}Please configure the OAuth consent screen before continuing.${NC}\"\n echo -e \"Re-run this script when ready.\"\n exit 1\nfi\n\n# 3. Deploy Cloud Function\necho -e \"\\n${YELLOW}Step 3: Deploying Cloud Function...${NC}\"\n\necho -e \"${YELLOW}Please enter the GCP region for your Cloud Function (e.g., us-central1):${NC}\"\nread REGION\nif [ -z \"$REGION\" ]; then\n REGION=\"us-central1\"\n echo -e \"${YELLOW}No region entered, defaulting to $REGION.${NC}\"\nfi\n\n# Check if the function already exists and get its URL\nFUNCTION_URL=\"\"\nif gcloud functions describe \"$FUNCTION_NAME\" --region=\"$REGION\" &> /dev/null; then\n FUNCTION_URL=$(gcloud functions describe \"$FUNCTION_NAME\" --region=\"$REGION\" --format='value(serviceConfig.uri)')\n echo -e \"${GREEN}Cloud Function already exists at: $FUNCTION_URL${NC}\"\n echo -e \"It will be updated with the final configuration in a later step.\"\nelse\n echo \"Deploying Cloud Function (initial)...\"\n gcloud functions deploy \"$FUNCTION_NAME\" \\\n --gen2 \\\n --runtime=nodejs22 \\\n --region=\"$REGION\" \\\n --source=\"./cloud_function\" \\\n --entry-point=oauthHandler \\\n --trigger-http \\\n --allow-unauthenticated\n\n FUNCTION_URL=$(gcloud functions describe \"$FUNCTION_NAME\" --region=\"$REGION\" --format='value(serviceConfig.uri)')\nfi\n\nif [ -z \"$FUNCTION_URL\" ]; then\n echo -e \"${RED}Error: Could not retrieve Cloud Function URL. Please check the deployment logs.${NC}\"\n exit 1\nfi\n\necho -e \"${GREEN}Cloud Function URL: $FUNCTION_URL${NC}\"\n\n# 4. Collect OAuth credentials\necho -e \"\\n${YELLOW}Step 4: Configuring OAuth credentials...${NC}\"\necho -e \"Create an OAuth 2.0 Client ID in the Google Cloud Console\"\necho -e \"(or locate your existing one):\"\necho -e \" 1. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID\"\necho -e \" 2. Select ${GREEN}Web application${NC}\"\necho -e \" 3. Add the following as an Authorized redirect URI:\"\necho -e \" ${GREEN}$FUNCTION_URL${NC}\"\necho -e \" 4. Copy the Client ID and Client Secret\"\necho \"\"\n\nCREDENTIALS_URL=\"https://console.cloud.google.com/apis/credentials?project=$PROJECT_ID\"\necho -e \"Opening the Credentials page...\"\nopen_url \"$CREDENTIALS_URL\"\n\necho \"\"\necho -e \"If the page did not open, go to:\"\necho -e \" ${GREEN}$CREDENTIALS_URL${NC}\"\necho \"\"\n\necho -e \"${YELLOW}Please enter the OAuth 2.0 Client ID:${NC}\"\nread CLIENT_ID\nif [ -z \"$CLIENT_ID\" ]; then\n echo -e \"${RED}Error: Client ID cannot be empty.${NC}\"\n exit 1\nfi\n\necho -e \"${YELLOW}Please enter the OAuth 2.0 Client Secret:${NC}\"\nread -s CLIENT_SECRET\necho\nif [ -z \"$CLIENT_SECRET\" ]; then\n echo -e \"${RED}Error: Client Secret cannot be empty.${NC}\"\n exit 1\nfi\n\n# 5. Setup Secret Manager\necho -e \"\\n${YELLOW}Step 5: Storing Client Secret in Secret Manager...${NC}\"\n\nif gcloud secrets describe \"$SECRET_ID\" &> /dev/null; then\n echo \"Secret $SECRET_ID already exists. Adding new version...\"\nelse\n echo \"Creating secret $SECRET_ID...\"\n gcloud secrets create \"$SECRET_ID\" --replication-policy=automatic\nfi\n\necho -n \"$CLIENT_SECRET\" | gcloud secrets versions add \"$SECRET_ID\" --data-file=-\necho -e \"${GREEN}Secret stored successfully.${NC}\"\n\n# 6. Update Cloud Function with OAuth configuration\necho -e \"\\n${YELLOW}Step 6: Updating Cloud Function with OAuth configuration...${NC}\"\ngcloud functions deploy \"$FUNCTION_NAME\" \\\n --gen2 \\\n --runtime=nodejs22 \\\n --region=\"$REGION\" \\\n --source=\"./cloud_function\" \\\n --entry-point=oauthHandler \\\n --trigger-http \\\n --allow-unauthenticated \\\n --set-env-vars \"CLIENT_ID=$CLIENT_ID,SECRET_NAME=projects/$PROJECT_ID/secrets/$SECRET_ID/versions/latest,REDIRECT_URI=$FUNCTION_URL\"\n\necho -e \"${GREEN}Cloud Function updated with OAuth configuration.${NC}\"\n\n# 7. Grant Permissions\necho -e \"\\n${YELLOW}Step 7: Granting Secret Manager Access to Cloud Function...${NC}\"\nSERVICE_ACCOUNT=$(gcloud functions describe \"$FUNCTION_NAME\" --region=\"$REGION\" --format='value(serviceConfig.serviceAccountEmail)')\n\ngcloud secrets add-iam-policy-binding \"$SECRET_ID\" \\\n --member=\"serviceAccount:$SERVICE_ACCOUNT\" \\\n --role=\"roles/secretmanager.secretAccessor\"\n\necho -e \"${GREEN}Permissions granted successfully.${NC}\"\n\necho -e \"\\n${GREEN}GCP Setup Complete!${NC}\"\necho -e \"---------------------------------------------------\"\necho -e \"${YELLOW}Next Steps:${NC}\"\necho \"Set the following environment variables in your local environment:\"\necho -e \" ${GREEN}export WORKSPACE_CLIENT_ID=\\\"$CLIENT_ID\\\"${NC}\"\necho -e \" ${GREEN}export WORKSPACE_CLOUD_FUNCTION_URL=\\\"$FUNCTION_URL\\\"${NC}\"\necho -e \"---------------------------------------------------\"\n" }, { "path": "scripts/start.js", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nconst { spawn } = require('node:child_process');\nconst path = require('node:path');\n\nfunction runCommand(command, args, options) {\n return new Promise((resolve, reject) => {\n // On Windows, npm is a batch file and needs a shell\n if (process.platform === 'win32' && command === 'npm') {\n command = `${command}.cmd`;\n options = { ...options, shell: true };\n }\n const child = spawn(command, args, options);\n\n // Pipe stderr to the parent process's stderr if it's available.\n // This is more efficient than listening for 'data' events.\n if (child.stderr) {\n child.stderr.pipe(process.stderr);\n }\n\n child.on('close', (code) => {\n if (code !== 0) {\n reject(\n new Error(\n `Command failed with code ${code}: ${command} ${args.join(' ')}`,\n ),\n );\n } else {\n resolve();\n }\n });\n child.on('error', (err) => {\n reject(err);\n });\n });\n}\n\nasync function main() {\n try {\n await runCommand('npm', ['install'], {\n stdio: ['ignore', 'ignore', 'pipe'],\n });\n\n const SERVER_PATH = path.join(\n __dirname,\n '..',\n 'workspace-server',\n 'dist',\n 'index.js',\n );\n await runCommand('node', [SERVER_PATH, '--debug', '--use-dot-names'], {\n stdio: 'inherit',\n });\n } catch (error) {\n console.error(error);\n process.exit(1);\n }\n}\n\nmain();\n" }, { "path": "scripts/tsconfig.json", "content": "{\n \"extends\": \"../tsconfig.json\",\n \"compilerOptions\": {\n \"rootDir\": \"..\"\n },\n \"include\": [\"**/*.ts\", \"../workspace-server/src/**/*\"]\n}\n" }, { "path": "scripts/utils/dependencies.js", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nconst fs = require('node:fs');\nconst path = require('node:path');\n\n/**\n * Gets the direct dependencies of a package from its package.json.\n * @param {string} rootDir - The root directory containing node_modules.\n * @param {string} pkgName - The name of the package.\n * @returns {string[]} - A list of dependency names.\n */\nfunction getDependencies(rootDir, pkgName) {\n const pkgPath = path.join(rootDir, 'node_modules', pkgName, 'package.json');\n if (!fs.existsSync(pkgPath)) {\n return [];\n }\n const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));\n return Object.keys(pkg.dependencies || {});\n}\n\n/**\n * Recursively finds all transitive dependencies for a list of packages.\n * @param {string} rootDir - The root directory containing node_modules.\n * @param {string[]} startPkgs - The list of initial packages to resolve.\n * @returns {Set} - A set of all transitive dependencies (including startPkgs).\n */\nfunction getTransitiveDependencies(rootDir, startPkgs) {\n const visited = new Set();\n const toVisit = [...startPkgs];\n\n while (toVisit.length > 0) {\n const pkg = toVisit.pop();\n if (visited.has(pkg)) continue;\n visited.add(pkg);\n\n const deps = getDependencies(rootDir, pkg);\n deps.forEach((dep) => {\n if (!visited.has(dep)) {\n toVisit.push(dep);\n }\n });\n }\n\n return visited;\n}\n\nmodule.exports = {\n getDependencies,\n getTransitiveDependencies,\n};\n" }, { "path": "skills/gmail/SKILL.md", "content": "---\nname: gmail\ndescription: >\n CRITICAL: You MUST activate this skill BEFORE composing, sending, drafting, or\n searching emails. Always trigger this skill as the first step when the user\n mentions \"email\", \"gmail\", or sending a message. Contains strict formatting\n mandates that override default email behavior.\n---\n\n# Gmail Expert\n\nYou are an expert at composing and managing email through the Gmail API. Follow\nthese guidelines when helping users with email tasks.\n\n## Rich Text Email Formatting\n\nWhen composing emails (via `gmail.send` or `gmail.createDraft`), **always use\nHTML formatting with `isHtml: true`** unless the user explicitly requests plain\ntext. Rich HTML emails look professional and are the standard for business\ncommunication.\n\n### Supported HTML Tags\n\nGmail supports a broad set of HTML tags for email bodies. Use these freely:\n\n| Category | Tags |\n| :------- | :---------------------------------------------------------------- |\n| Text | `

`, `
`, ``, `

`, `
`, `
`, `
` |\n| Headings | `
` through `
`                                             |\n| Emphasis | ``, ``, ``, ``, ``, ``, ``        |\n| Code     | ``, `
`                                                 |\n| Lists    | `
    `, `
      `, `
    1. `                                            |\n| Tables   | ``, ``, ``, ``, `
      `, ``           |\n| Links    | ``                                                  |\n| Images   | `\"...\"`                                       |\n\n### Inline CSS Styling\n\nGmail strips `\n```\n\n### Common Inline CSS Properties\n\nThese CSS properties work reliably across Gmail clients:\n\n- **Typography**: `font-family`, `font-size`, `font-weight`, `font-style`,\n  `color`, `text-align`, `text-decoration`, `line-height`, `letter-spacing`\n- **Spacing**: `margin`, `padding` (use on `` for table cell spacing)\n- **Borders**: `border`, `border-collapse` (on ``)\n- **Background**: `background-color`\n- **Layout**: `width`, `max-width`, `height` (on tables and images)\n\n### Things to Avoid\n\n- ❌ `