CLI (#22)

* scaffold a cli configuration

* wire up ui and call commands

* run command impl

* prevent auto close of stream, task.halt on event

* remove inflight and instead capture with a single scope

* simplify server

* remove some sse-client error expectations

these are now handled by the server

* update readme with CLI instructions

* send undefined return as default if screen lives forever

* 🔧 send null instead of undefined for stream return values

- Change protocol schema from Undef to Null for watchScopes and
  recordNodeMap return types
- Add truncate() stream operator to convert arbitrary close values to null
- Rework SSE server to use explicit resource management for subscriptions
- Handle connection close state properly in UI data layer
- Simplify SSE client by removing undefined string parsing workaround

* swap out context api for middleware createApi

* lockfile

* move cli to folder

* handle node, deno and bun runtimes

* fmt

* test off suspended example

* prepend host and runtime with inspect

* add missing types needed for strip-types

* remove tsx as dev dep

* loader logs write to stderr

* remove special export handler, fix config types

* wait for process ready before fetch

* shift to multi-config loaders

* fix alias for require

* parse-sse as dep

* add finally to forever example

* dance a bit to allow process to write finally

* handle multiple module loaders

* handle entrypoint explicitly

* remove unused deps

* entrypoint removed arg passthrough

* entrypoint no longer throws

* ui can take a port

* recording error is less scary

* pin on minor configliere

* lint

---------

Co-authored-by: Charles Lowell <cowboyd@frontside.com>

Author: jbolda

.oxfmtrc.json

@@ -1,4 +1,7 @@
 {
   "$schema": "./node_modules/oxfmt/configuration_schema.json",
-  "ignorePatterns": []
+  "ignorePatterns": [],
+  "sortPackageJson": {
+    "sortScripts": true
+  }
 }

.oxlintrc.json

@@ -3,6 +3,7 @@
   "plugins": null,
   "categories": {},
   "rules": {
+    "typescript/consistent-type-imports": ["error", { "fixStyle": "inline-type-imports" }],
     "require-yield": "off",
     "no-unused-vars": [
       "error",

CONTRIBUTING.md

@@ -24,7 +24,7 @@ This runs Vite and serves the Crank-based inspector UI. Open http://localhost:51
 To run server with the example file, use:
 
 ```shell
-node --import tsx --import ./loader.ts examples/example.ts --suspend
+node --experimental-strip-types --import ./loader.ts examples/spawn-children.ts --suspend
 ```
 
 This will run the loader with an example effection program. It serves both a live stream of data, and also the built files for the UI. If you are working on the UI on the `/live` integration, you may need to use both of these dev servers, and `localhost:5173` appropriately proxies to port `:41000`. If you have run a `pnpm run build`, then you can directly visit http://localhost:41000.

README.md

@@ -1,52 +1,85 @@
 # inspector
 
-Helpers to inspect an effection tree.
+Helpers to inspect an effection tree. These utilities can be used through `npx` or similar or installed as a dev dependency.
 
 ## Running
 
-### Live
-
-Start your application with the inspector loader so it runs alongside your app.
-
-Node:
+When the package is installed as a dev dependency the binary is available in
+`node_modules/.bin/inspector`; you can also invoke it directly with npx:
 
 ```bash
-node --import @effectionx/inspector ./your-app.js --suspend
+npx @effectionx/inspector [options] <command> [args]
+# or when installed as a dev dependency
+inspector [options] <command> [args]
 ```
 
-Deno:
+Use `npx @effectionx/inspector help` to explore available commands. Typically you will run to inspector in "live" mode or "record" more.
 
-```bash
-deno run --preload npm:@effectionx/inspector ./your-app.ts --suspend
+Under the hood the CLI chooses which binary to execute based on the `--runtime` option or, if you omit that, it will guess from the process that started the CLI, either `node`, `deno`, or `bun`.
+
+These raw `call` commands mirror the behaviour of the HTTP routes produced by the same code that powers the SSE server (see `lib/sse-server.ts`).
+
+### Live
+
+Start your application with the inspector loader so it runs alongside your app.
+
+```shell
+# generate a recording, but also pause
+inspector --inspect-pause --experimental-strip-types program.ts
 ```
 
-When started this way the inspector will launch a small SSE server (default port: 41000) and serve the UI at `http://localhost:41000`.
+When started directly with the loader, the inspector will launch a small SSE server (default port: 41000) and serve the UI at `http://localhost:41000`. You will need to "play" or continue execution of your program when you use `--inspect-pause`. This gives you time to load the UI, and press the play button or issue the "play" call, e.g. `npx @effectionx/inspector call play`.
 
 ### Recording ✅
 
-The UI supports loading saved recordings useful for review and sharing. From the Home screen click `Load Recording` > `Browse files` and choose a `.json` or `.effection` file. A recording is a JSON array of NodeMap snapshots. The inspector accepts `.json` and `.effection` files.
+The UI supports loading saved recordings useful for review and sharing. From the Home screen click `Load Recording` > `Browse files` and choose the `.json` or `.effection` file. A recording is a JSON array of NodeMap snapshots. The inspector accepts `.json` and `.effection` files.
 
 #### Creating a recording from a live session:
 
-You can capture the SSE stream from a running inspector and save the emitted data. Start by using [the instructions for running the process live](#live).
+You can capture the SSE stream from a running inspector and save the emitted data. It is run similarly with an additional `--inspect-record` argument.
 
-```bash
-# Start capturing and it will close once your effection process closes
-curl -sN -X POST http://localhost:41000/recordNodeMap \
-  -H "Accept: text/event-stream" -d '[]' \
-  | jq -R -s 'split("\n") | map(select(startswith("data: "))) | map(.[6:] | fromjson)' \
-  > recording.json
+```shell
+# generate a recording, but also pause
+inspector --inspect-record=output.json --experimental-strip-types program.ts
 ```
 
-If you started the inspected process with `--suspend`, click the red Play button in the inspector header (next to the `live` badge) to resume execution — the UI issues the appropriate POST for you.
+If you started the inspected process with `--inspect-pause`, click the play button or issue the "play" call, e.g. `npx @effectionx/inspector call play`.
 
-If you prefer the command line, the same request can be made manually:
+## CLI Examples
 
 ```bash
-curl -s -X POST http://localhost:41000/play -H 'Content-Type: application/json' -d '[]'
+# query the default server
+inspector call getScopes
+
+# record output
+inspector call watchScopes --out=events.json
+
+# use the alias
+inspector c recordNodeMap
+
+# inspect and run a script (node assumed by default)
+inspector program.js
+
+# override runtime explicitly
+inspector --runtime deno --inspect-pause program.ts
+# or when using bun:
+inspector --runtime bun program.js
+
+# pass through runtime flags
+inspector --experimental-strip-types program.ts
+inspector --import=tsx program.ts
+
+# generate a recording, but also pause
+inspector --inspect-pause --inspect-record=recording.inspector.json --import=tsx program.ts
+# generate a recording, but begin execution immediately
+inspector --inspect-record=recording.inspector.json --import=tsx program.ts
 ```
 
-You can also monitor player state with `/watchPlayerState`.
+Pause behaviour is communicated to the loader via the `INSPECT_PAUSE` environment variable, and using `--inspect-pause` sets that for you. When running the program with the CLI, the program is run through the loader with the environment variable passed, e.g.:
+
+```bash
+INSPECT_PAUSE=1 node --import @effectionx/inspector ./your-app.js
+```
 
 ## Contributing
 

cli/build-run-args.ts

@@ -0,0 +1,119 @@
+import type { ExecOptions } from "@effectionx/process";
+import process from "node:process";
+import type { RunConfig } from "./config.ts";
+
+export type Runtime = "node" | "deno" | "bun";
+
+function hasLoaderSpecified(packageName: string) {
+  return (args: string[] | undefined) => {
+    return !!args && args.some((imp) => imp.includes(packageName));
+  };
+}
+
+export function buildProcessOptions(
+  runtime: Runtime,
+  config: RunConfig,
+  passthroughArgs: string[],
+): ExecOptions {
+  let env = { ...process.env } as Record<string, string>;
+
+  if (config.inspectPause) {
+    env.INSPECT_PAUSE = "1";
+  }
+  if (config.inspectPort && config.inspectPort !== 41000) {
+    env.INSPECT_PORT = String(config.inspectPort);
+  }
+
+  const args = [] as string[];
+  if (runtime === "deno") {
+    // deno requires the `run` subcommand and permissions
+    args.push("run", "--allow-run=deno");
+  }
+
+  // we make the assumption that if the user is setting the loader they know which
+  // environment is being used and that it is properly passed, e.g. uses `--import` for node
+
+  const hasLoader = hasLoaderSpecified(config.inspectPackage);
+  switch (runtime) {
+    case "node": {
+      if (config.preload.length) {
+        throw new Error("preload is not supported for node runtime; use --import instead");
+      }
+
+      // gather any imports or requires the user provided
+      const provided = [...config.import, ...config.require];
+
+      // if the inspector loader isn't already in the list, prepend it
+      if (!hasLoader(provided)) {
+        args.push("--import", config.inspectPackage);
+      }
+
+      // always forward the explicit arguments the user gave
+      if (provided.length > 0) {
+        const direct = provided.flatMap((d) => ["--import", d]);
+        args.push(...direct);
+      }
+      break;
+    }
+    case "deno": {
+      if (config.import.length || config.require.length) {
+        throw new Error("preload is not supported for deno runtime; use --preload instead");
+      }
+
+      const provided = [...config.preload];
+      if (!hasLoader(provided)) {
+        args.push("--preload", `npm:${config.inspectPackage}`);
+      }
+
+      if (provided.length > 0) {
+        const direct = provided.flatMap((d) => ["--preload", d]);
+        args.push(...direct);
+      }
+      break;
+    }
+    case "bun": {
+      if (config.import.length || config.preload.length) {
+        throw new Error("preload is not supported for bun runtime; use --require instead");
+      }
+
+      const provided = [...config.require];
+      if (!hasLoader(provided)) {
+        args.push("--require", config.inspectPackage);
+      }
+
+      if (provided.length > 0) {
+        const direct = provided.flatMap((d) => ["--require", d]);
+        args.push(...direct);
+      }
+      break;
+    }
+  }
+
+  if (passthroughArgs) {
+    args.push(...passthroughArgs.filter((arg) => arg !== "--"));
+  }
+
+  return { arguments: args, env };
+}
+
+/**
+ * Determine which runtime should be used for execution.  Explicit `runtime`
+ * configuration takes precedence; otherwise we try to guess from `process.execPath`.
+ *
+ * Most invocations occur through `npx`/`pnpx` which itself is a Node process,
+ * hence the default is still "node".  If the executable name contains
+ * "deno" or "bun" we return the corresponding runtime.
+ */
+export function resolveRuntime(config: RunConfig): Runtime {
+  if (config.inspectRuntime) {
+    return config.inspectRuntime as Runtime;
+  }
+  let exec = process.execPath;
+  if (exec.includes("deno")) {
+    return "deno";
+  }
+  if (exec.includes("bun")) {
+    return "bun";
+  }
+  return "node";
+}

cli/config.ts

@@ -0,0 +1,112 @@
+import { commands, field, object, program, help } from "configliere";
+import packageJSON from "../package.json" with { type: "json" };
+import { type } from "arktype";
+import { scope, player } from "../lib/protocols.ts";
+import { combine } from "../mod.ts";
+import type { ParsedConfig } from "./types.ts";
+
+export const inspector = combine.protocols(scope.protocol, player.protocol);
+
+const commandBase = object({
+  out: {
+    description: "write out the response to a file",
+    ...field(type("string | undefined"), field.default(undefined)),
+  },
+  host: {
+    description: "inspector base URL (overrides default)",
+    ...field(type("string"), field.default("http://localhost:41000")),
+  },
+});
+type InspectorProtocolCommandBase = Record<
+  keyof typeof inspector.methods,
+  { description: string } & typeof commandBase
+>;
+const inspectorProtocolEntries = (
+  Object.keys(inspector.methods) as (keyof typeof inspector.methods)[]
+).reduce((base, current) => {
+  base[current] = {
+    description: `/${current} API`,
+    ...commandBase,
+  };
+  return base satisfies InspectorProtocolCommandBase;
+}, {} as InspectorProtocolCommandBase);
+
+const protocolCommands = commands(inspectorProtocolEntries);
+
+export type ProtocolCommandConfig = ParsedConfig<typeof protocolCommands>;
+
+const runBase = object({
+  // TODO this throws an error if we have a remainder of more than one arg,
+  // which is a problem for the `run` command since we want to support passing
+  // through args to the program being run.
+  // entrypoint: {
+  //   description: "entrypoint file",
+  //   ...field(type("string"), cli.argument()),
+  // },
+  inspectRecord: {
+    description: "write inspector recording to the given file",
+    ...field(type("string | undefined"), field.default(undefined)),
+  },
+  inspectRuntime: {
+    description:
+      "which JavaScript runtime to launch (node, deno, bun).\n" +
+      "If omitted we infer from the executable that invoked the CLI",
+    ...field(type("'node'|'deno'|'bun'"), field.default("node")),
+  },
+  inspectPause: {
+    description: "start program paused until resumed by inspector",
+    ...field(type("boolean"), field.default(false)),
+  },
+  inspectPort: {
+    description: "port number to give to the inspector loader",
+    ...field(type("number"), field.default(41000)),
+  },
+  inspectPackage: {
+    description: "package spec to preload/import/require (defaults to @effectionx/inspector)",
+    ...field(type("string"), field.default("@effectionx/inspector")),
+  },
+  import: {
+    description: "tracking loader passed in from the user",
+    ...field(type("string[]"), field.array(), field.default([])),
+  },
+  preload: {
+    description: "tracking loader passed in from the user",
+    ...field(type("string[]"), field.array(), field.default([])),
+  },
+  require: {
+    description: "tracking loader passed in from the user",
+    aliases: ["-r"],
+    ...field(type("string[]"), field.array(), field.default([])),
+  },
+});
+
+export const config = program({
+  name: "inspector",
+  version: packageJSON.version,
+  config: commands(
+    {
+      help,
+      ui: {
+        description: "start up the inspector UI",
+        ...object({
+          inspectPort: {
+            description: "port number to give to the inspector loader",
+            ...field(type("number"), field.default(41000)),
+          },
+        }),
+      },
+      call: {
+        description: "invoke a inspector protocol method directly (low level)",
+        aliases: ["c"],
+        ...protocolCommands,
+      },
+      run: {
+        description: "inspect a CLI program",
+        ...runBase,
+      },
+    },
+    { default: "run" },
+  ),
+});
+
+export type RunConfig = ParsedConfig<typeof runBase>;