lr-lumentest-cli 0.5.1__tar.gz

lr_lumentest_cli-0.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LumenRadio AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lr_lumentest_cli-0.5.1/Makefile

@@ -0,0 +1,145 @@
+VENV := .venv
+PY   := $(VENV)/bin/python
+PIP  := $(VENV)/bin/pip
+
+# Resolve black config from the repo root (one directory up).
+# This avoids duplicating line-length / target-version between server and CLI.
+ROOT_DIR := $(abspath $(dir $(lastword $(MAKEFILE_LIST)))/..)
+
+# setuptools_scm version, resolved on the host from the installed _version.py.
+# Injected via SETUPTOOLS_SCM_PRETEND_VERSION_FOR_* so the sdist build skips the
+# VCS file-finder (which root=".." would otherwise use to pull in the whole
+# monorepo), and so in-container builds (no git / no repo-root mount) get it too.
+DIST_ENV := SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LR_LUMENTEST_CLI
+SCM_VERSION = $(shell $(PY) -c "import lumentest._version as v; print(v.version)" 2>/dev/null)
+
+# Only the sdist and wheel are valid PyPI distributions; dist/ also holds the
+# PyInstaller one-file binary and the linux-arm64/ build tree, so a bare
+# dist/* glob trips twine on files it was never meant to see.
+DIST_FILES := dist/*.whl dist/*.tar.gz
+
+PYPI_REPOSITORY ?= https://upload.pypi.org/legacy/
+TEST_PYPI_REPOSITORY ?= https://test.pypi.org/legacy/
+
+# The PyPI token lives in the releasing developer's shell, exported by hand
+# before running `publish`/`publish-test` — the same arrangement lr-gladiator
+# and lr-qrm use. No CI job holds it, so a release reaches PyPI only when a
+# person runs the target.
+#
+# setuptools_scm derives SCM_VERSION from the `lumentest-*` tag: any commit
+# past the tag carries a `.devN+g<sha>` suffix. PyPI rejects a local (`+…`)
+# segment outright, and a `.dev` upload permanently spends a version number
+# the index can never reuse — so both upload targets refuse anything but a
+# clean tag.
+CHECK_RELEASE_VERSION = case "$(SCM_VERSION)" in *dev*|*+*|"") echo "error: refusing to upload $(SCM_VERSION) — build from a clean 'lumentest-X.Y.Z' tag"; exit 2 ;; esac
+
+.DEFAULT_GOAL := install
+
+.PHONY: install dev test test-only format dist check publish publish-test shell clean package build-linux-docker build-linux-arm64-docker build-windows-docker
+
+$(VENV)/bin/activate:
+	python3.12 -m venv $(VENV)
+	$(PIP) install --upgrade pip
+
+install: $(VENV)/bin/activate
+	$(PIP) install .
+
+dev: $(VENV)/bin/activate
+	$(PIP) install -e ".[dev,package]"
+
+# `test` is the whole job: sync the venv, then run pytest. `test-only` is the
+# pytest half on its own, for a driver that has already done the `dev` pass and
+# wants to run several sub-trees at once -- the editable installs `dev` performs
+# write in-tree build artefacts, so they must not overlap; pytest runs may.
+test: dev test-only
+
+test-only:
+	$(VENV)/bin/pytest \
+		--cov=lumentest \
+		--cov-report=term-missing \
+		--cov-report=html:htmlcov \
+		--junit-xml=test-results.xml \
+		tests/
+
+format: dev
+	$(VENV)/bin/black --config $(ROOT_DIR)/pyproject.toml src/ tests/
+
+# Clearing the previous sdist and wheel is what keeps `$(DIST_FILES)` meaning
+# "this build": every artefact accumulates under its own version, and an upload
+# globbing the directory would carry a stale version along with the current one.
+# The PyInstaller binary and the arm64 tree in dist/ are left alone.
+dist: dev
+	rm -f dist/*.whl dist/*.tar.gz
+	$(DIST_ENV)="$(SCM_VERSION)" $(PY) -m build
+
+check: dist
+	$(VENV)/bin/twine check $(DIST_FILES)
+
+# Both upload targets pass credentials through TWINE_USERNAME/TWINE_PASSWORD,
+# which twine reads natively, and silence the upload line with `@`. `-u`/`-p`
+# would put the token in the echoed recipe line and in the upload process's
+# argv, where `ps` can read it — visible in a developer's scrollback and, since
+# this target also runs as a CI job, in a captured job log.
+publish-test: check
+	@$(CHECK_RELEASE_VERSION)
+	@if [ -z "$$TEST_PYPI_TOKEN" ]; then echo "error: TEST_PYPI_TOKEN is required — create one at https://test.pypi.org/manage/account/token/"; exit 2; fi
+	@TWINE_USERNAME=__token__ TWINE_PASSWORD="$$TEST_PYPI_TOKEN" $(VENV)/bin/twine upload --repository-url $(TEST_PYPI_REPOSITORY) $(DIST_FILES)
+
+publish: check
+	@$(CHECK_RELEASE_VERSION)
+	@if [ -z "$$PYPI_TOKEN" ]; then echo "error: PYPI_TOKEN is required — create one at https://pypi.org/manage/account/token/"; exit 2; fi
+	@TWINE_USERNAME=__token__ TWINE_PASSWORD="$$PYPI_TOKEN" $(VENV)/bin/twine upload --repository-url $(PYPI_REPOSITORY) $(DIST_FILES)
+
+shell:
+	@echo "source $(VENV)/bin/activate"
+
+clean:
+	rm -rf $(VENV) dist/ build/ htmlcov/ test-results.xml .coverage
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null; true
+	find . -name "*.pyc" -delete 2>/dev/null; true
+	find . -name "*.egg-info" -type d -exec rm -rf {} + 2>/dev/null; true
+
+package: dev
+	$(VENV)/bin/pyinstaller lumentest.spec
+
+# ubuntu:24.04 caps the glibc floor at 2.39 by construction.
+build-linux-docker: dev
+	docker run --rm \
+		-e $(DIST_ENV)="$(SCM_VERSION)" \
+		-e DEBIAN_FRONTEND=noninteractive \
+		-v "$(CURDIR):/src" \
+		-w /src \
+		ubuntu:24.04 \
+		bash -c "apt-get update -qq && \
+		apt-get install -y --no-install-recommends python3 python3-venv python3-pip binutils && \
+		python3 -m venv /build-venv && \
+		/build-venv/bin/pip install --no-cache-dir --upgrade pip setuptools wheel && \
+		/build-venv/bin/pip install --no-cache-dir -e ".[package]" && \
+		/build-venv/bin/pyinstaller lumentest.spec; \
+		rc=\$$?; chown -R $(shell id -u):$(shell id -g) build dist src/*.egg-info 2>/dev/null; exit \$$rc"
+
+build-linux-arm64-docker: dev
+	docker run --rm \
+		--platform linux/arm64 \
+		-e $(DIST_ENV)="$(SCM_VERSION)" \
+		-e DEBIAN_FRONTEND=noninteractive \
+		-v "$(CURDIR):/src" \
+		-w /src \
+		ubuntu:24.04 \
+		bash -c "apt-get update -qq && \
+		apt-get install -y --no-install-recommends python3 python3-venv python3-pip binutils && \
+		python3 -m venv /build-venv && \
+		/build-venv/bin/pip install --no-cache-dir --upgrade pip setuptools wheel && \
+		/build-venv/bin/pip install --no-cache-dir -e ".[package]" && \
+		/build-venv/bin/pyinstaller lumentest.spec --distpath dist/linux-arm64 --workpath build/linux-arm64; \
+		rc=\$$?; chown -R $(shell id -u):$(shell id -g) build dist src/*.egg-info 2>/dev/null; exit \$$rc"
+
+build-windows-docker: dev
+	docker run --rm \
+		--entrypoint bash \
+		-e $(DIST_ENV)="$(SCM_VERSION)" \
+		-v "$(CURDIR):/src" \
+		-w /src \
+		batonogov/pyinstaller-windows:v5.0.0 \
+		-c "pip install --no-cache-dir --upgrade -e . && pyinstaller lumentest.spec; \
+		rc=\$$?; chown -R $(shell id -u):$(shell id -g) build dist src/*.egg-info 2>/dev/null; exit \$$rc"

lr_lumentest_cli-0.5.1/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: lr-lumentest-cli
+Version: 0.5.1
+Summary: CLI client for the LumenRadio LumenTest production test station: import artifact packages, run test sequences, and read results over HTTP.
+Author-email: Jonas Estberger <jonas.estberger@lumenradio.com>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/lumenradio/production/lumentest
+Project-URL: Changelog, https://gitlab.com/lumenradio/production/lumentest/-/blob/main/CHANGELOG.md
+Keywords: LumenRadio,LumenTest,production test,test station,CLI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.8
+Requires-Dist: mnemonic>=0.21
+Provides-Extra: dev
+Requires-Dist: build>=1.2.1; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+Requires-Dist: pytest>=8.4; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: black>=25.9; extra == "dev"
+Provides-Extra: package
+Requires-Dist: pyinstaller==6.21.0; extra == "package"
+Dynamic: license-file
+
+# lr-lumentest-cli
+
+CLI for the LumenRadio LumenTest production test station server.
+
+## Installation
+
+```bash
+pip install lr-lumentest-cli
+```
+
+## Quick Start
+
+```bash
+# Point the CLI at your station server and identify yourself by scanning
+# your badge (the handheld scanner types the badge id at the prompt)
+lumentest login --base-url http://10.0.0.1:17080 --badge-id LOP0000001
+
+# Check server health and login state
+lumentest status
+
+# Scan and list imported products
+lumentest product scan
+lumentest product list
+
+# Run a full test sequence interactively (prompts on ALERT steps)
+lumentest test start --serial SN-00001
+
+# Run a single step (for development / debugging)
+lumentest test step production-test flash-firmware --serial SN-00001
+```
+
+## Command Reference
+
+```
+lumentest login    [--base-url URL] --badge-id ID
+  # ID is the scanned QR badge; the server resolves it to your operator id.
+lumentest logout
+lumentest status   [--output rich|json]
+lumentest --version
+
+lumentest product list   [--output rich|json]
+  # Table includes a Build Words column — see doc/build-words.md. The manifest
+  # digest is not shown: read it from --output json when you need the digest.
+lumentest product active
+lumentest product set    ARTICLE [REVISION]
+lumentest product remove ARTICLE [REVISION] [--yes]
+lumentest product scan   [--rescan] [--output rich|json]
+  # Scans the station's artifact_cache/, registers every valid package, and
+  # reports each package's declared env variables (from parameters.toml) —
+  # the value a run will see, where it came from (config.toml's [env], the
+  # station's own environment, or the package default) and which are still
+  # unconfigured — alongside its prerequisites (the external tools its
+  # sequences need) against the station itself. Each unconfigured variable's
+  # line carries the exact `lumentest config set env.NAME <VALUE>` command to
+  # fix it; a set value applies to the running station immediately, so
+  # re-running scan is enough to confirm it, for a variable and for a tool
+  # newly installed on PATH alike — no restart needed either way. --output
+  # json emits the raw payload.
+lumentest product import PATH [--update] [--bundle] [--output rich|json]
+  # PATH: directory or .zip/.tar.gz archive.
+  # --update: recompute SHA-256 checksums in artifact-manifest.json before
+  #           uploading — useful during step development to skip manual hashing.
+  # --bundle: pack PATH into <PATH>.tar.gz (manifest + declared files only)
+  #           next to it instead of uploading — for email/USB delivery;
+  #           import the archive later with the same command. Requires a
+  #           directory; passing an archive file just warns and exits.
+  #           Prints the package's Build Words (doc/build-words.md) so a
+  #           technician can read them off a locally built bundle without a
+  #           running server; --output json carries them as "build_words".
+  # Reports the package's declared env variables the same way `product scan`
+  # does: the value a run will see, where it came from, and which still need
+  # a value. Fix an unconfigured one with the `lumentest config set` command
+  # printed on its line, then re-run `product scan` to confirm — same as
+  # confirming a newly installed prerequisite tool, neither needs a restart.
+  # Only artifact-manifest.json's declared files (and declared extra
+  # sequences) are packed and uploaded — the manifest is the contract for
+  # what the package needs. A package that needs a file its manifest does
+  # not declare must have that file added to the manifest, not bundled some
+  # other way.
+  # A directory import first checks with the station which files it already
+  # has (by digest, including across every other cached revision) — a
+  # retry after an interrupted upload resumes instead of re-sending
+  # everything. Only what's actually missing is uploaded, with a progress
+  # bar over just those bytes; the command then reports how many files were
+  # reused, e.g. "12 of 24 files already on the station (302 MB reused)".
+  # An existing .zip/.tar.gz archive still uploads as a single one-shot
+  # transfer. --output json moves all of the above to stderr so stdout
+  # carries nothing but the final JSON — see "Machine-readable output".
+
+lumentest sequence list       [--article ARTICLE] [--output rich|json]
+lumentest sequence steps      ARTICLE SEQUENCE
+lumentest sequence selection get   ARTICLE SEQUENCE
+lumentest sequence selection set   ARTICLE SEQUENCE --steps 1,2,5
+lumentest sequence selection clear ARTICLE SEQUENCE
+
+lumentest test start   [--serial SN] [--article ARTICLE] [--sequence NAME]
+  # Blocks with an interactive Rich UI; handles ALERT prompts; exits with
+  # the run's terminal status: 0 PASS, 1 FAIL, 2 ABORTED, 3 ERROR (outcome
+  # undetermined — station unreachable or run gone). The operator comes
+  # from the bearer token established by `lumentest login`, not a flag.
+  # The run header shows the package's Build Words when the station reports
+  # them.
+lumentest test step    SEQUENCE STEP [--article ARTICLE] [--serial SN]
+  # Runs one step via the same interactive UI.  STEP is a name or 0-based index.
+lumentest test status  [--output rich|json]
+  # One-shot snapshot of the currently active test run.
+
+lumentest result list  [--limit N] [--serial SN] [--output rich|json]
+  # --serial SN filters to runs for one device (exact dut_id match); the station
+  #   filters server-side so high-throughput stations don't ship the full history.
+lumentest result show  [RUN_ID]
+  # RUN_ID is optional: omit it to show the most recent run.
+lumentest result logs  [RUN_ID] [--step IDX] [--stream stdout|stderr|traceback]
+                      [--download DIR] [--output rich|json]
+  # RUN_ID is optional: omit it to fetch the most recent run's logs.
+  # Without --step: fetches the complete log bundle via GET /logs/all — run error,
+  #   structured journal, and every step's stdout/stderr/traceback.  --output json
+  #   emits the raw JSON bundle; --download DIR writes the tree to DIR/<run_id>/
+  #   (error.txt, log.jsonl, steps/<name>/{stdout,stderr,traceback}.txt, omitting
+  #   empty files).  --output json takes precedence when both flags are given.
+  # With --step IDX: shows that step's stdout, stderr, and traceback (or a single
+  #   stream via --stream).
+lumentest result export [RUN_ID] [--all] [--serial SN] [--limit N]
+                        [--out DIR] [--output rich|json]
+  # Downloads one .tar.gz station snapshot via GET /api/results/export: the
+  #   selected run(s) verbatim under results/ (run.json, qrm-payload.json, the
+  #   journal, every step's captured streams) plus the station's own log,
+  #   state.json, operator_stats.json and effective config under station/ —
+  #   laid out exactly as the station stores them on disk. RUN_ID / --all /
+  #   --serial / --limit govern results/ only; the station context is always
+  #   included. Bare `result export` packs only the most recent run; --all
+  #   opts into every retained run. RUN_ID is mutually exclusive with --all,
+  #   --serial and --limit.
+  # --out DIR: directory to write the archive into (default: the current
+  #   directory). The filename is stamped by the station itself from its own
+  #   [station].id and a UTC timestamp, so an export stays identifiable once
+  #   it is off the station.
+  # artifact_cache/ package binaries are never packed — represented instead by
+  #   an inventory (article, revision, size, file count); Arena is the system
+  #   of record for firmware. Re-send a run to QRM by hand with
+  #   `qrm result upload <run>/qrm-payload.json` against the extracted tree.
+  # An export contains the station's QRM service password, session token
+  #   hashes, operator identities, and whatever a step or tool printed. Treat
+  #   an archive as a secret — see doc/troubleshooting.md § Collecting a
+  #   station snapshot for support.
+
+lumentest config list  [--output rich|json]
+  # Flattens config.toml to dotted keys (station.id, env.NRF_TOOLS,
+  # timeouts.default_step_s, ...) so a technician can scan the whole
+  # effective configuration in one table. Secrets (qrm.password,
+  # serial.client_secret, user password hashes) show as "<redacted>" and are
+  # marked in the Notes column, alongside keys that need a station restart
+  # to take effect (station.host, station.port, debug.results_dir).
+lumentest config get   KEY  [--output rich|json]
+lumentest config set   KEY VALUE [--json] [--output rich|json]
+  # VALUE is sent as a raw string and coerced through the server's pydantic
+  # validation (e.g. "90" -> the int 90); pass --json to send VALUE parsed
+  # as JSON instead, for list/dict/explicitly-typed values. This is how a
+  # newly required package env variable gets set without restarting the
+  # station: `lumentest config set env.SOME_VAR value` then
+  # `lumentest product scan`. A key flagged restart-required still saves,
+  # but a visible warning says it only takes effect after the next restart.
+  # Setting a secret back to its own masked "<redacted>" value is rejected,
+  # so a `config get` / `config set` round trip can never silently
+  # overwrite a credential.
+lumentest config unset KEY
+  # Resets KEY to its model default; for the free-form [env] and
+  # [test].fake_tools maps this removes the entry instead. A required key
+  # with no default (e.g. station.id) is rejected. A restart-required key
+  # carries the same warning `config set` gives — the reset is saved, but
+  # the running station keeps the old value until it restarts.
+
+lumentest operator whoami [--output rich|json]
+  # Resolve the operator behind the stored token via GET /api/auth/whoami.
+  # Exits 1 if the token is missing, unknown, or expired.
+
+lumentest operator stats [OPERATOR_ID] [--stations URL1,URL2,...] [--output rich|json]
+  # Per-operator statistics aggregated across stations (counters add,
+  # last_login = max).  Omit OPERATOR_ID to list every operator seen.
+  # --stations defaults to the logged-in station.
+```
+
+## Machine-readable output
+
+Every command above that takes `--output json` writes **exactly one JSON document
+to stdout and nothing else**, so a caller can pipe it straight into a parser:
+
+```bash
+lumentest product import --bundle --output json ./400-1011_A | jq -r .build_words
+```
+
+Everything meant for a human — progress bars, warnings, "generated the
+manifest" — goes to **stderr** in JSON mode, and errors always do. Redirect it
+away with `2>/dev/null`, or keep it to watch a long import while still capturing
+the result.
+
+A command that finds nothing to report emits `null` rather than staying silent,
+so stdout parses unconditionally.
+
+`result logs --step IDX` is the one exception: it has no JSON form, so `--output`
+is inert there and the step's captured streams go to stdout either way. Piping
+that output works with the flag or without it.
+
+In `--output rich` (the default) the human output goes to stdout as usual.
+
+## Server URL
+
+The CLI reads the server URL from (in order of priority):
+
+1. `--base-url` flag on `lumentest login`
+2. `LUMENTEST_URL` environment variable
+3. Stored value in `~/.config/lumentest/login.json`
+4. Default: `http://127.0.0.1:17080`

lr_lumentest_cli-0.5.1/README.md

@@ -0,0 +1,213 @@
+# lr-lumentest-cli
+
+CLI for the LumenRadio LumenTest production test station server.
+
+## Installation
+
+```bash
+pip install lr-lumentest-cli
+```
+
+## Quick Start
+
+```bash
+# Point the CLI at your station server and identify yourself by scanning
+# your badge (the handheld scanner types the badge id at the prompt)
+lumentest login --base-url http://10.0.0.1:17080 --badge-id LOP0000001
+
+# Check server health and login state
+lumentest status
+
+# Scan and list imported products
+lumentest product scan
+lumentest product list
+
+# Run a full test sequence interactively (prompts on ALERT steps)
+lumentest test start --serial SN-00001
+
+# Run a single step (for development / debugging)
+lumentest test step production-test flash-firmware --serial SN-00001
+```
+
+## Command Reference
+
+```
+lumentest login    [--base-url URL] --badge-id ID
+  # ID is the scanned QR badge; the server resolves it to your operator id.
+lumentest logout
+lumentest status   [--output rich|json]
+lumentest --version
+
+lumentest product list   [--output rich|json]
+  # Table includes a Build Words column — see doc/build-words.md. The manifest
+  # digest is not shown: read it from --output json when you need the digest.
+lumentest product active
+lumentest product set    ARTICLE [REVISION]
+lumentest product remove ARTICLE [REVISION] [--yes]
+lumentest product scan   [--rescan] [--output rich|json]
+  # Scans the station's artifact_cache/, registers every valid package, and
+  # reports each package's declared env variables (from parameters.toml) —
+  # the value a run will see, where it came from (config.toml's [env], the
+  # station's own environment, or the package default) and which are still
+  # unconfigured — alongside its prerequisites (the external tools its
+  # sequences need) against the station itself. Each unconfigured variable's
+  # line carries the exact `lumentest config set env.NAME <VALUE>` command to
+  # fix it; a set value applies to the running station immediately, so
+  # re-running scan is enough to confirm it, for a variable and for a tool
+  # newly installed on PATH alike — no restart needed either way. --output
+  # json emits the raw payload.
+lumentest product import PATH [--update] [--bundle] [--output rich|json]
+  # PATH: directory or .zip/.tar.gz archive.
+  # --update: recompute SHA-256 checksums in artifact-manifest.json before
+  #           uploading — useful during step development to skip manual hashing.
+  # --bundle: pack PATH into <PATH>.tar.gz (manifest + declared files only)
+  #           next to it instead of uploading — for email/USB delivery;
+  #           import the archive later with the same command. Requires a
+  #           directory; passing an archive file just warns and exits.
+  #           Prints the package's Build Words (doc/build-words.md) so a
+  #           technician can read them off a locally built bundle without a
+  #           running server; --output json carries them as "build_words".
+  # Reports the package's declared env variables the same way `product scan`
+  # does: the value a run will see, where it came from, and which still need
+  # a value. Fix an unconfigured one with the `lumentest config set` command
+  # printed on its line, then re-run `product scan` to confirm — same as
+  # confirming a newly installed prerequisite tool, neither needs a restart.
+  # Only artifact-manifest.json's declared files (and declared extra
+  # sequences) are packed and uploaded — the manifest is the contract for
+  # what the package needs. A package that needs a file its manifest does
+  # not declare must have that file added to the manifest, not bundled some
+  # other way.
+  # A directory import first checks with the station which files it already
+  # has (by digest, including across every other cached revision) — a
+  # retry after an interrupted upload resumes instead of re-sending
+  # everything. Only what's actually missing is uploaded, with a progress
+  # bar over just those bytes; the command then reports how many files were
+  # reused, e.g. "12 of 24 files already on the station (302 MB reused)".
+  # An existing .zip/.tar.gz archive still uploads as a single one-shot
+  # transfer. --output json moves all of the above to stderr so stdout
+  # carries nothing but the final JSON — see "Machine-readable output".
+
+lumentest sequence list       [--article ARTICLE] [--output rich|json]
+lumentest sequence steps      ARTICLE SEQUENCE
+lumentest sequence selection get   ARTICLE SEQUENCE
+lumentest sequence selection set   ARTICLE SEQUENCE --steps 1,2,5
+lumentest sequence selection clear ARTICLE SEQUENCE
+
+lumentest test start   [--serial SN] [--article ARTICLE] [--sequence NAME]
+  # Blocks with an interactive Rich UI; handles ALERT prompts; exits with
+  # the run's terminal status: 0 PASS, 1 FAIL, 2 ABORTED, 3 ERROR (outcome
+  # undetermined — station unreachable or run gone). The operator comes
+  # from the bearer token established by `lumentest login`, not a flag.
+  # The run header shows the package's Build Words when the station reports
+  # them.
+lumentest test step    SEQUENCE STEP [--article ARTICLE] [--serial SN]
+  # Runs one step via the same interactive UI.  STEP is a name or 0-based index.
+lumentest test status  [--output rich|json]
+  # One-shot snapshot of the currently active test run.
+
+lumentest result list  [--limit N] [--serial SN] [--output rich|json]
+  # --serial SN filters to runs for one device (exact dut_id match); the station
+  #   filters server-side so high-throughput stations don't ship the full history.
+lumentest result show  [RUN_ID]
+  # RUN_ID is optional: omit it to show the most recent run.
+lumentest result logs  [RUN_ID] [--step IDX] [--stream stdout|stderr|traceback]
+                      [--download DIR] [--output rich|json]
+  # RUN_ID is optional: omit it to fetch the most recent run's logs.
+  # Without --step: fetches the complete log bundle via GET /logs/all — run error,
+  #   structured journal, and every step's stdout/stderr/traceback.  --output json
+  #   emits the raw JSON bundle; --download DIR writes the tree to DIR/<run_id>/
+  #   (error.txt, log.jsonl, steps/<name>/{stdout,stderr,traceback}.txt, omitting
+  #   empty files).  --output json takes precedence when both flags are given.
+  # With --step IDX: shows that step's stdout, stderr, and traceback (or a single
+  #   stream via --stream).
+lumentest result export [RUN_ID] [--all] [--serial SN] [--limit N]
+                        [--out DIR] [--output rich|json]
+  # Downloads one .tar.gz station snapshot via GET /api/results/export: the
+  #   selected run(s) verbatim under results/ (run.json, qrm-payload.json, the
+  #   journal, every step's captured streams) plus the station's own log,
+  #   state.json, operator_stats.json and effective config under station/ —
+  #   laid out exactly as the station stores them on disk. RUN_ID / --all /
+  #   --serial / --limit govern results/ only; the station context is always
+  #   included. Bare `result export` packs only the most recent run; --all
+  #   opts into every retained run. RUN_ID is mutually exclusive with --all,
+  #   --serial and --limit.
+  # --out DIR: directory to write the archive into (default: the current
+  #   directory). The filename is stamped by the station itself from its own
+  #   [station].id and a UTC timestamp, so an export stays identifiable once
+  #   it is off the station.
+  # artifact_cache/ package binaries are never packed — represented instead by
+  #   an inventory (article, revision, size, file count); Arena is the system
+  #   of record for firmware. Re-send a run to QRM by hand with
+  #   `qrm result upload <run>/qrm-payload.json` against the extracted tree.
+  # An export contains the station's QRM service password, session token
+  #   hashes, operator identities, and whatever a step or tool printed. Treat
+  #   an archive as a secret — see doc/troubleshooting.md § Collecting a
+  #   station snapshot for support.
+
+lumentest config list  [--output rich|json]
+  # Flattens config.toml to dotted keys (station.id, env.NRF_TOOLS,
+  # timeouts.default_step_s, ...) so a technician can scan the whole
+  # effective configuration in one table. Secrets (qrm.password,
+  # serial.client_secret, user password hashes) show as "<redacted>" and are
+  # marked in the Notes column, alongside keys that need a station restart
+  # to take effect (station.host, station.port, debug.results_dir).
+lumentest config get   KEY  [--output rich|json]
+lumentest config set   KEY VALUE [--json] [--output rich|json]
+  # VALUE is sent as a raw string and coerced through the server's pydantic
+  # validation (e.g. "90" -> the int 90); pass --json to send VALUE parsed
+  # as JSON instead, for list/dict/explicitly-typed values. This is how a
+  # newly required package env variable gets set without restarting the
+  # station: `lumentest config set env.SOME_VAR value` then
+  # `lumentest product scan`. A key flagged restart-required still saves,
+  # but a visible warning says it only takes effect after the next restart.
+  # Setting a secret back to its own masked "<redacted>" value is rejected,
+  # so a `config get` / `config set` round trip can never silently
+  # overwrite a credential.
+lumentest config unset KEY
+  # Resets KEY to its model default; for the free-form [env] and
+  # [test].fake_tools maps this removes the entry instead. A required key
+  # with no default (e.g. station.id) is rejected. A restart-required key
+  # carries the same warning `config set` gives — the reset is saved, but
+  # the running station keeps the old value until it restarts.
+
+lumentest operator whoami [--output rich|json]
+  # Resolve the operator behind the stored token via GET /api/auth/whoami.
+  # Exits 1 if the token is missing, unknown, or expired.
+
+lumentest operator stats [OPERATOR_ID] [--stations URL1,URL2,...] [--output rich|json]
+  # Per-operator statistics aggregated across stations (counters add,
+  # last_login = max).  Omit OPERATOR_ID to list every operator seen.
+  # --stations defaults to the logged-in station.
+```
+
+## Machine-readable output
+
+Every command above that takes `--output json` writes **exactly one JSON document
+to stdout and nothing else**, so a caller can pipe it straight into a parser:
+
+```bash
+lumentest product import --bundle --output json ./400-1011_A | jq -r .build_words
+```
+
+Everything meant for a human — progress bars, warnings, "generated the
+manifest" — goes to **stderr** in JSON mode, and errors always do. Redirect it
+away with `2>/dev/null`, or keep it to watch a long import while still capturing
+the result.
+
+A command that finds nothing to report emits `null` rather than staying silent,
+so stdout parses unconditionally.
+
+`result logs --step IDX` is the one exception: it has no JSON form, so `--output`
+is inert there and the step's captured streams go to stdout either way. Piping
+that output works with the flag or without it.
+
+In `--output rich` (the default) the human output goes to stdout as usual.
+
+## Server URL
+
+The CLI reads the server URL from (in order of priority):
+
+1. `--base-url` flag on `lumentest login`
+2. `LUMENTEST_URL` environment variable
+3. Stored value in `~/.config/lumentest/login.json`
+4. Default: `http://127.0.0.1:17080`

lr_lumentest_cli-0.5.1/lumentest.spec

@@ -0,0 +1,48 @@
+# -*- mode: python ; coding: utf-8 -*-
+from PyInstaller.utils.hooks import (
+    copy_metadata,
+    collect_data_files,
+    collect_submodules,
+)
+
+a = Analysis(
+    ["src/lumentest/__main__.py"],
+    pathex=[],
+    binaries=[],
+    datas=[
+        *copy_metadata("lr-lumentest-cli"),
+        *collect_data_files("rich"),
+    ],
+    # rich.cells lazily import_module()s a Unicode-version-specific submodule
+    # (e.g. rich._unicode_data.unicode17-0-0) whose name is computed at runtime,
+    # so PyInstaller's static analysis can't discover it. Collect them all.
+    hiddenimports=[*collect_submodules("rich._unicode_data")],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    noarchive=False,
+)
+
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    a.binaries,
+    a.datas,
+    [],
+    name="lumentest",
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    runtime_tmpdir=None,
+    console=True,
+    disable_windowed_traceback=False,
+    argv_emulation=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+)