@punica/editor 1.3.6 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.3.6",
+  "version": "1.4.0",
   "description": "Punica Editor",
   "private": false,
   "type": "module",

package/types/index.d.ts

@@ -39,6 +39,7 @@
 /// <reference path="punica.module.runtime.lifecycle.d.ts" />
 /// <reference path="punica.module.runtime.capabilities.d.ts" />
 /// <reference path="punica.module.runtime.harness.d.ts" />
+/// <reference path="punica.module.runtime.debug.d.ts" />
 /// <reference path="punica.module.runtime.api.d.ts" />
 /// <reference path="punica.module.flow.d.ts" />
 /// <reference path="punica.module.flow.primitives.d.ts" />

package/types/punica.module.runtime.api.d.ts

@@ -5,6 +5,7 @@
 /// <reference path="punica.module.runtime.modelRuntimes.d.ts" />
 /// <reference path="punica.module.runtime.inference.d.ts" />
 /// <reference path="punica.module.runtime.vectors.d.ts" />
+/// <reference path="punica.module.runtime.debug.d.ts" />
 
 declare module 'punica' {
   export namespace runtime {
@@ -148,6 +149,15 @@ declare module 'punica' {
        */
       capabilities: CapabilitiesApi;
 
+      /**
+       * Message-oriented transport to DAP debug adapters. Hosts with
+       * local process access (Electron) inject a concrete provider;
+       * absent on hosts without one (browser). Extensions should
+       * feature-detect via `punica.runtime.debug.list()` failure or the
+       * host platform before offering debug UI.
+       */
+      debug: debug.DebugAdapterApi;
+
       /**
        * Host wiring helpers for registering providers.
        * These methods are always available at runtime for extension convenience.
@@ -164,6 +174,7 @@ declare module 'punica' {
       setSearchProvider: (provider: SearchApi) => void;
       setWorkspaceProvider: (provider: WorkspaceApi) => void;
       setTerminalProvider: (provider: TerminalApi) => void;
+      setDebugProvider: (provider: debug.DebugAdapterApi) => void;
       setVcsProvider: (provider: VcsApi) => void;
       setResourcesProvider: (provider: ResourcesApi) => void;
       setTasksProvider: (provider: TaskRunnerApi) => void;

package/types/punica.module.runtime.debug.d.ts

@@ -0,0 +1,91 @@
+declare module 'punica' {
+  export namespace runtime {
+    export namespace debug {
+      /**
+       * How to reach a DAP (Debug Adapter Protocol) adapter. The host owns
+       * the transport (process lifetime, sockets, Content-Length framing)
+       * and exchanges parsed protocol messages with extensions.
+       */
+      export type DebugAdapterTransport =
+        /**
+         * Spawn the adapter and speak DAP over piped stdio
+         * (e.g. `python -m debugpy.adapter`).
+         */
+        | {
+            kind: 'stdio';
+            command: string;
+            args?: string[];
+            cwd?: string;
+            env?: Record<string, string>;
+          }
+        /**
+         * Spawn an adapter that listens on TCP, then connect to it
+         * (e.g. `dlv dap --listen=…`, js-debug's dapDebugServer). When
+         * `port` is absent the host picks a free port and substitutes the
+         * literal token `${port}` in `args` before spawning.
+         */
+        | {
+            kind: 'server';
+            command: string;
+            args?: string[];
+            cwd?: string;
+            env?: Record<string, string>;
+            port?: number;
+            host?: string;
+            connectTimeoutMs?: number;
+          }
+        /**
+         * Connect to an already-running adapter (attach scenarios, or a
+         * second connection for js-debug child sessions).
+         */
+        | { kind: 'tcp'; host?: string; port: number };
+
+      export interface DebugAdapterSessionInfo {
+        id: string;
+        transport: DebugAdapterTransport['kind'];
+        /** Adapter process pid (stdio/server transports). */
+        pid?: number;
+        /** Resolved TCP port (server/tcp transports). */
+        port?: number;
+        createdAt: number;
+      }
+
+      /**
+       * Raw DAP ProtocolMessage. The host does framing only — no DAP
+       * semantics; request/response correlation and event handling live
+       * in the extension's DAP client.
+       */
+      export interface ProtocolMessage {
+        seq: number;
+        type: 'request' | 'response' | 'event' | string;
+        [key: string]: unknown;
+      }
+
+      /**
+       * Message-oriented debug adapter transport API. Hosts provide a
+       * concrete implementation (Electron: child_process + net; a future
+       * browser host: WebSocket bridge) and extensions only depend on
+       * this abstraction.
+       */
+      export interface DebugAdapterApi {
+        start(
+          transport: DebugAdapterTransport
+        ): Promise<DebugAdapterSessionInfo>;
+        send(id: string, message: ProtocolMessage): void;
+        onMessage(
+          id: string,
+          listener: (message: ProtocolMessage) => void
+        ): () => void;
+        /** Adapter's own stderr (diagnostics — NOT debuggee output). */
+        onStderr(id: string, listener: (chunk: string) => void): () => void;
+        onExit(
+          id: string,
+          listener: (code: number | null, signal?: string) => void
+        ): () => void;
+        /** Close the connection and terminate the adapter process. */
+        stop(id: string): Promise<void>;
+        list(): Promise<DebugAdapterSessionInfo[]>;
+      }
+    }
+  }
+}