Compare commits

...
13 Commits
26 changed files with 606 additions and 245 deletions
+4
View File
@@ -11,6 +11,7 @@ jobs:
candidate:
runs-on: alkane-ci
env:
CARGO_TARGET_DIR: target
WX_PREFIX: /root/.cache/wx-3.3.3-linux
WX_RS_WXCONFIG: /root/.cache/wx-3.3.3-linux/bin/wx-config
steps:
@@ -46,3 +47,6 @@ jobs:
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/release-rc.py "${{ steps.version.outputs.tag }}" true "dist/alkane-toolkit-${{ steps.version.outputs.version }}-linux-x86_64.tar.gz"
- name: Clean generated Toolkit build
if: always()
run: python3 ci/cleanup-generated.py
+12 -5
View File
@@ -14,6 +14,7 @@ jobs:
release:
runs-on: alkane-ci
env:
CARGO_TARGET_DIR: target
WX_PREFIX: /root/.cache/wx-3.3.3-linux
# Set once for the whole job so build/clippy/test/bench steps don't each
# re-export it (round 18 #12).
@@ -37,6 +38,9 @@ jobs:
- name: Benchmark history checks
run: python3 ci/test-bench-history.py
- name: Benchmark suite checks
run: python3 ci/test-bench-badge.py
- name: Install build dependencies
run: |
apt-get update -qq
@@ -88,12 +92,12 @@ jobs:
- name: Microbenchmarks
run: |
# Capture the bench stdout for the weighted-average delta badge (round 19
# #1) while keeping the step a hard gate: pipefail preserves cargo's exit
# code (each bench asserts its own absolute ceiling) even through tee.
# Require every declared benchmark before publishing history or a release.
set -o pipefail
cargo test -p alkane-gui -p alkane-artifacts --release --offline -- --ignored --nocapture bench_ \
cargo test -p alkane-gui -p alkane-artifacts --release --offline -- --ignored --nocapture bench_ --test-threads=1 \
| tee bench-current.txt
python3 ci/bench-badge.py --current bench-current.txt \
--baseline badges/bench-baseline.json --no-write
- name: Record private benchmark history
env:
@@ -166,7 +170,7 @@ jobs:
python3 ci/gen-badges.py --tests "$PASS" \
--coverage "${{ steps.cov.outputs.pct }}" \
--bench-coverage "${{ steps.benchcov.outputs.pct }}" \
--bench-delta "$BENCH_DELTA"
--bench-delta "$BENCH_DELTA" --clippy clean
- name: Publish measured badges
env:
@@ -203,3 +207,6 @@ jobs:
- name: No release needed
if: steps.ver.outputs.release != 'true'
run: echo "No backend/UI change since ${{ steps.ver.outputs.last_tag }} - skipping release."
- name: Clean generated Toolkit build
if: always()
run: python3 ci/cleanup-generated.py
+5 -1
View File
@@ -14,6 +14,7 @@ jobs:
verify:
runs-on: alkane-ci
env:
CARGO_TARGET_DIR: target
WX_PREFIX: /root/.cache/wx-3.3.3-linux
WX_RS_WXCONFIG: /root/.cache/wx-3.3.3-linux/bin/wx-config
steps:
@@ -55,7 +56,7 @@ jobs:
cargo test -p alkane-artifacts -p alkane-flash -p alkane-cli --offline
- name: Microbenchmarks
run: cargo test -p alkane-gui -p alkane-artifacts --release --offline -- --ignored --nocapture bench_
run: cargo test -p alkane-gui -p alkane-artifacts --release --offline -- --ignored --nocapture bench_ --test-threads=1
- name: Headless UI self-test
run: |
@@ -76,3 +77,6 @@ jobs:
else
echo "cargo-audit not installed on this runner; skipping"
fi
- name: Clean generated Toolkit build
if: always()
run: python3 ci/cleanup-generated.py
Generated
+2
View File
@@ -74,6 +74,8 @@ version = "0.1.0"
dependencies = [
"alkane-artifacts",
"alkane-core",
"sha2",
"tempfile",
"thiserror",
]
+39 -90
View File
@@ -1,4 +1,4 @@
# alkane-toolkit
# Alkane Toolkit
[![CI](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/main.svg)](https://gitea.bluefla.re/blueflare/alkane-toolkit/actions)
![tests](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/tests.svg)
@@ -10,112 +10,61 @@
![dependencies](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/dependencies.svg)
![license](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/license.svg)
The CI badge shows the last completed attempt for this branch while newer
runs are queued. Badge SVGs are stored in a private, machine-maintained branch.
Desktop fleet discovery and monitoring for ASIC miners. The Rust GUI uses
wxWidgets through a patched [wx-rs bridge](thirdparty/wx-rs). Firmware
installation is under development.
A cross-platform desktop toolkit for discovering, monitoring, and re-flashing
ASIC miners. It scans a fleet over the network, shows live health and hashrate
in a sortable table. The install path is under development for **stock** and
**alkaneOS** firmware on boards running stock, VNish/AnthillOS, Braiins OS+,
LuxOS, ePIC, HiveOn, BixBit, WardenOS).
The core and UI are pure Rust; the native window is wxWidgets driven through a
vendored, patched [wx-rs](thirdparty/wx-rs) bridge, so there is no Electron,
no web view, and a single self-contained binary per platform.
## What it does
- **Discover** a fleet by CIDR or IP range and identify each miner's make,
model, control board, and firmware (via a vendored [asic-rs](vendor/asic-rs)).
- **Monitor** hashrate vs. expected, per-board health, chip temperatures, fans,
PSU state, and pool workers, with an Excel-style filter and drag-reorderable
columns.
- **Operate** miners from a right-click menu: flash the locate light, pause /
resume, restart, set a power or hashrate target, select a firmware profile
(LuxOS/VNish presets), configure pools, set the timezone, and change the
password -- each action offered only when every selected miner supports it.
- **Install firmware**: push stock or aftermarket images, or revert an
aftermarket miner to stock, behind a typed confirmation.
Discovery and telemetry are read-only and safe to run against any fleet; every
mutating action is capability-gated and, where destructive, confirmed.
## Build and run (Debian/Ubuntu)
## Run locally
```sh
scripts/build-wx-linux.sh # once: builds the vendored wxWidgets 3.3.3 into ~/.cache
scripts/build-gui-linux.sh # cargo build --release -p alkane-gui
~/.cache/alkane-tk-target/release/alkane-toolkit
scripts/build-wx-linux.sh
scripts/build-gui-linux.sh
ALKANE_FAKE_SCAN=1 ~/.cache/alkane-tk-target/release/alkane-toolkit
```
Runtime needs GTK 3: `sudo apt install libgtk-3-0`. To explore the UI with no
hardware, run the offline demo fleet:
The first command builds wxWidgets 3.3.3 once. Linux runtime needs GTK 3
(`libgtk-3-0` on Debian/Ubuntu). The fake scan uses offline fixtures and
does not contact hardware. Windows and macOS use their respective
`scripts/build-gui-*.sh` scripts and platform toolchains.
```sh
ALKANE_FAKE_SCAN=1 alkane-toolkit
```
## Current scope
Windows and macOS share all GUI code; only the C++ bridge and wx build differ
(`scripts/build-gui-windows.sh` needs an msys2 toolchain, `-macos.sh` needs a
Mac).
- Discover miners by CIDR or IP range with vendored
[asic-rs](vendor/asic-rs), and show model, firmware, health, hashrate,
temperatures, fans, PSU, and pool workers.
- Filter, sort, and reorder columns in the desktop table.
- Probe discovery, telemetry, presets, and write actions with the
`miner_probe` CLI. Run it without arguments for the verb list.
## Command-line probe
`miner_probe` is a headless companion for hardware checks that should not go
through the window event loop -- discovery, telemetry, and each write action:
```sh
miner_probe scan 10.0.0.0/24 # discover + telemetry (TSV)
miner_probe presets 10.0.0.5 # list a firmware's selectable profiles
miner_probe setpreset 10.0.0.5 540MHz
```
Run `miner_probe` with no arguments for the full verb list.
The installer and some operator actions remain roadmap items; see the
[implementation plan](docs/IMPLEMENTATION-PLAN.md) and
[firmware parity matrix](docs/aftermarket-parity-roadmap.md). A listed
firmware or board is not an install claim. Discovery is read-only.
## Development
```sh
export WX_RS_WXCONFIG="$HOME/.cache/wx-3.3.3-linux/bin/wx-config"
export CARGO_TARGET_DIR="$HOME/.cache/alkane-tk-target" # keep the target tree off the source share
cargo test -p alkane-gui # unit tests
cargo test -p alkane-gui --release -- --ignored bench_ # microbenchmarks
cargo clippy -p alkane-gui --no-deps --bins -- -D warnings # lint gate
xvfb-run -a env ALKANE_SELFTEST=1 \
"$CARGO_TARGET_DIR/release/alkane-toolkit" # headless UI self-test
ci/coverage.sh --summary-only # coverage (tests + self-test)
export CARGO_TARGET_DIR="$HOME/.cache/alkane-tk-target"
cargo test -p alkane-gui --offline
cargo clippy -p alkane-gui --no-deps --bins -- -D warnings
scripts/ui-selftest.sh
ci/coverage.sh --summary-only
```
CI mirrors these: `verify.yml` runs lint, tests, benchmarks, the self-test, and
a dependency audit on development branches. `release.yml` runs the full gate
on every `main` push and cuts an `X.Y.Z` release when the change warrants it.
`next.yml` builds release candidates with little testing and publishes `-rc`
releases. Dependencies are vendored under `vendor/`, so builds never touch the
network.
Keep build output off the source share. `main` runs the full CI gate and
publishes qualifying releases; `next` builds `-rc` candidates. Badges
report host tests and benchmarks, not installation support. Benchmark
comparisons require the same CPU class. The code quality letter reports the
Clippy gate; the separate coverage badge reports exercised lines.
## Architecture
## Firmware safety
- `crates/alkane-gui` -- the application: scan engine, data model, wxWidgets UI,
and the `miner_probe` CLI (the other `crates/alkane-*` are early scaffolding).
- `vendor/asic-rs` -- the miner-discovery and control library, vendored and
extended through numbered patches under `thirdparty/asic-rs/patches`.
- `thirdparty/wx-rs` -- the patched wxWidgets bridge (see `docs/adr/0002`,
`0003`).
See [`docs/IMPLEMENTATION-PLAN.md`](docs/IMPLEMENTATION-PLAN.md) for the roadmap
and [`docs/aftermarket-parity-roadmap.md`](docs/aftermarket-parity-roadmap.md)
for the firmware config/scan parity work.
## Firmware safety rules
Encoded in code, from alkane-sdk `docs/install-methods.md`:
1. Never write the bootloader or secure region.
2. Verify on a channel the installer does not control.
3. Reboot is root-only; a dropped SSH connection can still be success.
4. A packer is per board; never reuse one across boards.
5. Boot-switch handling is an explicit, verified step.
The [SDK install rules](https://gitea.bluefla.re/blueflare/alkane-sdk/src/branch/main/docs/install-methods.md) require
serial and recovery checks for risky writes. Installation must never write
the bootloader or secure region, must verify over an independent channel,
and must use the packer and boot-switch procedure for the exact board.
## License
Licensed under the [MIT license](LICENSE).
[MIT](LICENSE). Vendored dependencies keep their own terms.
+58 -46
View File
@@ -1,27 +1,8 @@
#!/usr/bin/env python3
"""Compute the weighted-average microbenchmark delta versus the previous release.
Reads the captured stdout of `cargo test ... --ignored --nocapture bench_` (whose
timings are Rust `Duration` Debug strings: "12.3ms", "512us"/"512µs", "840ns",
"1.2s"), compares each bench to a committed baseline of the previous release's
numbers, and prints the time-weighted average change as a signed percentage:
(sum(current) / sum(baseline) - 1) * 100 over benches present in both
Weighting by duration means the slow benches dominate, so the number tracks
overall wall-time change rather than giving a tiny bench equal say. Then the
baseline is rewritten with the current numbers, so the next release compares
against this one ("the previous commit").
Usage:
bench-badge.py --current bench-current.txt --baseline badges/bench-baseline.json
Prints the delta as a plain number (e.g. "-3.2", or "NEW" when there is no
usable baseline) to stdout. The baseline JSON lives under badges/ so committing
it back does not trip compute-version.sh's path-based release bump.
"""
"""Check the Toolkit benchmark suite and compare it with the prior release."""
import argparse
import json
import math
import os
import re
import sys
@@ -29,9 +10,17 @@ import sys
# A Duration Debug token: a number immediately followed by a time unit, with the
# multi-char units listed before the bare "s" so alternation prefers them. The
# trailing (?![a-zA-Z]) stops "s" in words like "rows"/"cidrs" from matching.
_DUR = re.compile(r"([0-9]+(?:\.[0-9]+)?)\s*(ns|µs|us|ms|s)(?![a-zA-Z])")
_UNIT_NS = {"ns": 1.0, "us": 1e3, "µs": 1e3, "ms": 1e6, "s": 1e9}
_NAME = re.compile(r"^(bench_[A-Za-z0-9_]+)\s*:")
_DUR = re.compile(r"([0-9]+(?:\.[0-9]+)?)\s*(ns|\u00b5s|us|ms|s)(?![a-zA-Z])")
_UNIT_NS = {"ns": 1.0, "us": 1e3, "\u00b5s": 1e3, "ms": 1e6, "s": 1e9}
_NAME = re.compile(r"^(?:test [A-Za-z0-9_:]+ \.\.\. )?(bench_[A-Za-z0-9_]+)\s*:")
EXPECTED_BENCHES = {
"bench_verify_artifact", "bench_naming_transforms",
"bench_parse_line_near_max_addrs", "bench_parse_targets_many_ranges_near_cap",
"bench_targets_to_cidrs_large_range", "bench_view_pipeline",
"bench_render_cells", "bench_health_diagnostics",
"bench_view_pipeline_default_sort", "bench_sort_by_each_column",
"bench_view_pipeline_with_filter", "bench_upsert_cold_start_population",
}
def parse_bench(text: str) -> dict:
@@ -44,12 +33,33 @@ def parse_bench(text: str) -> dict:
continue
durs = _DUR.findall(line)
if not durs:
continue
raise ValueError(f"missing timing for {m.group(1)}")
val, unit = durs[-1]
out[m.group(1)] = float(val) * _UNIT_NS[unit]
elapsed = float(val) * _UNIT_NS[unit]
if m.group(1) in out or not math.isfinite(elapsed) or elapsed <= 0:
raise ValueError(f"duplicate or invalid timing for {m.group(1)}")
out[m.group(1)] = elapsed
return out
def require_suite(results: dict) -> dict:
if results.keys() != EXPECTED_BENCHES:
raise ValueError("microbenchmark results differ from the declared suite")
return results
def benchmark_delta(current: dict, baseline: dict) -> float | None:
"""Average each comparable benchmark's percentage improvement."""
if not baseline:
return None
changes = [(baseline[name] - current[name]) / baseline[name]
for name in baseline]
delta = math.fsum(changes) / len(changes) * 100
if not math.isfinite(delta):
raise ValueError("benchmark comparison is not finite")
return delta
def main() -> int:
ap = argparse.ArgumentParser()
ap.add_argument("--current", required=True, help="captured bench stdout")
@@ -59,32 +69,34 @@ def main() -> int:
try:
with open(args.current, encoding="utf-8") as fh:
current = parse_bench(fh.read())
except OSError as e:
current = require_suite(parse_bench(fh.read()))
except (OSError, ValueError) as e:
print(f"bench-badge: cannot read current results: {e}", file=sys.stderr)
print("NEW")
return 0
if not current:
print("bench-badge: no bench lines parsed from current results", file=sys.stderr)
print("NEW")
return 0
return 1
baseline = {}
try:
with open(args.baseline, encoding="utf-8") as fh:
baseline = {k: float(v) for k, v in json.load(fh).items()}
except (OSError, ValueError):
baseline = {}
baseline = json.load(fh)
except FileNotFoundError:
pass
except (OSError, ValueError) as e:
print(f"bench-badge: invalid baseline: {e}", file=sys.stderr)
return 1
if (not isinstance(baseline, dict)
or not set(baseline).issubset(current)
or any(not isinstance(value, (int, float)) or isinstance(value, bool)
or not math.isfinite(value) or value <= 0
for value in baseline.values())):
print("bench-badge: invalid or retired benchmark in baseline", file=sys.stderr)
return 1
common = [k for k in current if k in baseline and baseline[k] > 0]
if common:
sum_new = sum(current[k] for k in common)
sum_old = sum(baseline[k] for k in common)
delta = (sum_new / sum_old - 1.0) * 100.0 if sum_old > 0 else 0.0
print(f"{delta:.1f}")
else:
print("NEW")
try:
delta = benchmark_delta(current, baseline)
except ValueError as error:
print(f"bench-badge: {error}", file=sys.stderr)
return 1
print("NEW" if delta is None else f"{delta:.1f}")
if not args.no_write:
os.makedirs(os.path.dirname(args.baseline) or ".", exist_ok=True)
+11 -5
View File
@@ -17,6 +17,7 @@ from urllib.error import HTTPError
from urllib.parse import quote
from badge_store import BADGE_BRANCH, publish_file, request_json
from bench_host import identity as benchmark_host
bench_spec = importlib.util.spec_from_file_location(
"bench_badge", Path(__file__).with_name("bench-badge.py"))
@@ -59,13 +60,15 @@ def git_distance(ancestor: str, sha: str) -> int | None:
return int(result.stdout.strip()) if ancestor_check.returncode == 0 else None
def previous_measurement(index: dict, sha: str, distance=None) -> dict:
def previous_measurement(index: dict, sha: str, distance=None, host=None) -> dict:
distance = distance or git_distance
choices = []
for entry in index.get("entries", []):
ancestor = entry.get("sha")
if ancestor == sha or not isinstance(ancestor, str):
continue
if host is not None and entry.get("metrics", {}).get("bench_host") != host:
continue
gap = distance(ancestor, sha)
if gap is not None and gap > 0:
choices.append((gap, entry))
@@ -95,6 +98,9 @@ def render_html(index: dict) -> str:
cells = [f'<td><a href="https://gitea.bluefla.re/blueflare/alkane-toolkit/commit/{sha}">{sha[:10]}</a></td>',
f'<td>{html.escape(entry["timestamp"])}</td>']
values = valid_benches(entry["metrics"])
host = entry["metrics"].get("bench_host", {})
host_label = host.get("cpu_model", "unknown") if isinstance(host, dict) else "unknown"
cells.append(f'<td>{html.escape(str(host_label))}</td>')
cells += [f'<td>{values[name]:.3f}</td>' if name in values else '<td>new</td>'
for name in names]
rows.append("<tr>" + "".join(cells) + "</tr>")
@@ -114,7 +120,7 @@ def render_html(index: dict) -> str:
f"<p><small>Most recent {len(entries)} measured commits. Full per-commit JSON is retained "
"in the private ci-badges branch.</small></p>"
f"<div class=\"scroll\"><table><thead><tr><th scope=\"col\">Commit</th>"
f"<th scope=\"col\">UTC</th>{headings}</tr></thead><tbody>{''.join(rows)}"
f"<th scope=\"col\">UTC</th><th scope=\"col\">CPU</th>{headings}</tr></thead><tbody>{''.join(rows)}"
"</tbody></table></div></body></html>\n")
@@ -130,13 +136,13 @@ def main() -> None:
if index.get("schema") != 1 or not isinstance(index.get("entries"), list):
raise ValueError("unsupported benchmark history index")
if args.action == "prepare":
baseline = previous_measurement(index, sha)
baseline = previous_measurement(index, sha, host=benchmark_host())
Path("badges").mkdir(exist_ok=True)
Path("badges/bench-baseline.json").write_text(json.dumps(baseline) + "\n")
print(f"Loaded {len(baseline)} prior benchmark measurements")
return
metrics = {"bench_ns_per_op": bench_badge.parse_bench(
Path("bench-current.txt").read_text())}
metrics = {"bench_ns_per_op": bench_badge.require_suite(bench_badge.parse_bench(
Path("bench-current.txt").read_text())), "bench_host": benchmark_host()}
timestamp = datetime.now(timezone.utc).isoformat(timespec="seconds")
index = updated_index(index, sha, metrics, timestamp)
record = json.dumps(index["entries"][-1], indent=2).encode() + b"\n"
+19
View File
@@ -0,0 +1,19 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Identify the CPU class used for comparable CI microbenchmark baselines."""
import os
import platform
from pathlib import Path
def identity() -> dict[str, object]:
model = "unknown"
cpuinfo = Path("/proc/cpuinfo")
if cpuinfo.is_file():
for line in cpuinfo.read_text(errors="replace").splitlines():
if line.startswith(("model name\t", "Hardware\t", "Processor\t")):
model = line.partition(":")[2].strip()[:160]
break
return {"architecture": platform.machine(), "cpu_model": model,
"logical_cpus": os.cpu_count() or 1}
+42
View File
@@ -0,0 +1,42 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Remove generated Toolkit CI work after the release asset is uploaded."""
import os
from pathlib import Path
import shutil
import sys
ROOT = Path(__file__).resolve().parents[1]
DIRECTORIES = ("target", "dist", "coverage")
FILES = ("bench-current.txt",)
def cleanup() -> None:
if not os.environ.get("GITHUB_RUN_ID"):
raise ValueError("cleanup is restricted to CI runs")
for name in DIRECTORIES:
path = ROOT / name
if path.is_symlink() or path.parent.resolve() != ROOT.resolve():
raise ValueError(f"unsafe generated directory: {path}")
if path.is_dir():
shutil.rmtree(path)
print(f"Removed generated directory: {name}")
elif path.exists():
raise ValueError(f"expected a generated directory: {path}")
for name in FILES:
path = ROOT / name
if path.is_symlink() or path.parent.resolve() != ROOT.resolve():
raise ValueError(f"unsafe generated file: {path}")
if path.is_file():
path.unlink()
print(f"Removed generated file: {name}")
if __name__ == "__main__":
try:
cleanup()
except (OSError, ValueError) as error:
print(f"ERROR: Toolkit cleanup: {error}", file=sys.stderr)
raise SystemExit(1)
+13 -12
View File
@@ -2,10 +2,11 @@
# Measure line coverage from BOTH the unit tests AND the headless UI self-test.
#
# The self-test (ALKANE_SELFTEST=1) builds the real wxWidgets table, renders every
# fixture through the real widgets, and checks each cell against the model -- it
# exercises most of ui.rs. Because it runs as a separate binary invocation, a plain
# `cargo llvm-cov` (which only runs the #[test]s) never counts it, so ui.rs shows
# ~4% even though it is integration-tested. This combines both runs' coverage.
# fixture through the real widgets, and checks each cell against the model.
# It covers the fixture-rendering path, while interactive event handlers need
# separate tests. Because it runs as a separate binary invocation, a plain
# `cargo llvm-cov` (which only runs the #[test]s) never counts it. This
# combines both runs' coverage.
#
# Usage: ci/coverage.sh [extra `cargo llvm-cov report` args, e.g. --summary-only]
set -euo pipefail
@@ -16,8 +17,12 @@ export WX_RS_WXCONFIG="${WX_RS_WXCONFIG:-$HOME/.cache/wx-3.3.3-linux/bin/wx-conf
# default; override with CARGO_LLVM_COV_FLAGS if you need something else.
read -ra CARGO_FLAGS <<<"${CARGO_LLVM_COV_FLAGS:---offline}"
# A display for the self-test's real widgets.
need_xvfb() { command -v xvfb-run >/dev/null 2>&1; }
# A display is required for the self-test; skipping it would publish an
# incomplete coverage number as if the measured test set had run.
if ! command -v xvfb-run >/dev/null 2>&1; then
echo "coverage.sh: xvfb-run is required for the UI self-test" >&2
exit 1
fi
cargo llvm-cov clean --workspace
@@ -27,12 +32,8 @@ cargo llvm-cov --no-report "${CARGO_FLAGS[@]}" \
-p alkane-artifacts -p alkane-flash -p alkane-cli
# 2. Headless UI self-test, under the same instrumentation, its coverage appended.
if need_xvfb; then
xvfb-run -a env GDK_BACKEND=x11 ALKANE_SELFTEST=1 \
cargo llvm-cov run --no-report "${CARGO_FLAGS[@]}" --bin alkane-toolkit
else
echo "coverage.sh: xvfb-run not found; skipping the self-test run (unit tests only)" >&2
fi
xvfb-run -a env GDK_BACKEND=x11 ALKANE_SELFTEST=1 \
cargo llvm-cov run --no-report "${CARGO_FLAGS[@]}" --bin alkane-toolkit
# 3. Merged report, our source only (vendored asic-rs + the patched wx-rs bridge
# are out of scope).
+25 -14
View File
@@ -11,6 +11,7 @@ Metrics not passed on the command line are computed here (LOC from the source
tree, dependency count from Cargo.lock, license from Cargo.toml).
"""
import argparse
import math
import os
import re
import sys
@@ -107,13 +108,13 @@ def loc_color(n: int) -> str:
def bench_color(delta_pct: float) -> str:
# Negative delta = faster than the previous release. A +/-2% dead band absorbs
# the run-to-run jitter of microbenchmarks on a shared CI runner.
if delta_pct <= -2.0:
# Positive delta means faster than the previous release. A +/-2% band
# absorbs run-to-run jitter on the dedicated CI runner.
if delta_pct >= 2.0:
return "brightgreen"
if delta_pct < 2.0:
if delta_pct > -2.0:
return "blue"
if delta_pct < 10.0:
if delta_pct > -10.0:
return "yellow"
return "orange"
@@ -130,6 +131,12 @@ def cov_color(pct: float) -> str:
return "red"
def quality_grade(clippy: str | None) -> str:
if clippy is None:
return "pending"
return "A" if clippy == "clean" else "F"
def human(n: int) -> str:
suffixes = ("", "K", "M", "G")
value = float(n)
@@ -154,12 +161,14 @@ def main() -> int:
ap.add_argument("--coverage", type=float, default=None)
ap.add_argument("--bench-coverage", type=float, default=None)
ap.add_argument("--bench", default=None)
# Weighted-average microbench delta vs the previous release, as a signed
# percentage string (e.g. "-3.2"), or "NEW"/"" when there is no baseline yet
# (round 19 #1). Takes precedence over --bench for the bench badge.
# Mean per-benchmark improvement vs the previous release, as a signed
# percentage string, or "NEW" when there is no baseline.
ap.add_argument("--bench-delta", default=None)
ap.add_argument("--clippy", default="clean")
ap.add_argument("--clippy", choices=("clean", "failed"))
args = ap.parse_args()
for value in (args.coverage, args.bench_coverage):
if value is not None and (not math.isfinite(value) or not 0 <= value <= 100):
ap.error("coverage must be a finite percentage between 0 and 100")
os.makedirs(os.path.join(args.root, args.out), exist_ok=True)
@@ -176,8 +185,10 @@ def main() -> int:
write("loc", "lines of code", human(loc), loc_color(loc))
write("license", "license", lic, "blue")
write("dependencies", "dependencies", str(deps), "blue")
grade = "A" if args.clippy == "clean" else "F"
write("quality", "code quality", grade, "brightgreen" if grade == "A" else "red")
grade = quality_grade(args.clippy)
write("quality", "code quality", grade,
{"A": "brightgreen", "B": "yellowgreen", "C": "yellow",
"D": "orange", "F": "red", "pending": "lightgrey"}[grade])
if args.tests is not None:
write("tests", "tests", f"{args.tests} passing", "brightgreen")
if args.coverage is not None:
@@ -185,8 +196,8 @@ def main() -> int:
write("bench-coverage", "bench coverage",
f"{args.bench_coverage:.0f}%" if args.bench_coverage is not None else "pending",
cov_color(args.bench_coverage) if args.bench_coverage is not None else "lightgrey")
# Bench badge: prefer the weighted-average delta vs the previous release; fall
# back to the static label (first run, or when the delta could not be computed).
# Bench badge: prefer the mean per-benchmark improvement vs the previous
# release. Use the static label when no comparison is available.
delta = None
if args.bench_delta not in (None, "", "NEW"):
try:
@@ -194,7 +205,7 @@ def main() -> int:
except ValueError:
delta = None
if delta is not None:
# Negative = faster than the previous release (good).
# Positive = faster than the previous release.
msg = f"{'+' if delta > 0 else ''}{delta:.1f}% vs prev"
write("bench", "bench", msg, bench_color(delta))
elif args.bench_delta == "NEW":
+55
View File
@@ -0,0 +1,55 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Check that every Toolkit benchmark contributes to the release badge."""
import importlib.util
import re
from pathlib import Path
import unittest
ROOT = Path(__file__).resolve().parents[1]
spec = importlib.util.spec_from_file_location("bench_badge", ROOT / "ci/bench-badge.py")
assert spec is not None and spec.loader is not None
badge = importlib.util.module_from_spec(spec)
spec.loader.exec_module(badge)
badge_spec = importlib.util.spec_from_file_location("gen_badges", ROOT / "ci/gen-badges.py")
assert badge_spec is not None and badge_spec.loader is not None
gen_badges = importlib.util.module_from_spec(badge_spec)
badge_spec.loader.exec_module(gen_badges)
class BenchBadgeTests(unittest.TestCase):
def test_declared_suite_matches_rust_benchmarks(self):
names = set()
for directory in (ROOT / "crates/alkane-gui/src", ROOT / "crates/alkane-artifacts/src"):
for path in directory.rglob("*.rs"):
names.update(re.findall(
r'#\[test\]\s*#\[ignore(?:\s*=\s*"[^"]*")?\]\s*'
r'fn (bench_[A-Za-z0-9_]+)\s*\(', path.read_text()))
self.assertEqual(names, badge.EXPECTED_BENCHES)
def test_incomplete_duplicate_and_malformed_results_fail(self):
lines = [f"test tests::{name} ... {name}: 10ms/op"
for name in sorted(badge.EXPECTED_BENCHES)]
values = badge.require_suite(badge.parse_bench("\n".join(lines)))
self.assertEqual(len(values), 12)
with self.assertRaisesRegex(ValueError, "declared suite"):
badge.require_suite(badge.parse_bench("\n".join(lines[:-1])))
with self.assertRaisesRegex(ValueError, "duplicate"):
badge.parse_bench("\n".join(lines + [lines[0]]))
with self.assertRaisesRegex(ValueError, "missing timing"):
badge.parse_bench(lines[0].replace("10ms/op", "missing"))
def test_badge_averages_each_benchmark_improvement(self):
current = {"short": 50.0, "long": 900.0}
baseline = {"short": 100.0, "long": 1000.0}
self.assertEqual(badge.benchmark_delta(current, baseline), 30.0)
self.assertAlmostEqual(badge.benchmark_delta(baseline, current), -55.5555556)
self.assertIsNone(badge.benchmark_delta(current, {}))
self.assertEqual(gen_badges.bench_color(30.0), "brightgreen")
self.assertEqual(gen_badges.bench_color(-55.5555556), "orange")
if __name__ == "__main__":
unittest.main()
+26 -2
View File
@@ -7,10 +7,23 @@ from pathlib import Path
import unittest
sys.path.insert(0, str(Path(__file__).resolve().parent))
from bench_history import previous_measurement, render_html, updated_index
from bench_history import bench_badge, previous_measurement, render_html, updated_index
class HistoryTests(unittest.TestCase):
def test_cargo_nocapture_benchmark_lines_are_parsed(self):
output = (
"test tests::bench_verify_artifact ... bench_verify_artifact: 208.302µs\n"
"test model::tests::bench_render_cells ... bench_render_cells: "
"5000 rows x 10 cols = 8.007185ms/full-render (bytes=13553600)\n"
"bench_direct: 12ns/op\n"
)
self.assertEqual(bench_badge.parse_bench(output), {
"bench_verify_artifact": 208_302.0,
"bench_render_cells": 8_007_185.0,
"bench_direct": 12.0,
})
def test_retry_uses_previous_commit(self):
first = "a" * 40
second = "b" * 40
@@ -33,9 +46,20 @@ class HistoryTests(unittest.TestCase):
with self.assertRaises(ValueError):
updated_index({}, "a" * 40, {"bench_ns_per_op": {"hash": -1}}, "now")
def test_baseline_must_match_cpu_class(self):
host = {"architecture": "x86_64", "cpu_model": "A", "logical_cpus": 8}
other = {"architecture": "x86_64", "cpu_model": "B", "logical_cpus": 8}
index = {"entries": [{"sha": "a" * 40, "metrics": {
"bench_ns_per_op": {"hash": 10.0}, "bench_host": host}}]}
distance = lambda _ancestor, _sha: 1
self.assertEqual(previous_measurement(index, "b" * 40, distance, host),
{"hash": 10.0})
self.assertEqual(previous_measurement(index, "b" * 40, distance, other), {})
def test_site_escapes_history_content(self):
entry = {"sha": "a" * 40, "timestamp": "<script>alert(1)</script>",
"metrics": {"bench_ns_per_op": {"hash": 10.0}}}
"metrics": {"bench_ns_per_op": {"hash": 10.0},
"bench_host": {"cpu_model": "<script>cpu</script>"}}}
page = render_html({"entries": [entry]})
self.assertIn("&lt;script&gt;", page)
self.assertNotIn("<script>", page)
+20 -4
View File
@@ -52,6 +52,11 @@ impl VerifiedArtifact {
pub fn reader(&mut self) -> &mut File {
&mut self.file
}
/// Recheck the same descriptor immediately before a guarded write.
pub fn revalidate(&mut self) -> Result<(), VerifyError> {
verify_open_file(&mut self.file, &self.record)
}
}
pub fn seed_manifest() -> Result<Vec<ArtifactRecord>, VerifyError> {
@@ -118,9 +123,18 @@ fn signature_matches(format: &str, first: &[u8]) -> Result<bool, VerifyError> {
pub fn verify_file(path: &Path, record: &ArtifactRecord) -> Result<VerifiedArtifact, VerifyError> {
let mut file = File::open(path)?;
verify_open_file(&mut file, record)?;
Ok(VerifiedArtifact {
file,
record: record.clone(),
})
}
fn verify_open_file(file: &mut File, record: &ArtifactRecord) -> Result<(), VerifyError> {
if file.metadata()?.len() != record.size_bytes {
return Err(VerifyError::Size);
}
file.seek(SeekFrom::Start(0))?;
let mut first = [0_u8; 16];
let length = file.read(&mut first)?;
if !signature_matches(&record.format, &first[..length])? {
@@ -147,10 +161,7 @@ pub fn verify_file(path: &Path, record: &ArtifactRecord) -> Result<VerifiedArtif
return Err(VerifyError::Digest);
}
file.seek(SeekFrom::Start(0))?;
Ok(VerifiedArtifact {
file,
record: record.clone(),
})
Ok(())
}
#[cfg(test)]
@@ -189,9 +200,14 @@ mod tests {
applicability: "test".to_owned(),
};
let mut verified = verify_file(&path, &record).unwrap();
verified.revalidate().unwrap();
let mut replay = Vec::new();
verified.reader().read_to_end(&mut replay).unwrap();
assert_eq!(replay, bytes);
std::fs::write(&path, b"PK\x03\x04changed").unwrap();
assert!(matches!(verified.revalidate(), Err(VerifyError::Digest)));
std::fs::write(&path, bytes).unwrap();
verified.revalidate().unwrap();
record.size_bytes += 1;
assert!(matches!(
verify_file(&path, &record),
+2
View File
@@ -7,4 +7,6 @@ license.workspace = true
[dependencies]
alkane-core = { path = "../alkane-core" }
alkane-artifacts = { path = "../alkane-artifacts" }
sha2.workspace = true
thiserror.workspace = true
tempfile = "3"
+131 -10
View File
@@ -3,7 +3,8 @@
//! Board transport adapters must supply serial, recovery and readback evidence.
use alkane_artifacts::VerifiedArtifact;
use std::io::{Read, Seek, SeekFrom};
use sha2::{Digest, Sha256};
use std::io::{Read, Seek, SeekFrom, Write};
use thiserror::Error;
pub struct PartitionSpec {
@@ -65,6 +66,10 @@ pub enum FlashError {
ReadbackMismatch,
#[error("verified image has an invalid digest")]
InvalidDigest,
#[error("image changed since verification")]
ArtifactChanged,
#[error("writer did not consume the complete image")]
IncompleteWrite,
#[error("write transport: {0}")]
Write(String),
#[error("readback transport: {0}")]
@@ -85,6 +90,52 @@ fn digest_bytes(hex: &str) -> Result<[u8; 32], FlashError> {
Ok(result)
}
fn stage_verified_artifact(
artifact: &mut VerifiedArtifact,
size: u64,
expected: [u8; 32],
) -> Result<std::fs::File, FlashError> {
let mut staged = tempfile::tempfile().map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
artifact
.reader()
.seek(SeekFrom::Start(0))
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
let mut source = DigestReader {
inner: artifact.reader(),
remaining: size,
digest: Sha256::new(),
};
std::io::copy(&mut source, &mut staged).map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
if source.remaining != 0 || <[u8; 32]>::from(source.digest.finalize()) != expected {
return Err(FlashError::ArtifactChanged);
}
staged
.flush()
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
staged
.seek(SeekFrom::Start(0))
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
Ok(staged)
}
struct DigestReader<'a> {
inner: &'a mut dyn Read,
remaining: u64,
digest: Sha256,
}
impl Read for DigestReader<'_> {
fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
let limit = buffer
.len()
.min(usize::try_from(self.remaining).unwrap_or(usize::MAX));
let length = self.inner.read(&mut buffer[..limit])?;
self.remaining -= length as u64;
self.digest.update(&buffer[..length]);
Ok(length)
}
}
/// Stop before reboot. The caller must still prove live boot and persistence.
pub fn write_verified<W: Writer, R: IndependentReadback>(
partition: &PartitionSpec,
@@ -119,6 +170,13 @@ pub fn write_verified<W: Writer, R: IndependentReadback>(
return Err(FlashError::RecoveryRequired);
}
}
artifact
.revalidate()
.map_err(|_| FlashError::ArtifactChanged)?;
let expected = digest_bytes(&artifact.record().sha256)?;
// The source path may change while backup or transport I/O runs. Copy and
// verify it before any device write; the anonymous file is removed on drop.
let mut staged = stage_verified_artifact(artifact, size, expected)?;
let backup = writer
.backup(partition)
.map_err(|e| FlashError::Write(e.to_string()))?;
@@ -128,14 +186,21 @@ pub fn write_verified<W: Writer, R: IndependentReadback>(
{
return Err(FlashError::BackupIncomplete);
}
let expected = digest_bytes(&artifact.record().sha256)?;
artifact
.reader()
.seek(SeekFrom::Start(0))
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
let mut stream = DigestReader {
inner: &mut staged,
remaining: size,
digest: Sha256::new(),
};
writer
.write(partition, artifact.reader(), size)
.write(partition, &mut stream, size)
.map_err(|e| FlashError::Write(e.to_string()))?;
if stream.remaining != 0 {
return Err(FlashError::IncompleteWrite);
}
let written_digest: [u8; 32] = stream.digest.finalize().into();
if written_digest != expected {
return Err(FlashError::ArtifactChanged);
}
let actual = readback
.sha256(partition, size)
.map_err(|e| FlashError::Readback(e.to_string()))?;
@@ -162,8 +227,10 @@ mod tests {
serial: bool,
recovery: bool,
backup_bytes: u64,
max_read: Option<u64>,
writes: usize,
contents: Vec<u8>,
mutate_source_on_write: Option<PathBuf>,
}
impl Writer for MockWriter {
@@ -192,9 +259,19 @@ mod tests {
_: u64,
) -> Result<(), Self::Error> {
self.writes += 1;
image
.read_to_end(&mut self.contents)
.map_err(|_| "read failed")?;
if let Some(path) = &self.mutate_source_on_write {
std::fs::write(path, b"PK\x03\x04changed").map_err(|_| "mutation failed")?;
}
if let Some(limit) = self.max_read {
image
.take(limit)
.read_to_end(&mut self.contents)
.map_err(|_| "read failed")?;
} else {
image
.read_to_end(&mut self.contents)
.map_err(|_| "read failed")?;
}
Ok(())
}
}
@@ -236,8 +313,10 @@ mod tests {
serial: true,
recovery: true,
backup_bytes: 4096,
max_read: None,
writes: 0,
contents: Vec::new(),
mutate_source_on_write: None,
}
}
@@ -322,4 +401,46 @@ mod tests {
assert_eq!(writer.contents, IMAGE);
std::fs::remove_file(path).unwrap();
}
#[test]
fn refuses_changed_or_partially_consumed_artifacts() {
let (path, mut image) = artifact("changed");
let target = partition();
let mut writer = writer();
let mut readback = MockReadback {
channel: "serial",
digest: digest_bytes(SHA).unwrap(),
};
std::fs::write(&path, b"PK\x03\x04changed").unwrap();
assert!(matches!(
write_verified(&target, &mut image, &mut writer, &mut readback),
Err(FlashError::ArtifactChanged)
));
assert_eq!(writer.writes, 0);
std::fs::write(&path, IMAGE).unwrap();
writer.max_read = Some(4);
assert!(matches!(
write_verified(&target, &mut image, &mut writer, &mut readback),
Err(FlashError::IncompleteWrite)
));
assert_eq!(writer.writes, 1);
std::fs::remove_file(path).unwrap();
}
#[test]
fn writes_verified_snapshot_when_source_changes_during_transport() {
let (path, mut image) = artifact("mutated-during-write");
let mut writer = writer();
writer.mutate_source_on_write = Some(path.clone());
let mut readback = MockReadback {
channel: "serial",
digest: digest_bytes(SHA).unwrap(),
};
let receipt = write_verified(&partition(), &mut image, &mut writer, &mut readback).unwrap();
assert_eq!(receipt.image_sha256, digest_bytes(SHA).unwrap());
assert_eq!(writer.contents, IMAGE);
assert_eq!(std::fs::read(&path).unwrap(), b"PK\x03\x04changed");
std::fs::remove_file(path).unwrap();
}
}
+32
View File
@@ -2604,6 +2604,38 @@ mod tests {
assert!(per.as_millis() < 100, "cell rendering regressed: {per:?}");
}
/// Microbenchmark: component health scores and operator-facing diagnostics
/// recomputed when scan results refresh the table.
#[test]
#[ignore]
fn bench_health_diagnostics() {
use std::hint::black_box;
use std::time::Instant;
let rows = bench_fleet();
let iters = 1000u32;
let start = Instant::now();
let mut sink = 0usize;
for _ in 0..iters {
for row in &rows {
for facet in [
HealthFacet::Overall,
HealthFacet::Power,
HealthFacet::Fans,
HealthFacet::Boards,
] {
sink += black_box(row.health_score(facet)) as usize;
}
sink += row.health_summary().len();
sink += row.health_tooltips(4, 3).iter().map(String::len).sum::<usize>();
}
}
black_box(sink);
let per = start.elapsed() / iters;
println!("bench_health_diagnostics: {} rows = {:?}/refresh", rows.len(), per);
assert!(per.as_millis() < 20, "health diagnostics regressed: {per:?}/refresh");
}
#[test]
fn selection_survives_upsert() {
let mut rows = bench_fleet();
+34 -1
View File
@@ -58,7 +58,11 @@ pub fn firmware_family(raw: &str) -> (String, Option<String>) {
// Vendor prefixes asic-rs prepends on stock-firmware family strings, matched
// case-insensitively.
for vendor in ["AntMiner", "WhatsMiner"] {
if trimmed.len() > vendor.len() && trimmed[..vendor.len()].eq_ignore_ascii_case(vendor) {
if trimmed.len() > vendor.len()
&& trimmed
.get(..vendor.len())
.is_some_and(|prefix| prefix.eq_ignore_ascii_case(vendor))
{
let rest = trimmed[vendor.len()..].trim();
if !rest.is_empty() {
return (rest.to_string(), Some(vendor.to_string()));
@@ -477,6 +481,35 @@ mod tests {
assert_eq!(firmware_family("Braiins"), ("Braiins".to_string(), None));
// A bare vendor word with nothing after it is left as-is (not emptied).
assert_eq!(firmware_family("AntMiner"), ("AntMiner".to_string(), None));
// Firmware strings arrive from the network and may contain UTF-8 at
// the byte position used to check a vendor prefix.
let non_ascii = "AntMine\u{e9} Stock";
assert_eq!(firmware_family(non_ascii), (non_ascii.to_string(), None));
}
#[test]
#[ignore = "microbenchmark"]
fn bench_naming_transforms() {
let cases = [
("Antminer", "S19jPro", "AntMiner Stock", "Xilinx"),
("Antminer", "S21Pro", "VNish", "CVITek"),
("Whatsminer", "M30SPlusVE40", "WhatsMiner Stock", "H616"),
("Whatsminer", "M50SPlusPlusVK30", "Braiins", "H6"),
];
let iterations = 20_000;
let started = std::time::Instant::now();
for index in 0..iterations {
let (make, model, firmware, board) = cases[index % cases.len()];
let clean = clean_model(make, model);
std::hint::black_box(firmware_family(firmware));
std::hint::black_box(control_board_code(make, board, &clean));
std::hint::black_box(chip_type_for_model(make, model));
std::hint::black_box(clean);
}
let elapsed = started.elapsed();
let per = elapsed / iterations as u32;
println!("bench_naming_transforms: {per:?}/record");
assert!(elapsed < std::time::Duration::from_millis(500));
}
#[test]
+6 -6
View File
@@ -1,10 +1,10 @@
# UI Spec — primary view
# Primary view
Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
## Header (above the table)
## Header
- **KPI block, top left — 6 KPIs:**
- **KPI block, top left: 6 KPIs:**
1. Total miners
2. Hashing
3. Slow
@@ -31,7 +31,7 @@ Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
4. Cooling (fan)
5. Firmware
6. Pool worker account name
7. …then the remaining statistics in registry order.
7. Remaining statistics in registry order.
## Data sources
@@ -45,10 +45,10 @@ Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
ships with the board registry; missing band = excluded from Slow, counted
in Hashing).
## Implementation notes
## Implementation
- wxWidgets: the view is a `wxDataViewListCtrl`/`wxDataViewCtrl` (virtual
list — thousands of rows without materializing cells), checkbox column +
list for thousands of rows without materializing cells), checkbox column +
IP column fixed via attribute/serializer, drag reorder via `wxReorderable`
column events, sort via column header click events mapped to the model.
- Filter panel: per-column distinct-value checklist with text search,
+1 -1
View File
@@ -1,4 +1,4 @@
# ADR 0001: Recipes as data, interpreted by one engine
# ADR 0001: Recipe engine
Status: ACCEPTED
Date: 2026-09-14
+15 -29
View File
@@ -1,41 +1,27 @@
# ADR 0002: GUI bindings — wxWidgets shell in C++ + Rust core, spike to revisit
# ADR 0002: GUI bindings
Status: RESOLVED 2026-09-15 - the operator chose Option B (pure Rust via
wx-rs) with vendoring (ADR-0003). wx-rs 0.2.0 was extended via the patch
queue: Linux/GTK3 wx-config build path plus the widget bridge (panel,
sizers, static text, button, text ctrl, checkbox, checklistbox, dialog,
data view list ctrl, timer). The app ships this way; no C++ shell.
Date: 2026-09-14
Resolved: 2026-09-15
## Context
The toolkit must present a native cross-platform GUI (wxWidgets chosen).
Rust bindings to wxWidgets checked on crates.io 2026-09-14:
- `wxRust` 0.0.1-alpha — unmaintained since 2022.
- `wx-rs` 0.2.0 (2023, self-contained) — ~6k downloads, no 1.0.
Betting the GUI on alpha bindings risks weeks of binding-gap debugging
(paste-heavy widgets, worker threads + event loops, GTK/WinCocoa quirks).
The toolkit needs a native wxWidgets GUI. At the time of evaluation,
`wxRust` 0.0.1-alpha had seen no maintenance since 2022, and `wx-rs`
0.2.0 lacked widgets needed for the Toolkit.
## Decision
Default: **thin C++17 wxWidgets shell (`gui/`) + Rust core exposed over a
small stable C ABI** (cdylib from `alkane-core`, header generated with
cbindgen). The shell holds frames, lists, the install wizard, and event
glue only — no business logic, no safety logic. All invariants, engines,
and tests live in Rust where they are testable headlessly.
The operator chose a Rust GUI through a vendored, patched `wx-rs` 0.2.0.
The patch queue adds the Linux/GTK3 build path and bindings for panels,
sizers, controls, dialogs, data views, timers, and event dispatch. The
application uses this bridge; it has no separate C++ shell.
Gate: M0 runs a time-boxed `wx-rs` spike (window + list/tree + wizard flow
+ worker-thread progress + cancel on Linux and Windows). If the spike is
solid, flip to pure Rust; either way the decision is recorded before M3.
The original proposal was a small C++17 wxWidgets shell calling a Rust
core through a C ABI. The `wx-rs` spike met the GUI need, so that proposal
was not adopted.
## Consequences
- The repo builds two things: a Rust workspace and a small C++ app linked
against the core cdylib. CMake in `gui/`.
- Core API surface stays small and event-oriented (discover, identify,
plan, execute, cancel, progress events, log tail) — good FFI hygiene and
a natural match for the CLI too (D4).
- If wx-rs wins the spike, the C ABI is kept as an integration boundary for
scripted/HIL use anyway.
- Keep business logic and safety checks in testable Rust code.
- Carry wx-rs changes as numbered patches under `thirdparty/wx-rs/patches`.
- Recheck the bridge on Linux, Windows, and macOS packaging changes.
+2 -2
View File
@@ -1,4 +1,4 @@
# ADR 0003: Vendoring policy — pristine upstream archives + patch queue
# ADR 0003: Vendoring
Status: ACCEPTED
Date: 2026-09-15
@@ -42,7 +42,7 @@ thirdparty/
Rules:
1. Never edit a vendored pristine tree in place — every local change is a
1. Never edit a vendored pristine tree in place. Every local change is a
patch in `patches/`, applied by the build in numeric order. This makes
an upstream update: replace pristine archive, `git apply` surviving
patches, rebase the rest.
+1
View File
@@ -5,6 +5,7 @@
# scripts/build-wx-linux.sh to produce it).
set -e
REPO=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
trap 'bash "$REPO/scripts/clean-old-builds.sh" || true' 0
WX_PREFIX="${1:-$HOME/.cache/wx-3.3.3-linux}"
if [ ! -x "$WX_PREFIX/bin/wx-config" ]; then
"$REPO/scripts/build-wx-linux.sh"
+15
View File
@@ -6,6 +6,21 @@ REPO=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
SRC="$REPO/thirdparty/wxwidgets/wxWidgets-3.3.3"
BUILD="$HOME/.cache/wxbuild/wxWidgets-3.3.3"
PREFIX="$HOME/.cache/wx-3.3.3-linux"
cleanup_wx_build() {
python3 - "$BUILD" "$HOME/.cache/wxbuild" <<'PY'
from pathlib import Path
import shutil
import sys
build, parent = map(Path, sys.argv[1:])
if (build.name != "wxWidgets-3.3.3" or build.parent != parent
or build.is_symlink() or parent.is_symlink()):
raise SystemExit("refusing unsafe wxWidgets build cleanup path")
if build.is_dir():
shutil.rmtree(build)
PY
}
trap cleanup_wx_build 0
[ -d "$BUILD" ] || { mkdir -p "$HOME/.cache/wxbuild"; cp -r "$SRC" "$BUILD"; }
[ -d "$BUILD" ] || { echo "thirdparty wxWidgets tree missing"; exit 1; }
chmod +x "$BUILD/configure" "$BUILD/config.guess" "$BUILD/config.sub" "$BUILD/install-sh" 2>/dev/null || true
+9
View File
@@ -18,6 +18,15 @@
set -uo pipefail
TARGET="${CARGO_TARGET_DIR:-$HOME/.cache/alkane-tk-target}"
REPO="$(cd "$(dirname "$0")/.." && pwd)"
case "$(realpath -m "$TARGET")" in
"$HOME/.cache/alkane-tk-target"|"$REPO/target") ;;
*) echo "clean-old-builds: refusing unexpected target $TARGET" >&2; exit 1 ;;
esac
if [ -L "$TARGET" ]; then
echo "clean-old-builds: refusing symlink target $TARGET" >&2
exit 1
fi
if [ ! -d "$TARGET" ]; then
echo "clean-old-builds: no target dir at $TARGET (nothing to do)"
exit 0
+27 -17
View File
@@ -8,13 +8,13 @@
#
# Usage: scripts/ui-screenshot.sh [out.png] [--live] [binary]
set -u
REPO=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
REPO=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)
WX_PREFIX="${WX_PREFIX:-$HOME/.cache/wx-3.3.3-linux}"
export WX_RS_WXCONFIG="${WX_RS_WXCONFIG:-$WX_PREFIX/bin/wx-config}"
OUT="${1:-alkane-toolkit.png}"
LIVE=0; BIN=""
shift 2>/dev/null || true
[ "$#" -eq 0 ] || shift
for a in "$@"; do
case "$a" in
--live) LIVE=1 ;;
@@ -32,17 +32,31 @@ if [ -z "$BIN" ]; then
fi
[ -x "$BIN" ] || { echo "binary not found: $BIN" >&2; exit 3; }
DISP=":98"
FAKE_ENV="ALKANE_FAKE_SCAN=1"
[ "$LIVE" = "1" ] && FAKE_ENV=""
Xvfb "$DISP" -screen 0 1280x850x24 -nolisten tcp >/dev/null 2>&1 &
DISPLAY_FILE=$(mktemp)
XPID=""; APID=""; WARM=""
cleanup() {
[ -z "$APID" ] || kill "$APID" 2>/dev/null || true
[ -z "$WARM" ] || kill "$WARM" 2>/dev/null || true
[ -z "$XPID" ] || kill "$XPID" 2>/dev/null || true
rm -f "$DISPLAY_FILE"
}
trap cleanup EXIT
Xvfb -displayfd 3 -screen 0 1280x850x24 -nolisten tcp 3>"$DISPLAY_FILE" >/dev/null 2>&1 &
XPID=$!
sleep 1.2
for _ in {1..30}; do
[ -s "$DISPLAY_FILE" ] && break
kill -0 "$XPID" 2>/dev/null || { echo "Xvfb exited before startup" >&2; exit 3; }
sleep 0.1
done
[ -s "$DISPLAY_FILE" ] || { echo "Xvfb did not start" >&2; exit 3; }
DISP=":$(cat "$DISPLAY_FILE")"
# warm the font/GTK caches so the first window map is not stalled
DISPLAY="$DISP" xclock >/dev/null 2>&1 & WARM=$!; sleep 1.2; kill "$WARM" 2>/dev/null
# shellcheck disable=SC2086
DISPLAY="$DISP" GDK_BACKEND=x11 $FAKE_ENV "$BIN" >/dev/null 2>&1 &
if [ "$LIVE" = "1" ]; then
DISPLAY="$DISP" GDK_BACKEND=x11 "$BIN" >/dev/null 2>&1 &
else
DISPLAY="$DISP" GDK_BACKEND=x11 ALKANE_FAKE_SCAN=1 "$BIN" >/dev/null 2>&1 &
fi
APID=$!
WID=""; t=0
while [ "$t" -lt 25 ]; do
@@ -52,10 +66,6 @@ while [ "$t" -lt 25 ]; do
[ -n "$line" ] && { WID=$(echo "$line" | awk '{print $1}'); break; }
done
sleep 2 # let it paint and drain a scan tick
if [ -n "$WID" ]; then
DISPLAY="$DISP" import -window "$WID" "$OUT" && echo "wrote $OUT (window $WID, ${t}s)"
else
DISPLAY="$DISP" import -window root "$OUT"; echo "no app window; captured root -> $OUT" >&2
fi
kill "$APID" 2>/dev/null
kill "$XPID" 2>/dev/null
[ -n "$WID" ] || { echo "no app window mapped" >&2; exit 1; }
DISPLAY="$DISP" import -window "$WID" "$OUT" || exit 1
echo "wrote $OUT (window $WID, ${t}s)"