tirtc-devtools-cli 0.0.1

package/README.md

@@ -0,0 +1,52 @@
+# TiRTC DevTool CLI
+
+`devtools/cli/` 承接 `TiRTC DevTool CLI`。它是当前唯一用户界面的产品门面 (command client)，为用户提供了一套操作 `Matrix Host` 控制面的终端工具。
+
+## 使用说明 (C-Lite)
+
+关于 `tirtc-devtool` 命令的详细使用方法、参数说明与示例，请参考 [USAGE.md](./USAGE.md)。
+
+## 负责什么
+
+- **唯一用户产品门面**：提供 `tirtc-devtool` 命令族，覆盖常见的 RTC 测试操作，让内部研发、外部开发者和 AI agent 脚本无需手写底层协议。
+- **配置解析与翻译**：负责解析用户传入的 CLI 参数和 TOML 配置文件，进行本地必填校验、脱敏，并翻译为 App Server 协议的 request。
+- **产品级 Observability**：将底层的运行时事件和状态翻译为结构化输出 (JSON) 或友好的终端日志输出。
+- **调试期工具内聚**：承接调试期必要工具（如 token bootstrap、二维码与媒体预处理）的产品化入口，避免把调试流程散落在 runtime 或外部手工步骤中。
+- **本地 token 工具**：提供直接签发 token、打印组合 JSON、单独 token 与本地二维码 PNG 路径的公开 CLI 能力，服务本地联调与体验验证。
+
+## 不负责什么
+
+- **不拥有底层 RTC 能力**：它只是一个客户端门面，它自己不负责跑 RTC 媒体栈，所有的执行能力均交由底层的 `Matrix Host` 进程完成。
+- **不重新定义协议**：不私自发明 undocumented control path；CLI 命令到 Host method 的映射必须与协议文档保持一一对应。
+- **不把 App Server 变成业务服务**：鉴权签发等能力仅用于本地联调 bootstrap，不替代正式业务系统。
+
+## 依赖方向
+
+- **依赖 `app-server/protocol-client/`**：通过可复用的第一方协议客户端与 `Matrix Host` 进程通信。
+- **绝不依赖 `runtime/` 代码实现**：CLI 不直接链接 runtime 模块，只消费 app-server 打包好的运行时产物与 Host 协议。
+
+## 这里应该放什么
+
+- CLI 命令行入口、命令树 (Commands) 的注册与参数解析逻辑。
+- 配置文件 (TOML) 的读取与校验逻辑。
+- 终端交互、控制台进度打印、结构化输出等 UI 面板逻辑。
+- 与 `protocol-client/` 交互并把业务结果展示给用户的封装逻辑。
+
+## 代码规范与 lint
+
+- TypeScript 代码规范通过 `eslint` 承接，配置文件位于 `devtools/cli/.eslintrc.cjs`。
+- 本目录作者侧收口命令：`npm run lint`、`npm test`、`npm run build`。
+- 仓库级 gate 会通过 `./script/lint_node_products.sh` 在 `pre-commit` 与 `./script/check.sh` 中统一执行 Node 产品 lint。
+
+## 开发与构建
+
+- `npm run build`：执行 TypeScript 编译。
+- `npm test`：运行 CLI 门面与 Smoke 测试。
+- `npm run package`：执行 `./script/package.sh`，构建 CLI 本体并同步 npm 发布所需的 app-server/runtime vendor 资产。
+- 运行 `media assets prepare` 时，CLI 会优先复用系统 `ffmpeg/ffprobe`；若本机不存在，则首次使用时自动下载到用户缓存目录。
+
+## Runtime E2E Tester Config
+
+- 本地测试配置文件路径：`devtools/cli/tests/.local/runtime-backed.e2e.local.json`（必需，已在 `.gitignore` 忽略）。
+- 示例模板：`devtools/cli/tests/runtime-backed.e2e.config.example.json`。
+- 推荐先运行 `tirtc-devtool media assets prepare --source .refers/simple.mp4 --output-root ./.tmp/tirtc-devtool/assets`，再把 `assetsDir` 指向返回的 `assets_dir`。

package/USAGE.md

@@ -0,0 +1,417 @@
+# TiRTC DevTool CLI（用户手册）
+
+`tirtc-devtool` 是基于 `app-server/host` 的命令行门面，用来控制会话、服务、连接、流、命令通道与调试工具。
+
+## 一、先说清楚关系
+
+- Runtime：底层内核能力（transport/audio/video/media/facade）。
+- App Server：把 Runtime 组织成稳定控制面协议（Host 进程）。
+- CLI（`devtools/cli`）：面向用户的命令行门面，通过协议控制 App Server。
+
+也就是说：CLI 不是独立重做一套 RTC 能力，而是消费 App Server；App Server 再消费 Runtime。
+
+## 二、如何编译“最新”CLI
+
+你提到的重点是对的：不仅要“安装”，还要能拿到**最新源码构建产物**。
+
+### 1) 开发态构建（最快）
+
+```bash
+npm --prefix app-server ci && \
+ npm --prefix devtools/cli ci && \
+ npm --prefix app-server run build && \
+ npm --prefix devtools/cli run build
+```
+
+构建后可直接运行：
+
+```bash
+node devtools/cli/bin/tirtc-devtool.js --help
+```
+
+### 2) 发布态打包（可分发二进制）
+
+按统一链路执行（先准备 runtime，再打包产品）：
+
+```bash
+./runtime/script/prepare_product_runtime.sh --platform macos-arm64 --consumer both
+./app-server/script/package.sh
+./devtools/cli/script/package.sh
+```
+
+产物位置：
+
+- App Server：`app-server/bin/dist/`
+- CLI：`devtools/cli/bin/dist/`
+
+### 3) 一键验收（推荐）
+
+```bash
+./script/acceptance_app_server_devtools.sh
+```
+
+## 三、全局参数
+
+- `--config <path>`：TOML 配置文件路径。
+- `--json`：结构化 JSON 输出。
+- `--session <sessionId>`：指定会话（除 `service start` / `connection connect` 外必须显式传）。
+
+## 四、会话模型
+
+一个 session = 一个常驻 Host 进程 + 一个 endpoint runtime 实例。
+
+- `tirtc-devtool host session start`：创建会话，返回 `sessionId`
+- `tirtc-devtool host session list`：查看会话
+- `tirtc-devtool host session stop <sessionId>`：停止会话
+
+设计约束：
+
+- 单机同一时刻只允许一个 `service` 会话；再次 `service start` 会直接失败并提示先停止已有服务会话。
+- `service start`：自动创建一个 session（也可通过 `--session` 绑定已有 session）。
+- `connection connect`：总是创建新的 session（不支持复用已有 session），允许多个 client 会话并行。
+- 除上述两条入口命令外，其他业务命令都必须显式传 `--session <sessionId>`。
+
+## 五、命令总览
+
+### Config
+
+用途：初始化 CLI 配置文件，作为后续 `service/debug/logging` 等命令的参数来源。
+
+- `tirtc-devtool init [outputPath]`：生成配置模板；不传路径时默认写入 `./.tmp/tirtc-devtool/config.toml`。
+
+### Host
+
+用途：管理 Host 进程生命周期与会话健康状态。
+
+- `tirtc-devtool host status`：查看当前 Host/service/connection/artifact 状态。
+- `tirtc-devtool host stop`：停止当前 `--session` 对应的 Host 进程。
+- `tirtc-devtool host stop --all`：停止全部 session 对应 Host，并清理本机 orphan host 进程。
+
+### Service
+
+用途：控制服务端角色（等待远端连接的一侧）。
+
+- `tirtc-devtool service start [serviceEntry] [license]`：启动服务并进入等待连接状态。
+- `tirtc-devtool service stop`：停止服务。
+
+说明：`license` 必填；`serviceEntry` 可省略，省略时走 runtime/core/transport 默认值。
+
+`debug bootstrap qrcode` / `debug bootstrap qrcode-from-config` 默认复用当前唯一活跃 session；多 session 时请显式传 `--session`。
+
+### Connection
+
+用途：控制客户端侧连接动作（主动连接/断开）。
+
+- `tirtc-devtool connection show`：查看当前连接状态。
+- `tirtc-devtool connection connect [serviceEntry] <peerId> [token]`：主动发起连接（不传 token 时自动签发）。
+- `tirtc-devtool connection disconnect`：主动断开连接。
+
+说明：`connect` 每次都会新建一个 session；省略 `serviceEntry` 时，Host 回退到 runtime 配置默认值。
+
+自动签发补充：
+
+- 若命令行和 `[connection].token` 都为空，且 TOML 提供 `[connection.auto_token]` 的 `access_id/secret_key`，CLI 会传 `tokenMode=auto`，由 App Server 在连接前实时签发新 token。
+- `local_id` 可选；缺省时 App Server 侧回退为本次连接使用的 `peer_id`。
+- 若手动 token 与自动签发配置都缺失，命令会失败。
+
+### Token
+
+用途：直接签发 token，并把调试所需的核心信息一次性输出到控制台，同时在本地生成二维码 PNG。
+
+- `tirtc-devtool token issue <accessId> <secretKey> <localId> <peerId>`：签发 token。
+
+可选参数：
+
+- `--openapi-entry <url>`：覆盖默认 openapi entry。
+- `--service-entry <entry>`：附加到组合 payload，便于扫码后直接连到目标服务。
+- `--user-ttl-seconds <seconds>`：覆盖 user token ttl。
+- `--channel-ttl-seconds <seconds>`：覆盖 channel token ttl。
+
+默认输出四部分：
+
+- `Issued Token Summary`：面向人类阅读的摘要，快速确认 local/peer/entry/ttl。
+- `Token`：单独罗列 token 字符串，便于复制粘贴。
+- `Payload JSON`：组合 JSON，对方或 Agent 可直接复制使用。
+- `QR Code PNG`：基于组合 JSON 生成的本地 PNG 文件绝对路径。适合人工打开图片后扫码。
+
+说明：
+
+- 组合 JSON 的 `type` 固定为 `tirtc-connect-token`。
+- PNG 二维码承载的是组合 JSON，不再暴露 `secret_key`。
+- `--json` 模式下会输出 `payload`、`payloadJson`、`token` 和 `qrCodePngPath`。
+
+### Stream
+
+用途：管理音视频流的发送/接收与远端请求策略。
+
+- `tirtc-devtool stream list`：列出当前流状态。
+- `tirtc-devtool media assets prepare --source <mp4> --output-root <dir>`：把 MP4 prepare 为 local assets。
+- `tirtc-devtool stream send start <streamId> <media> <assets_dir>`：启动发送流并绑定 prepared local assets。
+- `tirtc-devtool stream send stop <streamId>`：停止发送流。
+- `tirtc-devtool stream receive start <streamId> <media>`：启动接收流。
+- `tirtc-devtool stream receive stop <streamId>`：停止接收流。
+- `tirtc-devtool stream request-policy get`：查看远端请求策略。
+- `tirtc-devtool stream request-policy set <manual|auto-if-bound>`：设置远端请求策略。
+
+`request-policy` 行为：
+
+- `manual`：只上报远端请求事件，由上层显式决定是否发流。
+- `auto-if-bound`：如果本地已通过 `stream send start` 绑定 `(streamId, media, assets_dir)`，远端请求到达后自动启动发送。
+
+发送链路说明：
+
+- `stream/sendStart` 走 runtime-backed 真实发送路径。
+- 实际链路：`prepared local assets -> A/V PTS 对齐 -> 真实 uplink (runtime-backed transport)`。
+- 返回字段中的 `source.local_assets.assets_dir` 可用于验收与排障。
+
+### Output
+
+用途：把流内容挂到具体消费端（文件、预览页等）。
+
+- `tirtc-devtool output attach <streamId> <consumer> <mediaView> <format> <delivery> [targetPath] [maxFiles]`：附加输出消费。
+- `tirtc-devtool output detach <outputId>`：移除输出消费。
+
+`output attach` 当前最小稳定组合（CLI 前置校验）：
+
+- `consumer=web_preview`：`delivery` 必须是 `artifact_path`，`format` 推荐 `jpeg`/`pcm`（兼容旧值 `h264`/`g711a`）。
+- `consumer=file_sink`：`delivery` 必须是 `file`，`format` 必须是 `mp4`。
+
+`web_preview` 用法（音视频一起预览）：
+
+- 先在客户端会话中启动接收（必须两路都起）：
+  - `tirtc-devtool stream receive start <videoStreamId> video`
+  - `tirtc-devtool stream receive start <audioStreamId> audio`
+- 再挂接两路输出到同一个预览页：
+  - `tirtc-devtool output attach <videoStreamId> web_preview encoded jpeg artifact_path [videoTargetPath]`
+  - `tirtc-devtool output attach <audioStreamId> web_preview encoded pcm artifact_path [audioTargetPath]`
+- 两次 `output attach` 返回的 `result.preview.url` 应一致；用该 URL 在 Chrome 打开本地预览。
+- 页面打开后会自动触发 `GET /preview/start?token=...`；若浏览器拦截自动播放音频，请手动点击 `Start Stream` 解锁。
+- 可通过 `GET /preview/status?token=...` 查看 audio/video source 启动状态与 frame 计数。
+
+### Command
+
+用途：发送业务命令与实时观察命令事件。
+
+- `tirtc-devtool command send <commandId> <kind> <payloadEncoding> <payload>`：发送命令。
+- `tirtc-devtool command send-json <commandId> <kind> <payloadJson>`：以 JSON-first 形态发送命令。
+- `tirtc-devtool command tail`：持续监听命令相关事件。
+
+`command send-json` 约束：
+
+- `payloadJson` 必须是合法 JSON 文本。
+- CLI 固定按 `payloadEncoding=json` 下发给 Host。
+
+### Debug Bootstrap 二维码
+
+用途：生成客户端扫码连接所需的 bootstrap 二维码（只包含连接信息，不签发 token）。
+
+- `tirtc-devtool debug bootstrap qrcode <accessId> <secretKey> <peerId> [serviceEntry]`：按命令参数生成二维码。
+- `tirtc-devtool debug bootstrap qrcode-from-config`：按 `[debug.connect_bootstrap]` 配置生成二维码。
+
+二维码产物会落到 Host artifact 的 `debug/` 目录。
+
+### 观测与报告
+
+用途：做运行观测与验收证据导出。
+
+- `tirtc-devtool events tail`：实时查看事件流。
+- `tirtc-devtool logs export <outputPath>`：导出日志。
+- `tirtc-devtool report show`：查看报告。
+- `tirtc-devtool report export <outputPath>`：导出报告。
+
+## 六、服务端操作指引（对接安卓扫码）
+
+目标：只操作 CLI 服务端，启动后自动待推流；安卓端扫码拿到 bootstrap 信息，自行签发 token 后连接并观看音视频。
+
+### 1) 启动服务端
+
+```bash
+node devtools/cli/bin/tirtc-devtool.js service start "" "runtime-license"
+```
+
+记下返回里的 `sessionId`。
+
+### 2) 让服务端进入“自动按需发流”
+
+```bash
+编辑 `--config` 指向的 TOML：
+[stream.request_policy]
+mode = "auto-if-bound"
+
+[streams.send]
+assets_dir = "./.tmp/tirtc-devtool/assets/<prepared-assets-id>"
+audio_stream_id = 10
+video_stream_id = 11
+
+再执行 service start（CLI 会自动应用 request_policy + send 绑定）。
+```
+
+说明：
+- `auto-if-bound` 表示远端请求到达后，若本地已配置并应用发送绑定，服务端会自动开始对应发送。
+- `[streams.send]` 只配置一次 prepared assets 目录；音视频都从同一个 local assets 输入读取。
+- `audio_stream_id` 与 `video_stream_id` 必须与客户端请求的 stream id 一致。
+
+### 3) 生成给安卓扫码的 bootstrap 二维码
+
+```bash
+node devtools/cli/bin/tirtc-devtool.js --session <SESSION_ID> debug bootstrap qrcode \
+  "<access-id>" "<secret-key>" "<peer-id>" "<service-entry>"
+```
+
+命令会在 Host artifact 的 `debug/` 目录下生成：
+- `*.qr.png`（扫码图）
+
+### 4) 安卓端扫码后的预期流程（安卓实现不在本仓库）
+
+- 安卓扫描二维码，解析出 bootstrap JSON。
+- 使用 `access_id + secret_key` 在客户端侧（或你们外部签发服务）签发连接 token。
+- 使用签发后的 token + `peer_id`（必要时加 `service_entry`）建立连接。
+- 连接成功后请求接收对应流（例如 `10/video`、`11/audio`），即可看到服务端已绑定的媒体内容。
+
+### 4.1) 本地直接签发 token（公开调试入口）
+
+```bash
+node devtools/cli/bin/tirtc-devtool.js token issue \
+  "<access-id>" "<secret-key>" "<local-id>" "<peer-id>" \
+  --service-entry "<service-entry>"
+```
+
+输出包含：
+
+- 一份可直接复制的组合 JSON
+- 单独的 token 字符串
+- 同一份组合 JSON 对应的本地二维码 PNG 路径
+
+二维码内容示例：
+
+```json
+{
+  "version": 1,
+  "type": "tirtc-connect-token",
+  "peer_id": "<peer-id>",
+  "local_id": "<local-id>",
+  "service_entry": "<service-entry>",
+  "token": "<issued-token>",
+  "openapi_entry": "http://api-test-tirtc.tange365.com",
+  "user_ttl_seconds": 86400,
+  "channel_ttl_seconds": 300,
+  "generated_at": "<iso8601>"
+}
+```
+
+### 5) Web Preview 手动控制（建议验收路径）
+
+- 在客户端会话 attach 两路 `web_preview` 后，打开返回的 `preview.url`。
+- 页面默认只建立事件连接，不会自动起流。
+- 点击 `Start Stream`：触发服务端开始推送音视频。
+- 点击 `Stop Stream`：触发服务端停止推送。
+- 关闭页面：会自动触发一次 stop 请求（作为兜底）。
+
+## 六点四、二维码内容协议（安卓对齐）
+
+`debug bootstrap qrcode*` 生成的 payload 是一个 JSON 字符串，字段如下：
+
+```json
+{
+  "version": 1,
+  "type": "tirtc-connect-bootstrap",
+  "access_id": "<access-id>",
+  "secret_key": "<secret-key>",
+  "peer_id": "<peer-id>",
+  "service_entry": "<service-entry>"
+}
+```
+
+字段约束：
+- `version`: 固定 `1`。
+- `type`: 固定 `tirtc-connect-bootstrap`。
+- `access_id`: 客户端签发 token 所需。
+- `secret_key`: 客户端签发 token 所需。
+- `peer_id`: 目标服务端 peer 标识。
+- `service_entry`: 可选；为空或缺失时，客户端按自身默认 entry 策略处理。
+
+注意：
+- 该二维码不包含 token，也不在 App Server 侧签发 token。
+- token 签发职责在客户端或外部系统。
+
+
+## 六点五、日志配置与实时观测
+
+`[logging]` 段默认已在模板里生成：
+
+- `root_dir`：会话日志根目录（默认 `./.tmp/tirtc-devtool/logging`）
+- `console_mirror`：是否把 Host 关键日志镜像到当前命令终端
+- `level`：日志级别预留位（当前 Host 以统一关键路径日志为主）
+
+日志目录结构：
+
+- `<root_dir>/<session_id>/host.process.log`（Host 进程 stdio）
+- `<root_dir>/<session_id>/runtime.host.log`（Host 侧结构化运行日志）
+- `<root_dir>/<session_id>/uplink/*.transport-uplink.log`（发送 worker 日志）
+
+实时观察：
+
+- `node devtools/cli/bin/tirtc-devtool.js --session <SESSION_ID> events tail`
+- 输出中包含 `family=logs` / `kind=host.line` 的实时日志事件
+
+## 六点六、配置格式说明
+
+- 推荐使用 TOML（支持注释，便于人工维护）
+- `init` 默认生成 TOML 模板：`.tmp/tirtc-devtool/config.toml`
+
+## 七、本地 E2E 配置（必需）
+
+创建本地测试配置（已被 git ignore）：
+
+```bash
+mkdir -p devtools/cli/tests/.local
+cp devtools/cli/tests/runtime-backed.e2e.config.example.json devtools/cli/tests/.local/runtime-backed.e2e.local.json
+```
+
+推荐输入（客户端自行签发 token）：
+
+```json
+{
+  "assetsDir": "./.tmp/tirtc-devtool/assets/<prepared-assets-id>",
+  "license": "<license>",
+  "peerId": "<peer-id>",
+  "useFakeToken": false,
+  "accessId": "<access-id>",
+  "secretKey": "<secret-key>",
+  "e2eToken": "<externally-issued-token>"
+}
+```
+
+说明：
+- `useFakeToken=true` 时会走本地 fake token（不依赖 token 签发服务）。
+- `useFakeToken=false` 时必须提供外部签发 token（优先 `e2eToken`，否则读取环境变量 `TIRTC_E2E_TOKEN`）。
+- `debug bootstrap qrcode*` 仅生成客户端连接信息二维码（`access_id` / `secret_key` / `peer_id` / 可选 `service_entry`），不负责签发 token。
+
+## 八、FFmpeg 说明
+
+- FFmpeg 不入库（不纳入 git 版本管理）。
+- 打包时自动准备并放入：
+  - `devtools/cli/bin/tools/<platform>/`
+  - `devtools/cli/bin/dist/tools/<platform>/`
+
+## 九、新手入口
+
+- `node devtools/cli/bin/tirtc-devtool.js guide quickstart`
+
+会直接打印“服务端启动 -> 绑定自动发流 -> 生成 bootstrap 二维码 -> 客户端扫码签发 token 并连接 -> 打开 Web Preview 后手动 Start/Stop -> 观测报告”的最小闭环步骤。
+
+## 十、常用验收命令
+
+- App Server：`./app-server/script/test.sh acceptance`
+- CLI：`./devtools/cli/script/test.sh acceptance`
+- 联合一键：`./script/acceptance_app_server_devtools.sh`
+
+## 十一、退出码
+
+- `0`：成功
+- `1`：内部错误
+- `2`：协议版本不匹配
+- `3`：未初始化
+- `4`：请求/参数错误
+- `7`：连接失败
+- `8`：流不存在

package/bin/tirtc-devtool.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/devtools/cli/src/index.js');

package/dist/app-server/protocol-client/index.d.ts

@@ -0,0 +1,25 @@
+import { EventEmitter } from 'events';
+export interface Transport {
+    send(data: string): void;
+    onMessage(handler: (data: string) => void): void;
+    onClose(handler: () => void): void;
+    onError(handler: (error: Error) => void): void;
+}
+export declare class AppServerClient extends EventEmitter {
+    private transport;
+    private pendingRequests;
+    initialized: boolean;
+    private buffer;
+    constructor(transport: Transport);
+    private rejectAllPending;
+    private handleData;
+    private handleMessage;
+    sendRequest(method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
+    sendNotification(method: string, params?: unknown): void;
+    initialize(clientInfo: {
+        name: string;
+        version: string;
+        title?: string;
+    }, capabilities?: unknown): Promise<unknown>;
+    subscribeEvents(families: string[]): Promise<unknown>;
+}

package/dist/app-server/protocol-client/index.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppServerClient = void 0;
+const events_1 = require("events");
+const crypto_1 = require("crypto");
+class AppServerClient extends events_1.EventEmitter {
+    transport;
+    pendingRequests;
+    initialized = false;
+    buffer = '';
+    constructor(transport) {
+        super();
+        this.transport = transport;
+        this.pendingRequests = new Map();
+        this.transport.onMessage((data) => this.handleData(data));
+        this.transport.onError((error) => {
+            this.emit('error', error);
+            this.rejectAllPending(error);
+        });
+        this.transport.onClose(() => {
+            const error = new Error('transport closed');
+            this.emit('close');
+            this.rejectAllPending(error);
+        });
+    }
+    rejectAllPending(error) {
+        for (const [id, req] of this.pendingRequests.entries()) {
+            this.pendingRequests.delete(id);
+            if (req.timeoutTimer) {
+                clearTimeout(req.timeoutTimer);
+            }
+            req.reject(error);
+        }
+    }
+    handleData(chunk) {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() || '';
+        for (const line of lines) {
+            if (!line.trim()) {
+                continue;
+            }
+            try {
+                const msg = JSON.parse(line);
+                this.handleMessage(msg);
+            }
+            catch {
+                this.emit('error', new Error(`Failed to parse message: ${line}`));
+            }
+        }
+    }
+    handleMessage(msg) {
+        if (msg.id !== undefined && (msg.result !== undefined || msg.error !== undefined)) {
+            const req = this.pendingRequests.get(msg.id);
+            if (req) {
+                this.pendingRequests.delete(msg.id);
+                if (req.timeoutTimer) {
+                    clearTimeout(req.timeoutTimer);
+                }
+                if (msg.error !== undefined) {
+                    req.reject(msg.error);
+                }
+                else {
+                    req.resolve(msg.result);
+                }
+            }
+            return;
+        }
+        if (msg.method !== undefined && msg.id === undefined) {
+            this.emit('notification', msg.method, msg.params);
+            if (msg.method === 'events/event') {
+                this.emit('event', msg.params);
+            }
+        }
+    }
+    async sendRequest(method, params, timeoutMs = 30_000) {
+        const id = (0, crypto_1.randomUUID)();
+        return await new Promise((resolve, reject) => {
+            const pending = { resolve, reject };
+            pending.timeoutTimer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`request timeout after ${timeoutMs}ms: ${method}`));
+            }, timeoutMs);
+            this.pendingRequests.set(id, pending);
+            const payload = JSON.stringify({
+                id,
+                method,
+                params,
+            });
+            this.transport.send(`${payload}\n`);
+        });
+    }
+    sendNotification(method, params) {
+        const payload = JSON.stringify({
+            method,
+            params
+        });
+        this.transport.send(`${payload}\n`);
+    }
+    async initialize(clientInfo, capabilities) {
+        const result = await this.sendRequest('initialize', {
+            protocolVersion: '1.0.0',
+            clientInfo,
+            capabilities
+        });
+        this.sendNotification('initialized');
+        this.initialized = true;
+        return result;
+    }
+    async subscribeEvents(families) {
+        return await this.sendRequest('events/subscribe', { families });
+    }
+}
+exports.AppServerClient = AppServerClient;

package/dist/devtools/cli/src/config.d.ts

@@ -0,0 +1,46 @@
+export type CliConfig = {
+    service?: {
+        service_entry?: string;
+        license?: string;
+    };
+    connection?: {
+        service_entry?: string;
+        peer_id?: string;
+        token?: string;
+        auto_token?: {
+            openapi_entry?: string;
+            access_id?: string;
+            secret_key?: string;
+            local_id?: string;
+            user_ttl_seconds?: number;
+            channel_ttl_seconds?: number;
+        };
+    };
+    stream?: {
+        request_policy?: {
+            mode?: 'manual' | 'auto-if-bound';
+        };
+    };
+    streams?: {
+        send?: {
+            assets_dir?: string;
+            audio_stream_id?: number;
+            video_stream_id?: number;
+        };
+    };
+    logging?: {
+        root_dir?: string;
+        console_mirror?: boolean;
+        level?: 'verbose' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+    };
+    debug?: {
+        connect_bootstrap?: {
+            access_id?: string;
+            secret_key?: string;
+            peer_id?: string;
+            service_entry?: string;
+        };
+    };
+};
+export declare function loadConfig(configPath?: string): CliConfig;
+export declare function writeConfigTemplate(outputPath?: string): string;