Skip to content

Migrate CLI to Rust with Tauri UI and PyO3 bridge #14

Closed

Description

@zackees

Migrate CLI to Rust with Tauri UI and PyO3 bridge

Orchestration process

Each phase is a sub-issue. The workflow for every phase:

  1. Branch from main (e.g. rust/phase-1a-scaffold)
  2. Implement the phase tasks
  3. Push and open a PR referencing the sub-issue
  4. CI must be green -- if red, fix on the branch until green
  5. Merge to main once CI passes
  6. Close the sub-issue
  7. Start the next phase from the updated main

Dependencies between phases are strict -- do not start a phase until its prerequisites are merged to main. Phases 2b, 2c, 2d are independent of each other and can run in parallel after 2a merges.

Phase 1a  ->  Phase 1b  ->  Phase 1c
                                |
                            Phase 2a
                           /   |    \
                        2b    2c    2d
                           \   |    /
                            Phase 2e
                                |
                            Phase 3a
                                |
                            Phase 3b
                                |
                            Phase 4

Sub-issues

Phase 1: Scaffold

Phase 2: Port core logic

Phase 3: Tauri UI

Phase 4: Ship


Motivation

The CLI is currently pure Python. Migrating to Rust gives us:

  • Startup time: ~5ms vs ~300-500ms Python interpreter startup
  • Single binary distribution: No Python runtime required for end users
  • Tauri UI: Replace Flask HTTP server + system browser with a native webview window (~3 MB vs ~200 MB Playwright Chromium)
  • Consistency with other tools: running-process already uses this pattern

Reference implementation: zackees/running-process

The running-process repo provides the blueprint:

Project structure

Cargo.toml                    # Workspace root
rust-toolchain.toml           # Pinned Rust version
pyproject.toml                # maturin build backend

crates/
  running-process-core/       # Pure Rust library (no Python)
  running-process-py/         # PyO3 cdylib bridge -> running_process._native

src/
  running_process/            # Python package (imports from _native)

ci/                           # Python-based CI orchestration

Key patterns to replicate

  • Cargo workspace with pure-Rust core crate + PyO3 bridge crate
  • maturin as Python build backend with abi3-py310 (one wheel for Python 3.10+)
  • sccache in CI via mozilla-actions/sccache-action@v0.0.9 + SCCACHE_GHA_ENABLED=true + RUSTC_WRAPPER=sccache, combined with Swatinem/rust-cache@v2 (registry only, cache-targets: false)
  • Reusable workflow templates (_build.yml, _lint.yml, etc.) called by thin per-platform workflows
  • Fingerprint-based dev builds to skip unnecessary recompilation

CI matrix (6 platforms)

Platform Runner
Linux x86 ubuntu-24.04
Linux ARM ubuntu-24.04-arm
Windows x86 windows-2025
Windows ARM windows-11-arm
macOS x86 macos-15-intel
macOS ARM macos-15

Proposed architecture

fastled-wasm/
  Cargo.toml                       # Workspace root
  rust-toolchain.toml              # Pinned Rust toolchain
  pyproject.toml                   # maturin build backend

  crates/
    fastled-cli/                   # Pure Rust binary (the CLI)
      src/
        main.rs                    # Entry point, clap args
        watcher.rs                 # File watching (notify crate)
        build.rs                   # Compilation orchestration
        archive.rs                 # Toolchain download/extract
        project.rs                 # Project init, sketch detection
        keyboard.rs                # Terminal input (termios/Win32)

    fastled-tauri/                 # Tauri UI viewer (separate binary)
      src/
        main.rs                    # Tauri app, window management
        ipc.rs                     # JS <-> Rust commands
      tauri.conf.json

    fastled-py/                    # PyO3 bridge crate (cdylib)
      src/
        lib.rs                     # #[pymodule] exposing Rust to Python

  src/
    fastled/                       # Python package (imports from _native)
      toolchain/
        internal_wasm_build.py     # Stays Python (Meson/Ninja orchestration)
      playwright/                  # Stays Python (browser automation)

Runtime flow

fastled --just-compile examples/Wasm
  -> Rust CLI parses args (clap)
  -> Detects sketch directory (Rust)
  -> Calls Python subprocess for WASM build
  |    -> internal_wasm_build.py (Meson/Ninja)
  -> Reports results

fastled --app examples/Wasm
  -> Rust CLI parses args
  -> Spawns Tauri viewer (sidecar binary)
  |    -> Native webview window, no localhost server
  |    -> Loads frontend assets directly (no HTTP, no CORS)
  |    -> IPC for debug symbol resolution
  -> Watches files (notify crate)
  -> On change: calls Python subprocess for rebuild
  -> Notifies Tauri viewer to reload

What moves to Rust vs stays Python

MIGRATE TO RUST (~90% of codebase)

Module LOC Rust replacement
parse_args.py + args.py 395 clap
filewatcher.py 307 notify crate
server_flask.py 226 Eliminated by Tauri
open_browser.py 211 Eliminated by Tauri
emscripten_archive.py 250 reqwest + tar/zstd
frontend_esbuild.py 227 reqwest + zip
project_init.py 419 reqwest + zip
keyboard.py 120 termios/Win32 API
debug_symbols.py 212 Rust path resolution
debug_routes.py 47 Tauri IPC command
build_service.py + build_types.py 279 Rust structs
compile_native.py 189 Rust orchestration loop
Utilities (emoji, spinner, types, etc.) ~300 Standard Rust

KEEP AS PYTHON (called via subprocess)

Module LOC Reason
toolchain/internal_wasm_build.py 1,696 Orchestrates Meson/Ninja C++ build system
toolchain/emscripten.py 879 Emscripten env setup, delegates to internal_wasm_build
playwright/* 1,153 Playwright Python library dependency
select_sketch_directory.py 160 Interactive prompts (low priority to port)

BRIDGE VIA PyO3 (for pip install fastled compatibility)

The PyO3 bridge crate exposes the Rust CLI functionality as a Python module (fastled._native) so that pip install fastled continues to work. Python callers get:

  • fastled._native.build(sketch_dir, mode) -> calls Rust build orchestration
  • fastled._native.watch(sketch_dir) -> starts file watcher
  • fastled._native.init(example_name) -> project scaffolding

Tauri replaces Flask + browser

What gets eliminated

Current component Status
Flask HTTP server Eliminated -- Tauri loads assets directly
flask-cors Eliminated -- no cross-origin (same process)
HTTPS + self-signed certs Eliminated -- Tauri custom protocol is a secure context
COEP/COOP headers Simplified -- configurable in tauri.conf.json
Port finding / conflicts Eliminated -- no TCP server
Playwright browser (~200 MB) Eliminated -- uses OS webview (0 bytes)
Process cleanup / orphans Eliminated -- single process lifecycle

Tauri integration approach: Sidecar binary

The Tauri viewer is built as a separate binary (fastled-tauri) rather than embedding Tauri into the main CLI. This keeps the CLI lightweight for headless/CI use:

// In fastled-cli, when --app is requested:
let tauri_path = find_tauri_sidecar(); // downloaded on first use, like esbuild
Command::new(tauri_path)
    .arg("--frontend-dir").arg(output_dir)
    .spawn()?;

Cross-platform webview

Platform Engine Bundled?
Windows WebView2 (Chromium) Pre-installed on Win 11; installer handles Win 10
macOS WKWebView (WebKit) Always available
Linux WebKitGTK Must be installed (apt install libwebkit2gtk-4.1-dev)

Risk: Linux WebKitGTK fragmentation

Older Linux distros ship older webkit2gtk versions that may lack SharedArrayBuffer support. Mitigations:

  • Require minimum webkit2gtk version in package dependencies
  • Keep Flask+browser as a --legacy-browser fallback for unsupported systems
  • Document the requirement

Existing frontend works as-is

The esbuild-built frontend (index.html, app.js, index.css) loads directly into Tauri webview. The tauri.conf.json points to the built frontend directory:

{
  "build": {
    "frontendDist": "../src/fastled/frontend/dist"
  }
}

Rust crate dependencies

Need Crate
CLI args clap
File watching notify
HTTP client reqwest
Archive extraction tar, zip, zstd
JSON serde, serde_json
Async runtime tokio
Error handling thiserror, anyhow
Path manipulation std::path + dunce (Windows UNC)
String matching strsim
Progress bars indicatif
Terminal input crossterm
Python bridge pyo3 (abi3-py310)
UI framework tauri v2
Hashing sha2, blake3
Process management running-process-core

CI setup (matching running-process)

sccache configuration

env:
  CARGO_HOME: ${{ github.workspace }}/.cargo
  RUSTUP_HOME: ${{ github.workspace }}/.rustup
  SCCACHE_GHA_ENABLED: "true"
  RUSTC_WRAPPER: sccache

steps:
  - uses: mozilla-actions/sccache-action@v0.0.9
  - uses: Swatinem/rust-cache@v2
    with:
      shared-key: fastled-${{ inputs.runs-on }}
      cache-targets: false

Reusable workflow templates

  • _build.yml -- build wheels + Tauri binaries
  • _lint.yml -- cargo fmt + cargo clippy + ruff
  • _unit-test.yml -- cargo test + pytest
  • _integration-test.yml -- end-to-end compilation tests

Acceptance criteria

  • fastled --just-compile examples/Wasm works via Rust CLI calling Python build subprocess
  • fastled --app examples/Wasm opens a Tauri webview window (not system browser)
  • pip install fastled still works via PyO3 bridge
  • No Flask, no Playwright dependency for default usage
  • CI builds on all 6 platform/arch combinations with sccache
  • Startup time < 50ms (vs ~300-500ms Python)
  • Single binary size < 15 MB (Tauri viewer) + < 5 MB (CLI)

Activity

  1. added a commit that references this issue on Apr 12, 2026
    92855a9
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions