first commit

.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright 2025 Tim Pietrusky
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

docs/conventions.md

@@ -0,0 +1,143 @@
+# LeRobot.js Conventions
+
+## Project Overview
+
+**lerobot.js** is a TypeScript/JavaScript implementation of Hugging Face's [lerobot](https://github.com/huggingface/lerobot) robotics library. Our goal is to bring state-of-the-art AI for real-world robotics directly to the JavaScript ecosystem, enabling robot control without any Python dependencies.
+
+### Vision Statement
+
+> Lower the barrier to entry for robotics by making cutting-edge robotic AI accessible through JavaScript, the world's most widely used programming language.
+
+## Project Goals
+
+### Primary Objectives
+
+1. **Native JavaScript/TypeScript Implementation**: Complete robotics stack running purely in JS/TS
+2. **Feature Parity**: Implement core functionality from the original Python lerobot
+3. **Web-First Design**: Enable robotics applications to run in browsers, Edge devices, and Node.js
+4. **Real-World Robot Control**: Direct hardware interface without Python bridge
+5. **Hugging Face Integration**: Seamless model and dataset loading from HF Hub
+
+### Core Features to Implement
+
+- **Pretrained Models**: Load and run robotics policies (ACT, Diffusion, TDMPC, VQ-BeT)
+- **Dataset Management**: LeRobotDataset format with HF Hub integration
+- **Simulation Environments**: Browser-based robotics simulations
+- **Real Robot Support**: Hardware interfaces for motors, cameras, sensors
+- **Training Infrastructure**: Policy training and evaluation tools
+- **Visualization Tools**: Dataset and robot state visualization
+
+## Technical Foundation
+
+### Core Stack
+
+- **Runtime**: Node.js 18+ / Modern Browsers
+- **Language**: TypeScript with strict type checking
+- **Build Tool**: Vite (development and production builds)
+- **Package Manager**: pnpm
+- **Module System**: ES Modules
+- **Target**: ES2020
+
+## Architecture Principles
+
+### 1. Python lerobot Faithfulness (Primary Principle)
+
+**lerobot.js must maintain UX/API compatibility with Python lerobot**
+
+- **Identical Commands**: `npx lerobot find-port` matches `python -m lerobot.find_port`
+- **Same Terminology**: Use "MotorsBus", not "robot arms" - keep Python's exact wording
+- **Matching Output**: Error messages, prompts, and flow identical to Python version
+- **Familiar Workflows**: Python lerobot users should feel immediately at home
+- **No "Improvements"**: Resist urge to add features/UX that Python version doesn't have
+
+> **Why?** Users are already trained on Python lerobot. Our goal is seamless migration to TypeScript, not learning a new tool.
+
+### 2. Modular Design
+
+```
+lerobot/
+├── common/
+│   ├── datasets/     # Dataset loading and management
+│   ├── envs/         # Simulation environments
+│   ├── policies/     # AI policies and models
+│   ├── devices/      # Hardware device interfaces
+│   └── utils/        # Shared utilities
+├── core/             # Core robotics primitives
+├── web/              # Browser-specific implementations
+└── node/             # Node.js-specific implementations
+```
+
+### 3. Platform Abstraction
+
+- **Universal Core**: Platform-agnostic robotics logic
+- **Web Adapters**: Browser-specific implementations (WebGL, WebAssembly, WebUSB)
+- **Node Adapters**: Node.js implementations (native modules, serial ports)
+
+### 4. Progressive Enhancement
+
+- **Core Functionality**: Works everywhere (basic policy inference)
+- **Enhanced Features**: Leverage platform capabilities (GPU acceleration, hardware access)
+- **Premium Features**: Advanced capabilities (real-time training, complex simulations)
+
+## Development Standards
+
+### Code Style
+
+- **Formatting**: Prettier with default settings
+- **Linting**: ESLint with TypeScript recommended rules
+- **Naming**:
+  - camelCase for variables/functions
+  - PascalCase for classes/types
+  - snake_case for file names (following lerobot convention)
+- **File Structure**: Feature-based organization with index.ts barrels
+
+### TypeScript Standards
+
+- **Strict Mode**: All strict compiler options enabled
+- **Type Safety**: Prefer types over interfaces for data structures
+- **Generics**: Use generics for reusable components
+- **Error Handling**: Use Result<T, E> pattern for recoverable errors
+
+### Implementation Philosophy
+
+- **Python First**: When in doubt, check how Python lerobot does it
+- **Port, Don't Innovate**: Direct ports are better than clever improvements
+- **User Expectations**: Maintain the exact experience Python users expect
+- **Terminology Consistency**: Use Python lerobot's exact naming and messaging
+
+### Development Process
+
+- **Python Reference**: Always check Python lerobot implementation first
+- **UX Matching**: Test that commands, outputs, and workflows match exactly
+- **User Story Validation**: Validate against real Python lerobot users
+
+### Testing Strategy
+
+- **Unit Tests**: Vitest for individual functions and classes
+- **Integration Tests**: Test component interactions
+- **E2E Tests**: Playwright for full workflow testing
+- **Hardware Tests**: Mock/stub hardware interfaces for CI
+- **UX Compatibility Tests**: Verify outputs match Python version
+
+## Package Structure
+
+### NPM Package Name
+
+- **Public Package**: `lerobot` (on npm)
+- **Development Name**: `lerobot.js` (GitHub repository)
+
+## Dependencies Strategy
+
+### Core Dependencies
+
+- **ML Inference**: ONNX.js for model execution (browser + Node.js)
+- **Tensor Operations**: Custom lightweight tensor lib for data manipulation
+- **Math**: Custom math utilities for robotics
+- **Networking**: Fetch API (universal)
+- **File I/O**: Platform-appropriate abstractions
+
+### Optional Enhanced Dependencies
+
+- **3D Graphics**: Three.js for simulation and visualization
+- **Hardware**: Platform-specific libraries for device access
+- **Development**: Vitest, ESLint, Prettier

docs/getting_started_with_so100.md

@@ -0,0 +1,219 @@
+## install lerobot
+
+- clone the repo: git clone https://github.com/huggingface/lerobot.git
+- go into the dir: cd lerobot
+- setup venv with your favorite tool, i use uv: uv venv --python 3.10
+- activate venv: windows: .venv\Scripts\activate
+- install dependencies: uv pip install -e ".[feetech]"
+  (we install feetech here as that is needed to talk with the motors that the so100 is using)
+
+## identify USB ports
+
+- connect usb / power
+- run `python lerobot/find_port.py`
+
+```
+python lerobot/find_port.py
+Finding all available ports for the MotorsBus.
+Ports before disconnecting: ['COM3', 'COM4']
+Remove the USB cable from your MotorsBus and press Enter when done.
+
+The port of this MotorsBus is 'COM3'
+Reconnect the USB cable.
+```
+
+- the port it will show you is the one from the disconnected arm
+- in my case on windows the follower arm is COM4 and the leader arm is COM3 (but this could change, as the port mappings on windows are not fixed)
+
+## check motor ids
+
+**Important: Always do this first!** This checks if your robot motors are already configured correctly. If they are, you can skip the tedious setup process entirely.
+
+**What are motor IDs?** Each motor needs a unique ID number (1, 2, 3, 4, 5, 6) so the computer can talk to them individually. Brand new motors usually all have the same default ID (1), which doesn't work.
+
+### check follower arm
+
+```
+python -m lerobot.check_motors --robot.port=COM4
+```
+
+### check leader arm
+
+```
+python -m lerobot.check_motors --teleop.port=COM3
+```
+
+**If you see this - you're lucky! Skip to calibration:**
+
+```
+🎉 PERFECT! This arm is correctly configured:
+   ✅ All 6 motors found: [1, 2, 3, 4, 5, 6]
+   ✅ Correct baudrate: 1000000
+
+✅ This arm is ready for calibration!
+```
+
+**If you see this - continue to "setup motors" below:**
+
+```
+⚠️  This arm needs motor ID setup:
+   Expected IDs: [1, 2, 3, 4, 5, 6]
+   Found IDs: [1, 1, 1, 1, 1, 1]
+   Duplicate IDs: [1] (likely all motors have ID=1)
+```
+
+## setup motors
+
+**⚠️ Only do this section if the motor check above showed your motors need setup!**
+
+This is a one-time process where you connect each motor individually to assign unique ID numbers. It's tedious but only needed once - the ID gets permanently stored in each motor's memory.
+
+**Why is this needed?** Motors come from the factory with the same default ID (usually 1). The computer can't tell them apart, so we need to give each motor a unique number.
+
+**⚠️ Important safety notes:**
+
+- Always power down (unplug power + USB) when connecting/disconnecting motors
+- Connect only ONE motor at a time during this process
+- The motor gears should be removed from the leader arm before this step
+
+### follower arm
+
+```
+python -m lerobot.setup_motors --robot.type=so100_follower --robot.port=COM4
+```
+
+The script will guide you through connecting each motor one by one. Follow the prompts carefully.
+
+### leader arm
+
+```
+python -m lerobot.setup_motors --teleop.type=so100_leader --teleop.port=COM3
+```
+
+Same process as the follower arm.
+
+**After setup:** Run the motor check commands again to verify everything worked correctly. You should now see the "PERFECT!" message.
+
+## calibrate
+
+**What is calibration?** This teaches both robot arms to have the same understanding of joint positions. When both arms are in the same physical pose, they should report the same position values. This is crucial for the leader arm to properly control the follower arm.
+
+**Why is this needed?** Even though the arms are identical, small manufacturing differences mean their position sensors might read slightly different values for the same physical position. Calibration fixes this.
+
+**Important:** Make sure both arms have all motors properly connected (daisy-chained) before calibrating. The motor setup process has you disconnect motors individually, but for calibration you need the full arm assembled.
+
+> **💡 Don't be intimidated by calibration!**
+>
+> **It's really simple:** You just manually move each joint to the correct position - no special technique required! The calibration process is just:
+>
+> 1. Start from the neutral position (standard in robotics)
+> 2. Manually move each motor/joint to where it needs to be
+> 3. Move them one at a time at whatever pace feels comfortable
+> 4. The robot learns from the positions you set
+>
+> **That's it!** You're just physically positioning the joints - the software handles all the complex stuff automatically.
+
+### calibrate follower arm
+
+**Step 1:** Start the calibration script:
+
+```
+python -m lerobot.calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm
+```
+
+**Step 2:** Follow the script's prompts:
+
+1. The script will ask you to **move the arm to the middle position**. This should be a **neutral pose** where:
+
+   - **Shoulder pan (base, joint 1):** 0° - Point the arm straight forward along the +X axis (not twisted left or right)
+   - **Shoulder lift (joint 2):** ~45° - Lift the upper arm segment upward at roughly 45 degrees from horizontal
+   - **Elbow (joint 3):** ~90° - Bend the elbow to form an "L" shape, with the forearm perpendicular to the upper arm
+   - **Wrist flex (joint 4):** 0° - Keep the wrist straight, aligned with the forearm
+   - **Wrist roll (joint 5):** 0° - Keep the gripper pointing straight (not twisted around the forearm axis)
+   - **Gripper (joint 6):** Fully closed position (mechanical hard stop)
+
+   **Technical reference:** This is similar to a "home position" or "zero configuration" used in robot calibration - a repeatable, neutral pose that avoids joint limits and singularities. The arm should form clear geometric references (forward direction, L-shaped elbow) that are easy to reproduce.
+
+   **💡 Tip:** Once you get the arm in the correct position, consider taking a photo for future reference!
+
+2. The script will ask you to **move joints through their full range** - gently move each joint from its furthest position in one direction to its furthest position in the other direction (the joint will stop when it hits its physical limit). Do this for all joints while the script records, then press Enter when done
+3. The script will **save the calibration automatically**
+
+### calibrate leader arm
+
+**Step 1:** Start the calibration script:
+
+```
+python -m lerobot.calibrate --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm
+```
+
+**Step 2:** Follow the script's prompts:
+
+1. The script will ask you to **move the arm to the middle position**. This should be a **neutral pose** where:
+
+   - **Shoulder pan (base, joint 1):** 0° - Point the arm straight forward along the +X axis (not twisted left or right)
+   - **Shoulder lift (joint 2):** ~45° - Lift the upper arm segment upward at roughly 45 degrees from horizontal
+   - **Elbow (joint 3):** ~90° - Bend the elbow to form an "L" shape, with the forearm perpendicular to the upper arm
+   - **Wrist flex (joint 4):** 0° - Keep the wrist straight, aligned with the forearm
+   - **Wrist roll (joint 5):** 0° - Keep the gripper pointing straight (not twisted around the forearm axis)
+   - **Gripper (joint 6):** Fully closed position (mechanical hard stop)
+
+   **Technical reference:** This is similar to a "home position" or "zero configuration" used in robot calibration - a repeatable, neutral pose that avoids joint limits and singularities.
+
+2. The script will ask you to **move joints through their full range** - gently move each joint from its furthest position in one direction to its furthest position in the other direction (the joint will stop when it hits its physical limit). Do this for all joints while the script records, then press Enter when done
+3. The script will **save the calibration automatically**
+
+**✅ After both arms are calibrated, you're ready for teleoperation!**
+
+## test teleoperation
+
+Now test that your leader arm can control the follower arm:
+
+```bash
+python -m lerobot.teleoperate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm
+```
+
+**What should happen:**
+
+- Both arms should connect automatically
+- When you move the leader arm (manually), the follower arm should copy the movements
+- Press `Ctrl+C` to stop teleoperation
+
+**If something goes wrong:**
+
+- Check your COM ports are correct
+- Make sure both arms are powered on
+- Verify the cables are properly connected
+
+## record demonstrations (optional)
+
+Once teleoperation works, you can record demonstrations for training a robot learning policy.
+
+**For example, to record 10 episodes of a simple task:**
+
+```bash
+python -m lerobot.record --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm --dataset-name=my_first_dataset --num-episodes=10 --task="Pick up the red block and place it in the box"
+```
+
+**What this does:**
+
+- Records your demonstrations using teleoperation
+- Saves data to train a neural network later
+- Each "episode" is one complete demonstration of the task
+
+## next steps
+
+✅ **You now have working SO-100 robot arms!**
+
+**To continue with robot learning:**
+
+- Follow the [Getting Started with Real-World Robots](https://huggingface.co/docs/lerobot/getting_started_real_world_robot) tutorial
+- Learn how to train policies and run them autonomously
+- Join the [Discord community](https://discord.com/invite/s3KuuzsPFb) for help and discussions
+
+**Common next steps:**
+
+1. **Add cameras** for vision-based tasks
+2. **Record more complex demonstrations**
+3. **Train neural network policies**
+4. **Run policies autonomously**

docs/planning/001_find_usb_ports.md

@@ -0,0 +1,124 @@
+# User Story 001: Find USB Ports
+
+## Story
+
+**As a** robotics developer setting up SO-100 robot arms  
+**I want** to identify which USB ports my robot arms are connected to  
+**So that** I can configure my robot arms without manually testing each port
+
+## Background
+
+When setting up SO-100 robot arms (or any robotics hardware), users need to identify which USB/serial ports correspond to their robot controllers. The Python lerobot provides a `find_port.py` script that:
+
+1. Lists all available serial ports
+2. Asks the user to disconnect a specific device
+3. Detects which port disappeared
+4. Identifies that port as belonging to the disconnected device
+
+We need to replicate this functionality in Node.js for lerobot.js.
+
+## Acceptance Criteria
+
+### Core Functionality
+
+- [ ] **Port Discovery**: List all available serial/USB ports on the system
+- [ ] **Interactive Detection**: Guide user through disconnect/reconnect process
+- [ ] **Port Identification**: Detect which port corresponds to which robot arm
+- [ ] **Cross-Platform**: Work on Windows, macOS, and Linux
+- [ ] **CLI Interface**: Provide `npx lerobot find-port` command identical to Python version
+
+### User Experience
+
+- [ ] **Clear Instructions**: Provide step-by-step guidance to user
+- [ ] **Error Handling**: Handle cases where no ports are found or detection fails
+- [ ] **Progress Feedback**: Show current status during detection process
+- [ ] **Results Display**: Clearly show which port belongs to which device
+
+### Technical Requirements
+
+- [ ] **Node.js Native**: Use Node.js serial port libraries (no Python dependencies)
+- [ ] **TypeScript**: Fully typed implementation following our conventions
+- [ ] **CLI Tool**: Executable via `npx lerobot find-port` (matching Python version)
+- [ ] **snake_case**: File naming follows lerobot conventions
+
+## Expected User Flow
+
+```bash
+$ npx lerobot find-port
+
+Finding all available ports for the MotorsBus.
+Ports before disconnecting: ['COM3', 'COM4']
+Remove the USB cable from your MotorsBus and press Enter when done.
+
+The port of this MotorsBus is 'COM3'
+Reconnect the USB cable.
+```
+
+**For multiple arms, run separately:**
+
+```bash
+# First arm
+$ npx lerobot find-port
+# Follow prompts...
+
+# Second arm
+$ npx lerobot find-port
+# Follow prompts...
+```
+
+## Implementation Details
+
+### File Structure
+
+```
+src/lerobot/
+└── find_port.ts                   # Direct port of Python script
+
+src/cli/
+└── index.ts                       # Main CLI entry point with find-port command
+```
+
+### Key Dependencies
+
+- **serialport**: For cross-platform serial port detection and management
+- **readline**: Node.js built-in for simple input() equivalent
+
+### Core Functions to Implement
+
+```typescript
+// find_port.ts (matching Python naming)
+async function findAvailablePorts(): Promise<string[]>;
+async function findPort(): Promise<void>; // Main interactive function
+```
+
+### Technical Considerations
+
+#### Cross-Platform Serial Ports
+
+- **Windows**: COM ports (COM1, COM2, etc.)
+- **macOS**: /dev/cu._ or /dev/tty._
+- **Linux**: /dev/ttyUSB*, /dev/ttyACM*
+
+#### Error Scenarios to Handle
+
+- No serial ports detected
+- Multiple ports disconnected simultaneously
+- Port permissions issues
+- User cancels detection process
+- Same port reconnected to different device
+
+#### Performance & UX
+
+- Fast port scanning (< 1 second)
+- Clear progress indicators
+- Timeout handling for user input
+- Graceful interrupt handling (Ctrl+C)
+
+## Definition of Done
+
+- [ ] **Functional**: Successfully identifies robot arm ports on Windows/macOS/Linux
+- [ ] **Tested**: Unit tests for core logic, integration tests with mock serial ports
+- [ ] **Documented**: README section explaining usage
+- [ ] **CLI Ready**: Installable and runnable as CLI tool
+- [ ] **Type Safe**: Full TypeScript coverage with strict mode
+- [ ] **Follows Conventions**: snake_case files, proper architecture

index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + TS</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package.json

@@ -0,0 +1,48 @@
+{
+  "name": "lerobot",
+  "version": "0.0.0",
+  "description": "State-of-the-art AI for real-world robotics in JS",
+  "type": "module",
+  "bin": {
+    "lerobot": "./dist/cli/index.js"
+  },
+  "main": "./dist/lerobot/find_port.js",
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "keywords": [
+    "robotics",
+    "ai",
+    "machine-learning",
+    "typescript",
+    "lerobot"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "pnpm run build:cli",
+    "build:cli": "tsc --project tsconfig.cli.json",
+    "build:web": "tsc && vite build",
+    "preview": "vite preview",
+    "cli:find-port": "tsx src/cli/index.ts find-port",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "serialport": "^12.0.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.3",
+    "vite": "^6.3.5",
+    "tsx": "^4.19.2",
+    "@types/node": "^22.10.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/timpietrusky/lerobot.js"
+  },
+  "license": "Apache-2.0",
+  "author": "Tim Pietrusky",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

pnpm-lock.yaml

@@ -0,0 +1,813 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      serialport:
+        specifier: ^12.0.0
+        version: 12.0.0
+    devDependencies:
+      '@types/node':
+        specifier: ^22.10.5
+        version: 22.15.31
+      tsx:
+        specifier: ^4.19.2
+        version: 4.20.3
+      typescript:
+        specifier: ~5.8.3
+        version: 5.8.3
+      vite:
+        specifier: ^6.3.5
+        version: 6.3.5(@types/[email protected])([email protected])
+
+packages:
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-9o3TMmpmftaCMepOdA5k/yDw8SfInyzWWTjYTFCX3kPSDJMROQTb8jg+h9Cnwnmm1vOzvxN7gIfB5V2ewpjtGA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-VGzGhj4lJO+TVGV1v8ntCZWJktV7SGCs3Pn1GRWI1SBFtRALoomm8k5E9Pmwg3HOAal2VDc2F9+PM/rEY6oIDg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-AdJKSPeEHgi7/ZhuIPtcQKr5RQdo6OO2IL87JkianiMYMPbCtot9fxPbrMiBADOWWm3T2si9stAiVsGbTQFkbA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-D2GyJT1kjvO//drbRT3Hib9XPwQeWd9vZoBJn+bu/lVsOZ13cqNdDeqIF/xQ5/VmWvMduP6AmXvylO/PIc2isw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-GtaBgammVvdF7aPIgH2jxMDdivezgFu6iKpmT+48+F8Hhg5J/sfnDieg0aeG/jfSvkYQU2/pceFPDKlqZzwnfQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-1iT4FVL0dJ76/q1wd7XDsXrSW+oLoquptvh4CLR4kITDtqi2e/xwXwdCVH8hVHU43wgJdsq7Gxuzcs6Iq/7bxQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-nk4tGP3JThz4La38Uy/gzyXtpkPW8zSAmoUhK9xKKXdBCzKODMc2adkB2+8om9BDYugz+uGV7sLmpTYzvmz6Sw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-PrikaNjiXdR2laW6OIjlbeuCPrPaAl0IwPIaRv+SMV8CiM8i2LqVUHFC1+8eORgWyY7yhQY+2U2fA55mBzReaw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-Z9kfb1v6ZlGbWj8EJk9T6czVEjjq2ntSYLY2cw6pAZl4oKtfgQuS4HOq41M/BcoLPzrUbNd+R4BXFyH//nHxVg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-cPzojwW2okgh7ZlRpcBEtsX7WBuqbLrNXqLU89GxWbNt6uIg78ET82qifUy3W6OVww6ZWobWub5oqZOVtwolfw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-sQ7l00M8bSv36GLV95BVAdhJ2QsIbCuCjh/uYrWiMQSUuV+LpXwIqhgJDcvMTj+VsQmqAHL2yYaasENvJ7CDKA==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-0ur7ae16hDUC4OL5iEnDb0tZHDxYmuQyhKhsPBV8f99f6Z9KQM02g33f93rNH5A30agMS46u2HP6qTdEt6Q1kg==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-kB/66P1OsHO5zLz0i6X0RxlQ+3cu0mkxS3TKFvkb5lin6uwZ/ttOkP3Z8lfR9mJOBk14ZwZ9182SIIWFGNmqmg==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-UZCmJ7r9X2fe2D6jBmkLBMQetXPXIsZjQJCjgwpVDz+YMcS6oFR27alkgGv3Oqkv07bxdvw7fyB71/olceJhkQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-kTxwu4mLyeOlsVIFPfQo+fQJAV9mh24xL+y+Bm6ej067sYANjyEw1dNHmvoqxJUCMnkBdKpvOn0Ahql6+4VyeA==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-K2dSKTKfmdh78uJ3NcWFiqyRrimfdinS5ErLSn3vluHNeHVnBAFWC8a4X5N+7FgVE1EjXS1QDZbpqZBjfrqMTQ==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-uhj8N2obKTE6pSZ+aMUbqq+1nXxNjZIIjCjGLfsWvVpy7gKCOL6rsY1MhRh9zLtUtAI7vpgLMK6DxjO8Qm9lJw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-pwHtMP9viAy1oHPvgxtOv+OkduK5ugofNTVDilIzBLpoWAM16r7b/mxBvfpuQDpRQFMfuVr5aLcn4yveGvBZvw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-WOb5fKrvVTRMfWFNCroYWWklbnXH0Q5rZppjq0vQIdlsQKuw6mdSihwSo4RV/YdQ5UCKKvBy7/0ZZYLBZKIbwQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-7A208+uQKgTxHd0G0uqZO8UjK2R0DDb4fDmERtARjSHWxqMTye4Erz4zZafx7Di9Cv+lNHYuncAkiGFySoD+Mw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-G4hE405ErTWraiZ8UiSoesH8DaCsMm0Cay4fsFWOOUcz8b8rC6uCvnagr+gnioEjWn0wC+o1/TAHt+It+MpIMg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-l+azKShMy7FxzY0Rj4RCt5VD/q8mG/e+mDivgspo+yL8zW7qEwctQ6YqKX34DTEleFAvCIUviCFX1SDZRSyMQA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-O2S7SNZzdcFG7eFKgvwUEZ2VG9D/sn/eIiz8XRZ1Q/DO5a3s76Xv0mdBzVM5j5R639lXQmPmSo0iRpHqUUrsxw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-onOJ02pqs9h1iMJ1PQphR+VZv8qBMQ77Klcsqv9CNW2w6yLqoURLcgERAIurY6QE63bbLuqgP9ATqajFLK5AMQ==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/[email protected]':
+    resolution: {integrity: sha512-TXv6YnJ8ZMVdX+SXWVBo/0p8LTcrUYngpWjvm91TMjjBQii7Oz11Lw5lbDV5Y0TzuhSJHwiH4hEtC1I42mMS0g==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-Krjy9awJl6rKbruhQDgivNbD1WuLb8xAclM4IR4cN5pHGAs2oIMMQJEiC3IC/9TZJ+QZkmZhlMO/6MBGxPidpw==}
+    cpu: [arm]
+    os: [android]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-ss4YJwRt5I63454Rpj+mXCXicakdFmKnUNxr1dLK+5rv5FJgAxnN7s31a5VchRYxCFWdmnDWKd0wbAdTr0J5EA==}
+    cpu: [arm64]
+    os: [android]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-eKoL8ykZ7zz8MjgBenEF2OoTNFAPFz1/lyJ5UmmFSz5jW+7XbH1+MAgCVHy72aG59rbuQLcJeiMrP8qP5d/N0A==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-SYwXJgaBYW33Wi/q4ubN+ldWC4DzQY62S4Ll2dgfr/dbPoF50dlQwEaEHSKrQdSjC6oIe1WgzosoaNoHCdNuMg==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-SV+U5sSo0yujrjzBF7/YidieK2iF6E7MdF6EbYxNz94lA+R0wKl3SiixGyG/9Klab6uNBIqsN7j4Y/Fya7wAjQ==}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-J7uCsiV13L/VOeHJBo5SjasKiGxJ0g+nQTrBkAsmQBIdil3KhPnSE9GnRon4ejX1XDdsmK/l30IYLiAaQEO0Cg==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-gTJ/JnnjCMc15uwB10TTATBEhK9meBIY+gXP4s0sHD1zHOaIh4Dmy1X9wup18IiY9tTNk5gJc4yx9ctj/fjrIw==}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-ZJ3gZynL1LDSIvRfz0qXtTNs56n5DI2Mq+WACWZ7yGHFUEirHBRt7fyIk0NsCKhmRhn7WAcjgSkSVVxKlPNFFw==}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-8FnkipasmOOSSlfucGYEu58U8cxEdhziKjPD2FIa0ONVMxvl/hmONtX/7y4vGjdUhjcTHlKlDhw3H9t98fPvyA==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-KPPyAdlcIZ6S9C3S2cndXDkV0Bb1OSMsX0Eelr2Bay4EsF9yi9u9uzc9RniK3mcUGCLhWY9oLr6er80P5DE6XA==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-HPGDIH0/ZzAZjvtlXj6g+KDQ9ZMHfSP553za7o2Odegb/BEfwJcR0Sw0RLNpQ9nC6Gy8s+3mSS9xjZ0n3rhcYg==}
+    cpu: [loong64]
+    os: [linux]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-gEmwbOws4U4GLAJDhhtSPWPXUzDfMRedT3hFMyRAvM9Mrnj+dJIFIeL7otsv2WF3D7GrV0GIewW0y28dOYWkmw==}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-XXKvo2e+wFtXZF/9xoWohHg+MuRnvO29TI5Hqe9xwN5uN8NKUYy7tXUG3EZAlfchufNCTHNGjEx7uN78KsBo0g==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-ruf3hPWhjw6uDFsOAzmbNIvlXFXlBQ4nk57Sec8E8rUxs/AI4HD6xmiiasOOx/3QxS2f5eQMKTAwk7KHwpzr/Q==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-QmNIAqDiEMEvFV15rsSnjoSmO0+eJLoKRD9EAa9rrYNwO/XRCtOGM3A5A0X+wmG+XRrw9Fxdsw+LnyYiZWWcVw==}
+    cpu: [s390x]
+    os: [linux]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-jAHr/S0iiBtFyzjhOkAics/2SrXE092qyqEg96e90L3t9Op8OTzS6+IX0Fy5wCt2+KqeHAkti+eitV0wvblEoQ==}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-3yATWgdeXyuHtBhrLt98w+5fKurdqvs8B53LaoKD7P7H7FKOONLsBVMNl9ghPQZQuYcceV5CDyPfyfGpMWD9mQ==}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-wVzXp2qDSCOpcBCT5WRWLmpJRIzv23valvcTwMHEobkjippNf+C3ys/+wf07poPkeNix0paTNemB2XrHr2TnGw==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-fYCTEyzf8d+7diCw8b+asvWDCLMjsCEA8alvtAutqJOJp/wL5hs1rWSqJ1vkjgW0L2NB4bsYJrpKkiIPRR9dvw==}
+    cpu: [ia32]
+    os: [win32]
+
+  '@rollup/[email protected]':
+    resolution: {integrity: sha512-SnGhLiE5rlK0ofq8kzuDkM0g7FN1s5VYY+YSMTibP7CqShxCQvqtNxTARS4xX4PFJfHjG0ZQYX9iGzI3FQh5Aw==}
+    cpu: [x64]
+    os: [win32]
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-HAFzGhk9OuFMpuor7aT5G1ChPgn5qSsklTFOTUX72Rl6p0xwcSVsRtG/xaGp6bxpN7fI9D/S8THLBWbBgS6ldw==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-r2XOwY2dDvbW7dKqSPIk2gzsr6M6Qpe9+/Ngs94fNaNlcTRCV02PfaoDmRgcubpNVVcLATlxSxPTIDw12dbKOg==}
+    engines: {node: '>=16.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-CJaUd5bLvtM9c5dmO9rPBHPXTa9R2UwpkJ0wdh9JCYcbrPWsKz+ErvR0hBLeo7NPeiFdjFO4sonRljiw4d2XiA==}
+    engines: {node: ^12.22 || ^14.13 || >=16}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-0ei0txFAj+s6FTiCJFBJ1T2hpKkX8Md0Pu6dqMrYoirjPskDLJRgZGLqoy3/lnU1bkvHpnJO+9oJ3PB9v8rNlg==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-0PfLzO9t2X5ufKuBO34DQKLXrCCqS9xz2D0pfuaLNeTkyGUBv426zxoMf3rsMRodDOZNbFblu3Ae84MOQXjnZw==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-aZLJhlRTjSmEwllLG7S4J8s8ctRAS0cbvCpO87smLvl3e4BgzbVgF6Z6zaJd3Aji2uSiYgfedCdNc4L6W+1E2g==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-gu26tVt5lQoybhorLTPsH2j2LnX3AOP2x/34+DUSTNaUTzu2fBXw+isVjQJpUBFWu6aeQRZw5bJol5X9Gxjblw==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-GnCh8K0NAESfhCuXAt+FfBRz1Cf9CzIgXfp7SdMgXwrtuUnCC/yuRTUFWRvuzhYKoAo1TL0hhUo77SFHUH1T/w==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-p1hiCRqvGHHLCN/8ZiPUY/G0zrxd7gtZs251n+cfNTn+87rwcdUeu9Dps3Aadx30/sOGGFL6brIRGK4l/t7MuQ==}
+    engines: {node: '>=8.6.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-rRAivhRkT3YO28WjmmG4FQX6L+KMb5/ikhyylRfzWPw0nSXy97+u07peS9CbHqaNvJkMhH1locp2H36aGMOEIA==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-O7cywCWC8PiOMvo/gglEBfAkLjp/SENEML46BXDykfKP5mTPM46XMaX1L0waWU6DXJpBgjaL7+yX6VriVPbN4w==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-ygDwj3O4SDpZlbrRUraoXIoIqb8sM7aMKryGjYTIF0JRnKeB1ys8+wIp0RFMdFbO62YriUDextHB5Um5cKFSWg==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-dCAVh4P/pZrLcPv9NJ2mvPRBg64L5jXuiRxIlyxxdZGH4WubwXVXY/kBTihQmiAMPxbT3yshSX8f2+feqWsxqA==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-0APxDGR9YvJXTRfY+uRGhzOhTpU5akSH183RUcwzN7QXh8/1jwFsFLCu0grmAUfi+fItCkR+Xr1TcNJLR13VNA==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-dozONxhPC/78pntuxpz/NOtVps8qIc/UZzdc/LuPvVsqCoJXiRxOg6ZtCP/W58iibJDKPZPAWPGYeZt9DJxI+Q==}
+    engines: {node: '>=12.0.0'}
+
+  '@serialport/[email protected]':
+    resolution: {integrity: sha512-9On64rhzuqKdOQyiYLYv2lQOh3TZU/D3+IWCR5gk0alPel2nwpp4YwDEGiUBfrQZEdQ6xww0PWkzqth4wqwX3Q==}
+    engines: {node: '>=12.0.0'}
+
+  '@types/[email protected]':
+    resolution: {integrity: sha512-w28IoSUCJpidD/TGviZwwMJckNESJZXFu7NBZ5YJ4mEUnNraUn9Pm8HSZm/jDF1pDWYKspWE7oVphigUPRakIQ==}
+
+  '@types/[email protected]':
+    resolution: {integrity: sha512-jnVe5ULKl6tijxUhvQeNbQG/84fHfg+yMak02cT8QVhBx/F05rAVxCGBYYTh2EKz22D6JF5ktXuNwdx7b9iEGw==}
+
+  [email protected]:
+    resolution: {integrity: sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  [email protected]:
+    resolution: {integrity: sha512-P8OtKZRv/5J5hhz0cUAdu/cLuPIKXpQl1R9pZtvmHWQvrAUVd0UNIPT4IB4W3rNOqVO0rlqHmCIbSwxh/c9yUQ==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  [email protected]:
+    resolution: {integrity: sha512-hiFoqpyZcfNm1yc4u8oWCf9A2c4D3QjCrks3zmoVKVxpQRzmPNar1hUJcBG2RQHvEVGDN+Jm81ZheVLAQMK6+w==}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  [email protected]:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  [email protected]:
+    resolution: {integrity: sha512-auHyJ4AgMz7vgS8Hp3N6HXSmlMdUyhSUrfBF16w153rxtLIEOE+HGqaBppczZvnHLqQJfiHotCYpNhl0lUROFQ==}
+
+  [email protected]:
+    resolution: {integrity: sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==}
+
+  [email protected]:
+    resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  [email protected]:
+    resolution: {integrity: sha512-vgbBJTS4m5/KkE16t5Ly0WW9hz46swAstv0hYYwMtbG7AznRhNyfLRe8HZAiWIpcHzoO7HxhLuBQj9rJ/Ho0ZA==}
+
+  [email protected]:
+    resolution: {integrity: sha512-NTZVKn9IylLwUzaKjkas1e4u2DLNcV4rdYagA4PWdPwW87Bi7z+BznyKSRwS/761tV/lzCGXplWsiaMjLqP2zQ==}
+    hasBin: true
+
+  [email protected]:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  [email protected]:
+    resolution: {integrity: sha512-M7BAV6Rlcy5u+m6oPhAPFgJTzAioX/6B0DxyvDlo9l8+T3nLKbrczg2WLUyzd45L8RqfUMyGPzekbMvX2Ldkwg==}
+    engines: {node: '>=12'}
+
+  [email protected]:
+    resolution: {integrity: sha512-d/jtm+rdNT8tpXuHY5MMtcbJFBkhXE6593XVR9UoGCH8jSFGci7jGvMGH5RYd5PBJW+00NZQt6gf7CbagJCrhg==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  [email protected]:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  [email protected]:
+    resolution: {integrity: sha512-wdN2Kd3Twh8MAEOEJZsuxuLKCsBEo4PVNLK6tQWAn10VhsVewQLzcucMgLolRlhFybGxfclbPeEYBaP6RvUFGg==}
+    engines: {node: '>=18.0.0', npm: '>=8.0.0'}
+    hasBin: true
+
+  [email protected]:
+    resolution: {integrity: sha512-AmH3D9hHPFmnF/oq/rvigfiAouAKyK/TjnrkwZRYSFZxNggJxwvbAbfYrLeuvq7ktUdhuHdVdSjj852Z55R+uA==}
+    engines: {node: '>=16.0.0'}
+
+  [email protected]:
+    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
+    engines: {node: '>=0.10.0'}
+
+  [email protected]:
+    resolution: {integrity: sha512-tX5e7OM1HnYr2+a2C/4V0htOcSQcoSTH9KgJnVvNm5zm/cyEWKJ7j7YutsH9CxMdtOkkLFy2AHrMci9IM8IPZQ==}
+    engines: {node: '>=12.0.0'}
+
+  [email protected]:
+    resolution: {integrity: sha512-qjbnuR9Tr+FJOMBqJCW5ehvIo/buZq7vH7qD7JziU98h6l3qGy0a/yPFjwO+y0/T7GFpNgNAvEcPPVfyT8rrPQ==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  [email protected]:
+    resolution: {integrity: sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  [email protected]:
+    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
+  [email protected]:
+    resolution: {integrity: sha512-cZn6NDFE7wdTpINgs++ZJ4N49W2vRp8LCKrn3Ob1kYNtOo21vfDoaV5GzBfLU4MovSAB8uNRm4jgzVQZ+mBzPQ==}
+    engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^18.0.0 || ^20.0.0 || >=22.0.0
+      jiti: '>=1.21.0'
+      less: '*'
+      lightningcss: ^1.21.0
+      sass: '*'
+      sass-embedded: '*'
+      stylus: '*'
+      sugarss: '*'
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      lightningcss:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+snapshots:
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@esbuild/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@rollup/[email protected]':
+    optional: true
+
+  '@serialport/[email protected]':
+    dependencies:
+      '@serialport/bindings-interface': 1.2.2
+      debug: 4.3.4
+    transitivePeerDependencies:
+      - supports-color
+
+  '@serialport/[email protected]':
+    dependencies:
+      '@serialport/bindings-interface': 1.2.2
+      '@serialport/parser-readline': 11.0.0
+      debug: 4.3.4
+      node-addon-api: 7.0.0
+      node-gyp-build: 4.6.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@serialport/[email protected]': {}
+
+  '@serialport/[email protected]': {}
+
+  '@serialport/[email protected]': {}
+
+  '@serialport/[email protected]': {}
+
+  '@serialport/[email protected]': {}
+
+  '@serialport/[email protected]': {}
+
+  '@serialport/[email protected]': {}
+
+  '@serialport/[email protected]':
+    dependencies:
+      '@serialport/parser-delimiter': 11.0.0
+
+  '@serialport/[email protected]':
+    dependencies:
+      '@serialport/parser-delimiter': 12.0.0
+
+  '@serialport/[email protected]': {}
+
+  '@serialport/[email protected]': {}
+
+  '@serialport/[email protected]': {}
+
+  '@serialport/[email protected]': {}
+
+  '@serialport/[email protected]':
+    dependencies:
+      '@serialport/bindings-interface': 1.2.2
+      debug: 4.3.4
+    transitivePeerDependencies:
+      - supports-color
+
+  '@types/[email protected]': {}
+
+  '@types/[email protected]':
+    dependencies:
+      undici-types: 6.21.0
+
+  [email protected]:
+    dependencies:
+      ms: 2.1.2
+
+  [email protected]:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.25.5
+      '@esbuild/android-arm': 0.25.5
+      '@esbuild/android-arm64': 0.25.5
+      '@esbuild/android-x64': 0.25.5
+      '@esbuild/darwin-arm64': 0.25.5
+      '@esbuild/darwin-x64': 0.25.5
+      '@esbuild/freebsd-arm64': 0.25.5
+      '@esbuild/freebsd-x64': 0.25.5
+      '@esbuild/linux-arm': 0.25.5
+      '@esbuild/linux-arm64': 0.25.5
+      '@esbuild/linux-ia32': 0.25.5
+      '@esbuild/linux-loong64': 0.25.5
+      '@esbuild/linux-mips64el': 0.25.5
+      '@esbuild/linux-ppc64': 0.25.5
+      '@esbuild/linux-riscv64': 0.25.5
+      '@esbuild/linux-s390x': 0.25.5
+      '@esbuild/linux-x64': 0.25.5
+      '@esbuild/netbsd-arm64': 0.25.5
+      '@esbuild/netbsd-x64': 0.25.5
+      '@esbuild/openbsd-arm64': 0.25.5
+      '@esbuild/openbsd-x64': 0.25.5
+      '@esbuild/sunos-x64': 0.25.5
+      '@esbuild/win32-arm64': 0.25.5
+      '@esbuild/win32-ia32': 0.25.5
+      '@esbuild/win32-x64': 0.25.5
+
+  [email protected]([email protected]):
+    optionalDependencies:
+      picomatch: 4.0.2
+
+  [email protected]:
+    optional: true
+
+  [email protected]:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  [email protected]: {}
+
+  [email protected]: {}
+
+  [email protected]: {}
+
+  [email protected]: {}
+
+  [email protected]: {}
+
+  [email protected]: {}
+
+  [email protected]:
+    dependencies:
+      nanoid: 3.3.11
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  [email protected]: {}
+
+  [email protected]:
+    dependencies:
+      '@types/estree': 1.0.7
+    optionalDependencies:
+      '@rollup/rollup-android-arm-eabi': 4.43.0
+      '@rollup/rollup-android-arm64': 4.43.0
+      '@rollup/rollup-darwin-arm64': 4.43.0
+      '@rollup/rollup-darwin-x64': 4.43.0
+      '@rollup/rollup-freebsd-arm64': 4.43.0
+      '@rollup/rollup-freebsd-x64': 4.43.0
+      '@rollup/rollup-linux-arm-gnueabihf': 4.43.0
+      '@rollup/rollup-linux-arm-musleabihf': 4.43.0
+      '@rollup/rollup-linux-arm64-gnu': 4.43.0
+      '@rollup/rollup-linux-arm64-musl': 4.43.0
+      '@rollup/rollup-linux-loongarch64-gnu': 4.43.0
+      '@rollup/rollup-linux-powerpc64le-gnu': 4.43.0
+      '@rollup/rollup-linux-riscv64-gnu': 4.43.0
+      '@rollup/rollup-linux-riscv64-musl': 4.43.0
+      '@rollup/rollup-linux-s390x-gnu': 4.43.0
+      '@rollup/rollup-linux-x64-gnu': 4.43.0
+      '@rollup/rollup-linux-x64-musl': 4.43.0
+      '@rollup/rollup-win32-arm64-msvc': 4.43.0
+      '@rollup/rollup-win32-ia32-msvc': 4.43.0
+      '@rollup/rollup-win32-x64-msvc': 4.43.0
+      fsevents: 2.3.3
+
+  [email protected]:
+    dependencies:
+      '@serialport/binding-mock': 10.2.2
+      '@serialport/bindings-cpp': 12.0.1
+      '@serialport/parser-byte-length': 12.0.0
+      '@serialport/parser-cctalk': 12.0.0
+      '@serialport/parser-delimiter': 12.0.0
+      '@serialport/parser-inter-byte-timeout': 12.0.0
+      '@serialport/parser-packet-length': 12.0.0
+      '@serialport/parser-readline': 12.0.0
+      '@serialport/parser-ready': 12.0.0
+      '@serialport/parser-regex': 12.0.0
+      '@serialport/parser-slip-encoder': 12.0.0
+      '@serialport/parser-spacepacket': 12.0.0
+      '@serialport/stream': 12.0.0
+      debug: 4.3.4
+    transitivePeerDependencies:
+      - supports-color
+
+  [email protected]: {}
+
+  [email protected]:
+    dependencies:
+      fdir: 6.4.6([email protected])
+      picomatch: 4.0.2
+
+  [email protected]:
+    dependencies:
+      esbuild: 0.25.5
+      get-tsconfig: 4.10.1
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  [email protected]: {}
+
+  [email protected]: {}
+
+  [email protected](@types/[email protected])([email protected]):
+    dependencies:
+      esbuild: 0.25.5
+      fdir: 6.4.6([email protected])
+      picomatch: 4.0.2
+      postcss: 8.5.5
+      rollup: 4.43.0
+      tinyglobby: 0.2.14
+    optionalDependencies:
+      '@types/node': 22.15.31
+      fsevents: 2.3.3
+      tsx: 4.20.3

src/cli/index.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+/**
+ * lerobot.js CLI
+ *
+ * Provides command-line interface for lerobot functionality
+ * Maintains compatibility with Python lerobot command structure
+ */
+
+import { findPort } from "../lerobot/find_port.js";
+
+/**
+ * Show usage information
+ */
+function showUsage() {
+  console.log("Usage: lerobot <command>");
+  console.log("");
+  console.log("Commands:");
+  console.log(
+    "  find-port    Find the USB port associated with your MotorsBus"
+  );
+  console.log("");
+  console.log("Examples:");
+  console.log("  lerobot find-port");
+  console.log("");
+}
+
+/**
+ * Main CLI function
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    showUsage();
+    process.exit(1);
+  }
+
+  const command = args[0];
+
+  try {
+    switch (command) {
+      case "find-port":
+        await findPort();
+        break;
+
+      case "help":
+      case "--help":
+      case "-h":
+        showUsage();
+        break;
+
+      default:
+        console.error(`Unknown command: ${command}`);
+        showUsage();
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error("Error:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+// Run the CLI
+main();

src/counter.ts

@@ -0,0 +1,9 @@
+export function setupCounter(element: HTMLButtonElement) {
+  let counter = 0
+  const setCounter = (count: number) => {
+    counter = count
+    element.innerHTML = `count is ${counter}`
+  }
+  element.addEventListener('click', () => setCounter(counter + 1))
+  setCounter(0)
+}

src/lerobot/find_port.ts

@@ -0,0 +1,127 @@
+/**
+ * Helper to find the USB port associated with your MotorsBus.
+ *
+ * Direct port of Python lerobot find_port.py
+ *
+ * Example:
+ * ```
+ * npx lerobot find-port
+ * ```
+ */
+
+import { SerialPort } from "serialport";
+import { createInterface } from "readline";
+import { platform } from "os";
+import { readdir } from "fs/promises";
+import { join } from "path";
+
+/**
+ * Find all available serial ports on the system
+ * Mirrors Python's find_available_ports() function
+ */
+async function findAvailablePorts(): Promise<string[]> {
+  if (platform() === "win32") {
+    // List COM ports using serialport library (equivalent to pyserial)
+    const ports = await SerialPort.list();
+    return ports.map((port) => port.path);
+  } else {
+    // List /dev/tty* ports for Unix-based systems (Linux/macOS)
+    try {
+      const devFiles = await readdir("/dev");
+      const ttyPorts = devFiles
+        .filter((file) => file.startsWith("tty"))
+        .map((file) => join("/dev", file));
+      return ttyPorts;
+    } catch (error) {
+      // Fallback to serialport library if /dev reading fails
+      const ports = await SerialPort.list();
+      return ports.map((port) => port.path);
+    }
+  }
+}
+
+/**
+ * Create readline interface for user input
+ * Equivalent to Python's input() function
+ */
+function createReadlineInterface() {
+  return createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+/**
+ * Prompt user for input and wait for response
+ * Equivalent to Python's input() function
+ */
+function waitForInput(prompt: string = ""): Promise<string> {
+  const rl = createReadlineInterface();
+  return new Promise((resolve) => {
+    if (prompt) {
+      process.stdout.write(prompt);
+    }
+    rl.on("line", (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+/**
+ * Sleep for specified milliseconds
+ * Equivalent to Python's time.sleep()
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Main find port function - direct port of Python find_port()
+ * Maintains identical UX and messaging
+ */
+export async function findPort(): Promise<void> {
+  console.log("Finding all available ports for the MotorsBus.");
+
+  const portsBefore = await findAvailablePorts();
+  console.log("Ports before disconnecting:", portsBefore);
+
+  console.log(
+    "Remove the USB cable from your MotorsBus and press Enter when done."
+  );
+  await waitForInput();
+
+  // Allow some time for port to be released (equivalent to Python's time.sleep(0.5))
+  await sleep(500);
+
+  const portsAfter = await findAvailablePorts();
+  const portsDiff = portsBefore.filter((port) => !portsAfter.includes(port));
+
+  if (portsDiff.length === 1) {
+    const port = portsDiff[0];
+    console.log(`The port of this MotorsBus is '${port}'`);
+    console.log("Reconnect the USB cable.");
+  } else if (portsDiff.length === 0) {
+    throw new Error(
+      `Could not detect the port. No difference was found (${JSON.stringify(
+        portsDiff
+      )}).`
+    );
+  } else {
+    throw new Error(
+      `Could not detect the port. More than one port was found (${JSON.stringify(
+        portsDiff
+      )}).`
+    );
+  }
+}
+
+/**
+ * CLI entry point when called directly
+ */
+if (import.meta.url === `file://${process.argv[1]}`) {
+  findPort().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}

src/main.ts

@@ -0,0 +1,24 @@
+import './style.css'
+import typescriptLogo from './typescript.svg'
+import viteLogo from '/vite.svg'
+import { setupCounter } from './counter.ts'
+
+document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
+  <div>
+    <a href="https://vite.dev" target="_blank">
+      <img src="${viteLogo}" class="logo" alt="Vite logo" />
+    </a>
+    <a href="https://www.typescriptlang.org/" target="_blank">
+      <img src="${typescriptLogo}" class="logo vanilla" alt="TypeScript logo" />
+    </a>
+    <h1>Vite + TypeScript</h1>
+    <div class="card">
+      <button id="counter" type="button"></button>
+    </div>
+    <p class="read-the-docs">
+      Click on the Vite and TypeScript logos to learn more
+    </p>
+  </div>
+`
+
+setupCounter(document.querySelector<HTMLButtonElement>('#counter')!)

src/style.css

@@ -0,0 +1,96 @@
+:root {
+  font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+a {
+  font-weight: 500;
+  color: #646cff;
+  text-decoration: inherit;
+}
+a:hover {
+  color: #535bf2;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  place-items: center;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+h1 {
+  font-size: 3.2em;
+  line-height: 1.1;
+}
+
+#app {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.vanilla:hover {
+  filter: drop-shadow(0 0 2em #3178c6aa);
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}
+
+button {
+  border-radius: 8px;
+  border: 1px solid transparent;
+  padding: 0.6em 1.2em;
+  font-size: 1em;
+  font-weight: 500;
+  font-family: inherit;
+  background-color: #1a1a1a;
+  cursor: pointer;
+  transition: border-color 0.25s;
+}
+button:hover {
+  border-color: #646cff;
+}
+button:focus,
+button:focus-visible {
+  outline: 4px auto -webkit-focus-ring-color;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    color: #213547;
+    background-color: #ffffff;
+  }
+  a:hover {
+    color: #747bff;
+  }
+  button {
+    background-color: #f9f9f9;
+  }
+}

src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

tsconfig.cli.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/lerobot/**/*", "src/cli/**/*"],
+  "exclude": [
+    "src/main.ts",
+    "src/counter.ts",
+    "src/style.css",
+    "src/vite-env.d.ts"
+  ]
+}

tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}