@gjsify/devtools-protocol 0.8.0 → 0.12.0

package/README.md

@@ -0,0 +1,47 @@
+# @gjsify/devtools-protocol
+
+The **transport-agnostic contract** for the gjsify devtools control plane — pure TypeScript, no platform imports, no side effects. It defines the method surface, the pause classification, the JSON envelope, the server/client transport interfaces, instance routing, and the well-known DBus interface name.
+
+Every adapter and bridge imports it so they always agree:
+
+- [`@gjsify/devtools`](../devtools) — the in-app **DBus** adapter (GTK/GJS).
+- [`@gjsify/devtools-mcp`](../devtools-mcp) — the **MCP bridge** an agent talks to.
+- A future `@gjsify/devtools-web` — a **WebSocket** adapter for web apps.
+
+Because it is pure, browser web apps can import it too — the same envelope maps 1:1 onto WebSocket-JSON-RPC.
+
+## The contract
+
+The surface is **commands + state + introspection**, not "GActions" — so it is toolkit-neutral.
+
+```ts
+import { DEVTOOLS_INTERFACE, GENERIC_METHODS, type MethodKind } from '@gjsify/devtools-protocol';
+
+DEVTOOLS_INTERFACE; // 'org.gjsify.Devtools' — constant across apps; each app uses its own bus name + path
+```
+
+### Generic methods and the pause policy
+
+Each method carries a **kind** that the pause guard enforces. When a host pauses external control, `mutating` methods are rejected; `read-only` and `presence` always pass.
+
+| Kind | Meaning | While paused |
+|---|---|---|
+| `read-only` | Observation / diagnostics (`GetStatus`, `Screenshot`, `DumpTree`, …) | allowed |
+| `presence` | An external driver's own awareness channel (cursor / label) | allowed |
+| `mutating` | Edits app state or the user's UI (`ActivateAction`, `SetProperty`, `SwapCss`, …) | rejected |
+
+`GENERIC_METHODS` is the toolkit-neutral baseline (core control + full introspection). Adapters implement the subset they support; the bridge advertises only the implemented ones. App-specific methods are added via extensions with their own kinds — **the registry rejects an unclassified method name**, so a new method cannot silently bypass the pause policy.
+
+## Exports
+
+- `DEVTOOLS_INTERFACE` — the well-known interface name.
+- `GENERIC_METHODS`, `MethodKind`, `GenericMethodName` — the method surface + classification.
+- `DevtoolsServerTransport` / `DevtoolsClientTransport` — the app-side (`serve(handler)` / `close()`) and bridge-side (`connect()` / `request(req)` / `close()`) transport seams, plus the `DevtoolsHandler` type.
+- envelope + error types, the method registry, instance-routing helpers, and shared introspection types.
+
+## Build / test
+
+```bash
+gjsify workspace @gjsify/devtools-protocol build
+gjsify workspace @gjsify/devtools-protocol test
+```

package/lib/esm/index.js

@@ -1 +1 @@
-import{resolveBusAddress as e,sanitizeInstanceId as t}from"./routing.js";import{DevtoolsError as n,formatDbusErrorMessage as r,parseDbusErrorMessage as i,toErrorPayload as a}from"./errors.js";import{DEVTOOLS_INTERFACE as o}from"./constants.js";import{GENERIC_METHODS as s}from"./methods.js";import{errResponse as c,okResponse as l}from"./envelope.js";import"./transport.js";import{MethodRegistry as u}from"./registry.js";import"./types.js";export{o as DEVTOOLS_INTERFACE,n as DevtoolsError,s as GENERIC_METHODS,u as MethodRegistry,c as errResponse,r as formatDbusErrorMessage,l as okResponse,i as parseDbusErrorMessage,e as resolveBusAddress,t as sanitizeInstanceId,a as toErrorPayload};
+import{DEVTOOLS_INTERFACE as e}from"./constants.js";import{errResponse as t,okResponse as n}from"./envelope.js";import{DevtoolsError as r,formatDbusErrorMessage as i,parseDbusErrorMessage as a,toErrorPayload as o}from"./errors.js";import{GENERIC_METHODS as s}from"./methods.js";import"./transport.js";import{MethodRegistry as c}from"./registry.js";import{resolveBusAddress as l,sanitizeInstanceId as u}from"./routing.js";import"./types.js";export{e as DEVTOOLS_INTERFACE,r as DevtoolsError,s as GENERIC_METHODS,c as MethodRegistry,t as errResponse,i as formatDbusErrorMessage,n as okResponse,a as parseDbusErrorMessage,l as resolveBusAddress,u as sanitizeInstanceId,o as toErrorPayload};

package/lib/esm/registry.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{toErrorPayload as e}from"./errors.js";import{errResponse as t,okResponse as n}from"./envelope.js";var MethodRegistry=class{constructor(){this._methods=new Map}register(e){if(this._methods.has(e.name))throw Error(`Devtools method '${e.name}' is already registered`);this._methods.set(e.name,e)}has(e){return this._methods.has(e)}list(){return[...this._methods.values()].map(({name:e,kind:t})=>({name:e,kind:t}))}async dispatch(r,i={}){let a=this._methods.get(r.method);if(!a)return t({code:`not-found`,message:`unknown devtools method '${r.method}'`},r.id);if(i.paused&&a.kind===`mutating`)return t({code:`paused`,message:`${r.method} rejected — external control is paused. Read-only methods keep working.`},r.id);try{return n(await a.handler(r.params??{}),r.id)}catch(n){return t(e(n),r.id)}}};export{MethodRegistry};
+import"./_virtual/_rolldown/runtime.js";import{errResponse as e,okResponse as t}from"./envelope.js";import{toErrorPayload as n}from"./errors.js";var MethodRegistry=class{constructor(){this._methods=new Map}register(e){if(this._methods.has(e.name))throw Error(`Devtools method '${e.name}' is already registered`);this._methods.set(e.name,e)}has(e){return this._methods.has(e)}list(){return[...this._methods.values()].map(({name:e,kind:t})=>({name:e,kind:t}))}async dispatch(r,i={}){let a=this._methods.get(r.method);if(!a)return e({code:`not-found`,message:`unknown devtools method '${r.method}'`},r.id);if(i.paused&&a.kind===`mutating`)return e({code:`paused`,message:`${r.method} rejected — external control is paused. Read-only methods keep working.`},r.id);try{return t(await a.handler(r.params??{}),r.id)}catch(t){return e(n(t),r.id)}}};export{MethodRegistry};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/devtools-protocol",
-    "version": "0.8.0",
+    "version": "0.12.0",
     "description": "Transport-agnostic devtools contract (methods, JSON envelope, method-kinds, transport interface) shared by every gjsify devtools adapter and the MCP bridge",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -35,8 +35,8 @@
     ],
     "dependencies": {},
     "devDependencies": {
-        "@gjsify/cli": "^0.8.0",
-        "@gjsify/unit": "^0.8.0",
+        "@gjsify/cli": "^0.12.0",
+        "@gjsify/unit": "^0.12.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
@@ -45,7 +45,7 @@
             "gjs": "polyfill",
             "node": "none",
             "browser": "none",
-            "nativescript": "none"
+            "nativescript": "polyfill"
         }
     },
     "license": "MIT",