feat(docs): add a structured document reader

.changeset/current-clippy-baseline.md

@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": patch
+---
+
+Keep Apps Script file selection compatible with the current Clippy checks.

.changeset/docs-structured-read.md

@@ -0,0 +1,9 @@
+---
+"@googleworkspace/cli": minor
+---
+
+Add `gws docs +read` to translate documents into compact structured content with
+recursive tabs, headings and an outline, styled text, suggestions, nested tables,
+figure metadata, and reference markers. Preserve API indices and revisions,
+reject partial field masks, and support the existing formatters, sanitization,
+and credential-free dry-run.

.changeset/yaml-empty-collections.md

@@ -0,0 +1,7 @@
+---
+"@googleworkspace/cli": patch
+---
+
+Fix YAML mapping values containing empty arrays or objects by separating their
+inline collection syntax from the mapping colon. This also fixes structured
+Docs reader output with empty outlines, child tabs, or style maps.

crates/google-workspace-cli/src/formatter.rs

@@ -319,7 +319,10 @@ fn json_to_yaml(value: &Value, indent: usize) -> String {
                 match val {
                     Value::Object(_) | Value::Array(_) => {
                         let val_str = json_to_yaml(val, indent + 1);
-                        let _ = write!(out, "\n{prefix}{key}:{val_str}");
+                        // Empty collections use inline flow syntax and need a
+                        // space after the colon; block collections start a line.
+                        let separator = if val_str.starts_with('\n') { "" } else { " " };
+                        let _ = write!(out, "\n{prefix}{key}:{separator}{val_str}");
                     }
                     _ => {
                         let val_str = json_to_yaml(val, indent);
@@ -637,6 +640,24 @@ mod tests {
         assert!(output.contains("count: 42"));
     }
 
+    #[test]
+    fn test_format_yaml_empty_collections_as_mapping_values() {
+        let value = json!({"array": [], "object": {}, "tail": true});
+        assert_eq!(
+            format_value(&value, &OutputFormat::Yaml),
+            "\narray: []\nobject: {}\ntail: true"
+        );
+    }
+
+    #[test]
+    fn test_format_yaml_empty_collections_nested_in_sequences() {
+        let value = json!({"items": [[], {}, {"array": [], "object": {}}, "tail"]});
+        assert_eq!(
+            format_value(&value, &OutputFormat::Yaml),
+            "\nitems:\n  - []\n  - {}\n  - \n    array: []\n    object: {}\n  - \"tail\""
+        );
+    }
+
     #[test]
     fn test_format_table_empty_array() {
         let val = json!({"files": []});

crates/google-workspace-cli/src/helpers/docs.rs

@@ -21,14 +21,21 @@ use serde_json::json;
 use std::future::Future;
 use std::pin::Pin;
 
+mod read;
+
 pub struct DocsHelper;
 
+#[cfg(test)]
+#[path = "docs/read_tests.rs"]
+mod read_tests;
+
 impl Helper for DocsHelper {
     fn inject_commands(
         &self,
         mut cmd: Command,
         _doc: &crate::discovery::RestDescription,
     ) -> Command {
+        cmd = cmd.subcommand(read::command());
         cmd = cmd.subcommand(
             Command::new("+write")
                 .about("[Helper] Append text to a document")
@@ -63,9 +70,13 @@ TIPS:
         &'a self,
         doc: &'a crate::discovery::RestDescription,
         matches: &'a ArgMatches,
-        _sanitize_config: &'a crate::helpers::modelarmor::SanitizeConfig,
+        sanitize_config: &'a crate::helpers::modelarmor::SanitizeConfig,
     ) -> Pin<Box<dyn Future<Output = Result<bool, GwsError>> + Send + 'a>> {
         Box::pin(async move {
+            if let Some(matches) = matches.subcommand_matches("+read") {
+                read::handle(doc, matches, sanitize_config).await?;
+                return Ok(true);
+            }
             if let Some(matches) = matches.subcommand_matches("+write") {
                 let (params_str, body_str, scopes) = build_write_request(matches, doc)?;