Serial Port
@shrug/serial-portv2026.07.22.2
01README
USB-UART serial console + config management. The serial-port type is the raw console primitive (establish/send/read/exec/login) over a serial device (e.g. /dev/ttyUSB0); line config via stty(1), byte I/O via a direct Deno.open fd or a dd/cat subprocess fallback (auto), device paths allowlisted so login's vaulted password can't reach an arbitrary terminal. The serial-cfgmgmt/* types (node/exec/package/service) are the serial-console counterpart to SSH config management — for boards with no network — built on that same console primitive.
02Models
@shrug/serial-portv2026.07.22.2serial_port.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| device | string | Serial device path, e.g. /dev/ttyUSB0. |
| baud | number | Baud rate. Default 115200. |
| framing | string | Data/parity/stop framing, e.g. 8N1 (8 data bits, no parity, 1 stop bit). |
| lineEnding | string | Line terminator appended to sent lines. Default LF; use \\r for consoles that need carriage return. |
| transport | enum | Byte-I/O transport: 'direct' (Deno.open raw fd), 'subprocess' (dd, needs only allow-run), or 'auto' (direct with subprocess fallback on a device-open permission denial). |
| username? | string | Default username for `login`. |
| password? | string | Default password for `login`, resolved from a vault reference. Never a literal. |
fn establish()
Validate + configure the serial port (baud/framing/raw), probe it briefly, and record the `port` resource that later calls inherit config from. Fails loudly when the port is held by another process.
fn send(text: string, appendNewline: boolean, raw: boolean)
Write one line to the port (appends the line ending unless raw). Does not read a response.
| Argument | Type | Description |
|---|---|---|
| text | string | Text to send. |
| appendNewline | boolean | Append the configured line ending. Set false with `raw` to send exact bytes. |
| raw | boolean | Treat `text` as an exact payload (implies appendNewline=false). |
fn read()
Drain inbound bytes from the port until it goes idle or the cap is reached.
fn exec(command: string, prompt?: string, stripEcho: boolean)
Send a command line and capture the response until the prompt returns (if given) or the line goes idle. The console-shell primitive.
| Argument | Type | Description |
|---|---|---|
| command | string | Command line to send. |
| prompt? | string | Optional regex; stop reading once the response's tail matches it (e.g. the shell prompt). |
| stripEcho | boolean | Strip the echoed command line from the captured output. |
fn login(username?: string, promptAfter?: string)
Answer a getty login (login:/Password:) using the vaulted credential, then confirm the shell prompt. The password is never written to the recorded transcript.
| Argument | Type | Description |
|---|---|---|
| username? | string | Username; defaults to the model's `username` global. |
| promptAfter? | string | Optional regex for the shell prompt to expect after login (default matches a trailing $ , # , or > ). |
fn session_start()
Start a persistent session holder: a detached `socat` opens the port once and bridges it to a PTY, so the logged-in shell survives across separate method runs. Later send/read/exec/login (and serial-cfgmgmt) calls automatically attach to the holder. Idempotency: errors if one is already live — stop it first with session_stop.
fn session_stop()
Stop the persistent session holder on the port (SIGTERM the socat holder, remove the PTY link). Safe to call when none is running.
fn session_status()
Report whether a persistent session holder is running on the port. Recomputes liveness from the holder pid + PTY link (a dead holder reads as not-live and I/O methods fall back to open/close).
Resources
port(infinite)— The configured serial port and its probe capture.
sent(infinite)— Record of a send() write.
captured(infinite)— Output captured by read().
execResult(infinite)— Result of an exec() command/response round-trip.
loginResult(infinite)— Result of a login() attempt (password scrubbed).
session(infinite)— A persistent socat session holder for the port (pid + PTY link).
@shrug/serial-cfgmgmt/nodev2026.07.22.2serial_cfgmgmt_node.ts
fn gather()
Log in over the serial console (if credentials are set) and gather system facts (hostname, OS, arch, kernel, package managers). Writes the `info` resource.
Resources
info(infinite)— System facts gathered from the node over the serial console.
@shrug/serial-cfgmgmt/execv2026.07.22.2serial_cfgmgmt_exec.ts
fn run(command: string)
Run a single command line over the serial console and record its stdout and exit code.
| Argument | Type | Description |
|---|---|---|
| command | string | Command line to run. |
Resources
result(infinite)— Result of a command run over the serial console.
@shrug/serial-cfgmgmt/packagev2026.07.22.2serial_cfgmgmt_package.ts
fn query(name: string)
Check whether a package is installed on the target (read-only) and record its version.
| Argument | Type | Description |
|---|---|---|
| name | string | Package name. |
fn install(name: string)
Install a package on the target (MUTATING; assumes a privileged shell). Idempotent: no-op when already installed.
| Argument | Type | Description |
|---|---|---|
| name | string | Package name. |
Resources
package(infinite)— State of a package on the target.
@shrug/serial-cfgmgmt/servicev2026.07.22.2serial_cfgmgmt_service.ts
fn status(name: string)
Read a systemd unit's active and enabled state (read-only).
| Argument | Type | Description |
|---|---|---|
| name | string | systemd unit name, e.g. sshd.service. |
Resources
service(infinite)— State of a systemd unit on the target.
03Stats
A
100 / 100
Downloads
4
Archive size
90.2 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
04Platforms
05Labels