feat: expose minimal library crate for programmatic API access

Cargo.toml

@@ -25,6 +25,10 @@ authors = ["Justin Poehnelt"]
 keywords = ["cli", "google-workspace", "google", "drive", "gmail"]
 categories = ["command-line-utilities", "web-programming"]
 
+[lib]
+name = "gws"
+path = "src/lib.rs"
+
 [[bin]]
 name = "gws"
 path = "src/main.rs"

src/auth_commands.rs

@@ -92,29 +92,7 @@ const READONLY_SCOPES: &[&str] = &[
 ];
 
 pub fn config_dir() -> PathBuf {
-    if let Ok(dir) = std::env::var("GOOGLE_WORKSPACE_CLI_CONFIG_DIR") {
-        return PathBuf::from(dir);
-    }
-
-    // Use ~/.config/gws on all platforms for a consistent, user-friendly path.
-    let primary = dirs::home_dir()
-        .unwrap_or_else(|| PathBuf::from("."))
-        .join(".config")
-        .join("gws");
-    if primary.exists() {
-        return primary;
-    }
-
-    // Backward compat: fall back to OS-specific config dir for existing installs
-    // (e.g. ~/Library/Application Support/gws on macOS, %APPDATA%\gws on Windows).
-    let legacy = dirs::config_dir()
-        .unwrap_or_else(|| PathBuf::from("."))
-        .join("gws");
-    if legacy.exists() {
-        return legacy;
-    }
-
-    primary
+    crate::config::config_dir()
 }
 
 fn plain_credentials_path() -> PathBuf {

src/config.rs

@@ -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.
+
+//! Configuration directory resolution.
+//!
+//! Provides [`config_dir()`] to locate the gws config directory, respecting
+//! the `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` environment variable and falling back
+//! to `~/.config/gws` (or the OS-specific legacy path for existing installs).
+
+use std::path::PathBuf;
+
+/// Returns the gws configuration directory.
+///
+/// Resolution order:
+/// 1. `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` environment variable (if set)
+/// 2. `~/.config/gws` (if it exists — primary location)
+/// 3. OS-specific config dir / `gws` (legacy fallback for existing installs)
+/// 4. `~/.config/gws` (default for new installs)
+pub fn config_dir() -> PathBuf {
+    if let Ok(dir) = std::env::var("GOOGLE_WORKSPACE_CLI_CONFIG_DIR") {
+        return PathBuf::from(dir);
+    }
+
+    // Use ~/.config/gws on all platforms for a consistent, user-friendly path.
+    let primary = dirs::home_dir()
+        .unwrap_or_else(|| PathBuf::from("."))
+        .join(".config")
+        .join("gws");
+    if primary.exists() {
+        return primary;
+    }
+
+    // Backward compat: fall back to OS-specific config dir for existing installs
+    // (e.g. ~/Library/Application Support/gws on macOS, %APPDATA%\gws on Windows).
+    let legacy = dirs::config_dir()
+        .unwrap_or_else(|| PathBuf::from("."))
+        .join("gws");
+    if legacy.exists() {
+        return legacy;
+    }
+
+    primary
+}

src/discovery.rs

@@ -195,7 +195,7 @@ pub async fn fetch_discovery_document(
     let version =
         crate::validate::validate_api_identifier(version).map_err(|e| anyhow::anyhow!("{e}"))?;
 
-    let cache_dir = crate::auth_commands::config_dir().join("cache");
+    let cache_dir = crate::config::config_dir().join("cache");
     std::fs::create_dir_all(&cache_dir)?;
 
     let cache_file = cache_dir.join(format!("{service}_{version}.json"));

src/lib.rs

@@ -0,0 +1,39 @@
+// 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.
+
+//! Google Workspace CLI — library crate.
+//!
+//! This crate exposes a focused subset of `gws` internals for programmatic
+//! access to Google Workspace APIs. Library consumers can introspect API
+//! schemas, resolve service names, validate inputs, and build authenticated
+//! HTTP clients without depending on any CLI-specific code (clap, ratatui,
+//! interactive OAuth flows, etc.).
+//!
+//! # Exposed modules
+//!
+//! | Module | Purpose |
+//! |---|---|
+//! | [`discovery`] | `RestDescription`, `RestMethod`, `RestResource` — introspect Google APIs |
+//! | [`error`] | `GwsError` — unified error type |
+//! | [`config`] | `config_dir()` — resolve the gws configuration directory |
+//! | [`services`] | `resolve_service()`, `SERVICES` — service name to API mapping |
+//! | [`validate`] | `validate_api_identifier()`, input safety helpers |
+//! | [`client`] | `build_client()`, `send_with_retry()` — HTTP with retry |
+
+pub mod client;
+pub mod config;
+pub mod discovery;
+pub mod error;
+pub mod services;
+pub mod validate;

src/main.rs

@@ -21,24 +21,27 @@
 
 mod auth;
 pub(crate) mod auth_commands;
-mod client;
 mod commands;
 pub(crate) mod credential_store;
-mod discovery;
-mod error;
 mod executor;
 mod formatter;
 mod fs_util;
 mod generate_skills;
 mod helpers;
 mod oauth_config;
 mod schema;
-mod services;
 mod setup;
 mod setup_tui;
 mod text;
 mod token_storage;
-pub(crate) mod validate;
+
+// Re-use modules from the library crate
+use gws::client;
+use gws::config;
+use gws::discovery;
+use gws::error;
+use gws::services;
+use gws::validate;
 
 use error::{print_error_json, GwsError};