Version and validate the agent-context schema (6.2.2)

cargo-orthohelp/src/agent_context/mod.rs

@@ -177,7 +177,7 @@ fn build_input(field: &FieldMetadata) -> Option<AgentInput> {
         default: field
             .default
             .as_ref()
-            .map(|default| default.display.clone()),
+            .map(|default| normalize_default_display(&default.display)),
         enum_values: enum_values(field),
     })
 }
@@ -237,6 +237,32 @@ fn enum_values(field: &FieldMetadata) -> Vec<String> {
     }
 }
 
+fn normalize_default_display(display: &str) -> String {
+    let mut normalised = String::with_capacity(display.len());
+    let mut chars = display.chars().peekable();
+
+    while let Some(character) = chars.next() {
+        if character == ':' && chars.peek() == Some(&':') {
+            while normalised
+                .chars()
+                .next_back()
+                .is_some_and(char::is_whitespace)
+            {
+                normalised.pop();
+            }
+            normalised.push_str("::");
+            chars.next();
+            while chars.peek().is_some_and(|next| next.is_whitespace()) {
+                chars.next();
+            }
+        } else {
+            normalised.push(character);
+        }
+    }
+
+    normalised
+}
+
 #[cfg(test)]
 mod proptests;
 

cargo-orthohelp/src/agent_context/proptests.rs

@@ -38,6 +38,19 @@ proptest! {
         }
     }
 
+    #[test]
+    fn transformed_trees_serialize_deterministically(tree in metadata_tree_with_fields()) {
+        let first = bridge_ir_to_agent_context(&tree, "demo_pkg", None);
+        let second = bridge_ir_to_agent_context(&tree, "demo_pkg", None);
+
+        let first_json = serde_json::to_string_pretty(&first)
+            .expect("first transform should serialize");
+        let second_json = serde_json::to_string_pretty(&second)
+            .expect("second transform should serialize");
+
+        prop_assert_eq!(first_json, second_json);
+    }
+
     #[test]
     fn hidden_fields_are_omitted_from_inputs(hidden_name in field_name("hidden")) {
         let mut tree = doc("root", Some("demo"), Vec::new());

cargo-orthohelp/src/agent_context/tests.rs

@@ -153,12 +153,60 @@ fn transform_recovers_enum_values_from_cli_metadata_for_custom_types() {
         .expect("log level input should be generated");
 
     assert_eq!(input.value_type.as_deref(), Some("enum"));
+    assert_eq!(input.default.as_deref(), Some("LogLevel::Info"));
     assert_eq!(
         input.enum_values,
         ["Debug", "Info", "Warn", "Error"].map(str::to_owned)
     );
 }
 
+#[test]
+fn transform_normalizes_default_path_separators() {
+    let metadata = doc(DocSpec {
+        app_name: "demo",
+        bin_name: Some("demo-bin"),
+        about_id: "root.about",
+        fields: vec![cli_field(FieldSpec {
+            name: "host",
+            long: Some("host"),
+            short: None,
+            takes_value: true,
+            hide_in_help: false,
+            value: Some(ValueType::String),
+            default: Some("String :: from(\"localhost\")"),
+            required: false,
+        })],
+        subcommands: Vec::new(),
+    });
+
+    let context = bridge_ir_to_agent_context(&metadata, "demo_pkg", None);
+    let command = context
+        .commands
+        .first()
+        .expect("root command should be generated");
+    let input = command
+        .inputs
+        .first()
+        .expect("host input should be generated");
+
+    assert_eq!(
+        input.default.as_deref(),
+        Some("String::from(\"localhost\")")
+    );
+}
+
+#[test]
+fn transform_projects_nested_tree_with_sorted_commands_and_inputs() {
+    let context = bridge_ir_to_agent_context(&nested_metadata(), "demo_pkg", None);
+    let commands: Vec<_> = context
+        .commands
+        .iter()
+        .map(nested_command_summary)
+        .collect();
+
+    assert_eq!(commands, expected_nested_command_summaries());
+}
+
 #[rstest]
 #[case(None, None)]
 #[case(Some(""), None)]
@@ -203,6 +251,76 @@ fn metadata_with_subcommands(subcommands: Vec<DocMetadata>) -> DocMetadata {
     })
 }
 
+fn nested_metadata() -> DocMetadata {
+    doc(DocSpec {
+        app_name: "nested-app",
+        bin_name: Some("fixture"),
+        about_id: "root.about",
+        fields: vec![string_cli_field("global", "global", None, true)],
+        subcommands: vec![version_metadata(), admin_metadata(), greet_metadata()],
+    })
+}
+
+fn version_metadata() -> DocMetadata {
+    leaf_metadata("version", "cmd.version", Vec::new())
+}
+
+fn admin_metadata() -> DocMetadata {
+    doc(DocSpec {
+        app_name: "admin",
+        bin_name: None,
+        about_id: "cmd.admin",
+        fields: vec![string_cli_field(
+            "scope",
+            "scope",
+            Some("String :: from(\"local\")"),
+            false,
+        )],
+        subcommands: vec![
+            leaf_metadata(
+                "grant-access",
+                "cmd.admin.grant-access",
+                vec![string_cli_field("principal", "principal", None, true)],
+            ),
+            leaf_metadata(
+                "audit",
+                "cmd.admin.audit",
+                vec![bool_cli_field("dry_run", "dry-run")],
+            ),
+        ],
+    })
+}
+
+fn greet_metadata() -> DocMetadata {
+    leaf_metadata(
+        "greet",
+        "cmd.greet",
+        vec![
+            string_cli_field(
+                "recipient",
+                "recipient",
+                Some("String :: from(\"World\")"),
+                false,
+            ),
+            bool_cli_field("excited", "excited"),
+        ],
+    )
+}
+
+fn leaf_metadata(
+    app_name: &'static str,
+    about_id: &'static str,
+    fields: Vec<FieldMetadata>,
+) -> DocMetadata {
+    doc(DocSpec {
+        app_name,
+        bin_name: None,
+        about_id,
+        fields,
+        subcommands: Vec::new(),
+    })
+}
+
 fn assert_visible_inputs(command: &ortho_config::AgentCommand) {
     let inputs: Vec<_> = command.inputs.iter().map(input_summary).collect();
 
@@ -249,6 +367,77 @@ fn input_summary(
     )
 }
 
+type NestedInputSummary = (String, Option<String>, Option<String>);
+type NestedCommandSummary = (Vec<String>, Vec<NestedInputSummary>, Option<String>);
+
+fn nested_command_summary(command: &ortho_config::AgentCommand) -> NestedCommandSummary {
+    (
+        command.path.clone(),
+        command
+            .inputs
+            .iter()
+            .map(|input| {
+                (
+                    input.name.clone(),
+                    input.long.clone(),
+                    input.default.clone(),
+                )
+            })
+            .collect(),
+        command.canonical_verb.clone(),
+    )
+}
+
+fn expected_nested_command_summaries() -> Vec<NestedCommandSummary> {
+    vec![
+        (
+            vec!["fixture".to_owned()],
+            vec![("global".to_owned(), Some("global".to_owned()), None)],
+            None,
+        ),
+        (
+            vec!["fixture".to_owned(), "admin".to_owned()],
+            vec![(
+                "scope".to_owned(),
+                Some("scope".to_owned()),
+                Some("String::from(\"local\")".to_owned()),
+            )],
+            None,
+        ),
+        (
+            vec!["fixture".to_owned(), "admin".to_owned(), "audit".to_owned()],
+            vec![("dry_run".to_owned(), Some("dry-run".to_owned()), None)],
+            None,
+        ),
+        (
+            vec![
+                "fixture".to_owned(),
+                "admin".to_owned(),
+                "grant-access".to_owned(),
+            ],
+            vec![("principal".to_owned(), Some("principal".to_owned()), None)],
+            None,
+        ),
+        (
+            vec!["fixture".to_owned(), "greet".to_owned()],
+            vec![
+                ("excited".to_owned(), Some("excited".to_owned()), None),
+                (
+                    "recipient".to_owned(),
+                    Some("recipient".to_owned()),
+                    Some("String::from(\"World\")".to_owned()),
+                ),
+            ],
+            None,
+        ),
+        (
+            vec!["fixture".to_owned(), "version".to_owned()],
+            Vec::new(),
+            None,
+        ),
+    ]
+}
+
 struct DocSpec {
     app_name: &'static str,
     bin_name: Option<&'static str>,
@@ -331,6 +520,37 @@ fn cli_field(spec: FieldSpec<'_>) -> FieldMetadata {
     cli_field_with_possible_values(spec, [])
 }
 
+fn string_cli_field(
+    name: &'static str,
+    long: &'static str,
+    default: Option<&'static str>,
+    required: bool,
+) -> FieldMetadata {
+    cli_field(FieldSpec {
+        name,
+        long: Some(long),
+        short: None,
+        takes_value: true,
+        hide_in_help: false,
+        value: Some(ValueType::String),
+        default,
+        required,
+    })
+}
+
+fn bool_cli_field(name: &'static str, long: &'static str) -> FieldMetadata {
+    cli_field(FieldSpec {
+        name,
+        long: Some(long),
+        short: None,
+        takes_value: false,
+        hide_in_help: false,
+        value: Some(ValueType::Bool),
+        default: None,
+        required: false,
+    })
+}
+
 fn cli_field_with_possible_values<const N: usize>(
     spec: FieldSpec<'_>,
     possible_values: [&str; N],

cargo-orthohelp/src/cli.rs

@@ -21,7 +21,7 @@ pub enum OutputFormat {
     Man,
     /// Emit `PowerShell` help output.
     Ps,
-    /// Emit all outputs (IR, man pages, and `PowerShell` help).
+    /// Emit all outputs (IR, man pages, `PowerShell` help, and agent-context).
     All,
     /// Emit compact agent-context JSON output.
     AgentContext,

cargo-orthohelp/src/main.rs

@@ -151,7 +151,7 @@ fn generate_agent_context_if_requested(
     doc_metadata: &DocMetadata,
     out_dir: &Utf8PathBuf,
 ) -> Result<(), OrthohelpError> {
-    if !matches!(args.format, OutputFormat::AgentContext) {
+    if !matches!(args.format, OutputFormat::AgentContext | OutputFormat::All) {
         tracing::debug!(
             package = %selection.package_name,
             format = ?args.format,

cargo-orthohelp/tests/features/orthohelp_agent_context.feature

@@ -5,3 +5,9 @@ Feature: cargo-orthohelp agent-context generation
     And the orthohelp cache is empty
     When I run cargo-orthohelp with format agent-context for the fixture
     Then the output contains agent-context JSON for the fixture
+
+  Scenario: Generate nested agent-context JSON from the fixture
+    Given a temporary output directory
+    And the orthohelp cache is empty
+    When I run cargo-orthohelp with format agent-context for the nested fixture
+    Then the output contains nested agent-context command paths for the fixture

cargo-orthohelp/tests/features/orthohelp_roff.feature

@@ -30,3 +30,4 @@ Feature: cargo-orthohelp roff man page generation
     Then the output contains localized IR JSON for en-US
     And the output contains a man page for fixture
     And the output contains a PowerShell module named FixtureHelp
+    And the output contains agent-context JSON for the fixture

cargo-orthohelp/tests/golden/agent_context__fixture.json.snap

@@ -1,5 +1,6 @@
 ---
 source: cargo-orthohelp/tests/golden/agent_context_tests.rs
+assertion_line: 30
 expression: snapshot
 ---
 {
@@ -27,7 +28,7 @@ expression: snapshot
           "long": "host",
           "value_type": "string",
           "required": false,
-          "default": "String :: from(\"localhost\")",
+          "default": "String::from(\"localhost\")",
           "enum_values": []
         },
         {
@@ -51,7 +52,7 @@ expression: snapshot
           "long": "log-level",
           "value_type": "enum",
           "required": false,
-          "default": "LogLevel :: Info",
+          "default": "LogLevel::Info",
           "enum_values": [
             "Debug",
             "Info",