hello-lights 0.3.0 → 0.3.2

package/.github/workflows/ci.yml

@@ -0,0 +1,116 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libusb-1.0-0-dev libudev-dev
+
+      - run: npm ci
+
+      - run: npm run lint
+
+      - run: npm run coverage
+
+      - run: npm run coverage:text
+
+      - run: npm run build:web
+
+      - name: Upload web artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: web
+
+  deploy:
+    needs: build
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4
+
+  publish:
+    needs: build
+    if: github.event_name == 'push' && !contains(github.event.head_commit.message, '[skip ci]')
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libusb-1.0-0-dev libudev-dev
+
+      - run: npm ci
+
+      - run: npm install -g npm@latest
+
+      - name: Determine version bump type
+        id: bump
+        run: |
+          COMMIT_MSG="${{ github.event.head_commit.message }}"
+          if echo "$COMMIT_MSG" | grep -qiE '\[major\]|BREAKING CHANGE'; then
+            echo "type=major" >> $GITHUB_OUTPUT
+          elif echo "$COMMIT_MSG" | grep -qi '\[minor\]'; then
+            echo "type=minor" >> $GITHUB_OUTPUT
+          else
+            echo "type=patch" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Bump version
+        id: version
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          npm version ${{ steps.bump.outputs.type }} -m "v%s [skip ci]"
+          echo "new_version=$(node -p 'require("./package.json").version')" >> $GITHUB_OUTPUT
+
+      - name: Push version bump
+        run: git push --follow-tags
+
+      - name: Publish to npm
+        run: npm publish --provenance
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version.outputs.new_version }}
+          generate_release_notes: true

package/README.md

@@ -1,9 +1,7 @@
 # hello-lights
 
 [![npm](https://img.shields.io/npm/v/hello-lights.svg)](https://www.npmjs.com/package/hello-lights)
-[![Build Status](https://travis-ci.org/jordao76/hello-lights.svg)](https://travis-ci.org/jordao76/hello-lights)
-[![Dependency Status](https://david-dm.org/jordao76/hello-lights.svg)](https://david-dm.org/jordao76/hello-lights)
-[![devDependency Status](https://david-dm.org/jordao76/hello-lights/dev-status.svg)](https://david-dm.org/jordao76/hello-lights#info=devDependencies)
+[![CI](https://github.com/jordao76/hello-lights/actions/workflows/ci.yml/badge.svg)](https://github.com/jordao76/hello-lights/actions/workflows/ci.yml)
 [![License](http://img.shields.io/:license-mit-blue.svg)](https://github.com/jordao76/hello-lights/blob/master/LICENSE.md)
 
 > Commands to control a traffic light
@@ -39,6 +37,52 @@ Check out the available commands [here](https://jordao76.github.io/hello-lights)
 
 For the documentation look [here](https://jordao76.github.io/hello-lights/doc/index.html).
 
+## Development
+
+Install dependencies:
+
+```sh
+$ npm install
+```
+
+### npm scripts
+
+| Script | Description |
+|---|---|
+| `npm test` | Run all tests (generates PEG parsers first) |
+| `npm run lint` | Lint source and test files |
+| `npm run coverage` | Run tests with coverage instrumentation |
+| `npm run coverage:text` | Print a text coverage summary to the terminal |
+| `npm run coverage:open` | Generate and open an HTML coverage report |
+| `npm run build:doc` | Generate JSDoc documentation into `web/doc/` |
+| `npm run build:web` | Build all web assets (PEG parsers, browserify bundle, docs) |
+| `npm run doc` | Build and open the documentation in the browser |
+| `npm run web` | Build and open the browser demo |
+| `npm run mocha-grep <pattern>` | Run only tests matching a pattern |
+| `npm run cli` | Run the CLI locally |
+
+### CLI
+
+Run the CLI locally with `npm run cli`:
+
+```sh
+$ npm run cli -- exec bounce 300       # execute a command
+$ npm run cli -- exec-file ./cmds.clj  # execute commands from a file
+$ npm run cli -- repl                  # start an interactive REPL
+$ npm run cli -- serve                 # start the HTTP server on port 9000
+$ 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.
+
+## CI
+
+The CI workflow runs on every push and pull request to `master`. It has three jobs:
+
+- **Build** -- lints, runs tests with coverage, and builds all web assets.
+- **Deploy** -- on push to `master`, deploys the `web/` directory to GitHub Pages.
+- **Publish** -- on push to `master`, bumps the package version, publishes to npm with provenance via trusted publishing, and creates a GitHub Release. The version bump type is determined from the commit message: `[major]` or `BREAKING CHANGE` for major, `[minor]` for minor, and patch by default.
+
 ## License
 
 Licensed under the [MIT license](https://github.com/jordao76/hello-lights/blob/master/LICENSE.md).

package/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+require('./lib/cli').parse();
+

package/lib/cli/commander-options.js

@@ -0,0 +1,127 @@
+const chalk = require('chalk');
+const path = require('path');
+const {Commander} = require('..');
+const {MetaFormatter, CodeFormatter} = require('..').commands;
+
+/////////////////////////////////////////////////////////////////
+
+const logger = {
+  log: (...args) => {
+    console.log(chalk.gray(...args));
+  },
+  error: (...args) => {
+    console.error(chalk.red(...args));
+  }
+};
+
+/////////////////////////////////////////////////////////////////
+
+class ChalkCodeFormatter extends CodeFormatter {
+
+  formatCommand(text) {
+    return chalk.blue(text);
+  }
+
+  formatIdentifier(text) {
+    if (['red', 'yellow', 'green'].indexOf(text) >= 0) return chalk[text](text);
+    return chalk.blue(text);
+  }
+
+  formatVariable(text) {
+    return chalk.green(text);
+  }
+
+  formatNumber(text) {
+    return chalk.magenta(text);
+  }
+
+  formatString(text) {
+    return chalk.cyan(text);
+  }
+
+  formatComment(text) {
+    return chalk.gray(text);
+  }
+
+}
+
+class ChalkMetaFormatter extends MetaFormatter {
+
+  constructor() {
+    super(new ChalkCodeFormatter());
+  }
+
+  formatName(name) {
+    return chalk.yellow(name);
+  }
+
+  formatParam(param) {
+    return chalk.cyan(super.formatParam(param));
+  }
+
+  formatReturn($return) {
+    return chalk.magenta(super.formatReturn($return));
+  }
+
+  formatInlineCode(code) {
+    return chalk.cyan(`${code.trim()}`);
+  }
+
+}
+
+/////////////////////////////////////////////////////////////////
+
+function resolveDeviceManager(options) {
+  const clewareDevicePath = '../devices/cleware-switch1';
+  let devicePath;
+  if (options.devicePath) {
+    devicePath = path.resolve(options.devicePath);
+  } else {
+    // for now, it is always the case that: options.deviceType === 'cleware'
+    devicePath = clewareDevicePath;
+  }
+  const {Manager} = require(devicePath);
+  return Manager;
+}
+
+/////////////////////////////////////////////////////////////////
+
+function resolveCommander(options) {
+  return Commander[options.selector]({
+    logger,
+    formatter: new ChalkMetaFormatter(),
+    manager: resolveDeviceManager(options),
+    serialNum: options.serialNum
+  });
+}
+
+/////////////////////////////////////////////////////////////////
+
+function define(yargs) {
+  yargs
+    .option('device-type', {
+      alias: 'd',
+      describe: 'device type to use',
+      choices: ['cleware'],
+      default: 'cleware',
+      hidden: true }) // un-hide when more than one option exists
+    .option('device-path', {
+      alias: 'p',
+      describe: 'device type path to use, overrides --device',
+      normalize: true,
+      hidden: true }) // hide advanced option
+    .option('serial-num', {
+      alias: 'n',
+      describe: 'serial number of device to use (only for "single" selector)' })
+    .option('selector', {
+      alias: 's',
+      describe: 'selector type to use',
+      choices: ['single', 'multi'],
+      default: 'single' });
+}
+
+/////////////////////////////////////////////////////////////////
+
+module.exports = {define, resolveCommander};
+
+/////////////////////////////////////////////////////////////////

package/lib/cli/exec-command.js

@@ -0,0 +1,42 @@
+/////////////////////////////////////////////////////////////////
+
+const commanderOptions = require('./commander-options');
+
+/////////////////////////////////////////////////////////////////
+
+async function exec(options, cmd, cdr = []) {
+  let commander = commanderOptions.resolveCommander(options);
+  cdr.unshift(cmd);
+  let command = cdr.join(' ');
+  await commander.run(command);
+  commander.close();
+}
+
+/////////////////////////////////////////////////////////////////
+
+const commandSpec = {
+
+  command: 'exec <cmd>',
+  describe: 'executes a command',
+
+  builder: yargs =>
+    yargs.positional('cmd', { describe: 'command to execute' }),
+
+  handler: argv =>
+    exec(argv, argv.cmd, argv._.slice(1)) // argv._ includes 'exec' at index 0
+
+};
+
+/////////////////////////////////////////////////////////////////
+
+function define(yargs) {
+  yargs
+    .command(commandSpec)
+    .example('$0 exec bounce 300', '# executes the `bounce 300` command');
+};
+
+/////////////////////////////////////////////////////////////////
+
+module.exports = {define};
+
+/////////////////////////////////////////////////////////////////

package/lib/cli/exec-file-command.js

@@ -0,0 +1,40 @@
+/////////////////////////////////////////////////////////////////
+
+const commanderOptions = require('./commander-options');
+
+/////////////////////////////////////////////////////////////////
+
+async function execFile(options, filePath) {
+  let commander = commanderOptions.resolveCommander(options);
+  await commander.runFile(filePath);
+  commander.close();
+}
+
+/////////////////////////////////////////////////////////////////
+
+const commandSpec = {
+
+  command: 'exec-file <file-path>',
+  describe: 'executes commands in a file',
+
+  builder: yargs =>
+    yargs.positional('file-path', { describe: 'file to execute' }),
+
+  handler: argv =>
+    execFile(argv, argv.filePath)
+
+};
+
+/////////////////////////////////////////////////////////////////
+
+function define(yargs) {
+  yargs
+    .command(commandSpec)
+    .example('$0 exec-file ./my-file.clj', '# executes the file');
+};
+
+/////////////////////////////////////////////////////////////////
+
+module.exports = {define};
+
+/////////////////////////////////////////////////////////////////

package/lib/cli/index.js

@@ -0,0 +1 @@
+module.exports = require('./yargs');

package/lib/cli/repl-command.js

@@ -0,0 +1,127 @@
+/////////////////////////////////////////////////////////////////
+
+const repl = require('repl');
+
+/////////////////////////////////////////////////////////////////
+
+class CommanderRepl {
+
+  constructor(commander) {
+    this.commander = commander;
+    this.multiline = false;
+    this.logger = this.commander.logger;
+    this.manager = this.commander.manager;
+  }
+
+  formatCommandNames() {
+    let names = this.commander.commandNames;
+    let parts = ['  '];
+    names.forEach((name, i) => {
+      parts.push(`  ${name}`);
+      if ((i + 1) % 8 === 0) parts.push('\n  ');
+    });
+    return parts.join('');
+  }
+
+  help(commandName) {
+    if (commandName === undefined) {
+      this.logger.log([
+        `Commands for the traffic light`,
+        `> help`,
+        `> help [command name]`,
+        `> check device` + (this.supportsNewDevice() ? '\n> new device' : ''),
+        `> exit | quit`,
+        `> [command]`,
+        `> { [... multi line command] }`,
+        `  available commands:`,
+        this.formatCommandNames()
+      ].join('\n'));
+    } else {
+      this.commander.help(commandName);
+    }
+  }
+
+  execute(text, context, filename, callback) {
+    text = text.trim();
+    let match;
+    if (!text) {
+    } else if (text === 'cancel') {
+      this.commander.cancel();
+    } else if (text === 'help') {
+      this.help();
+    } else if (match = text.match(/^help\s+(.+)/)) { // eslint-disable-line no-cond-assign
+      this.help(match[1]);
+    } else if (text === 'exit' || text === 'quit') {
+      this.commander.cancel();
+      this.commander.close();
+      this.logger.log('Bye');
+      process.exit(0);
+    } else if (text === 'check device') {
+      this.commander.logInfo();
+    } else if (this.supportsNewDevice() && text === 'new device') {
+      this.newDevice();
+    } else if (text.startsWith('{')) {
+      this.multiline = true;
+      return this.execute(text.replace('{', ''), context, filename, callback);
+    } else if (this.multiline && text.endsWith('}')) {
+      this.multiline = false;
+      this.commander.run(text.replace('}', ''));
+    } else if (this.multiline) {
+      return callback(new repl.Recoverable());
+    } else {
+      this.commander.run(text);
+    }
+    return callback();
+  }
+
+  launch() {
+    this.help();
+    let server = repl.start({
+      prompt: '> ',
+      eval: (...args) => this.execute(...args)
+    });
+    server.on('exit', () => process.exit(0));
+  }
+
+  supportsNewDevice() {
+    return !!this.manager.newDevice;
+  }
+  newDevice() {
+    this.manager.newDevice();
+  }
+
+}
+
+/////////////////////////////////////////////////////////////////
+
+const commanderOptions = require('./commander-options');
+
+/////////////////////////////////////////////////////////////////
+
+function main(options) {
+  let commander = commanderOptions.resolveCommander(options);
+  let commanderRepl = new CommanderRepl(commander);
+  commanderRepl.launch();
+}
+
+/////////////////////////////////////////////////////////////////
+
+const commandSpec = {
+  command: 'repl',
+  describe: 'starts the REPL',
+  handler: main
+};
+
+/////////////////////////////////////////////////////////////////
+
+function define(yargs) {
+  yargs
+    .command(commandSpec)
+    .example('$0 repl', '# starts a REPL');
+};
+
+/////////////////////////////////////////////////////////////////
+
+module.exports = {define, CommanderRepl};
+
+/////////////////////////////////////////////////////////////////

package/lib/cli/serve/index.js

@@ -0,0 +1,72 @@
+/////////////////////////////////////////////////////////////////
+
+const path = require('path');
+const commanderOptions = require('../commander-options');
+
+/////////////////////////////////////////////////////////////////
+
+function createApp(commander) {
+  const express = require('express');
+  const app = express();
+
+  app.use(express.static(path.join(__dirname, 'public')));
+  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();
+    });
+  });
+
+  return app;
+}
+
+function serve(options) {
+  const commander = commanderOptions.resolveCommander(options);
+  const app = createApp(commander);
+  const server = app.listen(options.port, () => console.log(`Server listening on port ${options.port}`));
+  server.on('error', err => {
+    if (err.code === 'EADDRINUSE') {
+      console.error(`Error: port ${options.port} is already in use`);
+    } else {
+      console.error(`Error: ${err.message}`);
+    }
+    process.exit(1);
+  });
+}
+
+/////////////////////////////////////////////////////////////////
+
+const commandSpec = {
+
+  command: 'serve',
+  describe: 'starts the HTTP server for remote light control',
+
+  builder: yargs =>
+    yargs.option('port', {
+      alias: 'P',
+      describe: 'port to listen on',
+      default: 9000,
+      type: 'number'
+    }),
+
+  handler: argv => serve(argv)
+
+};
+
+/////////////////////////////////////////////////////////////////
+
+function define(yargs) {
+  yargs
+    .command(commandSpec)
+    .example('$0 serve', '# starts the server on port 9000')
+    .example('$0 serve --port 3000', '# starts the server on port 3000');
+}
+
+/////////////////////////////////////////////////////////////////
+
+module.exports = {define, createApp};
+
+/////////////////////////////////////////////////////////////////

package/lib/cli/serve/public/index.html

@@ -0,0 +1,42 @@
+<!doctype html>
+<html>
+
+<head>
+  <meta charset="utf-8">
+  <title>Hello Lights</title>
+  <link rel="stylesheet" href="style.css">
+  <script src="main.js"></script>
+</head>
+
+<body>
+
+  <div class="container">
+
+    <div class="header">
+      <h2>hello-lights</h2>
+    </div>
+
+    <div class="command">
+      <div>
+        <textarea id="command" name="command" spellcheck="false"></textarea>
+      </div>
+    </div>
+
+    <div class="toolbar">
+      <div class="buttons">
+        <button id="run">Run</button>
+        <button id="cancel">Cancel</button>
+        <button id="reset">Reset</button>
+      </div>
+    </div>
+
+    <div class="footer">
+      By <a href="https://github.com/jordao76">Jordão</a>.
+      Check it out on <a href="https://github.com/jordao76/hello-lights">GitHub</a>.
+    </div>
+
+  </div>
+
+</body>
+
+</html>