xs-dev 0.3.0 → 0.4.0

package/README.md

@@ -20,12 +20,16 @@ The Moddable SDK and associated dev board tooling is incredibly empowering for e
 
 - [X] Mac
 - [ ] Windows
-- [ ] Linux
+- [X] Linux
 
 ## Requirements
 
 [Node.js >= v12](https://nodejs.org/en/)
 
+**On Linux:**
+
+Setup commands rely on [`ssh-askpass`](https://packages.ubuntu.com/bionic/ssh-askpass) to prompt for permission when installing other tools and dependencies.
+
 ## Install
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xs-dev",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI for automating the setup and usage of Moddable XS tools",
   "types": "build/types/types.d.ts",
   "bin": {
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "axios": "^0.24.0",
-    "gluegun": "latest",
+    "gluegun": "^5.0.0",
     "serve-handler": "^6.1.3",
     "tar-fs": "^2.1.1",
     "unzip-stream": "^0.3.1"
@@ -70,5 +70,5 @@
     "snapupdate": "jest --updateSnapshot",
     "coverage": "jest --coverage"
   },
-  "readme": "# CLI for automating the setup and usage of [Moddable XS tools](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/Moddable%20SDK%20-%20Getting%20Started.md)\n\nThe Moddable SDK and associated dev board tooling is incredibly empowering for embedded JS hardware development, however the set up process can be tedious to follow when getting started. This project aims to streamline the install and environment configuration requirements across platforms in just a few commands.\n\n**This project is a work in progress and should be considered pre-1.0.**\n\n**Feature support:**\n\n- [X] [Moddable SDK install & setup](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/Moddable%20SDK%20-%20Getting%20Started.md)\n- [X] [ESP32 SDK setup](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/devices/esp32.md)\n- [X] [ESP8266 SDK setup](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/devices/esp8266.md)\n- [ ] [Gecko SDK setup](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/devices/gecko/GeckoBuild.md)\n- [ ] [QCA4020 SDK setup](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/devices/qca4020/README.md)\n- [X] Update Moddable SDK\n- [X] Project management, including dependencies\n- [X] WASM simulator\n- [ ] Raspberry Pi Pico\n\n**Platform support:**\n\n- [X] Mac\n- [ ] Windows\n- [ ] Linux\n\n## Requirements\n\n[Node.js >= v12](https://nodejs.org/en/)\n\n## Install\n\n```\nnpm install -g xs-dev\n```\n\n## Features\n\n### Moddable SDK setup / update / teardown\n\nThis process mostly automates the instructions provided by Moddable's \"Getting Started\" documentation with a few exceptions:\n\n- it will not install XCode, just ensures the command line tools are available\n- the `moddable` git repo is cloned into `~/.local/share` instead of a new/existing `~/Projects` directory\n- a symlink for `xsbug.app` is created in `/Applications` for easy access through Launchpad (on Mac)\n\nRun script for initial setup:\n\n```\nxs-dev setup\n```\n\nRun script for updating SDK:\n\n```\nxs-dev update\n```\n\nRemove all setup and environment changes with teardown command:\n\n```\nxs-dev teardown\n```\n\n### ESP32 SDK install / setup\n\nThis process automates the instructions for downloading and building the esp-idf SDK tooling. This tooling will be placed in the `~/.local/share/esp32` directory, which will be created if it doesn't exist.\n\nRun script for platform setup:\n\n```\nxs-dev setup --device=esp32\n```\n\nRun script to confirm the setup:\n\n```\nxs-dev run --example helloworld --device=esp32\n```\n\nFlags:\n\n- `device`: `esp8266` | `esp32` | [any of the allowed platform identifiers](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#arguments) (defaults to current OS platform)\n- `port`: path to port for connected device (defaults to: `UPLOAD_PORT` environment variable)\n\n### ESP8266 SDK install / setup\n\nThis process automates the instructions for downloading all the dependencies for the ESP8266 RTOS SDK. These dependencies will be placed in the `~/.local/share/esp` directory, which will be created if it doesn't exist.\n\nRun script for platform setup:\n\n```\nxs-dev setup --device=esp8266\n```\n\nRun script to confirm the setup:\n\n```\nxs-dev run --example helloworld --device=esp8266\n```\n\nFlags:\n\n- `device`: `esp8266` | `esp32` | [any of the allowed platform identifiers](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#arguments) (defaults to current OS platform)\n- `port`: path to port for connected device (defaults to: `UPLOAD_PORT` environment variable)\n\n### Wasm Simulator install / setup\n\nThis process automates the instructions for downloading all the dependencies for the [wasm simulator](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/devices/wasm.md) and building the Moddable tooling. These dependencies will be placed in `~/.local/share/wasm`, which will be created if it doesn't exist.\n\nRun script for platform setup:\n\n```\nxs-dev setup --device=wasm\n```\n\n_If there are issues building the Moddable wasm tools, please try running `eval $SHELL` or starting a new shell insance before running the setup script again._\n\n\nRun script to confirm the setup:\n\n```\nxs-dev run --example helloworld --device=wasm\n```\n\n### Run Moddable examples\n\nWhile it is still possible to run the Moddable example projects in the documented workflow:\n\n```\ncd $MODDABLE/examples/<example directory>\nmcconfig -d -m -p <platform here>\n```\n\nThis tool aims to simplify that process.\n\nList available examples:\n```\nxs-dev run --list-examples\n```\n\nRun an example (coming soon):\n```\nxs-dev run --example helloworld\n```\n\nFlags:\n\n- `device`: `esp8266` | `esp32` | [any of the allowed platform identifiers](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#arguments) (defaults to current OS platform)\n- `port`: path to port for connected device (defaults to: `UPLOAD_PORT` environment variable)\n\n## Project management\n\n### Start a project\n\n\n```\nxs-dev init my-project\n```\n\nCreates a `main.js` and base configured `manifest.json` for running in the simulator.\n\nFlags:\n\n- `typescript`: includes typings and creates `main.ts` (experimental)\n- `io`: includes [TC53 IO manifest](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/io/io.md)\n\n### Build and run a project\n\nIn the project directory:\n\n```\nxs-dev run\n```\n\nWhen not in the project directory:\n\n```\nxs-dev run path/to/project\n```\n\nFlags:\n\n- `device`: `esp8266` | `esp32` | [any of the allowed platform identifiers](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#arguments) (defaults to current OS platform)\n- `port`: path to port for connected device (defaults to: `UPLOAD_PORT` environment variable)\n\n### Add a Moddable module\n\n```\nxs-dev include network/wifi\n```\n\nOr select from available modules:\n\n```\nxs-dev include\n```\n\nUpdates the `manifest.json` with the path to the dependency.\n\n### Add a remote dependency (Coming soon)\n\n```\nxs-dev get dtex/j5e\n```\n\nAssumes the dependency is a GitHub repo, clones it to `~/.local/share`, creates an environment variable with the name of the repo, and updates the `manifest.json` with the path to that dependency.\n\nTo include a specific module for the installed dependency:\n\n```\nxs-dev include j5e/lib/led\n```\n\n### Remove a dependency\n\n```\nxs-dev remove network/wifi\n```\n\nUpdates the `manifest.json` to remove the dependency.\n\n## Development\n\nClone the project and install dependencies. We're using [pnpm](https://pnpm.io/) and [volta](https://volta.sh/) to manage packages and Node.\n\n```\ngit clone https://github.com/HipsterBrown/xs-dev.git\ncd xs-dev\npnpm install\n```\n\nLink dev version of CLI using `pnpm`, which will override any other globally installed version:\n\n```\npnpm link --global\npnpm link --global xs-dev\n```\n\nOr create an alias to clearly denote the local version of the CLI:\n\n```\nalias local-xs-dev=$PWD/bin/xs-dev\n```\n\nTo maintain the alias between shell sessions, for example I use zsh:\n\n```\necho \"alias local-xs-dev=$PWD/bin/xs-dev\" >> ~/.zshrc\n```\n"
+  "readme": "# CLI for automating the setup and usage of [Moddable XS tools](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/Moddable%20SDK%20-%20Getting%20Started.md)\n\nThe Moddable SDK and associated dev board tooling is incredibly empowering for embedded JS hardware development, however the set up process can be tedious to follow when getting started. This project aims to streamline the install and environment configuration requirements across platforms in just a few commands.\n\n**This project is a work in progress and should be considered pre-1.0.**\n\n**Feature support:**\n\n- [X] [Moddable SDK install & setup](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/Moddable%20SDK%20-%20Getting%20Started.md)\n- [X] [ESP32 SDK setup](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/devices/esp32.md)\n- [X] [ESP8266 SDK setup](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/devices/esp8266.md)\n- [ ] [Gecko SDK setup](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/devices/gecko/GeckoBuild.md)\n- [ ] [QCA4020 SDK setup](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/devices/qca4020/README.md)\n- [X] Update Moddable SDK\n- [X] Project management, including dependencies\n- [X] WASM simulator\n- [ ] Raspberry Pi Pico\n\n**Platform support:**\n\n- [X] Mac\n- [ ] Windows\n- [X] Linux\n\n## Requirements\n\n[Node.js >= v12](https://nodejs.org/en/)\n\n**On Linux:**\n\nSetup commands rely on [`ssh-askpass`](https://packages.ubuntu.com/bionic/ssh-askpass) to prompt for permission when installing other tools and dependencies.\n\n## Install\n\n```\nnpm install -g xs-dev\n```\n\n## Features\n\n### Moddable SDK setup / update / teardown\n\nThis process mostly automates the instructions provided by Moddable's \"Getting Started\" documentation with a few exceptions:\n\n- it will not install XCode, just ensures the command line tools are available\n- the `moddable` git repo is cloned into `~/.local/share` instead of a new/existing `~/Projects` directory\n- a symlink for `xsbug.app` is created in `/Applications` for easy access through Launchpad (on Mac)\n\nRun script for initial setup:\n\n```\nxs-dev setup\n```\n\nRun script for updating SDK:\n\n```\nxs-dev update\n```\n\nRemove all setup and environment changes with teardown command:\n\n```\nxs-dev teardown\n```\n\n### ESP32 SDK install / setup\n\nThis process automates the instructions for downloading and building the esp-idf SDK tooling. This tooling will be placed in the `~/.local/share/esp32` directory, which will be created if it doesn't exist.\n\nRun script for platform setup:\n\n```\nxs-dev setup --device=esp32\n```\n\nRun script to confirm the setup:\n\n```\nxs-dev run --example helloworld --device=esp32\n```\n\nFlags:\n\n- `device`: `esp8266` | `esp32` | [any of the allowed platform identifiers](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#arguments) (defaults to current OS platform)\n- `port`: path to port for connected device (defaults to: `UPLOAD_PORT` environment variable)\n\n### ESP8266 SDK install / setup\n\nThis process automates the instructions for downloading all the dependencies for the ESP8266 RTOS SDK. These dependencies will be placed in the `~/.local/share/esp` directory, which will be created if it doesn't exist.\n\nRun script for platform setup:\n\n```\nxs-dev setup --device=esp8266\n```\n\nRun script to confirm the setup:\n\n```\nxs-dev run --example helloworld --device=esp8266\n```\n\nFlags:\n\n- `device`: `esp8266` | `esp32` | [any of the allowed platform identifiers](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#arguments) (defaults to current OS platform)\n- `port`: path to port for connected device (defaults to: `UPLOAD_PORT` environment variable)\n\n### Wasm Simulator install / setup\n\nThis process automates the instructions for downloading all the dependencies for the [wasm simulator](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/devices/wasm.md) and building the Moddable tooling. These dependencies will be placed in `~/.local/share/wasm`, which will be created if it doesn't exist.\n\nRun script for platform setup:\n\n```\nxs-dev setup --device=wasm\n```\n\n_If there are issues building the Moddable wasm tools, please try running `eval $SHELL` or starting a new shell insance before running the setup script again._\n\n\nRun script to confirm the setup:\n\n```\nxs-dev run --example helloworld --device=wasm\n```\n\n### Run Moddable examples\n\nWhile it is still possible to run the Moddable example projects in the documented workflow:\n\n```\ncd $MODDABLE/examples/<example directory>\nmcconfig -d -m -p <platform here>\n```\n\nThis tool aims to simplify that process.\n\nList available examples:\n```\nxs-dev run --list-examples\n```\n\nRun an example (coming soon):\n```\nxs-dev run --example helloworld\n```\n\nFlags:\n\n- `device`: `esp8266` | `esp32` | [any of the allowed platform identifiers](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#arguments) (defaults to current OS platform)\n- `port`: path to port for connected device (defaults to: `UPLOAD_PORT` environment variable)\n\n## Project management\n\n### Start a project\n\n\n```\nxs-dev init my-project\n```\n\nCreates a `main.js` and base configured `manifest.json` for running in the simulator.\n\nFlags:\n\n- `typescript`: includes typings and creates `main.ts` (experimental)\n- `io`: includes [TC53 IO manifest](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/io/io.md)\n\n### Build and run a project\n\nIn the project directory:\n\n```\nxs-dev run\n```\n\nWhen not in the project directory:\n\n```\nxs-dev run path/to/project\n```\n\nFlags:\n\n- `device`: `esp8266` | `esp32` | [any of the allowed platform identifiers](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#arguments) (defaults to current OS platform)\n- `port`: path to port for connected device (defaults to: `UPLOAD_PORT` environment variable)\n\n### Add a Moddable module\n\n```\nxs-dev include network/wifi\n```\n\nOr select from available modules:\n\n```\nxs-dev include\n```\n\nUpdates the `manifest.json` with the path to the dependency.\n\n### Add a remote dependency (Coming soon)\n\n```\nxs-dev get dtex/j5e\n```\n\nAssumes the dependency is a GitHub repo, clones it to `~/.local/share`, creates an environment variable with the name of the repo, and updates the `manifest.json` with the path to that dependency.\n\nTo include a specific module for the installed dependency:\n\n```\nxs-dev include j5e/lib/led\n```\n\n### Remove a dependency\n\n```\nxs-dev remove network/wifi\n```\n\nUpdates the `manifest.json` to remove the dependency.\n\n## Development\n\nClone the project and install dependencies. We're using [pnpm](https://pnpm.io/) and [volta](https://volta.sh/) to manage packages and Node.\n\n```\ngit clone https://github.com/HipsterBrown/xs-dev.git\ncd xs-dev\npnpm install\n```\n\nLink dev version of CLI using `pnpm`, which will override any other globally installed version:\n\n```\npnpm link --global\npnpm link --global xs-dev\n```\n\nOr create an alias to clearly denote the local version of the CLI:\n\n```\nalias local-xs-dev=$PWD/bin/xs-dev\n```\n\nTo maintain the alias between shell sessions, for example I use zsh:\n\n```\necho \"alias local-xs-dev=$PWD/bin/xs-dev\" >> ~/.zshrc\n```\n"
 }