lr-lumentest-cli 0.5.1__py3-none-any.whl

lr_lumentest_cli-0.5.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,26 @@
+lr_lumentest_cli-0.5.1.dist-info/licenses/LICENSE,sha256=cEnG3HeMPa3GKtuENkytOQaNJS9rwMMU_KWHObdWbOY,1070
+lumentest/__init__.py,sha256=IyOHnTq79cSXeELA5QCGzS164PZFaUqUPv5JuefIitg,253
+lumentest/__main__.py,sha256=VmwcYSnsDe9MR_GCkhw1HR4AFENhvtSYub9mZG1M7Wo,37
+lumentest/_version.py,sha256=et8oVdAxXtM6it836Cx8r9oFEtQha0JynHTCzNzn8eQ,520
+lumentest/auth.py,sha256=qBvjLuNG0ictE6tSo6n_8l5yktbwOvArQbdECIda8t0,5527
+lumentest/build_words.py,sha256=zACXpNEW0qvOqM6BLVLHRk5tQgkhQxM8PQcGxTZUWP4,4033
+lumentest/cli.py,sha256=p7a36ri_WESeUhW9nZRv8XcpiweCz8j9hncmaCP8OBo,1625
+lumentest/client.py,sha256=T1wai5oLmePzabQUt5ctNBRinChVrqQ9XGBNvPITtz0,46675
+lumentest/commands_shared.py,sha256=j5ZeBqyupbVr4l6Awo57ufXrvjcqBRVebQk0rxVk0jQ,10347
+lumentest/config.py,sha256=Heo9ABHK13QXcTYrT5mlgwtBKD_0QH5IgoQPgIa6-Hk,2382
+lumentest/env_report.py,sha256=PtLu_I9kadXynMUw1brEDoLtF-c_i11FmQMJ-MCv3og,8614
+lumentest/manifest_gen.py,sha256=wuQVVMY5NgAuoM592RW8GbINOTkBWRaSgeMn6hBH07E,9321
+lumentest/prerequisites_report.py,sha256=hs5yxmTZKaeQ--3a9KJX0d8L95exnNJp9gKcpj7AZQs,8964
+lumentest/commands/__init__.py,sha256=sa5StNEFUUs_HJQXF1S_hA0IsCMxia3uAkBBAOj9CV8,46
+lumentest/commands/config.py,sha256=Byt4iowPSZy7Kz0sishMWZnAIKwte08KRlve1dtWKQw,7279
+lumentest/commands/operator.py,sha256=ri0ljoifMVh8jCgGEu0KRhMRwyjrSXx_iNeWnZhUHAw,7148
+lumentest/commands/product.py,sha256=If4iI1EzApHCn0TnzI97kEFDAwPK0qEDNrHUrQnaCO4,26011
+lumentest/commands/result.py,sha256=YYbEIUu0dsIOwyFOYom4zCKc-h-kWF56hBldeMRzT1o,25188
+lumentest/commands/sequence.py,sha256=B8LAXzLKR8BNLeejbwtkd6U5hn_rO7ZFY3G4_mZgMXA,11065
+lumentest/commands/test.py,sha256=GM33JcQTtMN7d3HrKcjlV112x2t35D5EzDQWfXgb6ug,9824
+lumentest/commands/test_ui.py,sha256=yNbci0PtqlNymETOPaqZZvfi7TKxUGvJV6QcrM3p2jk,34196
+lr_lumentest_cli-0.5.1.dist-info/METADATA,sha256=SvW5y-5AkaHwY_DlVaSZzyyOAAxSwhaGUitrOX4aunU,12541
+lr_lumentest_cli-0.5.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+lr_lumentest_cli-0.5.1.dist-info/entry_points.txt,sha256=TzyC9nHlZLbcBYRILLqCp2uRYcve8chHGY16t_pmLW8,48
+lr_lumentest_cli-0.5.1.dist-info/top_level.txt,sha256=lQModdT5-g8DctLm-3TBrsSwOav0Aj8lq05feMUICoY,10
+lr_lumentest_cli-0.5.1.dist-info/RECORD,,

lr_lumentest_cli-0.5.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lr_lumentest_cli-0.5.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lumentest = lumentest.cli:app

lr_lumentest_cli-0.5.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+lumentest

lumentest/__init__.py

@@ -0,0 +1,6 @@
+"""lr-lumentest-cli — CLI for the LumenRadio LumenTest test station server."""
+
+try:
+    from lumentest._version import __version__
+except ImportError:  # pragma: no cover - _version.py is generated by setuptools_scm
+    __version__ = "0.0.0+unknown"

lumentest/__main__.py

@@ -0,0 +1,3 @@
+from lumentest.cli import app
+
+app()

lumentest/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.5.1'
+__version_tuple__ = version_tuple = (0, 5, 1)
+
+__commit_id__ = commit_id = None

lumentest/auth.py

@@ -0,0 +1,185 @@
+"""Authentication commands: login, logout, status."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.table import Table
+
+from .client import LumenTestClient, LumenTestClientError, LoginState
+from .config import DEFAULT_CONFIG_PATH, save_login_state
+from .commands_shared import (
+    DEFAULT_BASE_URL,
+    OutputFormat,
+    console,
+    emit,
+    handle_error,
+    load_state_or_exit,
+    output_option,
+)
+
+auth_app = typer.Typer(help="Manage server login state.")
+
+
+# ---------------------------------------------------------------------------
+# login
+# ---------------------------------------------------------------------------
+
+
+@auth_app.command()
+def login(
+    base_url: str = typer.Option(
+        DEFAULT_BASE_URL,
+        "--base-url",
+        "-b",
+        help="Base URL of the lumentest-station server.",
+        envvar="LUMENTEST_URL",
+    ),
+    badge_id: str = typer.Option(
+        ...,
+        "--badge-id",
+        "-o",
+        prompt="Scan badge",
+        help="Scanned QR badge identifier (the handheld scanner types it for you).",
+        envvar="LUMENTEST_BADGE_ID",
+    ),
+    config_path: Path = typer.Option(
+        None,
+        "--config-path",
+        help="Override the location of the login.json file.",
+    ),
+) -> None:
+    """Identify the operator by scanning their badge and store login state.
+
+    Contacts ``GET /api/health`` to confirm the server is up, then
+    ``POST /api/auth/login`` with the scanned badge.  The server resolves the
+    operator id and issues a token, which is written to
+    ``~/.config/lumentest/login.json``.  An unrecognised badge fails with a
+    non-zero exit code.
+    """
+    destination = config_path or DEFAULT_CONFIG_PATH
+
+    client = LumenTestClient(base_url=base_url)
+    try:
+        client.health()
+        token, operator_id = client.auth_login(badge_id.strip())
+    except LumenTestClientError as exc:
+        typer.secho(
+            f"Login failed against {base_url}: {exc}",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1) from exc
+    finally:
+        client.close()
+
+    state = LoginState(base_url=base_url, operator_id=operator_id, token=token)
+    save_login_state(state, destination)
+
+    console.print(
+        f"[green]Logged in as [bold]{operator_id}[/bold] "
+        f"→ {base_url}  (saved to {destination})[/green]"
+    )
+
+
+# ---------------------------------------------------------------------------
+# logout
+# ---------------------------------------------------------------------------
+
+
+@auth_app.command()
+def logout(
+    config_path: Path = typer.Option(
+        None,
+        "--config-path",
+        help="Override the location of the login.json file.",
+    ),
+) -> None:
+    """Invalidate the server session and remove the stored login state."""
+    destination = config_path or DEFAULT_CONFIG_PATH
+    if not destination.exists():
+        typer.secho("Not logged in — nothing to remove.", fg=typer.colors.YELLOW)
+        return
+
+    # Best-effort: notify the server; ignore failures (token may already be gone).
+    state = load_state_or_exit(destination)
+    client = LumenTestClient(base_url=state.base_url, token=state.token)
+    try:
+        client.auth_logout()
+    except LumenTestClientError:
+        pass  # server unreachable or stub returned an error — proceed anyway
+    finally:
+        client.close()
+
+    destination.unlink()
+    console.print(f"[green]Logged out (removed {destination})[/green]")
+
+
+# ---------------------------------------------------------------------------
+# status
+# ---------------------------------------------------------------------------
+
+
+@auth_app.command()
+def status(
+    config_path: Path = typer.Option(
+        None,
+        "--config-path",
+        help="Override the location of the login.json file.",
+    ),
+    output: OutputFormat = output_option(),
+) -> None:
+    """Show login state and confirm the server is reachable.
+
+    Reads ``login.json``, contacts ``GET /api/health``, and renders a
+    summary table with ``server_ok``, ``base_url``, and ``operator_id``.
+    """
+    state = load_state_or_exit(config_path)
+
+    client = LumenTestClient(base_url=state.base_url, token=state.token)
+    server_ok = False
+    server_version: str | None = None
+    error_msg: str | None = None
+
+    try:
+        health = client.health()
+        server_ok = health.get("status") == "ok"
+        server_version = health.get("version")
+    except LumenTestClientError as exc:
+        error_msg = str(exc)
+    finally:
+        client.close()
+
+    payload = {
+        "server_ok": server_ok,
+        "base_url": state.base_url,
+        "operator_id": state.operator_id,
+        "server_version": server_version or error_msg or "unknown",
+    }
+
+    if output is OutputFormat.json:
+        emit(payload, output)
+        return
+
+    # Rich rendering
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Field", style="cyan", no_wrap=True)
+    table.add_column("Value", style="green")
+
+    server_ok_str = "[green]yes[/green]" if server_ok else "[red]no[/red]"
+    table.add_row("server_ok", server_ok_str)
+    table.add_row("base_url", state.base_url)
+    table.add_row("operator_id", state.operator_id)
+    if server_version:
+        table.add_row("server_version", server_version)
+    if error_msg:
+        table.add_row("error", f"[red]{error_msg}[/red]")
+
+    console.print(table)
+
+    if not server_ok:
+        raise typer.Exit(code=1)
+
+
+__all__ = ["auth_app"]

lumentest/build_words.py

@@ -0,0 +1,94 @@
+"""Build Words: a two-word, speakable fingerprint of an artifact package's
+content files. Algorithm reference: doc/build-words.md.
+
+This is the client-side twin of the station's
+``lumentest_station.build_words``. It computes identical words from a
+manifest's ``files[]`` array so a technician can read them off a locally
+built bundle without a running server. The station computes over validated
+``ManifestFile`` models; here the same fields are read straight from
+``artifact-manifest.json``, so each entry is reduced to exactly the fields the
+``ManifestFile`` schema declares, at their effective value after defaults
+(``title``/``sha256`` default null, ``os`` defaults ``"any"``). Any field the
+schema does not declare is dropped, matching the station's ``model_dump`` —
+the station would reject a manifest carrying extra fields at load time.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Iterable
+
+from mnemonic import Mnemonic
+
+BUILD_WORDS_COUNT = 2  # words rendered
+_BITS_PER_WORD = 11  # 2048-word BIP39 list -> 11 bits per word
+_TOTAL_BITS = BUILD_WORDS_COUNT * _BITS_PER_WORD  # 22
+
+# The fields the ManifestFile schema declares, with their effective value
+# after defaults. Kept in lockstep with
+# service/src/lumentest_station/manifest.py::ManifestFile so the two
+# implementations produce identical words. See doc/build-words.md §2.
+_FIELD_DEFAULTS: dict[str, Any] = {
+    "path": None,
+    "role": None,
+    "title": None,
+    "sha256": None,
+    "os": "any",
+}
+
+_WORDLIST: tuple[str, ...] = tuple(Mnemonic("english").wordlist)
+
+if len(_WORDLIST) != 2048:
+    # Every index below assumes exactly 2048 entries; a resized list would
+    # silently map to different words instead of failing.
+    raise RuntimeError(f"expected 2048-word BIP39 wordlist, got {len(_WORDLIST)}")
+
+__all__ = ["BUILD_WORDS_COUNT", "content_digest", "build_words"]
+
+
+def _canonical_entry(entry: dict[str, Any]) -> dict[str, Any]:
+    """Reduce a raw ``files[]`` entry to the canonical ManifestFile fields.
+
+    Only the fields the schema declares survive, each at its effective value
+    after defaults, so the JSON serialised below matches the station's
+    ``ManifestFile.model_dump(mode="json")``.
+    """
+    return {key: entry.get(key, default) for key, default in _FIELD_DEFAULTS.items()}
+
+
+def content_digest(files: Iterable[dict[str, Any]]) -> str:
+    """Master SHA-256 hex digest over the canonicalised ``files[]`` entries."""
+    # Sorting by path (Unicode code-point order) is what makes a re-export
+    # that reorders files[] produce identical Build Words.
+    entries = sorted((_canonical_entry(f) for f in files), key=lambda f: f["path"])
+    digest = hashlib.sha256()
+    for obj in entries:
+        # No host-OS filtering: every entry is hashed whatever its os value.
+        # Filtering would make one package yield different Build Words on a
+        # Linux station and a Windows station, defeating the point of an
+        # operator reading them back.
+        blob = json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+            "utf-8"
+        )
+        # The newline separator is unambiguous because JSON escapes newlines
+        # inside strings.
+        digest.update(blob + b"\n")
+    return digest.hexdigest()
+
+
+def build_words(files: Iterable[dict[str, Any]]) -> str:
+    """Two BIP39 words derived from :func:`content_digest`.
+
+    Top-level manifest fields (article, revision, name, sns_article) are not
+    hashed: identical content ships under different parts and must
+    fingerprint identically. Only files[] is content.
+    """
+    digest = content_digest(files)
+    # Most-significant _TOTAL_BITS bits of the digest, MSB-first, matching
+    # BIP39's bit convention. No checksum -- every bit is entropy.
+    head = bytes.fromhex(digest)[:3]
+    value = int.from_bytes(head, "big") >> (8 * len(head) - _TOTAL_BITS)
+    first = value >> _BITS_PER_WORD
+    second = value & 0x7FF
+    return f"{_WORDLIST[first]} {_WORDLIST[second]}"