feat: implement namespace-aware config resolution and add man page rendering support

Author: tercel

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "apcore-cli"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2021"
 description = "Command-line interface for apcore modules"
 license = "Apache-2.0"
@@ -21,7 +21,7 @@ name = "apcore_cli"
 path = "src/lib.rs"
 
 [dependencies]
-apcore = ">=0.14"
+apcore = "=0.15.1"
 async-trait = "0.1"
 clap = { version = "4", features = ["derive", "env", "string"] }
 serde = { version = "1", features = ["derive"] }

src/cli.rs

@@ -823,8 +823,10 @@ fn is_valid_module_id(s: &str) -> bool {
 /// * everything else (including `MODULE_EXECUTE_ERROR` / `MODULE_TIMEOUT`) → 1
 pub(crate) fn map_apcore_error_to_exit_code(error_code: &str) -> i32 {
     use crate::{
-        EXIT_ACL_DENIED, EXIT_APPROVAL_DENIED, EXIT_CONFIG_NOT_FOUND, EXIT_MODULE_EXECUTE_ERROR,
-        EXIT_MODULE_NOT_FOUND, EXIT_SCHEMA_CIRCULAR_REF, EXIT_SCHEMA_VALIDATION_ERROR,
+        EXIT_ACL_DENIED, EXIT_APPROVAL_DENIED, EXIT_CONFIG_BIND_ERROR, EXIT_CONFIG_MOUNT_ERROR,
+        EXIT_CONFIG_NAMESPACE_RESERVED, EXIT_CONFIG_NOT_FOUND, EXIT_ERROR_FORMATTER_DUPLICATE,
+        EXIT_MODULE_EXECUTE_ERROR, EXIT_MODULE_NOT_FOUND, EXIT_SCHEMA_CIRCULAR_REF,
+        EXIT_SCHEMA_VALIDATION_ERROR,
     };
     match error_code {
         "MODULE_NOT_FOUND" | "MODULE_LOAD_ERROR" | "MODULE_DISABLED" => EXIT_MODULE_NOT_FOUND,
@@ -833,6 +835,13 @@ pub(crate) fn map_apcore_error_to_exit_code(error_code: &str) -> i32 {
         "CONFIG_NOT_FOUND" | "CONFIG_INVALID" => EXIT_CONFIG_NOT_FOUND,
         "SCHEMA_CIRCULAR_REF" => EXIT_SCHEMA_CIRCULAR_REF,
         "ACL_DENIED" => EXIT_ACL_DENIED,
+        // Config Bus errors (apcore >= 0.15.0)
+        "CONFIG_NAMESPACE_RESERVED"
+        | "CONFIG_NAMESPACE_DUPLICATE"
+        | "CONFIG_ENV_PREFIX_CONFLICT" => EXIT_CONFIG_NAMESPACE_RESERVED,
+        "CONFIG_MOUNT_ERROR" => EXIT_CONFIG_MOUNT_ERROR,
+        "CONFIG_BIND_ERROR" => EXIT_CONFIG_BIND_ERROR,
+        "ERROR_FORMATTER_DUPLICATE" => EXIT_ERROR_FORMATTER_DUPLICATE,
         _ => EXIT_MODULE_EXECUTE_ERROR,
     }
 }

src/config.rs

@@ -41,6 +41,22 @@ impl ConfigResolver {
         ("cli.stdin_buffer_limit", "10485760"),
         ("cli.auto_approve", "false"),
         ("cli.help_text_max_length", "1000"),
+        // Namespace-mode aliases (apcore >= 0.15.0 Config Bus)
+        ("apcore-cli.stdin_buffer_limit", "10485760"),
+        ("apcore-cli.auto_approve", "false"),
+        ("apcore-cli.help_text_max_length", "1000"),
+        ("apcore-cli.logging_level", "WARNING"),
+    ];
+
+    /// Namespace key → legacy key mapping for backward compatibility.
+    const NAMESPACE_MAP: &'static [(&'static str, &'static str)] = &[
+        ("apcore-cli.stdin_buffer_limit", "cli.stdin_buffer_limit"),
+        ("apcore-cli.auto_approve", "cli.auto_approve"),
+        (
+            "apcore-cli.help_text_max_length",
+            "cli.help_text_max_length",
+        ),
+        ("apcore-cli.logging_level", "logging.level"),
     ];
 
     /// Create a new `ConfigResolver`.
@@ -94,16 +110,36 @@ impl ConfigResolver {
         }
 
         // Tier 3: Config file — key must be present in the flattened map.
+        // Try both namespace and legacy keys for backward compatibility.
         if let Some(ref file_map) = self.config_file {
             if let Some(value) = file_map.get(key) {
                 return Some(value.clone());
             }
+            // Try alternate key (namespace ↔ legacy)
+            if let Some(alt) = Self::alternate_key(key) {
+                if let Some(value) = file_map.get(alt) {
+                    return Some(value.clone());
+                }
+            }
         }
 
         // Tier 4: Built-in defaults.
         self.defaults.get(key).map(|s| s.to_string())
     }
 
+    /// Look up the alternate key (namespace ↔ legacy) for backward compatibility.
+    fn alternate_key(key: &str) -> Option<&'static str> {
+        for &(ns, legacy) in Self::NAMESPACE_MAP {
+            if key == ns {
+                return Some(legacy);
+            }
+            if key == legacy {
+                return Some(ns);
+            }
+        }
+        None
+    }
+
     /// Load and flatten a YAML config file into dot-notation keys.
     ///
     /// Returns `None` if the file does not exist or cannot be parsed.
@@ -346,4 +382,116 @@ mod tests {
         let result = resolver.flatten_dict(map);
         assert_eq!(result.get("a.b.c"), Some(&"deep".to_string()));
     }
+
+    // ---- Namespace-aware config resolution (apcore >= 0.15.0) ----
+
+    #[test]
+    fn test_defaults_contain_namespace_keys() {
+        let resolver = ConfigResolver::new(None, None);
+        for key in [
+            "apcore-cli.stdin_buffer_limit",
+            "apcore-cli.auto_approve",
+            "apcore-cli.help_text_max_length",
+            "apcore-cli.logging_level",
+        ] {
+            assert!(
+                resolver.defaults.contains_key(key),
+                "missing namespace default: {key}"
+            );
+        }
+    }
+
+    #[test]
+    fn test_alternate_key_namespace_to_legacy() {
+        assert_eq!(
+            ConfigResolver::alternate_key("apcore-cli.stdin_buffer_limit"),
+            Some("cli.stdin_buffer_limit")
+        );
+        assert_eq!(
+            ConfigResolver::alternate_key("apcore-cli.auto_approve"),
+            Some("cli.auto_approve")
+        );
+        assert_eq!(
+            ConfigResolver::alternate_key("apcore-cli.logging_level"),
+            Some("logging.level")
+        );
+    }
+
+    #[test]
+    fn test_alternate_key_legacy_to_namespace() {
+        assert_eq!(
+            ConfigResolver::alternate_key("cli.stdin_buffer_limit"),
+            Some("apcore-cli.stdin_buffer_limit")
+        );
+        assert_eq!(
+            ConfigResolver::alternate_key("cli.auto_approve"),
+            Some("apcore-cli.auto_approve")
+        );
+        assert_eq!(
+            ConfigResolver::alternate_key("logging.level"),
+            Some("apcore-cli.logging_level")
+        );
+    }
+
+    #[test]
+    fn test_alternate_key_unknown_returns_none() {
+        assert_eq!(ConfigResolver::alternate_key("unknown.key"), None);
+        assert_eq!(ConfigResolver::alternate_key("extensions.root"), None);
+    }
+
+    #[test]
+    fn test_resolve_namespace_key_from_legacy_file() {
+        // Simulate a config file with legacy "cli.stdin_buffer_limit" key
+        let mut file_map = HashMap::new();
+        file_map.insert("cli.stdin_buffer_limit".to_string(), "5242880".to_string());
+        let resolver = ConfigResolver {
+            cli_flags: HashMap::new(),
+            config_file: Some(file_map),
+            config_path: None,
+            defaults: ConfigResolver::DEFAULTS.iter().copied().collect(),
+        };
+        // Querying the namespace key should find the legacy key via fallback
+        let result = resolver.resolve("apcore-cli.stdin_buffer_limit", None, None);
+        assert_eq!(result, Some("5242880".to_string()));
+    }
+
+    #[test]
+    fn test_resolve_legacy_key_from_namespace_file() {
+        // Simulate a config file with namespace "apcore-cli.auto_approve" key
+        let mut file_map = HashMap::new();
+        file_map.insert("apcore-cli.auto_approve".to_string(), "true".to_string());
+        let resolver = ConfigResolver {
+            cli_flags: HashMap::new(),
+            config_file: Some(file_map),
+            config_path: None,
+            defaults: ConfigResolver::DEFAULTS.iter().copied().collect(),
+        };
+        // Querying the legacy key should find the namespace key via fallback
+        let result = resolver.resolve("cli.auto_approve", None, None);
+        assert_eq!(result, Some("true".to_string()));
+    }
+
+    #[test]
+    fn test_direct_key_takes_precedence_over_alternate() {
+        let mut file_map = HashMap::new();
+        file_map.insert("cli.help_text_max_length".to_string(), "500".to_string());
+        file_map.insert(
+            "apcore-cli.help_text_max_length".to_string(),
+            "2000".to_string(),
+        );
+        let resolver = ConfigResolver {
+            cli_flags: HashMap::new(),
+            config_file: Some(file_map),
+            config_path: None,
+            defaults: ConfigResolver::DEFAULTS.iter().copied().collect(),
+        };
+        assert_eq!(
+            resolver.resolve("cli.help_text_max_length", None, None),
+            Some("500".to_string())
+        );
+        assert_eq!(
+            resolver.resolve("apcore-cli.help_text_max_length", None, None),
+            Some("2000".to_string())
+        );
+    }
 }

src/lib.rs

@@ -30,6 +30,13 @@ pub const EXIT_APPROVAL_DENIED: i32 = 46;
 pub const EXIT_CONFIG_NOT_FOUND: i32 = 47;
 pub const EXIT_SCHEMA_CIRCULAR_REF: i32 = 48;
 pub const EXIT_ACL_DENIED: i32 = 77;
+// Config Bus errors (apcore >= 0.15.0)
+pub const EXIT_CONFIG_NAMESPACE_RESERVED: i32 = 78;
+pub const EXIT_CONFIG_NAMESPACE_DUPLICATE: i32 = 78;
+pub const EXIT_CONFIG_ENV_PREFIX_CONFLICT: i32 = 78;
+pub const EXIT_CONFIG_MOUNT_ERROR: i32 = 66;
+pub const EXIT_CONFIG_BIND_ERROR: i32 = 65;
+pub const EXIT_ERROR_FORMATTER_DUPLICATE: i32 = 70;
 pub const EXIT_SIGINT: i32 = 130;
 
 // Re-export primary public types at crate root.

src/main.rs

@@ -65,6 +65,67 @@ pub fn extract_binding_path(args: &[String]) -> Option<String> {
     extract_argv_option(args, "--binding")
 }
 
+// ---------------------------------------------------------------------------
+// render_man_page
+// ---------------------------------------------------------------------------
+
+/// Render a roff man page to stdout.
+///
+/// When stdout is a TTY, attempts to render through `mandoc` or `groff` and
+/// pipe through a pager for formatted display. When stdout is not a TTY
+/// (piped or redirected), outputs raw roff for file redirection.
+fn render_man_page(roff: &str) {
+    use std::io::{IsTerminal, Write};
+    use std::process::{Command, Stdio};
+
+    let is_tty = std::io::stdout().is_terminal();
+    if !is_tty {
+        print!("{roff}");
+        return;
+    }
+
+    // Try mandoc first (macOS/BSD), then groff.
+    let renderers: &[(&str, &[&str])] = &[("mandoc", &["-a"]), ("groff", &["-man", "-Tutf8"])];
+    for &(cmd, args) in renderers {
+        let Ok(mut child) = Command::new(cmd)
+            .args(args)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .spawn()
+        else {
+            continue;
+        };
+        if let Some(mut stdin) = child.stdin.take() {
+            let _ = stdin.write_all(roff.as_bytes());
+        }
+        let Ok(output) = child.wait_with_output() else {
+            continue;
+        };
+        if !output.status.success() || output.stdout.is_empty() {
+            continue;
+        }
+        // Pipe rendered output through PAGER or less.
+        let pager = std::env::var("PAGER").unwrap_or_else(|_| "less".to_string());
+        if let Ok(mut pager_child) = Command::new(&pager)
+            .arg("-R")
+            .stdin(Stdio::piped())
+            .stdout(Stdio::inherit())
+            .stderr(Stdio::inherit())
+            .spawn()
+        {
+            if let Some(mut stdin) = pager_child.stdin.take() {
+                let _ = stdin.write_all(&output.stdout);
+            }
+            let _ = pager_child.wait();
+            return;
+        }
+    }
+
+    // Fallback: raw roff output.
+    print!("{roff}");
+}
+
 // ---------------------------------------------------------------------------
 // resolve_prog_name
 // ---------------------------------------------------------------------------
@@ -182,6 +243,10 @@ fn build_cli_command(
         .version(env!("CARGO_PKG_VERSION"))
         .long_version(format!("{}, version {}", name, env!("CARGO_PKG_VERSION")))
         .about("CLI adapter for the apcore module ecosystem.")
+        .after_help(
+            "Use --help --verbose to show all options (including built-in apcore options).\n\
+             Use --help --man to display a formatted man page.",
+        )
         .allow_external_subcommands(true)
         .arg(
             clap::Arg::new("extensions-dir")
@@ -287,7 +352,7 @@ async fn main() {
             None,
             None,
         );
-        println!("{roff}");
+        render_man_page(&roff);
         std::process::exit(0);
     }