From d14c20ef87d1e107a2df371efe58575cb1096a7f Mon Sep 17 00:00:00 2001 From: zackees Date: Wed, 13 May 2026 15:16:43 -0700 Subject: [PATCH 1/3] docs: add CLAUDE.md and CODEX.md agent playbook 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 --- CLAUDE.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CODEX.md | 1 + 2 files changed, 70 insertions(+) create mode 100644 CLAUDE.md create mode 100644 CODEX.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..344b30bd --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,69 @@ +# Agent Instructions + +This file is read by Claude Code, Codex, and other coding agents that work on this repo. Codex agents should also see `CODEX.md` — that file is a single-line pointer back here so both agents read the same playbook. + +## Layout + +- Python package: `src/fastled/` +- Rust workspace: `crates/fastled-cli`, `crates/fastled-py`, `crates/fastled-tauri` +- Tests: `tests/unit/` (Python), `cargo test --workspace` (Rust) +- CI workflows: `.github/workflows/_*.yml` +- Dev scripts: `./install`, `./lint`, `./test`, `./build-wheel`, `./clean` + +## Build cache — use soldr + zccache + +This project uses **soldr** (build orchestrator) + **zccache** (compile cache). They are NOT optional for local Rust builds: a clean `cargo build -p fastled-py` recompiles PyO3 + reqwest + tokio + axum + clap from scratch and takes 8–10 minutes. With soldr/zccache the same build hits the cache and finishes in seconds. + +- Binaries live at `/c/tools/python13/Scripts/{soldr,zccache}` on Windows, or wherever `uv pip install soldr` placed them. +- `soldr` wraps `cargo` and automatically uses `zccache` as `RUSTC_WRAPPER`. +- CI installs soldr via `zackees/setup-soldr@v0` (see workflows). Local dev should match. + +**When you invoke cargo from an agent, prefer `soldr cargo …` over plain `cargo …`.** The `./_cargo` trampoline currently exec's plain `cargo` — that's a known gap (#76) and will be replaced. Until then, run cargo directly through soldr or you'll burn 10 minutes per build. + +If `soldr` is not on PATH, fall back to plain `cargo` but warn the user that builds will be slow. + +## Tests are slow — pick a narrow set + +`bash test` runs the full pytest + cargo test suite. Some unit tests (`tests/unit/test_cli.py`, `tests/unit/test_build_service.py`) perform real WASM compiles via emscripten and can take 10+ minutes each. + +For iterative work, run targeted tests: + +```bash +uv run pytest tests/unit/test_string_diff.py tests/unit/test_select_sketch_directory.py -v +``` + +Skip `test_cli.py` unless you actually need to validate end-to-end WASM output: + +```bash +uv run pytest tests/unit --ignore=tests/unit/test_cli.py -v +``` + +**Do not pipe pytest through `| tail -N`** if you want streaming output — it buffers until pytest exits, and a multi-minute pytest looks indistinguishable from a hang. Redirect to a file or use `-v`. + +## Architecture notes + +- The user-facing CLI is the Rust binary `fastled` (built from `crates/fastled-cli`, bundled into the wheel via `[tool.maturin] data`). Python `cli.py` / `app.py` are 15-line shims that call `fastled._rust_cli.invoke_rust_fastled_cli`. +- `fastled._native` is the PyO3 extension compiled from `crates/fastled-py/src/lib.rs`. It exposes Rust functions to Python (sketch discovery, build service, project init, string diff, frontend bundling, …). +- The compile path goes Rust → Python toolchain → Rust: `crates/fastled-cli/src/build.rs` constructs `fastled._native.NativeBuildService` and calls it; the Python toolchain (Meson/Ninja/Emscripten internals under `src/fastled/toolchain/`) is intentionally Python-owned. +- For PyO3 changes, after `cargo build -p fastled-py` the new `.dll` lands in `target/maturin/_native.dll`. `maturin develop` copies that to `src/fastled/_native.pyd`. If `_native.pyd` is locked by other Python processes (common on Windows), use the move-aside trick: `mv src/fastled/_native.pyd src/fastled/_native.pyd.old && cp target/maturin/_native.dll src/fastled/_native.pyd`. Remember to delete the `.pyd.old` before committing. + +## Conventions + +- Lint command: `bash lint` — runs cargo fmt + clippy, then ruff/black/isort/pyright. Must be green before commit. +- Test command: `bash test` (or targeted subset; see above). +- Cross-platform pyright warnings about `sys.platform` are expected — don't chase them. +- Always fix all diagnostics found, even pre-existing ones not caused by current changes, before declaring a change complete. +- Prefer native (Rust) implementations and fail-loud over silent Python fallbacks. The migration tracked in #14/#71/#72/#73 is moving everything in this direction. +- Don't add backwards-compat hacks for code paths that no longer exist (e.g. unused `_var` renames, "removed" comments). + +## Common gotchas + +- The installed `fastled` CLI on PATH (e.g. `/c/tools/python13/Scripts/fastled.exe`) may be stale; `find_rust_fastled_cli` in `src/fastled/_rust_cli.py` prefers `target/{release,debug}/fastled.exe` over PATH for exactly this reason. If a CLI test fails, check `uv run python -c "from fastled._rust_cli import find_rust_fastled_cli; print(find_rust_fastled_cli())"`. +- Error messages from the Rust CLI go to **stderr**. Tests asserting `result.stdout` for error text should use `result.stdout + result.stderr` (the parse_args.py removal in #72 exposed this). +- `tasklist` on Windows may report tens of thousands of `python.exe` zombies — most are stale tasklist artifacts, not real processes. `ps -ef | grep python` is more reliable for live ones. + +## Filing issues / PRs + +- `gh issue create --repo zackees/fastled-wasm …` +- `gh pr create …` +- Reference the originating issue (`Refs #72`) in commits/PRs when applicable. diff --git a/CODEX.md b/CODEX.md new file mode 100644 index 00000000..82974b46 --- /dev/null +++ b/CODEX.md @@ -0,0 +1 @@ +READ CLAUDE.md From 6ecd1c222cbcfe219dd6762b4233124486e7b828 Mon Sep 17 00:00:00 2001 From: zackees Date: Wed, 13 May 2026 15:17:05 -0700 Subject: [PATCH 2/3] refactor: strip Python fallbacks; delete dead orchestration modules 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 --- src/fastled/args.py | 88 -------- src/fastled/build_service.py | 3 +- src/fastled/compile_native.py | 125 ----------- src/fastled/parse_args.py | 286 ------------------------ src/fastled/project_init.py | 186 ++------------- src/fastled/select_sketch_directory.py | 6 +- src/fastled/sketch.py | 271 ++++------------------ src/fastled/string_diff.py | 252 +-------------------- tests/unit/test_init_ref_args.py | 9 +- tests/unit/test_parse_args.py | 53 ----- tests/unit/test_post_migration.py | 23 -- tests/unit/test_project_init.py | 4 +- tests/unit/test_purge.py | 187 ---------------- tests/unit/test_sketch_partial_match.py | 217 +++++++----------- 14 files changed, 154 insertions(+), 1556 deletions(-) delete mode 100644 src/fastled/args.py delete mode 100644 src/fastled/compile_native.py delete mode 100644 src/fastled/parse_args.py delete mode 100644 tests/unit/test_parse_args.py delete mode 100644 tests/unit/test_purge.py diff --git a/src/fastled/args.py b/src/fastled/args.py deleted file mode 100644 index 485f84b3..00000000 --- a/src/fastled/args.py +++ /dev/null @@ -1,88 +0,0 @@ -import argparse -from dataclasses import dataclass -from pathlib import Path - - -@dataclass -class Args: - directory: Path | None - init: bool | str - just_compile: bool - profile: bool - app: bool # Deprecated — Tauri viewer is now the default; kept for backward compat - debug: bool - quick: bool - release: bool - serve_dir: Path | None = None - install: bool = False # Install FastLED development environment - dry_run: bool = False # Dry run mode for testing - no_interactive: bool = False # Non-interactive mode - enable_https: bool = True # Enable HTTPS for local server (default: True) - fastled_path: Path | str | None = ( - None # Path to FastLED library for native compilation - ) - purge: bool = False # Purge cached FastLED repo, forcing fresh re-download - - @staticmethod - def from_namespace(args: argparse.Namespace) -> "Args": - assert isinstance( - args.directory, str | None - ), f"expected str | None, got {type(args.directory)}" - assert isinstance( - args.serve_dir, str | None - ), f"expected str | None, got {type(args.serve_dir)}" - assert isinstance( - args.init, bool | str | None - ), f"expected bool, got {type(args.init)}" - assert isinstance( - args.just_compile, bool - ), f"expected bool, got {type(args.just_compile)}" - assert isinstance( - args.profile, bool - ), f"expected bool, got {type(args.profile)}" - assert isinstance(args.app, bool), f"expected bool, got {type(args.app)}" - assert isinstance(args.debug, bool), f"expected bool, got {type(args.debug)}" - assert isinstance(args.quick, bool), f"expected bool, got {type(args.quick)}" - assert isinstance( - args.release, bool - ), f"expected bool, got {type(args.release)}" - assert isinstance( - args.install, bool - ), f"expected bool, got {type(args.install)}" - assert isinstance( - args.dry_run, bool - ), f"expected bool, got {type(args.dry_run)}" - assert isinstance( - args.no_interactive, bool - ), f"expected bool, got {type(args.no_interactive)}" - assert isinstance( - args.no_https, bool - ), f"expected bool, got {type(args.no_https)}" - assert isinstance( - args.fastled_path, str | None - ), f"expected str | None, got {type(args.fastled_path)}" - - init: bool | str = False - if args.init is None: - init = False - elif isinstance(args.init, bool): - init = args.init - elif isinstance(args.init, str): - init = args.init - return Args( - directory=Path(args.directory) if args.directory else None, - serve_dir=Path(args.serve_dir) if args.serve_dir else None, - init=init, - just_compile=args.just_compile, - profile=args.profile, - app=args.app, - debug=args.debug, - quick=args.quick, - release=args.release, - install=args.install, - dry_run=args.dry_run, - no_interactive=args.no_interactive, - enable_https=not args.no_https, # Invert no_https to enable_https - fastled_path=Path(args.fastled_path) if args.fastled_path else None, - purge=args.purge, - ) diff --git a/src/fastled/build_service.py b/src/fastled/build_service.py index 3d0026f3..8a230f91 100644 --- a/src/fastled/build_service.py +++ b/src/fastled/build_service.py @@ -3,12 +3,11 @@ from pathlib import Path from typing import Protocol, cast +from fastled._native import NativeBuildService as _NativeBuildService from fastled.build_types import BuildRequest, BuildResult, BuildStrategy from fastled.interrupts import handle_keyboard_interrupt from fastled.types import BuildMode, CompileResult -from fastled._native import NativeBuildService as _NativeBuildService - def _toolchain_key(fastled_path: Path | None) -> str | None: return str(fastled_path.resolve()) if fastled_path else None diff --git a/src/fastled/compile_native.py b/src/fastled/compile_native.py deleted file mode 100644 index 32cc7fc7..00000000 --- a/src/fastled/compile_native.py +++ /dev/null @@ -1,125 +0,0 @@ -""" -Native EMSDK compilation entrypoints. -""" - -from __future__ import annotations - -from pathlib import Path -from typing import TYPE_CHECKING - -from fastled.build_service import BuildService -from fastled.build_types import BuildRequest -from fastled.emoji_util import EMO -from fastled.types import BuildMode, CompileResult - -if TYPE_CHECKING: - from fastled.toolchain.emscripten import EmscriptenToolchain - - -def compile_native( - directory: Path, - build_mode: BuildMode = BuildMode.QUICK, - profile: bool = False, - fastled_path: Path | str | None = None, - toolchain: EmscriptenToolchain | None = None, -) -> CompileResult: - """ - Compile a FastLED sketch using the native build service. - - The optional `toolchain` argument is kept for compatibility with existing callers. - """ - from fastled.toolchain.emscripten import EmscriptenToolchain - - output_dir = directory / "fastled_js" - - print(f"{EMO('🔨', 'BUILDING:')} Compiling sketch: {directory}") - print(f"{EMO('📋', 'MODE:')} Build mode: {build_mode.value}") - print(f"{EMO('📁', 'OUTPUT:')} Output directory: {output_dir}") - - if toolchain is None: - toolchain = EmscriptenToolchain(fastled_path=fastled_path) - - if not toolchain.check_installation(): - version_info = toolchain.get_version() - if version_info: - print(f"Emscripten version: {version_info}") - else: - return CompileResult( - success=False, - stdout=( - "Emscripten SDK not found. Please install EMSDK:\n\n" - " 1. Download from: https://emscripten.org/docs/getting_started/downloads.html\n" - " 2. Install and activate:\n" - " git clone https://github.com/emscripten-core/emsdk.git\n" - " cd emsdk\n" - " ./emsdk install latest\n" - " ./emsdk activate latest\n" - " source ./emsdk_env.sh # or emsdk_env.bat on Windows\n" - ), - hash_value=None, - zip_bytes=b"", - zip_time=0.0, - libfastled_time=0.0, - sketch_time=0.0, - response_processing_time=0.0, - ) - - version = toolchain.get_version() - if version: - print(f"{EMO('✨', 'EMSDK:')} {version}") - - service = BuildService() - result = service.build( - BuildRequest( - sketch_dir=directory, - build_mode=build_mode, - profile=profile, - fastled_path=Path(fastled_path) if fastled_path else None, - ) - ) - return result.compile_result - - -def run_native_compile( - directory: Path, - build_mode: BuildMode = BuildMode.QUICK, - profile: bool = False, - open_browser: bool = True, - keep_running: bool = True, - enable_https: bool = True, - fastled_path: Path | str | None = None, - app: bool = False, -) -> int: - """ - Run native compilation with optional browser and file watching. - - NOTE: The HTTP server and file watching are now handled by the Rust CLI - (compile_and_serve in main.rs). When called via ``--just-compile`` this - function only performs the compilation step and returns immediately. - """ - del open_browser, keep_running, enable_https, app # handled by Rust CLI - - from fastled.toolchain.emscripten import EmscriptenToolchain - - toolchain = EmscriptenToolchain(fastled_path=fastled_path) - request = BuildRequest( - sketch_dir=directory, - build_mode=build_mode, - profile=profile, - fastled_path=Path(fastled_path) if fastled_path else None, - ) - service = BuildService() - service.register_toolchain(request.fastled_path, toolchain) - result = service.build(request) - - if not result.success: - print(f"\n{EMO('❌', 'ERROR:')} Compilation failed:") - print(result.stdout) - return 1 - - print(f"\n{EMO('✅', 'SUCCESS:')} Compilation successful!") - print(f" Time: {result.sketch_time:.2f} seconds") - print(f" Strategy: {result.strategy}") - print(f" Output: {result.output_dir}") - - return 0 diff --git a/src/fastled/parse_args.py b/src/fastled/parse_args.py deleted file mode 100644 index b0ccfaf1..00000000 --- a/src/fastled/parse_args.py +++ /dev/null @@ -1,286 +0,0 @@ -import argparse -import os -import sys -from pathlib import Path - -from fastled.args import Args -from fastled.interrupts import handle_keyboard_interrupt -from fastled.project_init import project_init -from fastled.select_sketch_directory import select_sketch_directory -from fastled.sketch import ( - find_sketch_by_partial_name, - find_sketch_directories, - looks_like_fastled_repo, - looks_like_sketch_directory, -) - - -def _resolve_path(path_str: str) -> str: - """Resolve a path string, handling MSYS /c/... style paths on Windows.""" - import re - - resolved = Path(path_str).resolve() - if resolved.exists(): - return str(resolved) - # Handle MSYS-style paths: /c/Users/... -> C:\Users\... - if sys.platform == "win32": - m = re.match(r"^/([a-zA-Z])/(.*)", path_str) - if m: - win_path = Path(f"{m.group(1).upper()}:/{m.group(2)}") - if win_path.exists(): - return str(win_path.resolve()) - # Try expanduser for ~ paths - expanded = Path(os.path.expanduser(path_str)).resolve() - if expanded.exists(): - return str(expanded) - return path_str - - -def _find_fastled_repo(start: Path) -> Path | None: - """Find the FastLED repo directory by searching upwards from the current directory.""" - current = start - while current != current.parent: - if looks_like_fastled_repo(current): - return current - current = current.parent - return None - - -_DEFAULT_HELP_TEXT = """ -FastLED WASM Compiler - Useful options: - Directory containing the FastLED sketch to compile - --serve-dir Serve an existing output directory without compiling - --init [example] Initialize one of the top tier WASM examples - --no-https Disable HTTPS and use HTTP for local server - --quick Build in quick mode (default) - --profile Enable profiling the C++ build system - --version Show version information - --help Show detailed help -Examples: - fastled (will auto detect the sketch directory and compile natively) - fastled my_sketch - fastled --init Blink (initializes a new sketch directory with the Blink example) - -Build modes: - --debug Build with debug symbols for dev-tools debugging - --release Build in optimized release mode -""" - - -def parse_args() -> Args: - """Parse command-line arguments.""" - from fastled import __version__ - - # Check if no arguments were provided - if len(sys.argv) == 1: - print(_DEFAULT_HELP_TEXT) - - parser = argparse.ArgumentParser(description=f"FastLED WASM Compiler {__version__}") - parser.add_argument("--version", action="version", version=f"{__version__}") - parser.add_argument( - "directory", - type=str, - nargs="?", - default=None, - help="Directory containing the FastLED sketch to compile", - ) - parser.add_argument( - "--serve-dir", - type=str, - default=None, - help="Serve an existing directory without compiling a sketch", - ) - parser.add_argument( - "--init", - nargs="?", - const=True, - help="Initialize the FastLED sketch in the current directory. Optional name can be provided", - ) - parser.add_argument( - "--just-compile", - action="store_true", - help="Just compile, skip opening the browser and watching for changes.", - ) - parser.add_argument( - "--profile", - action="store_true", - help="Enable profiling of the C++ build system used for wasm compilation.", - ) - parser.add_argument( - "--app", - action="store_true", - help=argparse.SUPPRESS, # Deprecated: Tauri viewer is now the default - ) - - parser.add_argument( - "--install", - action="store_true", - help="Install FastLED development environment with VSCode configuration and Auto Debug extension", - ) - - parser.add_argument( - "--dry-run", - action="store_true", - help="Run in dry-run mode (simulate actions without making changes)", - ) - - parser.add_argument( - "--no-interactive", - action="store_true", - help="Run in non-interactive mode (fail instead of prompting for input)", - ) - - parser.add_argument( - "--no-https", - action="store_true", - help="Disable HTTPS and use HTTP for the local server (useful for debugging)", - ) - - parser.add_argument( - "--latest", - action="store_true", - help="Use latest release when initializing examples with --init (default behavior)", - ) - parser.add_argument( - "--branch", - type=str, - default=None, - help="Use a specific branch when initializing examples with --init (e.g. --branch master)", - ) - parser.add_argument( - "--commit", - type=str, - default=None, - help="Use a specific commit SHA when initializing examples with --init", - ) - - parser.add_argument( - "--fastled-path", - type=str, - default=None, - help="Path to FastLED library for native compilation (defaults to downloading from master repo)", - ) - - parser.add_argument( - "--purge", - action="store_true", - help="Purge the cached FastLED repo download, forcing a fresh re-download on next build", - ) - - build_mode = parser.add_mutually_exclusive_group() - build_mode.add_argument("--debug", action="store_true", help="Build in debug mode") - build_mode.add_argument( - "--quick", - action="store_true", - help="Build in quick mode (default)", - ) - build_mode.add_argument( - "--release", action="store_true", help="Build in release mode" - ) - - args = parser.parse_args() - - # Resolve --fastled-path to an absolute path (handles MSYS /c/... paths on Windows) - if args.fastled_path: - args.fastled_path = _resolve_path(args.fastled_path) - if args.serve_dir: - args.serve_dir = _resolve_path(args.serve_dir) - - # Auto-detect FastLED repo for native compilation - if not args.fastled_path: - cwd = Path(os.getcwd()) - fastled_repo = _find_fastled_repo(cwd) - if fastled_repo is not None: - print( - f"Detected FastLED repo at {fastled_repo}, using it for native compilation." - ) - args.fastled_path = str(fastled_repo) - - # --app is now a no-op; Tauri viewer is always used when available. - # Keep the flag for backward compatibility but ignore it. - - # Handle --install early before other processing - if args.install: - # Don't process other arguments when --install is used - return Args.from_namespace(args) - - if args.serve_dir: - return Args.from_namespace(args) - - # Handle --purge early: if no directory given, skip directory resolution - if args.purge and args.directory is None: - return Args.from_namespace(args) - - if args.init: - example = args.init if args.init is not True else None - # --latest is mutually exclusive with --branch and --commit - if args.latest and (args.branch or args.commit): - print("Error: --latest cannot be used with --branch or --commit") - sys.exit(1) - # Resolve ref: --commit takes precedence over --branch - ref: str | None = None - if args.commit: - ref = args.commit - elif args.branch: - ref = args.branch - # --latest (or default) leaves ref=None, which means latest release - try: - args.directory = project_init(example, args.directory, ref=ref) - except KeyboardInterrupt as ki: - handle_keyboard_interrupt(ki) - except Exception as e: - print(f"Failed to initialize project: {e}") - sys.exit(1) - print("\nInitialized FastLED project in", args.directory) - print(f"Use 'fastled {args.directory}' to compile the project.") - sys.exit(0) - - cwd: Path = Path(os.getcwd()) - fastled_dir: Path | None = _find_fastled_repo(cwd) - is_fastled_dir: bool = fastled_dir is not None - - if not (args.debug or args.quick or args.release): - if is_fastled_dir: - args.quick = True - print("Defaulting to --quick mode in fastled repo") - else: - args.quick = True - print("Defaulting to --quick mode") - - if args.directory is None: - # does current directory look like a sketch? - maybe_sketch_dir = Path(os.getcwd()) - if looks_like_sketch_directory(maybe_sketch_dir): - args.directory = str(maybe_sketch_dir) - else: - print("Searching for sketch directories...") - cwd_is_fastled = looks_like_fastled_repo(Path(os.getcwd())) - sketch_directories = find_sketch_directories(maybe_sketch_dir) - selected_dir = select_sketch_directory( - sketch_directories, cwd_is_fastled, is_followup=True - ) - if selected_dir: - print(f"Using sketch directory: {selected_dir}") - args.directory = selected_dir - else: - print("\nYou need to specify a sketch directory.") - sys.exit(1) - elif args.directory is not None: - # Check if directory is a file path - if os.path.isfile(args.directory): - dir_path = Path(args.directory).parent - if looks_like_sketch_directory(dir_path): - print(f"Using sketch directory: {dir_path}") - args.directory = str(dir_path) - # Check if directory exists as a path - elif not os.path.exists(args.directory): - # Directory doesn't exist - try partial name matching - try: - matched_dir = find_sketch_by_partial_name(args.directory) - print(f"Matched '{args.directory}' to sketch directory: {matched_dir}") - args.directory = str(matched_dir) - except ValueError as e: - print(f"Error: {e}") - sys.exit(1) - - return Args.from_namespace(args) diff --git a/src/fastled/project_init.py b/src/fastled/project_init.py index 85a29cd1..5e2f0976 100644 --- a/src/fastled/project_init.py +++ b/src/fastled/project_init.py @@ -1,37 +1,18 @@ -import json import os -import shutil -import subprocess -import sys from dataclasses import dataclass from pathlib import Path -from fastled._rust_cli import find_rust_fastled_cli as _find_rust_fastled_cli +from fastled._native import collect_examples as _native_collect_examples +from fastled._native import ensure_fastled_repo as _native_ensure_fastled_repo +from fastled._native import ( + find_fastled_repo_upwards as _native_find_fastled_repo_upwards, +) +from fastled._native import init_example_from_repo as _native_init_example_from_repo +from fastled._native import read_fastled_json_ref as _native_read_fastled_json_ref from fastled.interrupts import handle_keyboard_interrupt DEFAULT_EXAMPLE = "wasm" -try: - from fastled._native import collect_examples as _native_collect_examples - from fastled._native import find_example_in_repo as _native_find_example_in_repo - from fastled._native import ( - ensure_fastled_repo as _native_ensure_fastled_repo, - ) - from fastled._native import ( - find_fastled_repo_upwards as _native_find_fastled_repo_upwards, - ) - from fastled._native import ( - init_example_from_repo as _native_init_example_from_repo, - ) - from fastled._native import read_fastled_json_ref as _native_read_fastled_json_ref -except ImportError: - _native_collect_examples = None - _native_find_example_in_repo = None - _native_ensure_fastled_repo = None - _native_find_fastled_repo_upwards = None - _native_init_example_from_repo = None - _native_read_fastled_json_ref = None - @dataclass class _CachedRepo: @@ -40,47 +21,16 @@ class _CachedRepo: def _ensure_repo_via_rust(ref: str | None) -> Path: - """Invoke the Rust binary's hidden ``--internal-ensure-fastled-repo`` flag - to materialise the FastLED repo locally and return the path. + """Materialise the FastLED repo locally via the native Rust extension and + return the path. The Rust side owns the actual GitHub download. Python never performs the HTTP request itself. """ - if _native_ensure_fastled_repo is not None: - repo_path = Path(_native_ensure_fastled_repo(ref)) - if not repo_path.is_dir(): - raise RuntimeError( - f"Rust extension returned non-existent repo path: {str(repo_path)!r}" - ) - return repo_path - - cli = _find_rust_fastled_cli() - if cli is None: - raise RuntimeError( - "Could not locate the fastled CLI binary; cannot fetch FastLED repo." - ) - - cmd: list[str] = [str(cli), "--internal-ensure-fastled-repo"] - if ref is not None: - cmd.append(ref) - - try: - result = subprocess.run(cmd, capture_output=True, text=True, timeout=180) - except KeyboardInterrupt as ki: - handle_keyboard_interrupt(ki) - raise - - if result.returncode != 0: - sys.stderr.write(result.stderr) - raise RuntimeError( - f"fastled --internal-ensure-fastled-repo failed (exit {result.returncode})" - ) - - repo_path_str = result.stdout.strip().splitlines()[-1] if result.stdout else "" - repo_path = Path(repo_path_str) + repo_path = Path(_native_ensure_fastled_repo(ref)) if not repo_path.is_dir(): raise RuntimeError( - f"Rust binary returned non-existent repo path: {repo_path_str!r}" + f"Rust extension returned non-existent repo path: {str(repo_path)!r}" ) return repo_path @@ -89,8 +39,8 @@ def _get_local_fastled_repo(ref: str | None) -> _CachedRepo: """Return a path to the locally-cached FastLED repo (and the resolved ref). Prefers ``FASTLED_LOCAL_REPO_DIR`` set by the Rust CLI's --init pre-step. - Falls back to invoking the Rust binary directly so direct Python API - consumers (Api.project_init, Api.get_examples) still work without httpx. + Falls back to invoking the native Rust helper directly so direct Python API + consumers (Api.project_init, Api.get_examples) still work. """ env_path = os.environ.get("FASTLED_LOCAL_REPO_DIR") if env_path: @@ -111,30 +61,7 @@ def _get_local_fastled_repo(ref: str | None) -> _CachedRepo: def _read_fastled_json(directory: Path) -> str | None: """Read the 'ref' field from fastled.json in the given directory.""" - if _native_read_fastled_json_ref is not None: - return _native_read_fastled_json_ref(str(directory)) - - fpath = directory / "fastled.json" - if not fpath.exists(): - return None - try: - data = json.loads(fpath.read_text(encoding="utf-8")) - return data.get("ref") - except (json.JSONDecodeError, OSError): - return None - - -def _write_fastled_json(directory: Path, ref: str) -> None: - """Write fastled.json with the given ref.""" - fpath = directory / "fastled.json" - data: dict[str, str] = {} - if fpath.exists(): - try: - data = json.loads(fpath.read_text(encoding="utf-8")) - except (json.JSONDecodeError, OSError): - pass - data["ref"] = ref - fpath.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8") + return _native_read_fastled_json_ref(str(directory)) # --- FastLED repo detection --- @@ -145,73 +72,16 @@ def _find_fastled_repo_via_library_json(start: Path) -> Path | None: Returns the repo root directory, or None. """ - if _native_find_fastled_repo_upwards is not None: - found = _native_find_fastled_repo_upwards(str(start), 10) - if found: - return Path(found) - - current = start.resolve() - for _ in range(10): # limit depth - lib_json = current / "library.json" - if lib_json.exists(): - try: - data = json.loads(lib_json.read_text(encoding="utf-8")) - if data.get("name") == "FastLED": - return current - except (json.JSONDecodeError, OSError): - pass - parent = current.parent - if parent == current: - break - current = parent - return None + found = _native_find_fastled_repo_upwards(str(start), 10) + return Path(found) if found else None # --- Core lookup helpers --- -def _find_example_in_repo(repo_root: Path, example: str) -> Path | None: - """Search for an example directory in the FastLED repo. - - Handles both flat layout (examples/FxSdCard/) and nested layout - (examples/Fx/FxSdCard/). - """ - if _native_find_example_in_repo is not None: - found = _native_find_example_in_repo(str(repo_root), example) - return Path(found) if found else None - - examples_dir = repo_root / "examples" - if not examples_dir.exists(): - return None - direct = examples_dir / example - if direct.exists() and direct.is_dir(): - return direct - for subdir in examples_dir.iterdir(): - if subdir.is_dir(): - nested = subdir / example - if nested.exists() and nested.is_dir(): - return nested - return None - - def _collect_examples_from_dir(examples_dir: Path) -> list[str]: """Collect example names from an examples directory.""" - if _native_collect_examples is not None: - return list(_native_collect_examples(str(examples_dir))) - - if not examples_dir.exists(): - return [] - found: list[str] = [] - for entry in examples_dir.iterdir(): - if entry.is_dir(): - ino_files = list(entry.glob("*.ino")) - if ino_files: - found.append(entry.name) - else: - for nested in entry.iterdir(): - if nested.is_dir() and list(nested.glob("*.ino")): - found.append(nested.name) - return sorted(found) + return list(_native_collect_examples(str(examples_dir))) def get_examples(ref: str | None = None) -> list[str]: @@ -349,25 +219,11 @@ def _init_example_from_repo( outputdir: Path, resolved_ref: str | None, ) -> Path: - if _native_init_example_from_repo is not None: - return Path( - _native_init_example_from_repo( - str(repo_root), example, str(outputdir), resolved_ref - ) + return Path( + _native_init_example_from_repo( + str(repo_root), example, str(outputdir), resolved_ref ) - - example_src = _find_example_in_repo(repo_root, example) - if example_src is None: - raise FileNotFoundError(f"Example '{example}' not found in FastLED repo") - - dest = outputdir / example - dest.mkdir(parents=True, exist_ok=True) - shutil.copytree(example_src, dest, dirs_exist_ok=True) - - if resolved_ref is not None: - _write_fastled_json(dest, resolved_ref) - - return dest + ) def unit_test() -> None: diff --git a/src/fastled/select_sketch_directory.py b/src/fastled/select_sketch_directory.py index a758757c..2f511eb5 100644 --- a/src/fastled/select_sketch_directory.py +++ b/src/fastled/select_sketch_directory.py @@ -92,11 +92,7 @@ def _disambiguate_user_choice( user_input_lower = user_input.lower() is_partial = ( - sum( - 1 - for label in option_labels - if user_input_lower in label.lower() - ) + sum(1 for label in option_labels if user_input_lower in label.lower()) > 1 ) current_prompt = ( diff --git a/src/fastled/sketch.py b/src/fastled/sketch.py index d9313b9f..c2858a58 100644 --- a/src/fastled/sketch.py +++ b/src/fastled/sketch.py @@ -1,251 +1,60 @@ -import os -from pathlib import Path - -_MAX_FILES_SEARCH_LIMIT = 10000 - -try: - from fastled._native import ( - find_sketch_by_partial_name as _native_find_sketch_by_partial_name, - ) - from fastled._native import ( - find_sketch_directories as _native_find_sketch_directories, - ) - from fastled._native import looks_like_fastled_repo as _native_looks_like_fastled_repo - from fastled._native import ( - looks_like_sketch_directory as _native_looks_like_sketch_directory, - ) -except ImportError: - _native_find_sketch_by_partial_name = None - _native_find_sketch_directories = None - _native_looks_like_fastled_repo = None - _native_looks_like_sketch_directory = None - - -def find_sketch_directories(directory: Path | None = None) -> list[Path]: - if directory is None: - directory = Path(".") - if _native_find_sketch_directories is not None: - return [Path(p) for p in _native_find_sketch_directories(str(directory))] - file_count = 0 - sketch_directories: list[Path] = [] - # search all the paths one level deep - for path in directory.iterdir(): - if path.is_dir(): - dir_name = path.name - if str(dir_name).startswith("."): - continue - file_count += 1 - if file_count > _MAX_FILES_SEARCH_LIMIT: - print( - f"More than {_MAX_FILES_SEARCH_LIMIT} files found. Stopping search." - ) - break - - if looks_like_sketch_directory(path, quick=True): - sketch_directories.append(path) - if dir_name.lower() == "examples": - # Recursively search examples directory for sketch directories - def search_examples_recursive( - examples_path: Path, depth: int = 0, max_depth: int = 3 - ): - nonlocal file_count - if depth >= max_depth: - return - for example in examples_path.iterdir(): - if example.is_dir(): - if str(example.name).startswith("."): - continue - file_count += 1 - if file_count > _MAX_FILES_SEARCH_LIMIT: - return - if looks_like_sketch_directory(example, quick=True): - sketch_directories.append(example) - else: - # Keep searching deeper if this isn't a sketch directory - search_examples_recursive(example, depth + 1, max_depth) +"""Sketch detection helpers. - search_examples_recursive(path) - # make relative to cwd - sketch_directories = [p.relative_to(directory) for p in sketch_directories] - return sketch_directories +This module is a thin Python wrapper around the native Rust implementation in +``fastled._native``. The wrappers exist only to: +* normalize ``Path``-vs-``str`` inputs for callers, and +* return ``pathlib.Path`` instances rather than strings. -_ORIGINAL_FIND_SKETCH_DIRECTORIES = find_sketch_directories +There is no longer a Python fallback — the native extension is the +authoritative implementation. Stream A of the Rust orchestration migration +deliberately removed all Python-side fallback code paths. +""" +from pathlib import Path -def get_sketch_files(directory: Path) -> list[Path]: - file_count = 0 - files: list[Path] = [] - for root, dirs, filenames in os.walk(directory): - # ignore hidden directories - dirs[:] = [d for d in dirs if not d.startswith(".")] - # ignore fastled_js directory - dirs[:] = [d for d in dirs if "fastled_js" not in d] - # ignore hidden files - filenames = [f for f in filenames if not f.startswith(".")] - outer_break = False - for filename in filenames: - if "platformio.ini" in filename: - continue - file_count += 1 - if file_count > _MAX_FILES_SEARCH_LIMIT: - print( - f"More than {_MAX_FILES_SEARCH_LIMIT} files found. Stopping search." - ) - outer_break = True - break - files.append(Path(root) / filename) - if outer_break: - break - - return files - - -def looks_like_fastled_repo(directory: Path = Path(".")) -> bool: - if _native_looks_like_fastled_repo is not None: - return bool(_native_looks_like_fastled_repo(str(directory))) - libprops = directory / "library.properties" - if not libprops.exists(): - return False - txt = libprops.read_text(encoding="utf-8", errors="ignore") - return "FastLED" in txt - +from fastled._native import ( + find_sketch_by_partial_name as _native_find_sketch_by_partial_name, +) +from fastled._native import find_sketch_directories as _native_find_sketch_directories +from fastled._native import looks_like_fastled_repo as _native_looks_like_fastled_repo +from fastled._native import ( + looks_like_sketch_directory as _native_looks_like_sketch_directory, +) -def _lots_and_lots_of_files(directory: Path) -> bool: - return len(get_sketch_files(directory)) > 100 +__all__ = [ + "find_sketch_by_partial_name", + "find_sketch_directories", + "looks_like_fastled_repo", + "looks_like_sketch_directory", +] -def looks_like_sketch_directory(directory: Path | str | None, quick=False) -> bool: +def find_sketch_directories(directory: Path | str | None = None) -> list[Path]: if directory is None: - return False - if _native_looks_like_sketch_directory is not None: - return bool(_native_looks_like_sketch_directory(str(directory), quick)) - directory = Path(directory) - if looks_like_fastled_repo(directory): - print("Directory looks like the FastLED repo") - return False - - if not quick: - if _lots_and_lots_of_files(directory): - return False - - # walk the path and if there are over 30 files, return False - # at the root of the directory there should either be an ino file or a src directory - # or some cpp files - # if there is a platformio.ini file, return True - ino_file_at_root = list(directory.glob("*.ino")) - if ino_file_at_root: - return True - cpp_file_at_root = list(directory.glob("*.cpp")) - if cpp_file_at_root: - return True - platformini_file = list(directory.glob("platformio.ini")) - if platformini_file: - return True - return False + directory = Path(".") + return [Path(p) for p in _native_find_sketch_directories(str(directory))] def find_sketch_by_partial_name( - partial_name: str, search_dir: Path | None = None -) -> Path | None: - """ - Find a sketch directory by partial name match. - - Args: - partial_name: Partial name to match against sketch directories - search_dir: Directory to search in (defaults to current directory) + partial_name: str, search_dir: Path | str | None = None +) -> Path: + """Find a sketch directory by partial name match (delegates to Rust). - Returns: - Path to the matching sketch directory, or None if no unique match found - - Raises: - ValueError: If multiple matches are found with no clear best match, or no matches found + Raises ``ValueError`` if no unique match is found. """ if search_dir is None: search_dir = Path(".") + return Path(_native_find_sketch_by_partial_name(partial_name, str(search_dir))) - if ( - _native_find_sketch_by_partial_name is not None - and find_sketch_directories is _ORIGINAL_FIND_SKETCH_DIRECTORIES - ): - return Path(_native_find_sketch_by_partial_name(partial_name, str(search_dir))) - - # First, find all sketch directories - sketch_directories = find_sketch_directories(search_dir) - # Normalize the partial name to use forward slashes for cross-platform matching - partial_name_normalized = partial_name.replace("\\", "/").lower() +def looks_like_fastled_repo(directory: Path | str = Path(".")) -> bool: + return bool(_native_looks_like_fastled_repo(str(directory))) - # Get the set of characters in the partial name for similarity check - partial_chars = set(partial_name_normalized) - # Find matches where the partial name appears in the path - matches = [] - for sketch_dir in sketch_directories: - # Normalize the sketch directory path to use forward slashes - sketch_str_normalized = str(sketch_dir).replace("\\", "/").lower() - - # Character similarity check: at least 50% of partial name chars must be in target - target_chars = set(sketch_str_normalized) - matching_chars = partial_chars & target_chars - similarity = ( - len(matching_chars) / len(partial_chars) if len(partial_chars) > 0 else 0 - ) - - # Check if partial_name matches the directory name or any part of the path - # AND has sufficient character similarity - if partial_name_normalized in sketch_str_normalized and similarity >= 0.5: - matches.append(sketch_dir) - - if len(matches) == 0: - # Check if this is a total mismatch (low character similarity with all sketches) - all_low_similarity = True - for sketch_dir in sketch_directories: - sketch_str_normalized = str(sketch_dir).replace("\\", "/").lower() - target_chars = set(sketch_str_normalized) - matching_chars = partial_chars & target_chars - similarity = ( - len(matching_chars) / len(partial_chars) - if len(partial_chars) > 0 - else 0 - ) - if similarity > 0.5: - all_low_similarity = False - break - - if all_low_similarity and len(sketch_directories) > 0: - # List all available sketches - sketches_str = "\n ".join(str(s) for s in sketch_directories) - raise ValueError( - f"'{partial_name}' does not look like any of the available sketches.\n\n" - f"Available sketches:\n {sketches_str}" - ) - else: - raise ValueError(f"No sketch directory found matching '{partial_name}'") - elif len(matches) == 1: - return matches[0] - else: - # Multiple matches - try to find the best match - # Best match criteria: exact match of the final directory name - exact_matches = [] - for match in matches: - # Get the final directory name - final_dir_name = match.name.lower() - if final_dir_name == partial_name_normalized: - exact_matches.append(match) - - if len(exact_matches) == 1: - # Found exactly one exact match - this is the best match - return exact_matches[0] - elif len(exact_matches) > 1: - # Multiple exact matches - still ambiguous - matches_str = "\n ".join(str(m) for m in exact_matches) - raise ValueError( - f"Multiple sketch directories found matching '{partial_name}':\n {matches_str}" - ) - else: - # No exact match - ambiguous partial matches - matches_str = "\n ".join(str(m) for m in matches) - raise ValueError( - f"Multiple sketch directories found matching '{partial_name}':\n {matches_str}" - ) +def looks_like_sketch_directory( + directory: Path | str | None, quick: bool = False +) -> bool: + if directory is None: + return False + return bool(_native_looks_like_sketch_directory(str(directory), quick)) diff --git a/src/fastled/string_diff.py b/src/fastled/string_diff.py index c92a92b7..b3336e10 100644 --- a/src/fastled/string_diff.py +++ b/src/fastled/string_diff.py @@ -1,253 +1,8 @@ -from difflib import SequenceMatcher from pathlib import Path -try: - from fastled._native import is_in_order_match as _native_is_in_order_match - from fastled._native import string_diff as _native_string_diff -except ImportError: - _native_is_in_order_match = None - _native_string_diff = None +from fastled._native import is_in_order_match, string_diff - -def _token_sort_ratio(a: str, b: str) -> float: - """Return a 0..100 similarity score after sorting whitespace-split tokens.""" - a_sorted = " ".join(sorted(a.split())) - b_sorted = " ".join(sorted(b.split())) - return SequenceMatcher(None, a_sorted, b_sorted).ratio() * 100.0 - - -def _filter_out_obvious_bad_choices( - input_str: str, string_list: list[str] -) -> list[str]: - """ - Filter out strings that are too different from the input string. - This is a heuristic and may not be perfect. - """ - if not input_str.strip(): # Handle empty input - return string_list - - input_chars = set(input_str.lower()) - filtered_list = [] - for s in string_list: - # Check if at least half of the input characters are in the string - s_chars = set(s.lower()) - common_chars = input_chars.intersection(s_chars) - if len(common_chars) >= len(input_chars) / 2: - filtered_list.append(s) - return filtered_list - - -def is_in_order_match(input_str: str, other: str) -> bool: - if _native_is_in_order_match is not None: - return bool(_native_is_in_order_match(input_str, other)) - """ - Check if the input string is an in-order match for any string in the list. - An in-order match means that the characters of the input string appear - in the same order in the string from the list, ignoring spaces in the input. - """ - - # Remove spaces from input string for matching - input_chars = [c.lower() for c in input_str if c != " "] - other_chars = [c.lower() for c in other] - input_index = 0 - other_index = 0 - while input_index < len(input_chars) and other_index < len(other_chars): - if input_chars[input_index] == other_chars[other_index]: - input_index += 1 - other_index += 1 - # If we reached the end of the input string, it means all characters were found in order - if input_index == len(input_chars): - return True - return False - - -# Returns the min distance strings. If there is a tie, it returns -# all the strings that have the same min distance. -# Returns a tuple of index and string. -def string_diff( - input_string: str, string_list: list[str], ignore_case=True -) -> list[tuple[float, str]]: - if _native_string_diff is not None: - return list(_native_string_diff(input_string, string_list, ignore_case)) - - def normalize(s: str) -> str: - return s.lower() if ignore_case else s - - # Handle empty input or empty list - if not input_string.strip(): - # Return all strings with equal distance for empty input - return [(i, s) for i, s in enumerate(string_list)] - - if not string_list: - return [] - - map_string: dict[str, str] = {} - - if ignore_case: - map_string = {s.lower(): s for s in string_list} - else: - map_string = {s: s for s in string_list} - - original_string_list = string_list.copy() - if ignore_case: - string_list = [s.lower() for s in string_list] - input_string = input_string.lower() - - # Check for exact matches, but also check if there are other substring matches - exact_matches = [s for s in string_list if s == input_string] - substring_matches = [s for s in string_list if input_string in s] - - # If there's exactly one exact match, and there are substring matches, - # check if we should prioritize the exact match or return all variants - if len(exact_matches) == 1 and len(substring_matches) > 1: - exact_match = exact_matches[0] - other_substring_matches = [s for s in substring_matches if s != exact_match] - - # Prioritize exact match only if it appears at the start of other matches - # AND those matches have a camelCase boundary (indicating compound words) - # We need to use the original (non-lowercased) strings for camelCase detection - should_prioritize_exact = True - original_exact_match = map_string[exact_match] # Get the original casing - - for other_match in other_substring_matches: - original_other_match = map_string[other_match] # Get the original casing - - if not original_other_match.lower().startswith( - original_exact_match.lower() - ): - # If the exact match isn't at the start, don't prioritize - should_prioritize_exact = False - break - - # Check for camelCase boundary after the exact match in the ORIGINAL string - remainder = original_other_match[len(original_exact_match) :] - if remainder and remainder[0].isupper(): - # Only prioritize exact match if the exact match is very short (4 chars or less) - # AND the remainder suggests a different concept - if len(original_exact_match) <= 4 and len(remainder) >= 6: - # This looks like a camelCase compound word (e.g., "wasm" -> "WasmScreenCoords") - continue - else: - # This looks like a variant (e.g., "Noise" -> "NoisePlayground", "Fire2012" -> "Fire2012WithPalette") - should_prioritize_exact = False - break - else: - # This looks like a variant/extension (e.g., "Blur" -> "Blur2d") - should_prioritize_exact = False - break - - if should_prioritize_exact: - out: list[tuple[float, str]] = [] - for i, s in enumerate(exact_matches): - s_mapped = map_string.get(s, s) - out.append((i, s_mapped)) - return out - else: - # Apply character count filtering only for very specific compound terms - # Main criteria: contains numbers AND ends with numbers/letters (like Wave2d, Fire2012) - original_exact_match = map_string[exact_match] - should_apply_char_filter = ( - len(original_exact_match) >= 5 # Longer terms - and any(c.isdigit() for c in original_exact_match) # Contains numbers - and ( - original_exact_match[-1].isdigit() - or original_exact_match[-1].islower() - ) # Ends specifically (compound pattern) - ) - - if should_apply_char_filter: - # Filter substring matches based on extra character count - # Use a more lenient threshold for shorter base terms - if len(original_exact_match) <= 6: - # For short terms, allow more extra chars (e.g., "Wave2d" + "FxWave2d") - MAX_EXTRA_CHARS = min(10, len(original_exact_match) * 2) - else: - # For longer terms, allow significant extensions (e.g., "Fire2012" + "Fire2012WithPalette") - MAX_EXTRA_CHARS = 12 - - filtered_matches = [] - - for s in substring_matches: - original_s = map_string[s] - if s == exact_match: - # Always include the exact match - filtered_matches.append(s) - else: - # Calculate extra characters - extra_chars = len(original_s) - len(original_exact_match) - if extra_chars <= MAX_EXTRA_CHARS: - filtered_matches.append(s) - - # Return filtered matches - out: list[tuple[float, str]] = [] - for i, s in enumerate(filtered_matches): - s_mapped = map_string.get(s, s) or s - out.append((i, s_mapped)) - return out - else: - # Return all substring matches (original behavior for base terms) - out: list[tuple[float, str]] = [] - for i, s in enumerate(substring_matches): - s_mapped = map_string.get(s, s) or s - out.append((i, s_mapped)) - return out - - # If there's only an exact match and no other substring matches, return just the exact match - if exact_matches and len(substring_matches) == 1: - out: list[tuple[float, str]] = [] - for i, s in enumerate(exact_matches): - s_mapped = map_string.get(s, s) - out.append((i, s_mapped)) - return out - - # Apply set membership filtering for queries with 3+ characters - if len(input_string.strip()) >= 3: - filtered = _filter_out_obvious_bad_choices(input_string, string_list) - if filtered: # Only apply filter if it doesn't eliminate everything - string_list = filtered - - # Second filter: exact substring filtering if applicable - if substring_matches: - string_list = substring_matches - # Return all substring matches - out: list[tuple[float, str]] = [] - for i, s in enumerate(string_list): - s_mapped = map_string.get(s, s) - out.append((i, s_mapped)) - return out - - # Third filter: in order exact match filtering if applicable. - in_order_matches = [s for s in string_list if is_in_order_match(input_string, s)] - if in_order_matches: - string_list = in_order_matches - - # Calculate distances - distances: list[float] = [] - for s in string_list: - dist = _token_sort_ratio(normalize(input_string), normalize(s)) - distances.append(1.0 / (dist + 1.0)) - - # Handle case where no strings remain after filtering - if not distances: - # Fall back to original list and calculate distances - string_list = original_string_list.copy() - if ignore_case: - string_list = [s.lower() for s in string_list] - - distances = [] - for s in string_list: - dist = _token_sort_ratio(normalize(input_string), normalize(s)) - distances.append(1.0 / (dist + 1.0)) - - min_distance = min(distances) - out: list[tuple[float, str]] = [] - for i, d in enumerate(distances): - if d == min_distance: - s = string_list[i] - s_mapped = map_string.get(s, s) - out.append((i, s_mapped)) - - return out +__all__ = ["is_in_order_match", "string_diff", "string_diff_paths"] def string_diff_paths( @@ -260,8 +15,7 @@ def string_diff_paths( tmp = string_diff(input_str, string_list, ignore_case) out: list[tuple[float, Path]] = [] for i, j in tmp: - # Find the original path that matches the normalized result - for idx, orig_path in enumerate(path_list): + for orig_path in path_list: if str(orig_path).replace("\\", "/") == j: out.append((i, orig_path)) break diff --git a/tests/unit/test_init_ref_args.py b/tests/unit/test_init_ref_args.py index f23f487e..564bf93e 100644 --- a/tests/unit/test_init_ref_args.py +++ b/tests/unit/test_init_ref_args.py @@ -36,14 +36,16 @@ def test_latest_with_branch_fails(self) -> None: result = _run_fastled("--init=wasm", "--latest", "--branch", "master") self.assertNotEqual(result.returncode, 0) self.assertIn( - "--latest cannot be used with --branch or --commit", result.stdout + "--latest cannot be used with --branch or --commit", + result.stdout + result.stderr, ) def test_latest_with_commit_fails(self) -> None: result = _run_fastled("--init=wasm", "--latest", "--commit", "abc1234") self.assertNotEqual(result.returncode, 0) self.assertIn( - "--latest cannot be used with --branch or --commit", result.stdout + "--latest cannot be used with --branch or --commit", + result.stdout + result.stderr, ) def test_latest_with_branch_and_commit_fails(self) -> None: @@ -52,7 +54,8 @@ def test_latest_with_branch_and_commit_fails(self) -> None: ) self.assertNotEqual(result.returncode, 0) self.assertIn( - "--latest cannot be used with --branch or --commit", result.stdout + "--latest cannot be used with --branch or --commit", + result.stdout + result.stderr, ) def test_branch_and_commit_together_accepted(self) -> None: diff --git a/tests/unit/test_parse_args.py b/tests/unit/test_parse_args.py deleted file mode 100644 index e016c1e2..00000000 --- a/tests/unit/test_parse_args.py +++ /dev/null @@ -1,53 +0,0 @@ -import subprocess -import sys -from pathlib import Path - -SRC_DIR = str(Path(__file__).parent.parent.parent / "src") - - -def _run_fastled(*args: str) -> subprocess.CompletedProcess[str]: - import os - - env = os.environ.copy() - env["PYTHONPATH"] = SRC_DIR + os.pathsep + env.get("PYTHONPATH", "") - return subprocess.run( - [sys.executable, "-m", "fastled", *args], - capture_output=True, - text=True, - timeout=60, - stdin=subprocess.DEVNULL, - env=env, - ) - - -def test_help_no_longer_advertises_local_flag() -> None: - result = _run_fastled("--help") - legacy_flag = "--" + "local" - assert legacy_flag not in result.stdout - - -def test_help_no_longer_advertises_server_or_web_flags() -> None: - result = _run_fastled("--help") - assert "--server" not in result.stdout - assert "--web" not in result.stdout - - -def test_parse_args_source_has_no_local_flag() -> None: - source = ( - Path(__file__).parent.parent.parent / "src" / "fastled" / "parse_args.py" - ).read_text() - legacy_flag = "--" + "local" - assert legacy_flag not in source - - -def test_parse_args_source_has_no_server_or_web_flags() -> None: - source = ( - Path(__file__).parent.parent.parent / "src" / "fastled" / "parse_args.py" - ).read_text() - assert "--server" not in source - assert "--web" not in source - - -def test_help_advertises_serve_dir() -> None: - result = _run_fastled("--help") - assert "--serve-dir" in result.stdout diff --git a/tests/unit/test_post_migration.py b/tests/unit/test_post_migration.py index 4522eea6..69de53db 100644 --- a/tests/unit/test_post_migration.py +++ b/tests/unit/test_post_migration.py @@ -1,6 +1,5 @@ """Tests for post-migration cleanup: dead code removal, stale exports, and bug fixes.""" -import ast import unittest from pathlib import Path @@ -75,27 +74,5 @@ def test_no_stale_exports(self) -> None: ) -class TestNoRedundantNativeField(unittest.TestCase): - """Bug 5: The always-True 'native' field should be removed from Args.""" - - def test_args_has_no_native_field(self) -> None: - from fastled.args import Args - - fields = {f.name for f in Args.__dataclass_fields__.values()} - self.assertNotIn( - "native", - fields, - "Args.native is always True and should be removed", - ) - - def test_parse_args_no_native_flag(self) -> None: - """The --native argparse flag should be removed.""" - source = (SRC_DIR / "parse_args.py").read_text() - tree = ast.parse(source) - for node in ast.walk(tree): - if isinstance(node, ast.Constant) and node.value == "--native": - self.fail("parse_args.py should not define a --native argparse flag") - - if __name__ == "__main__": unittest.main() diff --git a/tests/unit/test_project_init.py b/tests/unit/test_project_init.py index dfe299ea..7036f182 100644 --- a/tests/unit/test_project_init.py +++ b/tests/unit/test_project_init.py @@ -45,9 +45,7 @@ def test_init_example_from_repo_prefers_native_extension(self, mock_native) -> N resolved_ref="master", ) self.assertEqual(out, result) - mock_native.assert_called_once_with( - "repo", "Blink", tmpdir, "master" - ) + mock_native.assert_called_once_with("repo", "Blink", tmpdir, "master") if __name__ == "__main__": diff --git a/tests/unit/test_purge.py b/tests/unit/test_purge.py deleted file mode 100644 index 501046e7..00000000 --- a/tests/unit/test_purge.py +++ /dev/null @@ -1,187 +0,0 @@ -"""Unit tests for the --purge feature.""" - -import argparse -from pathlib import Path - -import pytest # type: ignore[reportMissingImports] - -from fastled.app import purge_cache -from fastled.args import Args - - -class TestPurgeArgs: - """Test that the purge flag is correctly parsed into Args.""" - - def test_args_purge_default_false(self) -> None: - """purge defaults to False.""" - args = Args( - directory=None, - init=False, - just_compile=False, - profile=False, - app=False, - debug=False, - quick=True, - release=False, - ) - assert args.purge is False - - def test_args_purge_true(self) -> None: - """purge can be set to True.""" - args = Args( - directory=None, - init=False, - just_compile=False, - profile=False, - app=False, - debug=False, - quick=True, - release=False, - purge=True, - ) - assert args.purge is True - - def test_args_from_namespace_purge(self) -> None: - """Args.from_namespace correctly passes through the purge flag.""" - ns = argparse.Namespace( - directory=None, - serve_dir=None, - init=None, - just_compile=False, - profile=False, - app=False, - debug=False, - quick=True, - release=False, - install=False, - dry_run=False, - no_interactive=False, - no_https=False, - fastled_path=None, - purge=True, - ) - args = Args.from_namespace(ns) - assert args.purge is True - - -class TestPurgeCache: - """Test the purge_cache function.""" - - def test_purge_removes_cache_dir( - self, tmp_path: Path, capsys: pytest.CaptureFixture[str] - ) -> None: - """purge_cache removes the cache directory when it exists.""" - cache_dir = tmp_path / ".fastled" / "cache" - cache_dir.mkdir(parents=True) - # Put some files in it - (cache_dir / "some_repo.zip").write_text("data") - (cache_dir / "subdir").mkdir() - (cache_dir / "subdir" / "file.txt").write_text("nested") - - purge_cache(cache_dir) - - assert not cache_dir.exists() - assert "Purged FastLED cache:" in capsys.readouterr().out - - def test_purge_no_cache_dir( - self, tmp_path: Path, capsys: pytest.CaptureFixture[str] - ) -> None: - """purge_cache prints a message when cache directory doesn't exist.""" - cache_dir = tmp_path / ".fastled" / "cache" - assert not cache_dir.exists() - - purge_cache(cache_dir) - - assert "No FastLED cache to purge." in capsys.readouterr().out - - def test_purge_wasm_build_artifacts( - self, tmp_path: Path, capsys: pytest.CaptureFixture[str] - ) -> None: - """purge_cache removes stale WASM build artifacts when fastled_path is provided.""" - cache_dir = tmp_path / "cache" - cache_dir.mkdir() - fastled_path = tmp_path / "FastLED" - wasm_dir = fastled_path / ".build" / "meson-wasm-debug" - wasm_dir.mkdir(parents=True) - - # Create the stale artifacts - stale_files = ["wasm_ld_args.json", "wasm_ld_args.key", "fastled_glue.js"] - for name in stale_files: - (wasm_dir / name).write_text("stale") - - # Also create a non-stale file that should NOT be removed - (wasm_dir / "keep_me.txt").write_text("important") - - purge_cache(cache_dir, fastled_path=fastled_path) - - for name in stale_files: - assert not (wasm_dir / name).exists(), f"{name} should have been purged" - assert ( - wasm_dir / "keep_me.txt" - ).exists(), "Non-stale files should be preserved" - - out = capsys.readouterr().out - for name in stale_files: - assert f"Purged: {wasm_dir / name}" in out - - def test_purge_wasm_multiple_meson_dirs(self, tmp_path: Path) -> None: - """purge_cache handles multiple meson-wasm-* directories.""" - cache_dir = tmp_path / "cache" - cache_dir.mkdir() - fastled_path = tmp_path / "FastLED" - - dirs = ["meson-wasm-debug", "meson-wasm-release", "meson-wasm-quick"] - for d in dirs: - wasm_dir = fastled_path / ".build" / d - wasm_dir.mkdir(parents=True) - (wasm_dir / "wasm_ld_args.json").write_text("stale") - - purge_cache(cache_dir, fastled_path=fastled_path) - - for d in dirs: - assert not (fastled_path / ".build" / d / "wasm_ld_args.json").exists() - - def test_purge_no_fastled_path_skips_wasm( - self, tmp_path: Path, capsys: pytest.CaptureFixture[str] - ) -> None: - """purge_cache only removes cache dir when fastled_path is None.""" - cache_dir = tmp_path / "cache" - cache_dir.mkdir() - - purge_cache(cache_dir, fastled_path=None) - - assert not cache_dir.exists() - out = capsys.readouterr().out - assert "Purged FastLED cache:" in out - # No WASM artifact messages - assert "wasm_ld_args" not in out - - def test_purge_wasm_no_build_dir(self, tmp_path: Path) -> None: - """purge_cache handles missing .build directory gracefully.""" - cache_dir = tmp_path / "cache" - cache_dir.mkdir() - fastled_path = tmp_path / "FastLED" - # Don't create .build dir - - # Should not raise - purge_cache(cache_dir, fastled_path=fastled_path) - - def test_purge_wasm_partial_artifacts( - self, tmp_path: Path, capsys: pytest.CaptureFixture[str] - ) -> None: - """purge_cache handles directories with only some stale artifacts.""" - cache_dir = tmp_path / "cache" - cache_dir.mkdir() - fastled_path = tmp_path / "FastLED" - wasm_dir = fastled_path / ".build" / "meson-wasm-quick" - wasm_dir.mkdir(parents=True) - - # Only create one of the three stale files - (wasm_dir / "fastled_glue.js").write_text("stale") - - purge_cache(cache_dir, fastled_path=fastled_path) - - assert not (wasm_dir / "fastled_glue.js").exists() - out = capsys.readouterr().out - assert "fastled_glue.js" in out - assert "wasm_ld_args.json" not in out diff --git a/tests/unit/test_sketch_partial_match.py b/tests/unit/test_sketch_partial_match.py index 20914666..a7b3bdad 100644 --- a/tests/unit/test_sketch_partial_match.py +++ b/tests/unit/test_sketch_partial_match.py @@ -1,152 +1,97 @@ """ Unit tests for find_sketch_by_partial_name to ensure correct partial matching behavior. + +These tests exercise the native Rust implementation re-exported through +``fastled.sketch``. The Python-side fallback no longer exists (Stream A: Rust +is authoritative), so we use real on-disk fixtures rather than mocking the +search. """ import unittest from pathlib import Path -from unittest.mock import patch +from tempfile import TemporaryDirectory from fastled.sketch import find_sketch_by_partial_name +def _make_sketch(root: Path, relative: str) -> Path: + """Create a minimal sketch directory containing an .ino file.""" + sketch_dir = root / relative + sketch_dir.mkdir(parents=True, exist_ok=True) + (sketch_dir / f"{sketch_dir.name}.ino").write_text("void setup(){}void loop(){}\n") + return sketch_dir + + class TestFindSketchByPartialName(unittest.TestCase): - """Test find_sketch_by_partial_name behavior.""" - - @patch("fastled.sketch.find_sketch_directories") - def test_single_match_returns_path(self, mock_find): - """Single unique match should return the matching path.""" - mock_find.return_value = [ - Path("examples/sketch1"), - Path("examples/sketch2"), - ] - result = find_sketch_by_partial_name("sketch2") - self.assertEqual(Path("examples/sketch2"), result) - - @patch("fastled.sketch.find_sketch_directories") - def test_no_match_raises_error(self, mock_find): + """Test find_sketch_by_partial_name behavior against the native resolver.""" + + def test_single_match_returns_path(self) -> None: + """A unique partial match should return the matching sketch.""" + with TemporaryDirectory() as tmp: + root = Path(tmp) + _make_sketch(root, "examples/sketch1") + _make_sketch(root, "examples/sketch2") + result = find_sketch_by_partial_name("sketch2", root) + self.assertTrue(result.match("**/sketch2")) + + def test_no_match_raises_error(self) -> None: """No matches should raise ValueError.""" - mock_find.return_value = [ - Path("examples/sketch1"), - Path("examples/sketch2"), - ] - with self.assertRaises(ValueError) as context: - find_sketch_by_partial_name("nonexistent") - self.assertIn("No sketch directory found", str(context.exception)) - - @patch("fastled.sketch.find_sketch_directories") - def test_multiple_matches_raises_error(self, mock_find): - """Multiple matches should raise ValueError with list of matches.""" - mock_find.return_value = [ - Path("examples/sketch1"), - Path("examples/sketch2"), - Path("more/sketch3"), - ] - with self.assertRaises(ValueError) as context: - find_sketch_by_partial_name("sketch") - error_msg = str(context.exception) - self.assertIn("Multiple sketch directories found", error_msg) - # Check using normalized paths (cross-platform) - self.assertIn("sketch1", error_msg) - self.assertIn("sketch2", error_msg) - - @patch("fastled.sketch.find_sketch_directories") - def test_case_insensitive_match(self, mock_find): + with TemporaryDirectory() as tmp: + root = Path(tmp) + _make_sketch(root, "examples/sketch1") + _make_sketch(root, "examples/sketch2") + with self.assertRaises(ValueError): + find_sketch_by_partial_name("nonexistent", root) + + def test_multiple_matches_raises_error(self) -> None: + """An ambiguous partial match should raise ValueError listing matches.""" + with TemporaryDirectory() as tmp: + root = Path(tmp) + _make_sketch(root, "examples/sketch1") + _make_sketch(root, "examples/sketch2") + _make_sketch(root, "more/sketch3") + with self.assertRaises(ValueError) as context: + find_sketch_by_partial_name("sketch", root) + error_msg = str(context.exception) + self.assertIn("sketch1", error_msg) + self.assertIn("sketch2", error_msg) + + def test_case_insensitive_match(self) -> None: """Match should be case insensitive.""" - mock_find.return_value = [ - Path("examples/MySketch"), - Path("examples/OtherSketch"), - ] - result = find_sketch_by_partial_name("mysketch") - self.assertEqual(Path("examples/MySketch"), result) - - @patch("fastled.sketch.find_sketch_directories") - def test_partial_path_match(self, mock_find): - """Should match partial paths, not just directory names.""" - mock_find.return_value = [ - Path("examples/path/sketch1"), - Path("examples/other/sketch2"), - ] - result = find_sketch_by_partial_name("path/sketch1") - self.assertEqual(Path("examples/path/sketch1"), result) - - @patch("fastled.sketch.find_sketch_directories") - def test_best_match_exact_name(self, mock_find): - """When multiple partial matches exist, exact directory name match wins.""" - mock_find.return_value = [ - Path("examples/sketch"), - Path("examples/sketch1"), - Path("examples/sketch2"), - ] - result = find_sketch_by_partial_name("sketch") - self.assertEqual(Path("examples/sketch"), result) - - @patch("fastled.sketch.find_sketch_directories") - def test_no_exact_match_with_multiple_partials_errors(self, mock_find): - """Multiple partial matches with no exact match should error.""" - mock_find.return_value = [ - Path("examples/sketch1"), - Path("examples/sketch2"), - ] - with self.assertRaises(ValueError) as context: - find_sketch_by_partial_name("sketch") - self.assertIn("Multiple sketch directories found", str(context.exception)) - - @patch("fastled.sketch.find_sketch_directories") - def test_multiple_exact_matches_errors(self, mock_find): - """Multiple exact matches should error.""" - mock_find.return_value = [ - Path("examples/sketch"), - Path("more/sketch"), - ] - with self.assertRaises(ValueError) as context: - find_sketch_by_partial_name("sketch") - self.assertIn("Multiple sketch directories found", str(context.exception)) - - @patch("fastled.sketch.find_sketch_directories") - def test_low_character_similarity_shows_available_sketches(self, mock_find): - """When search term has low character similarity, show available sketches.""" - mock_find.return_value = [ - Path("path/to/sketch"), - Path("examples/MyProject"), - ] - with self.assertRaises(ValueError) as context: - find_sketch_by_partial_name("blah") - error_msg = str(context.exception) - self.assertIn("does not look like any of the available sketches", error_msg) - self.assertIn("Available sketches:", error_msg) - self.assertIn("sketch", error_msg) - self.assertIn("MyProject", error_msg) - - @patch("fastled.sketch.find_sketch_directories") - def test_substring_match_with_low_similarity_rejected(self, mock_find): - """Substring match with low character similarity should be rejected.""" - mock_find.return_value = [ - Path("qrs/tuv"), - ] - # "ab" has chars {a, b}, "qrs/tuv" has chars {q, r, s, /, t, u, v} - # No common characters, so similarity = 0/2 = 0% < 50% - with self.assertRaises(ValueError) as context: - find_sketch_by_partial_name("ab") - error_msg = str(context.exception) - self.assertIn("does not look like any of the available sketches", error_msg) - - @patch("fastled.sketch.find_sketch_directories") - def test_sufficient_similarity_allows_match(self, mock_find): - """Match with sufficient character similarity should succeed.""" - mock_find.return_value = [ - Path("examples/sketch123"), - ] - # "sketch" has all chars in "examples/sketch123" (100% similarity) - result = find_sketch_by_partial_name("sketch") - self.assertEqual(Path("examples/sketch123"), result) - - @patch("fastled.sketch._native_find_sketch_by_partial_name") - def test_prefers_native_extension_when_available(self, mock_native): - """Normal runtime should delegate partial matching to the Rust extension.""" - mock_native.return_value = "examples/FxWave2d" - result = find_sketch_by_partial_name("FxWave2d", Path("demo")) - self.assertEqual(Path("examples/FxWave2d"), result) - mock_native.assert_called_once_with("FxWave2d", "demo") + with TemporaryDirectory() as tmp: + root = Path(tmp) + _make_sketch(root, "examples/MySketch") + _make_sketch(root, "examples/OtherSketch") + result = find_sketch_by_partial_name("mysketch", root) + self.assertTrue(result.match("**/MySketch")) + + def test_partial_path_match(self) -> None: + """Partial path components should match.""" + with TemporaryDirectory() as tmp: + root = Path(tmp) + _make_sketch(root, "examples/path/sketch1") + _make_sketch(root, "examples/other/sketch2") + result = find_sketch_by_partial_name("path/sketch1", root) + self.assertTrue(result.match("**/path/sketch1")) + + def test_best_match_exact_name(self) -> None: + """When multiple partial matches exist, an exact directory name wins.""" + with TemporaryDirectory() as tmp: + root = Path(tmp) + _make_sketch(root, "examples/sketch") + _make_sketch(root, "examples/sketch1") + _make_sketch(root, "examples/sketch2") + result = find_sketch_by_partial_name("sketch", root) + self.assertEqual("sketch", result.name) + + def test_multiple_exact_matches_errors(self) -> None: + """Multiple exact directory-name matches should error.""" + with TemporaryDirectory() as tmp: + root = Path(tmp) + _make_sketch(root, "examples/group1/sketch") + _make_sketch(root, "examples/group2/sketch") + with self.assertRaises(ValueError): + find_sketch_by_partial_name("sketch", root) if __name__ == "__main__": From ad6957781d8fb3167af5ac64b4a318548ad9a943 Mon Sep 17 00:00:00 2001 From: zackees Date: Wed, 13 May 2026 15:17:44 -0700 Subject: [PATCH 3/3] feat(rust): port frontend bundling; unwind Python build round-trip 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/// 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 --- crates/fastled-cli/src/archive.rs | 1 - crates/fastled-cli/src/build.rs | 166 ++++++---- crates/fastled-cli/src/frontend.rs | 487 +++++++++++++++++++++++++++++ crates/fastled-cli/src/install.rs | 3 +- crates/fastled-cli/src/lib.rs | 3 +- crates/fastled-cli/src/viewer.rs | 85 ++++- crates/fastled-py/src/lib.rs | 90 ++---- src/fastled/frontend_esbuild.py | 163 +--------- src/fastled/open_browser.py | 129 +------- 9 files changed, 726 insertions(+), 401 deletions(-) create mode 100644 crates/fastled-cli/src/frontend.rs diff --git a/crates/fastled-cli/src/archive.rs b/crates/fastled-cli/src/archive.rs index 5ba38e6f..1c1b7a08 100644 --- a/crates/fastled-cli/src/archive.rs +++ b/crates/fastled-cli/src/archive.rs @@ -1,6 +1,5 @@ //! Archive download, verification, and extraction utilities. //! -//! Ports the core logic from `emscripten_archive.py` and `frontend_esbuild.py`: //! * HTTP(S) download with streaming //! * SHA-256 file verification //! * `.tar.zst` extraction (used for the emscripten toolchain) diff --git a/crates/fastled-cli/src/build.rs b/crates/fastled-cli/src/build.rs index 20377ad3..df64a3ce 100644 --- a/crates/fastled-cli/src/build.rs +++ b/crates/fastled-cli/src/build.rs @@ -3,10 +3,12 @@ //! The Rust CLI now drives the Python build service in-process through PyO3 //! instead of shelling out through `python -m fastled.app`. +use std::fs; use std::path::{Path, PathBuf}; use std::time::Instant; use anyhow::{Context, Result}; +use pyo3::exceptions::PyKeyboardInterrupt; use pyo3::prelude::*; use pyo3::types::{PyDict, PyModule}; @@ -100,22 +102,16 @@ fn workspace_python_source() -> Option { src_dir.is_dir().then_some(src_dir) } -fn py_path(py: Python<'_>, path: &Path) -> PyResult> { - let pathlib = PyModule::import(py, "pathlib")?; - let cls = pathlib.getattr("Path")?; - Ok(cls - .call1((path.to_string_lossy().as_ref(),))? - .into_any() - .unbind()) +fn normalize_path(path: &Path) -> PathBuf { + fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf()) } -fn py_fspath(value: &Bound<'_, PyAny>) -> PyResult { - let py = value.py(); - let os = PyModule::import(py, "os")?; - let fspath = os.getattr("fspath")?; - let path_value = fspath.call1((value,))?; - let path_str: String = path_value.extract()?; - Ok(PathBuf::from(path_str)) +/// Canonicalize a sketch/`fastled_path` so the toolchain key registered with +/// `NativeBuildService.register_toolchain` matches the key passed into +/// `NativeBuildService.build` — mirrors `_toolchain_key` in +/// `src/fastled/build_service.py`. +fn toolchain_key(fastled_path: Option<&Path>) -> Option { + fastled_path.map(|p| normalize_path(p).to_string_lossy().into_owned()) } fn ensure_workspace_src_on_sys_path(py: Python<'_>) -> PyResult<()> { @@ -140,13 +136,11 @@ fn run_build_embedded(request: &BuildRequest) -> Result { ensure_workspace_src_on_sys_path(py) .context("failed to add workspace Python sources to sys.path")?; - let build_service_mod = PyModule::import(py, "fastled.build_service") - .context("import fastled.build_service")?; - let build_types_mod = - PyModule::import(py, "fastled.build_types").context("import fastled.build_types")?; + let native_mod = + PyModule::import(py, "fastled._native").context("import fastled._native")?; let types_mod = PyModule::import(py, "fastled.types").context("import fastled.types")?; - let build_mode = types_mod + let build_mode_obj = types_mod .getattr("BuildMode") .context("BuildMode enum missing")? .getattr(request.build_mode.py_member_name()) @@ -154,66 +148,102 @@ fn run_build_embedded(request: &BuildRequest) -> Result { format!("BuildMode.{} missing", request.build_mode.py_member_name()) })?; - let request_kwargs = PyDict::new(py); - request_kwargs - .set_item("sketch_dir", py_path(py, &request.sketch_dir)?) - .context("set sketch_dir")?; - request_kwargs - .set_item("build_mode", &build_mode) - .context("set build_mode")?; - request_kwargs - .set_item("profile", request.profile) - .context("set profile")?; + let service = native_mod + .getattr("NativeBuildService") + .context("NativeBuildService class missing")? + .call0() + .context("construct NativeBuildService")?; + + // Register the Emscripten toolchain inline (still Python-owned). + let toolchain_mod = PyModule::import(py, "fastled.toolchain.emscripten") + .context("import fastled.toolchain.emscripten")?; + let toolchain_kwargs = PyDict::new(py); match &request.fastled_path { - Some(path) => request_kwargs - .set_item("fastled_path", py_path(py, path)?) - .context("set fastled_path")?, - None => request_kwargs + Some(path) => toolchain_kwargs + .set_item("fastled_path", path.to_string_lossy().as_ref()) + .context("set toolchain fastled_path")?, + None => toolchain_kwargs .set_item("fastled_path", py.None()) - .context("set fastled_path none")?, + .context("set toolchain fastled_path none")?, } - request_kwargs - .set_item("force_clean", request.force_clean) - .context("set force_clean")?; - - let build_request = build_types_mod - .getattr("BuildRequest") - .context("BuildRequest class missing")? - .call((), Some(&request_kwargs)) - .context("construct BuildRequest")?; - - let service = build_service_mod - .getattr("BuildService") - .context("BuildService class missing")? - .call0() - .context("construct BuildService")?; + let toolchain = toolchain_mod + .getattr("EmscriptenToolchain") + .context("EmscriptenToolchain class missing")? + .call((), Some(&toolchain_kwargs)) + .context("construct EmscriptenToolchain")?; + + let key = toolchain_key(request.fastled_path.as_deref()); + service + .call_method1("register_toolchain", (toolchain, key.clone())) + .context("register_toolchain")?; + + let sketch_dir_str = request.sketch_dir.to_string_lossy().into_owned(); + let build_mode_str = request.build_mode.py_member_name(); + + let build_call = service.call_method1( + "build", + ( + sketch_dir_str.as_str(), + build_mode_str, + build_mode_obj, + request.profile, + key.clone(), + request.force_clean, + ), + ); + + let result = match build_call { + Ok(r) => r, + Err(err) => { + if err.is_instance_of::(py) { + // Mirror the Python wrapper: route through + // fastled.interrupts.handle_keyboard_interrupt so a + // worker-thread Ctrl+C wakes the main thread. + if let Ok(interrupts) = PyModule::import(py, "fastled.interrupts") { + if let Ok(handler) = interrupts.getattr("handle_keyboard_interrupt") { + let _ = handler.call1((err.clone_ref(py),)); + } + } + } + return Err(err).context("NativeBuildService.build failed"); + } + }; - let result = service - .call_method1("build", (build_request,)) - .context("BuildService.build failed")?; + let result_dict = result + .downcast_into::() + .map_err(|e| anyhow::anyhow!("NativeBuildService.build returned non-dict: {e}"))?; - let success: bool = result - .getattr("success") + let success: bool = result_dict + .get_item("success") .context("missing build result success")? + .ok_or_else(|| anyhow::anyhow!("missing build result success"))? .extract() .context("extract build success")?; - let output: String = result - .getattr("stdout") + let output: String = result_dict + .get_item("stdout") .context("missing build result stdout")? + .ok_or_else(|| anyhow::anyhow!("missing build result stdout"))? .extract() .context("extract build stdout")?; - let strategy: String = result - .getattr("strategy") + let strategy: String = result_dict + .get_item("strategy") .context("missing build strategy")? + .ok_or_else(|| anyhow::anyhow!("missing build strategy"))? .extract() .context("extract build strategy")?; - let sketch_time_secs: f64 = result - .getattr("sketch_time") + let sketch_time_secs: f64 = result_dict + .get_item("sketch_time") .context("missing sketch_time")? + .ok_or_else(|| anyhow::anyhow!("missing sketch_time"))? .extract() .context("extract sketch_time")?; - let output_dir = py_fspath(&result.getattr("output_dir").context("missing output_dir")?) + let output_dir_str: String = result_dict + .get_item("output_dir") + .context("missing output_dir")? + .ok_or_else(|| anyhow::anyhow!("missing output_dir"))? + .extract() .context("extract output_dir")?; + let output_dir = PathBuf::from(output_dir_str); Ok(BuildResult { success, @@ -407,6 +437,20 @@ mod tests { assert!(src_dir.is_dir()); } + #[test] + fn test_toolchain_key_is_none_when_unset() { + assert_eq!(toolchain_key(None), None); + } + + #[test] + fn test_toolchain_key_returns_some_when_set() { + // The canonicalize call may fail for nonexistent paths and fall back + // to the input path, which is fine for this test. + let p = PathBuf::from("/tmp/fastled-test-keypath-does-not-exist"); + let key = toolchain_key(Some(&p)); + assert!(key.is_some()); + } + // ------------------------------------------------------------------ // BuildResult // ------------------------------------------------------------------ diff --git a/crates/fastled-cli/src/frontend.rs b/crates/fastled-cli/src/frontend.rs new file mode 100644 index 00000000..1d282aa4 --- /dev/null +++ b/crates/fastled-cli/src/frontend.rs @@ -0,0 +1,487 @@ +//! Frontend bundling: esbuild orchestration + frontend asset copy. +//! +//! Runs esbuild over `src/fastled/frontend/app.ts` and +//! `modules/core/fastled_background_worker.ts`, materialises the result under +//! `/dist/`, then copies the contents of that dist directory into the +//! sketch output. A SHA-256 hash marker (`.frontend_hash`) lives at the output +//! root so repeat invocations skip the copy when nothing changed. + +use std::fs::{self, File}; +use std::io::Read; +use std::path::{Component, Path, PathBuf}; +use std::process::Command; +use std::time::UNIX_EPOCH; + +use anyhow::{Context, Result}; +use sha2::{Digest, Sha256}; + +use crate::install; + +// --------------------------------------------------------------------------- +// Source/dist resolution +// --------------------------------------------------------------------------- + +fn workspace_root() -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")) + .parent() + .and_then(Path::parent) + .map(Path::to_path_buf) + .unwrap_or_else(|| PathBuf::from(env!("CARGO_MANIFEST_DIR"))) +} + +/// Walk up from `CARGO_MANIFEST_DIR` looking for the workspace's +/// `src/fastled/frontend` directory. +fn default_source_dir() -> Result { + let candidate = workspace_root() + .join("src") + .join("fastled") + .join("frontend"); + if candidate.is_dir() { + return Ok(candidate); + } + // Fall back to walking parents (defensive: layout may shift). + let mut current = Some(workspace_root()); + while let Some(dir) = current { + let candidate = dir.join("src").join("fastled").join("frontend"); + if candidate.is_dir() { + return Ok(candidate); + } + current = dir.parent().map(Path::to_path_buf); + } + anyhow::bail!( + "could not locate src/fastled/frontend relative to CARGO_MANIFEST_DIR={}", + env!("CARGO_MANIFEST_DIR") + ) +} + +/// Resolve the esbuild binary path. +/// +/// Honours `FASTLED_ESBUILD_PATH` when set (so a Rust CLI run can re-use the +/// freshly-installed binary), otherwise falls back to +/// `install::ensure_esbuild_installed()`. +fn resolve_esbuild() -> Result { + if let Ok(path) = std::env::var("FASTLED_ESBUILD_PATH") { + let candidate = PathBuf::from(path); + if candidate.is_file() { + return Ok(candidate); + } + } + install::ensure_esbuild_installed().context("ensure esbuild installed") +} + +// --------------------------------------------------------------------------- +// Filesystem helpers +// --------------------------------------------------------------------------- + +/// Returns `true` when any component of `path` (relative to `root`) is +/// literally `dist`. +fn path_contains_dist_component(root: &Path, path: &Path) -> bool { + let relative = path.strip_prefix(root).unwrap_or(path); + relative + .components() + .any(|comp| matches!(comp, Component::Normal(name) if name == "dist")) +} + +/// Recursively collect every regular file under `dir`, skipping any sub-tree +/// whose path contains a component named `dist`. Returns a sorted list of +/// absolute paths. +fn walk_files(dir: &Path) -> Vec { + fn inner(root: &Path, current: &Path, out: &mut Vec) { + let Ok(entries) = fs::read_dir(current) else { + return; + }; + for entry in entries.flatten() { + let path = entry.path(); + if path_contains_dist_component(root, &path) { + continue; + } + let Ok(file_type) = entry.file_type() else { + continue; + }; + if file_type.is_dir() { + inner(root, &path, out); + } else if file_type.is_file() { + out.push(path); + } + } + } + + let mut files = Vec::new(); + inner(dir, dir, &mut files); + files.sort(); + files +} + +/// Maximum mtime (seconds since UNIX epoch) over every non-`dist` file under +/// `source_dir`. Returns 0.0 when no files are found. +fn get_source_mtime(source_dir: &Path) -> Result { + let mut max_mtime = 0.0f64; + for path in walk_files(source_dir) { + let meta = fs::metadata(&path).with_context(|| format!("stat {}", path.display()))?; + let modified = meta + .modified() + .with_context(|| format!("modified mtime missing for {}", path.display()))?; + let secs = modified + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0); + if secs > max_mtime { + max_mtime = secs; + } + } + Ok(max_mtime) +} + +/// SHA-256 over a deterministic iteration of (relative path bytes, file bytes) +/// for every regular file under `dir`. Output is lower-case hex. +fn compute_dir_hash(dir: &Path) -> Result { + let mut hasher = Sha256::new(); + let mut files: Vec = Vec::new(); + fn collect(current: &Path, out: &mut Vec) { + let Ok(entries) = fs::read_dir(current) else { + return; + }; + for entry in entries.flatten() { + let path = entry.path(); + let Ok(file_type) = entry.file_type() else { + continue; + }; + if file_type.is_dir() { + collect(&path, out); + } else if file_type.is_file() { + out.push(path); + } + } + } + collect(dir, &mut files); + files.sort(); + + for file_path in &files { + let relative = file_path.strip_prefix(dir).unwrap_or(file_path); + // Normalise separators so cross-platform hashes match. + let relative_str = relative.to_string_lossy().replace('\\', "/"); + hasher.update(relative_str.as_bytes()); + + let mut file = + File::open(file_path).with_context(|| format!("open {}", file_path.display()))?; + let mut buf = vec![0u8; 1024 * 64]; + loop { + let n = file + .read(&mut buf) + .with_context(|| format!("read {}", file_path.display()))?; + if n == 0 { + break; + } + hasher.update(&buf[..n]); + } + } + + Ok(format!("{:x}", hasher.finalize())) +} + +fn copy_file(src: &Path, dst: &Path) -> Result<()> { + if let Some(parent) = dst.parent() { + fs::create_dir_all(parent) + .with_context(|| format!("create parent {}", parent.display()))?; + } + fs::copy(src, dst).with_context(|| format!("copy {} -> {}", src.display(), dst.display()))?; + Ok(()) +} + +fn copy_tree(src: &Path, dst: &Path) -> Result<()> { + if dst.exists() { + fs::remove_dir_all(dst) + .with_context(|| format!("remove existing dst {}", dst.display()))?; + } + fs::create_dir_all(dst).with_context(|| format!("create dst {}", dst.display()))?; + for entry in fs::read_dir(src).with_context(|| format!("read_dir {}", src.display()))? { + let entry = entry?; + let path = entry.path(); + let target = dst.join(entry.file_name()); + let file_type = entry.file_type()?; + if file_type.is_dir() { + copy_tree(&path, &target)?; + } else if file_type.is_file() { + copy_file(&path, &target)?; + } + } + Ok(()) +} + +// --------------------------------------------------------------------------- +// esbuild orchestration +// --------------------------------------------------------------------------- + +fn run_esbuild(esbuild: &Path, source_dir: &Path, args: &[String]) -> Result<()> { + let status = Command::new(esbuild) + .arg("--alias:three=./vendor/three/build/three.module.js") + .args(args) + .current_dir(source_dir) + .status() + .with_context(|| format!("spawn esbuild at {}", esbuild.display()))?; + if !status.success() { + anyhow::bail!( + "esbuild failed with exit code {}", + status.code().unwrap_or(-1) + ); + } + Ok(()) +} + +fn build_dist(source_dir: &Path) -> Result { + let dist_dir = source_dir.join("dist"); + let marker = dist_dir.join(".esbuild_marker"); + let source_mtime = get_source_mtime(source_dir)?; + + if dist_dir.exists() && marker.exists() { + if let Ok(text) = fs::read_to_string(&marker) { + if let Ok(value) = text.trim().parse::() { + if value >= source_mtime { + return Ok(dist_dir); + } + } + } + } + + if dist_dir.exists() { + fs::remove_dir_all(&dist_dir) + .with_context(|| format!("remove dist {}", dist_dir.display()))?; + } + fs::create_dir_all(&dist_dir).with_context(|| format!("create dist {}", dist_dir.display()))?; + + let esbuild = resolve_esbuild()?; + + let app_ts = source_dir.join("app.ts"); + let app_out = dist_dir.join("app.js"); + run_esbuild( + &esbuild, + source_dir, + &[ + app_ts.to_string_lossy().into_owned(), + "--bundle".to_string(), + "--format=esm".to_string(), + "--platform=browser".to_string(), + "--target=es2021".to_string(), + "--sourcemap".to_string(), + format!("--outfile={}", app_out.display()), + "--log-level=warning".to_string(), + ], + )?; + + let worker_ts = source_dir + .join("modules") + .join("core") + .join("fastled_background_worker.ts"); + let worker_out = dist_dir.join("fastled_background_worker.js"); + run_esbuild( + &esbuild, + source_dir, + &[ + worker_ts.to_string_lossy().into_owned(), + "--bundle".to_string(), + "--format=esm".to_string(), + "--platform=browser".to_string(), + "--target=es2021".to_string(), + "--sourcemap".to_string(), + format!("--outfile={}", worker_out.display()), + "--log-level=warning".to_string(), + ], + )?; + + let index_src = source_dir.join("index.html"); + let index_html = fs::read_to_string(&index_src) + .with_context(|| format!("read {}", index_src.display()))? + .replace("./app.ts", "./app.js"); + fs::write(dist_dir.join("index.html"), index_html) + .with_context(|| format!("write {}", dist_dir.join("index.html").display()))?; + + copy_file(&source_dir.join("index.css"), &dist_dir.join("index.css"))?; + copy_file( + &source_dir + .join("modules") + .join("audio") + .join("audio_worklet_processor.js"), + &dist_dir.join("audio_worklet_processor.js"), + )?; + + let assets_dir = source_dir.join("assets"); + if assets_dir.exists() { + copy_tree(&assets_dir, &dist_dir.join("assets"))?; + } + + fs::write(&marker, format!("{}", source_mtime)) + .with_context(|| format!("write marker {}", marker.display()))?; + Ok(dist_dir) +} + +// --------------------------------------------------------------------------- +// Public entry point +// --------------------------------------------------------------------------- + +/// Build the frontend (if stale) and copy the bundled output into `output_dir`. +/// +/// Mirrors `src/fastled/frontend_esbuild.py::copy_frontend_to_output`. When +/// `source_dir` is `None`, the frontend tree is located relative to the +/// workspace `CARGO_MANIFEST_DIR`. +pub fn copy_frontend_to_output(output_dir: &Path, source_dir: Option<&Path>) -> Result<()> { + let source = match source_dir { + Some(path) => path.to_path_buf(), + None => default_source_dir()?, + }; + let dist_dir = build_dist(&source)?; + + let hash_marker = output_dir.join(".frontend_hash"); + let current_hash = compute_dir_hash(&dist_dir)?; + if hash_marker.is_file() { + if let Ok(existing) = fs::read_to_string(&hash_marker) { + if existing.trim() == current_hash { + println!(" Frontend assets unchanged, skipping copy."); + return Ok(()); + } + } + } + + fs::create_dir_all(output_dir) + .with_context(|| format!("create output dir {}", output_dir.display()))?; + + for entry in + fs::read_dir(&dist_dir).with_context(|| format!("read_dir {}", dist_dir.display()))? + { + let entry = entry?; + let destination = output_dir.join(entry.file_name()); + let file_type = entry.file_type()?; + if file_type.is_dir() { + copy_tree(&entry.path(), &destination)?; + } else { + copy_file(&entry.path(), &destination)?; + } + } + + fs::write(&hash_marker, current_hash) + .with_context(|| format!("write hash marker {}", hash_marker.display()))?; + Ok(()) +} + +// --------------------------------------------------------------------------- +// Tests +// --------------------------------------------------------------------------- + +#[cfg(test)] +mod tests { + use super::*; + use std::thread; + use std::time::Duration; + use tempfile::TempDir; + + fn write(path: &Path, content: &[u8]) { + if let Some(parent) = path.parent() { + fs::create_dir_all(parent).unwrap(); + } + fs::write(path, content).unwrap(); + } + + #[test] + fn compute_dir_hash_is_deterministic() { + let dir = TempDir::new().unwrap(); + let root = dir.path(); + // Create files in mixed order; the function must sort internally. + write(&root.join("b.txt"), b"bravo"); + write(&root.join("a.txt"), b"alpha"); + write(&root.join("sub").join("c.txt"), b"charlie"); + + let h1 = compute_dir_hash(root).unwrap(); + // Slight pause so any mtime-based caching wouldn't pollute the hash; + // compute_dir_hash itself only hashes content, but be defensive. + thread::sleep(Duration::from_millis(5)); + let h2 = compute_dir_hash(root).unwrap(); + assert_eq!(h1, h2, "hash must be deterministic across calls"); + } + + #[test] + fn compute_dir_hash_changes_on_content_change() { + let dir = TempDir::new().unwrap(); + let root = dir.path(); + write(&root.join("a.txt"), b"alpha"); + + let h1 = compute_dir_hash(root).unwrap(); + write(&root.join("a.txt"), b"alpha!"); + let h2 = compute_dir_hash(root).unwrap(); + assert_ne!(h1, h2, "hash must differ when a file body changes"); + } + + #[test] + fn walk_files_skips_dist_subtree() { + let dir = TempDir::new().unwrap(); + let root = dir.path(); + write(&root.join("app.ts"), b"// app"); + write(&root.join("dist").join("app.js"), b"// built"); + write(&root.join("modules").join("util.ts"), b"// util"); + write(&root.join("mydist").join("note.txt"), b"// kept"); + + let files = walk_files(root); + let names: Vec = files + .iter() + .map(|p| { + p.strip_prefix(root) + .unwrap() + .to_string_lossy() + .replace('\\', "/") + }) + .collect(); + assert!(names.contains(&"app.ts".to_string())); + assert!(names.contains(&"modules/util.ts".to_string())); + assert!( + names.contains(&"mydist/note.txt".to_string()), + "must not skip dirs that merely contain 'dist' in name" + ); + assert!( + !names.iter().any(|n| n.starts_with("dist/")), + "must skip the dist/ subtree, got {names:?}" + ); + } + + #[test] + fn copy_frontend_to_output_skips_when_marker_matches() { + // Stand up a fake dist tree, point copy_frontend_to_output at a source + // that *already* has a populated dist + matching marker, so build_dist + // returns immediately. Then run copy twice and confirm the second + // invocation short-circuits on the hash marker. + let workspace = TempDir::new().unwrap(); + let source = workspace.path().join("frontend"); + let dist = source.join("dist"); + fs::create_dir_all(&dist).unwrap(); + write(&dist.join("app.js"), b"// stub app"); + write(&dist.join("index.html"), b"t"); + // Marker must satisfy `marker_value >= source_mtime` so build_dist is a + // no-op. Use a value far in the future so any reasonable source mtime + // is <= it. + write(&dist.join(".esbuild_marker"), b"9999999999.0"); + + let output = TempDir::new().unwrap(); + copy_frontend_to_output(output.path(), Some(&source)).expect("first copy"); + assert!(output.path().join("app.js").exists()); + let hash_after_first = fs::read_to_string(output.path().join(".frontend_hash")).unwrap(); + + // Touch nothing; second call must be a no-op (marker matches). + let app_js_meta_before = fs::metadata(output.path().join("app.js")) + .unwrap() + .modified() + .unwrap(); + thread::sleep(Duration::from_millis(20)); + copy_frontend_to_output(output.path(), Some(&source)).expect("second copy"); + let app_js_meta_after = fs::metadata(output.path().join("app.js")) + .unwrap() + .modified() + .unwrap(); + let hash_after_second = fs::read_to_string(output.path().join(".frontend_hash")).unwrap(); + + assert_eq!( + hash_after_first, hash_after_second, + "hash marker must be stable across no-op copies" + ); + assert_eq!( + app_js_meta_before, app_js_meta_after, + "files must not be re-copied when the hash marker already matches" + ); + } +} diff --git a/crates/fastled-cli/src/install.rs b/crates/fastled-cli/src/install.rs index c9d805c0..2747fd42 100644 --- a/crates/fastled-cli/src/install.rs +++ b/crates/fastled-cli/src/install.rs @@ -216,8 +216,7 @@ fn esbuild_platform_arch() -> Result<(&'static str, &'static str)> { /// `~/.fastled/toolchains/esbuild/{platform}/{arch}/{version}/`. /// Returns the path to the executable. /// -/// Layout matches the previous Python implementation -/// (`src/fastled/frontend_esbuild.py`). +/// Used by `crates/fastled-cli/src/frontend.rs` to bundle frontend assets. pub fn ensure_esbuild_installed() -> Result { let (platform, arch) = esbuild_platform_arch()?; let version = ESBUILD_VERSION; diff --git a/crates/fastled-cli/src/lib.rs b/crates/fastled-cli/src/lib.rs index fa32b647..3b262385 100644 --- a/crates/fastled-cli/src/lib.rs +++ b/crates/fastled-cli/src/lib.rs @@ -7,11 +7,12 @@ use std::process::{Command, ExitCode}; mod archive; mod build; +pub mod frontend; pub mod install; mod keyboard; pub mod project; mod server; -mod viewer; +pub mod viewer; mod watcher; const DEFAULT_EXAMPLE: &str = "wasm"; diff --git a/crates/fastled-cli/src/viewer.rs b/crates/fastled-cli/src/viewer.rs index 8143a861..3ad2e662 100644 --- a/crates/fastled-cli/src/viewer.rs +++ b/crates/fastled-cli/src/viewer.rs @@ -25,9 +25,9 @@ const VIEWER_EXE: &str = "fastled-viewer"; /// /// Search order: /// 1. Same directory as the currently running executable. -/// 2. `target/debug/` relative to the workspace root (detected via the -/// executable path heuristic or `CARGO_MANIFEST_DIR`). -/// 3. `target/release/` via the same heuristic. +/// 2. `target/debug/` and `target/release/` relative to the workspace root +/// (detected via the executable path heuristic or `CARGO_MANIFEST_DIR`). +/// 3. `target//{debug,release}/` for cross-compiled builds. /// 4. `PATH` — `which`-style lookup via [`Command::new`]. /// /// Returns `None` if the binary cannot be found. @@ -43,8 +43,8 @@ pub fn find_tauri_viewer() -> Option { } // 2. Walk up from the current executable to find a Cargo workspace root - // (directory that contains a `Cargo.toml` with `[workspace]`), then - // check `target/debug` and `target/release`. + // (directory that contains a `Cargo.toml`), then check `target/debug` + // and `target/release`. if let Some(workspace_root) = find_workspace_root() { for profile in &["debug", "release"] { let candidate = workspace_root.join("target").join(profile).join(VIEWER_EXE); @@ -52,9 +52,16 @@ pub fn find_tauri_viewer() -> Option { return Some(candidate); } } + + // 3. Scan `target//{debug,release}/` for cross-compiled + // artifacts (e.g. `target/x86_64-pc-windows-msvc/release/`). + let target_dir = workspace_root.join("target"); + if let Some(candidate) = find_viewer_in_arch_dirs(&target_dir) { + return Some(candidate); + } } - // 3. Fall back to PATH lookup. + // 4. Fall back to PATH lookup. if is_on_path(VIEWER_EXE) { // Return just the bare name so the OS resolves it through PATH. return Some(PathBuf::from(VIEWER_EXE)); @@ -63,6 +70,28 @@ pub fn find_tauri_viewer() -> Option { None } +/// Scan ``//{debug,release}/`` for the viewer binary. +/// Skips dotfiles and non-directory entries. +fn find_viewer_in_arch_dirs(target_dir: &std::path::Path) -> Option { + let entries = std::fs::read_dir(target_dir).ok()?; + for entry in entries.flatten() { + let arch_dir = entry.path(); + if !arch_dir.is_dir() { + continue; + } + if entry.file_name().to_string_lossy().starts_with('.') { + continue; + } + for profile in &["debug", "release"] { + let candidate = arch_dir.join(profile).join(VIEWER_EXE); + if candidate.is_file() { + return Some(candidate); + } + } + } + None +} + /// Return `true` when the Tauri viewer binary can be found. #[inline] pub fn viewer_available() -> bool { @@ -134,6 +163,8 @@ fn is_on_path(name: &str) -> bool { #[cfg(test)] mod tests { use super::*; + use std::fs; + use tempfile::TempDir; #[test] fn test_viewer_available_does_not_panic() { @@ -156,4 +187,46 @@ mod tests { fn test_find_workspace_root_does_not_panic() { let _ = find_workspace_root(); } + + #[test] + fn test_find_viewer_in_arch_dirs_finds_binary() { + // Set up a fake target tree: + // /target/x86_64-pc-windows-msvc/release/fastled-viewer[.exe] + let tmp = TempDir::new().expect("tempdir"); + let target = tmp.path().join("target"); + let arch_dir = target.join("x86_64-pc-windows-msvc").join("release"); + fs::create_dir_all(&arch_dir).expect("mkdir arch_dir"); + let viewer_path = arch_dir.join(VIEWER_EXE); + fs::write(&viewer_path, b"fake binary").expect("write fake viewer"); + + let found = find_viewer_in_arch_dirs(&target).expect("expected to find viewer"); + assert_eq!(found, viewer_path); + } + + #[test] + fn test_find_viewer_in_arch_dirs_skips_dotfiles() { + // A hidden `.cache` dir should not be scanned. + let tmp = TempDir::new().expect("tempdir"); + let target = tmp.path().join("target"); + let hidden = target.join(".cache").join("debug"); + fs::create_dir_all(&hidden).expect("mkdir hidden"); + fs::write(hidden.join(VIEWER_EXE), b"fake").expect("write fake"); + + assert!(find_viewer_in_arch_dirs(&target).is_none()); + } + + #[test] + fn test_find_viewer_in_arch_dirs_returns_none_for_empty_tree() { + let tmp = TempDir::new().expect("tempdir"); + let target = tmp.path().join("target"); + fs::create_dir_all(&target).expect("mkdir target"); + assert!(find_viewer_in_arch_dirs(&target).is_none()); + } + + #[test] + fn test_find_viewer_in_arch_dirs_missing_target() { + let tmp = TempDir::new().expect("tempdir"); + let missing = tmp.path().join("does-not-exist"); + assert!(find_viewer_in_arch_dirs(&missing).is_none()); + } } diff --git a/crates/fastled-py/src/lib.rs b/crates/fastled-py/src/lib.rs index cc2f6219..175441ce 100644 --- a/crates/fastled-py/src/lib.rs +++ b/crates/fastled-py/src/lib.rs @@ -1,5 +1,7 @@ +use fastled_cli::frontend; use fastled_cli::install; use fastled_cli::project; +use fastled_cli::viewer; use fastled_cli::{PromptChoice, SketchSelection}; use pyo3::exceptions::{PyRuntimeError, PyValueError}; use pyo3::prelude::*; @@ -9,69 +11,9 @@ use std::collections::HashMap; use std::fs; use std::io::{self, Write}; use std::path::{Path, PathBuf}; -use std::process::Command; use std::time::Instant; use zip::write::SimpleFileOptions; -// --------------------------------------------------------------------------- -// Internal: Tauri viewer discovery (mirrors viewer.rs in fastled-cli) -// --------------------------------------------------------------------------- - -#[cfg(windows)] -const VIEWER_EXE: &str = "fastled-viewer.exe"; -#[cfg(not(windows))] -const VIEWER_EXE: &str = "fastled-viewer"; - -fn find_tauri_viewer_path() -> Option { - // 1. Sibling of the running shared library / executable. - if let Ok(exe) = std::env::current_exe() { - if let Some(dir) = exe.parent() { - let candidate = dir.join(VIEWER_EXE); - if candidate.is_file() { - return Some(candidate); - } - } - } - - // 2. Walk up from the current executable looking for a Cargo workspace root, - // then check target/debug and target/release. - if let Some(root) = find_workspace_root_py() { - for profile in &["debug", "release"] { - let candidate = root.join("target").join(profile).join(VIEWER_EXE); - if candidate.is_file() { - return Some(candidate); - } - } - } - - // 3. PATH lookup. - let on_path = Command::new(VIEWER_EXE) - .arg("--version") - .output() - .map(|o| o.status.success()) - .unwrap_or(false); - if on_path { - return Some(PathBuf::from(VIEWER_EXE)); - } - - None -} - -fn find_workspace_root_py() -> Option { - let start = std::env::current_exe().ok()?; - let mut dir = start.parent()?.to_path_buf(); - for _ in 0..10 { - if dir.join("Cargo.toml").is_file() { - return Some(dir.clone()); - } - match dir.parent() { - Some(p) => dir = p.to_path_buf(), - None => break, - } - } - None -} - // --------------------------------------------------------------------------- // Internal: Native BuildService // --------------------------------------------------------------------------- @@ -605,6 +547,7 @@ impl NativeBuildService { } #[pyo3(signature = (sketch_dir, build_mode, build_mode_obj, profile=false, fastled_path=None, force_clean=false))] + #[allow(clippy::too_many_arguments)] fn build( &mut self, py: Python<'_>, @@ -783,6 +726,7 @@ impl NativeBuildService { py_fspath(py, &js_file) } + #[allow(clippy::too_many_arguments)] fn build_payload( py: Python<'_>, success: bool, @@ -997,7 +941,16 @@ fn build_available() -> bool { /// found alongside the CLI, in the Cargo target directory, or on PATH. #[pyfunction] fn viewer_available() -> bool { - find_tauri_viewer_path().is_some() + viewer::find_tauri_viewer().is_some() +} + +/// Locate the `fastled-viewer` (Tauri) binary. Returns `None` if not found. +/// +/// Delegates to `fastled_cli::viewer::find_tauri_viewer` so the Python shim no +/// longer duplicates the discovery logic. +#[pyfunction] +fn find_fastled_viewer() -> Option { + viewer::find_tauri_viewer().map(|p| p.to_string_lossy().into_owned()) } #[pyfunction] @@ -1014,6 +967,19 @@ fn string_diff( string_diff_impl(input_string, &string_list, ignore_case) } +/// Build the FastLED frontend (if stale) and copy it into ``output_dir``. +/// +/// Mirrors ``src/fastled/frontend_esbuild.py::copy_frontend_to_output`` so the +/// Python shim can delegate without re-implementing the bundling logic. +#[pyfunction] +#[pyo3(signature = (output_dir, source_dir=None))] +fn copy_frontend_to_output(output_dir: &str, source_dir: Option<&str>) -> PyResult<()> { + let out = PathBuf::from(output_dir); + let src = source_dir.map(PathBuf::from); + frontend::copy_frontend_to_output(&out, src.as_deref()) + .map_err(|e| PyRuntimeError::new_err(format!("{e:#}"))) +} + /// FastLED native extension module. #[pymodule] fn _native(m: &Bound<'_, PyModule>) -> PyResult<()> { @@ -1037,8 +1003,10 @@ fn _native(m: &Bound<'_, PyModule>) -> PyResult<()> { m.add_function(wrap_pyfunction!(init_example_from_repo, m)?)?; m.add_function(wrap_pyfunction!(build_available, m)?)?; m.add_function(wrap_pyfunction!(viewer_available, m)?)?; + m.add_function(wrap_pyfunction!(find_fastled_viewer, m)?)?; m.add_function(wrap_pyfunction!(is_in_order_match, m)?)?; m.add_function(wrap_pyfunction!(string_diff, m)?)?; + m.add_function(wrap_pyfunction!(copy_frontend_to_output, m)?)?; Ok(()) } diff --git a/src/fastled/frontend_esbuild.py b/src/fastled/frontend_esbuild.py index 426b4af7..fd253f47 100644 --- a/src/fastled/frontend_esbuild.py +++ b/src/fastled/frontend_esbuild.py @@ -1,160 +1,19 @@ -from __future__ import annotations - -import hashlib -import os -import shutil -import subprocess -from pathlib import Path - -FRONTEND_DIR = Path(__file__).resolve().parent / "frontend" - - -def _resolve_esbuild() -> Path: - """Return the path to the esbuild binary. - - The Rust CLI installs esbuild via ``crates/fastled-cli/src/install.rs`` - and exports the path through ``FASTLED_ESBUILD_PATH``. If that env var - is missing (e.g. Python invoked directly without the Rust pre-step), the - function falls back to the binary on ``PATH``. - """ - env_path = os.environ.get("FASTLED_ESBUILD_PATH") - if env_path: - candidate = Path(env_path) - if candidate.is_file(): - return candidate - located = shutil.which("esbuild") - if located: - return Path(located) - raise RuntimeError( - "esbuild binary not available. Ensure FASTLED_ESBUILD_PATH is set by " - "the Rust CLI or that esbuild is on PATH." - ) - - -def _copy_tree(src: Path, dst: Path) -> None: - if dst.exists(): - shutil.rmtree(dst) - shutil.copytree(src, dst) - - -def _copy_file(src: Path, dst: Path) -> None: - dst.parent.mkdir(parents=True, exist_ok=True) - shutil.copy2(src, dst) - +"""Compatibility shim. Frontend bundling is implemented in Rust. -def _get_source_mtime(source_dir: Path) -> float: - max_mtime = 0.0 - skip_names = frozenset(("dist",)) - for path in source_dir.rglob("*"): - if any(part in skip_names for part in path.parts): - continue - if path.is_file(): - max_mtime = max(max_mtime, path.stat().st_mtime) - return max_mtime +See ``crates/fastled-cli/src/frontend.rs`` for the implementation; this module +exists so existing callers (``fastled.toolchain.emscripten``, +``fastled.toolchain.internal_wasm_build``) keep working without churn. +""" +from __future__ import annotations -def _compute_dir_hash(directory: Path) -> str: - digest = hashlib.md5(usedforsecurity=False) - for file_path in sorted(p for p in directory.rglob("*") if p.is_file()): - digest.update(str(file_path.relative_to(directory)).encode("utf-8")) - digest.update(file_path.read_bytes()) - return digest.hexdigest() - - -def _run_esbuild(source_dir: Path, args: list[str]) -> None: - esbuild = _resolve_esbuild() - result = subprocess.run( - [ - str(esbuild), - "--alias:three=./vendor/three/build/three.module.js", - *args, - ], - cwd=str(source_dir), - ) - if result.returncode != 0: - raise RuntimeError(f"esbuild failed with exit code {result.returncode}") - - -def _build_dist(source_dir: Path) -> Path: - dist_dir = source_dir / "dist" - marker = dist_dir / ".esbuild_marker" - source_mtime = _get_source_mtime(source_dir) - if dist_dir.exists() and marker.exists(): - try: - if float(marker.read_text(encoding="utf-8").strip()) >= source_mtime: - return dist_dir - except ValueError: - pass - - if dist_dir.exists(): - shutil.rmtree(dist_dir) - dist_dir.mkdir(parents=True, exist_ok=True) - - _run_esbuild( - source_dir, - [ - str(source_dir / "app.ts"), - "--bundle", - "--format=esm", - "--platform=browser", - "--target=es2021", - "--sourcemap", - f"--outfile={source_dir / 'dist' / 'app.js'}", - "--log-level=warning", - ], - ) - _run_esbuild( - source_dir, - [ - str(source_dir / "modules" / "core" / "fastled_background_worker.ts"), - "--bundle", - "--format=esm", - "--platform=browser", - "--target=es2021", - "--sourcemap", - f"--outfile={source_dir / 'dist' / 'fastled_background_worker.js'}", - "--log-level=warning", - ], - ) - - index_html = ( - (source_dir / "index.html") - .read_text(encoding="utf-8") - .replace("./app.ts", "./app.js") - ) - (dist_dir / "index.html").write_text(index_html, encoding="utf-8") - _copy_file(source_dir / "index.css", dist_dir / "index.css") - _copy_file( - source_dir / "modules" / "audio" / "audio_worklet_processor.js", - dist_dir / "audio_worklet_processor.js", - ) +from pathlib import Path - assets_dir = source_dir / "assets" - if assets_dir.exists(): - _copy_tree(assets_dir, dist_dir / "assets") +from fastled._native import copy_frontend_to_output as _native_copy_frontend_to_output - marker.write_text(str(source_mtime), encoding="utf-8") - return dist_dir +FRONTEND_DIR = Path(__file__).resolve().parent / "frontend" def copy_frontend_to_output(output_dir: Path, source_dir: Path | None = None) -> None: - source = source_dir or FRONTEND_DIR - dist_dir = _build_dist(source) - - hash_marker = output_dir / ".frontend_hash" - current_hash = _compute_dir_hash(dist_dir) - if ( - hash_marker.exists() - and hash_marker.read_text(encoding="utf-8").strip() == current_hash - ): - print(" Frontend assets unchanged, skipping copy.") - return - - for item in dist_dir.iterdir(): - destination = output_dir / item.name - if item.is_dir(): - _copy_tree(item, destination) - else: - _copy_file(item, destination) - - hash_marker.write_text(current_hash, encoding="utf-8") + source = source_dir if source_dir is not None else FRONTEND_DIR + _native_copy_frontend_to_output(str(output_dir), str(source)) diff --git a/src/fastled/open_browser.py b/src/fastled/open_browser.py index 9841802b..3c5bde50 100644 --- a/src/fastled/open_browser.py +++ b/src/fastled/open_browser.py @@ -1,121 +1,13 @@ import atexit -import shutil import subprocess -import sys import time import weakref from pathlib import Path +from fastled._native import find_fastled_viewer +from fastled._rust_cli import find_rust_fastled_cli from fastled.interrupts import handle_keyboard_interrupt - -def _find_tauri_viewer() -> Path | None: - """Locate the fastled-viewer (Tauri) binary. - - Search order mirrors crates/fastled-cli/src/viewer.rs: - 1. Same directory as the running Python executable. - 2. target/debug/ and target/release/ relative to the project workspace. - 3. PATH lookup. - """ - exe_name = "fastled-viewer.exe" if sys.platform == "win32" else "fastled-viewer" - - # 1. Sibling of the running interpreter / entry-point script. - exe_path = Path(sys.executable).resolve() - candidate = exe_path.parent / exe_name - if candidate.is_file(): - return candidate - - # 2. Walk up to find a Cargo workspace root and check target dirs. - search_start = Path(__file__).resolve().parent # src/fastled/ - current = search_start - for _ in range(10): - cargo_toml = current / "Cargo.toml" - if cargo_toml.is_file(): - for profile in ("debug", "release"): - candidate = current / "target" / profile / exe_name - if candidate.is_file(): - return candidate - # Also check platform-specific target dir (e.g. target/x86_64-pc-windows-msvc/...) - target_dir = current / "target" - if target_dir.is_dir(): - for arch_dir in target_dir.iterdir(): - if arch_dir.is_dir() and not arch_dir.name.startswith("."): - for profile in ("debug", "release"): - candidate = arch_dir / profile / exe_name - if candidate.is_file(): - return candidate - break - parent = current.parent - if parent == current: - break - current = parent - - # 3. PATH lookup. - found = shutil.which(exe_name) - if found: - return Path(found) - - return None - - -def _launch_tauri_viewer(frontend_dir: Path) -> subprocess.Popen | None: - """Try to launch the Tauri viewer. Returns the process or None on failure.""" - viewer = _find_tauri_viewer() - if viewer is None: - return None - try: - proc = subprocess.Popen( - [str(viewer), "--frontend-dir", str(frontend_dir)], - ) - return proc - except KeyboardInterrupt as ki: - handle_keyboard_interrupt(ki) - except Exception: - return None - - -def _find_fastled_cli() -> Path | None: - """Locate the fastled CLI binary (Rust).""" - exe_name = "fastled.exe" if sys.platform == "win32" else "fastled" - - # 1. Sibling of the running interpreter. - exe_path = Path(sys.executable).resolve() - candidate = exe_path.parent / exe_name - if candidate.is_file(): - return candidate - - # 2. Walk up to find a Cargo workspace root and check target dirs. - search_start = Path(__file__).resolve().parent - current = search_start - for _ in range(10): - cargo_toml = current / "Cargo.toml" - if cargo_toml.is_file(): - for profile in ("debug", "release"): - candidate = current / "target" / profile / exe_name - if candidate.is_file(): - return candidate - target_dir = current / "target" - if target_dir.is_dir(): - for arch_dir in target_dir.iterdir(): - if arch_dir.is_dir() and not arch_dir.name.startswith("."): - for profile in ("debug", "release"): - candidate = arch_dir / profile / exe_name - if candidate.is_file(): - return candidate - break - parent = current.parent - if parent == current: - break - current = parent - - # 3. PATH lookup. - found = shutil.which(exe_name) - if found: - return Path(found) - - return None - - # Use a weak reference set to track processes without preventing garbage collection _WEAK_CLEANUP_SET: weakref.WeakSet = weakref.WeakSet() @@ -150,12 +42,13 @@ def spawn_http_server( ) -> subprocess.Popen: """Spawn the Rust CLI HTTP server as a subprocess. - This replaces the old Flask-based server. The Rust binary's - ``--serve-dir`` flag starts a native HTTP server. + The Rust binary's ``--serve-dir`` flag starts a native HTTP server and + auto-launches the Tauri viewer when the ``fastled-viewer`` binary is + available, so no Python-side viewer spawn is required. """ del app, enable_https, sketch_dir, fastled_path # handled by Rust - cli = _find_fastled_cli() + cli = find_rust_fastled_cli() if cli is None: raise RuntimeError("Could not find the fastled CLI binary") @@ -189,13 +82,15 @@ def spawn_http_server( url = f"http://localhost:{actual_port}" else: url = "http://localhost:8089" - tauri_proc = _launch_tauri_viewer(fastled_js) - if tauri_proc is not None: - print("Opening FastLED sketch in Tauri viewer") - else: + + # The Rust CLI auto-launches the viewer; only fall back to the system + # browser when no viewer binary is present. + if find_fastled_viewer() is None: print(f"Opening browser to {url}") import webbrowser webbrowser.open(url=url, new=1, autoraise=True) + else: + print("FastLED viewer will be launched by the Rust CLI") return proc