Merge pull request openSUSE#325 from mimi1vx/docu_refresh2

docs: align README, config reference, and FAQ with current tool

Author: mimi1vx

Documentation/cfg.rst

@@ -268,6 +268,128 @@ Used e.g. in lock files.
 .. __: https://docs.python.org/2/library/getpass.html#getpass.getuser
 
 
+``mcp.max_output_bytes``
+~~~~~~~~~~~~~~~~~~~~~~~~
+  | **type**
+  |     int (bytes)
+  | **default**
+  |     100000
+
+Caps the size of a single ``mtui-mcp`` tool result. Output beyond the cap
+is truncated with a one-line notice pointing at the ``offset``/``limit``
+paging on the testreport read tools. A value of ``0`` disables the cap.
+Ignored outside the MCP server. See :doc:`mcp`.
+
+
+``mcp.session_cap``
+~~~~~~~~~~~~~~~~~~~
+  | **type**
+  |     int
+  | **default**
+  |     32
+
+Maximum number of concurrent client sessions the ``mtui-mcp`` ``http``
+transport will create; a tool call that would exceed the cap fails with a
+clear error instead of spawning unbounded SSH connections and worker
+threads. Must be a positive integer. Ignored under the ``stdio``
+transport. See :doc:`mcp`.
+
+
+``mcp.session_idle_timeout``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  | **type**
+  |     int (seconds)
+  | **default**
+  |     1800
+
+Seconds of inactivity after which an idle ``mtui-mcp`` ``http`` session is
+swept and its hosts disconnected. Because the MCP SDK provides no
+per-session teardown callback, this sweep is what releases the SSH
+connections of a client that simply disconnected. Must be a positive
+integer; set to ``0`` to disable reaping. Ignored under the ``stdio``
+transport. See :doc:`mcp`.
+
+
+``mcp.tool_profile``
+~~~~~~~~~~~~~~~~~~~~
+  | **type**
+  |     enum: ``full``, ``core``
+  | **default**
+  |     ``full``
+
+Selects which synthesised tools the ``mtui-mcp`` server exposes.
+``full`` keeps every command tool. ``core`` exposes only the curated
+everyday subset (load/inspect/run/install, report editing, approve/reject,
+the ``testreport_*`` and ``job_*`` tools), roughly halving the per-request
+tool-list payload the model must carry. Fine-tune either profile with
+``mcp.tools_allow`` and ``mcp.tools_deny``. See :doc:`mcp`.
+
+
+``mcp.tools_allow``
+~~~~~~~~~~~~~~~~~~~
+  | **type**
+  |     list: comma-separated tool names
+  | **default**
+  |     (empty)
+
+Tool names added back on top of the selected ``mcp.tool_profile``. Applied
+before ``mcp.tools_deny``. See :doc:`mcp`.
+
+
+``mcp.tools_deny``
+~~~~~~~~~~~~~~~~~~
+  | **type**
+  |     list: comma-separated tool names
+  | **default**
+  |     (empty)
+
+Tool names removed from the exposed set last, after the profile and
+``mcp.tools_allow`` have been applied (deny always wins). See :doc:`mcp`.
+
+
+``obs.api_url``
+~~~~~~~~~~~~~~~
+  | **type**
+  |     URL
+  | **default**
+  |     ``https://api.suse.de``
+
+OBS/IBS API that mtui acts against for native ``SUSE:Maintenance`` and
+Product Increment review actions (``assign``, ``unassign``, ``approve``,
+``reject``, ``comment``). No credentials live here: the acting user and
+the SSH signing key are read from the user's ``~/.oscrc`` (see
+``obs.conffile``), and this value must match a section header in that
+oscrc. OBS TLS verification is governed by ``mtui.ssl_verify``, not by
+oscrc's own TLS options.
+
+Must be an ``http://`` or ``https://`` URL with a host (an explicit
+port must be numeric); an invalid value is rejected when the
+configuration is read and the default is used instead.
+
+
+``obs.conffile``
+~~~~~~~~~~~~~~~~
+  | **type**
+  |     pathname
+  | **default**
+  |     (empty; ``~/.oscrc``)
+
+Path to the oscrc from which the native OBS backend reads the acting user
+and SSH ``sshkey``. An empty value (the default) uses ``~/.oscrc``.
+
+
+``obs.request_timeout``
+~~~~~~~~~~~~~~~~~~~~~~~
+  | **type**
+  |     int (seconds)
+  | **default**
+  |     180
+
+Coarse wall-clock budget checked **between** the individual HTTP calls a
+native OBS operation makes; each call is itself bounded by the shared HTTP
+timeout. This is not a mid-call hard kill. Must be a positive integer.
+
+
 ``openqa.baremetal``
 ~~~~~~~~~~~~~~~~~~~~
   | **type**
@@ -478,6 +600,18 @@ Example
   template_dir = /path/to/where/you/want/to/store/test-reports
   
 
+  [obs]
+  api_url = https://api.suse.de
+  request_timeout = 180
+  
+
+  [mcp]
+  session_cap = 32
+  session_idle_timeout = 1800
+  tool_profile = full
+  max_output_bytes = 100000
+  
+
   [openqa]
   openqa = https://openqa.suse.de
   

Documentation/faq.rst

@@ -36,17 +36,51 @@ Example:
 
 .. code-block:: sh
 
-  # EDITOR=nano mtui -r SUSE:Maintenance:3601:126030
+  # EDITOR=nano mtui -a SUSE:Maintenance:3601:126030
 
 Is there a way to easily distinguish among different updates?
 =============================================================
 
 When you are testing different updates at the same time, you can load several
-test reports into a single MTUI session as templates and switch between them.
-The bottom toolbar shows the active template's RRID together with the total
-number of loaded templates, so the prompt stays unambiguous. See
-`load_template`, `switch`, and `list_templates` in the interactive commands
-reference.
+test reports into a single MTUI session as templates. Each ``load_template``
+adds another RRID to the session; ``list_templates`` shows the loaded set,
+``switch`` changes the active one, and ``unload`` drops one (closing only its
+host connections). The bottom toolbar shows the active template's RRID together
+with the total number of loaded templates, so the prompt stays unambiguous.
+
+Action commands fan out across every loaded template by default, each acting on
+that template's own hosts (or report), with each template's output prefixed by
+an ``=== <RRID> ===`` banner. Scope a single command to one template with
+``-T RRID``/``--template RRID``, or force fan-out explicitly with
+``--all-templates``. See `load_template`, `list_templates`, `switch`, and
+`unload` in the interactive commands reference.
+
+Example::
+
+  mtui> load_template -a SUSE:Maintenance:3601:126030
+  mtui> load_template -a SUSE:Maintenance:3602:126040
+  mtui> list_templates
+  * SUSE:Maintenance:3602:126040  hosts: 2  workflow: manual
+    SUSE:Maintenance:3601:126030  hosts: 3  workflow: manual
+  mtui> switch SUSE:Maintenance:3601:126030
+
+Which update should I pick up next?
+===================================
+
+The ``updates`` command lists the update queue live from the TeReGen API,
+sorted by priority. By default it shows the actionable pickup queue:
+**unassigned** updates that are **in testing**, so you can grab the next one
+without wading through released entries. Each row shows priority, status, kind,
+deadline and the RRID.
+
+Pass ``--status all`` for the full queue (every status and assignee), or use
+the assignment filters ``--mine`` (updates assigned to you), ``--assignee
+<user>``, or ``--all-assignees``. Restrict to a review group with
+``--review-group`` and cap the row count with ``--limit``.
+
+Example::
+
+  mtui> updates --review-group qam-sle --limit 5
 
 Can I run MTUI without loading a test report?
 =============================================
@@ -306,6 +340,23 @@ Example::
   info: connecting to craig.qam.suse.cz
 
 
+How can I search the reference-host inventory without connecting?
+=================================================================
+
+The ``list_refhosts`` command queries the same inventory ``add_host``
+resolves through, but reads it offline: it makes no SSH connection, takes no
+lock, and needs no loaded test report. Filter by hostname glob (``--name``),
+arch (``--arch``), base product (``--product``), version (``--version``),
+addon (``--addon``), or a full testplatform query (``--testplatform``). Add
+``--free`` to additionally probe each matched host's live lock state (the only
+part that goes on the wire), ``--pool`` to group by test-target slot, or
+``--json`` for structured output.
+
+Example::
+
+  mtui> list_refhosts --product sles --version 15-SP6 --arch x86_64
+
+
 How can I override refhosts mentioned in the test report?
 =========================================================
 
@@ -316,12 +367,12 @@ machines, the host list could be overwritten with the ``-s`` option.
 
 Example::
 
-  # mtui -s edna.qam.suse.cz,moe.qam.suse.cz -r SUSE:Maintenance:3601:126030
+  # mtui -s edna.qam.suse.cz,moe.qam.suse.cz -a SUSE:Maintenance:3601:126030
   info: connecting to edna.qam.suse.cz
   info: connecting to moe.qam.suse.cz
   mtui> list_hosts
-  edna.qam.suse.cz     (sle12None)             : Enabled (parallel)
-  moe.qam.suse.cz      (sle12None)             : Enabled (parallel)
+  edna.qam.suse.cz     (sles12_module-x86_64): Enabled (parallel)
+  moe.qam.suse.cz      (sles12_module-x86_64): Enabled (parallel)
   mtui>
 
 Can I run commands only on a subset of the host list?
@@ -371,59 +422,6 @@ Example::
   mtui> unlock -f
 
 
-Tests
-#####
-
-Can I run a QA ctcs2 testsuite within MTUI?
-===========================================
-
-The ``testsuite_*`` commands offer several options to run testsuites
-and manage the submission to QADB.
-
-Examples
-~~~~~~~~
-
-List available testsuites on a refhost::
-
-  mtui> testsuite_list -t kenny.qam.suse.cz
-  testsuites on kenny.qam.suse.cz (sles12sp2_module-x86_64):
-  test_gzip-run
-  test_php-run
-  test_tiff-run
-
-
-Run a specific testsuite::
-
-  mtui> testsuite_run -t moe.qam.suse.cz test_bzip2-run
-  moe.qam.suse.cz:~> test_bzip2-testsuite [0]
-  INFO: Variable TESTS_LOGDIR is set, logs will be stored in /var/log/qa/SUSE:Maintenance:3601:126030/ctcs2.
-  Initializing test run for control file qa_bzip2.tcf...
-  Current time: Thu Apr 20 11:26:02 CEST 2017
-  **** Test in progress ****
-  qa_bzip2_validation ... ... PASSED (2s)
-  qa_bzip2_bigfilerun ... ... PASSED (3s)
-  qa_bzip2_bznew ... ... PASSED (1s)
-  qa_bzip2_compile ... ... PASSED (1s)
-  **** Test run complete ****
-  Current time: Thu Apr 20 11:26:09 CEST 2017
-  Exiting test run..
-  Displaying report...
-  Total test time: 7s
-  Tests passed:
-  qa_bzip2_bigfilerun qa_bzip2_bznew qa_bzip2_compile qa_bzip2_validation
-  **** Test run completed successfully ****
-
-  info: done
-
-
-Submit the testsuite results to QADB2::
-
-  mtui> testsuite_submit -t moe.qam.suse.cz test_bzip2-run
-  info: Submiting results of test_bzip2-run from moe.qam.suse.cz
-  info: submission for moe.qam.suse.cz (sles12_module-x86_64): http://qadb2.suse.de/qadb/submission.php?submission_id=494079
-  info: done
-
-
 Where are stored installation logs from refhosts?
 =================================================
 

README.md

@@ -10,16 +10,18 @@ In addition, MTUI provides convenience commands to help with maintenance update
 
 ## Features
 
-- Parallel SSH command execution across SUSE reference hosts (`run`, `prepare`, `update`, `install`, `downgrade`, …) with per-host `enabled` / `disabled` / `dryrun` states and `parallel` / `serial` execution modes.
-- OBS / IBS maintenance-request workflow: `assign`, `unassign`, `approve`, `reject`, `comment`, each dispatched to either `osc` or Gitea depending on the request kind. `approve -r REVIEWER` records the reviewer in the testreport and commits to SVN in one step.
-- openQA integration: `reload_openqa`, `set_workflow {auto,manual,kernel}`, and `openqa_overview` (port of `oqa-search`) which prints PASSED/FAILED/RUNNING per SLE version, aggregated-update builds, and parsed build-check summaries, with `--export` to inject the block into the testreport's `regression tests:` section.
-- Reference-host lock management: cooperative `/var/lock/mtui.lock` files, automatic locking of every connected host while a Product Increment is under test (`[lock] pi_autolock`), and automatic reaping of stale locks left over from crashed sessions (`[lock] reap_stale`, `[lock] stale_age`).
+- Parallel SSH command execution across SUSE reference hosts (`run`, `prepare`, `update`, `install`, `uninstall`, `downgrade`, `reboot`, …) with per-host `enabled` / `disabled` / `dryrun` states and `parallel` / `serial` execution modes.
+- OBS / IBS maintenance-request workflow: `assign`, `unassign`, `approve`, `reject`, `comment`, dispatched to the native OBS/IBS API for `SUSE:Maintenance` and Product Increment requests (no `osc` subprocess; credentials and the SSH signing key are read from `~/.oscrc`) or to Gitea for SLFO / SL-Micro requests. `approve -r REVIEWER` records the reviewer in the testreport and commits to SVN in one step.
+- Update-queue and template workflow: `updates` lists the actionable pickup queue (unassigned updates in testing) from the TeReGen API sorted by priority, `checkers` shows the build-check result runs for the loaded update, and `regenerate` rebuilds a loaded update's test-report template via TeReGen and reloads it in place.
+- Multiple templates in one session: `load_template` adds each RRID to the session, `list_templates` / `switch` / `unload` manage the loaded set, and action commands fan out across every loaded template by default (scope a single one with `-T RRID` or force fan-out with `--all-templates`). Fan-out arbitrates a distinct free reference host per test-target slot from the shared pool so templates never collide on a host.
+- openQA integration: `reload_openqa`, `set_workflow {auto,manual,kernel}`, `openqa_overview` (port of `oqa-search`) which prints PASSED/FAILED/RUNNING per SLE version, aggregated-update builds, and parsed build-check summaries (with `--export` to inject the block into the testreport's `regression tests:` section), and `openqa_jobs` which lists the individual openQA jobs for the incident build so you can see which scenarios passed or failed.
+- Reference-host lock management: cooperative lock files, automatic locking of every connected host while a Product Increment is under test (`[lock] pi_autolock`), automatic reaping of stale locks left over from crashed sessions (`[lock] reap_stale`, `[lock] stale_age`), and independent host-pool claims (`list_locks -p`, `unlock -p`) that queue politely on an exhausted pool (`[lock] wait`, `[lock] wait_poll`).
 - Test-report lifecycle: `load_template`, `checkout`, `commit`, `edit`, `export`, with SVN and Gitea checkout backends.
-- Reference-host discovery: HTTPS- or filesystem-resolved `refhosts.yml` with location-aware fallback and configurable cache expiry, plus offline inventory search (`list_refhosts`) that filters the fleet by hostname glob, arch, product, version, addon, or testplatform query (and optionally probes live lock state) without connecting, locking, or loading a template.
-- File transfer: `put` (glob upload to all hosts) and `get` (download with per-host filename suffix or recursive folder mode).
-- Interactive `prompt_toolkit`-based shell: tab completion over the live command registry, persistent history with reverse-search (Ctrl-R), autosuggest-from-history (right-arrow to accept), lexer-highlighted command tokens, a bottom toolbar showing the loaded RRID, per-command `--help`, configurable log level, optional desktop notifications (`notify` extra), and OS-keyring credential storage (`keyring` extra).
+- Reference-host discovery: HTTPS- or filesystem-resolved `refhosts.yml` with a single merged host pool and configurable cache expiry, plus offline inventory search (`list_refhosts`) that filters the fleet by hostname glob, arch, product, version, addon, or testplatform query (and optionally probes live lock state) without connecting, locking, or loading a template.
+- File transfer: `put` (glob upload to all hosts, preserving directory trees) and `get` (download with per-host filename suffix or recursive folder mode).
+- Interactive `prompt_toolkit`-based shell: tab completion over the live command registry, persistent history with reverse-search (Ctrl-R), autosuggest-from-history (right-arrow to accept), lexer-highlighted command tokens, a bottom toolbar showing the loaded-template count and the active RRID, per-command `--help`, configurable log level, optional desktop notifications (`notify` extra), and OS-keyring credential storage (`keyring` extra).
 - Shell-completion script via the `completion` extra (`register-python-argcomplete mtui`).
-- MCP server (`mtui-mcp`, optional `mcp` extra): exposes every non-interactive mtui command as a [Model Context Protocol](https://modelcontextprotocol.io) tool, plus dedicated `testreport_read` / `testreport_patch` / `testreport_write` tools, so LLM clients can drive a headless mtui session over `stdio` or `http`.
+- MCP server (`mtui-mcp`, optional `mcp` extra): exposes every non-interactive mtui command as a [Model Context Protocol](https://modelcontextprotocol.io) tool, plus dedicated `testreport_read` / `testreport_patch` / `testreport_write` tools, so LLM clients can drive a headless mtui session over `stdio` or `http`. The HTTP transport isolates state per client, slow host commands can run as backgrounded jobs (`job_list` / `job_status` / `job_result` / `job_cancel`), and the exposed tool surface is tunable through the `[mcp]` config section.
 
 ## License