[cueadmin] Add lock-state filter and idle sort to host list

[ramonfigueiredo]

Related Issues

• [cueadmin] Add lock-state filter and idle sort to cueadmin -lh for identifying idle hosts #2481

Summarize your change.

[cueadmin] Add lock-state filter and idle sort to host list

Add two options to cueadmin -lh to help surface idle hosts:

• -lock-state {OPEN,LOCKED,NIMBY_LOCKED} filters the host list to a single lock state (e.g. NIMBY_LOCKED).
• -sort-idle sorts the output by most idle resources first (idle cores, then idle memory) instead of by host name.

Filtering and sorting are applied client-side in displayHosts(), so no gRPC or backend changes are required. Existing default behavior (sort by name, no filter) is unchanged.

[docs/cueadmin] Document -lock-state and -sort-idle host list options

Document the two new cueadmin -lh options for surfacing idle hosts:

• -lock-state {OPEN,LOCKED,NIMBY_LOCKED} filters the host list to a single lock state.
• -sort-idle sorts the output by most idle resources first.

Updates the cueadmin command and tools reference, the cueadmin tutorial, the desktop rendering control guide, and the cueadmin README, noting that NIMBY_LOCKED indicates an active user and that -lh reports current state only (poll over time to track idle duration).

[coderabbitai]

📝 Walkthrough

Walkthrough

Added -lock-state and -sort-idle host-listing options to cueadmin, passed them through host retrieval and rendering, and updated the related reference docs, tutorial, and README examples.

Changes

Host lock-state filter and idle sort

Layer / File(s)	Summary
CLI options and getHosts call cueadmin/cueadmin/common.py	Adds -lock-state (OPEN, LOCKED, NIMBY_LOCKED) and -sort-idle parser options, and passes lock_state/sort_idle through to opencue.api.getHosts(...) in the -lh path.
displayHosts filtering and sorting cueadmin/cueadmin/output.py	displayHosts accepts lock_state and sort_idle, filters hosts by lock state, sorts by idle cores/memory or by name, and iterates the processed host list directly.
Reference and tutorial updates cueadmin/README.md, docs/_docs/other-guides/desktop-rendering-control.md, docs/_docs/reference/commands/cueadmin.md, docs/_docs/reference/tools/cueadmin.md, docs/_docs/tutorials/cueadmin-tutorial.md	Examples and reference text are expanded to show -lock-state and -sort-idle usage, explain the allowed lock-state values, and document the idle-sorting behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant cueadmin_common
  participant opencue_api
  participant cueadmin_output

  User->>cueadmin_common: cueadmin -lh -lock-state LOCKED -sort-idle
  cueadmin_common->>opencue_api: getHosts(match, state, alloc, lock_state, sort_idle)
  opencue_api-->>cueadmin_common: hosts list
  cueadmin_common->>cueadmin_output: displayHosts(hosts, lock_state, sort_idle)
  cueadmin_output->>cueadmin_output: filter by lock_state
  cueadmin_output->>cueadmin_output: sort by idle resources or name
  cueadmin_output-->>User: printed host list

Loading

Suggested reviewers: lithorus, DiegoTavares

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding lock-state filtering and idle-based sorting to the host list.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[ramonfigueiredo]

@DiegoTavares / @lithorus
Ready for review!