xs-dev 0.14.1 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +4 -0
  2. package/build/commands/scan.js +13 -6
  3. package/build/toolbox/setup/esp32.js +2 -2
  4. package/build/toolbox/update/esp32.js +2 -2
  5. package/docs/astro.config.mjs +13 -0
  6. package/docs/public/favicon.ico +0 -0
  7. package/docs/public/make-scrollable-code-focusable.js +3 -0
  8. package/docs/src/components/Footer/AvatarList.astro +149 -0
  9. package/docs/src/components/Footer/Footer.astro +16 -0
  10. package/docs/src/components/HeadCommon.astro +41 -0
  11. package/docs/src/components/HeadSEO.astro +34 -0
  12. package/docs/src/components/Header/Header.astro +133 -0
  13. package/docs/src/components/Header/LanguageSelect.css +47 -0
  14. package/docs/src/components/Header/LanguageSelect.tsx +49 -0
  15. package/docs/src/components/Header/Search.css +39 -0
  16. package/docs/src/components/Header/Search.tsx +65 -0
  17. package/docs/src/components/Header/SidebarToggle.tsx +44 -0
  18. package/docs/src/components/Header/SkipToContent.astro +22 -0
  19. package/docs/src/components/LeftSidebar/LeftSidebar.astro +118 -0
  20. package/docs/src/components/PageContent/PageContent.astro +41 -0
  21. package/docs/src/components/RightSidebar/MoreMenu.astro +70 -0
  22. package/docs/src/components/RightSidebar/RightSidebar.astro +27 -0
  23. package/docs/src/components/RightSidebar/TableOfContents.tsx +49 -0
  24. package/docs/src/components/RightSidebar/ThemeToggleButton.css +37 -0
  25. package/docs/src/components/RightSidebar/ThemeToggleButton.tsx +83 -0
  26. package/docs/src/config.ts +43 -0
  27. package/docs/src/languages.ts +10 -0
  28. package/docs/src/layouts/MainLayout.astro +122 -0
  29. package/docs/src/pages/en/features/include.md +48 -0
  30. package/docs/src/pages/en/features/init.md +57 -0
  31. package/docs/src/pages/en/features/run.md +63 -0
  32. package/docs/src/pages/en/features/scan.md +28 -0
  33. package/docs/src/pages/en/features/setup.md +55 -0
  34. package/docs/src/pages/en/features/teardown.md +13 -0
  35. package/docs/src/pages/en/features/update.md +21 -0
  36. package/docs/src/pages/en/introduction.md +68 -0
  37. package/docs/src/pages/index.astro +5 -0
  38. package/docs/src/pages/search-index.json.ts +18 -0
  39. package/docs/src/styles/index.css +382 -0
  40. package/docs/src/styles/theme.css +125 -0
  41. package/docs/tailwind.config.cjs +7 -0
  42. package/docs/tsconfig.json +15 -0
  43. package/package.json +20 -6
  44. package/docs/commands.md +0 -3
  45. package/docs/plugins.md +0 -47
package/docs/src/layouts/MainLayout.astro ADDED
@@ -0,0 +1,122 @@
1
+ ---
2
+ import HeadCommon from '../components/HeadCommon.astro';
3
+ import HeadSEO from '../components/HeadSEO.astro';
4
+ import Header from '../components/Header/Header.astro';
5
+ import Footer from '../components/Footer/Footer.astro';
6
+ import PageContent from '../components/PageContent/PageContent.astro';
7
+ import LeftSidebar from '../components/LeftSidebar/LeftSidebar.astro';
8
+ import RightSidebar from '../components/RightSidebar/RightSidebar.astro';
9
+ import * as CONFIG from '../config';
10
+
11
+ const { content = {} } = Astro.props;
12
+ const currentPage = new URL(Astro.request.url).pathname;
13
+ const currentFile = `src/pages${currentPage.replace(/\/$/, '')}.md`;
14
+ const githubEditUrl = CONFIG.GITHUB_EDIT_URL && CONFIG.GITHUB_EDIT_URL + currentFile;
15
+ ---
16
+
17
+ <html dir={content.dir ?? 'ltr'} lang={content.lang ?? 'en-us'} class="initial">
18
+ <head>
19
+ <HeadCommon />
20
+ <HeadSEO {content} canonicalURL={Astro.canonicalURL} />
21
+ <title>{content.title ? `${content.title} 🚀 ${CONFIG.SITE.title}` : CONFIG.SITE.title}</title>
22
+ <style>
23
+ body {
24
+ width: 100%;
25
+ display: grid;
26
+ grid-template-rows: var(--theme-navbar-height) 1fr;
27
+ --gutter: 0.5rem;
28
+ --doc-padding: 2rem;
29
+ }
30
+ .layout {
31
+ display: grid;
32
+ grid-auto-flow: column;
33
+ grid-template-columns:
34
+ minmax(var(--gutter), 1fr)
35
+ minmax(0, var(--max-width))
36
+ minmax(var(--gutter), 1fr);
37
+ overflow-x: hidden;
38
+ }
39
+ .layout :global(> *) {
40
+ width: 100%;
41
+ height: 100%;
42
+ }
43
+ .grid-sidebar {
44
+ height: 100vh;
45
+ position: sticky;
46
+ top: 0;
47
+ padding: 0;
48
+ }
49
+ #grid-left {
50
+ position: fixed;
51
+ background-color: var(--theme-bg);
52
+ z-index: 10;
53
+ display: none;
54
+ }
55
+ #grid-main {
56
+ padding: var(--doc-padding) var(--gutter);
57
+ grid-column: 2;
58
+ display: flex;
59
+ flex-direction: column;
60
+ height: 100%;
61
+ }
62
+ #grid-right {
63
+ display: none;
64
+ }
65
+ :global(.mobile-sidebar-toggle) {
66
+ overflow: hidden;
67
+ }
68
+ :global(.mobile-sidebar-toggle) #grid-left {
69
+ display: block;
70
+ top: 2rem;
71
+ }
72
+ @media (min-width: 50em) {
73
+ .layout {
74
+ overflow: initial;
75
+ grid-template-columns:
76
+ 20rem
77
+ minmax(0, var(--max-width));
78
+ gap: 1em;
79
+ }
80
+ #grid-left {
81
+ display: flex;
82
+ padding-left: 2rem;
83
+ position: sticky;
84
+ grid-column: 1;
85
+ }
86
+ }
87
+
88
+ @media (min-width: 72em) {
89
+ .layout {
90
+ grid-template-columns:
91
+ 20rem
92
+ minmax(0, var(--max-width))
93
+ 18rem;
94
+ padding-left: 0;
95
+ padding-right: 0;
96
+ margin: 0 auto;
97
+ }
98
+ #grid-right {
99
+ grid-column: 3;
100
+ display: flex;
101
+ }
102
+ }
103
+ </style>
104
+ </head>
105
+
106
+ <body>
107
+ <Header {currentPage} />
108
+ <main class="layout">
109
+ <aside id="grid-left" class="grid-sidebar" title="Site Navigation">
110
+ <LeftSidebar {currentPage} />
111
+ </aside>
112
+ <div id="grid-main">
113
+ <PageContent {content} {githubEditUrl}>
114
+ <slot />
115
+ </PageContent>
116
+ </div>
117
+ <aside id="grid-right" class="grid-sidebar" title="Table of Contents">
118
+ <RightSidebar {content} {githubEditUrl} />
119
+ </aside>
120
+ </main>
121
+ </body>
122
+ </html>
package/docs/src/pages/en/features/include.md ADDED
@@ -0,0 +1,48 @@
1
+ ---
2
+ title: Include
3
+ description: Manage modules from Moddable SDK
4
+ layout: ../../../layouts/MainLayout.astro
5
+ ---
6
+
7
+ # Manage modules from Moddable
8
+
9
+ The Moddable SdK ships with many first-party modules to support various features, peripherals, sensors, etc. The `include` command will update the project `manifest.json` with the selected module:
10
+
11
+ ```
12
+ xs-dev include network/wifi
13
+ ```
14
+
15
+ Or select from available modules:
16
+
17
+ ```
18
+ xs-dev include
19
+ xs-dev include files
20
+ ```
21
+
22
+ ## Select a device
23
+
24
+ When the `--device` flag is present, the module is added to the `platforms` section of the `manifest.json` for the specified device. When `device` is not provided, the module is added to the global manifest section to be used for all devices. For example, the following adds the module for use on `esp32` devices only:
25
+
26
+ ```
27
+ xs-dev include files/flash --device esp32
28
+ ```
29
+
30
+ ## Remove a module
31
+
32
+ Updates the `manifest.json` to remove the module.
33
+
34
+ ```
35
+ xs-dev remove network/wifi
36
+ ```
37
+
38
+ Or remove all modules that contain a string. This removes all modules that contain `"wifi"`.
39
+
40
+ ```
41
+ xs-dev remove wifi
42
+ ```
43
+
44
+ The `--device` flag works for the `remove` command as well:
45
+
46
+ ```
47
+ xs-dev remove network/mqtt --device esp32
48
+ ```
package/docs/src/pages/en/features/init.md ADDED
@@ -0,0 +1,57 @@
1
+ ---
2
+ title: Init
3
+ description: Scaffold new Moddable projects
4
+ layout: ../../../layouts/MainLayout.astro
5
+ ---
6
+
7
+ # Scaffold new Moddable projects
8
+
9
+ The default template creates a `main.js` and minimally configured `manifest.json` for running in the simulator.
10
+
11
+ ```
12
+ xs-dev init my-project
13
+ ```
14
+
15
+ ## TypeScript
16
+
17
+ The `--typescript` flag will create a project with Moddable types and a `main.ts` to get started:
18
+
19
+ ```
20
+ xs-dev init my-typed-project --typescript
21
+ ```
22
+
23
+ ## IO (ECMA 419)
24
+
25
+ The `--io` flag sets up the project to use the [TC53 IO manifest](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/io/io.md) in the generated `mainfest.json`:
26
+
27
+ ```
28
+ xs-dev init my-io-project --io
29
+ ```
30
+
31
+ ## Moddable example
32
+
33
+ For the `--example` flag, it can be used as a boolean to select a project from the list of available [Moddable examples](https://github.com/Moddable-OpenSource/moddable/tree/public/examples):
34
+
35
+ ```
36
+ xs-dev init my-example-project --example
37
+ ```
38
+
39
+ Or select from a filtered list of projects:
40
+
41
+ ```
42
+ xs-dev init my-http-project --example http
43
+ ```
44
+
45
+ Or if the complete example name is passed, it will be selected by default:
46
+
47
+ ```
48
+ xs-dev init my-mqtt-project --example network/mqtt/mqttbasic
49
+ ```
50
+
51
+ ## Overwrite
52
+
53
+ An existing directory matching the project name can be overwritten with the `--overwrite` flag:
54
+
55
+ ```
56
+ xs-dev init my-existing-project --overwrite
57
+ ```
package/docs/src/pages/en/features/run.md ADDED
@@ -0,0 +1,63 @@
1
+ ---
2
+ title: Run
3
+ description: Build and run Moddable projects or examples
4
+ layout: ../../../layouts/MainLayout.astro
5
+ ---
6
+
7
+ # Run Moddable projects
8
+
9
+ Within a project directory, the `run` command will invoke [`mcconfig`](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#mcconfig) to generate the `make` file based on the `manifest.json` followed by building and running the project in the current environment simulator:
10
+
11
+ ```
12
+ xs-dev run
13
+ ```
14
+
15
+ When not in the project directory, a path can be passed to `run`:
16
+
17
+ ```
18
+ xs-dev run path/to/project
19
+ ```
20
+
21
+ ## Moddable examples
22
+
23
+ Use the `--example` flag to run a project included with the Moddable SDK:
24
+
25
+ ```
26
+ xs-dev run --example helloworld
27
+ ```
28
+
29
+ The `--list-examples` provides a searchable list of available example projects:
30
+
31
+ ```
32
+ xs-dev run --list-examples
33
+ ```
34
+
35
+ ## Select a device target
36
+
37
+ The `--device` flag allows for selecting a supported [device or simulator target](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#arguments):
38
+
39
+ ```
40
+ xs-dev run --device esp32
41
+ ```
42
+
43
+ To dynamically select the device, use the `--list-devices` flag:
44
+
45
+ ```
46
+ xs-dev run --list-devices
47
+ ```
48
+
49
+ This can be used in tandem with the `--example` or `--list-examples` flags to run an example project on a connected device:
50
+
51
+ ```
52
+ xs-dev run --list-devices --list-examples
53
+ ```
54
+
55
+ ## Select a port address
56
+
57
+ The `--port` flag accepts a path to port for connected device (defaults to: `UPLOAD_PORT` environment variable):
58
+
59
+ ```
60
+ xs-dev run --port /dev/cu.usbserial-0001 --device esp8266
61
+ ```
62
+
63
+ _This value can be discovered using the [`scan`](./scan) command._
package/docs/src/pages/en/features/scan.md ADDED
@@ -0,0 +1,28 @@
1
+ ---
2
+ title: Scan
3
+ description: Discover connected device targets
4
+ layout: ../../../layouts/MainLayout.astro
5
+ ---
6
+
7
+ # Discovery available devices
8
+
9
+ This command will use the [`esptool.py`](https://github.com/espressif/esptool) and/or [`picotool`](https://github.com/raspberrypi/picotool) command line tools to find available device targets connected over USB to the local dev environment.
10
+
11
+ ```
12
+ xs-dev scan
13
+ ```
14
+
15
+ This will provide info with the port address, device name, and discovered features:
16
+
17
+ ```
18
+ ✔ Found the following available devices!
19
+ Port Device Features
20
+ /dev/cu.usbserial-0001 ESP8266EX WiFi
21
+ /dev/cu.usbserial-DN02N5XK ESP32-D0WDQ6 (revision 0) WiFi, BT, Dual Core, Coding Scheme None
22
+ ```
23
+
24
+ The port can be used with the [`run`](./run) command to specify a device, if multiple are connected:
25
+
26
+ ```
27
+ xs-dev run --port /dev/cu.usbserial-0001 --device esp8266
28
+ ```
package/docs/src/pages/en/features/setup.md ADDED
@@ -0,0 +1,55 @@
1
+ ---
2
+ title: Setup
3
+ description: xs-dev platform setup
4
+ layout: ../../../layouts/MainLayout.astro
5
+ ---
6
+
7
+ # Moddable Platform Setup
8
+
9
+ This command downloads and builds the [Moddable developer tooling](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md) for the current OS (Windows support coming soon).
10
+
11
+ [After installing the CLI](/en/introduction#installation), call the `setup` command:
12
+
13
+ ```
14
+ xs-dev setup
15
+ ```
16
+
17
+ This process mostly automates the instructions provided by [Moddable's "Getting Started" documentation](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/Moddable%20SDK%20-%20Getting%20Started.md) with a few exceptions.
18
+
19
+ **On macOS:**
20
+
21
+ [Homebrew](https://brew.sh/) is assumed to be installed.
22
+
23
+ The [Xcode Command Line tools](https://developer.apple.com/xcode/) are required; `setup` will check for their existence before continuing.
24
+
25
+ A symlink for [`xsbug.app`](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/xs/xsbug.md) is created in `/Applications` for easy access through Launchpad.
26
+
27
+ **On Unix environments:**
28
+
29
+ The [`moddable` git repo](https://github.com/Moddable-OpenSource/moddable) is cloned into `~/.local/share` instead of a new/existing `~/Projects` directory.
30
+
31
+ ## Device Setup
32
+
33
+ While the `setup` command provides the Moddable SDK for the dev environment, the `--device` flag selects another platform target SDK to set up. It ensures the Moddable SDK has been installed first.
34
+
35
+ ```
36
+ xs-dev setup --device esp32
37
+ ```
38
+
39
+ Use the `--list-devices` flag to get a prompt for supported device tooling to install.
40
+
41
+ ```
42
+ xs-dev setup --list-devices
43
+ ```
44
+
45
+ ## Additional related tooling
46
+
47
+ There are some utilities that are not included in the Moddable SDK or other platform tooling but can be helpful with some common development tasks. The `--tool` flag allows for installing one of these related tools, which may not be easily done from a typical package manager.
48
+
49
+ **Supported tools:**
50
+
51
+ [`fontbm`](https://github.com/vladimirgamalyan/fontbm): BMFont compatible, cross-platform (Linux/macOS/Windows) command line bitmap font generator (FreeType2 based render)
52
+
53
+ ```
54
+ xs-dev setup --tool fontbm
55
+ ```
package/docs/src/pages/en/features/teardown.md ADDED
@@ -0,0 +1,13 @@
1
+ ---
2
+ title: Teardown
3
+ description: Clean up dev environment
4
+ layout: ../../../layouts/MainLayout.astro
5
+ ---
6
+
7
+ # Clean up environment changes
8
+
9
+ Remove all installed git repos and toolchains, unset environment changes. This is all or nothing currently; there's no filter for selecting an individual platform or device tooling.
10
+
11
+ ```
12
+ xs-dev teardown
13
+ ```
package/docs/src/pages/en/features/update.md ADDED
@@ -0,0 +1,21 @@
1
+ ---
2
+ title: Update
3
+ description: Stay up to date with the latest tooling
4
+ layout: ../../../layouts/MainLayout.astro
5
+ ---
6
+
7
+ # SDK & Tooling Updates
8
+
9
+ Stay up to date with the latest tooling from Moddable and supported device targets. As with the [`setup`](./setup) command, the current dev environment (Mac or Linux) is the default selected target:
10
+
11
+ ```
12
+ xs-dev update
13
+ ```
14
+
15
+ The `--device` flag allows for selecting a different target platform:
16
+
17
+ ```
18
+ xs-dev update --device esp32
19
+ ```
20
+
21
+ _There may be some platforms that are supported by the `setup` command but not `update` yet._
package/docs/src/pages/en/introduction.md ADDED
@@ -0,0 +1,68 @@
1
+ ---
2
+ title: Introduction
3
+ description: xs-dev intro
4
+ layout: ../../layouts/MainLayout.astro
5
+ ---
6
+
7
+ # **Welcome to xs-dev!**
8
+
9
+ 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)
10
+
11
+ The 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 installation and environment configuration requirements across platforms in just a few commands.
12
+
13
+ **This project is a work in progress and should be considered pre-1.0.**
14
+
15
+ **Features:**
16
+
17
+ - [X] [Moddable SDK setup](./features/setup)
18
+ - [X] [SDK updates](./features/update)
19
+ - [X] [Teardown](./features/teardown)
20
+ - [X] [Device discovery](./features/scan)
21
+ - [X] [Project creation](./features/init)
22
+ - [X] [Run a project or example](./features/run)
23
+ - [X] [SDK module management](./features/include)
24
+ - [ ] Third-party dependency management ([coming soon](https://github.com/HipsterBrown/xs-dev/issues/49))
25
+
26
+ **Platform support:**
27
+
28
+ - [X] Mac
29
+ - [ ] Windows ([coming soon](https://github.com/HipsterBrown/xs-dev/pull/44))
30
+ - [X] Linux
31
+
32
+ ## Requirements
33
+
34
+ [Node.js >= v12](https://nodejs.org/en/)
35
+
36
+ **On Linux:**
37
+
38
+ Setup commands rely on [`ssh-askpass`](https://packages.ubuntu.com/bionic/ssh-askpass) to prompt for permission when installing other tools and dependencies.
39
+
40
+ ## Installation
41
+
42
+ Install the package globally from `npm`:
43
+
44
+ ```
45
+ npm install -g xs-dev
46
+ ```
47
+
48
+ ```
49
+ pnpm install -g xs-dev
50
+ ```
51
+
52
+ ```
53
+ yarn global add xs-dev
54
+ ```
55
+
56
+ ## Update to latest release
57
+
58
+ ```
59
+ npm update -g xs-dev
60
+ ```
61
+
62
+ ```
63
+ pnpm update -g xs-dev
64
+ ```
65
+
66
+ ```
67
+ yarn global upgrade xs-dev
68
+ ```
package/docs/src/pages/index.astro ADDED
@@ -0,0 +1,5 @@
1
+ <script is:inline>
2
+ // Redirect your homepage to the first page of documentation.
3
+ // If you have a landing page, remove this script and add it here!
4
+ window.location.pathname += `en/introduction`;
5
+ </script>
package/docs/src/pages/search-index.json.ts ADDED
@@ -0,0 +1,18 @@
1
+ export async function get() {
2
+ const pagesMeta = import.meta.glob('./en/**/*.md')
3
+ const pages = await Promise.all(
4
+ Object.values(pagesMeta).map(async (getInfo) => {
5
+ const { rawContent, url, frontmatter } = await getInfo()
6
+ return {
7
+ content: rawContent(),
8
+ url,
9
+ ...frontmatter,
10
+ }
11
+ })
12
+ )
13
+ const json = JSON.stringify(pages)
14
+
15
+ return {
16
+ body: json,
17
+ }
18
+ }