gws-mcp: Instructions file for Codex

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: CI runs cargo test --workspace (ci.yml) — this fork has no codecov/coverage gate — but new or modified lines should still be 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.

cargo build          # Build in dev mode
cargo clippy -- -D warnings  # Lint check
cargo test           # Run tests

Changesets

Every PR that changes Rust source or the workspace root Cargo.toml/Cargo.lock must include a changeset file (the CI policy check skips this requirement for PRs that touch no Rust/Cargo files, e.g. docs-only PRs). Create one at .changeset/<descriptive-name>.md:

---
"@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 (policy.yml) fails without a changeset when a PR changes Rust source or the workspace root Cargo.toml/Cargo.lock.

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