cli: Add command line interface to combine/split uhex files.

config/rollup.config.js

@@ -1,4 +1,5 @@
 import { resolve } from 'path';
+import builtins from 'builtin-modules';
 import sourceMaps from 'rollup-plugin-sourcemaps';
 import nodeResolve from '@rollup/plugin-node-resolve';
 import commonjs from '@rollup/plugin-commonjs';
@@ -28,7 +29,7 @@ const plugins = /** @type {Plugin[]} */ ([
   commonjs(),
   // Allow node_modules resolution.  Use 'external' to control
   // which external modules to include in the bundle
-  // https://github.com/rollup/rollup-plugin-node-resolve#usage
+  // https://github.com/rollup/plugins/blob/master/packages/node-resolve/
   nodeResolve(),
   sourceMaps(),
   babel({
@@ -99,4 +100,18 @@ const umdConfigMin = createUmdConfig({
   ],
 });
 
-export default [umdConfig, umdConfigMin];
+const cjsConfigCli = {
+  inlineDynamicImports: true,
+  external: [...external, ...Object.keys(pkg.dependencies), ...builtins],
+  input: resolve(dist, 'esm5', 'cli.js'),
+  output: {
+    banner: '#!/usr/bin/env node',
+    file: pkg.bin.uhex,
+    format: 'cjs',
+    name: pkg.config.umdName,
+    sourcemap: true,
+  },
+  plugins: [commonjs(), nodeResolve(), sourceMaps()],
+};
+
+export default [umdConfig, umdConfigMin, cjsConfigCli];

package.json

@@ -9,6 +9,9 @@
     "universal hex",
     "uh"
   ],
+  "bin": {
+    "uhex": "./dist/bundles/microbit-uh-cli.cjs.js"
+  },
   "main": "./dist/bundles/microbit-uh.umd.js",
   "mainMin": "./dist/bundles/microbit-uh.umd.min.js",
   "module": "./dist/esm5/index.js",
@@ -46,6 +49,9 @@
     "lint:fix": "npm run lint -- --fix",
     "docs": "typedoc --options config/typedoc.json"
   },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
   "devDependencies": {
     "@babel/core": "^7.23.9",
     "@babel/polyfill": "^7.12.1",
@@ -72,4 +78,4 @@
     "typedoc-neo-theme": "^1.1.1",
     "typescript": "^4.9.5"
   }
-}
+}

src/cli.ts

@@ -0,0 +1,185 @@
+import * as fs from 'fs';
+import { sep } from 'path';
+import * as process from 'process';
+import { Command } from 'commander';
+import * as microbitUh from './universal-hex';
+
+/**
+ * Combines two micro:bit Intel Hex files into a Universal Hex file.
+ *
+ * @param v1IntelHexPath - Path to the input micro:bit V1 Intel Hex file.
+ * @param v2IntelHexPath - Path to the input micro:bit V2 Intel Hex file.
+ * @param universalHexPath - Path to the output Universal Hex file.
+ *    If not specified, it will be saved in the current working directory.
+ * @param overwrite - Flag indicating whether to overwrite the output file
+ *    if it already exists.
+ */
+function combine(
+  v1IntelHexPath: string,
+  v2IntelHexPath: string,
+  universalHexPath: string | undefined,
+  overwrite: boolean | undefined
+) {
+  console.log('Combining Intel Hex files into Universal Hex');
+  console.log(`V1 Intel hex file: ${fs.realpathSync(v1IntelHexPath)}`);
+  console.log(`V2 Intel hex file: ${fs.realpathSync(v2IntelHexPath)}`);
+
+  if (!universalHexPath) {
+    // If the output path is not specified, save it in the current working directory
+    universalHexPath = `${process.cwd()}${sep}universal.hex`;
+  }
+  if (!overwrite && fs.existsSync(universalHexPath)) {
+    throw new Error(
+      `Output file already exists: ${fs.realpathSync(universalHexPath)}\n` +
+        '\tUse "--overwrite" flag to replace it.'
+    );
+  }
+
+  const v1IntelHexStr = fs.readFileSync(v1IntelHexPath, 'ascii');
+  const v2IntelHexStr = fs.readFileSync(v2IntelHexPath, 'ascii');
+  const universalHexStr = microbitUh.createUniversalHex([
+    {
+      hex: v1IntelHexStr,
+      boardId: microbitUh.microbitBoardId.V1,
+    },
+    {
+      hex: v2IntelHexStr,
+      boardId: microbitUh.microbitBoardId.V2,
+    },
+  ]);
+  fs.writeFileSync(universalHexPath, universalHexStr, { encoding: 'ascii' });
+
+  console.log(`Universal Hex saved to: ${fs.realpathSync(universalHexPath)}`);
+}
+
+/**
+ * Separates a Universal Hex file into two micro:bit Intel Hex files.
+ *
+ * @param universalHexPath - Path to the input Universal Hex file to split.
+ * @param v1IntelHexPath - Path to the output micro:bit V1 Intel Hex file to
+ *    save. If not specified, it will be saved in the current working directory.
+ * @param v2IntelHexPath - Path to the output micro:bit V2 Intel Hex file to
+ *    save. If not specified, it will be saved in the current working directory.
+ * @param overwrite - Flag indicating whether to overwrite the output files if
+ *   they already exist.
+ */
+function split(
+  universalHexPath: string,
+  v1IntelHexPath: string | undefined,
+  v2IntelHexPath: string | undefined,
+  overwrite: boolean | undefined
+) {
+  console.log(
+    `Splitting Universal Hex file: ${fs.realpathSync(universalHexPath)}`
+  );
+  if (!v1IntelHexPath) {
+    v1IntelHexPath = `${process.cwd()}${sep}v1-intel.hex`;
+  }
+  if (!v2IntelHexPath) {
+    v2IntelHexPath = `${process.cwd()}${sep}v2-intel.hex`;
+  }
+  if (!overwrite && fs.existsSync(v1IntelHexPath)) {
+    throw new Error(
+      `Output V1 file already exists: ${fs.realpathSync(v1IntelHexPath)}\n` +
+        '\tUse "--overwrite" flag to replace it.'
+    );
+  }
+  if (!overwrite && fs.existsSync(v2IntelHexPath)) {
+    throw new Error(
+      `Output V2 file already exists: ${fs.realpathSync(v2IntelHexPath)}\n` +
+        '\tUse "--overwrite" flag to replace it.'
+    );
+  }
+
+  const universalHexStr = fs.readFileSync(universalHexPath, 'ascii');
+  const separatedHexes = microbitUh.separateUniversalHex(universalHexStr);
+  if (separatedHexes.length !== 2) {
+    const boardIds = separatedHexes.map((hexObj) => hexObj.boardId);
+    const errorMsg =
+      'Universal Hex should contain only two micro:bit Intel Hexes.\n' +
+      `Found ${separatedHexes.length}: ${boardIds.join(', ')}`;
+    throw new Error(errorMsg);
+  }
+
+  let intelHexV1Str = '';
+  let intelHexV2Str = '';
+  separatedHexes.forEach((hexObj) => {
+    if (microbitUh.V1_BOARD_IDS.includes(hexObj.boardId)) {
+      intelHexV1Str = hexObj.hex;
+    } else if (microbitUh.V2_BOARD_IDS.includes(hexObj.boardId)) {
+      intelHexV2Str = hexObj.hex;
+    }
+  });
+  if (!intelHexV1Str || !intelHexV2Str) {
+    const boardIds = separatedHexes.map((hexObj) => hexObj.boardId);
+    const errorMsg =
+      'Universal Hex does not contain both micro:bit Intel Hexes.\n' +
+      `Found hexes for following board IDs: ${boardIds.join(', ')}`;
+    throw new Error(errorMsg);
+  }
+  fs.writeFileSync(v1IntelHexPath, intelHexV1Str, { encoding: 'ascii' });
+  fs.writeFileSync(v2IntelHexPath, intelHexV2Str, { encoding: 'ascii' });
+
+  console.log(`V1 Intel Hex saved to: ${fs.realpathSync(v1IntelHexPath)}`);
+  console.log(`V2 Intel Hex saved to: ${fs.realpathSync(v2IntelHexPath)}`);
+}
+
+/**
+ * Command line interface for the Universal Hex tool.
+ *
+ * @param args - Command line arguments.
+ * @returns Exit code.
+ */
+function cli(args: string[]): number {
+  const uHexCli = new Command();
+
+  uHexCli
+    .command('combine')
+    .requiredOption('-v1, --v1 <path>', 'Path to input micro:bit V1 Intel Hex')
+    .requiredOption('-v2, --v2 <path>', 'Path to input micro:bit V2 Intel Hex')
+    .option('-u, --universal <path>', 'Path to output Universal Hex')
+    .option('-o, --overwrite', 'Overwrite output file if it exists', false)
+    .action(
+      (options: {
+        v1: string;
+        v2: string;
+        universal?: string;
+        overwrite: boolean;
+      }) => {
+        try {
+          combine(options.v1, options.v2, options.universal, options.overwrite);
+        } catch (e) {
+          console.error('Error:', e.message);
+          process.exit(1);
+        }
+      }
+    );
+
+  uHexCli
+    .command('split')
+    .requiredOption('-u, --universal <path>', 'Path to input Universal Hex')
+    .option('-v1, --v1 <path>', 'Path to output micro:bit V1 Intel Hex')
+    .option('-v2, --v2 <path>', 'Path to output micro:bit V2 Intel Hex')
+    .option('-o, --overwrite', 'Overwrite output files if they exist', false)
+    .action(
+      (options: {
+        v1?: string;
+        v2?: string;
+        universal: string;
+        overwrite: boolean;
+      }) => {
+        try {
+          split(options.universal, options.v1, options.v2, options.overwrite);
+        } catch (e) {
+          console.error('Error:', e.message);
+          process.exit(1);
+        }
+      }
+    );
+
+  uHexCli.parse(args);
+
+  return 0;
+}
+
+process.exit(cli(process.argv));

src/universal-hex.ts

@@ -19,6 +19,7 @@
 import * as ihex from './ihex';
 
 const V1_BOARD_IDS = [0x9900, 0x9901];
+const V2_BOARD_IDS = [0x9903, 0x9904, 0x9905, 0x9906];
 const BLOCK_SIZE = 512;
 
 /**
@@ -490,6 +491,8 @@ function separateUniversalHex(universalHexStr: string): IndividualHex[] {
 }
 
 export {
+  V1_BOARD_IDS,
+  V2_BOARD_IDS,
   microbitBoardId,
   IndividualHex,
   iHexToCustomFormatBlocks,

tslint.json

@@ -16,6 +16,7 @@
     },
     "object-literal-sort-keys": false,
     "interface-over-type-literal": false,
+    "no-console": false,
     "no-bitwise": false
   },
   "jsRules": true