roku-mcp 1.5.2 → 1.7.0

package/README.md

@@ -2,23 +2,23 @@
 
 A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for Roku device automation. Exposes tools for app deployment, ECP remote control, screenshot capture, SceneGraph node inspection, and BrightScript debug console access.
 
-## Installation
+## Install
 
-```bash
-npm install -g roku-mcp
-```
-
-Or run directly with npx (no install required):
+The server ships as a single `npx` command. Install once globally if you prefer, or let your MCP client launch it on demand via `npx -y roku-mcp` — both work.
 
 ```bash
-npx roku-mcp
+npm install -g roku-mcp     # optional, global install
+# or just point your client at: npx -y roku-mcp
 ```
 
-## Client Configuration
+Configure your AI client below. Every platform uses the same launch line; only the config file and reload step change.
 
-### Cursor
+<details>
+<summary><strong>Cursor</strong> — agent-mode tools, auto-discovers MCP servers</summary>
 
-1. Create `.cursor/mcp.json` in your project root:
+**Prerequisites:** Cursor 0.45+ with Agent mode.
+
+**Install:** create `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global):
 
 ```json
 {
@@ -35,14 +35,22 @@ npx roku-mcp
 }
 ```
 
-2. Reload the window: `Cmd+Shift+P` (macOS) / `Ctrl+Shift+P` (Windows/Linux) → **Developer: Reload Window**
-3. Go to **Cursor Settings → MCP** and verify the "roku" server shows a green status. If it appears disabled, click the toggle to enable it.
+Then reload the window (`Cmd+Shift+P` / `Ctrl+Shift+P` → **Developer: Reload Window**).
+
+**Verify:** open **Cursor Settings → MCP** and confirm the `roku` row shows a green dot. If it appears disabled, click the toggle. In a new agent chat, type `list roku tools` — you should see `roku_deploy`, `roku_screenshot`, etc.
 
-### VS Code
+**Routing rule (recommended):** the repo also ships an [`AGENTS.md`](./AGENTS.md). Cursor picks it up automatically, so the agent knows the canonical *observe → act → wait → verify* loop and the RTA `uiElementId` gotcha without you having to re-explain it every session.
 
-Requires VS Code **1.99+** with the GitHub Copilot extension.
+**Troubleshoot:** if the server stays grey/disabled, check `View → Output → MCP Logs` — the most common cause is `ROKU_DEVICE_HOST` unreachable on the LAN. Omit the `env` block entirely to fall back to SSDP auto-discovery.
 
-1. Create `.vscode/mcp.json` in your project root:
+</details>
+
+<details>
+<summary><strong>VS Code (GitHub Copilot)</strong> — agent mode, MCP via <code>.vscode/mcp.json</code></summary>
+
+**Prerequisites:** VS Code 1.99+ with the GitHub Copilot extension and an active Copilot subscription that includes Agent mode.
+
+**Install:** create `.vscode/mcp.json` in your project root:
 
 ```json
 {
@@ -59,12 +67,21 @@ Requires VS Code **1.99+** with the GitHub Copilot extension.
 }
 ```
 
-2. Reload the window: `Cmd+Shift+P` / `Ctrl+Shift+P` → **Developer: Reload Window**
-3. Open Copilot Chat and switch to **Agent mode** (select from the chat mode dropdown). The roku tools will be available there.
+Reload the window (`Cmd+Shift+P` / `Ctrl+Shift+P` → **Developer: Reload Window**).
+
+**Verify:** open Copilot Chat, switch the chat-mode dropdown to **Agent**, and ask "what roku tools do you have?". You should see the full `roku_*` list. The MCP panel (`Cmd+Shift+P` → **MCP: List Servers**) should show `roku` as `Running`.
 
-### Claude Desktop
+**Troubleshoot:** if the server fails to start, run `npx -y roku-mcp --help` in a regular terminal first — that confirms Node 18+ and `npx` are working before VS Code launches it.
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong> — official Anthropic desktop app</summary>
+
+**Prerequisites:** Claude Desktop (latest from claude.ai/download), Node.js 18+ on `PATH`.
+
+**Install:** edit your Claude Desktop config:
 
-Add to your Claude Desktop config file:
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
@@ -83,11 +100,20 @@ Add to your Claude Desktop config file:
 }
 ```
 
-Restart Claude Desktop after saving.
+Fully quit and restart Claude Desktop (the menu-bar icon must close — `Cmd+Q` on macOS).
+
+**Verify:** open a new chat. The 🛠️ icon in the input bar should list `roku-mcp` with all its tools. Ask "take a Roku screenshot" — Claude will request approval for `roku_screenshot` and run it.
 
-### Windsurf
+**Troubleshoot:** if no tool icon appears, check `~/Library/Logs/Claude/mcp-server-roku.log` (macOS) — `command not found: npx` means Node isn't on the GUI app's `PATH`. Either install Node via the official `.pkg`, or hard-code the absolute paths: `"command": "/usr/local/bin/node"`, `"args": ["/usr/local/bin/npx", "-y", "roku-mcp"]`.
 
-Create `.windsurf/mcp.json` in your project root:
+</details>
+
+<details>
+<summary><strong>Windsurf</strong> — Codeium's agentic IDE</summary>
+
+**Prerequisites:** Windsurf with Cascade enabled.
+
+**Install:** create `.windsurf/mcp.json` in your project root (or `~/.codeium/windsurf/mcp_config.json` globally):
 
 ```json
 {
@@ -104,18 +130,75 @@ Create `.windsurf/mcp.json` in your project root:
 }
 ```
 
-Reload the window after saving.
+Reload the window. In Cascade settings, refresh the MCP server list.
+
+**Verify:** ask Cascade "list available MCP tools" — `roku_*` entries should appear.
 
-### Any MCP-compatible client
+**Troubleshoot:** Windsurf occasionally caches a stale server. If reloads don't pick up edits, fully quit Windsurf and reopen.
 
-The server uses **stdio transport**. Any client that supports MCP can launch it with:
+</details>
+
+<details>
+<summary><strong>Any MCP-compatible client</strong> (Continue, Cline, Zed, Codex, Claude Code, OpenCode, …)</summary>
+
+The server speaks the standard MCP **stdio** transport. Anywhere you can declare:
 
 ```
 command: npx
 args:    ["-y", "roku-mcp"]
+env:     { ROKU_DEVICE_HOST: "...", ROKU_DEVICE_PASSWORD: "..." }
+```
+
+…the server runs. Both env vars are optional: omit `ROKU_DEVICE_HOST` to use SSDP auto-discovery on the LAN, and pass `host` / `password` on each tool call to override.
+
+The repo-root [`AGENTS.md`](./AGENTS.md) is picked up automatically by Claude Code, OpenCode, Codex CLI, and any other tool that follows the AGENTS.md convention, so those agents inherit the same usage guidance without extra setup.
+
+</details>
+
+## Agent rules
+
+For better agent behavior (the `observe → act → wait → verify` loop, the RTA `uiElementId` gotcha that silently breaks `roku_edit_node`, when to use which tool), the repo ships drop-in rules pre-formatted for each major agent. The body is identical — only the wrapper differs to match what each agent auto-loads.
+
+| Agent | File | Install path |
+|---|---|---|
+| Cursor | [`rules/cursor/roku-mcp.mdc`](./rules/cursor/roku-mcp.mdc) | `.cursor/rules/roku-mcp.mdc` |
+| Claude Code | [`rules/claude-code/CLAUDE.md`](./rules/claude-code/CLAUDE.md) | `CLAUDE.md` (repo root) |
+| Claude Desktop | [`rules/claude-desktop/roku-mcp.md`](./rules/claude-desktop/roku-mcp.md) | Settings → System Prompt |
+| Windsurf | [`rules/windsurf/roku-mcp.md`](./rules/windsurf/roku-mcp.md) | `.windsurf/rules/roku-mcp.md` |
+| Codex CLI / OpenCode / Aider | [`AGENTS.md`](./AGENTS.md) (repo root) | `AGENTS.md` (repo root) |
+
+See [`rules/README.md`](./rules/README.md) for one-line copy commands per agent.
+
+## Quickstart
+
+Once your client is wired up, these three prompts work out of the box and exercise the main capability groups.
+
+**1. Confirm the device is reachable**
+
+```
+Use roku-mcp to query my Roku device info and tell me the model, firmware, and IP.
+```
+
+The agent should call `roku_query_device_info` (and possibly `roku_discover` if no host is configured) and reply in one turn.
+
+**2. Drive the UI with screenshots**
+
+```
+Press Home, wait 2 seconds, take a screenshot, then move Right twice and
+screenshot again. Describe what changed between the two screenshots.
 ```
 
-Pass `ROKU_DEVICE_HOST` and `ROKU_DEVICE_PASSWORD` as environment variables, or omit the host to use SSDP auto-discovery.
+This exercises `roku_keypress`, `roku_sleep`, and `roku_screenshot` — the standard *observe → act → wait → verify* loop.
+
+**3. Live-edit a running channel (requires RTA — see [Runtime UI Editing](#runtime-ui-editing))**
+
+```
+On the currently running dev channel, find the label that shows the page
+title, change its text to "Hello from MCP", verify the change with
+roku_get_value, then change it back.
+```
+
+The agent will `roku_query_app_ui` to locate the node, grab the `uiElementId`, call `roku_edit_node` + `roku_get_value`, and roll back — proving end-to-end RTA wiring.
 
 ## Environment Variables
 
@@ -197,6 +280,63 @@ Or simply add the two expected variables to your `.env` alongside your existing
 | `roku_console_send` | Send a command to the debug console and auto-disconnect |
 | `roku_console_disconnect` | Close the console connection (safety net) |
 
+### Runtime UI Editing
+
+Edit the SceneGraph UI of a running sideloaded dev channel without redeploying — the same backend the SceneGraph Inspector in the [vscode-brightscript-language](https://github.com/rokucommunity/vscode-brightscript-language) extension uses. These tools speak the [roku-test-automation](https://github.com/triwav/roku-test-automation) (RTA) protocol against the channel's **On-Device Component** on TCP port 9000, so changes apply instantly with no debugger pause.
+
+| Tool | Description |
+|---|---|
+| `roku_edit_node` | Set one or more fields on a node by id (visible, translation, text, color, opacity, etc.) |
+| `roku_set_node_visible` | Show or hide a node by id |
+| `roku_move_node` | Move a node to `[x, y]` |
+| `roku_focus_node` | Set focus on a node by id (RTA `focusNode`) |
+| `roku_remove_node` | Detach a node from its parent at runtime (RTA `removeNode`) |
+| `roku_create_node` | Create a new node and append it to a parent by id (RTA `createChild`) |
+| `roku_get_value` | Read a field value (or full `keyPath`) from the running scene (RTA `getValue`) |
+| `roku_observe_field` | Wait for a field to change or match a value (RTA `onFieldChangeOnce`) — great for "wait until X" assertions |
+
+**How it works.** Each tool opens a short-lived TCP connection to the RTA On-Device Component (port 9000) in the running channel, sends a length-prefixed JSON request (`setValue` / `getValue` / `focusNode` / ...) and parses the framed JSON response. Mutations apply on the SceneGraph thread without breaking into the debugger.
+
+**Node addressing.** `nodeId` accepts either:
+- A `uiElementId` like `RTA_1773` (visible in the `roku_query_sg_nodes` / `roku_query_app_ui` output for every node when RTA is running). This is the most robust target.
+- A real BrightScript `id` attribute defined on the node in the channel source.
+
+Anything matching `/^RTA_\d+$/` is sent with RTA `base: "elementId"`; otherwise it's sent with `base: "scene"`.
+
+#### Required: install the RTA On-Device Component in your channel
+
+These tools only work when the channel under test bundles RTA. You have two options:
+
+**Option A — let `roku-debug` inject RTA on every sideload (recommended for VS Code users).**
+
+1. In your `launch.json`, enable:
+
+    ```json
+    "injectRdbOnDeviceComponent": true
+    ```
+
+2. In `source/main.brs`, add the marker comment immediately after `screen.show()`:
+
+    ```brightscript
+    sub main()
+        screen = createObject("roSGScreen")
+        ' ...
+        screen.show()
+        ' vscode_rdb_on_device_component_entry
+        ' ...
+    end sub
+    ```
+
+**Option B — bundle the RTA component yourself.** Copy the `device/components` folder from [roku-test-automation](https://github.com/triwav/roku-test-automation) into your channel and instantiate `RTA_OnDeviceComponent` once from your scene.
+
+Either way, on a successful install you will see this in the device log at channel launch:
+
+```
+[RTA][INFO] OnDeviceComponent init
+```
+
+If a runtime UI tool returns a connection-refused error, RTA is not present in the running channel — apply one of the two install options above and redeploy.
+
 ### BrightScript Profiler
 
 Analyze `.bsprof` files generated by Roku devices. These tools use [bsprof-cli](https://www.npmjs.com/package/bsprof-cli) to parse the binary profiler format and return structured JSON reports.
@@ -224,6 +364,16 @@ Record, analyze, and compare Perfetto traces from Roku devices. Requires **Roku
 
 Workflow: enable tracing → start recording → interact with app → stop recording → analyze. The `.trace` files can also be opened at [ui.perfetto.dev](https://ui.perfetto.dev/).
 
+### Stream Diagnosis
+
+Figure out why an HLS/DASH stream that plays everywhere else fails on Roku.
+
+| Tool | Description |
+|---|---|
+| `roku_diagnose_stream` | Correlate the Video-node `errorInfo`, the manifest (a fetchable `url` or pasted `content`), and an optional Charles/HAR capture into ranked Roku-specific root causes (cause, evidence, confidence, severity, fix, doc link). Optionally `captureLive=true` deploys the bundled StreamProbe harness to capture the device error first. |
+
+It detects Roku-specific gotchas such as muxed audio+video in fMP4/CMAF HLS (plays video but silent), video codecs/levels beyond the hardware decoder (e.g. 4K H.264 or 8K HEVC), token/403-gated CDNs, and DRM license rejections. The static manifest checks are treated as hints; when you supply the real device `errorInfo` the diagnosis is corroborated to high confidence.
+
 ## Requirements
 
 - Node.js 18+

package/dist/assets/streamprobe/components/StreamProbe.xml

@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!-- StreamProbe scene: plays the stream described by deep-link args and exposes
+     the Video node error fields (errorCode/errorMsg/errorInfo) for RTA capture. -->
+
+<component name="StreamProbe" extends="Scene">
+
+  <interface>
+    <field id="launchArgs" type="assocarray" onChange="onLaunchArgs" />
+    <!-- Mirror fields the diagnoser reads via RTA getValue. -->
+    <field id="probeState" type="string" value="idle" />
+    <field id="probeErrorCode" type="integer" value="0" />
+    <field id="probeErrorMsg" type="string" value="" />
+    <field id="probeErrorInfo" type="string" value="" />
+  </interface>
+
+  <script type="text/brightscript">
+  <![CDATA[
+
+    sub init()
+      m.video = m.top.findNode("probeVideo")
+      m.video.observeField("state", "onVideoState")
+    end sub
+
+    ' Re-entrant: launch args may arrive after init.
+    sub onLaunchArgs()
+      startPlayback(m.top.launchArgs)
+    end sub
+
+    sub startPlayback(args as dynamic)
+      if args = invalid then return
+
+      url = pickArg(args, "input_url", "url")
+      if url = invalid or url = "" then return
+
+      format = pickArg(args, "input_format", "format")
+      if format = invalid or format = "" then format = "hls"
+
+      content = createObject("RoSGNode", "ContentNode")
+      content.title = "StreamProbe"
+      content.streamFormat = format
+      content.url = url
+
+      keySystem = pickArg(args, "input_drm", "drm")
+      licenseUrl = pickArg(args, "input_license_url", "licenseServerURL")
+      if keySystem <> invalid and keySystem <> "" then
+        drmParams = { KeySystem: keySystem }
+        if licenseUrl <> invalid and licenseUrl <> "" then
+          drmParams.licenseServerURL = licenseUrl
+        end if
+        headerName = pickArg(args, "input_license_header_name", invalid)
+        headerValue = pickArg(args, "input_license_header_value", invalid)
+        if headerName <> invalid and headerName <> "" then
+          drmParams.licenseReqHeaders = [ { name: headerName, value: headerValue } ]
+        end if
+        content.drmParams = drmParams
+      end if
+
+      m.video.content = content
+      m.video.setFocus(true)
+      m.video.control = "play"
+      m.top.probeState = "requested"
+    end sub
+
+    function pickArg(args as object, primary as string, fallback as dynamic) as dynamic
+      if args.doesExist(primary) then return args[primary]
+      if fallback <> invalid and args.doesExist(fallback) then return args[fallback]
+      return invalid
+    end function
+
+    sub onVideoState()
+      st = m.video.state
+      m.top.probeState = st
+      ' Mirror to console (port 8085) so the error can be captured without RTA.
+      print "[StreamProbe] state changed "; st
+      if st = "error" then
+        m.top.probeErrorCode = m.video.errorCode
+        m.top.probeErrorMsg = m.video.errorMsg
+        info = m.video.errorInfo
+        print "[StreamProbe] errorCode = "; m.video.errorCode
+        print "[StreamProbe] errorMsg = "; m.video.errorMsg
+        if info <> invalid then
+          m.top.probeErrorInfo = formatJSON(info)
+          print "[StreamProbe] errorInfo = "; m.top.probeErrorInfo
+        end if
+      end if
+    end sub
+
+  ]]>
+  </script>
+
+  <children>
+    <Video id="probeVideo" width="1920" height="1080" />
+  </children>
+
+</component>

package/dist/assets/streamprobe/manifest

@@ -0,0 +1,11 @@
+title=StreamProbe
+subtitle=roku-mcp stream diagnoser harness
+major_version=1
+minor_version=0
+build_version=00001
+
+ui_resolutions=fhd
+rsg_version=1.2
+
+requires_widevine_drm=1
+requires_widevine_version=1.0

package/dist/assets/streamprobe/source/main.brs

@@ -0,0 +1,29 @@
+' StreamProbe — minimal harness used by roku-mcp's roku_diagnose_stream tool to
+' attempt playback of an arbitrary stream and expose the Video node's error
+' fields for capture over RTA.
+
+sub Main(args as dynamic)
+  showStreamProbe(args)
+end sub
+
+sub showStreamProbe(args as dynamic)
+  screen = CreateObject("roSGScreen")
+  m.port = CreateObject("roMessagePort")
+  screen.setMessagePort(m.port)
+  scene = screen.CreateScene("StreamProbe")
+  screen.show()
+  ' vscode_rdb_on_device_component_entry
+
+  ' Forward deep-link launch args (input_url, input_format, input_*) to the scene.
+  if args <> invalid
+    scene.launchArgs = args
+  end if
+
+  while true
+    msg = wait(0, m.port)
+    msgType = type(msg)
+    if msgType = "roSGScreenEvent"
+      if msg.isScreenClosed() then return
+    end if
+  end while
+end sub

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,eAAe,CAAC;AASvB,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,QAAQ,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAclF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,eAAe,CAAC;AAWvB,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,QAAQ,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgBlF"}

package/dist/index.js

@@ -7,10 +7,12 @@ import { registerScreenshotTools } from './tools/screenshot.js';
 import { registerConsoleTools } from './tools/console.js';
 import { registerBsprofTools } from './tools/bsprof.js';
 import { registerPerfettoTools } from './tools/perfetto.js';
+import { registerEditUiTools } from './tools/edit-ui.js';
+import { registerStreamTools } from './tools/stream.js';
 export default function createServer(_options) {
     const server = new McpServer({
         name: 'roku-mcp',
-        version: '1.5.2',
+        version: '1.7.0',
     });
     registerDeployTools(server);
     registerEcpTools(server);
@@ -18,6 +20,8 @@ export default function createServer(_options) {
     registerConsoleTools(server);
     registerBsprofTools(server);
     registerPerfettoTools(server);
+    registerEditUiTools(server);
+    registerStreamTools(server);
     return server.server;
 }
 const isDirectRun = typeof process !== 'undefined' &&
@@ -28,7 +32,7 @@ if (isDirectRun) {
         const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
         const server = new McpServer({
             name: 'roku-mcp',
-            version: '1.5.2',
+            version: '1.7.0',
         });
         registerDeployTools(server);
         registerEcpTools(server);
@@ -36,6 +40,8 @@ if (isDirectRun) {
         registerConsoleTools(server);
         registerBsprofTools(server);
         registerPerfettoTools(server);
+        registerEditUiTools(server);
+        registerStreamTools(server);
         const transport = new StdioServerTransport();
         await server.connect(transport);
     })();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,QAA8C;IACjF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAE9B,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAED,MAAM,WAAW,GACf,OAAO,OAAO,KAAK,WAAW;IAC9B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACf,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;AAEnF,IAAI,WAAW,EAAE,CAAC;IAChB,CAAC,KAAK,IAAI,EAAE;QACV,MAAM,EAAE,oBAAoB,EAAE,GAAG,MAAM,MAAM,CAAC,2CAA2C,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;YAC3B,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,OAAO;SACjB,CAAC,CAAC;QAEH,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC5B,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACzB,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAChC,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC7B,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC5B,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAE9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC,CAAC,EAAE,CAAC;AACP,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,QAA8C;IACjF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAE5B,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAED,MAAM,WAAW,GACf,OAAO,OAAO,KAAK,WAAW;IAC9B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACf,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;AAEnF,IAAI,WAAW,EAAE,CAAC;IAChB,CAAC,KAAK,IAAI,EAAE;QACV,MAAM,EAAE,oBAAoB,EAAE,GAAG,MAAM,MAAM,CAAC,2CAA2C,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;YAC3B,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,OAAO;SACjB,CAAC,CAAC;QAEH,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC5B,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACzB,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAChC,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC7B,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC5B,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC9B,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC5B,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAE5B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC,CAAC,EAAE,CAAC;AACP,CAAC"}

package/dist/stream/charles.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Parse a Charles Proxy session (or HAR capture) into normalized HTTP entries
+ * and classify each request as manifest / segment / license / key / other.
+ *
+ * Supported export formats:
+ *   - Charles ".chlsj" (JSON Session File): either a single JSON array of
+ *     request objects, or newline-delimited JSON (one object per line).
+ *   - ".har" (HTTP Archive): the standard `{ log: { entries: [...] } }` shape
+ *     produced by Charles "Export > HAR" and by browser devtools.
+ *
+ * NOTE: the binary ".chls" format is NOT supported (it is a proprietary binary
+ * blob). Callers should instruct the user to export as ".chlsj" or ".har".
+ *
+ * Charles .chlsj entry shape (varies slightly by version) roughly looks like:
+ *   {
+ *     "host": "...", "method": "GET", "path": "/x.m3u8",
+ *     "scheme": "https", "status": 200,
+ *     "request":  { "header": { "headers": [{ "name", "value" }] }, "body": {...} },
+ *     "response": { "header": { "headers": [...] }, "body": { "text"|"encoded", "contentType" } },
+ *     "times": { "totalDuration": 123 }
+ *   }
+ */
+export interface NormalizedHttpEntry {
+    url: string;
+    host: string;
+    path: string;
+    method: string;
+    status: number;
+    reqHeaders: Record<string, string>;
+    respHeaders: Record<string, string>;
+    /** Decoded response body text when available (manifests, license errors). */
+    respBody?: string;
+    /** Response content-type, lowercased. */
+    mimeType?: string;
+    durationMs?: number;
+    kind: HttpEntryKind;
+}
+export type HttpEntryKind = 'manifest' | 'segment' | 'license' | 'key' | 'other';
+export interface CharlesSession {
+    entries: NormalizedHttpEntry[];
+    /** Entries with a non-2xx status or otherwise suspicious response. */
+    failing: NormalizedHttpEntry[];
+    format: 'chlsj' | 'har';
+    notes: string[];
+}
+/** Parse the raw text of a Charles .chlsj or .har file. */
+export declare function parseCharlesText(text: string): CharlesSession;
+/** A request is "failing" if it has a non-2xx status, or an empty body where one is expected. */
+export declare function isFailing(entry: NormalizedHttpEntry): boolean;
+//# sourceMappingURL=charles.d.ts.map

package/dist/stream/charles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"charles.d.ts","sourceRoot":"","sources":["../../src/stream/charles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,GAAG,OAAO,CAAC;AAEjF,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,sEAAsE;IACtE,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,MAAM,EAAE,OAAO,GAAG,KAAK,CAAC;IACxB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAqKD,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CA4D7D;AAQD,iGAAiG;AACjG,wBAAgB,SAAS,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAQ7D"}