tapeo-cli 0.3.0 → 0.4.0

package/README.md

@@ -1,16 +1,50 @@
-# Tapeo local clients (developer preview)
+<p align="center">
+  <img src="https://tapeo.net/icons/icon-512.png" alt="Tapeo" width="96" height="96">
+</p>
 
-A terminal client and a VS Code extension for the same Tapeo projects as the web app. They call the same server, file storage, workflow queue, and plan allowances as the browser, through the token-authenticated API under `/api/client/v1`. They are a developer preview: installed from this repository. Publishing on npm (`tapeo-cli`) and the VS Code Marketplace (`tapeo.tapeo-vscode`) is prepared but not done; see [`docs/RELEASING.md`](../docs/RELEASING.md).
+<h1 align="center">Tapeo for your terminal and VS Code</h1>
+
+<p align="center">Design, run, and fix chips from your own shell or editor, on the same projects as <a href="https://tapeo.net">tapeo.net</a>.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/tapeo-cli"><img src="https://img.shields.io/npm/v/tapeo-cli?label=tapeo-cli&logo=npm&color=cb3837" alt="tapeo-cli on npm"></a>
+  <a href="https://marketplace.visualstudio.com/items?itemName=tapeo.tapeo-vscode"><img src="https://img.shields.io/badge/VS%20Code%20Marketplace-Tapeo-0078d4?logo=visualstudiocode&logoColor=white" alt="Tapeo for VS Code"></a>
+  <img src="https://img.shields.io/node/v/tapeo-cli?logo=nodedotjs&logoColor=white&color=5fa04e" alt="Node.js version">
+  <a href="https://tapeo.net/docs#local-clients"><img src="https://img.shields.io/badge/docs-tapeo.net-e8914a" alt="Documentation"></a>
+</p>
+
+## Quick start
+
+```sh
+npm install -g tapeo-cli
+tapeo login                                   # approve this device in your browser
+tapeo new "A 4-bit counter with enable" ./counter   # design, build, and pull the files
+cd counter && tapeo show                         # stage results of that build
+# edit rtl/…, then: tapeo push --all && tapeo run --watch
+```
+
+In VS Code, install **Tapeo** from the Extensions view and run **Tapeo: Connect to Server**.
+
+| Feature | What you get |
+|---|---|
+| 🧭 **Design with the Architect** | `tapeo new` asks clarifying questions, proposes design options, shows the build plan, and builds. |
+| 🔁 **Edit → run → results** | Push your files, run the full flow or one stage, and read stage results, tool logs, and goals. |
+| 🎯 **Errors on the right line** | `tapeo problems`, or the VS Code Problems panel, points at the line a tool complained about. |
+| 🛠️ **AI Engineer** | `tapeo ask` streams an answer; review the proposed diff and `tapeo apply` it locally. |
+| 🔒 **Safe sync** | Every push names the version it was based on; your local edits are never overwritten. |
+
+## About
+
+A terminal client and a VS Code extension for the same Tapeo projects as the web app. They call the same server, file storage, workflow queue, and plan allowances as the browser, through the token-authenticated API under `/api/client/v1`. Version 0.4.0 was published on 2026-10-24 (`tapeo-cli` on npm and **Tapeo**, `tapeo.tapeo-vscode`, on the VS Code Marketplace). They are early releases (0.x).
 
 The edit → run → results loop works without the browser: push your files, start a run, follow it stage by stage, and read stage results, tool logs, and goal results. You can also start a new design with the Architect, ask the AI Engineer and apply its proposed changes locally, and see tool errors on the lines they name. The 2D/3D layout views, Evaluation-plan review, and Architect image/PDF attachments stay in the web workspace.
 
-The server needs migrations `0008_client_tokens` and `0009_device_authorization` (`npx prisma migrate deploy`; the Docker deployment applies them on start).
+Self-hosted servers need migrations `0008_client_tokens` and `0009_device_authorization` (`npx prisma migrate deploy`; the Docker deployment applies them on start). Maintainers: releasing is described in `docs/RELEASING.md` in the Tapeo repository.
 
 ## Sign in
 
 ```sh
-npm install -g ./clients          # or: npm run tapeo -- <command> from the repository root
-                                  # once published: npm install -g tapeo-cli
+npm install -g tapeo-cli          # from source: npm install -g ./clients, or npm run tapeo -- <command>
 tapeo login                       # https://tapeo.net; or: tapeo login https://your-own-server
 ```
 
@@ -22,6 +56,7 @@ tapeo login                       # https://tapeo.net; or: tapeo login https://y
 tapeo projects                         # your projects
 tapeo create "My sensor" ./my-sensor   # new empty project, bound to the folder
 tapeo pull PROJECT_ID ./existing       # or bind an existing project
+tapeo delete PROJECT_ID                # delete a project on the server for good (asks for its name)
 cd ./my-sensor
 tapeo status                           # what changed locally, and the latest run
 tapeo push --all                       # push every modified and new source file
@@ -42,6 +77,8 @@ tapeo open                             # the project's web address
 tapeo --version                        # this client's version (tapeo help lists every command)
 ```
 
+`tapeo delete` removes a project on the server for good, like the delete button in the browser's project list: its files, checkpoints, runs, layouts, and Engineer history (a running workflow stops). In a linked folder it deletes that folder's project unless you name another. You confirm by typing the project name (`--yes` skips this, for scripts). Local files stay, and the folder is no longer linked.
+
 ### AI
 
 ```sh
@@ -64,6 +101,23 @@ The Engineer reads the saved server copy of your files (`tapeo ask` warns when l
 
 Stages: `simulation`, `synthesis`, `timing`, `physical`, `post-route-timing`, `drc`, `extraction`, `erc`, `lvs`. `--no-ai-repairs` turns off AI repairs for a stage run. A full run uses one build from your plan; a stage run does not. `tapeo run --watch` exits with code 3 when the run fails.
 
+### FPGA boards
+
+For a project whose target is an FPGA board, or an FPGA board and a chip (the Architect asks where a design runs; you can change it on the Workflow tab), the workflow simulates the RTL, then builds and checks a bitstream for the board on the server. Supported boards: Sipeed Tang Nano 9K and Tang Nano 20K, 1BitSquared iCEBreaker, and Radiona ULX3S (12F and 85F). A design clock other than the board clock gets a PLL generated by the toolchain's own calculator.
+
+```sh
+tapeo run --watch        # simulate, build the bitstream, report logic use and Fmax
+tapeo flash              # download the bitstream and program the connected board
+tapeo flash --flash      # keep it after power-off (Tang Nano and ULX3S otherwise load to SRAM)
+tapeo flash --board icebreaker   # when bitstreams exist for several boards
+tapeo monitor            # the board's serial (UART) output; type a line to send it
+tapeo monitor --port /dev/cu.usbserial-1101 --baud 9600
+```
+
+`tapeo flash` runs the open-source `openFPGALoader` on your computer and tells you how to install it if it is missing (`brew install openfpgaloader` on macOS, `sudo apt install openfpgaloader` on Debian/Ubuntu, or OSS CAD Suite elsewhere). `TAPEO_OPENFPGALOADER` points to it when it is not on your PATH. The bitstream is saved read-only under `generated/fpga/<board>/`.
+
+`tapeo monitor` needs no sign-in and works on macOS and Linux: it finds the USB serial port (name one with `--port` when there are several; a Tang Nano shows two and its serial link is usually the second) and uses 115200 baud unless you pass `--baud`. On Linux you may need to be in the `dialout` group. On Windows, use the **Serial monitor** on the project's Workflow tab in Chrome or Edge.
+
 ## VS Code
 
 Run `npm run build:vscode`, open `clients/vscode` in VS Code, and press F5; or run `npm run package:vscode` and install `clients/vscode/tapeo-vscode.vsix` with **Extensions: Install from VSIX...**. In the Command Palette:
@@ -75,6 +129,8 @@ Run `npm run build:vscode`, open `clients/vscode` in VS Code, and press F5; or r
 - **Show Workflow Runs**, **Show Run Details**, **Open a Tool Log**, **Show Goal Results**, **Cancel Workflow**, **Open Project in Browser**.
 - **New Design with the Architect** (in an empty folder): the Architect's questions appear as quick picks with "Not sure — you choose", then the design options and the build plan; **Build** creates the project, starts the first build, and pulls the generated files when it ends.
 - **Open AI Engineer** opens the **Tapeo Engineer** panel beside the editor: the project conversation, streamed answers, and the proposed changes with **Review** (a side-by-side diff), **Apply**, **Apply all**, and **Discard**. **Ask the AI Engineer**, **Review Proposed Changes**, **Apply All Proposed Changes**, and **Discard Proposed Changes** do the same from the Command Palette. Applying is refused while the file has unsaved edits; push afterwards.
+- **Program FPGA Board** (FPGA projects): downloads the bitstream and programs the connected board with `openFPGALoader` in a **Tapeo FPGA** terminal.
+- **Open Serial Monitor** (macOS and Linux): shows the board's serial output in a terminal and sends the lines you type.
 - **Show Tool Problems**: the latest run's tool errors and warnings in the Problems panel. This also happens automatically when a run the status bar follows ends, and starting a run clears them.
 
 The setting `tapeo.serverUrl` holds the server (Connect to Server sets it; remote servers must use HTTPS).

package/cli/tapeo.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, hostname } from "node:os";
 import path from "node:path";
@@ -8,6 +8,8 @@ import { assertUnbound, designFilesFrom, downloadFile, localChanges, moveProject
 import { applyProposals, changeDiff, describeChange, discardProposals, loadProposals, saveProposals } from "../shared/proposals.mjs";
 import { collectRunProblems, formatProblem } from "../shared/problems.mjs";
 import { NOT_SURE, clarificationAnswersMessage } from "../shared/stream.mjs";
+import { chooseSerialPort, openSerialPort, parseBaud, serialCandidates } from "../shared/serial.mjs";
+import { OPENFPGALOADER_INSTALL, chooseBitstream, downloadBitstream, flashArguments, openFpgaLoaderAvailable, openFpgaLoaderExecutable } from "../shared/fpga.mjs";
 import { createInterface } from "node:readline/promises";
 
 const configPath = path.join(homedir(), ".config", "tapeo", "client.json");
@@ -15,7 +17,7 @@ const clientVersion = JSON.parse(await readFile(new URL("../package.json", impor
 setClientIdentity("tapeo-cli", clientVersion);
 
 function usage() {
-  console.log(`Tapeo terminal client (developer preview)
+  console.log(`Tapeo terminal client
 
 Sign in
   tapeo login [server-url]        Sign in through your browser (approve this device there);
@@ -27,6 +29,9 @@ Sign in
 Projects and files
   tapeo projects                  List your projects
   tapeo create <name> [dir]       Create an empty project and bind a local folder
+  tapeo delete [project-id]       Delete a project on the server for good (this folder's
+                                  project by default; asks you to type its name, --yes
+                                  skips that); local files are kept
   tapeo pull <project-id> [dir]   Pull source files without overwriting local edits
   tapeo pull --outputs            Also download tool outputs (generated/, signoff/) read-only
   tapeo status                    What changed locally, and the latest run
@@ -57,6 +62,15 @@ Workflow
   tapeo cancel [run-id]           Cancel a queued or running workflow
   tapeo open                      Print this project's web address
 
+FPGA boards
+  tapeo flash [--board <id>] [--flash]
+                                  Download the bitstream and program the connected board with
+                                  openFPGALoader (--flash: keep it after power-off on boards
+                                  that load to SRAM by default, such as the Tang Nano 9K)
+  tapeo monitor [--port <path>] [--baud <n>]
+                                  Show the board's serial (UART) output and send what you
+                                  type; default 115200 baud (macOS and Linux)
+
 Stages: simulation, synthesis, timing, physical, post-route-timing, drc, extraction, erc, lvs.
 TAPEO_URL and TAPEO_TOKEN override the saved sign-in (for automation).`);
 }
@@ -121,7 +135,7 @@ async function configuredClient() {
   catch (error) { if (error.code !== "ENOENT") throw error; }
   const serverUrl = process.env.TAPEO_URL || saved.serverUrl;
   const token = process.env.TAPEO_TOKEN || saved.token;
-  if (!serverUrl || !token) throw new Error("Run `tapeo login <server-url>` first, or set TAPEO_URL and TAPEO_TOKEN.");
+  if (!serverUrl || !token) throw new Error("Run `tapeo login` first (or `tapeo login <server-url>` for your own server), or set TAPEO_URL and TAPEO_TOKEN.");
   return new TapeoClient(serverUrl, token);
 }
 
@@ -283,8 +297,29 @@ async function main() {
     console.log("Signed out on this computer. Revoke the token on the Account page to end its access everywhere.");
     return;
   }
+  // The serial monitor talks only to the board, so it needs no sign-in.
+  if (command === "monitor") {
+    const { flags } = parseArguments(rest, ["port", "baud"]);
+    const port = chooseSerialPort(serialCandidates(), typeof flags.port === "string" ? flags.port : undefined);
+    const baud = parseBaud(flags.baud);
+    const serial = openSerialPort(port, baud);
+    console.error(`Connected to ${port} at ${baud} baud. Type a line and press Enter to send it; Ctrl+C stops.`);
+    serial.input.pipe(process.stdout);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (text) => serial.write(text));
+    await new Promise((resolve) => {
+      const stop = () => { serial.close(); resolve(); };
+      process.once("SIGINT", stop);
+      // Ctrl+D at a keyboard stops; piped input just sends and keeps listening.
+      if (process.stdin.isTTY) process.stdin.once("end", stop);
+      serial.input.once("close", stop);
+      serial.input.once("error", (error) => { console.error(`The serial port closed: ${error.message}`); stop(); });
+    });
+    process.stdin.destroy();
+    return;
+  }
   const client = await configuredClient();
-  const { flags, positional: args } = parseArguments(rest, ["stage", "from", "option", "limit"]);
+  const { flags, positional: args } = parseArguments(rest, ["stage", "from", "option", "limit", "board"]);
   if (command === "new") {
     await newDesign(client, args[0], path.resolve(args[1] || "."), flags);
   } else if (command === "ask") {
@@ -337,6 +372,24 @@ async function main() {
     const { projects } = await client.projects();
     for (const project of projects) console.log(`${project.id}\t${project.name}`);
     if (!projects.length) console.log("No projects yet. Run tapeo create <name> [directory].");
+  } else if (command === "delete") {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client, args[0]);
+    const { project } = await client.project(projectId);
+    if (!flags.yes) {
+      if (!process.stdin.isTTY) throw new Error(`Deleting "${project.name}" cannot be undone. Confirm with --yes.`);
+      const prompt = prompter();
+      try {
+        console.log(`This deletes "${project.name}" (${project.id}) on ${client.serverUrl} for good: its files, checkpoints, runs, layouts, and Engineer history. A running workflow stops. Local files are kept.`);
+        const typed = (await prompt.ask("Type the project name to confirm: ")).trim();
+        if (typed !== project.name.trim()) { console.log("The name did not match. Nothing was deleted."); return; }
+      } finally { prompt.close(); }
+    }
+    await client.deleteProject(projectId);
+    // A folder bound to the deleted project is unbound, so later commands do not point at it.
+    const bound = await readState(directory).catch(() => null);
+    if (bound?.projectId === projectId && bound.serverUrl === client.serverUrl) await rm(path.join(directory, ".tapeo"), { recursive: true, force: true });
+    console.log(`Deleted "${project.name}".${bound?.projectId === projectId ? " This folder is no longer linked to a Tapeo project; its files are unchanged." : ""}`);
   } else if (command === "create") {
     if (!args[0]?.trim()) throw new Error("Usage: tapeo create <name> [directory]");
     const directory = path.resolve(args[1] || ".");
@@ -435,6 +488,18 @@ async function main() {
     }
     const { run } = await client.cancelRun(projectId, runId);
     console.log(`Cancelled ${run.id}. A tool step already running finishes first; finished stages keep their results.`);
+  } else if (command === "flash") {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client);
+    const { files } = await client.project(projectId);
+    const bitstream = chooseBitstream(files, flags.board);
+    const executable = openFpgaLoaderExecutable();
+    if (!openFpgaLoaderAvailable(executable)) throw new Error(OPENFPGALOADER_INSTALL);
+    const local = await downloadBitstream(client, projectId, bitstream, directory);
+    console.log(`Programming the ${bitstream.label} with ${path.relative(directory, local)}${flags.flash ? " (writing to flash)" : ""}…`);
+    const result = spawnSync(executable, flashArguments(bitstream, local, { flash: Boolean(flags.flash) }), { stdio: "inherit" });
+    if (result.error || result.status !== 0) throw new Error("openFPGALoader could not program the board. Check the USB cable and that no other program is using the board; its messages are above.");
+    console.log(`Programmed the ${bitstream.label}.`);
   } else if (command === "open") {
     const projectId = await projectIdFor(client, args[0]);
     console.log(`${client.serverUrl}/?project=${encodeURIComponent(projectId)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tapeo-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Terminal client for Tapeo: edit hardware projects locally, run the server's EDA workflow, read results, and work with the AI Architect and Engineer.",
   "keywords": [
     "tapeo",

package/shared/api.mjs

@@ -182,6 +182,16 @@ export class TapeoClient {
   projects() { return this.request("GET", "/projects"); }
   createProject(name, description = "", hardwareType = "Undecided") { return this.request("POST", "/projects", { name, description, hardwareType }); }
   project(id) { return this.request("GET", `/projects/${encodeURIComponent(id)}`); }
+  /** Delete a project on the server for good (files, runs, history). */
+  async deleteProject(id) {
+    try {
+      return await this.request("DELETE", `/projects/${encodeURIComponent(id)}`);
+    } catch (error) {
+      // Servers older than this client have no delete route for local clients.
+      if (error?.status === 405) throw new TapeoApiError(`This Tapeo server cannot delete projects from the terminal yet. Delete it in the browser: open ${this.serverUrl}, then use the delete button next to the project in your project list.`, 405);
+      throw error;
+    }
+  }
   file(id, path) { return this.request("GET", `/projects/${encodeURIComponent(id)}/files?path=${encodeURIComponent(path)}`); }
   saveFile(id, path, content, baseSha256, language) { return this.request("PUT", `/projects/${encodeURIComponent(id)}/files?path=${encodeURIComponent(path)}`, { content, baseSha256, language }); }
   deleteFile(id, path, baseSha256) { return this.request("DELETE", `/projects/${encodeURIComponent(id)}/files?path=${encodeURIComponent(path)}&baseSha256=${encodeURIComponent(baseSha256)}`); }

package/shared/fpga.mjs

@@ -0,0 +1,72 @@
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { localTarget } from "./sync.mjs";
+
+/**
+ * Programming an FPGA board from the local clients (tapeo flash, and Tapeo:
+ * Program FPGA Board in VS Code). The bitstream is built on the server; this
+ * downloads it and runs the open-source openFPGALoader on your computer.
+ * Board names mirror lib/fpga-boards.ts (tests/client-fpga.test.ts keeps them in sync).
+ */
+export const FPGA_PROGRAMMERS = {
+  tangnano9k: { label: "Sipeed Tang Nano 9K", openFpgaLoaderBoard: "tangnano9k" },
+  tangnano20k: { label: "Sipeed Tang Nano 20K", openFpgaLoaderBoard: "tangnano20k" },
+  icebreaker: { label: "1BitSquared iCEBreaker", openFpgaLoaderBoard: "ice40_generic" },
+  ulx3s12f: { label: "Radiona ULX3S (12F)", openFpgaLoaderBoard: "ulx3s" },
+  ulx3s85f: { label: "Radiona ULX3S (85F)", openFpgaLoaderBoard: "ulx3s" }
+};
+
+export const OPENFPGALOADER_INSTALL = [
+  "openFPGALoader is needed to program the board. Install it, then run this again:",
+  "  macOS:          brew install openfpgaloader",
+  "  Debian/Ubuntu:  sudo apt install openfpgaloader",
+  "  Windows/other:  it is included in OSS CAD Suite (https://github.com/YosysHQ/oss-cad-suite-build)"
+].join("\n");
+
+/** The bitstreams a project has, newest builds per board (paths from the server manifest). */
+export function findBitstreams(files) {
+  return files.flatMap((file) => {
+    const match = /^generated\/fpga\/([a-z0-9]+)\/board_top\.(fs|bin|bit)$/.exec(file.path);
+    return match && FPGA_PROGRAMMERS[match[1]] ? [{ path: file.path, boardId: match[1], ...FPGA_PROGRAMMERS[match[1]] }] : [];
+  });
+}
+
+/** Pick the board to program: the only one built, or the one named with --board. */
+export function chooseBitstream(files, boardId) {
+  const bitstreams = findBitstreams(files);
+  if (!bitstreams.length) throw new Error("This project has no bitstream yet. Run the workflow first (tapeo run --watch); FPGA projects build one for their board.");
+  if (boardId) {
+    const chosen = bitstreams.find((item) => item.boardId === boardId);
+    if (!chosen) throw new Error(`No bitstream for ${boardId}. Built for: ${bitstreams.map((item) => item.boardId).join(", ")}.`);
+    return chosen;
+  }
+  if (bitstreams.length > 1) throw new Error(`Bitstreams exist for several boards (${bitstreams.map((item) => item.boardId).join(", ")}). Name one with --board.`);
+  return bitstreams[0];
+}
+
+/** Download the bitstream into the project folder (read-only, like other tool outputs). */
+export async function downloadBitstream(client, projectId, bitstream, directory) {
+  const { bytes } = await client.rawFile(projectId, bitstream.path);
+  const target = await localTarget(directory, bitstream.path);
+  await mkdir(path.dirname(target), { recursive: true });
+  await chmod(target, 0o644).catch(() => undefined);
+  await writeFile(target, bytes);
+  await chmod(target, 0o444).catch(() => undefined);
+  return target;
+}
+
+/** The programmer to run; TAPEO_OPENFPGALOADER overrides the executable (for example a full path). */
+export function openFpgaLoaderExecutable() {
+  return process.env.TAPEO_OPENFPGALOADER || "openFPGALoader";
+}
+
+export function openFpgaLoaderAvailable(executable = openFpgaLoaderExecutable()) {
+  const result = spawnSync(executable, ["-V"], { encoding: "utf8" });
+  return !result.error && result.status === 0;
+}
+
+/** openFPGALoader arguments: SRAM by default (lost at power-off), flash with `flash: true`. */
+export function flashArguments(bitstream, localPath, { flash = false } = {}) {
+  return ["-b", bitstream.openFpgaLoaderBoard, ...(flash ? ["--write-flash"] : []), localPath];
+}

package/shared/serial.mjs

@@ -0,0 +1,77 @@
+import { closeSync, constants, openSync, readdirSync, writeSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import tty from "node:tty";
+
+/**
+ * A serial monitor for a connected FPGA board (tapeo monitor, and Tapeo: Open
+ * Serial Monitor in VS Code), without native modules: the port is opened as a
+ * file, configured with the system's stty on that open descriptor, and read as
+ * a terminal stream. macOS and Linux only; on Windows, use the browser's serial
+ * monitor on the Workflow tab (Chrome or Edge).
+ */
+
+export const DEFAULT_BAUD = 115200;
+export const SERIAL_UNSUPPORTED = "The serial monitor runs on macOS and Linux. On Windows, open the project's Workflow tab in Chrome or Edge and use its Serial monitor.";
+
+/** USB serial ports that may be a board, newest naming first. macOS uses the cu.* (call-out) devices, which do not wait for a carrier. */
+export function serialCandidates(platform = process.platform, names = safeList("/dev")) {
+  const pattern = platform === "darwin" ? /^cu\.(?:usbserial|usbmodem|wchusbserial|SLAB_USBtoUART)/ : platform === "linux" ? /^tty(?:USB|ACM)\d+$/ : null;
+  if (!pattern) return [];
+  return names.filter((name) => pattern.test(name)).sort().map((name) => `/dev/${name}`);
+}
+
+function safeList(directory) {
+  try { return readdirSync(directory); } catch { return []; }
+}
+
+/** The port to open: the one named, the only one found, or an explanation. */
+export function chooseSerialPort(candidates, requested) {
+  if (requested) return requested;
+  if (!candidates.length) throw new Error("No USB serial port was found. Connect the board by USB, or name the port with --port.");
+  if (candidates.length > 1) throw new Error(`Several serial ports were found:\n${candidates.map((item) => `  ${item}`).join("\n")}\nName one with --port. A Tang Nano shows two; its serial link is usually the second.`);
+  return candidates[0];
+}
+
+export function parseBaud(value) {
+  if (value === undefined || value === true) return DEFAULT_BAUD;
+  const baud = Number(value);
+  if (!Number.isInteger(baud) || baud < 300 || baud > 4_000_000) throw new Error(`--baud must be a whole number from 300 to 4000000 (got ${value}).`);
+  return baud;
+}
+
+/** stty settings for 8N1 raw data at `baud`, no flow control, ignoring modem lines. */
+export function sttyArguments(baud) {
+  return [String(baud), "raw", "-echo", "cs8", "-cstopb", "-parenb", "clocal", "-crtscts", "-ixon", "-ixoff"];
+}
+
+/**
+ * Open `portPath` at `baud`. Returns the incoming stream, a write function, and close.
+ * The settings are applied while the port is open, so the driver keeps them.
+ */
+export function openSerialPort(portPath, baud = DEFAULT_BAUD, platform = process.platform) {
+  if (platform !== "darwin" && platform !== "linux") throw new Error(SERIAL_UNSUPPORTED);
+  let readFd;
+  try {
+    readFd = openSync(portPath, constants.O_RDWR | constants.O_NOCTTY | constants.O_NONBLOCK);
+  } catch (error) {
+    throw new Error(error?.code === "EBUSY" || error?.code === "EACCES"
+      ? `Could not open ${portPath}: ${error.code === "EBUSY" ? "another program is using it (close other serial monitors)" : "permission denied (on Linux, add yourself to the dialout group, then sign in again)"}.`
+      : `Could not open ${portPath}: ${error?.message ?? error}`);
+  }
+  if (!tty.isatty(readFd)) { closeSync(readFd); throw new Error(`${portPath} is not a serial port.`); }
+  const configured = spawnSync("stty", sttyArguments(baud), { stdio: [readFd, "ignore", "pipe"], encoding: "utf8" });
+  if (configured.error || configured.status !== 0) { closeSync(readFd); throw new Error(`Could not set ${portPath} to ${baud} baud: ${configured.stderr?.trim() || configured.error?.message || "stty failed"}.`); }
+  const writeFd = openSync(portPath, constants.O_WRONLY | constants.O_NOCTTY);
+  const input = new tty.ReadStream(readFd);
+  let closed = false;
+  return {
+    input,
+    write(data) { if (!closed) writeSync(writeFd, typeof data === "string" ? Buffer.from(data, "utf8") : data); },
+    close() {
+      if (closed) return;
+      closed = true;
+      input.destroy();
+      try { closeSync(writeFd); } catch { /* already closed */ }
+    }
+  };
+}