hello-lights 0.3.4 → 0.3.6

package/README.md

@@ -10,13 +10,37 @@ Works with a [Cleware USB traffic light](http://www.cleware.info/data/usbtischam
 
 ## Install
 
+### As a CLI (global)
+
+```sh
+$ npm install -g hello-lights
+```
+
+### As a library
+
 ```sh
 $ npm install hello-lights --save
 ```
 
 ## Usage
 
-Issue commands to control a connected traffic light:
+### CLI
+
+Install globally and run `hello-lights` from the command line:
+
+```sh
+$ hello-lights exec bounce 300          # execute a command
+$ hello-lights exec-file ./cmds.clj     # execute commands from a file
+$ hello-lights repl                     # start an interactive REPL
+$ hello-lights serve                    # start the HTTP server on port 9000
+$ hello-lights serve --port 3000        # start the HTTP server on a custom port
+```
+
+Use `--help` for the full list of options, including `--serial-num` to target a specific device and `--selector multi` to control multiple traffic lights at once.
+
+### Library
+
+Use `hello-lights` as a library in your Node.js project:
 
 ```js
 const {Commander} = require('hello-lights');
@@ -75,6 +99,79 @@ $ npm run cli -- serve --port 3000     # start the HTTP server on a custom port
 
 Use `--help` for the full list of options, including `--serial-num` to target a specific device and `--selector multi` to control multiple traffic lights at once.
 
+## HTTP Server REST API
+
+The `serve` command starts an HTTP server that exposes the Commander interface as a REST API. By default it listens on port 9000.
+
+| Endpoint | Method | Body | Response |
+|---|---|---|---|
+| `/run` | POST | Command string (plain text) | 202 Accepted |
+| `/run?reset=true` | POST | Command string (plain text) | 202 Accepted (resets lights first) |
+| `/cancel` | POST | — | 200 OK |
+| `/definitions` | POST | Definition string (plain text) | 202 Accepted |
+| `/commands` | GET | — | 200 + JSON array of command names |
+| `/commands/:name` | GET | — | 200 + help text (`text/x-ansi`) or 404 |
+| `/info` | GET | — | 200 + JSON array of `{ serialNum, status }` |
+
+Examples:
+
+```sh
+$ curl -X POST http://localhost:9000/run -d 'blink 3 green 300'
+$ curl -X POST http://localhost:9000/run?reset=true -d 'twinkle red 400'
+$ curl -X POST http://localhost:9000/cancel
+$ curl -X POST http://localhost:9000/definitions -d '(def foo (blink 1 green 300))'
+$ curl http://localhost:9000/commands
+$ curl http://localhost:9000/commands/turn
+$ curl http://localhost:9000/info
+```
+
+The server also serves a browser demo at the root URL (`/`).
+
+## Running as a Linux Service
+
+You can set up `hello-lights serve` to run automatically as a systemd user service on Linux.
+
+Create the service file at `~/.config/systemd/user/hello-lights.service`:
+
+```ini
+[Unit]
+Description=Hello Lights Server
+After=network.target
+
+[Service]
+Type=simple
+Environment=PATH=/path/to/node/bin:/usr/bin:/bin
+ExecStart=/path/to/node/bin/hello-lights serve
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+Replace `/path/to/node/bin` with the directory containing your `node` and `hello-lights` binaries (e.g. `~/.nvm/versions/node/v24.13.1/bin`). The `Environment=PATH=...` line is needed because systemd doesn't load your shell profile, so tools installed via nvm won't be found otherwise.
+
+Then enable and start the service:
+
+```sh
+$ systemctl --user daemon-reload
+$ systemctl --user enable hello-lights   # start automatically on login
+$ systemctl --user start hello-lights    # start now
+```
+
+To start the service on boot (without needing to log in), enable lingering for your user:
+
+```sh
+$ sudo loginctl enable-linger $USER
+```
+
+Check status and logs:
+
+```sh
+$ systemctl --user status hello-lights
+$ journalctl --user -u hello-lights -f   # follow logs
+```
+
 ## CI
 
 The CI workflow runs on every push and pull request to `master`. It has three jobs:

package/lib/cli/serve/index.js

@@ -10,14 +10,44 @@ function createApp(commander) {
   const app = express();
 
   app.use(express.static(path.join(__dirname, 'public')));
+  app.use(express.text({type: '*/*'}));
+
   app.post('/run', (req, res) => {
-    let commandStr = '';
-    req.on('data', data => commandStr += data);
-    req.on('end', () => {
-      commander.run(commandStr);
-      res.statusCode = 202; // accepted
-      res.end();
-    });
+    let reset = req.query.reset === 'true';
+    commander.run(req.body || '', reset);
+    res.sendStatus(202);
+  });
+
+  app.post('/cancel', (req, res) => {
+    commander.cancel();
+    res.sendStatus(200);
+  });
+
+  app.post('/definitions', (req, res) => {
+    commander.runDefinitions(req.body || '');
+    res.sendStatus(202);
+  });
+
+  app.get('/commands', (req, res) => {
+    res.json(commander.commandNames);
+  });
+
+  app.get('/commands/:name', (req, res) => {
+    let command = commander.interpreter.lookup(req.params.name);
+    if (!command) {
+      res.status(404).send(`Command not found: "${req.params.name}"`);
+      return;
+    }
+    let helpText = commander.formatter.format(command.meta);
+    res.type('text/x-ansi').send(helpText);
+  });
+
+  app.get('/info', (req, res) => {
+    if (commander.manager) {
+      res.json(commander.manager.info());
+    } else {
+      res.json([]);
+    }
   });
 
   return app;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hello-lights",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Commands to control a traffic light",
   "main": "index.js",
   "bin": {