feat(setup/update): split target-branch into release, branch options

docs/src/content/docs/features/setup.md

@@ -37,20 +37,38 @@ The [`moddable` git repo](https://github.com/Moddable-OpenSource/moddable) is cl
 
 This command will create (and update) an environment configuration file called `~/.local/share/xs-dev-export.sh` (on Mac & Linux) or `Moddable.bat` (on Windows). This file will be sourced by `xs-dev` when running commands (on Mac & Linux) or through the custom command prompt (on Windows), to set environment variables and call other "exports" files for embedded tooling.
 
+## Tagged Release
+
+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 `--release` flag to select a tagged release version; this fetches the pre-compiled release assets and latest commit off that tag.
+
+```
+xs-dev setup --release 5.3.0
+```
+
+When combined with the `--source-repo` flag, it's possible to get the SDK from another source instead of the default GitHub repo.
+
+```
+xs-dev setup --source-repo https://my-sdk.moddable-git.not-real --release 5.4.0-alpha
+```
+
+_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._
+
 ## 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. This can be set to any branch name, however `public` is the main public branch for the Moddable-OpenSource repo.
+To override this behavior, use the `--branch` flag to select `public`; this fetches the latest commit off that main branch and runs the build to generate the associated tools. This can be set to any branch name, however `public` is the main public branch for the Moddable-OpenSource repo.
 
 ```
-xs-dev setup --target-branch public
+xs-dev setup --branch public
 ```
 
 When combined with the `--source-repo` flag, it's possible to get the SDK repo from another source instead of the default GitHub repo.
 
 ```
-xs-dev setup --source-repo https://my-sdk.moddable-git.not-real --target-branch main
+xs-dev setup --source-repo https://my-sdk.moddable-git.not-real --branch main
 ```
 
 _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._

docs/src/content/docs/features/update.md

@@ -11,14 +11,26 @@ Stay up to date with the latest tooling from Moddable and supported device targe
 xs-dev update
 ```
 
+## Tagged Release
+
+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 `--release` flag to select a tagged release version; this fetches the pre-compiled release assets and latest commit off that tag.
+
+```
+xs-dev update --release 5.3.0
+```
+
+_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._
+
 ## 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.
+To override this behavior, use the `--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
+xs-dev update --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._

src/commands/init.ts

@@ -42,7 +42,7 @@ const command = buildCommand({
 
       await sourceEnvironment()
 
-      if (example !== undefined ?? listExamples) {
+      if (example !== undefined || listExamples) {
         // find example project
         const exampleProjectPath = filesystem.resolve(
           String(process.env.MODDABLE),

src/commands/setup.ts

@@ -11,7 +11,8 @@ interface SetupOptions {
   device?: Device
   'list-devices'?: boolean
   tool?: 'ejectfix'
-  'target-branch'?: SetupArgs['targetBranch']
+  branch?: SetupArgs['branch']
+  release?: SetupArgs['release']
   'source-repo'?: string
 }
 const command = buildCommand({
@@ -25,7 +26,8 @@ const command = buildCommand({
       device,
       'list-devices': listDevices = false,
       tool,
-      'target-branch': targetBranch = 'latest-release',
+      branch,
+      release = 'latest',
       'source-repo': sourceRepo = MODDABLE_REPO,
     } = flags
     let target: Device = device ?? DEVICE_ALIAS[currentPlatform]
@@ -74,9 +76,9 @@ const command = buildCommand({
     ]
     const { default: setup } = await import(`../toolbox/setup/${target}`)
     if (platformDevices.includes(target)) {
-      await setup({ targetBranch, sourceRepo })
+      await setup({ branch, release, sourceRepo })
     } else {
-      await setup({ targetBranch })
+      await setup({ branch, release })
     }
   },
   parameters: {
@@ -100,11 +102,17 @@ const command = buildCommand({
         brief: 'Install additional tooling to support common development tasks',
         optional: true,
       },
-      'target-branch': {
+      branch: {
+        kind: 'parsed',
+        parse: String,
+        brief: 'The remote branch to use as the source for Moddable SDK set up',
+        optional: true,
+      },
+      release: {
         kind: 'parsed',
         parse: String,
         brief:
-          'The remote branch or release to use as source for Moddable SDK set up; defaults to `latest-release`',
+          'The release tag to use as the source for Moddable SDK set up; defaults to `latest`',
         optional: true,
       },
       'source-repo': {

src/commands/update.ts

@@ -6,7 +6,8 @@ import { DEVICE_ALIAS } from '../toolbox/prompt/devices'
 
 interface UpdateOptions {
   device?: Device
-  'target-branch'?: 'public' | 'latest-release'
+  branch?: 'public' | string
+  release?: 'latest' | string
 }
 
 const command = buildCommand({
@@ -17,10 +18,11 @@ const command = buildCommand({
     const currentPlatform: Device = platformType().toLowerCase() as Device
     const {
       device = DEVICE_ALIAS[currentPlatform],
-      'target-branch': targetBranch = 'latest-release',
+      branch,
+      release = 'latest',
     } = flags
     const { default: update } = await import(`../toolbox/update/${device}`)
-    await update({ targetBranch })
+    await update({ branch, release })
   },
   parameters: {
     flags: {
@@ -31,11 +33,18 @@ const command = buildCommand({
           'Target device or platform SDK to set up; defaults to Moddable SDK for current OS',
         optional: true,
       },
-      'target-branch': {
-        kind: 'enum',
-        values: ['public', 'latest-release'],
+      branch: {
+        kind: 'parsed',
+        parse: String,
+        brief:
+          'The remote branch to use as source for Moddable SDK update; overrides the --release flag',
+        optional: true,
+      },
+      release: {
+        kind: 'parsed',
+        parse: String,
         brief:
-          'The remote branch or release to use as source for Moddable SDK update; defaults to `latest-release`',
+          'The tagged release to use as source for Moddable SDK update; defaults to `latest`',
         optional: true,
       },
     },

src/toolbox/prompt/choices.ts

@@ -11,7 +11,9 @@ export function collectChoicesFromTree(
 ): string[] {
   if (
     fd.type === 'dir' &&
-    fd.children.find((file) => file.name === 'manifest.json') !== undefined
+    fd.children.find((file) =>
+      ['manifest.json', 'package.json'].includes(file.name),
+    ) !== undefined
   ) {
     results.push(root + fd.name)
   } else if (fd.type === 'dir') {

src/toolbox/setup/linux.ts

@@ -11,13 +11,14 @@ import {
 import upsert from '../patching/upsert'
 import { execWithSudo } from '../system/exec'
 import type { PlatformSetupArgs } from './types'
-import { fetchLatestRelease, downloadReleaseTools } from './moddable'
+import { fetchRelease, downloadReleaseTools } from './moddable'
 
 const chmodPromise = promisify(chmod)
 
 export default async function ({
   sourceRepo,
-  targetBranch,
+  branch,
+  release,
 }: PlatformSetupArgs): Promise<void> {
   print.info('Setting up Linux tools!')
 
@@ -69,11 +70,11 @@ export default async function ({
   if (filesystem.exists(INSTALL_PATH) !== false) {
     spinner.info('Moddable repo already installed')
   } else {
-    if (targetBranch === 'latest-release') {
+    if (release !== undefined && (branch === undefined || branch === null)) {
       spinner.start('Getting latest Moddable-OpenSource/moddable release')
-      const release = await fetchLatestRelease()
+      const remoteRelease = await fetchRelease(release)
       await system.spawn(
-        `git clone ${sourceRepo} ${INSTALL_PATH} --depth 1 --branch ${release.tag_name} --single-branch`,
+        `git clone ${sourceRepo} ${INSTALL_PATH} --depth 1 --branch ${remoteRelease.tag_name} --single-branch`,
       )
 
       filesystem.dir(BIN_PATH)
@@ -87,7 +88,7 @@ export default async function ({
       await downloadReleaseTools({
         writePath: BIN_PATH,
         assetName,
-        release,
+        release: remoteRelease,
       })
       const tools = filesystem.list(BIN_PATH) ?? []
       await Promise.all(
@@ -102,7 +103,7 @@ export default async function ({
     } else {
       spinner.start(`Cloning ${sourceRepo} repo`)
       await system.spawn(
-        `git clone ${sourceRepo} ${INSTALL_PATH} --depth 1 --branch ${targetBranch} --single-branch`,
+        `git clone ${sourceRepo} ${INSTALL_PATH} --depth 1 --branch ${branch} --single-branch`,
       )
     }
     spinner.succeed()
@@ -116,15 +117,15 @@ export default async function ({
   await upsert(EXPORTS_FILE_PATH, `export PATH="${BIN_PATH}:$PATH"`)
 
   // 5. Build the Moddable command line tools, simulator, and debugger from the command line:
-  if (targetBranch !== 'latest-release') {
+  if (typeof branch === 'string') {
     spinner.start('Building platform tooling')
     await system.exec('make', { cwd: BUILD_DIR, stdout: process.stdout })
     spinner.succeed()
   }
 
   // 6. Install the desktop simulator and xsbug debugger applications
   spinner.start('Installing simulator')
-  if (targetBranch === 'latest-release') {
+  if (release !== undefined && (branch === undefined || branch === null)) {
     filesystem.dir(
       filesystem.resolve(
         BUILD_DIR,

src/toolbox/setup/mac.ts

@@ -11,7 +11,7 @@ import {
 import upsert from '../patching/upsert'
 import {
   downloadReleaseTools,
-  fetchLatestRelease,
+  fetchRelease,
   MissingReleaseAssetError,
 } from './moddable'
 import type { PlatformSetupArgs } from './types'
@@ -20,7 +20,8 @@ const chmodPromise = promisify(chmod)
 
 export default async function ({
   sourceRepo,
-  targetBranch,
+  branch,
+  release,
 }: PlatformSetupArgs): Promise<void> {
   print.info('Setting up the mac tools!')
 
@@ -72,11 +73,11 @@ export default async function ({
     spinner.info('Moddable repo already installed')
   } else {
     try {
-      if (targetBranch === 'latest-release') {
+      if (release !== undefined && (branch === undefined || branch === null)) {
         spinner.start('Getting latest Moddable-OpenSource/moddable release')
-        const release = await fetchLatestRelease()
+        const remoteRelease = await fetchRelease(release)
         await system.spawn(
-          `git clone ${sourceRepo} ${INSTALL_PATH} --depth 1 --branch ${release.tag_name} --single-branch`,
+          `git clone ${sourceRepo} ${INSTALL_PATH} --depth 1 --branch ${remoteRelease.tag_name} --single-branch`,
         )
 
         filesystem.dir(BIN_PATH)
@@ -88,7 +89,7 @@ export default async function ({
           await downloadReleaseTools({
             writePath: BIN_PATH,
             assetName: universalAssetName,
-            release,
+            release: remoteRelease,
           })
         } catch (error: unknown) {
           if (error instanceof MissingReleaseAssetError) {
@@ -99,7 +100,7 @@ export default async function ({
             await downloadReleaseTools({
               writePath: BIN_PATH,
               assetName,
-              release,
+              release: remoteRelease,
             })
           } else {
             throw error as Error
@@ -129,7 +130,7 @@ export default async function ({
       } else {
         spinner.start(`Cloning ${sourceRepo} repo`)
         await system.spawn(
-          `git clone ${sourceRepo} ${INSTALL_PATH} --depth 1 --branch ${targetBranch} --single-branch`,
+          `git clone ${sourceRepo} ${INSTALL_PATH} --depth 1 --branch ${branch} --single-branch`,
         )
       }
       spinner.succeed()
@@ -147,7 +148,7 @@ export default async function ({
   await upsert(EXPORTS_FILE_PATH, `export PATH="${BIN_PATH}:$PATH"`)
 
   // 3. cd into makefiles dir for platform, run `make`
-  if (targetBranch !== 'latest-release') {
+  if (branch !== undefined || branch !== null) {
     try {
       spinner.start('Building platform tooling')
       await system.exec('make', { cwd: BUILD_DIR, stdout: process.stdout })

src/toolbox/setup/moddable.ts

@@ -62,18 +62,29 @@ type GitHubRelease = ExtractFromArray<
   RestEndpointMethodTypes['repos']['listReleases']['response']['data']
 >
 
-export async function fetchLatestRelease(): Promise<GitHubRelease> {
+export async function fetchRelease(
+  release: 'latest' | string,
+): Promise<GitHubRelease> {
   const octokit = new Octokit()
-  const { data: latestRelease } = await octokit.rest.repos.getLatestRelease({
-    owner: 'Moddable-OpenSource',
-    repo: 'moddable',
-  })
-  return latestRelease
+  if (release === 'latest') {
+    const { data: latestRelease } = await octokit.rest.repos.getLatestRelease({
+      owner: 'Moddable-OpenSource',
+      repo: 'moddable',
+    })
+    return latestRelease
+  } else {
+    const { data: taggedRelease } = await octokit.rest.repos.getReleaseByTag({
+      owner: 'Moddable-OpenSource',
+      repo: 'moddable',
+      tag: release,
+    })
+    return taggedRelease
+  }
 }
 
 export class MissingReleaseAssetError extends Error {
   constructor(assetName: string) {
-    super(`Unabled to find release asset matching ${assetName}`)
+    super(`Unable to find release asset matching ${assetName}`)
   }
 }
 

src/toolbox/setup/types.ts

@@ -1,5 +1,6 @@
 export interface SetupArgs {
-  targetBranch: 'public' | 'latest-release' | string
+  branch: 'public' | string
+  release: 'latest' | string
 }
 
 export interface PlatformSetupArgs extends SetupArgs {