feat: expose library crate for programmatic API access

Extract `config_dir()` into `src/config.rs` and Model Armor sanitization
types into `src/sanitize.rs` so they can be shared between the binary and
library targets without pulling in CLI-only code. Add `src/lib.rs` with
public module re-exports and `tests/lib_integration.rs` with offline tests.

Also moves `parse_service_and_version()` from `main.rs` to `services.rs`
so it is accessible from both the lib and bin crate roots.

Zero behavior changes to the binary.

Author: geofflittle

.changeset/add-library-crate.md

@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": minor
+---
+
+Expose library crate (`lib.rs`) for programmatic API access. Extracts `config_dir()` and Model Armor sanitization types into standalone modules so they can be shared between the binary and library targets without pulling in CLI-only code.

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.rs

@@ -78,7 +78,7 @@ pub async fn get_token(scopes: &[&str]) -> anyhow::Result<String> {
     }
 
     let creds_file = std::env::var("GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE").ok();
-    let config_dir = crate::auth_commands::config_dir();
+    let config_dir = crate::config::config_dir();
     let enc_path = credential_store::encrypted_credentials_path();
     let default_path = config_dir.join("credentials.json");
     let token_cache = config_dir.join("token_cache.json");

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,49 @@
+// 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.
+
+use std::path::PathBuf;
+
+/// Returns the gws configuration directory.
+///
+/// Prefers `~/.config/gws` for a consistent, cross-platform path.
+/// Falls back to the OS-specific config directory (e.g. `~/Library/Application Support/gws`
+/// on macOS) for backward compatibility with existing installs.
+///
+/// In tests, the `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` environment variable overrides the default.
+pub fn config_dir() -> PathBuf {
+    #[cfg(test)]
+    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/credential_store.rs

@@ -45,7 +45,7 @@ fn get_or_create_key() -> anyhow::Result<[u8; 32]> {
         .or_else(|_| std::env::var("USERNAME"))
         .unwrap_or_else(|_| "unknown-user".to_string());
 
-    let key_file = crate::auth_commands::config_dir().join(".encryption_key");
+    let key_file = crate::config::config_dir().join(".encryption_key");
 
     let entry = Entry::new("gws-cli", &username);
 
@@ -218,7 +218,7 @@ pub fn decrypt(data: &[u8]) -> anyhow::Result<Vec<u8>> {
 
 /// Returns the path for encrypted credentials.
 pub fn encrypted_credentials_path() -> PathBuf {
-    crate::auth_commands::config_dir().join("credentials.enc")
+    crate::config::config_dir().join("credentials.enc")
 }
 
 /// Saves credentials JSON to an encrypted file.

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/executor.rs

@@ -211,7 +211,7 @@ async fn handle_json_response(
     body_text: &str,
     pagination: &PaginationConfig,
     sanitize_template: Option<&str>,
-    sanitize_mode: &crate::helpers::modelarmor::SanitizeMode,
+    sanitize_mode: &crate::sanitize::SanitizeMode,
     output_format: &crate::formatter::OutputFormat,
     pages_fetched: &mut u32,
     page_token: &mut Option<String>,
@@ -224,15 +224,14 @@ async fn handle_json_response(
         // Run Model Armor sanitization if --sanitize is enabled
         if let Some(template) = sanitize_template {
             let text_to_check = serde_json::to_string(&json_val).unwrap_or_default();
-            match crate::helpers::modelarmor::sanitize_text(template, &text_to_check).await {
+            match crate::sanitize::sanitize_text(template, &text_to_check).await {
                 Ok(result) => {
                     let is_match = result.filter_match_state == "MATCH_FOUND";
                     if is_match {
                         eprintln!("⚠️  Model Armor: prompt injection detected (filterMatchState: MATCH_FOUND)");
                     }
 
-                    if is_match && *sanitize_mode == crate::helpers::modelarmor::SanitizeMode::Block
-                    {
+                    if is_match && *sanitize_mode == crate::sanitize::SanitizeMode::Block {
                         let blocked = serde_json::json!({
                             "error": "Content blocked by Model Armor",
                             "sanitizationResult": serde_json::to_value(&result).unwrap_or_default(),
@@ -370,7 +369,7 @@ pub async fn execute_method(
     dry_run: bool,
     pagination: &PaginationConfig,
     sanitize_template: Option<&str>,
-    sanitize_mode: &crate::helpers::modelarmor::SanitizeMode,
+    sanitize_mode: &crate::sanitize::SanitizeMode,
     output_format: &crate::formatter::OutputFormat,
     capture_output: bool,
 ) -> Result<Option<Value>, GwsError> {
@@ -1656,7 +1655,7 @@ async fn test_execute_method_dry_run() {
     let params_json = r#"{"fileId": "123"}"#;
     let body_json = r#"{"name": "test.txt"}"#;
 
-    let sanitize_mode = crate::helpers::modelarmor::SanitizeMode::Warn;
+    let sanitize_mode = crate::sanitize::SanitizeMode::Warn;
     let pagination = PaginationConfig::default();
 
     let result = execute_method(
@@ -1701,7 +1700,7 @@ async fn test_execute_method_missing_path_param() {
         ..Default::default()
     };
 
-    let sanitize_mode = crate::helpers::modelarmor::SanitizeMode::Warn;
+    let sanitize_mode = crate::sanitize::SanitizeMode::Warn;
     let result = execute_method(
         &doc,
         &method,

src/helpers/modelarmor.rs

@@ -18,65 +18,19 @@ use crate::discovery::RestDescription;
 use crate::error::GwsError;
 use anyhow::Context;
 use clap::{Arg, ArgMatches, Command};
-use serde::{Deserialize, Serialize};
 use serde_json::json;
 use std::future::Future;
 use std::pin::Pin;
 
-/// Result of a Model Armor sanitization check.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SanitizationResult {
-    /// The overall state of the match (e.g., "MATCH_FOUND", "NO_MATCH_FOUND").
-    pub filter_match_state: String,
-    /// Detailed results from specific filters (PI, Jailbreak, etc.).
-    #[serde(default)]
-    pub filter_results: serde_json::Value,
-    /// The final decision based on the policy (e.g., "BLOCK", "ALLOW").
-    #[serde(default)]
-    pub invocation_result: String,
-}
-
-/// Controls behavior when sanitization finds a match.
-#[derive(Debug, Clone, PartialEq)]
-pub enum SanitizeMode {
-    /// Log warning to stderr, annotate output with _sanitization field
-    Warn,
-    /// Suppress response output, exit non-zero
-    Block,
-}
+// Re-export sanitization types from the standalone module so existing
+// `helpers::modelarmor::` paths continue to compile.
+pub use crate::sanitize::{
+    sanitize_text, SanitizationResult, SanitizeConfig, SanitizeMode, CLOUD_PLATFORM_SCOPE,
+};
 
-/// Configuration for Model Armor sanitization, threaded through the CLI.
-#[derive(Debug, Clone)]
-pub struct SanitizeConfig {
-    pub template: Option<String>,
-    pub mode: SanitizeMode,
-}
-
-impl Default for SanitizeConfig {
-    /// Provides default values for `SanitizeConfig`.
-    ///
-    /// By default, no template is set (sanitization disabled) and the mode is `Warn`.
-    fn default() -> Self {
-        Self {
-            template: None,
-            mode: SanitizeMode::Warn,
-        }
-    }
-}
-
-impl SanitizeMode {
-    /// Parses a string into a `SanitizeMode`.
-    ///
-    /// * "block" (case-insensitive) -> `Block`
-    /// * Any other value -> `Warn` (safe default)
-    pub fn from_str(s: &str) -> Self {
-        match s.to_lowercase().as_str() {
-            "block" => SanitizeMode::Block,
-            _ => SanitizeMode::Warn,
-        }
-    }
-}
+// Re-export for tests in this module
+#[cfg(test)]
+pub(crate) use crate::sanitize::{build_sanitize_request_data, parse_sanitize_response};
 
 pub struct ModelArmorHelper;
 
@@ -243,42 +197,6 @@ TIPS:
     }
 }
 
-pub const CLOUD_PLATFORM_SCOPE: &str = "https://www.googleapis.com/auth/cloud-platform";
-
-/// Sanitize text through a Model Armor template and return the result.
-/// Template format: projects/PROJECT/locations/LOCATION/templates/TEMPLATE
-pub async fn sanitize_text(template: &str, text: &str) -> Result<SanitizationResult, GwsError> {
-    let (body, url) = build_sanitize_request_data(template, text, "sanitizeUserPrompt")?;
-
-    let token = auth::get_token(&[CLOUD_PLATFORM_SCOPE])
-        .await
-        .context("Failed to get auth token for Model Armor")?;
-
-    let client = crate::client::build_client()?;
-    let resp = client
-        .post(&url)
-        .header("Authorization", format!("Bearer {token}"))
-        .header("Content-Type", "application/json")
-        .body(body)
-        .send()
-        .await
-        .context("Model Armor request failed")?;
-
-    let status = resp.status();
-    let resp_text = resp
-        .text()
-        .await
-        .context("Failed to read Model Armor response")?;
-
-    if !status.is_success() {
-        return Err(GwsError::Other(anyhow::anyhow!(
-            "Model Armor API returned status {status}: {resp_text}"
-        )));
-    }
-
-    parse_sanitize_response(&resp_text)
-}
-
 /// Make a POST request to Model Armor's regional API endpoint.
 async fn model_armor_post(url: &str, body: &str) -> Result<(), GwsError> {
     let token = auth::get_token(&[CLOUD_PLATFORM_SCOPE])
@@ -459,23 +377,23 @@ mod tests {
 
     #[test]
     fn test_sanitize_mode_from_str_warn() {
-        assert_eq!(SanitizeMode::from_str("warn"), SanitizeMode::Warn);
-        assert_eq!(SanitizeMode::from_str("WARN"), SanitizeMode::Warn);
-        assert_eq!(SanitizeMode::from_str("Warn"), SanitizeMode::Warn);
+        assert_eq!(SanitizeMode::from("warn"), SanitizeMode::Warn);
+        assert_eq!(SanitizeMode::from("WARN"), SanitizeMode::Warn);
+        assert_eq!(SanitizeMode::from("Warn"), SanitizeMode::Warn);
     }
 
     #[test]
     fn test_sanitize_mode_from_str_block() {
-        assert_eq!(SanitizeMode::from_str("block"), SanitizeMode::Block);
-        assert_eq!(SanitizeMode::from_str("BLOCK"), SanitizeMode::Block);
-        assert_eq!(SanitizeMode::from_str("Block"), SanitizeMode::Block);
+        assert_eq!(SanitizeMode::from("block"), SanitizeMode::Block);
+        assert_eq!(SanitizeMode::from("BLOCK"), SanitizeMode::Block);
+        assert_eq!(SanitizeMode::from("Block"), SanitizeMode::Block);
     }
 
     #[test]
     fn test_sanitize_mode_from_str_unknown_defaults_to_warn() {
-        assert_eq!(SanitizeMode::from_str(""), SanitizeMode::Warn);
-        assert_eq!(SanitizeMode::from_str("invalid"), SanitizeMode::Warn);
-        assert_eq!(SanitizeMode::from_str("stop"), SanitizeMode::Warn);
+        assert_eq!(SanitizeMode::from(""), SanitizeMode::Warn);
+        assert_eq!(SanitizeMode::from("invalid"), SanitizeMode::Warn);
+        assert_eq!(SanitizeMode::from("stop"), SanitizeMode::Warn);
     }
 
     #[test]
@@ -565,47 +483,6 @@ mod tests {
     }
 }
 
-pub fn build_sanitize_request_data(
-    template: &str,
-    text: &str,
-    method: &str,
-) -> Result<(String, String), GwsError> {
-    let location = extract_location(template).ok_or_else(|| {
-        GwsError::Validation(
-            "Cannot extract location from --sanitize template. Expected format: projects/PROJECT/locations/LOCATION/templates/TEMPLATE".to_string(),
-        )
-    })?;
-
-    let base = regional_base_url(location);
-    let url = format!("{base}/{template}:{method}");
-
-    // Identify data field based on method
-    let data_field = if method == "sanitizeUserPrompt" {
-        "userPromptData"
-    } else {
-        "modelResponseData"
-    };
-
-    let body = json!({data_field: {"text": text}}).to_string();
-    Ok((body, url))
-}
-
-pub fn parse_sanitize_response(resp_text: &str) -> Result<SanitizationResult, GwsError> {
-    // Parse the response to extract sanitizationResult
-    let parsed: serde_json::Value =
-        serde_json::from_str(resp_text).context("Failed to parse Model Armor response")?;
-
-    let result = parsed.get("sanitizationResult").ok_or_else(|| {
-        GwsError::Other(anyhow::anyhow!(
-            "No sanitizationResult in Model Armor response"
-        ))
-    })?;
-
-    let res =
-        serde_json::from_value(result.clone()).context("Failed to parse sanitization result")?;
-    Ok(res)
-}
-
 fn parse_sanitize_args(matches: &ArgMatches, data_field: &str) -> Result<String, GwsError> {
     if let Some(json_str) = matches.get_one::<String>("json") {
         Ok(json_str.clone())