nova-control-command 0.0.1

package/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2026-present Andreas Rozek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# nova-control-command
+
+CLI for controlling a **NOVA DIY Artificial Intelligence Robot** by Creoqode. Provides one-shot commands, an interactive REPL shell, and a batch script runner for moving servos, running motion sequences, and inspecting the current servo state.
+
+---
+
+## Prerequisites
+
+| requirement | details |
+| --- | --- |
+| **Node.js 22+** | required to run `nova-control`. Download from [nodejs.org](https://nodejs.org). |
+| **NOVA robot** | connected via USB serial. The Arduino sketch must be flashed and running before issuing commands. |
+| **Linux serial permissions** | on Linux, add your user to the `dialout` group: `sudo usermod -aG dialout $USER` (re-login required). |
+
+---
+
+## Installation
+
+```bash
+npm install nova-control-command
+```
+
+After installation the `nova-control` binary is available in the project's `node_modules/.bin/` directory and — when installed globally — directly on the `PATH`.
+
+---
+
+## Concepts
+
+| mode | how to trigger |
+| --- | --- |
+| one-shot | `nova-control --port <path> <command> [args]` — runs a single command and exits |
+| script | `nova-control --port <path> --script <file>` — reads commands line-by-line from a file or stdin (`-`) |
+| REPL | `nova-control --port <path> shell` — opens an interactive read-eval-print loop |
+
+`nova-control` without any arguments prints the help text and exits.
+
+In script and REPL mode the serial connection is opened once on the first servo command and kept alive for the duration of the session — `wait` and `help` do not touch the port.
+
+---
+
+## Global options
+
+| option | description |
+| --- | --- |
+| `--port <path>` | serial port path (e.g. `/dev/ttyACM0` on Linux/macOS, `COM3` on Windows) |
+| `--baud <rate>` | baud rate (default: `9600`) |
+| `--on-error <mode>` | script error mode: `stop` (default), `continue`, or `ask` |
+| `--script <file>` | run commands from a file (`-` reads from stdin) |
+| `--version` | print version number and exit |
+
+---
+
+## Command reference
+
+### `home`
+
+```
+nova-control --port <path> home
+```
+
+Sends all five servos to their home positions simultaneously. Home positions are baked into the firmware (`s1=90°`, `s2=90°`, `s3=110°`, `s4=90°`, `s5=95°`).
+
+---
+
+### Individual servo commands
+
+Each command sets exactly one servo and leaves all others at their last-sent positions.
+
+```
+nova-control --port <path> shift-to  <deg>   # head forward (>90°) or back (<90°) — s1
+nova-control --port <path> roll-to   <deg>   # head clockwise (>90°) or counter-clockwise (<90°) — s2
+nova-control --port <path> pitch-to  <deg>   # head up (>110°) or down (<110°) — s3
+nova-control --port <path> rotate-to <deg>   # body rotation around Z-axis — s4
+nova-control --port <path> lift-to   <deg>   # secondary head lift, range 20°–150° — s5
+```
+
+`<deg>` is a number in degrees. The firmware clamps out-of-range values silently.
+
+---
+
+### `move`
+
+```
+nova-control --port <path> move [--shift-to <deg>] [--roll-to <deg>] [--pitch-to <deg>]
+                                 [--rotate-to <deg>] [--lift-to <deg>]
+```
+
+Sets multiple servos in a single packet. At least one option is required. Servos not mentioned stay at their last-sent positions. Useful when two or more joints must move simultaneously.
+
+---
+
+### `wait`
+
+```
+nova-control --port <path> wait <ms>
+```
+
+Pauses execution for `<ms>` milliseconds before the next command. Does not open the serial connection. Particularly useful in scripts and the REPL to let the robot settle between moves.
+
+---
+
+### `state`
+
+```
+nova-control --port <path> state
+```
+
+Prints the current servo state as a single JSON object to stdout. The state reflects what was last *sent* to the Arduino — there is no read-back channel in the protocol.
+
+---
+
+### `shell`
+
+```
+nova-control --port <path> shell
+```
+
+Opens an interactive REPL. Each line is parsed and executed as a `nova-control` command without the `nova-control` prefix. Blank lines and lines starting with `#` are ignored. Type `exit` or `quit` to close the session.
+
+The serial port is opened on the first command that needs it and held open for the entire session.
+
+**Getting help inside the REPL:**
+
+| what you type | what you get |
+| --- | --- |
+| `help` | list of all available commands |
+| `<command> --help` | help for a specific command (e.g. `move --help`) |
+
+---
+
+### `--script`
+
+```
+nova-control --port <path> --script <file>
+nova-control --port <path> --script -        # read from stdin
+```
+
+Reads commands from a file (or stdin), executing them one per line. Lines starting with `#` and blank lines are ignored. Error handling follows `--on-error`: `stop` aborts on the first error (default), `continue` keeps going, `ask` prompts interactively (TTY only, falls back to `stop` in pipes).
+
+---
+
+## Examples
+
+### One-shot commands
+
+```bash
+# send all servos home
+nova-control --port /dev/ttyACM0 home
+
+# move the head forward and look up
+nova-control --port /dev/ttyACM0 shift-to 110
+nova-control --port /dev/ttyACM0 pitch-to 130
+
+# rotate the body 30° clockwise from centre
+nova-control --port /dev/ttyACM0 rotate-to 120
+
+# move head and body simultaneously in one packet
+nova-control --port /dev/ttyACM0 move --shift-to 100 --rotate-to 120
+
+# check the current state
+nova-control --port /dev/ttyACM0 state
+```
+
+---
+
+### Motion script
+
+A script file runs a complete motion sequence from a file, pausing between moves with `wait`:
+
+```
+# greeting.nova — wave the head left and right
+home
+wait 500
+shift-to 110
+wait 400
+shift-to 70
+wait 400
+shift-to 110
+wait 400
+home
+```
+
+Run it:
+
+```bash
+nova-control --port /dev/ttyACM0 --script greeting.nova
+```
+
+Pipe a script from stdin:
+
+```bash
+printf 'home\nwait 500\nshift-to 110\nwait 1000\nhome\n' \
+  | nova-control --port /dev/ttyACM0 --script -
+```
+
+---
+
+### Interactive REPL session
+
+```
+$ nova-control --port /dev/ttyACM0 shell
+NOVA interactive shell — type "help [command]" for help, "exit" to quit
+nova-control> home
+nova-control> wait 500
+nova-control> shift-to 100
+nova-control> roll-to 60
+nova-control> state
+{"s1":100,"s2":60,"s3":110,"s4":90,"s5":95}
+nova-control> home
+nova-control> exit
+```
+
+---
+
+## Exit codes
+
+| code | meaning |
+| --- | --- |
+| `0` | success |
+| `1` | unspecified runtime error (e.g. serial port refused to open) |
+| `2` | bad arguments or missing required option |
+
+---
+
+## License
+
+[MIT License](../../LICENSE.md) © Andreas Rozek

package/dist/nova-control-command.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import { fileURLToPath as e } from "node:url";
+import { Command as t } from "commander";
+import { openNova as n } from "nova-control-node";
+import r from "node:readline";
+import i from "node:fs/promises";
+//#region src/CommandTokenizer.ts
+function a(e) {
+	let t = [], n = "", r = 0;
+	for (; r < e.length;) {
+		let i = e[r];
+		switch (!0) {
+			case i === " " || i === "	":
+				n.length > 0 && (t.push(n), n = ""), r++;
+				break;
+			case i === "'":
+				for (r++; r < e.length && e[r] !== "'";) n += e[r], r++;
+				r++;
+				break;
+			case i === "\"":
+				for (r++; r < e.length && e[r] !== "\"";) if (e[r] === "\\" && r + 1 < e.length) {
+					let t = e[r + 1];
+					n += t === "\"" || t === "\\" ? t : "\\" + t, r += 2;
+				} else n += e[r], r++;
+				r++;
+				break;
+			case i === "#" && n.length === 0:
+				r = e.length;
+				break;
+			default: i === "\\" && r + 1 < e.length ? (n += e[r + 1], r += 2) : (n += i, r++);
+		}
+	}
+	return n.length > 0 && t.push(n), t;
+}
+//#endregion
+//#region src/REPL.ts
+async function o(e, t) {
+	let n = process.stdin.isTTY, i = n ? `\x1b[1m${e}>\x1b[0m ` : `${e}> `, o = r.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+		terminal: n,
+		prompt: i
+	});
+	n && (process.stdout.write("NOVA interactive shell — type \"help [command]\" for help, \"exit\" to quit\n"), o.prompt());
+	for await (let r of o) {
+		let i = r.trim();
+		if (i === "" || i.startsWith("#")) {
+			n && o.prompt();
+			continue;
+		}
+		if (i === "exit" || i === "quit") break;
+		let s = a(i);
+		if (s.length === 0) {
+			n && o.prompt();
+			continue;
+		}
+		try {
+			await t(s);
+		} catch (t) {
+			process.stderr.write(`${e}: ${t.message}\n`);
+		}
+		n && o.prompt();
+	}
+	o.close();
+}
+//#endregion
+//#region src/ScriptRunner.ts
+async function s(e, t, n) {
+	let o;
+	if (t === "-") o = process.stdin;
+	else try {
+		o = (await i.open(t)).createReadStream();
+	} catch {
+		return process.stderr.write(`nova-control: cannot open script '${t}'\n`), 2;
+	}
+	let s = r.createInterface({
+		input: o,
+		terminal: !1
+	}), l = 0;
+	for await (let t of s) {
+		let r = t.trim();
+		if (r === "" || r.startsWith("#")) continue;
+		let i = a(r);
+		if (i.length === 0) continue;
+		let o = 0;
+		try {
+			o = await n(i);
+		} catch (e) {
+			o = 1, process.stderr.write(`nova-control: ${e.message}\n`);
+		}
+		if (o !== 0) switch (l = o, e) {
+			case "stop": return s.close(), o;
+			case "continue": break;
+			case "ask":
+				if (!await c()) return s.close(), o;
+				break;
+		}
+	}
+	return s.close(), l;
+}
+async function c() {
+	return process.stdin.isTTY ? new Promise((e) => {
+		let t = r.createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		t.question("error — continue? [y/N] ", (n) => {
+			t.close(), e(n.trim().toLowerCase() === "y");
+		});
+	}) : !1;
+}
+//#endregion
+//#region src/nova-control-command.ts
+var l = {
+	OK: 0,
+	GeneralError: 1,
+	UsageError: 2
+}, u = class extends Error {
+	ExitCode;
+	constructor(e, t = l.GeneralError) {
+		super(e), this.name = "NovaCommandError", this.ExitCode = t;
+	}
+}, d = "nova-control", f, p = 9600, m = "stop", h;
+async function g() {
+	if (f == null) throw new u("--port is required — specify the serial port (e.g. /dev/ttyACM0 or COM3)", l.UsageError);
+	return h ??= await n(f, p), h;
+}
+function _() {
+	h != null && (h.destroy(), h = void 0);
+}
+function v(e, t = 9600, n = "stop") {
+	f = e, p = t, m = n;
+}
+function y() {
+	_(), f = void 0, p = 9600, m = "stop";
+}
+function b(e) {
+	e.exitOverride(), e.configureOutput({ writeErr: () => {} });
+	for (let t of e.commands) b(t);
+}
+function x(e = !1) {
+	let n = new t(d);
+	return n.description("NOVA robot arm CLI").allowUnknownOption(!1).configureOutput({ writeErr: () => {} }), e || (n.option("--port <path>", "serial port path (e.g. /dev/ttyACM0 on Linux/macOS, COM3 on Windows)").option("--baud <rate>", "baud rate (default: 9600)", "9600").option("--on-error <mode>", "script error mode: stop | continue | ask (default: stop)"), n.hook("preAction", (e, t) => {
+		let n = t.optsWithGlobals();
+		f = n.port, p = Number(n.baud ?? "9600"), m = n.onError ?? "stop";
+	})), n.command("home").description("send all servos to their home positions").action(async () => {
+		await (await g()).home();
+	}), n.command("move").description("set one or more servo positions without interrupting the others").option("--shift-to <deg>", "shift head forward (>90°) or back (<90°) — s1").option("--roll-to <deg>", "roll head clockwise (>90°) or counter-clockwise (<90°) — s2").option("--pitch-to <deg>", "pitch head up (>110°) or down (<110°) — s3").option("--rotate-to <deg>", "rotate body around Z-axis — s4").option("--lift-to <deg>", "lift head on secondary axis, range 20°–150° — s5").action(async (e) => {
+		let t = {};
+		if (e.shiftTo != null && (t.s1 = Number(e.shiftTo)), e.rollTo != null && (t.s2 = Number(e.rollTo)), e.pitchTo != null && (t.s3 = Number(e.pitchTo)), e.rotateTo != null && (t.s4 = Number(e.rotateTo)), e.liftTo != null && (t.s5 = Number(e.liftTo)), Object.keys(t).length === 0) throw new u("move: specify at least one servo option (--shift-to, --roll-to, --pitch-to, --rotate-to, --lift-to)", l.UsageError);
+		let n = await g();
+		n.State = t, await n.sendServoState();
+	}), n.command("shift-to").description("shift head forward (>90°) or back (<90°) — s1").argument("<deg>", "target angle in degrees").action(async (e) => {
+		let t = await g();
+		t.State = { s1: Number(e) }, await t.sendServoState();
+	}), n.command("roll-to").description("roll head clockwise (>90°) or counter-clockwise (<90°) — s2").argument("<deg>", "target angle in degrees").action(async (e) => {
+		let t = await g();
+		t.State = { s2: Number(e) }, await t.sendServoState();
+	}), n.command("pitch-to").description("pitch head up (>110°) or down (<110°) — s3").argument("<deg>", "target angle in degrees").action(async (e) => {
+		let t = await g();
+		t.State = { s3: Number(e) }, await t.sendServoState();
+	}), n.command("rotate-to").description("rotate body around Z-axis — s4").argument("<deg>", "target angle in degrees").action(async (e) => {
+		let t = await g();
+		t.State = { s4: Number(e) }, await t.sendServoState();
+	}), n.command("lift-to").description("lift head on secondary axis, range 20°–150° — s5").argument("<deg>", "target angle in degrees").action(async (e) => {
+		let t = await g();
+		t.State = { s5: Number(e) }, await t.sendServoState();
+	}), n.command("wait").description("pause for <ms> milliseconds before the next command").argument("<ms>", "duration in milliseconds (non-negative number)").action(async (e) => {
+		let t = Number(e);
+		if (isNaN(t) || t < 0) throw new u(`wait: invalid duration '${e}' — expected a non-negative number`, l.UsageError);
+		await new Promise((e) => setTimeout(e, t));
+	}), n.command("state").description("print the current servo state as JSON").action(async () => {
+		let e = await g();
+		process.stdout.write(JSON.stringify(e.State) + "\n");
+	}), e || (n.command("shell").description("start an interactive REPL").action(async () => {
+		await o(d, (e) => S(e));
+	}), n.option("--script <file>", "run commands from a script file (use - for stdin)").action(async (e) => {
+		if (e.script != null) {
+			let t = await s(m, e.script, S);
+			process.exit(t);
+		} else process.stdout.write(n.helpInformation()), process.exit(l.OK);
+	}), n.addHelpCommand(!0)), n;
+}
+async function S(e) {
+	if (e.length === 0) return l.OK;
+	let t = x(!0);
+	b(t);
+	try {
+		return await t.parseAsync([
+			"node",
+			d,
+			...e
+		]), l.OK;
+	} catch (t) {
+		let n = t;
+		return n.code === "commander.help" || n.code === "commander.helpDisplayed" ? l.OK : n.code === "commander.unknownCommand" ? (process.stderr.write(`${d}: unknown command '${e[0]}' — try '${d} help'\n`), l.UsageError) : n.code === "commander.unknownOption" || n.code === "commander.missingArgument" || n.code === "commander.missingMandatoryOptionValue" ? (process.stderr.write(`${d}: ${n.message}\n`), l.UsageError) : t instanceof u ? (process.stderr.write(`${d}: ${t.message}\n`), t.ExitCode) : (process.stderr.write(`${d}: ${t.message ?? String(t)}\n`), l.GeneralError);
+	}
+}
+async function C() {
+	let e = x();
+	b(e);
+	try {
+		await e.parseAsync(process.argv);
+	} catch (t) {
+		let n = t;
+		(n.code === "commander.help" || n.code === "commander.helpDisplayed" || n.code === "commander.version") && process.exit(l.OK), (n.code === "commander.unknownCommand" || n.code === "commander.unknownOption" || n.code === "commander.missingArgument" || n.code === "commander.missingMandatoryOptionValue") && (process.stderr.write(`${d}: ${n.message}\n\n`), process.stderr.write(e.helpInformation()), process.exit(l.UsageError)), t instanceof u && (process.stderr.write(`${d}: ${t.message}\n`), process.exit(t.ExitCode)), process.stderr.write(`${d}: ${t.message ?? String(t)}\n`), process.exit(l.GeneralError);
+	} finally {
+		_();
+	}
+}
+process.argv[1] === e(import.meta.url) && C().catch((e) => {
+	process.stderr.write(`${d}: fatal: ${e.message ?? e}\n`), process.exit(l.GeneralError);
+});
+//#endregion
+export { y as _destroyForTests, v as _setupForTests, S as executeTokens };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "nova-control-command",
+  "description": "CLI for controlling a NOVA DIY Artificial Intelligence Robot by Creoqode",
+  "version": "0.0.1",
+  "type": "module",
+  "keywords": [
+    "nova",
+    "creoqode",
+    "robot",
+    "cli"
+  ],
+  "author": "Andreas Rozek",
+  "homepage": "https://github.com/rozek/nova-control#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rozek/nova-control.git",
+    "directory": "packages/nova-control-command"
+  },
+  "bugs": {
+    "url": "https://github.com/rozek/nova-control/issues"
+  },
+  "license": "MIT",
+  "bin": {
+    "nova-control": "./dist/nova-control-command.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "commander": "^12.0.0",
+    "nova-control-node": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
+}