cli: 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: 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.

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/<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 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