@microtronics/studio-cli 1.2.0-alpha.1 → 1.2.0-alpha.11

package/README.md

@@ -1,4 +1,5 @@
 # @microtronics/studio-cli
+
 > The Microtronics Studio CLI Tool
 
 This tool assists in installing, packaging and publishing Microtronics Studio libraries and apps.
@@ -16,22 +17,21 @@ $ npm i -g @microtronics/studio-cli
 ```console
 $ studio-cli --version
 ```
-For a reference on all the available `studio-cli` commands, run `studio-cli --help`
 
+For a reference on all the available `studio-cli` commands, run `studio-cli --help`
 
 ## Requirements
 
 [Node.js](https://nodejs.org/en/) version `22` or higher.
 
-
 ## Standalone executables
 
 Prebuilt single-file binaries are available for users without a [Node.js](https://nodejs.org) installation. They require no `node_modules` and no global npm install. Each binary is built with [`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg) and bundles the Node 22 runtime, the `usb` native addon and the `pawncc-wasm` DLO compiler. macOS is not built for now.
 
-| Platform | Artifact |
-| --- | --- |
-| Windows x64 | `studio-cli-win-x64-<version>.exe` |
-| Linux x64 (glibc) | `studio-cli-linux-x64-<version>` |
+| Platform          | Artifact                           |
+| ----------------- | ---------------------------------- |
+| Windows x64       | `studio-cli-win-x64-<version>.exe` |
+| Linux x64 (glibc) | `studio-cli-linux-x64-<version>`   |
 
 The Linux binary is glibc-linked and does not run on musl-only distributions such as Alpine.
 
@@ -73,6 +73,7 @@ The npm package is unaffected: the binaries are additional artifacts, and `npm i
 ## Commands
 
 ### install (alias: i)
+
 Install all dependencies in your project.
 
 ```console
@@ -85,10 +86,12 @@ project root with `npm install` - an in-sync `package-lock.json` is installed as
 non-workspace projects (or not covered by any workspace pattern) are installed individually with `npm ci`.
 
 **Options:**
+
 - `-e, --env <environment>` - CLI target environment (defaults to STUDIO_ENV environment variable)
 - `--token <API-token>` - API Access Token (defaults to STUDIO_TOKEN environment variable)
 
 **Examples:**
+
 ```console
 $ studio-cli install
 $ studio-cli i
@@ -96,6 +99,7 @@ $ studio-cli install dependency-name
 ```
 
 ### build
+
 Build the project.
 
 ```console
@@ -103,6 +107,7 @@ $ studio-cli build [options]
 ```
 
 **Options:**
+
 - `-p, --part <APM part>` - APM part that should be built
   - Available parts: `dde`, `dlo`, `pov`, `blo`, `dfiles`
 - `-e, --env <environment>` - CLI target environment
@@ -113,6 +118,7 @@ $ studio-cli build [options]
 You can overwrite manifest options using the `--option=value` syntax.
 
 **Examples:**
+
 ```console
 $ studio-cli build
 $ studio-cli build --part dlo
@@ -121,6 +127,7 @@ $ studio-cli build --dlo.mainFile="./dlo/test.dlo"
 ```
 
 ### publish
+
 Publish the project to the registry.
 
 ```console
@@ -128,6 +135,7 @@ $ studio-cli publish [options]
 ```
 
 **Options:**
+
 - `-ph, --phase <release phase>` - Specify a release phase (default: `release`)
   - Available phases: `alpha`, `beta`, `rc`, `release`, `stage`, `passive`, `withdrawn`
 - `--allowedBackends <null|*|server.xz;server.yz>` - Specify the allowedBackends deployment for this version
@@ -140,6 +148,7 @@ $ studio-cli publish [options]
 - `-i, --packagePath <path>` - Publish the provided library or app package. Use "*" for autodetection
 
 **Examples:**
+
 ```console
 $ studio-cli publish
 $ studio-cli publish --phase beta
@@ -148,6 +157,7 @@ $ studio-cli publish --packagePath ./my-package.tar.gz --env wynni
 ```
 
 ### package (alias: pack)
+
 Package the project.
 
 ```console
@@ -155,6 +165,7 @@ $ studio-cli package [options]
 ```
 
 **Options:**
+
 - `-ph, --phase <release phase>` - Specify a release phase (default: `release`)
   - Available phases: `alpha`, `beta`, `rc`, `release`, `stage`, `passive`, `withdrawn`
 - `-e, --env <environment>` - CLI target environment
@@ -162,6 +173,7 @@ $ studio-cli package [options]
 - `--token <API-token>` - API Access Token
 
 **Examples:**
+
 ```console
 $ studio-cli package
 $ studio-cli pack --phase alpha
@@ -169,6 +181,7 @@ $ studio-cli pack --env wynni
 ```
 
 ### run
+
 Build, upload to USB device, and create development site on myDatanet. This command is designed for development and integration testing purposes.
 
 ```console
@@ -176,6 +189,7 @@ $ studio-cli run -s <serial> --server <url> [options]
 ```
 
 **Options:**
+
 - `-s, --serial <serial>` - Device serial number (16 characters hex) **[required]**
 - `--server <url>` - myDatanet instance URL (https:// prefix optional). Defaults to `MYDATANET_HOST` environment variable
 - `--customer <customerId>` - myDatanet customer UID or ID. Defaults to `MYDATANET_CUSTOMER` environment variable
@@ -191,6 +205,7 @@ $ studio-cli run -s <serial> --server <url> [options]
 - `--siteName <name>` - Override the auto-generated development site name (max 50 characters). By default, the site name is derived from the device serial number (for DLO projects) or from the app name and current user (e.g. `MyApp_JohnDoe`)
 
 **Exit Codes:**
+
 - `0` - Success
 - `1` - Build failed
 - `2` - USB device not found
@@ -201,16 +216,19 @@ $ studio-cli run -s <serial> --server <url> [options]
 
 **Output:**
 On success, the command outputs:
+
 - Site UID of the newly created/reused development site
 - Site name
 - APM ID of the development tag
 
 With `--json`, the output is a single JSON line:
+
 ```json
-{"siteUid":"<uid>","siteName":"<name>","apmId":"<id>"}
+{ "siteUid": "<uid>", "siteName": "<name>", "apmId": "<id>" }
 ```
 
 **Examples:**
+
 ```console
 # Basic usage with environment variables
 $ export MYDATANET_TOKEN=your_token
@@ -235,9 +253,11 @@ $ studio-cli run -s 1234567890ABCDEF --server myserver.mydatanet.net --silent --
 ```
 
 ### usb
+
 USB device management commands.
 
 #### usb list
+
 List available USB devices.
 
 ```console
@@ -245,6 +265,7 @@ $ studio-cli usb list
 ```
 
 #### usb upload
+
 Upload an AMX binary to a USB device.
 
 ```console
@@ -252,17 +273,20 @@ $ studio-cli usb upload -s <serial> -f <path> [--debug]
 ```
 
 **Options:**
+
 - `-s, --serial <serial>` - Device serial number (16 characters hex) **[required]**
 - `-f, --file <path>` - Path to the AMX file (relative to current directory) **[required]**
 - `--debug` - Enable debug logging
 
 **Example:**
+
 ```console
 $ studio-cli usb upload -s 1234567890ABCDEF -f ./app.amx
 $ studio-cli usb upload -s 1234567890ABCDEF -f ./app.amx --debug
 ```
 
 #### usb sync
+
 Sync a USB device with the myDatanet server. This triggers a full device synchronization including optional MNT and MDN communication phases.
 
 ```console
@@ -270,15 +294,126 @@ $ studio-cli usb sync -s <serial> [--debug]
 ```
 
 **Options:**
+
 - `-s, --serial <serial>` - Device serial number (16 characters hex) **[required]**
 - `--debug` - Enable debug logging (shows sync mode, phases, and message counts)
 
 **Example:**
+
 ```console
 $ studio-cli usb sync -s 1234567890ABCDEF
 $ studio-cli usb sync -s 1234567890ABCDEF --debug
 ```
 
+### dev
+
+Build, flash and serve a **myDatanet-compatible REST API for the attached USB device** on localhost, using the
+project's own `dist/dde/dde.xml` as the data model. Reads are served from an in-memory mirror that a stamp poller
+keeps in sync with the device; writes are encoded via the project DDE and pushed as UTO `DATA` frames.
+
+```console
+$ studio-cli dev -s <serial> [options]
+```
+
+**Options:**
+
+- `-s, --serial <serial>` - Device serial number (16 characters hex) **[required unless `--replay`]**
+- `--replay <file>` - Support/forensics mode: replay a companion-app flight-recorder export (`.ndjson` or `.db`)
+  instead of a live device. Mutually exclusive with `--serial`; forces no build/flash/watch. Only the AT/debug
+  channel is byte-exact in a recording, so `/api/1/...` answers the empty/`E_EOD` envelope - `/dev/logs`,
+  `/events` and `device at` (TX-matched against the recording) still work.
+- `--session <id>` - Recording session to replay (default: the session with the most records)
+- `--speed <n|max>` - Replay speed multiplier, or `max` for no recorded delays (default `1`, real-time)
+- `--port <port>` - HTTP port (default `8765`)
+- `--host <host>` - Bind address (default `127.0.0.1`)
+- `--allow-remote` - Permit a non-loopback `--host` without `--bearer`
+- `--watch` - Rebuild, flash and sync on changes under `dlo/`, `dde/`, `app.ini`, `studio.json`
+- `--no-build` / `--no-flash` - Skip the initial build / the `dist/dlo/main.amx` upload
+- `--poll-interval <ms>` - Stamp-poll interval (default `2000`, `0` disables)
+- `--wait <ms>` - How long a write waits for the device to confirm it (default `3000`)
+- `--log-file [path]` - Append every log record as JSONL (default `.studio/dev/device.jsonl`)
+- `--bearer <token>` - Require this bearer token (`--token` stays the Studio API token)
+- `--pov [name]` - Also start `npm run dev -w pov/<name>` (default `details`) with `MYDATANET_HOST` injected
+- `--json` - Print one JSON line `{url, serial, apmId, port}`, then JSONL events
+
+Without `--bearer`, any incoming `Authorization` header is ignored, so a POV dev server proxying its
+`MYDATANET_TOKEN` works unchanged. `/api/1/sites/<uid>/...` accepts **any** site uid.
+
+A non-loopback `--host` (for example `0.0.0.0`) without `--bearer` would expose container writes, AT commands
+and flashing to everyone who can reach the port, so it is **refused**. Pass `--bearer <token>`, or
+`--allow-remote` to bind unauthenticated anyway - which logs a warning.
+
+Numeric options (`--port`, `--poll-interval`, `--wait`, and `--limit`/`--duration` on the `device`
+subcommands) must be integers in range; anything else is reported and exits with code `1`.
+
+In a non-`--json` TTY session, stdin accepts `at <cmd>`, `sync`, `flash`, `build` and `q`.
+
+**Endpoints:**
+
+| Method / path                                       | Purpose                                                                                      |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `/api/1/sites/<uid>/...`                            | myDatanet-compatible containers, timeseries, blueprint, `/api/1/me`, legacy `config[0-9a-c]` |
+| `GET /dev/status`                                   | Serial, connection, model containers, last sync, build state, poll status, `replay` when `--replay` |
+| `POST /dev/build`                                   | Run the build; returns diagnostics                                                           |
+| `POST /dev/flash`                                   | Upload `dist/dlo/main.amx` (or `{"file": "..."}`)                                            |
+| `POST /dev/sync`                                    | Full sync, or a targeted pull with `{"tags": [...]}`                                         |
+| `GET /dev/logs`                                     | Ring buffer (5000 records), `?since=<seq>&limit=`                                            |
+| `POST /dev/at`                                      | One AT command, `{"cmd": "at+rm2mstate"}`                                                    |
+| `GET /dev/state`                                    | Last rm2m state                                                                              |
+| `GET /dev/localdata`, `POST /dev/localdata/measure` | Live local-data values / trigger a measurement                                               |
+| `GET /dev/openapi.json`                             | `dist/api/main.yaml` merged with the `/dev/*` paths                                          |
+| `GET /events`                                       | SSE: `log`, `state`, `sync`, `build`, `uto`, `container-changed`; `?types=log,build` filters |
+
+Errors use the myDatanet envelope `{"err": "E_CODE message"}`. A write whose device confirmation did not arrive
+within `--wait` is answered with the header `x-mt-mirror: stale`; `?async=1` skips the wait entirely.
+
+**Agent workflow:**
+
+```console
+$ studio-cli dev -s 1234567890ABCDEF --watch --json &   # server + auto build/flash on save
+$ curl :8765/dev/openapi.json                           # discover this project's API
+$ curl -X PUT :8765/api/1/sites/dev/containers/command -d '{"param1":3,"param2":4}'
+$ curl :8765/api/1/sites/dev/containers/state            # -> {"sum":7} (the DLO wrote it)
+$ curl ':8765/dev/logs?since=0'                          # rm2mlog / printf output
+```
+
+### device
+
+One-shot, agent-friendly device commands: connect, act, disconnect. Every subcommand accepts
+`--url http://127.0.0.1:8765` to run against an already-running `studio-cli dev` server instead of opening USB
+(the USB device is single-owner - the server holds it), plus `--json`, `--silent` and `--debug`.
+
+```console
+$ studio-cli device <command> -s <serial> [options]
+```
+
+| Command                    | Purpose                                                                |
+| -------------------------- | ---------------------------------------------------------------------- |
+| `info`                     | DEVINFO/STAMPS-derived status and the model's containers               |
+| `get <container>[.field]`  | Read a container, decoded via the project DDE                          |
+| `set <container> <values>` | Encode a JSON object, push it, re-read the container                   |
+| `timeseries <container>`   | Histdata window; `--from`, `--to`, `--limit`                           |
+| `logs`                     | Ring buffer; `--follow`, `--duration <ms>`, `--filter <regex>`         |
+| `at <cmd>`                 | One AT command                                                         |
+| `state`                    | Last rm2m state                                                        |
+| `flash`                    | `usb upload` defaulting to `dist/dlo/main.amx`; `-f, --file` overrides |
+| `sync`                     | Pull the device data into the mirror (alias of `usb sync`'s intent)    |
+
+`device set` prints `{container, written, stale, record}`. `stale: true` means the device did not confirm the
+push within `--wait` (the mirror holds the value, the device may not) - the command still exits `0`; check the
+flag rather than the exit code.
+
+**Exit codes:** `0` success, `1` build failed, `2` device not found, `3` USB/UTO error, `7` no
+`dist/dde/dde.xml` (run `studio-cli build` first), `8` unknown container/field, `9` write forbidden.
+
+**Examples:**
+
+```console
+$ studio-cli device get command --url http://127.0.0.1:8765 --json
+$ studio-cli device set command '{"param1":3}' -s 1234567890ABCDEF --json
+$ studio-cli device logs -s 1234567890ABCDEF --follow --duration 10000
+```
+
 ## Library APM parts: version and dependencies
 
 Studio libraries (`type: "library"`) ship npm-consumable APM parts as `dist/blo/package.json` and