nff 0.1.0__py3-none-any.whl

nff/__init__.py

@@ -0,0 +1,3 @@
+"""nff — Claude Code IoT Bridge."""
+
+__version__ = "0.1.0"

nff/cli.py

@@ -0,0 +1,79 @@
+"""nff — entry point that wires all subcommands into one CLI."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.console import Console
+
+from nff import __version__
+
+if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+console = Console(legacy_windows=False)
+
+
+# ---------------------------------------------------------------------------
+# Root group
+# ---------------------------------------------------------------------------
+
+@click.group()
+@click.version_option(__version__, "-V", "--version", prog_name="nff")
+def cli() -> None:
+    """nff — Claude Code IoT Bridge.
+
+    Connects Claude Code to physical hardware devices via USB.
+    Run `nff init` to get started.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Subcommands
+# ---------------------------------------------------------------------------
+
+from nff.commands.init import init          # noqa: E402
+from nff.commands.flash import flash        # noqa: E402
+from nff.commands.monitor import monitor    # noqa: E402
+from nff.commands.doctor import doctor      # noqa: E402
+
+cli.add_command(init)
+cli.add_command(flash)
+cli.add_command(monitor)
+cli.add_command(doctor)
+
+
+@cli.command("install-deps")
+@click.option("--force", is_flag=True, help="Reinstall even if already present.")
+def install_deps(force: bool) -> None:
+    """Download and install arduino-cli (runs automatically during `nff init`)."""
+    from nff.tools import installer
+    console.print("[bold cyan]arduino-cli installer[/bold cyan]")
+    try:
+        exe = installer.install(force=force)
+        if not installer.verify(exe):
+            raise SystemExit(1)
+    except Exception as exc:
+        console.print(f"  [bold red]✗[/bold red] {exc}")
+        raise SystemExit(1)
+
+
+@cli.command()
+def mcp() -> None:
+    """Start the MCP server (stdio). Called automatically by Claude Code."""
+    from nff.mcp_server import main as _mcp_main
+    _mcp_main()
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """Setuptools / pipx entry point: ``nff = "nff.cli:main"``."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

nff/commands/doctor.py

@@ -0,0 +1,176 @@
+"""nff doctor — dependency and configuration health check."""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+
+# Fix sys.path when this file is run directly (`python doctor.py`).
+# Python adds commands/ to sys.path, making `nff` unresolvable.
+if __name__ == "__main__":
+    _pkg_parent = str(pathlib.Path(__file__).resolve().parents[2])
+    if _pkg_parent not in sys.path:
+        sys.path.insert(0, _pkg_parent)
+
+import importlib.metadata
+import json
+import platform
+import sys
+from pathlib import Path
+from typing import NamedTuple
+
+import click
+from rich.console import Console
+
+# Windows PowerShell defaults to cp1252 which can't encode ✓/✗.
+# Reconfigure stdout to UTF-8 before Rich initialises its stream.
+if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+from nff import config as cfg_module
+from nff.tools import boards as boards_module
+from nff.tools import toolchain
+
+console = Console(legacy_windows=False)
+
+_CLAUDE_DESKTOP_CONFIG = Path.home() / ".claude" / "claude_desktop_config.json"
+
+
+class Check(NamedTuple):
+    passed: bool
+    detail: str          # printed next to ✓ / ✗
+    fix: str | None = None   # hint shown when failed
+
+
+# ---------------------------------------------------------------------------
+# Individual checks
+# ---------------------------------------------------------------------------
+
+def check_python() -> Check:
+    v = sys.version_info
+    label = f"Python {v.major}.{v.minor}.{v.micro}"
+    if (v.major, v.minor) >= (3, 10):
+        return Check(True, label)
+    return Check(False, f"{label} — nff requires Python 3.10+", "Upgrade Python")
+
+
+def check_arduino_cli() -> Check:
+    version = toolchain.arduino_cli_version()
+    if version:
+        return Check(True, f"{version}  ({toolchain.find_arduino_cli()})")
+    return Check(
+        False,
+        "arduino-cli not found",
+        "Install from https://arduino.github.io/arduino-cli",
+    )
+
+
+def check_esptool() -> Check:
+    version = toolchain.esptool_version()
+    if version:
+        loc = toolchain.find_esptool() or "python -m esptool"
+        return Check(True, f"{version}  ({loc})")
+    return Check(False, "esptool not found", "Run: pip install esptool")
+
+
+def check_pyserial() -> Check:
+    try:
+        version = importlib.metadata.version("pyserial")
+        return Check(True, f"pyserial {version}")
+    except importlib.metadata.PackageNotFoundError:
+        return Check(False, "pyserial not installed", "Run: pip install pyserial")
+
+
+def check_config() -> Check:
+    if not cfg_module.exists():
+        return Check(False, "Config not found", "Run: nff init")
+    try:
+        cfg_module.load()
+        return Check(True, f"Config found at {cfg_module.CONFIG_PATH}")
+    except cfg_module.ConfigError as exc:
+        return Check(
+            False,
+            f"Config unreadable: {exc}",
+            f"Fix or delete {cfg_module.CONFIG_PATH}",
+        )
+
+
+def check_device() -> Check:
+    """Check that a recognised board is detected and its port is openable."""
+    # Lazy import — pyserial may not be installed; check_pyserial will flag it.
+    try:
+        import serial as _serial
+    except ImportError:
+        return Check(False, "Cannot check device — pyserial missing", "Run: pip install pyserial")
+
+    devices = boards_module.list_devices()
+    if not devices:
+        return Check(False, "No recognised board detected", "Plug in a board and run nff init")
+
+    device = devices[0]
+    label = f"Device detected: {device.board} on {device.port}"
+
+    try:
+        conn = _serial.Serial(device.port, timeout=0.5)
+        conn.close()
+    except _serial.SerialException as exc:
+        fix = f"Port {device.port} is inaccessible: {exc}"
+        if platform.system() == "Linux":
+            fix += "\n    → Add yourself to the dialout group: sudo usermod -aG dialout $USER"
+        return Check(False, f"{label} — port inaccessible", fix)
+
+    return Check(True, label)
+
+
+def check_claude_desktop() -> Check:
+    if not _CLAUDE_DESKTOP_CONFIG.exists():
+        return Check(False, "Claude Desktop config not found", "Run: nff init")
+    try:
+        data = json.loads(_CLAUDE_DESKTOP_CONFIG.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        return Check(False, f"Claude Desktop config unreadable: {exc}")
+    if "nff" not in data.get("mcpServers", {}):
+        return Check(
+            False,
+            "nff not registered in Claude Desktop config",
+            "Run: nff init",
+        )
+    return Check(True, f"Claude Desktop config OK  ({_CLAUDE_DESKTOP_CONFIG})")
+
+
+# ---------------------------------------------------------------------------
+# Click command
+# ---------------------------------------------------------------------------
+
+_CHECKS = [
+    check_python,
+    check_arduino_cli,
+    check_esptool,
+    check_pyserial,
+    check_config,
+    check_device,
+    check_claude_desktop,
+]
+
+
+@click.command()
+def doctor() -> None:
+    """Check dependencies, config, and device connectivity."""
+    any_failed = False
+
+    for fn in _CHECKS:
+        result = fn()
+        if result.passed:
+            console.print(f"  [bold green]✓[/bold green] {result.detail}")
+        else:
+            console.print(f"  [bold red]✗[/bold red] {result.detail}")
+            if result.fix:
+                console.print(f"    [yellow]→[/yellow] {result.fix}")
+            any_failed = True
+
+    if any_failed:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    doctor()

nff/commands/flash.py

@@ -0,0 +1,190 @@
+"""nff flash — compile and upload a sketch to the connected board."""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+
+if __name__ == "__main__":
+    _pkg_parent = str(pathlib.Path(__file__).resolve().parents[2])
+    if _pkg_parent not in sys.path:
+        sys.path.insert(0, _pkg_parent)
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from nff import config as cfg_module
+from nff.tools import toolchain
+
+if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+console = Console(legacy_windows=False)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_target(
+    board: str | None,
+    port: str | None,
+) -> tuple[str, str]:
+    """Return (fqbn, port), filling missing values from config.
+
+    Exits with code 1 if either value cannot be resolved.
+    """
+    try:
+        device = cfg_module.get_default_device()
+    except cfg_module.ConfigError:
+        device = {}
+
+    fqbn = board or device.get("fqbn") or ""
+    resolved_port = port or device.get("port") or ""
+
+    missing = []
+    if not fqbn:
+        missing.append("board FQBN (use --board or run nff init)")
+    if not resolved_port:
+        missing.append("port (use --port or run nff init)")
+
+    if missing:
+        for m in missing:
+            console.print(f"  [bold red]✗[/bold red] Missing {m}")
+        sys.exit(1)
+
+    return fqbn, resolved_port
+
+
+def _resolve_sketch(path: Path) -> Path:
+    """Return the sketch directory that arduino-cli should compile.
+
+    Handles three cases:
+    - A directory that is already a valid sketch folder.
+    - A .ino file already inside a correctly-named parent directory.
+    - A loose .ino file — copied to the default temp sketch directory.
+
+    Note: multi-file sketches passed as a loose .ino will only include
+    that single file. Pass the sketch directory for multi-file projects.
+
+    Exits with code 1 on invalid input.
+    """
+    if path.is_dir():
+        ino_files = list(path.glob("*.ino"))
+        if not ino_files:
+            console.print(
+                f"  [bold red]✗[/bold red] No .ino file found in [bold]{path}[/bold]"
+            )
+            sys.exit(1)
+        return path
+
+    if path.suffix.lower() != ".ino":
+        console.print(
+            f"  [bold red]✗[/bold red] Expected a .ino file or sketch directory, "
+            f"got: [bold]{path.name}[/bold]"
+        )
+        sys.exit(1)
+
+    # If the file already lives in a correctly-named sketch directory, use it in place.
+    if path.parent.name == path.stem:
+        return path.parent
+
+    # Loose .ino — write to the temp sketch directory.
+    console.print(
+        f"  [dim]Copying {path.name} → temp sketch dir "
+        f"(multi-file sketches need a directory)[/dim]"
+    )
+    code = path.read_text(encoding="utf-8")
+    return toolchain.write_sketch(code)
+
+
+def _stream_phase(label: str, stream: toolchain.ProcessStream) -> None:
+    """Print *label*, stream lines, then print pass/fail. Exits 1 on failure."""
+    console.print(f"\n  {label}")
+    for line in stream:
+        if line.strip():
+            console.print(f"    [dim]{line}[/dim]")
+
+    if stream.returncode != 0:
+        phase = label.split()[0].rstrip("…")
+        console.print(
+            f"\n  [bold red]✗[/bold red] {phase} failed "
+            f"(exit {stream.returncode})"
+        )
+        sys.exit(1)
+
+    phase = label.split()[0].rstrip("…")
+    console.print(f"  [bold green]✓[/bold green] {phase} complete")
+
+
+# ---------------------------------------------------------------------------
+# Click command
+# ---------------------------------------------------------------------------
+
+@click.command()
+@click.argument("file", type=click.Path(exists=True, path_type=Path))
+@click.option("--board", default=None, metavar="FQBN",
+              help="Board FQBN, e.g. arduino:avr:uno. Falls back to config.")
+@click.option("--port", default=None, metavar="PORT",
+              help="Serial port, e.g. COM3. Falls back to config.")
+@click.option("--baud", default=None, type=int,
+              help="Baud rate (stored in config, not used by arduino-cli).")
+@click.option("--manual-reset", is_flag=True,
+              help="Pause before upload — use when auto-reset is broken (common on ESP32 clones).")
+def flash(
+    file: Path,
+    board: str | None,
+    port: str | None,
+    baud: int | None,
+    manual_reset: bool,
+) -> None:
+    """Compile and upload FILE to the connected board.
+
+    FILE may be a .ino sketch file or a sketch directory.
+    Board and port default to the values stored by `nff init`.
+
+    If the upload fails with "Wrong boot mode detected", your board's
+    auto-reset is broken. Re-run with --manual-reset and hold the BOOT
+    button when prompted.
+    """
+    fqbn, resolved_port = _resolve_target(board, port)
+    sketch_dir = _resolve_sketch(file)
+
+    console.print(
+        f"  [bold]{sketch_dir.name}[/bold]  →  "
+        f"[bold]{fqbn}[/bold] on [bold]{resolved_port}[/bold]"
+    )
+
+    # --- compile ---
+    try:
+        compile_stream = toolchain.stream_compile(sketch_dir, fqbn)
+    except toolchain.ToolchainError as exc:
+        console.print(f"  [bold red]✗[/bold red] {exc}")
+        sys.exit(2)
+
+    _stream_phase("Compiling…", compile_stream)
+
+    # --- manual-reset gate ---
+    if manual_reset:
+        console.print(
+            "\n  [yellow]Hold the BOOT button on your board, "
+            "then press Enter to start uploading…[/yellow]"
+        )
+        click.pause(info="")
+        console.print()
+
+    # --- upload ---
+    try:
+        upload_stream = toolchain.stream_upload(sketch_dir, fqbn, resolved_port)
+    except toolchain.ToolchainError as exc:
+        console.print(f"  [bold red]✗[/bold red] {exc}")
+        sys.exit(2)
+
+    _stream_phase("Uploading…", upload_stream)
+
+
+if __name__ == "__main__":
+    flash()
+

nff/commands/init.py

@@ -0,0 +1,207 @@
+"""nff init — detect board, write config, register the MCP server."""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+
+if __name__ == "__main__":
+    _pkg_parent = str(pathlib.Path(__file__).resolve().parents[2])
+    if _pkg_parent not in sys.path:
+        sys.path.insert(0, _pkg_parent)
+
+import json
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from nff import config as cfg_module
+from nff.tools import boards as boards_module
+from nff.tools import toolchain
+from nff.tools import installer
+from nff.tools.boards import DetectedDevice
+
+if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+console = Console(legacy_windows=False)
+
+_CLAUDE_DESKTOP_CONFIG = Path.home() / ".claude" / "claude_desktop_config.json"
+_MCP_ENTRY: dict = {"command": "nff", "args": ["mcp"]}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _ensure_arduino_cli() -> None:
+    """Install arduino-cli silently if it is not already on PATH."""
+    if toolchain.find_arduino_cli():
+        return
+    console.print(
+        "  [yellow]⚠[/yellow]  arduino-cli not found — installing automatically…"
+    )
+    try:
+        exe = installer.install(force=False)
+        if installer.verify(exe):
+            console.print("  [bold green]✓[/bold green] arduino-cli installed.")
+        else:
+            console.print(
+                "  [yellow]⚠[/yellow]  arduino-cli installed but could not be verified. "
+                "Restart your terminal if commands fail."
+            )
+    except Exception as exc:
+        console.print(
+            f"  [yellow]⚠[/yellow]  Could not auto-install arduino-cli: {exc}\n"
+            "  Install manually: https://arduino.github.io/arduino-cli"
+        )
+
+
+def _pick_device(devices: list[DetectedDevice]) -> DetectedDevice:
+    """Return the chosen device; prompts when more than one is connected."""
+    if len(devices) == 1:
+        return devices[0]
+
+    console.print("\n[bold]Multiple boards detected:[/bold]")
+    for i, d in enumerate(devices, 1):
+        console.print(f"  {i}. [bold]{d.board}[/bold] on {d.port}")
+
+    choice = click.prompt(
+        "Select board",
+        type=click.IntRange(1, len(devices)),
+        default=1,
+    )
+    return devices[choice - 1]
+
+
+def _update_claude_desktop_config() -> None:
+    """Merge the nff MCP entry into ~/.claude/claude_desktop_config.json.
+
+    Preserves all pre-existing keys and other mcpServers entries.
+
+    Raises:
+        OSError: If the file cannot be written.
+        ValueError: If an existing file contains invalid JSON (caller should
+            surface this as a warning rather than aborting).
+    """
+    _CLAUDE_DESKTOP_CONFIG.parent.mkdir(parents=True, exist_ok=True)
+
+    data: dict = {}
+    if _CLAUDE_DESKTOP_CONFIG.exists():
+        raw = _CLAUDE_DESKTOP_CONFIG.read_text(encoding="utf-8")
+        if raw.strip():
+            data = json.loads(raw)  # raises ValueError on bad JSON
+
+    data.setdefault("mcpServers", {})["nff"] = _MCP_ENTRY
+
+    _CLAUDE_DESKTOP_CONFIG.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Click command
+# ---------------------------------------------------------------------------
+
+@click.command()
+@click.option("--port", default=None, metavar="PORT",
+              help="Serial port to use; skips auto-detection.")
+@click.option("--baud", default=9600, show_default=True,
+              help="Baud rate stored in config.")
+@click.option("--force", is_flag=True,
+              help="Overwrite an existing config without prompting.")
+def init(port: str | None, baud: int, force: bool) -> None:
+    """Detect a connected board, write config, and register the MCP server."""
+    _ensure_arduino_cli()
+
+    # Guard against overwriting an existing, valid config
+    if cfg_module.exists() and not force:
+        try:
+            existing = cfg_module.get_default_device()
+            if existing.get("port"):
+                console.print(
+                    f"[yellow]Config already exists[/yellow] "
+                    f"({existing.get('board', '?')} on {existing['port']}).\n"
+                    "  Pass [bold]--force[/bold] to overwrite."
+                )
+                return
+        except cfg_module.ConfigError:
+            pass  # unreadable config → let the user fix it by re-running init
+
+    # -----------------------------------------------------------------
+    # Device resolution
+    # -----------------------------------------------------------------
+    device: DetectedDevice | None = None
+
+    if port:
+        # User supplied a port — accept it even if the board isn't recognised.
+        console.print(f"  Using specified port [bold]{port}[/bold]…")
+        device = boards_module.find_device(port)
+        if device is None:
+            console.print(
+                f"  [yellow]⚠[/yellow]  {port} not matched to a known board. "
+                "Storing as 'Unknown'."
+            )
+            cfg_module.set_default_device(port=port, board="Unknown", fqbn="", baud=baud)
+            _write_success(port=port, board="Unknown", device=None)
+            return
+    else:
+        console.print("  Scanning USB ports…")
+        devices = boards_module.list_devices()
+
+        if not devices:
+            console.print(
+                "[bold red]✗[/bold red] No recognised boards found.\n"
+                "  Plug in a board and try again, or use "
+                "[bold]--port PORT[/bold] to specify one manually."
+            )
+            sys.exit(1)
+
+        device = _pick_device(devices)
+
+    # -----------------------------------------------------------------
+    # Write nff config
+    # -----------------------------------------------------------------
+    cfg_module.set_default_device(
+        port=device.port,
+        board=device.board,
+        fqbn=device.fqbn,
+        baud=baud,
+    )
+
+    _write_success(port=device.port, board=device.board, device=device)
+
+
+def _write_success(port: str, board: str, device: DetectedDevice | None) -> None:
+    """Print the success lines and update the Claude Desktop config."""
+    if device:
+        console.print(
+            f"  [bold green]✓[/bold green] Found: [bold]{device.board}[/bold] "
+            f"on {device.port} "
+            f"(vendor: {device.vendor_id}, product: {device.product_id})"
+        )
+
+    console.print(
+        f"  [bold green]✓[/bold green] Config written to "
+        f"[bold]{cfg_module.CONFIG_PATH}[/bold]"
+    )
+
+    try:
+        _update_claude_desktop_config()
+        console.print(
+            f"  [bold green]✓[/bold green] MCP config written to "
+            f"[bold]{_CLAUDE_DESKTOP_CONFIG}[/bold]"
+        )
+    except ValueError as exc:
+        console.print(
+            f"  [yellow]⚠[/yellow]  Claude Desktop config has invalid JSON — "
+            f"fix it manually: {exc}\n"
+            f"  Path: {_CLAUDE_DESKTOP_CONFIG}"
+        )
+    except OSError as exc:
+        console.print(
+            f"  [yellow]⚠[/yellow]  Could not write Claude Desktop config: {exc}"
+        )
+
+
+if __name__ == "__main__":
+    init()