Add class field discovery for computed selectors (#77)

## Summary

- Make `class fields --name <class>` the canonical field-inventory command.
- Include enabled shared and personal computed selectors with source, observed count, types, and examples.
- Retain `object fields --class <class>` as a deprecated compatibility alias that prints an exact, argument-preserving replacement.
- Add reusable command-deprecation metadata for future command-path and option migrations.

## Rationale and design decisions

Field discovery belongs to the class being described, so the canonical command moves under `class`. The shipped `object fields` spelling remains registered to avoid an abrupt command removal.

Deprecation behavior lives in the shared command builder rather than the individual field handler. A deprecated command declares its replacement path and option renames; the common runner then annotates help and emits a shell-safe replacement that preserves scoped invocations, options, positionals, pipelines, and the `--` boundary.

Computed definitions remain visible when enabled even if no sampled object produces a value. Counts, types, and examples are observation-based, while computed evaluation errors do not hide the definition row.

## Behavior notes

`class fields --name <class>` samples the class data paths and lists enabled shared selectors as `S:<key>` and enabled personal selectors as `P:<key>`. A `Source` column distinguishes data, shared-computed, and personal-computed rows.

The deprecated alias emits an exact replacement such as `class fields --name Hosts`, including rewritten `--class` or `-c` arguments and any trailing pipeline.

## User and compatibility impact

Existing field-inventory output has a breaking output-shape change: it gains a `Source` column and computed-selector rows. Structured consumers that validate the exact legacy column set or assume every row is a `data.*` path must accept the new column and either handle or filter the `S:` and `P:` rows.

No command is removed: `object fields --class <class>` continues to work. Users should migrate to `class fields --name <class>` using the exact replacement printed by the deprecation warning. There are no other breaking changes.

## Declared compatibility surface

The declared Hubuum server target remains 0.0.9, and `COMPATIBILITY.md` is unchanged. The OpenAPI surface and all request and response types are unchanged; the implementation composes existing typed gateway operations for computed definitions and computed object values.

Feature availability is unchanged, no MSRV is declared or changed, and dependencies and `Cargo.lock` are unchanged. The root manifest retains its exact `hubuum_client` 0.9.1 pin. No public workspace-crate API changes, so no Rust library semver migration is required.

This change makes no new cross-version server compatibility claim. The existing declared target remains backed by the immutable Hubuum v0.0.9 image recorded in `COMPATIBILITY.md` (`sha256:1f12baf882b6d3df5b4b2dbdf26aad0793274e57f86a2c186b8e1e68632db5db`).

## Changelog

`CHANGELOG.md` documents the canonical command, compatibility alias, exact migration, reusable warning behavior, computed-selector inventory, and breaking output-shape change under `[Unreleased]`.

Author: terjekv

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+- Added canonical `class fields --name <class>` field discovery, with
+  `object fields --class <class>` retained as a deprecated compatibility alias
+  that prints an exact replacement command. Existing invocations continue to
+  work; users should migrate to `class fields --name <class>`. Reusable command
+  deprecation metadata now annotates help and rewrites renamed options in
+  warnings. The inventory includes enabled shared and personal computed
+  selectors alongside sampled `data.*` paths, identifies each field's source,
+  and summarizes computed values observed in the same object sample. This is a
+  breaking output-shape change: the inventory gains a `Source` column and
+  computed-selector rows. Structured consumers that assumed an exact column set
+  or data-only rows must accept the new column and rows.
 - Added extension packs under `extension <pack>`, with dependency-free portable
   JSONC/JQ workflow packs as the preferred kind and a versioned argv/JSON
   protocol for explicitly executable packs. Packs have deterministic system and

README.md

@@ -236,11 +236,20 @@ hubuum-cli object list --class Hosts --computed all --output json
 
 In the REPL, data-field completion merges the selected class's JSON Schema with
 a sample of up to 100 objects, using the same depth-six traversal as
-`object fields`. This supplies escaped JSON Pointers for computed `--path`
+`class fields`. This supplies escaped JSON Pointers for computed `--path`
 options and dotted paths for aggregate dimensions, measures, and filters.
 Inspected fields are cached for `cache.time` seconds (one hour by default) and
 the cache can be bypassed with `cache.disable`.
 
+`class fields --name <class>` is also the field inventory for downstream
+selectors. Alongside sampled `data.*` paths, it lists enabled shared and
+personal computed fields as `S:<key>` and `P:<key>`. The `Source` column
+distinguishes the three kinds; counts, types, and examples are observed from the
+same object sample, so a computed definition with no sampled value still
+appears with an empty observation. The former `object fields --class <class>`
+spelling remains available as a deprecated compatibility alias and prints an
+exact replacement command when invoked.
+
 Without per-class configuration, computed values are off by default. Use repeatable, dynamically completed
 `--computed S:<key>` and `--computed P:<key>` options to select individual
 shared or personal fields, or `--computed all` to select every field:

docs/manual-test.md

@@ -73,7 +73,7 @@ object modify --class SmokeHost smoke-1 --description "Smoke object updated" --d
 object data patch --class SmokeHost --name smoke-1 --patch '[{"op":"add","path":"/facts","value":{"distribution":"RHEL","rhel_subscription":"active"}}]'
 object data patch --class SmokeHost --name smoke-1 --patch '[{"op":"add","path":"/facts","value":{"distribution":"Fedora"}}]'
 object data patch --class SmokeHost --name smoke-created --patch '[{"op":"add","path":"/facts","value":{"distribution":"Fedora"}}]' --create --description "Created by CLI smoke test"
-object fields --class SmokeHost
+class fields --name SmokeHost
 ```
 
 Run server-side object aggregates, including grouping, global numeric measures,
@@ -95,6 +95,7 @@ computed shared preview --class SmokeHost --key owner_copy --label "Owner copy"
 computed shared rebuild --class SmokeHost
 computed personal create --class SmokeHost --key owner_personal --label "Personal owner" --operation first_non_null --path /owner --result-type string
 computed personal list --class SmokeHost
+class fields --name SmokeHost
 object aggregate --class SmokeHost --group-by S:owner_copy --where S:owner_copy equals platform --output json
 object show --class SmokeHost smoke-1 --computed S:owner_copy
 object list --class SmokeHost --computed all --output json
@@ -160,6 +161,11 @@ Expected results:
   explicit `--computed` values replace them and `--computed none` suppresses them.
 - Computed list text uses `S:<key>` and `P:<key>` columns rather than a single
   truncated computed-data preview.
+- `class fields` includes enabled `S:<key>` and `P:<key>` selectors after the
+  sampled `data.*` paths, identifies their source, and reports values observed
+  in the same sample. `object fields --class SmokeHost` produces the same
+  inventory as a compatibility alias and warns to use the exact replacement
+  `class fields --name SmokeHost` command.
 - `S:<key>` and `P:<key>` sorts order the full matching set before `--limit`;
   combining either with `--cursor` returns an actionable error.
 - Display aliases use the first selector that exists and can be selected like

src/catalog.rs

@@ -1348,6 +1348,46 @@ mod tests {
         );
     }
 
+    #[test]
+    fn class_fields_is_canonical_and_object_fields_remains_compatible() {
+        let catalog = build_command_catalog();
+        let class_fields = catalog
+            .resolve_command(&[], &["class".to_string(), "fields".to_string()])
+            .expect("class fields command");
+        let object_fields = catalog
+            .resolve_command(&[], &["object".to_string(), "fields".to_string()])
+            .expect("object fields compatibility command");
+
+        assert_eq!(
+            class_fields.command.workflow_contract().command_id(),
+            "class fields"
+        );
+        assert!(class_fields
+            .command
+            .workflow_contract()
+            .input("name")
+            .is_some());
+        assert_eq!(
+            object_fields.command.workflow_contract().command_id(),
+            "object fields"
+        );
+        assert!(object_fields
+            .command
+            .workflow_contract()
+            .input("class")
+            .is_some());
+        assert!(object_fields
+            .command
+            .about
+            .as_deref()
+            .is_some_and(|about| about.ends_with("(deprecated)")));
+        assert!(object_fields
+            .command
+            .long_about
+            .as_deref()
+            .is_some_and(|about| about.contains("use 'class fields' instead")));
+    }
+
     #[test]
     fn render_command_help_includes_option_metadata() {
         let mut builder = CommandCatalogBuilder::new();
@@ -1472,9 +1512,13 @@ mod tests {
             .expect("collection scope");
 
         assert!(plain.contains("class"));
-        assert!(plain.contains("create, delete, list, modify, show"));
         assert!(plain.contains("object"));
-        assert!(plain.contains("create, delete, list, modify, show"));
+        assert_eq!(
+            plain
+                .matches("create, delete, fields, list, modify, show")
+                .count(),
+            2
+        );
         assert!(plain.contains("event"));
         assert!(plain.contains("delivery, sink, subscription"));
         assert!(!plain.contains("event-subscription"));

src/commands/builder.rs

@@ -7,13 +7,14 @@ use crate::catalog::{
     AsyncCommandHandler, CommandCatalog, CommandCatalogBuilder, CommandContext, CommandInvocation,
     CommandOutcome, CommandSpec, CompletionSpec, OptionSpec, ScopeAction,
 };
+use crate::command_line::shell_escape;
 use crate::commands::{self, command_options, render_format, table_headers, CliCommand};
 use crate::config::get_config;
 use crate::errors::AppError;
 use crate::extensions::{ExtensionRegistry, WorkflowProgram};
 use crate::output::{
-    reset_output, set_pipeline, set_pipeline_suffix, set_render_format, set_table_headers,
-    take_output,
+    add_warning, reset_output, set_pipeline, set_pipeline_suffix, set_render_format,
+    set_table_headers, take_output,
 };
 use crate::tokenizer::CommandTokenizer;
 
@@ -27,6 +28,88 @@ pub(crate) struct CommandDocs {
     pub examples: Option<&'static str>,
 }
 
+#[derive(Clone, Copy)]
+pub(crate) struct CommandDeprecation {
+    replacement_path: &'static [&'static str],
+    option_renames: &'static [(&'static str, &'static str)],
+}
+
+impl CommandDeprecation {
+    pub(crate) const fn renamed(
+        replacement_path: &'static [&'static str],
+        option_renames: &'static [(&'static str, &'static str)],
+    ) -> Self {
+        Self {
+            replacement_path,
+            option_renames,
+        }
+    }
+
+    fn replacement_command(
+        &self,
+        tokens: &CommandTokenizer,
+        command_index: usize,
+        pipeline_suffix: Option<&str>,
+    ) -> String {
+        let command = self
+            .replacement_path
+            .iter()
+            .map(|token| (*token).to_string())
+            .chain(
+                tokens
+                    .raw_tokens()
+                    .iter()
+                    .skip(command_index.saturating_add(1))
+                    .scan(false, |options_ended, token| {
+                        if token == "--" {
+                            *options_ended = true;
+                        }
+                        let token = if *options_ended {
+                            token.to_string()
+                        } else {
+                            self.rename_option(token)
+                        };
+                        Some(shell_escape(&token))
+                    }),
+            )
+            .collect::<Vec<_>>()
+            .join(" ");
+        match pipeline_suffix {
+            Some(suffix) => format!("{command} {suffix}"),
+            None => command,
+        }
+    }
+
+    fn rename_option(&self, token: &str) -> String {
+        for (old, new) in self.option_renames {
+            if token == *old {
+                return (*new).to_string();
+            }
+            if let Some(value) = token
+                .strip_prefix(old)
+                .and_then(|value| value.strip_prefix('='))
+            {
+                return format!("{new}={value}");
+            }
+        }
+        token.to_string()
+    }
+
+    fn help_notice(&self) -> String {
+        format!(
+            "Deprecated: use '{}' instead. Invocations print an exact replacement command.",
+            self.replacement_path.join(" ")
+        )
+    }
+
+    fn warning(&self, command_path: &[String], replacement: &str) -> String {
+        format!(
+            "Command '{}' is deprecated; use `{replacement}` instead.",
+            command_path.join(" ")
+        )
+    }
+}
+
 pub fn build_command_catalog() -> CommandCatalog {
     let mut builder = CommandCatalogBuilder::new();
     let mut extensions = ExtensionRegistry::discover(&get_config());
@@ -38,6 +121,7 @@ pub fn build_command_catalog() -> CommandCatalog {
     commands::auth::register_commands(&mut builder);
     commands::jobs::register_commands(&mut builder);
     commands::class::register_commands(&mut builder);
+    commands::class_fields::register_commands(&mut builder);
     commands::config::register_commands(&mut builder);
     commands::collection::register_commands(&mut builder);
     commands::computed::register_commands(&mut builder);
@@ -72,6 +156,30 @@ pub fn build_command_catalog() -> CommandCatalog {
 }
 
 pub(crate) fn catalog_command<C>(name: &str, command: C, docs: CommandDocs) -> CommandSpec
+where
+    C: CliCommand + Clone + 'static,
+{
+    catalog_command_with_deprecation(name, command, docs, None)
+}
+
+pub(crate) fn deprecated_catalog_command<C>(
+    name: &str,
+    command: C,
+    docs: CommandDocs,
+    deprecation: CommandDeprecation,
+) -> CommandSpec
+where
+    C: CliCommand + Clone + 'static,
+{
+    catalog_command_with_deprecation(name, command, docs, Some(deprecation))
+}
+
+fn catalog_command_with_deprecation<C>(
+    name: &str,
+    command: C,
+    docs: CommandDocs,
+    deprecation: Option<CommandDeprecation>,
+) -> CommandSpec
 where
     C: CliCommand + Clone + 'static,
 {
@@ -104,10 +212,21 @@ where
         C::EFFECTS,
         Arc::new(CommandHandler {
             command: Arc::new(command),
+            deprecation,
         }) as Arc<dyn AsyncCommandHandler>,
     );
-    spec.about = docs.about.map(str::to_string);
-    spec.long_about = docs.long_about.map(str::to_string);
+    spec.about = docs.about.map(|about| match deprecation {
+        Some(_) => format!("{about} (deprecated)"),
+        None => about.to_string(),
+    });
+    spec.long_about = match (docs.long_about, deprecation) {
+        (Some(long_about), Some(deprecation)) => {
+            Some(format!("{long_about}\n\n{}", deprecation.help_notice()))
+        }
+        (Some(long_about), None) => Some(long_about.to_string()),
+        (None, Some(deprecation)) => Some(deprecation.help_notice()),
+        (None, None) => None,
+    };
     spec.examples = docs.examples.map(str::to_string);
     spec
 }
@@ -117,6 +236,7 @@ where
     C: CliCommand + Clone + 'static,
 {
     command: Arc<C>,
+    deprecation: Option<CommandDeprecation>,
 }
 
 #[async_trait]
@@ -137,6 +257,7 @@ where
         })?;
         let raw_line = invocation.raw_line.clone();
         let pipeline = invocation.pipeline.clone();
+        let deprecation = self.deprecation;
 
         spawn_blocking(move || {
             reset_output()?;
@@ -147,6 +268,14 @@ where
                 invocation.command_index,
                 &command_options::<C>(),
             )?;
+            if let Some(deprecation) = deprecation {
+                let replacement = deprecation.replacement_command(
+                    &tokens,
+                    invocation.command_index,
+                    invocation.pipeline_suffix.as_deref(),
+                );
+                add_warning(deprecation.warning(&invocation.command_path, &replacement))?;
+            }
             set_render_format(render_format(&tokens)?)?;
             set_table_headers(table_headers(&tokens)?)?;
 
@@ -163,3 +292,57 @@ where
         .map_err(|err| AppError::CommandExecutionError(err.to_string()))?
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::CommandDeprecation;
+    use crate::tokenizer::CommandTokenizer;
+
+    const RENAMED_FIELDS: CommandDeprecation = CommandDeprecation::renamed(
+        &["class", "fields"],
+        &[("--class", "--name"), ("-c", "--name")],
+    );
+
+    #[test]
+    fn command_deprecation_builds_an_exact_replacement() {
+        let tokens = CommandTokenizer::new(
+            "object fields --class 'Host Group' --limit 10 --containers",
+            "fields",
+            &[],
+        )
+        .expect("deprecated command should tokenize");
+
+        let replacement = RENAMED_FIELDS.replacement_command(&tokens, 1, None);
+
+        assert_eq!(
+            replacement,
+            "class fields --name 'Host Group' --limit 10 --containers"
+        );
+        assert_eq!(
+            RENAMED_FIELDS.warning(&["object".to_string(), "fields".to_string()], &replacement),
+            "Command 'object fields' is deprecated; use `class fields --name 'Host Group' --limit 10 --containers` instead."
+        );
+    }
+
+    #[test]
+    fn command_deprecation_replaces_scoped_invocations_and_short_options() {
+        let tokens = CommandTokenizer::new("fields -c Hosts --depth 4", "fields", &[])
+            .expect("scoped deprecated command should tokenize");
+
+        assert_eq!(
+            RENAMED_FIELDS.replacement_command(&tokens, 0, Some("| P Field Source")),
+            "class fields --name Hosts --depth 4 | P Field Source"
+        );
+    }
+
+    #[test]
+    fn command_deprecation_does_not_rewrite_positionals_after_double_dash() {
+        let tokens = CommandTokenizer::new("fields -c Hosts -- --class", "fields", &[])
+            .expect("double-dash command should tokenize");
+
+        assert_eq!(
+            RENAMED_FIELDS.replacement_command(&tokens, 0, None),
+            "class fields --name Hosts -- --class"
+        );
+    }
+}