chore(cli): support and document debugging

packages/cli/README.md

@@ -1,3 +1,31 @@
 # cli
 
-docs coming soon
+## Usage
+
+See usage documentation on the [MUD docs](https://mud.dev/cli/tablegen).
+
+## Development
+
+### Debugging
+
+The CLI can be run in a debug environment:
+
+1. Set the `MUD_PACKAGES` environment variable (see `tsup.config.ts`)
+   ```bash
+   export MUD_PACKAGES=$(tsx ./scripts/log-mud-packages)
+   ```
+2. Setup your debugger with `tsx` as the TypeScript loader and `src/mud.ts` as the entrypoint
+3. Set the arguments to whichever command you want to run (e.g. `deploy`) and its options.
+   - Important: add the `--configPath` option as the path of your project's `mud.config.ts` file, because the current working directory will otherwise be the CLI source.
+
+The CLI should now run in your debugger with TypeScript support.
+
+### Production build
+
+The project can be built for production with `tsup`:
+
+```bash
+pnpm build
+```
+
+`pnpm link` can be used to run the locally-built package.

packages/cli/scripts/log-mud-packages.ts

@@ -0,0 +1,5 @@
+import defineConfig from "../tsup.config";
+
+// Log out the MUD_PACKAGES env var so it can be used to run the CLI in development mode
+// @ts-expect-error: defineConfig return type is not properly inferred
+console.log(defineConfig({}).env.MUD_PACKAGES);

packages/cli/tsup.config.ts

@@ -1,9 +1,12 @@
 import { defineConfig } from "tsup";
 import { globSync } from "glob";
 import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { MudPackages } from "./src/common";
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 const mudWorkspace = path.normalize(`${__dirname}/../..`);
 
 const mudPackages: MudPackages = Object.fromEntries(