Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
trim_trailing_whitespace = true

[*.py]
indent_size = 4

[*.{js,json,yml,yaml,sh}]
indent_size = 2

[*.md]
trim_trailing_whitespace = false
22 changes: 22 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
name: Bug report
description: Report reproducible application behavior.
body:
- type: textarea
id: environment
attributes:
label: Environment
description: App version, distribution, Python/GTK/Libadwaita versions, desktop/compositor, and Bolt or Bluetooth.
validations:
required: true
- type: textarea
id: reproduction
attributes:
label: Steps, expected result, and actual result
validations:
required: true
- type: textarea
id: diagnostics
attributes:
label: Diagnostics and relevant logs
description: Include doctor --json or a traceback when relevant. Remove device serials, usernames, and other private information.
render: text
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
blank_issues_enabled: true
contact_links:
- name: Security reporting
url: https://github.com/Dijo-404/mx4-linux/blob/main/SECURITY.md
about: Read private reporting guidance before sharing security-sensitive information.
16 changes: 16 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
name: Feature request
description: Describe a mouse-control or desktop workflow improvement.
body:
- type: textarea
id: problem
attributes:
label: What task is difficult today?
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposed behavior
description: Include the target desktop/compositor and connection type if relevant.
validations:
required: true
11 changes: 11 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
- package-ecosystem: pip
directory: /
schedule:
interval: monthly
open-pull-requests-limit: 3
10 changes: 10 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
Describe the problem and the behavior after this change.

## Validation

- [ ] Python checks pass (`pytest`, `ruff`, compilation).
- [ ] Launcher/package checks pass when packaging changes (`npm test`, `npm run check`, `npm run test:package`).
- [ ] GUI changes checked with `gui --demo`, including reduced motion and keyboard access.
- [ ] Documentation and `CHANGELOG.md` updated for user-visible changes.

State any remaining limitations. For hardware changes, distinguish simulated checks from physical-device observations and describe settings changed.
96 changes: 96 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
name: CI

on:
push:
branches: [main]
pull_request:
workflow_dispatch:
workflow_call:

permissions:
contents: read

concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
python:
name: Python ${{ matrix.python }}
runs-on: ubuntu-24.04
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
python: ['3.11', '3.14']
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
with:
persist-credentials: false
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
with:
python-version: ${{ matrix.python }}
cache: pip
cache-dependency-path: pyproject.toml
- name: Install native build dependencies
run: |
sudo apt-get update
sudo apt-get install --no-install-recommends -y gcc pkg-config libdbus-1-dev libcairo2-dev libgirepository-2.0-dev gir1.2-gtk-4.0 gir1.2-adw-1
- name: Install application and development tools
run: python -m pip install -e '.[test,dev]'
- name: Check Python correctness
run: |
python -m ruff check src tests scripts/gtk-smoke.py
python -m compileall -q src tests
python -m pytest -q
- name: Validate shell scripts and udev rules
run: |
for script in scripts/*.sh; do bash -n "$script"; done
udevadm verify data/70-mx4-linux.rules data/71-mx4-input.rules
- name: Build Python distributions
run: python -m build

npm:
name: npm / Node ${{ matrix.node }}
runs-on: ubuntu-24.04
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
node: ['22', '24']
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
with:
persist-credentials: false
- uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
with:
node-version: ${{ matrix.node }}
- name: Test launcher and install packed application
run: |
npm ci --ignore-scripts
npm test
npm run check
npm run test:package

gtk:
name: Native runtime and GTK smoke
runs-on: ubuntu-24.04
timeout-minutes: 15
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
with:
persist-credentials: false
- uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
with:
node-version: '24'
- name: Install desktop dependencies
run: |
sudo apt-get update
sudo apt-get install --no-install-recommends -y python3-venv python3-gi python3-gi-cairo python3-cairo python3-dbus gir1.2-gtk-4.0 gir1.2-adw-1 xvfb xauth dbus-x11
- name: Install the npm archive, set up its native runtime, and preview GUI
env:
PYTHON: /usr/bin/python3
GDK_BACKEND: x11
run: |
npm ci --ignore-scripts
dbus-run-session -- xvfb-run -a npm run test:native
52 changes: 52 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
name: Build release packages

on:
release:
types: [published]
workflow_dispatch:

permissions:
contents: read

jobs:
checks:
uses: ./.github/workflows/ci.yml
package:
name: Build verified release artifacts
needs: checks
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
with:
persist-credentials: false
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
with:
python-version: '3.14'
- uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
with:
node-version: '24'
- name: Verify release tag matches package versions
env:
RELEASE_TAG: ${{ github.event.release.tag_name }}
run: |
node --input-type=module - <<'JS'
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
const { version } = JSON.parse(readFileSync('package.json', 'utf8'));
if (process.env.RELEASE_TAG) assert.equal(process.env.RELEASE_TAG, `v${version}`, 'Use a release tag matching the package version');
JS
- name: Build archives and checksums
run: |
python -m pip install 'build>=1.2,<2'
python -m build
npm ci --ignore-scripts
npm run check
npm pack --pack-destination dist
sha256sum dist/*.whl dist/*.tar.gz dist/*.tgz > dist/SHA256SUMS
- uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
with:
name: mx4-linux-release
path: dist/
if-no-files-found: error
retention-days: 30
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,8 @@ __pycache__/
.pytest_cache/
build/
dist/
node_modules/
*.tgz
.ruff_cache/
evidence/artifacts/
evidence/*.png
37 changes: 37 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Changelog

User-visible changes are recorded here. This project follows semantic versioning; 0.x releases may change configuration or behavior with migration notes.

## [Unreleased]

### Added

- Linux npm launcher with explicit per-user Python setup, bundled application sources and icons, and `npm start` support.
- Separate Mouse, Actions and Profiles views, an animated wheel preview, and clearer ring and Smart Actions controls.
- Compact circular icon ring with animated radial opening, outward hover labels, a center close button and a live labeled editor preview.
- Optional side menus containing up to six existing routines, with pointer and keyboard selection and safe held-button release.
- Finite ring transitions and selection feedback that honor the desktop's reduced-motion preference.
- GitHub CI for Python 3.11/3.14, Node 22/24, package installation and native GTK smoke checks; validated release archives and checksums.
- Development checks, contribution conventions and issue/PR templates.

### Improved

- Keep Python dependencies in `pyproject.toml` and share the packaged SVG icon with the README.
- Detect unused imports in development and CI checks.
- Setting changes update the confirmed value without a complete follow-up discovery scan; saving profiles keeps existing device data.
- Ring rendering reuses native labels and controls, reducing work during animation.
- Hardware writes and listener startup address the selected receiver slot; setting writes construct only the needed capabilities while preserving live validation and readback.
- Bounded optional paired-node discovery removes repeated one-second waits; event bursts share a GTK dispatch while preserving movement and release order.

## [0.2.0] — unreleased baseline

- Native GTK 4 / Libadwaita control panel and CLI using Solaar 1.1.20.
- Supported settings, diagnostics, haptic playback and manual hardware profiles.
- Eight-position Actions Ring, Smart Actions editor and opt-in extra-button bindings for Niri on Wayland.
- Cancellable action execution, focus restoration and exact event-reporting cleanup.
- Optional native wtype helper, separate hidraw/uinput access installers, and application icon.

Physical settings, panel interaction, haptic feel, Bluetooth and reconnect behavior still need interactive validation. Flow remains deferred.

[Unreleased]: https://github.com/Dijo-404/mx4-linux/commits/main
[0.2.0]: https://github.com/Dijo-404/mx4-linux
42 changes: 42 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,31 @@ git clone https://github.com/Dijo-404/mx4-linux.git
cd mx4-linux
./scripts/setup.sh
.venv/bin/python -m pytest -q
.venv/bin/python -m ruff check src tests scripts/gtk-smoke.py
.venv/bin/python -m compileall -q src tests
for script in scripts/*.sh; do bash -n "$script"; done
npm ci --ignore-scripts
npm test
npm run check
npm run test:package
```

Build outputs (`build/`, `dist/`), pytest/Ruff caches, `__pycache__/` and source `*.egg-info/` directories are generated and can be removed when no longer needed. Keep `.venv/` for the installed development runtime. `.tools/` also holds the installed wtype checksum used by setup; its downloaded source and build directories are disposable.

The tracked records in `evidence/` support the research and validation guides. Current documentation images live in `docs/assets/`; the README shares the application icon from `src/mx4_linux/icons/`.

Use `.venv/bin/mx4-linux gui --demo` to inspect the settings interface without device access, and `actions run ID --dry-run` or `ring --preview` to inspect desktop behavior without executing a routine. Tests use simulated hardware; passing them is not a physical-device verification.

On a graphical session, `GDK_BACKEND=x11 .venv/bin/python scripts/gtk-smoke.py` checks demo loading, finite wheel/ring animations, reduced motion and the editor. For a headless machine with Xvfb installed:

```bash
GDK_BACKEND=x11 dbus-run-session -- xvfb-run -a .venv/bin/python scripts/gtk-smoke.py
```

The smoke script uses a temporary configuration directory and preview callbacks; it does not execute routines or write hardware settings. For UI changes, also check the actual window at narrow and normal widths, keyboard navigation, visible focus, both color schemes and disabled desktop animations.

`PYTHON=/usr/bin/python3 GDK_BACKEND=x11 npm run test:native` additionally installs the real npm archive into a temporary prefix, performs setup in an isolated XDG directory, checks its CLI and exercises the installed GTK runtime. It downloads Python dependencies; use the system interpreter that can import GObject. CI runs this under Xvfb.

If changing udev files, check their syntax when `udevadm` is available:

```bash
Expand All @@ -31,9 +50,32 @@ udevadm verify data/70-mx4-linux.rules data/71-mx4-input.rules
- Preserve opt-in diversion, exact reporting restoration and cancelled cleanup releases. Include regression coverage for meaningful lifecycle or validation changes.
- Keep command steps as explicit argument arrays, validate complete documents before writes and preserve cancellation/held-key cleanup.
- Update documentation when commands, configuration, access rules or supported behavior change.
- Add a concise user-visible entry under `Unreleased` in [CHANGELOG.md](CHANGELOG.md).

Do not bundle vendor installers, downloaded proprietary binaries, virtual environments, build caches or personal configuration. Avoid user paths, device serials and unrelated desktop content in new screenshots and reports.

## Code conventions and boundaries

- Use Python 3.11-compatible syntax, four-space indentation, descriptive `snake_case` names and small functions. Match the touched module's style; keep unrelated formatting out of the diff. Ruff checks syntax, definite correctness errors and unused imports through the checked-in configuration.
- Keep GTK construction and widget updates on the GTK thread. Run device I/O and potentially blocking desktop work off that thread; return results through the existing callbacks. Do not rescan hardware when a confirmed write response is sufficient.
- Keep Solaar imports and handles in workers. UI modules depend on the backend interface, and animation/state models remain testable without GTK or hardware. Add a layer only when a concrete second caller needs it.
- Animate on GTK's frame clock using elapsed time. Stop callbacks when motion settles or a widget hides; honor `gtk-enable-animations`. Native labels, keyboard operation and accessible names must remain available.
- Node code uses built-in modules, explicit argument arrays and two-space indentation. The npm launcher stays a small bridge to the native application. Keep npm installation free of hooks that install Python, invoke sudo, access devices or start the GUI.
- Validate external JSON and process responses before use. Preserve atomic configuration writes, cancellation, worker deadlines and actionable error messages. Avoid logging serials or private desktop contents.
- Add a focused regression test for changed validation, lifecycle or subprocess behavior. Avoid tests that only repeat constants or widget construction without checking behavior.

The architecture guide describes responsibilities. Keep shared behavior in its existing owner instead of duplicating it across GUI, CLI and package entry points. `.editorconfig` defines whitespace, `pyproject.toml` defines Python metadata/checks, and `package.json` defines the npm launch surface.

## CI and release preparation

CI tests Python 3.11 and 3.14, Node 22 and 24, actual npm archive installation, and a native GTK demo smoke test on Ubuntu 24.04. Native tests do not establish Niri/Wayland or physical hardware compatibility. GitHub Actions dependencies are pinned by commit; Dependabot proposes updates for review. Solaar updates need deliberate worker compatibility validation because internal APIs are used.

Before a release, update `pyproject.toml`, `src/mx4_linux/__init__.py`, `package.json` and `package-lock.json` together, move reviewed changelog entries into a dated version, then run the checks above. `npm run check` rejects differing package versions and missing runtime assets. Inspect `npm pack --dry-run` and build Python distributions with `.venv/bin/python -m build`.

The **Build release packages** workflow runs manually or when a GitHub release is published. It requires CI, verifies a release tag of `vVERSION`, and uploads wheel, source archive, npm archive and SHA-256 checksums as an Actions artifact. It does not publish to npm or PyPI. Download and review that artifact before a maintainer publishes it.

For an initial npm release, verify ownership/availability of the package name, use an npm account with publishing rights and 2FA, and publish the reviewed `.tgz` with `npm publish ./mx4-linux-VERSION.tgz --access public`. Configure [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) before adding automatic registry publication; [npm package metadata](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/) documents `bin`, packaged files and platform requirements. Registry configuration and publication are maintainer actions outside application setup.

## Bug reports and hardware validation

Include the application version, distribution, Python/GTK/Libadwaita versions, compositor/session, Bolt or Bluetooth connection, steps to reproduce and the actual error. Relevant `doctor --json` and `devices --json` output helps; redact identifying details first.
Expand Down
7 changes: 7 additions & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
include CHANGELOG.md CONTRIBUTING.md SECURITY.md package*.json .editorconfig
recursive-include bin *.js
recursive-include scripts *.sh *.py *.js
recursive-include data *.rules
recursive-include docs *.md *.png
recursive-include tests *.py *.js
recursive-include .github *.yml *.md
Loading
Loading