feat: add clean and debug commands (#169)

* feat: add clean command

* feat: add debug command

docs/src/content/docs/features/run.md

@@ -105,3 +105,37 @@ If you want to immediately deploy the release build, use the `--deploy` flag:
 ```
 xs-dev build --deploy --device esp32
 ```
+
+## Connect to running debugger sessions
+
+To conveniently restart a debugging session without redeploying the project, the `debug` 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 launch xsbug or the terminal debugger for the selected device or simulator.
+
+```
+xs-dev debug --device esp32
+```
+
+It even works with example projects:
+
+```
+xs-dev debug --example helloworld
+```
+
+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 debug --output ./dist --device esp32
+```
+
+## Cleaning up build artifacts
+
+The Moddable build tooling will do it's best to avoid repeating work to ensure quick incremental updates when recompiling programs or skipping compilation entirely if no changes have been made to the source code and config files. Whether it is to force a full recompile of your project or to make space on your development machine, the `clean` command is here to help! It takes the same flags as the `build` and `run` commands (except for "port" and "deploy") to invoke [`mcconfig`](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#mcconfig) with the required `clean` target.
+
+```
+xs-dev clean --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 clean --output ./dist --device esp32
+```

src/commands/clean.ts

@@ -0,0 +1,50 @@
+import type { GluegunCommand } from 'gluegun'
+import { type as platformType } from 'os'
+import type { Device, XSDevToolbox } from '../types'
+import { DEVICE_ALIAS } from '../toolbox/prompt/devices'
+
+type Mode = 'development' | 'production'
+
+interface CleanOptions {
+  device?: Device
+  example?: string
+  listExamples?: boolean
+  listDevices?: boolean
+  mode?: Mode
+  output?: string
+  config?: Record<string, string>
+}
+
+const command: GluegunCommand<XSDevToolbox> = {
+  name: 'clean',
+  description: 'Remove build artifacts for project',
+  run: async ({ parameters, filesystem, build }) => {
+    const currentPlatform: Device = platformType().toLowerCase() as Device
+    const {
+      device = currentPlatform,
+      example,
+      listExamples = false,
+      listDevices = false,
+      mode = (process.env.NODE_ENV as Mode) ?? 'development',
+      output,
+      config = {}
+    }: CleanOptions = parameters.options
+    const targetPlatform: string = DEVICE_ALIAS[device] ?? device
+    const projectPath = filesystem.resolve(parameters.first ?? '.')
+
+    await build({
+      listExamples,
+      listDevices,
+      example,
+      targetPlatform,
+      projectPath,
+      mode,
+      deployStatus: 'clean',
+      outputDir: output,
+      config
+    })
+  },
+}
+
+export default command
+

src/commands/debug.ts

@@ -0,0 +1,52 @@
+import type { GluegunCommand } from 'gluegun'
+import { type as platformType } from 'os'
+import type { Device, XSDevToolbox } from '../types'
+import { DEVICE_ALIAS } from '../toolbox/prompt/devices'
+
+type Mode = 'development' | 'production'
+
+interface DebugOptions {
+  device?: Device
+  port?: string
+  example?: string
+  listExamples?: boolean
+  listDevices?: boolean
+  log?: boolean
+  mode?: Mode
+  output?: string
+}
+
+const command: GluegunCommand<XSDevToolbox> = {
+  name: 'debug',
+  description: 'Connect to running debugging session on target device or simulator',
+  run: async ({ parameters, filesystem, build }) => {
+    const currentPlatform: Device = platformType().toLowerCase() as Device
+    const {
+      device = currentPlatform,
+      port,
+      example,
+      listExamples = false,
+      listDevices = false,
+      log = false,
+      mode = (process.env.NODE_ENV as Mode) ?? 'development',
+      output,
+    }: DebugOptions = parameters.options
+    const targetPlatform: string = DEVICE_ALIAS[device] ?? device
+    const projectPath = filesystem.resolve(parameters.first ?? '.')
+
+    await build({
+      port,
+      listExamples,
+      listDevices,
+      log,
+      example,
+      targetPlatform,
+      projectPath,
+      mode,
+      deployStatus: 'debug',
+      outputDir: output,
+    })
+  },
+}
+
+export default command

src/toolbox/build/index.ts

@@ -9,7 +9,7 @@ import { DEVICE_ALIAS } from '../prompt/devices'
 import { Device } from '../../types'
 import { sourceEnvironment } from '../system/exec'
 
-export type DeployStatus = 'none' | 'run' | 'push'
+export type DeployStatus = 'none' | 'run' | 'push' | 'clean' | 'debug'
 
 export interface BuildArgs {
   port?: string
@@ -25,6 +25,14 @@ export interface BuildArgs {
   config?: Record<string, string>
 }
 
+const DEPLOY_TARGET: Readonly<Record<DeployStatus, string>> = Object.freeze({
+  clean: 'clean',
+  debug: 'xsbug',
+  none: 'build',
+  push: 'build',
+  run: 'all',
+})
+
 export async function build({
   listDevices,
   port,
@@ -226,15 +234,24 @@ export async function build({
 
   const spinner = print.spin()
 
-  spinner.start(
-    `Building${deployStatus !== 'none' ? ' and deploying project' : ''
-    } ${projectPath} on ${targetPlatform}\n`
-  )
+  switch (deployStatus) {
+    case 'clean':
+      spinner.start(`Cleaning up build artifacts for project ${projectPath} on ${targetPlatform}\n`)
+      break;
+    case 'debug':
+      spinner.start(`Connecting to running debug session for ${projectPath} on ${targetPlatform}\n`)
+      break;
+    default:
+      spinner.start(
+        `Building${deployStatus !== 'none' ? ' and deploying project' : ''
+        } ${projectPath} on ${targetPlatform}\n`
+      )
+  }
 
   const configArgs = [
     '-m',
     `-p ${targetPlatform}`,
-    `-t ${deployStatus === 'run' ? 'all' : 'build'}`,
+    `-t ${DEPLOY_TARGET[deployStatus]}`,
     `-o ${outputDir}`,
   ]
   if (mode === 'development') configArgs.push('-d')