Skip to content

Port remaining Python app orchestration to Rust (closes #72) - #77

Merged
zackees merged 3 commits into
mainfrom
port-app-orchestration-to-rust
May 13, 2026
Merged

zackees merged 3 commits into
mainfrom
port-app-orchestration-to-rust

Conversation

@zackees

@zackees zackees commented May 13, 2026

Copy link
Copy Markdown
Member

Summary

Closes #72. The final cut of the Python→Rust migration tracked in #14 (after #71, #73).

  • Stream A — Python fallback strip + dead-code delete. Replace try/except _native fallbacks with hard imports in string_diff.py, sketch.py, project_init.py. Delete parse_args.py, args.py, compile_native.py (zero callers on the primary path — Rust clap is authoritative). Delete tests/unit/test_parse_args.py and tests/unit/test_purge.py (already broken; imported nonexistent fastled.app.purge_cache). Update test_init_ref_args.py mutex assertions to check stdout + stderr since the Rust CLI correctly emits errors to stderr.

  • Stream B — Port frontend_esbuild.py to Rust. New crates/fastled-cli/src/frontend.rs (487 lines) implements esbuild orchestration, mtime-marker caching, sha256 dist-hash, and idempotent copy-to-output. Exposed via #[pyfunction] copy_frontend_to_output in fastled-py. The Python file shrinks from 160 to ~20 lines and forwards to _native; toolchain callers keep their imports.

  • Stream C — Unwind Rust↔Python BuildService round-trip + viewer/CLI discovery dedupe. crates/fastled-cli/src/build.rs::run_build_embedded now constructs fastled._native.NativeBuildService directly and parses the PyDict result, skipping the Python BuildService wrapper (which stays as the public external API). crates/fastled-cli/src/viewer.rs gains target/<arch-triple>/<profile>/ scan (parity with deleted Python walker); new #[pyfunction] find_fastled_viewer lets src/fastled/open_browser.py drop 130 lines of duplicate discovery code.

  • Docs. New CLAUDE.md (agent playbook: layout, soldr/zccache build cache, slow-test guidance, architecture, gotchas) and CODEX.md (one-line pointer to CLAUDE.md).

Net diff

 25 files changed, 950 insertions(+), 1957 deletions(-)
 3 files deleted (parse_args.py, args.py, compile_native.py)
 2 test files deleted (test_parse_args.py, test_purge.py)
 1 new Rust module (crates/fastled-cli/src/frontend.rs)
 2 new PyO3 bindings (copy_frontend_to_output, find_fastled_viewer)
 1 Rust↔Python round-trip eliminated

Acceptance criteria (from #72)

  • fastled app/compile/watch flows are driven by Rust-native code paths by default.
  • The Python package no longer owns core app orchestration logic (only build_types.py + build_service.py shim + toolchain Python).
  • Remaining Python modules are either compatibility wrappers or explicitly documented holdouts (Meson/Ninja/Emscripten under toolchain/).
  • rg "python -m fastled.app|parse_args\(|BuildService\(" src/fastled no longer shows Python as the primary runtime owner (only the BuildService external API survives).
  • Unit/integration tests pass with the native path as the default.

Test plan

  • bash lint — green (cargo fmt + clippy + ruff + black + isort + pyright: 0 errors)
  • soldr cargo test -p fastled-cli — build.rs and viewer.rs tests pass (incl. new toolchain_key + arch-triple scan tests)
  • soldr cargo test -p fastled-cli frontend — 4 new frontend tests pass (hash determinism, dist skip, marker behavior)
  • Targeted pytest (test_build_service, test_post_migration, test_http_server, test_select_sketch_directory, test_string_diff*, test_sketch_partial_match, test_project_init, test_init_ref_args) — all pass
  • CI must validate full bash test including end-to-end test_cli.py (needs full EMSDK toolchain)
  • Smoke: from fastled._native import copy_frontend_to_output, find_fastled_viewer, NativeBuildService resolves
  • Smoke: from fastled.frontend_esbuild import copy_frontend_to_output, FRONTEND_DIR resolves
  • Smoke: from fastled.open_browser import spawn_http_server, add_cleanup resolves

Related

🤖 Generated with Claude Code

zackees added 3 commits May 13, 2026 15:16
Document the project conventions, build-cache requirement (soldr +
zccache), test layout, architecture, and common Windows gotchas in
one place so coding agents read consistent guidance. CODEX.md is a
one-line pointer to CLAUDE.md so Codex and Claude share the same
playbook.

Refs #75, #76
Make the Rust _native extension authoritative for sketch discovery,
fuzzy matching, project init, and prompt resolution. Strip the
try/except fallback branches that re-implemented this logic in pure
Python -- now hard imports from fastled._native; fail loud if the
extension is unavailable.

Delete three modules that have no callers on the primary path (Rust
clap parser owns CLI argument parsing now):
  - src/fastled/parse_args.py (286 lines)
  - src/fastled/args.py (88 lines)
  - src/fastled/compile_native.py (125 lines)

Update tests that asserted shape of the deleted Args dataclass or
parse_args.py source. Delete test_parse_args.py (refs deleted module)
and test_purge.py (already broken: imported nonexistent
fastled.app.purge_cache). Update test_init_ref_args.py mutex tests to
check stderr+stdout since Rust CLI correctly emits errors to stderr.

Net: -1530 lines across 18 files.

Refs #72
Two related cuts that move authoritative app orchestration onto Rust:

1. **Frontend bundling moved to Rust.** New crates/fastled-cli/src/frontend.rs
   (487 lines) implements esbuild orchestration, mtime-marker caching,
   sha256 dist-hash, and idempotent copy-to-output. Exposed via
   #[pyfunction] copy_frontend_to_output in crates/fastled-py. The Python
   shim at src/fastled/frontend_esbuild.py shrinks from 160 to ~20 lines
   and forwards to _native; toolchain callers in
   src/fastled/toolchain/{emscripten,internal_wasm_build}.py keep their
   existing imports unchanged.

2. **Eliminate Rust to Python BuildService round-trip.**
   crates/fastled-cli/src/build.rs::run_build_embedded now constructs
   fastled._native.NativeBuildService directly, registers the
   Emscripten toolchain inline, and parses the returned PyDict instead
   of round-tripping through src/fastled/build_service.py. KeyboardInterrupt
   is translated through fastled.interrupts.handle_keyboard_interrupt
   in Rust before the subprocess fallback. The Python BuildService
   class stays as the public external API surface.

3. **Viewer / CLI discovery dedupe.** crates/fastled-cli/src/viewer.rs gains
   target/<arch-triple>/<profile>/ scan (parity with the deleted Python
   walker). New #[pyfunction] find_fastled_viewer delegates to it.
   src/fastled/open_browser.py drops _find_tauri_viewer,
   _launch_tauri_viewer, and _find_fastled_cli (now use _native.find_fastled_viewer
   and existing _rust_cli.find_rust_fastled_cli). spawn_http_server keeps
   its signature; the Tauri spawn branch is removed since the Rust CLI's
   --serve-dir already auto-launches the viewer.

Refs #72
@zackees
zackees merged commit 9e35dfb into main May 13, 2026
18 of 25 checks passed
@zackees
zackees deleted the port-app-orchestration-to-rust branch November 5, 2026 05:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Port the remaining Python app orchestration layer to Rust

1 participant