commit 76a9e7a0cc50754edf8918ef3e81ba47842df60c Author: wehub-resource-sync Date: Mon Jul 13 12:38:06 2026 +0800 chore: import upstream snapshot with attribution diff --git a/.agent/skills/vhs.md b/.agent/skills/vhs.md new file mode 100644 index 0000000..a65ac71 --- /dev/null +++ b/.agent/skills/vhs.md @@ -0,0 +1,101 @@ +--- +description: Writing and editing VHS `.tape` files for terminal demo GIFs +--- + +# VHS Tape Files + +[VHS](https://github.com/charmbracelet/vhs) records terminal sessions into GIFs/MP4s/WebMs from `.tape` scripts. Run with `vhs demo.tape`. + +## Critical Syntax Rules + +### Type command and inline directives + +`Type`, `Sleep`, `Enter` are **separate directives on the same line**, delimited by the closing `"` of the `Type` string. The most common bug is forgetting to close the `Type` string, which causes `Sleep`/`Enter` to be typed literally into the terminal. + +``` +# ✅ CORRECT — closing " before Sleep +Type "echo hello" Sleep 300ms Enter + +# ❌ WRONG — Sleep and Enter are typed as literal text +Type "echo hello Sleep 300ms Enter +``` + +### Type with @speed override + +Override typing speed per-command with `@` immediately after `Type` (no space): + +``` +Type@80ms '{"pageSize": 2}' Sleep 100ms +``` + +### Quoting + +- Double quotes `"..."` are the standard Type delimiter +- Single quotes `'...'` also work and are useful when the typed content contains double quotes (e.g. JSON) +- Escape quotes inside strings with backticks: `` Type `VAR="value"` `` +- When building shell commands with nested quotes, split across multiple `Type` lines: + +``` +Type "gws drive files list --params '" Sleep 100ms +Type@80ms '{"pageSize": 2, "fields": "nextPageToken,files(id)"}' Sleep 100ms +Type "' --page-all" Sleep 300ms Enter +``` + +> **Pitfall**: Every `Type` line that is followed by `Sleep` or `Enter` on the same line MUST close its string first. Audit each line to ensure the quote is closed before any directive. + +## Settings (top of file only) + +Settings must appear before any non-setting command (except `Output`). `TypingSpeed` is the only setting that can be changed mid-tape. + +``` +Output demo.gif + +Set Shell "bash" +Set FontSize 14 +Set Width 1200 +Set Height 1200 +Set Theme "Catppuccin Mocha" +Set WindowBar Colorful +Set WindowBarSize 40 +Set TypingSpeed 40ms +Set Padding 20 +``` + +## Common Commands + +| Command | Example | Notes | +|---|---|---| +| `Output` | `Output demo.gif` | `.gif`, `.mp4`, `.webm` | +| `Type` | `Type "ls -la"` | Type characters | +| `Type@` | `Type@80ms "slow"` | Override typing speed | +| `Sleep` | `Sleep 2s`, `Sleep 300ms` | Pause recording | +| `Enter` | `Enter` | Press enter | +| `Hide` / `Show` | `Hide` ... `Show` | Hide setup commands | +| `Ctrl+` | `Ctrl+C` | Key combos | +| `Tab`, `Space`, `Backspace` | `Tab 2` | Optional repeat count | +| `Up`, `Down`, `Left`, `Right` | `Up 3` | Arrow keys | +| `Wait` | `Wait /pattern/` | Wait for regex on screen | +| `Screenshot` | `Screenshot out.png` | Capture frame | +| `Env` | `Env FOO "bar"` | Set env var | +| `Source` | `Source other.tape` | Include another tape | +| `Require` | `Require jq` | Assert program exists | + +## Hide/Show for Setup + +Use `Hide`/`Show` to run setup commands (e.g. setting `$PATH`, clearing screen) without recording them: + +``` +Hide +Type "export PATH=$PWD/target/release:$PATH" Enter +Type "clear" Enter +Sleep 2s +Show +``` + +## Checklist When Editing Tape Files + +1. **Every `Type` string must be closed** before `Sleep`/`Enter` on the same line +2. **Multi-line Type sequences** that build a single shell command: ensure the final line closes its string and includes `Enter` +3. **Sleep durations** after commands should be long enough for the command to finish (network calls may need 8s+) +4. **Settings go at the top** — only `TypingSpeed` can appear later +5. **Test locally** with `vhs .tape` before committing diff --git a/.agent/workflows/verify-skills.md b/.agent/workflows/verify-skills.md new file mode 100644 index 0000000..c79c609 --- /dev/null +++ b/.agent/workflows/verify-skills.md @@ -0,0 +1,73 @@ +--- +description: Verify all skills/*/SKILL.md files against actual CLI output for accuracy +--- + +# Verify Skills + +Ensure every `skills/*/SKILL.md` file is accurate and optimized for AI agent consumption. + +## Steps + +1. **List all skill files** + +```bash +find skills -name SKILL.md | sort +``` + +2. **Get top-level help for every service** + +// turbo +```bash +for svc in drive sheets gmail calendar admin admin-reports docs slides tasks people chat vault groupssettings reseller licensing apps-script; do + echo "=== $svc ===" + ./target/debug/gws $svc --help 2>&1 + echo +done +``` + +3. **Get sub-resource help for key services** (spot-check method names used in examples) + +// turbo +```bash +./target/debug/gws drive files --help 2>&1 +./target/debug/gws gmail users messages --help 2>&1 +./target/debug/gws sheets spreadsheets --help 2>&1 +./target/debug/gws sheets spreadsheets values --help 2>&1 +./target/debug/gws calendar events --help 2>&1 +./target/debug/gws people people --help 2>&1 +./target/debug/gws chat spaces --help 2>&1 +./target/debug/gws vault matters --help 2>&1 +./target/debug/gws admin users --help 2>&1 +./target/debug/gws tasks tasks --help 2>&1 +``` + +4. **For each SKILL.md, verify the following against the CLI `--help` output:** + + - [ ] **Resource names** match exactly (e.g., `files`, `spreadsheets`, `users`) + - [ ] **Method names** match exactly (e.g., `list`, `insert`, `batchUpdate`, `getContent`) + - [ ] **Nested resource paths** are correct (e.g., `spreadsheets values get`, not `values get`) + - [ ] **Alias** mentioned in the file matches `services.rs` (e.g., `gws script` for apps-script) + - [ ] **API version** in the header is correct + - [ ] **Example commands** use valid `--params` and `--json` flag syntax + - [ ] **No OAuth scopes section** — scopes should not be listed in skill files + - [ ] **Tips section** contains accurate, actionable advice + +5. **Cross-check `shared/SKILL.md`** covers: + + - [ ] `--fields` / field mask syntax + - [ ] CLI syntax (`--params`, `--json`, `--output`, `--upload`, `--page-all`, `--page-limit`, `--page-delay`) + - [ ] Authentication (`GOOGLE_WORKSPACE_CLI_CREDENTIALS`, `GOOGLE_WORKSPACE_API_KEY`) + - [ ] Auto-pagination (`--page-all`) with NDJSON output + - [ ] `gws schema ` introspection + - [ ] Error handling JSON structure + - [ ] Binary download with `--output` + - [ ] Version override (`--api-version`, colon syntax) + +6. **Fix any issues found** — update the SKILL.md files directly. + +7. **Rebuild and re-verify** if any examples were changed. + +// turbo +```bash +cargo build 2>&1 +``` diff --git a/.changeset/README.md b/.changeset/README.md new file mode 100644 index 0000000..e5b6d8d --- /dev/null +++ b/.changeset/README.md @@ -0,0 +1,8 @@ +# Changesets + +Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works +with multi-package repos, or single-package repos to help you version and publish your code. You can +find the full documentation for it [in our repository](https://github.com/changesets/changesets) + +We have a quick list of common questions to get you started engaging with this project in +[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md) diff --git a/.changeset/config.json b/.changeset/config.json new file mode 100644 index 0000000..b821332 --- /dev/null +++ b/.changeset/config.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json", + "changelog": "@changesets/cli/changelog", + "commit": false, + "fixed": [], + "linked": [], + "access": "public", + "baseBranch": "main", + "updateInternalDependencies": "patch", + "ignore": [] +} diff --git a/.changeset/sheets-append-range.md b/.changeset/sheets-append-range.md new file mode 100644 index 0000000..1f6ec7b --- /dev/null +++ b/.changeset/sheets-append-range.md @@ -0,0 +1,5 @@ +--- +"@googleworkspace/cli": minor +--- + +Add `--range` flag to `sheets +append` for targeting specific sheet tabs diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..ce5d273 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,5 @@ +{ + "attribution": { + "commit": "" + } +} diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..f503815 --- /dev/null +++ b/.env.example @@ -0,0 +1,29 @@ +# gws — Google Workspace CLI +# Copy this file to .env and uncomment the variables you need. +# All variables are optional. See README.md for details. + +# ── Authentication ──────────────────────────────────────────────── +# Pre-obtained OAuth2 access token (highest priority; bypasses all credential loading) +# GOOGLE_WORKSPACE_CLI_TOKEN= + +# Path to OAuth credentials JSON (user or service account) +# GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE= + +# ── OAuth Client ────────────────────────────────────────────────── +# OAuth client ID and secret (alternative to saving client_secret.json) +# GOOGLE_WORKSPACE_CLI_CLIENT_ID= +# GOOGLE_WORKSPACE_CLI_CLIENT_SECRET= + +# ── Configuration ───────────────────────────────────────────────── +# Override the config directory (default: ~/.config/gws) +# GOOGLE_WORKSPACE_CLI_CONFIG_DIR= + +# ── Model Armor (response sanitization) ────────────────────────── +# Default Model Armor template (overridden by --sanitize flag) +# GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE= +# Sanitization mode: warn (default) or block +# GOOGLE_WORKSPACE_CLI_SANITIZE_MODE=warn + +# ── Helpers ─────────────────────────────────────────────────────── +# GCP project ID fallback for gmail watch and events subscribe (overridden by --project) +# GOOGLE_WORKSPACE_PROJECT_ID= diff --git a/.gemini/config.yaml b/.gemini/config.yaml new file mode 100644 index 0000000..ee4918a --- /dev/null +++ b/.gemini/config.yaml @@ -0,0 +1,7 @@ +code_review: + comment_severity_threshold: HIGH + pull_request_opened: + help: false + summary: true + code_review: true + include_drafts: false diff --git a/.gemini/style_guide.md b/.gemini/style_guide.md new file mode 100644 index 0000000..5352149 --- /dev/null +++ b/.gemini/style_guide.md @@ -0,0 +1,39 @@ +# Code Review Style Guide + +## Project Architecture + +`gws` is a Rust CLI that dynamically generates commands from Google Discovery Documents at runtime. It does NOT use generated Rust crates (`google-drive3`, etc.) for API interaction. Do not suggest adding API-specific crates to `Cargo.toml`. + +For additional context, read `AGENTS.md`. + +## Security: Trusted vs Untrusted Inputs + +This CLI is frequently invoked by AI/LLM agents. CLI arguments may be adversarial. + +- **CLI arguments (untrusted)** — Must validate paths against traversal (`../../`), reject control characters, percent-encode URL path segments, and use `reqwest .query()` for query parameters. Validators: `validate_safe_output_dir()`, `validate_safe_dir_path()`, `encode_path_segment()`, `validate_resource_name()`. +- **Environment variables (trusted)** — Set by the user in their shell profile, `.env` file, or deployment config. Do NOT flag missing path validation on environment variable values. This is consistent with `XDG_CONFIG_HOME`, `CARGO_HOME`, etc. + +## Test Coverage + +The `codecov/patch` check requires new/modified lines to be covered by tests. Prefer extracting testable helper functions over embedding logic in `main`/`run`. Tests should cover both happy paths and rejection paths (e.g., pass `../../.ssh` and assert `Err`). + +## Changesets + +Every PR must include a `.changeset/.md` file. The package name **must** be `"@googleworkspace/cli"` (not `"googleworkspace-cli"`). Use `patch` for fixes/chores, `minor` for features, `major` for breaking changes. + +## PR Scope + +Review comments must stay within the PR's stated scope. If you spot an improvement opportunity that is unrelated to the PR's purpose (e.g., refactoring constants, adding support for a different credential type, making an unrelated function atomic), mark it as a **follow-up** suggestion — not a blocking review comment. Do not request changes that expand the PR beyond its original intent. + +Examples of scope creep to avoid: +- A bug-fix PR should not grow into a refactoring PR. +- Adding constants for strings used elsewhere is a separate cleanup task. +- Making a pre-existing function atomic is an enhancement, not a fix for the current PR. + +## Severity Calibration + +Mark issues as **critical** only when they cause data loss, security vulnerabilities, or incorrect behavior under normal conditions. Theoretical failures in infallible system APIs (e.g., `tokio::signal::ctrl_c()` registration) are **low** severity — do not label them critical. Contradicting a prior review suggestion (e.g., suggesting `expect()` then flagging `expect()` as wrong) erodes trust; verify consistency with earlier comments before posting. + +## Helper Commands (`+verb`) + +Helpers are handwritten commands that provide value Discovery-based commands cannot: multi-step orchestration, format translation, or multi-API composition. **Do not accept helpers that wrap a single API call, add flags to expose data already in the API response, or re-implement Discovery parameters as custom flags.** See [`src/helpers/README.md`](../src/helpers/README.md) for full guidelines and anti-patterns. diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..3c8b319 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,10 @@ +# Codeowners + +# Core engine code strictly requires your review +# Isolates agents to `skills/` or `src/helpers/` unless absolutely necessary +/src/main.rs @jpoehnelt +/src/executor.rs @jpoehnelt +/src/discovery.rs @jpoehnelt +/src/commands.rs @jpoehnelt +/src/auth.rs @jpoehnelt +/src/schema.rs @jpoehnelt diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..e1c628b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,16 @@ +## Description + +Please include a summary of the change and which issue is fixed. If adding a new feature or command, please include the output of running it with `--dry-run` to prove the JSON request body matches the Discovery Document schema. + +**Dry Run Output:** +```json +// Paste --dry-run output here if applicable +``` + +## Checklist: + +- [ ] My code follows the `AGENTS.md` guidelines (no generated `google-*` crates). +- [ ] I have run `cargo fmt --all` to format the code perfectly. +- [ ] I have run `cargo clippy -- -D warnings` and resolved all warnings. +- [ ] I have added tests that prove my fix is effective or that my feature works. +- [ ] I have provided a Changeset file (e.g. via `pnpx changeset`) to document my changes. diff --git a/.github/labeler.yml b/.github/labeler.yml new file mode 100644 index 0000000..c3fb071 --- /dev/null +++ b/.github/labeler.yml @@ -0,0 +1,78 @@ +# Labels applied to PRs based on changed files. +# Used by the actions/labeler action in .github/workflows/automation.yml + +"area: auth": + - changed-files: + - any-glob-to-any-file: + - crates/google-workspace-cli/src/auth.rs + - crates/google-workspace-cli/src/auth_commands.rs + - crates/google-workspace-cli/src/setup.rs + - crates/google-workspace-cli/src/accounts.rs + - crates/google-workspace-cli/src/credential_store.rs + - crates/google-workspace-cli/src/token_storage.rs + - crates/google-workspace-cli/src/oauth_config.rs + +"area: discovery": + - changed-files: + - any-glob-to-any-file: + - crates/google-workspace-cli/src/discovery.rs + - crates/google-workspace-cli/src/services.rs + - crates/google-workspace/src/discovery.rs + - crates/google-workspace/src/services.rs + +"area: http": + - changed-files: + - any-glob-to-any-file: + - crates/google-workspace-cli/src/executor.rs + - crates/google-workspace-cli/src/client.rs + - crates/google-workspace/src/client.rs + +"area: tui": + - changed-files: + - any-glob-to-any-file: + - crates/google-workspace-cli/src/setup_tui.rs + +"area: mcp": + - changed-files: + - any-glob-to-any-file: + - crates/google-workspace-cli/src/mcp_server.rs + +"area: skills": + - changed-files: + - any-glob-to-any-file: + - crates/google-workspace-cli/src/generate_skills.rs + - skills/** + +"area: docs": + - changed-files: + - any-glob-to-any-file: + - "*.md" + - docs/** + +"area: distribution": + - changed-files: + - any-glob-to-any-file: + - .github/workflows/release.yml + - .github/workflows/release-changesets.yml + - dist-workspace.toml + - Cargo.toml + - crates/*/Cargo.toml + +"area: core": + - changed-files: + - any-glob-to-any-file: + - crates/google-workspace-cli/src/main.rs + - crates/google-workspace-cli/src/commands.rs + - crates/google-workspace-cli/src/error.rs + - crates/google-workspace-cli/src/formatter.rs + - crates/google-workspace-cli/src/fs_util.rs + - crates/google-workspace-cli/src/helpers/** + - crates/google-workspace-cli/src/text.rs + - crates/google-workspace-cli/src/validate.rs + - crates/google-workspace-cli/src/schema.rs + +"crate: google-workspace": + - changed-files: + - any-glob-to-any-file: + - crates/google-workspace/src/** + - crates/google-workspace/Cargo.toml diff --git a/.github/workflows/audit.yml b/.github/workflows/audit.yml new file mode 100644 index 0000000..571cabb --- /dev/null +++ b/.github/workflows/audit.yml @@ -0,0 +1,45 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Audit + +on: + push: + branches: [main] + paths: ['Cargo.lock', 'Cargo.toml', 'crates/*/Cargo.toml'] + pull_request: + branches: [main] + paths: ['Cargo.lock', 'Cargo.toml', 'crates/*/Cargo.toml'] + schedule: + - cron: '0 6 * * *' # Daily at 06:00 UTC + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/main' }} + +jobs: + audit: + name: Security Audit + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - name: Install cargo-audit + uses: taiki-e/install-action@a37010ded18ff788be4440302bd6830b1ae50d8b # cargo-llvm-cov + with: + tool: cargo-audit + + - name: Run cargo audit + run: cargo audit diff --git a/.github/workflows/automation.yml b/.github/workflows/automation.yml new file mode 100644 index 0000000..5eb3de9 --- /dev/null +++ b/.github/workflows/automation.yml @@ -0,0 +1,142 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Automation + +on: + push: + branches: [main] + pull_request_target: + types: [opened, synchronize, reopened] + pull_request_review: + types: [submitted] + +permissions: + contents: write + issues: write + pull-requests: write + +jobs: + format: + name: Format + if: github.event_name == 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + with: + token: ${{ secrets.GOOGLEWORKSPACE_BOT_TOKEN }} + + - name: Install Rust + uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable + with: + components: rustfmt + + - name: Run cargo fmt + run: cargo fmt --all + + - name: Commit and push + run: | + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add -A + git diff --cached --quiet || git commit -m "style: cargo fmt" && git push + + file-labeler: + name: File Labeler + if: github.event_name == 'pull_request_target' + runs-on: ubuntu-latest + steps: + - uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9 # v5 + with: + repo-token: ${{ secrets.GOOGLEWORKSPACE_BOT_TOKEN }} + sync-labels: true + + gemini-review: + name: Gemini Review + if: >- + github.event_name == 'pull_request_target' && + github.event.action == 'synchronize' + runs-on: ubuntu-latest + concurrency: + group: gemini-review-${{ github.event.pull_request.number }} + cancel-in-progress: true + steps: + - name: Remove reviewed label + uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + try { + await github.rest.issues.removeLabel({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.payload.pull_request.number, + name: 'gemini: reviewed', + }); + } catch (e) { + // Label not present — ignore + } + + - name: Debounce + run: sleep 60 + + - name: Trigger Gemini Code Assist review + uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 + with: + github-token: ${{ secrets.GOOGLEWORKSPACE_BOT_TOKEN }} + script: | + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.payload.pull_request.number, + body: '/gemini review', + }); + + gemini-reviewed: + name: Gemini Reviewed + if: >- + github.event_name == 'pull_request_review' && + github.event.review.user.login == 'gemini-code-assist[bot]' + runs-on: ubuntu-latest + steps: + - name: Add reviewed label if review matches HEAD + uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + const pr = await github.rest.pulls.get({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.payload.pull_request.number, + }); + + if (context.payload.review.commit_id !== pr.data.head.sha) { + console.log(`Review is for ${context.payload.review.commit_id} but HEAD is ${pr.data.head.sha} — skipping label`); + return; + } + + try { + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.payload.pull_request.number, + labels: ['gemini: reviewed'], + }); + } catch (e) { + if (e.status === 403) { + console.log(`Token cannot add labels for this review event (${e.message}) — skipping`); + return; + } + throw e; + } diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..1eedc99 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,429 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/main' }} + +env: + CARGO_TERM_COLOR: always + SCCACHE_GHA_ENABLED: "true" + SCCACHE_IGNORE_SERVER_IO_ERROR: "true" + +jobs: + changes: + name: Detect Changes + runs-on: ubuntu-latest + outputs: + rust: ${{ steps.filter.outputs.rust }} + nix: ${{ steps.filter.outputs.nix }} + skills: ${{ steps.filter.outputs.skills }} + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3 + id: filter + with: + filters: | + rust: + - '**/*.rs' + - 'Cargo.toml' + - 'crates/*/Cargo.toml' + - 'Cargo.lock' + - 'build.rs' + - '.cargo/**' + nix: + - 'flake.nix' + - 'flake.lock' + skills: + - 'skills/**' + + test: + name: Test + needs: changes + if: needs.changes.outputs.rust == 'true' || github.event_name == 'push' + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest, macos-latest] + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - name: Install Rust + uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable + + - name: Setup sccache + id: sccache + uses: mozilla-actions/sccache-action@2df7dbab909c49ab7d3382d05da469f3f975c2d6 # v0.0.7 + continue-on-error: true + + - name: Enable sccache + if: steps.sccache.outcome == 'success' + shell: bash + run: | + if sccache --start-server 2>/dev/null; then + echo "RUSTC_WRAPPER=sccache" >> "$GITHUB_ENV" + else + echo "::warning::sccache server failed to start, building without cache" + fi + + - name: Cache cargo + uses: Swatinem/rust-cache@ad397744b0d591a723ab90405b7247fac0e6b8db # v2 + with: + key: test-${{ matrix.os }} + + - name: Run tests + run: cargo test --workspace --verbose + + nix: + name: Nix + needs: changes + if: needs.changes.outputs.rust == 'true' || needs.changes.outputs.nix == 'true' || github.event_name == 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + - name: Install Nix + uses: DeterminateSystems/nix-installer-action@d96bc962e61b3049ce8128d03d57a1144fa96539 # main + - name: Magic Nix Cache + uses: DeterminateSystems/magic-nix-cache-action@cec65ff6f104850203b152861d3f9e5f1747885d # main + - name: Check flake + run: nix flake check + - name: Build flake + run: nix build . + + lint: + name: Lint + needs: changes + if: needs.changes.outputs.rust == 'true' || github.event_name == 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - name: Install Rust + uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable + with: + components: rustfmt, clippy + + - name: Setup sccache + id: sccache + uses: mozilla-actions/sccache-action@2df7dbab909c49ab7d3382d05da469f3f975c2d6 # v0.0.7 + continue-on-error: true + + - name: Enable sccache + if: steps.sccache.outcome == 'success' + shell: bash + run: | + if sccache --start-server 2>/dev/null; then + echo "RUSTC_WRAPPER=sccache" >> "$GITHUB_ENV" + else + echo "::warning::sccache server failed to start, building without cache" + fi + + - name: Cache cargo + uses: Swatinem/rust-cache@ad397744b0d591a723ab90405b7247fac0e6b8db # v2 + with: + key: lint + + - name: Check formatting + run: | + if ! cargo fmt --all -- --check; then + echo "::error::Cargo fmt failed. Please run 'cargo fmt --all' locally and commit the changes." + exit 1 + fi + + - name: Clippy + run: cargo clippy --workspace -- -D warnings + + deny: + name: Cargo Deny + needs: changes + if: needs.changes.outputs.rust == 'true' || github.event_name == 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - name: Cargo deny + uses: EmbarkStudios/cargo-deny-action@3fd3802e88374d3fe9159b834c7714ec57d6c979 # v2.0.15 + with: + command: check + + + skills: + name: Verify Skills + needs: changes + if: needs.changes.outputs.rust == 'true' || github.event_name == 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - name: Install Rust + uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable + + - name: Setup sccache + id: sccache + uses: mozilla-actions/sccache-action@2df7dbab909c49ab7d3382d05da469f3f975c2d6 # v0.0.7 + continue-on-error: true + + - name: Enable sccache + if: steps.sccache.outcome == 'success' + shell: bash + run: | + if sccache --start-server 2>/dev/null; then + echo "RUSTC_WRAPPER=sccache" >> "$GITHUB_ENV" + else + echo "::warning::sccache server failed to start, building without cache" + fi + + - name: Cache cargo + uses: Swatinem/rust-cache@ad397744b0d591a723ab90405b7247fac0e6b8db # v2 + with: + key: skills + + - name: Regenerate skills + run: cargo run -- generate-skills --output-dir skills + + - name: Check for drift + run: | + if ! git diff --exit-code skills/; then + echo "::warning::Skills are out of date — the hourly auto-sync PR will fix this automatically." + fi + + lint-skills: + name: Lint Skills + needs: changes + if: needs.changes.outputs.skills == 'true' || github.event_name == 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + + - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5 + + - name: Validate skills + run: | + failed=0 + for skill_dir in skills/*/; do + if ! uvx --from skills-ref@0.1.1 agentskills validate "$skill_dir"; then + failed=1 + fi + done + if [ "$failed" -ne 0 ]; then + echo "::error::One or more skills failed validation." + exit 1 + fi + + build-linux: + name: Build (Linux x86_64) + needs: changes + if: needs.changes.outputs.rust == 'true' || github.event_name == 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - name: Install Rust + uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable + with: + targets: x86_64-unknown-linux-gnu + + - name: Setup sccache + id: sccache + uses: mozilla-actions/sccache-action@2df7dbab909c49ab7d3382d05da469f3f975c2d6 # v0.0.7 + continue-on-error: true + + - name: Enable sccache + if: steps.sccache.outcome == 'success' + shell: bash + run: | + if sccache --start-server 2>/dev/null; then + echo "RUSTC_WRAPPER=sccache" >> "$GITHUB_ENV" + else + echo "::warning::sccache server failed to start, building without cache" + fi + + - name: Cache cargo + uses: Swatinem/rust-cache@ad397744b0d591a723ab90405b7247fac0e6b8db # v2 + with: + key: build-x86_64-unknown-linux-gnu + cache-targets: "false" + + - name: Build + run: cargo build --release --target x86_64-unknown-linux-gnu + + - name: Upload binary + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + with: + name: gws-linux-x86_64 + path: target/x86_64-unknown-linux-gnu/release/gws + retention-days: 1 + + build: + name: Build + needs: [smoketest, changes] + if: | + always() && !cancelled() && !failure() + && (needs.changes.outputs.rust == 'true' || github.event_name == 'push') + runs-on: ${{ matrix.os }} + strategy: + matrix: + include: + - os: ubuntu-latest + target: aarch64-unknown-linux-gnu + - os: macos-latest + target: x86_64-apple-darwin + - os: macos-latest + target: aarch64-apple-darwin + - os: windows-latest + target: x86_64-pc-windows-msvc + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - name: Install Rust + uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable + with: + targets: ${{ matrix.target }} + + - name: Setup sccache + id: sccache + uses: mozilla-actions/sccache-action@2df7dbab909c49ab7d3382d05da469f3f975c2d6 # v0.0.7 + continue-on-error: true + + - name: Enable sccache + if: steps.sccache.outcome == 'success' + shell: bash + run: | + if sccache --start-server 2>/dev/null; then + echo "RUSTC_WRAPPER=sccache" >> "$GITHUB_ENV" + else + echo "::warning::sccache server failed to start, building without cache" + fi + + - name: Cache cargo + uses: Swatinem/rust-cache@ad397744b0d591a723ab90405b7247fac0e6b8db # v2 + with: + key: build-${{ matrix.target }} + cache-targets: "false" + + - name: Install cross-compilation tools + if: matrix.target == 'aarch64-unknown-linux-gnu' + run: | + sudo apt-get update + sudo apt-get install -y gcc-aarch64-linux-gnu + + - name: Disable Windows Defender scanning for cargo + if: runner.os == 'Windows' + run: | + Add-MpPreference -ExclusionPath "$env:USERPROFILE\.cargo" + Add-MpPreference -ExclusionPath "$env:USERPROFILE\.rustup" + Add-MpPreference -ExclusionPath "${{ github.workspace }}\target" + + - name: Build + run: cargo build --release --target ${{ matrix.target }} + env: + CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc + + smoketest: + name: API Smoketest + needs: build-linux + if: github.event.pull_request.head.repo.full_name == github.repository || github.event_name != 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - name: Download binary + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 + with: + name: gws-linux-x86_64 + path: ./bin + + - name: Make binary executable + run: chmod +x ./bin/gws + + - name: Decode credentials + env: + GOOGLE_CREDENTIALS_JSON: ${{ secrets.GOOGLE_CREDENTIALS_JSON }} + run: | + if [ -z "$GOOGLE_CREDENTIALS_JSON" ]; then + echo "::error::GOOGLE_CREDENTIALS_JSON secret is not set" + exit 1 + fi + echo "$GOOGLE_CREDENTIALS_JSON" | base64 -d > /tmp/credentials.json + + - name: Smoketest — help + run: ./bin/gws --help + + - name: Smoketest — schema introspection + run: ./bin/gws schema drive.files.list | jq -e '.httpMethod' + + - name: Smoketest — Drive files list + env: + GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /tmp/credentials.json + run: | + ./bin/gws drive files list \ + --params '{"pageSize": 1, "fields": "files(id,mimeType)"}' \ + | jq -e '.files' + + - name: Smoketest — Gmail messages + env: + GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /tmp/credentials.json + run: | + ./bin/gws gmail users messages list \ + --params '{"userId": "me", "maxResults": 1, "fields": "messages(id)"}' \ + | jq -e '.messages' + + - name: Smoketest — Calendar events + env: + GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /tmp/credentials.json + run: | + ./bin/gws calendar events list \ + --params '{"calendarId": "primary", "maxResults": 1, "fields": "kind,items(id,status)"}' \ + | jq -e '.kind' + + - name: Smoketest — Slides presentation + env: + GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /tmp/credentials.json + run: | + ./bin/gws slides presentations get \ + --params '{"presentationId": "1knOKD_87JWE4qsEbO4r5O91IxTER5ybBBhOJgZ1yLFI", "fields": "presentationId,slides(objectId)"}' \ + | jq -e '.presentationId' + + - name: Smoketest — pagination + env: + GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /tmp/credentials.json + run: | + LINES=$(./bin/gws drive files list \ + --params '{"pageSize": 1, "fields": "nextPageToken,files(id)"}' \ + --page-all --page-limit 2 \ + | wc -l) + if [ "$LINES" -lt 2 ]; then + echo "::error::Expected at least 2 NDJSON lines from pagination, got $LINES" + exit 1 + fi + + - name: Smoketest — error handling + run: | + if ./bin/gws fakeservice list 2>&1; then + echo "::error::Expected exit code 1 for unknown service" + exit 1 + fi + + - name: Cleanup credentials + if: always() + run: rm -f /tmp/credentials.json diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml new file mode 100644 index 0000000..c4a4809 --- /dev/null +++ b/.github/workflows/cla.yml @@ -0,0 +1,60 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: CLA + +on: + check_run: + types: [completed] + +permissions: + pull-requests: write + +jobs: + cla-label: + name: CLA Label + if: github.event.check_run.name == 'cla/google' + runs-on: ubuntu-latest + steps: + - name: Update CLA label + uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 + with: + github-token: ${{ secrets.GOOGLEWORKSPACE_BOT_TOKEN }} + script: | + const cr = context.payload.check_run; + const passed = cr.conclusion === 'success'; + + for (const pr of cr.pull_requests) { + const labels = passed + ? { add: 'cla: yes', remove: 'cla: no' } + : { add: 'cla: no', remove: 'cla: yes' }; + + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: pr.number, + labels: [labels.add], + }); + + try { + await github.rest.issues.removeLabel({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: pr.number, + name: labels.remove, + }); + } catch (e) { + // Label not present — ignore + } + } diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml new file mode 100644 index 0000000..4e1b323 --- /dev/null +++ b/.github/workflows/coverage.yml @@ -0,0 +1,54 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Coverage + +on: + push: + branches: [main] + paths: ['**/*.rs', 'Cargo.toml', 'Cargo.lock'] + pull_request: + branches: [main] + paths: ['**/*.rs', 'Cargo.toml', 'Cargo.lock'] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/main' }} + +jobs: + coverage: + name: Coverage + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - name: Install Rust + uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable + with: + components: llvm-tools-preview + + - name: Install cargo-llvm-cov + uses: taiki-e/install-action@a37010ded18ff788be4440302bd6830b1ae50d8b # cargo-llvm-cov + with: + tool: cargo-llvm-cov + + - name: Generate code coverage + run: cargo llvm-cov --all-features --workspace --lcov --output-path lcov.info + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4 + with: + files: lcov.info + fail_ci_if_error: false + token: ${{ secrets.CODECOV_TOKEN }} diff --git a/.github/workflows/generate-skills.yml b/.github/workflows/generate-skills.yml new file mode 100644 index 0000000..a30f1bc --- /dev/null +++ b/.github/workflows/generate-skills.yml @@ -0,0 +1,119 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Generate Skills + +on: + schedule: + - cron: "0 * * * *" # Hourly — keeps skills in sync with Discovery API changes + workflow_dispatch: # Manual trigger + push: + branches-ignore: + - main # main is kept up to date by PR merges + +concurrency: + group: generate-skills-${{ github.ref_name }} + cancel-in-progress: true + +env: + CARGO_TERM_COLOR: always + +jobs: + generate: + name: Generate and commit skills + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + with: + # For cron/dispatch: check out main. For push: check out the branch. + ref: ${{ github.head_ref || github.ref_name }} + token: ${{ secrets.GOOGLEWORKSPACE_BOT_TOKEN }} + + - name: Install Rust + uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable + + - name: Setup sccache + uses: mozilla-actions/sccache-action@2df7dbab909c49ab7d3382d05da469f3f975c2d6 # v0.0.7 + + - name: Cache cargo + uses: Swatinem/rust-cache@ad397744b0d591a723ab90405b7247fac0e6b8db # v2 + with: + key: generate-skills-ubuntu + + - name: Generate skills + run: cargo run -- generate-skills + + - name: Check for changes + id: diff + run: | + if git diff --quiet skills/ docs/skills.md; then + echo "changed=false" >> "$GITHUB_OUTPUT" + else + echo "changed=true" >> "$GITHUB_OUTPUT" + fi + + # --- Cron / workflow_dispatch: open a PR against main --- + - name: Create changeset for sync PR + if: >- + steps.diff.outputs.changed == 'true' && + (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') + run: | + mkdir -p .changeset + cat > .changeset/sync-skills.md << 'EOF' + --- + "@googleworkspace/cli": patch + --- + + Sync generated skills with latest Google Discovery API specs + EOF + + - name: Create or update sync PR + if: >- + steps.diff.outputs.changed == 'true' && + (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') + uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7 + with: + token: ${{ secrets.GOOGLEWORKSPACE_BOT_TOKEN }} + branch: chore/sync-skills + title: "chore: sync skills with Discovery API" + body: | + Automated PR — the Google Discovery API specs have changed and the + generated skill files are out of date. + + Created by the **Generate Skills** workflow (`generate-skills.yml`). + commit-message: "chore: regenerate skills from Discovery API" + add-paths: | + skills/ + docs/skills.md + .changeset/sync-skills.md + delete-branch: true + + # --- Push events (non-main branches): commit directly --- + - name: Commit and push if changed + if: >- + steps.diff.outputs.changed == 'true' && + github.event_name == 'push' + env: + GITHUB_TOKEN: ${{ secrets.GOOGLEWORKSPACE_BOT_TOKEN }} + run: | + git config user.name "googleworkspace-bot" + git config user.email "googleworkspace-bot@users.noreply.github.com" + + git add skills/ docs/skills.md + git commit -m "chore: regenerate skills [skip ci]" + git push diff --git a/.github/workflows/policy.yml b/.github/workflows/policy.yml new file mode 100644 index 0000000..271f711 --- /dev/null +++ b/.github/workflows/policy.yml @@ -0,0 +1,67 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Policy + +on: + push: + branches: [main] + pull_request: + branches: [main] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/main' }} + +jobs: + policy-check: + name: Policy Check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + with: + fetch-depth: 0 + - name: Enforce AGENTS.md rules + run: | + # Check CLI crate for prohibited google-* registry crates. + # Path dependencies (e.g. google-workspace = { path = ... }) are allowed. + if grep -E "^google-[a-zA-Z0-9_-]+[[:space:]]*=" crates/google-workspace-cli/Cargo.toml | grep -v 'path[[:space:]]*='; then + echo "::error file=crates/google-workspace-cli/Cargo.toml::Violates AGENTS.md: Adding generated google-* crates is prohibited. The CLI uses dynamic schema discovery at runtime." + exit 1 + fi + echo "Policy check passed." + - name: Enforce Changeset File + if: github.event_name == 'pull_request' + run: | + git fetch origin ${{ github.base_ref }} + # Skip changeset requirement if no Rust/Cargo files changed + if ! git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -qE '\.(rs)$|^Cargo\.(toml|lock)$'; then + echo "No Rust/Cargo files changed; skipping changeset requirement." + exit 0 + fi + if ! git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -q "^.changeset/.*\.md$"; then + echo "::error::A Changeset file is required! Please run 'npx changeset' or manually create a markdown file in the .changeset directory describing your changes to automatically version and release this PR." + exit 1 + fi + echo "Changeset file found!" + - name: Validate Changeset Package Name + if: github.event_name == 'pull_request' + run: | + for f in $(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep "^.changeset/.*\.md$"); do + if grep -q '"googleworkspace-cli"' "$f"; then + echo "::error file=$f::Wrong package name. Use '\"@googleworkspace/cli\"' not '\"googleworkspace-cli\"'." + exit 1 + fi + done + echo "Changeset package names valid!" diff --git a/.github/workflows/publish-skills.yml b/.github/workflows/publish-skills.yml new file mode 100644 index 0000000..3521438 --- /dev/null +++ b/.github/workflows/publish-skills.yml @@ -0,0 +1,55 @@ +name: Publish OpenClaw Skills + +on: + push: + branches: [main] + paths: + - "skills/**" + - ".github/workflows/publish-skills.yml" + pull_request: + branches: [main] + paths: + - "skills/**" + - ".github/workflows/publish-skills.yml" + schedule: + - cron: "0 * * * *" # Hourly, to drip-publish past rate limits + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }} + cancel-in-progress: false + +jobs: + publish: + # Skip fork PRs — secrets (CLAWHUB_TOKEN) are not available + if: github.event.pull_request.head.repo.full_name == github.repository || github.event_name != 'pull_request' + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + with: + node-version: "20" + + - name: Install ClawHub CLI + run: npm i -g clawhub@0.7.0 + + - name: Authenticate ClawHub + env: + CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }} + run: | + if [ -z "$CLAWHUB_TOKEN" ]; then + echo "::error::CLAWHUB_TOKEN secret is not set" + exit 1 + fi + clawhub login --token "$CLAWHUB_TOKEN" + + - name: Publish skills + run: | + if [ "${{ github.event_name }}" = "pull_request" ]; then + clawhub sync --root skills --all --dry-run + else + clawhub sync --root skills --all + fi diff --git a/.github/workflows/release-changesets.yml b/.github/workflows/release-changesets.yml new file mode 100644 index 0000000..25caa4f --- /dev/null +++ b/.github/workflows/release-changesets.yml @@ -0,0 +1,72 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Release (Changeset) + +on: + workflow_dispatch: + push: + branches: + - main + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: false + +jobs: + release: + name: Release + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + with: + token: ${{ secrets.GOOGLEWORKSPACE_BOT_TOKEN }} + + - name: Install Rust + uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable + + - name: Install Nix + uses: cachix/install-nix-action@08dcb3a5e62fa31e2da3d490afc4176ef55ecd72 # v30 + with: + github_access_token: ${{ secrets.GOOGLEWORKSPACE_BOT_TOKEN }} + + - uses: pnpm/action-setup@c5ba7f7862a0f64c1b1a05fbac13e0b8e86ba08c # v4 + + - name: Setup Node.js + uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + with: + node-version: '22' + cache: 'pnpm' + + - name: Install Dependencies + run: pnpm install + + - run: | + git config --global user.name "googleworkspace-bot" + git config --global user.email "googleworkspace-bot@google.com" + + - name: Create Release Pull Request or Tag + id: changesets + uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf # v1 + with: + version: pnpm run version-sync + publish: pnpm run tag-release + commit: 'chore: release versions' + title: 'chore: release versions' + setupGitUser: false + env: + GITHUB_TOKEN: ${{ secrets.GOOGLEWORKSPACE_BOT_TOKEN }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..6de7cbc --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,227 @@ +# Release workflow for @googleworkspace/cli +# +# Triggered by pushing a semver tag (e.g. v0.22.3). +# Builds platform binaries, creates a GitHub Release, publishes to npm and crates.io. + +name: Release +permissions: + contents: write + attestations: write + id-token: write + +on: + pull_request: + push: + tags: + - 'v[0-9]+.[0-9]+.[0-9]+*' + +env: + CARGO_TERM_COLOR: always + +jobs: + plan: + runs-on: ubuntu-latest + outputs: + version: ${{ steps.meta.outputs.version }} + prerelease: ${{ steps.meta.outputs.prerelease }} + publishing: ${{ github.ref_type == 'tag' }} + steps: + - id: meta + run: | + TAG="${GITHUB_REF_NAME}" + VERSION="${TAG#v}" + echo "version=${VERSION}" >> "$GITHUB_OUTPUT" + if [[ "$VERSION" == *-* ]]; then + echo "prerelease=true" >> "$GITHUB_OUTPUT" + else + echo "prerelease=false" >> "$GITHUB_OUTPUT" + fi + + build: + needs: plan + strategy: + fail-fast: false + matrix: + include: + - target: aarch64-apple-darwin + runner: macos-latest + archive: tar.gz + - target: x86_64-apple-darwin + runner: macos-latest + archive: tar.gz + - target: aarch64-unknown-linux-gnu + runner: ubuntu-latest + archive: tar.gz + cross: true + - target: aarch64-unknown-linux-musl + runner: ubuntu-latest + archive: tar.gz + cross: true + - target: x86_64-unknown-linux-gnu + runner: ubuntu-latest + archive: tar.gz + - target: x86_64-unknown-linux-musl + runner: ubuntu-latest + archive: tar.gz + cross: true + - target: x86_64-pc-windows-msvc + runner: windows-latest + archive: zip + runs-on: ${{ matrix.runner }} + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable + with: + targets: ${{ matrix.target }} + + - name: Install cross + if: matrix.cross + run: cargo install cross --git https://github.com/cross-rs/cross --tag v0.2.5 + + - name: Build + run: | + if [ "${{ matrix.cross }}" = "true" ]; then + cross build --release --target ${{ matrix.target }} --locked + else + cargo build --release --target ${{ matrix.target }} --locked + fi + shell: bash + + - name: Package (unix) + if: matrix.archive == 'tar.gz' + run: | + ARTIFACT="google-workspace-cli-${{ matrix.target }}" + mkdir -p staging + cp "target/${{ matrix.target }}/release/gws" staging/ + cp LICENSE README.md CHANGELOG.md staging/ + tar czf "${ARTIFACT}.tar.gz" -C staging . + shasum -a 256 "${ARTIFACT}.tar.gz" > "${ARTIFACT}.tar.gz.sha256" + shell: bash + + - name: Package (windows) + if: matrix.archive == 'zip' + run: | + $ARTIFACT = "google-workspace-cli-${{ matrix.target }}" + New-Item -ItemType Directory -Path $ARTIFACT + Copy-Item "target/${{ matrix.target }}/release/gws.exe" "$ARTIFACT/" + Copy-Item LICENSE, README.md, CHANGELOG.md "$ARTIFACT/" + Compress-Archive -Path "$ARTIFACT/*" -DestinationPath "$ARTIFACT.zip" + (Get-FileHash "$ARTIFACT.zip" -Algorithm SHA256).Hash.ToLower() + " $ARTIFACT.zip" | Out-File -Encoding ascii "$ARTIFACT.zip.sha256" + shell: pwsh + + - name: Attest + if: github.ref_type == 'tag' + uses: actions/attest-build-provenance@43d14bc2b83dec42d39ecae14e916627a18bb661 # v3 + with: + subject-path: google-workspace-cli-${{ matrix.target }}.${{ matrix.archive }} + + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + with: + name: binary-${{ matrix.target }} + path: | + google-workspace-cli-${{ matrix.target }}.${{ matrix.archive }} + google-workspace-cli-${{ matrix.target }}.${{ matrix.archive }}.sha256 + + release: + needs: [plan, build] + if: github.ref_type == 'tag' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 + with: + pattern: binary-* + path: artifacts/ + merge-multiple: true + + - name: Create GitHub Release + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + PRERELEASE_FLAG="" + if [ "${{ needs.plan.outputs.prerelease }}" = "true" ]; then + PRERELEASE_FLAG="--prerelease" + fi + + NOTES="## Installation + + Download the archive for your OS and architecture from the assets below. + + ### Linux / macOS + + Replace \`\` with your platform (e.g., \`aarch64-apple-darwin\` or \`x86_64-unknown-linux-gnu\`). + + \`\`\`bash + # 1. Download the archive and its checksum + curl -sLO https://github.com/googleworkspace/cli/releases/download/${{ github.ref_name }}/google-workspace-cli-.tar.gz + curl -sLO https://github.com/googleworkspace/cli/releases/download/${{ github.ref_name }}/google-workspace-cli-.tar.gz.sha256 + + # 2. Verify the checksum + shasum -a 256 -c google-workspace-cli-.tar.gz.sha256 + + # 3. Extract and install + tar -xzf google-workspace-cli-.tar.gz + chmod +x gws + sudo mv gws /usr/local/bin/ + \`\`\` + + ### Windows + + 1. Download \`google-workspace-cli-x86_64-pc-windows-msvc.zip\` and its \`.sha256\` file + 2. Verify the checksum (e.g., using PowerShell \`Get-FileHash\`) + 3. Extract the archive and move \`gws.exe\` to a directory included in your system \`PATH\`. + + --- + " + + gh release create "${{ github.ref_name }}" \ + --target "${{ github.sha }}" \ + --title "${{ github.ref_name }}" \ + --notes "$NOTES" \ + --generate-notes \ + $PRERELEASE_FLAG \ + artifacts/* + + publish-npm: + needs: [plan, release] + runs-on: ubuntu-latest + if: ${{ needs.plan.outputs.publishing == 'true' && needs.plan.outputs.prerelease == 'false' }} + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6 + with: + node-version: '20.x' + registry-url: 'https://wombat-dressing-room.appspot.com' + + - name: Publish to npm + working-directory: npm + run: npm publish --access public + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + + publish-cargo: + needs: [plan, release] + runs-on: ubuntu-latest + if: ${{ needs.plan.outputs.publishing == 'true' && needs.plan.outputs.prerelease == 'false' }} + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable + + # Publish library crate first (CLI depends on it) + - name: Publish google-workspace + run: cargo publish --package google-workspace + env: + CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }} + + # Wait for crates.io to index the library crate + - name: Wait for crates.io index + run: sleep 30 + + - name: Publish google-workspace-cli + run: cargo publish --package google-workspace-cli + env: + CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }} diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml new file mode 100644 index 0000000..18c0b9f --- /dev/null +++ b/.github/workflows/stale.yml @@ -0,0 +1,36 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: 'Close Stale PRs' +on: + schedule: + - cron: '30 1 * * *' + workflow_dispatch: + +permissions: + pull-requests: write + +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9 + with: + days-before-issue-stale: -1 + days-before-issue-close: -1 + days-before-pr-stale: 3 + days-before-pr-close: 0 + stale-pr-message: 'This PR has been inactive for 72 hours. Closing to keep the queue clean.' + close-pr-message: 'This PR was closed because it has been stalled for 72 hours. Feel free to magically reopen it if you want to continue working on it!' + exempt-pr-labels: 'keep-alive' diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..668f55f --- /dev/null +++ b/.gitignore @@ -0,0 +1,50 @@ +# Rust +/target/ +**/*.rs.bk +bin/ +lcov.info + + +.emails/ + +# Node +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* +.npm + +# Build outputs +/dist/ +*.tsbuildinfo +/bin/gws-native* + +# IDE +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db + +# Environment +.env +.env.local +.env.*.local + +# Test artifacts +*.log +coverage/ +.nyc_output/ +download.txt +files.jsonl + +# Plans (local design docs) +docs/plans/ + +# Generated +demo.mp4 +download.html \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7221122 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,239 @@ +# AGENTS.md + +## Project Overview + +`gws` is a Rust CLI tool for interacting with Google Workspace APIs. It dynamically generates its command surface at runtime by parsing Google Discovery Service JSON documents. + +> [!IMPORTANT] +> **Dynamic Discovery**: This project does NOT use generated Rust crates (e.g., `google-drive3`) for API interaction. Instead, it fetches the Discovery JSON at runtime and builds `clap` commands dynamically. When adding a new service, you only need to register it in `crates/google-workspace/src/services.rs` and verify the Discovery URL pattern in `crates/google-workspace/src/discovery.rs`. Do NOT add new crates to `Cargo.toml` for standard Google APIs. + +> [!NOTE] +> **Package Manager**: Use `pnpm` instead of `npm` for Node.js package management in this repository. + +## Build & Test + +> [!IMPORTANT] +> **Test Coverage**: The `codecov/patch` check requires that new or modified lines are covered by tests. When adding code, extract testable helper functions rather than embedding logic in `main`/`run` where it's hard to unit-test. Run `cargo test` locally and verify new branches are exercised. + +```bash +cargo build # Build in dev mode +cargo clippy -- -D warnings # Lint check +cargo test # Run tests +``` + +## Changesets + +Every PR must include a changeset file. Create one at `.changeset/.md`: + +```markdown +--- +"@googleworkspace/cli": patch +--- + +Brief description of the change +``` + +Use `patch` for fixes/chores, `minor` for new features, `major` for breaking changes. The CI policy check will fail without a changeset. + +## Architecture + +The CLI uses a **two-phase argument parsing** strategy: + +1. Parse argv to extract the service name (e.g., `drive`) +2. Fetch the service's Discovery Document, build a dynamic `clap::Command` tree, then re-parse + +### Workspace Layout + +The repository is a Cargo workspace with two crates: + +| Crate | Package | Purpose | +| ------------------------------ | ----------------------- | ------------------------------------------------- | +| `crates/google-workspace/` | `google-workspace` | Publishable library — core types and helpers | +| `crates/google-workspace-cli/` | `google-workspace-cli` | Binary crate — the `gws` CLI | + +#### Library (`crates/google-workspace/src/`) + +| File | Purpose | +| ---------------- | ---------------------------------------------------------- | +| `discovery.rs` | Serde models for Discovery Document + async fetch/cache | +| `services.rs` | Service alias → Discovery API name/version mapping | +| `error.rs` | `GwsError` enum, exit codes, JSON serialization | +| `validate.rs` | Path/URL/resource validators, `encode_path_segment()` | +| `client.rs` | HTTP client with retry logic | + +#### CLI (`crates/google-workspace-cli/src/`) + +| File | Purpose | +| ------------------- | ------------------------------------------------------------------------ | +| `main.rs` | Entrypoint, two-phase CLI parsing, method resolution | +| `auth.rs` | OAuth2 token acquisition via env vars, encrypted credentials, or ADC | +| `credential_store.rs` | AES-256-GCM encryption/decryption of credential files | +| `auth_commands.rs` | `gws auth` subcommands: `login`, `logout`, `setup`, `status`, `export` | +| `commands.rs` | Recursive `clap::Command` builder from Discovery resources | +| `executor.rs` | HTTP request construction, response handling, schema validation | +| `schema.rs` | `gws schema` command — introspect API method schemas | +| `logging.rs` | Opt-in structured logging (stderr + file) via `tracing` | +| `timezone.rs` | Account timezone resolution: `--timezone` flag, Calendar Settings API | + +## Demo Videos + +Demo recordings are generated with [VHS](https://github.com/charmbracelet/vhs) (`.tape` files). + +```bash +vhs docs/demo.tape +``` + +### VHS quoting rules + +- Use **double quotes** for simple strings: `Type "gws --help" Enter` +- Use **backtick quotes** when the typed text contains JSON with double quotes: + ``` + Type `gws drive files list --params '{"pageSize":5}'` Enter + ``` + `\"` escapes inside double-quoted `Type` strings are **not supported** by VHS and will cause parse errors. + +### Scene art + +ASCII art title cards live in `art/`. The `scripts/show-art.sh` helper clears the screen and cats the file. Portrait scenes use `scene*.txt`; landscape chapters use `long-*.txt`. + +## Input Validation & URL Safety + +> [!IMPORTANT] +> This CLI is frequently invoked by AI/LLM agents. Always assume inputs can be adversarial — validate paths against traversal (`../../.ssh`), restrict format strings to allowlists, reject control characters, and encode user values before embedding them in URLs. + +> [!NOTE] +> **Environment variables are trusted inputs.** The validation rules above apply to **CLI arguments** that may be passed by untrusted AI agents. Environment variables (e.g. `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`) are set by the user themselves — in their shell profile, `.env` file, or deployment config — and are not subject to path traversal validation. This is consistent with standard conventions like `XDG_CONFIG_HOME`, `CARGO_HOME`, etc. + +### Path Safety (`crates/google-workspace/src/validate.rs`) + +When adding new helpers or CLI flags that accept file paths, **always validate** using the shared helpers: + +| Scenario | Validator | Rejects | +| -------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------- | +| File path for writing (`--output-dir`) | `validate::validate_safe_output_dir()` | Absolute paths, `../` traversal, symlinks outside CWD, control chars | +| File path for reading (`--dir`) | `validate::validate_safe_dir_path()` | Absolute paths, `../` traversal, symlinks outside CWD, control chars | +| Enum/allowlist values (`--msg-format`) | clap `value_parser` (see `gmail/mod.rs`) | Any value not in the allowlist | + +```rust +// In your argument parser: +if let Some(output_dir) = matches.get_one::("output-dir") { + crate::validate::validate_safe_output_dir(output_dir)?; + builder.output_dir(Some(output_dir.clone())); +} +``` + +### URL Encoding (`crates/google-workspace-cli/src/helpers/mod.rs`) + +User-supplied values embedded in URL **path segments** must be percent-encoded. Use the shared helper: + +```rust +// CORRECT — encodes slashes, spaces, and special characters +let url = format!( + "https://www.googleapis.com/drive/v3/files/{}", + crate::helpers::encode_path_segment(file_id), +); + +// WRONG — raw user input in URL path +let url = format!("https://www.googleapis.com/drive/v3/files/{}", file_id); +``` + +For **query parameters**, use reqwest's `.query()` builder which handles encoding automatically: + +```rust +// CORRECT — reqwest encodes query values +client.get(url).query(&[("q", user_query)]).send().await?; + +// WRONG — manual string interpolation in query strings +let url = format!("{}?q={}", base_url, user_query); +``` + +### Resource Name Validation (`crates/google-workspace-cli/src/helpers/mod.rs`) + +When a user-supplied string is used as a GCP resource identifier (project ID, topic name, space name, etc.) that gets embedded in a URL path, validate it first: + +```rust +// Validates the string does not contain path traversal segments (`..`), control characters, or URL-breaking characters like `?` and `#`. +let project = crate::validate::validate_resource_name(&project_id)?; +let url = format!("https://pubsub.googleapis.com/v1/projects/{}/topics/my-topic", project); +``` + +This prevents injection of query parameters, path traversal, or other malicious payloads through resource name arguments like `--project` or `--space`. + +### Checklist for New Features + +When adding a new helper or CLI command: + +1. **File paths** → Use `validate_safe_output_dir` / `validate_safe_dir_path` +2. **Enum flags** → Constrain via clap `value_parser` or `validate_msg_format` +3. **URL path segments** → Use `encode_path_segment()` +4. **Query parameters** → Use reqwest `.query()` builder +5. **Resource names** (project IDs, space names, topic names) → Use `validate_resource_name()` +6. **Write tests** for both the happy path AND the rejection path (e.g., pass `../../.ssh` and assert `Err`) + +## PR Labels + +Use these labels to categorize pull requests and issues: + +- `area: discovery` — Discovery document fetching, caching, parsing +- `area: http` — Request execution, URL building, response handling +- `area: docs` — README, contributing guides, documentation +- `area: tui` — Setup wizard, picker, input fields +- `area: distribution` — Nix flake, npm packaging, GitHub Actions release workflow, install methods +- `area: auth` — OAuth, credentials, multi-account, ADC +- `area: skills` — AI skill generation and management + +## Helper Commands (`+verb`) + +Helpers are handwritten commands prefixed with `+` that provide value the schema-driven Discovery commands cannot: multi-step orchestration, format translation (e.g., Markdown → Docs JSON), or multi-API composition. + +> [!IMPORTANT] +> **Do NOT add a helper that** wraps a single API call already available via Discovery, adds flags to expose data already in the API response, or re-implements Discovery parameters as custom flags. Helper flags must control orchestration logic — use `--params` and `--format`/`jq` for API parameters and output filtering. + +See [`src/helpers/README.md`](crates/google-workspace-cli/src/helpers/README.md) for full guidelines, anti-patterns, and a checklist for new helpers. + +## Environment Variables + +### Authentication + +| Variable | Description | +|---|---| +| `GOOGLE_WORKSPACE_CLI_TOKEN` | Pre-obtained OAuth2 access token (highest priority; bypasses all credential file loading) | +| `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | Path to OAuth credentials JSON (no default; if unset, falls back to encrypted credentials in `~/.config/gws/`) | +| `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND` | Keyring backend: `keyring` (default, uses OS keyring with file fallback) or `file` (file only, for Docker/CI/headless) | + +| `GOOGLE_APPLICATION_CREDENTIALS` | Standard Google ADC path; used as fallback when no gws-specific credentials are configured | + +### Configuration + +| Variable | Description | +|---|---| +| `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` | Override the config directory (default: `~/.config/gws`) | + +### OAuth Client + +| Variable | Description | +|---|---| +| `GOOGLE_WORKSPACE_CLI_CLIENT_ID` | OAuth client ID (for `gws auth login` when no `client_secret.json` is saved) | +| `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET` | OAuth client secret (paired with `CLIENT_ID` above) | + +### Sanitization (Model Armor) + +| Variable | Description | +|---|---| +| `GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE` | Default Model Armor template (overridden by `--sanitize` flag) | +| `GOOGLE_WORKSPACE_CLI_SANITIZE_MODE` | `warn` (default) or `block` | + +### Helpers + +| Variable | Description | +|---|---| +| `GOOGLE_WORKSPACE_PROJECT_ID` | GCP project ID override for quota/billing and fallback for helper commands (overridden by `--project` flag) | + +### Logging + +| Variable | Description | +|---|---| +| `GOOGLE_WORKSPACE_CLI_LOG` | Log level filter for stderr output (e.g., `gws=debug`). Off by default. | +| `GOOGLE_WORKSPACE_CLI_LOG_FILE` | Directory for JSON-line log files with daily rotation. Off by default. | + +All variables can also live in a `.env` file (loaded via `dotenvy`). diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..f332f4e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,861 @@ +# @googleworkspace/cli + +## 0.22.5 + +### Patch Changes + +- 5d24ac2: Add cargo-audit CI workflow for automated dependency vulnerability scanning +- ecddf2e: Add cargo-deny configuration for license, advisory, and source auditing +- 503315b: Update installation instructions to prioritize GitHub Releases over npm +- 6ccbb42: fix: auto-install binary on run if missing + + pnpm skips postinstall when the package is already up to date. + This ensures run.js will auto-trigger install.js if the + binary is missing, fixing the 'gws binary not found' error. + +- b307856: Migrated the internal AI skills registry (personas and recipes) from YAML to TOML. This allows us to drop the unmaintained serde_yaml dependency, improving the project's supply chain security posture. +- 158f93a: Verify SHA256 checksum of downloaded binary in npm postinstall script +- b422e5d: Pin cross-rs to v0.2.5 in release workflow to prevent unpinned git HEAD builds + +## 0.22.4 + +### Patch Changes + +- 86c08cf: Remove cargo-dist; use native Node.js fetch for npm binary installer + + Replaces the cargo-dist generated release pipeline and npm package with: + + - A custom GitHub Actions release workflow with matrix cross-compilation + - A zero-dependency npm installer using native `fetch()` (Node 18+) + - Removes axios, rimraf, detect-libc, console.table, and axios-proxy-builder dependencies from the published npm package + +## 0.22.3 + +### Patch Changes + +- 674d53a: Fix `Lint Skills` CI job by installing `uv` via `astral-sh/setup-uv` before running `uvx` +- c7c42f6: fix: register script service and resolve test path validation errors +- 80bd150: feat(auth): use strict OS keychain integration on macOS and Windows + + Closes #623. The CLI no longer writes a fallback `.encryption_key` text file on macOS and Windows when securely storing credentials. Instead, it strictly uses the native OS keychain (Keychain Access on macOS, Credential Manager on Windows). If an old `.encryption_key` file is found during a successful keychain login, it will be automatically deleted for security. + Linux deployments continue to use a seamless file-based fallback by default to ensure maximum compatibility with headless continuous integration (CI) runners, Docker containers, and SSH environments without desktop DBUS services. + +- ec7f56b: Sync generated skills with latest Google Discovery API specs + +## 0.22.2 + +### Patch Changes + +- a52d297: Improve proxy-aware OAuth flows and clean up review feedback for auth login. + +## 0.22.1 + +### Patch Changes + +- 6a45832: Sync generated skills with latest Google Discovery API specs + +## 0.22.0 + +### Minor Changes + +- 0850c48: Add `--draft` flag to Gmail `+send`, `+reply`, `+reply-all`, and `+forward` helpers to save messages as drafts instead of sending them immediately + +## 0.21.2 + +### Patch Changes + +- c4448b9: Add crates.io publishing to release workflow + + Publishes both `google-workspace` and `google-workspace-cli` to crates.io on each release. The library crate is published first (as a dependency), followed by the CLI crate. + +## 0.21.1 + +### Patch Changes + +- ea0849a: Fix version-sync script and bump CLI crate version to 0.21.0 + + The `version-sync.sh` script was updating the root `Cargo.toml` which no longer has a `[package]` section after the workspace refactor. Updated to target `crates/google-workspace-cli/Cargo.toml`. Also syncs the CLI crate version to 0.21.0 to match `package.json`. + +## 0.21.0 + +### Minor Changes + +- 029e5de: Extract `google-workspace` library crate for programmatic Rust API access (closes #386) + + Introduces a Cargo workspace with a new `google-workspace` library crate (`crates/google-workspace/`) + that exposes the core modules for use as a Rust dependency: + + - `discovery` — Discovery Document types and fetching + - `error` — Structured `GwsError` type + - `services` — Service registry and resolution + - `validate` — Input validation and URL encoding + - `client` — HTTP client with retry logic + + The `gws` binary crate re-exports all library types transparently — zero behavioral changes. + +## 0.20.1 + +### Patch Changes + +- b8fd3d9: fix(client): add 10s connect timeout to prevent hangs on initial connection +- 2bfcca9: Move version from top-level SKILL.md frontmatter to metadata and track CLI version +- 2ddb46e: test(gmail): add regression tests for RFC 2822 display name quoting +- 75a7121: Sync generated skills with latest Google Discovery API specs + +## 0.20.0 + +### Minor Changes + +- e782dd7: Forward original attachments by default and preserve inline images in HTML mode. + + `+forward` now includes the original message's attachments and inline images by default, + matching Gmail web behavior. Use `--no-original-attachments` to opt out. + `+reply`/`+reply-all` with `--html` preserve inline images in the quoted body via + `multipart/related`. In plain-text mode, inline images are not included (matching Gmail web). + +## 0.19.0 + +### Minor Changes + +- a078945: Refactor all `gws auth` subcommands to use clap for argument parsing + + Replace manual argument parsing in `handle_auth_command`, `handle_login`, `resolve_scopes`, and `handle_export` with structured `clap::Command` definitions. Introduces `ScopeMode` enum for type-safe scope selection and adds proper `--help` support for all auth subcommands. + +### Patch Changes + +- 8a749c2: feat(helpers): add --dry-run support to events helper commands + + Add dry-run mode to `gws events +renew` and `gws events +subscribe` commands. + When --dry-run is specified, the commands will print what actions would be + taken without making any API calls. This allows agents to simulate requests + and learn without reaching the server. + +- d679401: Fix `mask_secret` panic on multi-byte UTF-8 secrets by using char-based indexing instead of byte-offset slicing +- d341de2: Handle --help/-h in `gws auth setup` before launching the setup wizard, preventing accidental project creation when users just want usage info +- f157208: fix: use block-style YAML sequences in generated SKILL.md frontmatter + + Replace flow sequences (`bins: ["gws"]`, `skills: [...]`) with block-style + sequences (`bins:\n - gws`) in all generated SKILL.md frontmatter templates. + + Flow sequences are valid YAML but rejected by `strictyaml`, which the + Agent Skills reference implementation (`agentskills validate`) uses to parse + frontmatter. This caused all 93 generated skills to fail validation. + + Fixes #521 + +- b4d5e26: Fix auth error propagation: properly propagate errors when token directory creation or permission setting fails, instead of silently ignoring them + +## 0.18.1 + +### Patch Changes + +- a87037b: Handle SIGTERM in `gws gmail +watch` and `gws events +subscribe` for clean container shutdown. + + Long-running pull loops now exit gracefully on SIGTERM (in addition to Ctrl+C), + enabling clean shutdown under Kubernetes, Docker, and systemd. + +## 0.18.0 + +### Minor Changes + +- 908cf73: feat(gmail): auto-populate From header with display name from send-as settings + + Fetch the user's send-as identities to set the From header with a display name in all mail helpers (+send, +reply, +reply-all, +forward), matching Gmail web client behavior. Also enriches bare `--from` emails with their configured display name. + +- 6e4daaf: Gmail helpers rollup: mail-builder migration, --attach flag (upload endpoint), +read helper + + - Migrate `+send`, `+reply`, `+reply-all`, and `+forward` to the `mail-builder` crate for RFC-compliant MIME construction + - Add `--from` flag to `+send` for send-as alias support + - Add `-a`/`--attach` flag to all mail helpers (`+send`, `+reply`, `+reply-all`, `+forward`) with `mime_guess2` auto-detection, 25MB size validation, and upload endpoint support (35MB API limit vs 5MB metadata-only) + - Add `+read` helper to extract message body and headers (text, HTML, or JSON output) + - Make `OriginalMessage.thread_id` optional (`Option`) for draft compatibility + - RFC 2822 display name quoting is handled natively by `mail-builder` + - Introduce `UploadSource` enum in executor for type-safe upload strategies + +### Patch Changes + +- 1e90380: fix(gmail): remove dead `--attachment` arg from `+send` + + The `+send` subcommand defined a duplicate `"attachment"` arg alongside the + `"attach"` arg already provided by `common_mail_args`. Since `parse_attachments` + reads `"attach"`, the `--attachment` flag was silently ignored. Removed the + dead duplicate. + +- 908cf73: fix(gmail): handle reply-all to own message correctly + + Reply-all to a message you sent no longer errors with "No To recipient remains." The original To recipients are now used as reply targets, matching Gmail web client behavior. + +- 2e909ae: Consolidate terminal sanitization, coloring, and output helpers into a new `output.rs` module. Fixes raw ANSI escape codes in `watch.rs` that bypassed `NO_COLOR` and TTY detection, upgrades `sanitize_for_terminal` to also strip dangerous Unicode characters (bidi overrides, zero-width spaces, directional isolates), and sanitizes previously raw API error body and user query outputs. + +## 0.17.0 + +### Minor Changes + +- 1b0a21f: feat: support google meet video conferencing in calendar +insert + +### Patch Changes + +- 811fe7b: Fix critical security vulnerability (TOCTOU/Symlink race) in atomic file writes. + + The atomic_write and atomic_write_async utilities now use: + + - Randomized temporary filenames to prevent predictability. + - O_EXCL creation flags to prevent following pre-existing symlinks. + - Strict 0600 permissions from the moment of file creation on Unix systems. + - Redundant post-write permission calls have been removed to close race windows. + +- b241a5b: fix(security): cap Retry-After sleep, sanitize upload mimeType, and validate --upload/--output paths +- 6f92e5b: Stderr/output hygiene rollup: route diagnostics to stderr, add colored error labels, propagate auth errors. + + - **triage.rs**: "No messages found" sent to stderr so stdout stays valid JSON for pipes + - **modelarmor.rs**: response body printed only on success; error message now includes body for diagnostics + - **error.rs**: colored `error[variant]:` labels on stderr (respects `NO_COLOR` env var), `hint:` prefix for accessNotConfigured guidance + - **calendar, chat, docs, drive, script, sheets**: auth failures now propagate as `GwsError::Auth` instead of silently proceeding unauthenticated (dry-run still works without auth) + +- 398e80c: Sync generated skills with latest Google Discovery API specs +- 8458104: Extend input validation to reject dangerous Unicode characters (zero-width chars, bidi overrides, Unicode line/paragraph separators) that were not caught by the previous ASCII-range check + +## 0.16.0 + +### Minor Changes + +- 47afe5f: Use Google account timezone instead of machine-local time for day-boundary calculations in calendar and workflow helpers. Adds `--timezone` flag to `+agenda` for explicit override. Timezone is fetched from Calendar Settings API and cached for 24 hours. + +### Patch Changes + +- c61b9cb: fix(gmail): RFC 2047 encode non-ASCII display names in To/From/Cc/Bcc headers + + Fixes mojibake when sending emails to recipients with non-ASCII display names (e.g. Japanese, Spanish accented characters). The new `encode_address_header()` function parses mailbox lists, encodes only the display-name portion via RFC 2047 Base64, and leaves email addresses untouched. + +## 0.15.0 + +### Minor Changes + +- 6f3e090: Add opt-in structured HTTP request logging via `tracing` + + New environment variables: + + - `GOOGLE_WORKSPACE_CLI_LOG`: stderr log filter (e.g., `gws=debug`) + - `GOOGLE_WORKSPACE_CLI_LOG_FILE`: directory for JSON log files with daily rotation + + Logging is completely silent by default (zero overhead). Only PII-free metadata is logged: API method ID, HTTP method, status code, latency, and content-type. + +## 0.14.0 + +### Minor Changes + +- dc561e0: Add `--upload-content-type` flag and smart MIME inference for multipart uploads + + Previously, multipart uploads used the metadata `mimeType` field for both the Drive + metadata and the media part's `Content-Type` header. This made it impossible to upload + a file in one format (e.g. Markdown) and have Drive convert it to another (e.g. Google Docs), + because the media `Content-Type` and the target `mimeType` must differ for import conversions. + + The new `--upload-content-type` flag allows setting the media `Content-Type` explicitly. + When omitted, the media type is now inferred from the file extension before falling back + to the metadata `mimeType`. This matches Google Drive's model where metadata `mimeType` + is the _target_ type (what the file should become) while the media `Content-Type` is the + _source_ type (what the bytes are). + + This means import conversions now work automatically: + + ```bash + # Extension inference detects text/markdown → conversion just works + gws drive files create \ + --json '{"name":"My Doc","mimeType":"application/vnd.google-apps.document"}' \ + --upload notes.md + + # Explicit flag still available as an override + gws drive files create \ + --json '{"name":"My Doc","mimeType":"application/vnd.google-apps.document"}' \ + --upload notes.md \ + --upload-content-type text/markdown + ``` + +### Patch Changes + +- 945ac91: Stream multipart uploads to avoid OOM on large files. File content is now streamed in chunks via `ReaderStream` instead of being read entirely into memory, reducing memory usage from O(file_size) to O(64 KB). + +## 0.13.3 + +### Patch Changes + +- 8ef27a2: fix(calendar): use local timezone for agenda day boundaries instead of UTC +- 4d7b420: Fix `+append --json-values` flattening multi-row arrays into a single row by preserving the `Vec>` row structure through to the API request body +- bb94016: fix(security): validate space name in chat +send to prevent path traversal +- 4b827cd: chore: fix maintainer email typo in flake.nix and harden coverage.sh +- 44767ed: Map People service to `contacts` and `directory` scope prefixes so `gws auth login -s people` includes the required OAuth scopes +- 8fce003: fix(docs): correct flag names in recipes (--spreadsheet-id, --attendees, --duration) +- 21b1840: Expose `repeated: true` in `gws schema` output and expand JSON arrays into repeated query parameters for `repeated` fields +- 1346d47: Sync generated skills with latest Google Discovery API specs +- 957b999: test(gmail): add unit tests for +triage argument parsing and format selection + +## 0.13.2 + +### Patch Changes + +- 3dcf818: Refresh OAuth access tokens for long-running Gmail watch and Workspace Events subscribe helpers before each Pub/Sub and Gmail request. +- 86ea6de: Validate `--subscription` resource name in `gmail +watch` and deduplicate `PUBSUB_API_BASE` constant. + +## 0.13.1 + +### Patch Changes + +- 510024f: Centralize token cache filenames as constants and support ServiceAccount credentials at the default plaintext path +- 510024f: Auto-recover from stale encrypted credentials after upgrade: remove undecryptable `credentials.enc` and fall through to other credential sources (plaintext, ADC) instead of hard-erroring. Also sync encryption key file backup when keyring has key but file is missing. +- e104106: Add shell tips section to gws-shared skill warning about zsh `!` history expansion, and replace single quotes with double quotes around sheet ranges containing `!` in recipes and skill examples + +## 0.13.0 + +### Minor Changes + +- 9d937af: Add `--html` flag to `+send`, `+reply`, `+reply-all`, and `+forward` for HTML email composition. + +### Patch Changes + +- 2df32ee: Document helper commands (`+` prefix) in README + + Adds a "Helper Commands" section to the Advanced Usage chapter explaining + the `+` prefix convention, listing all 24 helper commands across 10 services + with descriptions and usage examples. + +## 0.12.0 + +### Minor Changes + +- 247e27a: Add structured exit codes for scriptable error handling + + `gws` now exits with a type-specific code instead of always using `1`: + + | Code | Meaning | + | ---- | --------------------------------------------------------------- | + | `0` | Success | + | `1` | API error — Google returned a 4xx/5xx response | + | `2` | Auth error — credentials missing, expired, or invalid | + | `3` | Validation error — bad arguments, unknown service, invalid flag | + | `4` | Discovery error — could not fetch the API schema document | + | `5` | Internal error — unexpected failure | + + Exit codes are documented in `gws --help` and in the README. + +### Patch Changes + +- 087066f: Fix `gws auth login` encrypted credential persistence by enabling native keyring backends for the `keyring` crate on supported desktop platforms instead of silently falling back to the in-memory mock store. + +## 0.11.1 + +### Patch Changes + +- adbca87: Fix `--format csv` for array-of-arrays responses (e.g. Sheets values API) + +## 0.11.0 + +### Minor Changes + +- 4d4b09f: Add `--cc` and `--bcc` flags to `+send`, `--to` and `--bcc` to `+reply` and `+reply-all`, and `--bcc` to `+forward`. + +## 0.10.0 + +### Minor Changes + +- 8d89325: Add `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND` env var for explicit keyring backend selection (`keyring` or `file`). Fixes credential key loss in Docker/keyring-less environments by never deleting `.encryption_key` and always persisting it as a fallback. + +### Patch Changes + +- 06aa698: fix(auth): dynamically fetch scopes from Discovery docs when `-s` specifies services not in static scope lists +- 06aa698: fix(auth): format extract_scopes_from_doc and deduplicate dynamic scopes +- 5e7d120: Bring `+forward` behavior in line with Gmail's web UI: keep the forward in the sender's original thread, add a blank line between the forwarded message metadata and body, and remove the spurious closing delimiter. +- 2782cf1: Fix gmail +triage 403 error by using gmail.readonly scope instead of gmail.modify to avoid conflict with gmail.metadata scope that does not support the q parameter + +## 0.9.1 + +### Patch Changes + +- 5872dbe: Stop persisting encryption key to `.encryption_key` file when OS keyring is available. Existing file-based keys are migrated into the keyring and the file is removed on next CLI invocation. + +## 0.9.0 + +### Minor Changes + +- 7d15365: feat(gmail): add +reply, +reply-all, and +forward helpers + + Adds three new Gmail helper commands: + + - `+reply` -- reply to a message with automatic threading + - `+reply-all` -- reply to all recipients with --remove/--cc support + - `+forward` -- forward a message to new recipients + +### Patch Changes + +- 08716f8: Fix garbled non-ASCII email subjects in `gmail +send` by RFC 2047 encoding the Subject header and adding MIME-Version/Content-Type headers. +- f083eb9: Improve `gws auth setup` project creation failures in step 3: + - Detect Google Cloud Terms of Service precondition failures and show actionable guidance (`gcloud auth list`, account verification, Console ToS URL). + - Detect invalid project ID format / already-in-use errors and show clearer guidance. + - In interactive setup, keep the wizard open and re-prompt for a new project ID instead of exiting immediately on create failures. +- 789e7f1: Switch reqwest TLS from bundled Mozilla roots to native OS certificate store + + This allows the CLI to trust custom or corporate CA certificates installed + in the system trust store, fixing TLS errors in enterprise environments. + +## 0.8.1 + +### Patch Changes + +- 4d41e52: Prioritize local project configuration and `GOOGLE_WORKSPACE_PROJECT_ID` over global Application Default Credentials (ADC) for quota attribution. This fixes 403 errors when the Drive API is disabled in a global gcloud project but enabled in the project configured for gws. + +## 0.8.0 + +### Minor Changes + +- dd3fc90: Remove `mcp` command + +## 0.7.0 + +### Minor Changes + +- e1505af: Remove multi-account, domain-wide delegation, and impersonation support. Removes `gws auth list`, `gws auth default`, `--account` flag, `GOOGLE_WORKSPACE_CLI_ACCOUNT` and `GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER` env vars. + +### Patch Changes + +- 54b3b31: Move x-goog-user-project header from default client headers to API request builder, fixing Discovery Document fetches failing with 403 when the quota project lacks certain APIs enabled + +## 0.6.3 + +### Patch Changes + +- 322529d: Document all environment variables and enable GOOGLE_WORKSPACE_CLI_CONFIG_DIR in release builds +- 2173a92: Send x-goog-user-project header when using ADC with a quota_project_id +- 1f47420: fix: extract CLA label job into dedicated workflow to prevent feedback loop + + The Automation workflow's `check_run: [completed]` trigger caused a feedback + loop — every workflow completion fired a check_run event, re-triggering + Automation, which produced another check_run event, and so on. Moving the + CLA label job to its own `cla.yml` workflow eliminates the trigger from + Automation entirely. + +- 132c3b1: fix: warn on credential file permission failures instead of ignoring + + Replaced silent `let _ =` on `set_permissions` calls in `save_encrypted` + with `eprintln!` warnings so users are aware if their credential files + end up with insecure permissions. Also log keyring access failures + instead of silently falling through to file storage. + +- a2cc523: Add `x86_64-unknown-linux-musl` build target for Linux musl/static binary support +- c86b964: Fix multi-account selection: MCP server now respects `GOOGLE_WORKSPACE_CLI_ACCOUNT` env var (#221), and `--account` flag before service name no longer causes parse errors (#181) +- ff53538: Fix scope selection to use first (broadest) scope instead of all method scopes, preventing gmail.metadata restrictions from blocking query parameters +- c80eb52: Replace strip_suffix(".readonly").unwrap() with unwrap_or fallback + + Two call sites used `.strip_suffix(".readonly").unwrap()` which would + panic if a scope URL marked as `is_readonly` didn't actually end with + ".readonly". While the current data makes this unlikely, using + `unwrap_or` is a defensive improvement that prevents potential panics + from inconsistent discovery data. + +- 9a780d7: Log token cache decryption/parse errors instead of silently swallowing + + Previously, `load_from_disk` used four nested `if let Ok` blocks that + silently returned an empty map on any failure. When the encryption key + changed or the cache was corrupted, tokens silently stopped loading and + users were forced to re-authenticate with no explanation. + + Now logs specific warnings to stderr for decryption failures, invalid + UTF-8, and JSON parse errors, with a hint to re-authenticate. + +- 6daf90d: Fix MCP tool schemas to conditionally include `body`, `upload`, and `page_all` properties only when the underlying Discovery Document method supports them. `body` is included only when a request body is defined, `upload` only when `supportsMediaUpload` is true, and `page_all` only when the method has a `pageToken` parameter. Also drops empty `body: {}` objects that LLMs commonly send on GET methods, preventing 400 errors from Google APIs. + +## 0.6.2 + +### Patch Changes + +- 28fa25a: Clean up nits from PR #175 auth fix + + - Update stale docstring on `resolve_account` to match new fallthrough behavior + - Add breadcrumb comment on string-based error matching in `main.rs` + - Move identity scope injection before authenticator build for readability + +## 0.6.1 + +### Patch Changes + +- 88cb65c: chore: add automation workflow for auto-fmt, CLA labeling, and file-based PR triage +- a926e3f: Fix auth failures when accounts.json registry is missing + + Three related bugs caused all API calls to fail with "Access denied. No credentials provided" even after a successful `gws auth login`: + + 1. `resolve_account()` rejected valid `credentials.enc` as "legacy" when `accounts.json` was absent, instead of using them. + 2. `main.rs` silently swallowed all auth errors, masking real failures behind a generic message. + 3. `auth login` didn't include `openid`/`email` scopes, so `fetch_userinfo_email()` couldn't identify the user, causing credentials to be saved without an `accounts.json` entry. + +- cb1f988: Add Content-Length: 0 header for POST/PUT/PATCH requests with no body to fix HTTP 411 errors +- 3d59b2e: fix: isolate flaky auth tests from host ADC credentials + +## 0.6.0 + +### Minor Changes + +- b38b760: Add Application Default Credentials (ADC) support. + + `gws` now discovers ADC as a fourth credential source, after the encrypted + and plaintext credential files. The lookup order is: + + 1. `GOOGLE_WORKSPACE_CLI_TOKEN` env var (raw access token, highest priority) + 2. `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` env var + 3. Encrypted credentials (`~/.config/gws/credentials.enc`) + 4. Plaintext credentials (`~/.config/gws/credentials.json`) + 5. **ADC** — `GOOGLE_APPLICATION_CREDENTIALS` env var (hard error if file missing), then + `~/.config/gcloud/application_default_credentials.json` (silent if absent) + + This means `gcloud auth application-default login --client-id-file=client_secret.json` + is now a fully supported auth flow — no need to run `gws auth login` separately. + Both `authorized_user` and `service_account` ADC formats are supported. + +## 0.5.0 + +### Minor Changes + +- 9cf6e0e: Add `--tool-mode compact|full` flag to `gws mcp`. Compact mode exposes one tool per service plus a `gws_discover` meta-tool, reducing context window usage from 200-400 tools to ~26. + +### Patch Changes + +- 0a16d0b: Add `-s`/`--services` flag to `gws auth login` to filter the scope picker + by service name (e.g. `-s drive,gmail,sheets`). Also expands the workspace + admin scope blocklist to include `chat.admin.*` and `classroom.*` patterns. +- 5205467: fix(setup): drain stale keypresses between TUI screen transitions + +## 0.4.4 + +### Patch Changes + +- e1e08eb: Fix highlight color on light terminal themes by using reverse video instead of a dark-gray background + +## 0.4.3 + +### Patch Changes + +- fc6bc95: Exclude Workspace-admin-only scopes from the "Recommended" scope preset. + + Scopes that require Google Workspace domain-admin access (`apps.*`, + `cloud-identity.*`, `ediscovery`, `directory.readonly`, `groups`) now return + `400 invalid_scope` when used by personal `@gmail.com` accounts. These scopes + are no longer included in the "Recommended" template, preventing login failures + for non-Workspace users. + + Workspace admins can still select these scopes manually via the "Full Access" + template or by picking them individually in the scope picker. + + Adds a new `is_workspace_admin_scope()` helper (mirroring the existing + `is_app_only_scope()`) that centralises this detection logic. + +- 2aa6084: docs: Comprehensive README overhaul addressing user feedback. + + Added a Prerequisites section prior to the Quick Start to highlight the optional `gcloud` dependency. + Expanded the Authentication section with a decision matrix to help users choose the correct authentication path. + Added prominent warnings about OAuth "testing mode" limitations (the 25-scope cap) and the strict requirement to explicitly add the authorizing account as a "Test user" (#130). + Added a dedicated Troubleshooting section detailing fixes for common OAuth consent errors, "Access blocked" issues, and `redirect_uri_mismatch` failures. + Included shell escaping examples for Google Sheets A1 notation (`!`). + Clarified the `npm` installation rationale and added explicit links to pre-built native binaries on GitHub Releases. + +## 0.4.2 + +### Patch Changes + +- d3e90e4: fix: use ~/.config/gws on all platforms for consistent config path + + Previously used `dirs::config_dir()` which resolves to different paths per OS + (e.g. ~/Library/Application Support/gws on macOS, %APPDATA%\gws on Windows), + contradicting the documented ~/.config/gws/ path. Now uses ~/.config/gws/ + everywhere with a fallback to the legacy OS-specific path for existing installs. + +## 0.4.1 + +### Patch Changes + +- dbda001: Add "Enter project ID manually" option to project picker in `gws auth setup`. + + Users with large numbers of GCP projects often hit the 10-second listing timeout. + The picker now includes a "⌨ Enter project ID manually" item so users can type a + known project ID directly without waiting for `gcloud projects list` to complete. + +## 0.4.0 + +### Minor Changes + +- 87e4bb1: Add Linux ARM64 build targets (aarch64-unknown-linux-gnu and aarch64-unknown-linux-musl) to cargo-dist, enabling prebuilt binaries for ARM64 Linux users via npm, the shell installer, and GitHub Releases. +- d1825f9: ### Multi-Account Support + + Add support for managing multiple Google accounts with per-account credential storage. + + **New features:** + + - `--account EMAIL` global flag available on every command + - `GOOGLE_WORKSPACE_CLI_ACCOUNT` environment variable as fallback + - `gws auth login --account EMAIL` — associates credentials with a specific account + - `gws auth list` — lists all registered accounts + - `gws auth default EMAIL` — sets the default account + - `gws auth logout --account EMAIL` — removes a specific account + - `login_hint` in OAuth URL for automatic account pre-selection in browser + - Email validation via Google userinfo endpoint after OAuth flow + + **Breaking change:** Existing users must run `gws auth login` again after upgrading. The credential storage format has changed from a single `credentials.enc` to per-account files (`credentials..enc`) with an `accounts.json` registry. + +### Patch Changes + +- a6994ad: Filter out `apps.alerts` scopes from user OAuth login flow since they require service account with domain-wide delegation +- 1ad4f34: fix: replace unwrap() calls with proper error handling in MCP server + + Replaced four `unwrap()` calls in `mcp_server.rs` that could panic the MCP + server process with graceful error handling. Also added a warning log when + authentication silently falls back to unauthenticated mode. + +- a1be14f: fix: drain stdout pipe to prevent project listing timeout during auth setup + + Fixed `gws auth setup` timing out at step 3 (GCP project selection) for users + with many projects. The `gcloud projects list` stdout pipe was only read after + the child process exited, causing a deadlock when output exceeded the OS pipe + buffer (~64 KB). Stdout is now drained in a background thread to prevent the + pipe from filling up. + +- 364542b: fix: reject DEL character (0x7F) in input validation + + The `reject_control_chars` helper rejected bytes 0x00–0x1F but allowed + the DEL character (0x7F), which is also an ASCII control character. This + could allow malformed input from LLM agents to bypass validation. + +- 75cec1b: Fix URL template expansion so media upload endpoints substitute path parameters and avoid iterative replacement side effects. +- ed409e3: Harden URL and path construction across helper modules (gmail/watch, modelarmor, discovery) +- 263a8e5: fix: use gcloud.cmd on Windows and show platform-correct config paths + + On Windows, gcloud is installed as `gcloud.cmd` which Rust's `Command` + cannot find without the extension. Also replaced hardcoded `~/.config/gws/` + in error messages with the actual platform-resolved path. + +## 0.3.5 + +### Patch Changes + +- 4bca693: fix: credential masking panic and silent token write errors + + Fixed `gws auth export` masking which panicked on short strings and showed + the entire secret instead of masking it. Also fixed silent token cache write + failures in `save_to_disk` that returned `Ok(())` even when the write failed. + +- f84ce37: Fix URL template path expansion to safely encode path parameters, including + Sheets `range` values with Unicode and reserved characters. `{var}` expansions + now encode as a path segment, `{+var}` preserves slashes while encoding each + segment, and invalid path parameter/template mismatches fail fast. +- eb0347a: fix: correct author email typo in package.json +- 70d0cdd: Fix Slides presentations.get failure caused by flatPath placeholder mismatch + + When a Discovery Document's `flatPath` uses placeholder names that don't match + the method's parameter names (e.g., `{presentationsId}` vs `presentationId`), + `build_url` now falls back to the `path` field which uses RFC 6570 operators + that resolve correctly. + + Fixes #118 + +- 37ab483: Add flake.nix for nix & NixOS installs +- 1991d53: Add prominent disclaimer that this is not an officially supported Google product to README, --help, and --version output + +## 0.3.4 + +### Patch Changes + +- 704928b: fix(setup): enable APIs individually and surface gcloud errors + + Previously `gws auth setup` used a single batch `gcloud services enable` call + for all Workspace APIs. If any one API failed, the entire batch was marked as + failed and stderr was silently discarded. APIs are now enabled individually and + in parallel, with error messages surfaced to the user. + +## 0.3.3 + +### Patch Changes + +- 92e66a3: Add `gws version` as a bare subcommand alongside `gws --version` and `gws -V` + +## 0.3.2 + +### Patch Changes + +- 8fadbd6: Smarter truncation of method and resource descriptions from discovery docs. Descriptions now truncate at sentence boundaries when possible, fall back to word boundaries with an ellipsis, and strip markdown links to reclaim character budget. Fixes #64. + +## 0.3.1 + +### Patch Changes + +- b3669e0: Add hourly cron to generate-skills workflow to auto-sync skills with upstream Google Discovery API changes via PR +- e8d533e: Add workflow to publish OpenClaw skills to ClawHub +- 3b38c8d: Sync generated skills with latest Google Discovery API specs + +## 0.3.0 + +### Minor Changes + +- 670267f: feat: add `gws mcp` Model Context Protocol server + + Adds a new `gws mcp` subcommand that starts an MCP server over stdio, + exposing Google Workspace APIs as structured tools to any MCP-compatible + client (Claude Desktop, Gemini CLI, VS Code, etc.). + +### Patch Changes + +- 8c1042a: Fix x-goog-api-client header format to use `gl-rust/gws-` +- 3de9762: Fix docs: `gws setup` → `gws auth setup` (fixes #56, #57) + +## 0.2.2 + +### Patch Changes + +- f281797: docs(auth): add manual Google Cloud OAuth client setup and browser-assisted login guidance + + Adds step-by-step guidance for creating a Desktop OAuth client in Google Cloud Console, + where to place `client_secret.json`, and how humans/agents can complete browser consent + (including unverified app and scope-selection prompts). + +- ee2e216: Narrow default OAuth scopes to avoid `Error 403: restricted_client` on unverified apps and add a `--full` flag for broader access (fixes #25). Replace the cryptic non-interactive setup error with actionable step-by-step OAuth console instructions (fixes #24). +- de2787e: feat(error): detect disabled APIs and guide users to enable them + + When the Google API returns a 403 `accessNotConfigured` error (i.e., the + required API has not been enabled for the GCP project), `gws` now: + + - Extracts the GCP Console enable URL from the error message body. + - Prints the original error JSON to stdout (machine-readable, unchanged shape + except for an optional new `enable_url` field added to the error object). + - Prints a human-readable hint with the direct enable URL to stderr, along + with instructions to retry after enabling. + + This prevents a dead-end experience where users see a raw 403 JSON blob + with no guidance. The JSON output is backward-compatible; only an optional + `enable_url` field is added when the URL is parseable from the message. + + Fixes #31 + +- 9935dde: ci: auto-generate and commit skills on PR branch pushes +- 4b868c7: docs: add community guidance to gws-shared skill and gws --help output + + Encourages agents and users to star the repository and directs bug reports + and feature requests to GitHub Issues, with guidance to check for existing + issues before opening new ones. + +- 0603bce: fix: atomic credential file writes to prevent corruption on crash or Ctrl-C +- 666f9a8: fix(auth): support --help / -h flag on auth subcommand +- bcd2401: fix: flatten nested objects in table output and fix multi-byte char truncation panic +- ee35e4a: fix: warn to stderr when unknown --format value is provided +- e094b02: fix: YAML block scalar for strings with `#`/`:`, and repeated CSV/table headers with `--page-all` + + **Bug 1 — YAML output: `drive#file` rendered as block scalar** + + Strings containing `#` or `:` (e.g. `drive#file`, `https://…`) were + incorrectly emitted as YAML block scalars (`|`), producing output like: + + ```yaml + kind: | + drive#file + ``` + + Block scalars add an implicit trailing newline which changes the string + value and produces invalid-looking output. The fix restricts block + scalar to strings that genuinely contain newlines; all other strings + are double-quoted, which is safe for any character sequence. + + **Bug 2 — `--page-all` with `--format csv` / `--format table` repeats headers** + + When paginating with `--page-all`, each page printed its own header row, + making the combined output unusable for downstream processing: + + ``` + id,kind,name ← page 1 header + 1,drive#file,foo.txt + id,kind,name ← page 2 header (unexpected!) + 2,drive#file,bar.txt + ``` + + Column headers (and the table separator line) are now emitted only for + the first page; continuation pages contain data rows only. + +- 173d155: fix: add YAML document separators (---) when paginating with --page-all --format yaml +- 214fc18: ci: skip smoketest on fork pull requests + +## 0.2.1 + +### Patch Changes + +- 6ae7427: fix(auth): stabilize encrypted credential key fallback across sessions + + When the OS keyring returned `NoEntry`, the previous code could generate + a fresh random key on each process invocation instead of reusing one. + This caused `credentials.enc` written by `gws auth login` to be + unreadable by subsequent commands. + + Changes: + + - Always prefer an existing `.encryption_key` file before generating a new key + - When generating a new key, persist it to `.encryption_key` as a stable fallback + - Best-effort write new keys into the keyring as well + - Fix `OnceLock` race: return the already-cached key if `set` loses a race + + Fixes #27 + +## 0.2.0 + +### Minor Changes + +- b0d0b95: Add workflow helpers, personas, and 50 consumer-focused recipes + + - Add `gws workflow` subcommand with 5 built-in helpers: `+standup-report`, `+meeting-prep`, `+email-to-task`, `+weekly-digest`, `+file-announce` + - Add 10 agent personas (exec-assistant, project-manager, sales-ops, etc.) with curated skill sets + - Add `docs/skills.md` skills index and `registry/recipes.yaml` with 50 multi-step recipes for Gmail, Drive, Docs, Calendar, and Sheets + - Update README with skills index link and accurate skill count + - Fix lefthook pre-commit to run fmt and clippy sequentially + +### Patch Changes + +- 90adcb4: fix: percent-encode path parameters to prevent path traversal +- e71ce29: Fix Gemini extension installation issue by removing redundant authentication settings and update the documentation. +- 90adcb4: fix: harden input validation for AI/LLM callers + + - Add `src/validate.rs` with `validate_safe_output_dir`, `validate_msg_format`, and `validate_safe_dir_path` helpers + - Validate `--output-dir` against path traversal in `gmail +watch` and `events +subscribe` + - Validate `--msg-format` against allowlist (full, metadata, minimal, raw) in `gmail +watch` + - Validate `--dir` against path traversal in `script +push` + - Add clap `value_parser` constraint for `--msg-format` + - Document input validation patterns in `AGENTS.md` + +- 90adcb4: Security: Harden validate_resource_name and fix Gmail watch path traversal +- 90adcb4: Replace manual `urlencoded()` with reqwest `.query()` builder for safer URL encoding +- c11d3c4: Added test coverage for `EncryptedTokenStorage::new` initialization. +- 7664357: Add test for missing error path in load_client_config +- 90adcb4: fix: add shared URL safety helpers for path params (`encode_path_segment`, `validate_resource_name`) +- 90adcb4: fix: warn on stderr when API calls fail silently + +## 0.1.5 + +### Patch Changes + +- d29f41e: Fix README typography and spacing + +## 0.1.4 + +### Patch Changes + +- adb2cfa: Fix OAuth login failing with "no refresh token" error by decrypting the token cache before parsing and supporting the HashMap token format used by EncryptedTokenStorage +- d990dcc: Improve README branding by making the hero banner full-width. + +## 0.1.3 + +### Patch Changes + +- c714f4b: Fix npm package name to publish as @googleworkspace/cli instead of gws + +## 0.1.2 + +### Patch Changes + +- 3cd4d52: Fix release pipeline to sync Cargo.toml version with changesets and create git tags for private packages + +## 0.1.1 + +### Patch Changes + +- a0ad089: Speed up CI builds with Swatinem/rust-cache, sccache, and build artifact reuse for smoketests +- 30d929b: Optimize demo GIF and improve README diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2b3af2d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +When contributing to this repository, you must strictly follow all guidelines outlined in the AGENTS.md file. diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..8a0b03b --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,74 @@ +# Google Workspace CLI (`gws`) Context + +The `gws` CLI provides dynamic access to Google Workspace APIs (Drive, Gmail, Calendar, Sheets, Admin, etc.) by parsing Discovery Documents at runtime. + +## Rules of Engagement for Agents + +* **Schema Discovery:** *If you don't know the exact JSON payload structure, run `gws schema .` first to inspect the schema before executing.* +* **Context Window Protection:** *Workspace APIs (like Drive and Gmail) return massive JSON blobs. ALWAYS use field masks when listing or getting resources by appending `--params '{"fields": "id,name"}'` to avoid overwhelming your context window.* +* **Dry-Run Safety:** *Always use the `--dry-run` flag for mutating operations (create, update, delete) to validate your JSON payload before actual execution.* + +## Core Syntax + +```bash +gws [sub-resource] [flags] +``` + +Use `--help` to get help on the available commands. + +```bash +gws --help +gws --help +gws --help +gws --help +``` + +### Key Flags + +- `--params ''`: URL/query parameters (e.g., `id`, `q`, `pageSize`). +- `--json ''`: Request body for POST/PUT/PATCH methods. +- `--page-all`: Auto-paginates results and outputs NDJSON (one JSON object per line). +- `--fields ''`: Limits the response fields (critical for AI context window efficiency). +- `--upload `: Files for multipart uploads (e.g., `drive files create`). +- `--output `: Destination for binary downloads (e.g., `drive files get`). +- `--sanitize

gws

Success!