xs-dev 0.15.0 → 0.17.0

package/build/types/toolbox/setup/linux.d.ts

@@ -1 +1,2 @@
-export default function (): Promise<void>;
+import { SetupArgs } from './types';
+export default function ({ targetBranch }: SetupArgs): Promise<void>;

package/build/types/toolbox/setup/mac.d.ts

@@ -1 +1,2 @@
-export default function (): Promise<void>;
+import { SetupArgs } from './types';
+export default function ({ targetBranch }: SetupArgs): Promise<void>;

package/build/types/toolbox/setup/moddable.d.ts

@@ -1 +1,12 @@
+import { RestEndpointMethodTypes } from '@octokit/rest';
 export declare function moddableExists(): boolean;
+declare type ExtractFromArray<Item extends readonly unknown[]> = Item extends Readonly<Array<infer ItemType>> ? ItemType : never;
+declare type GitHubRelease = ExtractFromArray<RestEndpointMethodTypes['repos']['listReleases']['response']['data']>;
+export declare function fetchLatestRelease(): Promise<GitHubRelease>;
+interface DownloadToolsArgs {
+    writePath: string;
+    assetName: string;
+    release: GitHubRelease;
+}
+export declare function downloadReleaseTools({ writePath, assetName, release, }: DownloadToolsArgs): Promise<void>;
+export {};

package/build/types/toolbox/setup/types.d.ts

@@ -0,0 +1,3 @@
+export interface SetupArgs {
+    targetBranch: 'public' | 'latest-release';
+}

package/build/types/toolbox/setup/windows.d.ts

@@ -1 +1,2 @@
-export default function (): Promise<void>;
+import { SetupArgs } from './types';
+export default function (_args: SetupArgs): Promise<void>;

package/build/types/toolbox/update/linux.d.ts

@@ -1 +1,2 @@
-export default function (): Promise<void>;
+import { SetupArgs } from '../setup/types';
+export default function ({ targetBranch }: SetupArgs): Promise<void>;

package/build/types/toolbox/update/mac.d.ts

@@ -1 +1,2 @@
-export default function (): Promise<void>;
+import { SetupArgs } from '../setup/types';
+export default function ({ targetBranch }: SetupArgs): Promise<void>;

package/build/types/types.d.ts

@@ -1,6 +1,9 @@
 import type { GluegunToolbox } from 'gluegun';
+import type { SetupArgs } from './toolbox/setup/types';
+import type { BuildArgs } from './toolbox/build/index';
 export declare type Device = 'darwin' | 'linux' | 'windows_nt' | 'esp' | 'esp8266' | 'esp32' | 'wasm' | 'pico';
 export interface XSDevToolbox extends GluegunToolbox {
-    setup: Record<Device, () => Promise<void>>;
-    update: Record<Device, () => Promise<void>>;
+    setup: Record<Device, (() => Promise<void>) | ((args: SetupArgs) => Promise<void>)>;
+    update: Record<Device, (() => Promise<void>) | ((args: SetupArgs) => Promise<void>)>;
+    build: (args: BuildArgs) => Promise<void>;
 }

package/docs/public/make-scrollable-code-focusable.js

@@ -1,3 +1,3 @@
 Array.from(document.getElementsByTagName('pre')).forEach((element) => {
-	element.setAttribute('tabindex', '0');
-});
+  element.setAttribute('tabindex', '0')
+})

package/docs/src/components/HeadCommon.astro

@@ -30,12 +30,3 @@ import '../styles/index.css';
 		root.classList.remove('theme-dark');
 	}
 </script>
-
-<!-- Global site tag (gtag.js) - Google Analytics -->
-<!-- <script async src="https://www.googletagmanager.com/gtag/js?id=G-TEL60V1WM9" is:inline></script>
-<script>
-  window.dataLayer = window.dataLayer || [];
-  function gtag(){dataLayer.push(arguments);}
-  gtag('js', new Date());
-  gtag('config', 'G-TEL60V1WM9');
-</script> -->

package/docs/src/components/HeadSEO.astro

@@ -5,7 +5,8 @@ export interface Props {
 	site: any;
 	canonicalURL: URL | string;
 }
-const { content = {}, canonicalURL } = Astro.props;
+const canonicalURL = new URL(Astro.url.pathname, Astro.site);
+const { content = {} } = Astro.props;
 const formattedContentTitle = content.title ? `${content.title} 🚀 ${SITE.title}` : SITE.title;
 ---
 
@@ -25,10 +26,3 @@ const formattedContentTitle = content.title ? `${content.title} 🚀 ${SITE.titl
 <meta name="twitter:site" content={OPEN_GRAPH.twitter} />
 <meta name="twitter:title" content={formattedContentTitle} />
 <meta name="twitter:description" content={content.description ? content.description : SITE.description} />
-
-<!--
-  TODO: Add json+ld data, maybe https://schema.org/APIReference makes sense?
-  Docs: https://developers.google.com/search/docs/advanced/structured-data/intro-structured-data
-  https://www.npmjs.com/package/schema-dts seems like a great resource for implementing this.
-  Even better, there's a React component that integrates with `schema-dts`: https://github.com/google/react-schemaorg
--->

package/docs/src/components/Header/Header.astro

@@ -17,7 +17,7 @@ const lang = currentPage && getLanguageFromURL(currentPage);
 			<SidebarToggle client:idle />
 		</div>
 		<div class="logo flex">
-			<a href={Astro.site}>
+			<a href={import.meta.env.BASE_URL}>
 				<h1>{CONFIG.SITE.title ?? "Documentation"}</h1>
 			</a>
 		</div>

package/docs/src/components/LeftSidebar/LeftSidebar.astro

@@ -31,7 +31,7 @@ const sidebarSections = SIDEBAR[langCode].reduce((col, item, i) => {
 					<ul>
 						{section.children.map((child) => (
 							<li class="nav-link">
-								<a href={`${Astro.site.pathname}${child.link}`} aria-current={`${currentPageMatch === child.link ? 'page' : 'false'}`}>
+								<a href={`${import.meta.env.BASE_URL}${child.link}`} aria-current={`${currentPageMatch === child.link ? 'page' : 'false'}`}>
 									{child.text}
 								</a>
 							</li>

package/docs/src/config.ts

@@ -39,5 +39,8 @@ export const SIDEBAR = {
     { text: 'Project Creation', link: 'en/features/init' },
     { text: 'Build & Run', link: 'en/features/run' },
     { text: 'SDK Module Management', link: 'en/features/include' },
+    { text: 'Guide', header: true },
+    { text: '00. Prepare', link: 'en/guide/00-prepare' },
+    { text: '01. Hello Console', link: 'en/guide/01-hello-console' },
   ],
 }

package/docs/src/languages.ts

@@ -1,10 +1,10 @@
-import { KNOWN_LANGUAGES } from './config';
+import { KNOWN_LANGUAGES } from './config'
 
-export { KNOWN_LANGUAGES };
-export const KNOWN_LANGUAGE_CODES = Object.values(KNOWN_LANGUAGES);
-export const langPathRegex = /\/([a-z]{2}-?[A-Z]{0,2})\//;
+export { KNOWN_LANGUAGES }
+export const KNOWN_LANGUAGE_CODES = Object.values(KNOWN_LANGUAGES)
+export const langPathRegex = /\/([a-z]{2}-?[A-Z]{0,2})\//
 
 export function getLanguageFromURL(pathname: string) {
-	const langCodeMatch = pathname.match(langPathRegex);
-	return langCodeMatch ? langCodeMatch[1] : 'en';
+  const langCodeMatch = pathname.match(langPathRegex)
+  return langCodeMatch ? langCodeMatch[1] : 'en'
 }

package/docs/src/layouts/MainLayout.astro

@@ -17,7 +17,7 @@ const githubEditUrl = CONFIG.GITHUB_EDIT_URL && CONFIG.GITHUB_EDIT_URL + current
 <html dir={content.dir ?? 'ltr'} lang={content.lang ?? 'en-us'} class="initial">
 	<head>
 		<HeadCommon />
-		<HeadSEO {content} canonicalURL={Astro.canonicalURL} />
+		<HeadSEO {content} />
 		<title>{content.title ? `${content.title} 🚀 ${CONFIG.SITE.title}` : CONFIG.SITE.title}</title>
 		<style>
 			body {

package/docs/src/pages/en/features/run.md

@@ -1,10 +1,10 @@
 ---
-title: Run
+title: Build and Run
 description: Build and run Moddable projects or examples
 layout: ../../../layouts/MainLayout.astro
 ---
 
-# Run Moddable projects
+## Running Projects
 
 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:
 
@@ -61,3 +61,30 @@ xs-dev run --port /dev/cu.usbserial-0001 --device esp8266
 ```
 
 _This value can be discovered using the [`scan`](./scan) command._
+
+
+## Building projects for release
+
+Within a project directory, the `build` command takes the same flags as the `run` command to 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 only building the project for [the target device](#select-a-device-target):
+
+```
+xs-dev build --device esp32
+```
+
+The build `--mode` can be set to `production` for the optimized release code or `development` for the debug-enabled release code. This will default to the `NODE_ENV` environment variable or `development` if that variable is not set.
+
+```
+xs-dev build --mode production --device esp32
+```
+
+The output directory can also be set using the `--output` flag, overriding the default path of `$MODDABLE/build`, where `$MODDABLE` is the location of the Moddable tooling repo on your local filesystem.
+
+```
+xs-dev build --output ./dist --device esp32
+```
+
+If you want to immediately deploy the release build, use the `--deploy` flag:
+
+```
+xs-dev build --deploy --device esp32
+```

package/docs/src/pages/en/features/setup.md

@@ -6,7 +6,7 @@ layout: ../../../layouts/MainLayout.astro
 
 # Moddable Platform Setup
 
-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).
+This command downloads the [Moddable developer tooling](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md) for the current OS (Windows support coming soon).
 
 [After installing the CLI](/en/introduction#installation), call the `setup` command:
 
@@ -28,6 +28,18 @@ A symlink for [`xsbug.app`](https://github.com/Moddable-OpenSource/moddable/blob
 
 The [`moddable` git repo](https://github.com/Moddable-OpenSource/moddable) is cloned into `~/.local/share` instead of a new/existing `~/Projects` directory.
 
+## Target Branch
+
+The default behavior of this command for Moddable developer tooling pulls the [latest release tooling](https://github.com/Moddable-OpenSource/moddable/releases) and source code for the associated tagged branch. This provides a known-working state for the SDK and avoids needing to build the tooling on the local machine. 
+
+To override this behavior, use the `--target-branch` flag to select `public`; this fetches the latest commit off that main branch and runs the build to generate the associated tools.
+
+```
+xs-dev setup --target-branch public
+```
+
+_This will only work for the `mac`, `windows`, and `linux` device options, which are the respective defaults for the operating system on which the command is run._
+
 ## Device Setup
 
 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.

package/docs/src/pages/en/features/update.md

@@ -12,6 +12,22 @@ Stay up to date with the latest tooling from Moddable and supported device targe
 xs-dev update
 ```
 
+## Target Branch
+
+The default behavior of this command for Moddable developer tooling pulls the [latest release tooling](https://github.com/Moddable-OpenSource/moddable/releases) and source code for the associated tagged branch. This provides a known-working state for the SDK and avoids needing to build the tooling on the local machine. 
+
+To override this behavior, use the `--target-branch` flag to select `public`; this fetches the latest commit off that main branch and runs the build to generate the associated tools.
+
+```
+xs-dev setup --target-branch public
+```
+
+_This will only work for the `mac`, `windows`, and `linux` device options, which are the respective defaults for the operating system on which the command is run._
+
+## Device Updates
+
+While the `update` command provides the latest 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.
+
 The `--device` flag allows for selecting a different target platform:
 
 ```

package/docs/src/pages/en/guide/00-prepare.md

@@ -0,0 +1,50 @@
+---
+title: Prerequisites
+description: Prepare for embedded JS development
+layout: ../../../layouts/MainLayout.astro
+---
+
+**Prepare for embedded JS development**
+
+Getting started on the journey to developing embedded hardware projects with JavaScript assumes some knowledge of various technologies like the command line, text editors, package managers, and [the JavaScript programming language](https://developer.mozilla.org/en-US/docs/Web/javascript).
+
+## Command Line
+
+Tutorial content will reference command line utilities and jargon as part of the workflow for developing embedded JS projects. Select your operating system to learn more about this subject:
+
+- [MacOS OR Linux](https://www.freecodecamp.org/news/command-line-for-beginners/)
+- [Windows](https://www.freecodecamp.org/news/command-line-commands-cli-tutorial/)
+
+Inline terminal commands will usually be formatting like the following: `echo "hello world"`
+
+Code examples will look like the following:
+
+```javascript
+trace('hello world')
+```
+
+## Text Editors
+
+A local plain text editor is generally required for creating and editing your JavaScript projects. You can download one of the following free applications with either built-in or third-party support for JavaScript:
+
+- [Visual Studio Code](https://code.visualstudio.com/)
+- [Neovim](http://www.sublimetext.com/) / [Vim](https://www.vim.org/)
+- [Sublime Text](http://www.sublimetext.com/)
+
+These are not the only available editors, so feel free to do your own research and pick what feels right to you!
+
+## NodeJS Package Manager (optional)
+
+While [NodeJS](https://nodejs.org/en/) is not required for [Moddable XS](https://github.com/Moddable-OpenSource/moddable) projects, it is a dependency for installing and using the [`xs-dev` CLI](https://hipsterbrown.github.io/xs-dev/en/introduction/).
+
+Node can be [downloaded directly from the website](https://nodejs.org/en/download/), however using one of the following version managers can help with quickly switching to recommended versions of the tooling in the future:
+
+- [Volta](https://volta.sh/)
+- [fnm](https://github.com/Schniz/fnm)
+- [asdf](https://asdf-vm.com/guide/getting-started.html#_4-install-a-plugin)
+- [`pnpm env`](https://pnpm.io/cli/env)
+
+Node comes with [npm](https://docs.npmjs.com/cli/v8/commands/npm) as the included package manager, but there are other options available if needed:
+
+- [pnpm](https://pnpm.io/installation)
+- [yarn](https://yarnpkg.com/)

package/docs/src/pages/en/guide/01-hello-console.md

@@ -0,0 +1,62 @@
+---
+title: Hello Console
+description: How to set up the basic development environment and run your first program
+layout: ../../../layouts/MainLayout.astro
+---
+
+**How to set up the basic development environment and run your first program**
+
+## Install the CLI
+
+`xs-dev` can be installed globally using the [NodeJS package manager of your choice](./00-prepare#nodejs-package-manager-optional).
+
+```
+npm install -g xs-dev
+```
+
+```
+pnpm install -g xs-dev
+```
+
+```
+yarn global add xs-dev
+```
+
+## Setup system tooling
+
+As specified in the [setup documentation](../features/setup), the [Moddable SDK and associated tooling](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md) is installed using the following command:
+
+```
+xs-dev setup
+```
+
+This will determine the correct tooling to install based on your operating system.
+
+**[Windows support coming soon](https://github.com/HipsterBrown/xs-dev/pull/53)**
+
+Once this process is done, you should see a success message:
+
+```
+Moddable SDK successfully set up! Start a new terminal session and run the "helloworld example": xs-dev run --example helloworld
+```
+
+## Run the Hello World example
+
+To start a new terminal session, you can either execute your shell of choice (`bash`/`zsh`/`fish`) or create a new terminal window / tab. This will ensure the expected tooling is available in your session [PATH](https://en.wikipedia.org/wiki/PATH_(variable)).
+
+You can [run any Moddable example included in the SDK](../features/run#moddable-examples). The "Hello World" example provides the simplest program to get started and can be run in the [simulator](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#simulator):
+
+```
+xs-dev run --example helloworld
+```
+
+This will start up the debugger and simulator:
+
+![Moddable simulator app and debugger app running on MacOS](/run-hello-world.png)
+
+This will keep running until the `Ctrl+C` keys are entered in the terminal session or both apps are quit.
+
+## Keep exploring!
+
+Use the `--list-examples` flag with the `run` command to search the extensive list of available examples to run in the simulator: `xs-dev run --list-examples`
+

package/docs/tsconfig.json

@@ -9,6 +9,7 @@
     "resolveJsonModule": true,
     // Enable stricter transpilation for better output.
     "isolatedModules": true,
+    "noEmit": true,
     // Add type definitions for our Vite runtime.
     "types": ["vite/client"]
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xs-dev",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "CLI for automating the setup and usage of Moddable XS tools",
   "types": "build/types/types.d.ts",
   "bin": {
@@ -20,6 +20,7 @@
     "url": "https://github.com/HipsterBrown/xs-dev.git"
   },
   "dependencies": {
+    "@octokit/rest": "^19.0.3",
     "axios": "^0.24.0",
     "gluegun": "^5.0.0",
     "serialport": "^10.3.0",
@@ -29,11 +30,10 @@
     "usb": "^2.2.0"
   },
   "devDependencies": {
-    "@astrojs/lit": "^0.1.4",
-    "@astrojs/markdown-remark": "^0.11.0",
-    "@astrojs/preact": "^0.1.3",
-    "@astrojs/sitemap": "^0.1.0",
-    "@astrojs/tailwind": "^0.2.1",
+    "@astrojs/lit": "^1.0.0",
+    "@astrojs/preact": "^1.0.1",
+    "@astrojs/sitemap": "^1.0.0",
+    "@astrojs/tailwind": "^1.0.0",
     "@changesets/cli": "^2.19.0",
     "@types/jest": "^27.4.0",
     "@types/node": "^16.11.0",
@@ -43,7 +43,7 @@
     "@typescript-eslint/eslint-plugin": "^4.0.1",
     "@typescript-eslint/parser": "^4.0.0",
     "@webcomponents/template-shadowroot": "^0.1.0",
-    "astro": "^1.0.0-beta.40",
+    "astro": "^1.0.2",
     "eslint": "^7.12.1",
     "eslint-config-prettier": "^8.3.0",
     "eslint-config-standard-with-typescript": "^21.0.1",
@@ -57,7 +57,7 @@
     "preact-render-to-string": "^5.2.0",
     "prettier": "^2.5.1",
     "ts-jest": "^27.1.0",
-    "ts-node": "^10.4.0",
+    "ts-node": "^10.9.1",
     "typescript": "^4.7.3"
   },
   "jest": {
@@ -84,6 +84,10 @@
     "coverage": "jest --coverage",
     "start:docs": "astro dev --root ./docs",
     "build:docs": "astro build --root ./docs",
-    "preview:docs": "astro preview --root ./docs"
+    "preview:docs": "astro preview --root ./docs",
+    "ci:version:changeset": "changeset version",
+    "ci:version": "pnpm ci:version:changeset && pnpm ci:version:install",
+    "ci:version:install": "pnpm install --frozen-lockfile=false",
+    "ci:publish": "changeset publish"
   }
 }