@bscript/cli

The BlueScript CLI (bscript) is the primary tool for managing projects, setting up board environments, and running code on devices.

For end-user documentation, see the CLI Reference on the project website.

Development

From the repository root:

npm install

Build and test the CLI package:

cd cli
npm run build
npm test                 # unit tests only
npm run test:integration # host integration tests (macOS, Windows or Linux)
npm run test:all         # unit + integration

Test layout

| Script | Jest project | Location | Notes | | :--- | :--- | :--- | :--- | | npm test | unit | tests/**/*.test.ts (excludes integration/) | Mocks fs, shell, logger, devices | | npm run test:integration | integration | tests/integration/**/*.test.ts | Real host shell process; macOS, Linux or Windows (MinGW-w64) | | npm run test:all | both | — | Run before merging CLI changes |

Integration test requirements: macOS (cc), Linux(gcc) or Windows (MinGW-w64: gcc, mingw32-make), and the microcontroller/ tree at the repository root. On first run, tests build microcontroller/ports/host/build/shell (or shell.exe) and c-runtime.so (or c-runtime.dll) if missing.

Supported platforms: macOS, Linux and Windows for host and esp32 board setup. On Windows, install the Visual C++ Build Environment before npm install (node-gyp), and MinGW-w64 for the host runtime. See Windows prerequisites on the website.

Integration coverage (14 tests):

• tests/integration/project/run.host.test.ts — project run on host: normal output, built-in library, functions/variables, local import, local package import, inline C, .c / .h includes, compile error
• tests/integration/project/repl.host.test.ts — repl -b host: entry line, built-in calls, variable/function persistence, compile-error recovery

CLI step logs are suppressed during integration runs (tests/integration-setup.ts). Program output from BlueScript code is still asserted via captured stdout.

Integration tests do not replace manual checks for ESP32 hardware, serial/BLE, Notebook UI, Git-based project install, or interactive TTY behavior (Ctrl-D, prompts). See docs/manual-test.md for the manual QA checklist and coverage map.

Run the CLI from source without a global install:

npm start -- <subcommand> [options]
# Example:
npm start -- board list

Install locally for manual testing:

npm run build
npm link
bscript -v

Manual testing

Before merging CLI changes or cutting a release:

1. Run npm run test:all (or at least npm test; on mac, Linux or Windows also npm run test:integration).
2. Follow the manual QA checklist: docs/manual-test.md

• Daily PRs: run automated tests plus Quick smoke (host) (~15 minutes).
• Releases / ESP32 changes: run the full checklist and ESP32 scenarios.