@gjsify/devtools-protocol 0.8.0

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/constants.js

@@ -0,0 +1 @@
+const e=`org.gjsify.Devtools`;export{e as DEVTOOLS_INTERFACE};

package/lib/esm/envelope.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function okResponse(e,t){return{ok:!0,result:e,id:t}}function errResponse(e,t){return{ok:!1,error:e,id:t}}export{errResponse,okResponse};

package/lib/esm/errors.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";var DevtoolsError=class extends Error{constructor(e,t,n){super(t),this.name=`DevtoolsError`,this.code=e,this.data=n}};function toErrorPayload(e){return e instanceof DevtoolsError?{code:e.code,message:e.message,data:e.data}:{code:`internal`,message:e instanceof Error?e.message:String(e)}}const e=[`paused`,`human-only`,`unavailable`,`not-found`,`unsupported`,`invalid-params`,`internal`];function formatDbusErrorMessage(e,t){return`${e}: ${t}`}function parseDbusErrorMessage(t){let n=t.indexOf(`: `);if(n>0){let r=t.slice(0,n);if(e.includes(r))return{code:r,message:t.slice(n+2)}}return{code:`internal`,message:t}}export{DevtoolsError,formatDbusErrorMessage,parseDbusErrorMessage,toErrorPayload};

package/lib/esm/index.js

@@ -0,0 +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};

package/lib/esm/methods.js

@@ -0,0 +1 @@
+const e={GetStatus:`read-only`,Screenshot:`read-only`,ListActions:`read-only`,ActivateAction:`mutating`,ChangeActionState:`mutating`,PresentWindow:`read-only`,ResizeWindow:`mutating`,ListToplevels:`read-only`,DumpTree:`read-only`,GetProperty:`read-only`,SetProperty:`mutating`,GetFocused:`read-only`,EmitSignal:`mutating`,DumpGSettings:`read-only`,DumpCss:`read-only`,SwapCss:`mutating`};export{e as GENERIC_METHODS};

package/lib/esm/registry.js

@@ -0,0 +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};

package/lib/esm/routing.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function sanitizeInstanceId(e){let t=e.toLowerCase().replace(/[^a-z0-9]/g,``);return/^[a-z]/.test(t)?t:`i${t||`0`}`}function resolveBusAddress(e,t){let n=`/${e.replace(/\./g,`/`)}`,r=t&&t!==`default`?sanitizeInstanceId(t):`default`;return r===`default`?{busName:e,objectPath:`${n}/devtools`,instance:`default`}:{busName:`${e}.${r}`,objectPath:`${n}/${r}/devtools`,instance:r}}export{resolveBusAddress,sanitizeInstanceId};

package/lib/types/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The well-known DBus interface name. It is constant across apps — each app
+ * implements it on its own bus name + object path (see {@link resolveBusAddress}).
+ * Both the in-app adapter (@gjsify/devtools) and the MCP bridge
+ * (@gjsify/devtools-mcp) import it, so they always agree on the interface.
+ */
+export declare const DEVTOOLS_INTERFACE = "org.gjsify.Devtools";

package/lib/types/envelope.d.ts

@@ -0,0 +1,27 @@
+import type { DevtoolsErrorCode } from './errors.js';
+/** A request crossing any devtools transport. JSON-serialisable. */
+export interface DevtoolsRequest {
+    /** Method/command name, e.g. "GetStatus", "ActivateAction". */
+    method: string;
+    /** Method parameters (method-specific). */
+    params?: Record<string, unknown>;
+    /** Correlation id for stream transports (WebSocket); DBus call/return ignores it. */
+    id?: string | number;
+}
+export interface DevtoolsResponseOk {
+    ok: true;
+    result: unknown;
+    id?: string | number;
+}
+export interface DevtoolsResponseErr {
+    ok: false;
+    error: {
+        code: DevtoolsErrorCode;
+        message: string;
+        data?: unknown;
+    };
+    id?: string | number;
+}
+export type DevtoolsResponse = DevtoolsResponseOk | DevtoolsResponseErr;
+export declare function okResponse(result: unknown, id?: string | number): DevtoolsResponseOk;
+export declare function errResponse(error: DevtoolsResponseErr['error'], id?: string | number): DevtoolsResponseErr;

package/lib/types/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Typed error codes carried in the devtools JSON envelope. The string code
+ * travels over every transport (a DBus error-name suffix, a WS JSON
+ * `error.code`) so the MCP bridge can map a failure to a clear, actionable
+ * tool result.
+ *
+ * Convention: a method handler signals a typed failure by throwing a
+ * {@link DevtoolsError} whose `code` is one of these; transports serialise
+ * `code` + `message` and the bridge re-surfaces them verbatim.
+ */
+export type DevtoolsErrorCode = 'paused' | 'human-only' | 'unavailable' | 'not-found' | 'unsupported' | 'invalid-params' | 'internal';
+/** A failure a devtools method handler can throw to carry a typed code. */
+export declare class DevtoolsError extends Error {
+    readonly name = "DevtoolsError";
+    readonly code: DevtoolsErrorCode;
+    readonly data?: unknown;
+    constructor(code: DevtoolsErrorCode, message: string, data?: unknown);
+}
+/** Narrow an unknown thrown value to the envelope's error payload shape. */
+export declare function toErrorPayload(err: unknown): {
+    code: DevtoolsErrorCode;
+    message: string;
+    data?: unknown;
+};
+/**
+ * Encode a code into an error message as a `"<code>: <message>"` prefix.
+ * DBus carries only the message string of a thrown error, so the in-app DBus
+ * adapter prefixes the code this way and the bridge recovers it with
+ * {@link parseDbusErrorMessage} — the typed code survives the wire.
+ */
+export declare function formatDbusErrorMessage(code: DevtoolsErrorCode, message: string): string;
+/** Recover a `{ code, message }` from a `"<code>: <message>"` DBus error string. */
+export declare function parseDbusErrorMessage(raw: string): {
+    code: DevtoolsErrorCode;
+    message: string;
+};

package/lib/types/index.d.ts

@@ -0,0 +1,8 @@
+export * from './constants.js';
+export * from './errors.js';
+export * from './methods.js';
+export * from './envelope.js';
+export * from './transport.js';
+export * from './registry.js';
+export * from './routing.js';
+export * from './types.js';

package/lib/types/methods.d.ts

@@ -0,0 +1,33 @@
+/**
+ * How a method behaves while external control is paused by the host:
+ * - `read-only` — observation/diagnostics; always allowed.
+ * - `presence`  — an external driver's own awareness channel (cursor/label); allowed.
+ * - `mutating`  — edits app state or the user's UI; rejected while paused.
+ */
+export type MethodKind = 'read-only' | 'presence' | 'mutating';
+/**
+ * The generic, toolkit-neutral devtools methods and their kinds. Adapters
+ * (DBus / WebSocket) 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 bypass the pause policy unnoticed.
+ */
+export declare const GENERIC_METHODS: {
+    readonly GetStatus: "read-only";
+    readonly Screenshot: "read-only";
+    readonly ListActions: "read-only";
+    readonly ActivateAction: "mutating";
+    readonly ChangeActionState: "mutating";
+    readonly PresentWindow: "read-only";
+    readonly ResizeWindow: "mutating";
+    readonly ListToplevels: "read-only";
+    readonly DumpTree: "read-only";
+    readonly GetProperty: "read-only";
+    readonly SetProperty: "mutating";
+    readonly GetFocused: "read-only";
+    readonly EmitSignal: "mutating";
+    readonly DumpGSettings: "read-only";
+    readonly DumpCss: "read-only";
+    readonly SwapCss: "mutating";
+};
+export type GenericMethodName = keyof typeof GENERIC_METHODS;

package/lib/types/registry.d.ts

@@ -0,0 +1,32 @@
+import type { DevtoolsRequest, DevtoolsResponse } from './envelope.js';
+import type { MethodKind } from './methods.js';
+export interface MethodEntry {
+    /** Method name (unique within a registry). */
+    name: string;
+    /** Pause classification. */
+    kind: MethodKind;
+    /** Handler — receives params (defaulted to `{}`), returns the result value. */
+    handler: (params: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+export interface DispatchOptions {
+    /** When true, `mutating` methods are rejected with a `paused` error. */
+    paused?: boolean;
+}
+/**
+ * Transport-agnostic method registry + policy dispatcher. The in-app
+ * adapters (DBus / WebSocket) register handlers here and route inbound
+ * requests through {@link dispatch}; the pause policy and the
+ * unclassified-method guard live here so every transport enforces them
+ * identically. Pure TS — unit-tested on Node + GJS.
+ */
+export declare class MethodRegistry {
+    private readonly _methods;
+    register(entry: MethodEntry): void;
+    has(name: string): boolean;
+    list(): {
+        name: string;
+        kind: MethodKind;
+    }[];
+    /** Dispatch a request through the pause policy. Never throws — failures become error responses. */
+    dispatch(req: DevtoolsRequest, opts?: DispatchOptions): Promise<DevtoolsResponse>;
+}

package/lib/types/registry.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/routing.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Coerce a free-form instance label into a valid app-id segment
+ * (letter-led, lowercase alphanumeric). Shared by the in-app adapter and
+ * the MCP bridge so both derive the SAME per-instance bus name — replacing
+ * the byte-identical hand-maintained duplication the map-editor needed when
+ * its bridge was dependency-free.
+ */
+export declare function sanitizeInstanceId(label: string): string;
+export interface BusAddress {
+    busName: string;
+    objectPath: string;
+    instance: string;
+}
+/**
+ * Resolve an instance label to its DBus bus name + devtools object path,
+ * given the app's base id (e.g. `"org.example.App"`). The default instance
+ * keeps the bare base; a named instance gets a `.<segment>` bus-name suffix
+ * and a `/<segment>` path segment, so the bridge dials the right process
+ * when several run side by side.
+ *
+ * Mirrors `Gio.Application`'s own object-path derivation (id dots → slashes,
+ * leading slash) plus a trailing `/devtools` leaf. The in-app adapter should
+ * prefer the authoritative `app.get_dbus_object_path() + '/devtools'`; this
+ * helper lets the bridge predict the same address for the dotted-id case.
+ *
+ * - `("org.example.App")` → `org.example.App` @ `/org/example/App/devtools`
+ * - `("org.example.App", "host")` → `org.example.App.host` @ `/org/example/App/host/devtools`
+ */
+export declare function resolveBusAddress(base: string, label?: string): BusAddress;

package/lib/types/routing.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/transport.d.ts

@@ -0,0 +1,23 @@
+import type { DevtoolsRequest, DevtoolsResponse } from './envelope.js';
+/** Handles an inbound request on the app (server) side. */
+export type DevtoolsHandler = (req: DevtoolsRequest) => Promise<DevtoolsResponse>;
+/**
+ * App-side transport: exposes the control plane over some channel — a
+ * `Gio.DBusExportedObject` (GTK), a WebSocket server (web) — by wiring a
+ * handler. The same {@link MethodRegistry} feeds every transport.
+ */
+export interface DevtoolsServerTransport {
+    serve(handler: DevtoolsHandler): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Bridge-side transport: dials a running app's control plane (a DBus client
+ * for GTK, a WebSocket client for web) and issues request/response
+ * round-trips. The MCP bridge talks the contract over whichever transport
+ * it is given, so its tools are identical across runtimes.
+ */
+export interface DevtoolsClientTransport {
+    connect(): Promise<void>;
+    request(req: DevtoolsRequest): Promise<DevtoolsResponse>;
+    close(): Promise<void>;
+}

package/lib/types/types.d.ts

@@ -0,0 +1,50 @@
+/** Snapshot returned by `GetStatus`. Extensions merge extra keys in. */
+export interface DevtoolsStatus {
+    appId: string;
+    instance: string;
+    activeWindow: {
+        id: string;
+        title: string;
+        mapped: boolean;
+    } | null;
+    toplevelCount: number;
+    focusedWidget: string | null;
+    /** Whether external (AI/automation) control is paused by the host. */
+    paused: boolean;
+    /** Extension-contributed keys. */
+    [key: string]: unknown;
+}
+/** One GAction (GTK) or named command (web) descriptor. */
+export interface ActionDescriptor {
+    name: string;
+    enabled: boolean;
+    parameterType: string | null;
+    stateType: string | null;
+    state?: unknown;
+}
+/**
+ * Result of `ListActions`. `app`/`win` mirrors GTK's two action scopes; web
+ * adapters list global commands under `app` and leave `win` empty.
+ */
+export interface ActionList {
+    app: ActionDescriptor[];
+    win: ActionDescriptor[];
+}
+/**
+ * A node in an introspection tree — a GTK widget or a DOM element. The
+ * shape is shared so the same MCP tools render both runtimes.
+ */
+export interface NodeInfo {
+    /** Stable path from a toplevel, e.g. "toplevel:0/child:2/child:0". */
+    path: string;
+    /** GType name (GTK) or tagName (DOM). */
+    type: string;
+    /** gtk widget name / DOM id, if any. */
+    name: string | null;
+    cssClasses: string[];
+    mapped: boolean;
+    visible: boolean;
+    /** Shallow scalar properties, when requested. */
+    props?: Record<string, unknown>;
+    children: NodeInfo[];
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+    "name": "@gjsify/devtools-protocol",
+    "version": "0.8.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",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib"
+    ],
+    "scripts": {
+        "clear": "rm -rf lib tmp tsconfig.tsbuildinfo test.gjs.mjs || exit 0",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "devtools",
+        "debug",
+        "mcp",
+        "dbus",
+        "gtk"
+    ],
+    "dependencies": {},
+    "devDependencies": {
+        "@gjsify/cli": "^0.8.0",
+        "@gjsify/unit": "^0.8.0",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        }
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/framework/devtools-protocol"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/framework/devtools-protocol#readme"
+}