wip: terminals support

Author: antfu

package.json

@@ -44,6 +44,7 @@
     "@types/ws": "catalog:types",
     "@typescript-eslint/utils": "catalog:devtools",
     "@unocss/eslint-config": "catalog:devtools",
+    "@vueuse/core": "catalog:frontend",
     "ansis": "catalog:deps",
     "bumpp": "catalog:devtools",
     "esbuild": "catalog:build",

packages/core/package.json

@@ -67,6 +67,7 @@
     "pathe": "catalog:deps",
     "perfect-debounce": "catalog:deps",
     "sirv": "catalog:deps",
+    "tinyexec": "catalog:deps",
     "ws": "catalog:deps"
   },
   "devDependencies": {

packages/core/src/node/context.ts

@@ -4,6 +4,7 @@ import Debug from 'debug'
 import { ContextUtils } from './context-utils'
 import { DevToolsDockHost } from './host-docks'
 import { RpcFunctionsHost } from './host-functions'
+import { DevToolsTerminalHost } from './host-terminals'
 import { DevToolsViewHost } from './host-views'
 import { builtinRpcFunctions } from './rpc'
 
@@ -24,13 +25,16 @@ export async function createDevToolsContext(
     docks: undefined!,
     views: undefined!,
     utils: ContextUtils,
+    terminals: undefined!,
   }
   const rpcHost = new RpcFunctionsHost(context)
   const docksHost = new DevToolsDockHost(context)
   const viewsHost = new DevToolsViewHost(context)
+  const terminalsHost = new DevToolsTerminalHost(context)
   context.rpc = rpcHost
   context.docks = docksHost
   context.views = viewsHost
+  context.terminals = terminalsHost
 
   // Build-in function to list all RPC functions
   for (const fn of builtinRpcFunctions) {

packages/core/src/node/host-docks.ts

@@ -9,6 +9,7 @@ export class DevToolsDockHost implements DevToolsDockHostType {
     public readonly context: DevToolsNodeContext,
   ) {
     this._sendOnChange = debounce(() => {
+      // TODO: externalize this
       context.rpc?.boardcast?.$callOptional('vite:core:list-dock-entries:updated')
     }, 10)
   }

packages/core/src/node/host-terminals.ts

@@ -0,0 +1,107 @@
+import type { DevToolsChildProcessTerminalOptions, DevToolsChildProcessTerminalSession, DevToolsNodeContext, DevToolsTerminalHost as DevToolsTerminalHostType, DevToolsTerminalSession, DevToolsTerminalSessionSerializable } from '@vitejs/devtools-kit'
+import type { Result as TinyExecResult } from 'tinyexec'
+import process from 'node:process'
+
+export class DevToolsTerminalHost implements DevToolsTerminalHostType {
+  constructor(
+    public readonly context: DevToolsNodeContext,
+  ) {
+  }
+
+  readonly sessions: Map<string, DevToolsTerminalSession> = new Map()
+
+  serialize(session: DevToolsTerminalSession): DevToolsTerminalSessionSerializable {
+    return {
+      id: session.id,
+      title: session.title,
+      description: session.description,
+      status: session.status,
+      buffer: session.buffer ?? [],
+    }
+  }
+
+  register(session: DevToolsTerminalSession): DevToolsTerminalSession {
+    if (this.sessions.has(session.id)) {
+      throw new Error(`Terminal session with id "${session.id}" already registered`)
+    }
+    this.sessions.set(session.id, session)
+    return session
+  }
+
+  update(session: DevToolsTerminalSession): void {
+    if (!this.sessions.has(session.id)) {
+      throw new Error(`Terminal session with id "${session.id}" not registered`)
+    }
+    this.sessions.set(session.id, session)
+  }
+
+  async startChildProcess(options: DevToolsChildProcessTerminalOptions): Promise<DevToolsChildProcessTerminalSession> {
+    if (this.sessions.has(options.id)) {
+      throw new Error(`Terminal session with id "${options.id}" already registered`)
+    }
+    const { exec } = await import('tinyexec')
+
+    let controller: ReadableStreamDefaultController<string> | undefined
+    const buffer = new ReadableStream<string>({
+      async start(_controller) {
+        controller = _controller
+      },
+    })
+    const writer = new WritableStream<string>({
+      write(chunk) {
+        controller?.enqueue(chunk)
+      },
+    })
+
+    function createChildProcess() {
+      const cp = exec(
+        options.command,
+        options.args || [],
+        {
+          nodeOptions: {
+            env: {
+              COLORS: 'true',
+              FORCE_COLOR: 'true',
+              ...(options.env || {}),
+            },
+            cwd: options.cwd ?? process.cwd(),
+            stdio: 'pipe',
+          },
+        },
+      )
+
+      const stream = new ReadableStream<string>({
+        async start(controller) {
+          for await (const chunk of cp) {
+            controller.enqueue(chunk)
+          }
+        },
+      })
+      stream.pipeTo(writer)
+      return cp
+    }
+
+    let cp: TinyExecResult | undefined = createChildProcess()
+
+    const restart = async () => {
+      cp?.kill()
+      cp = createChildProcess()
+    }
+    const terminate = async () => {
+      cp?.kill()
+      cp = undefined
+    }
+
+    const session: DevToolsChildProcessTerminalSession = {
+      ...options,
+      status: 'running',
+      stream: buffer,
+      getChildProcess: () => cp?.process,
+      terminate,
+      restart,
+    }
+    this.sessions.set(session.id, session)
+
+    return Promise.resolve(session)
+  }
+}

packages/core/src/node/rpc/list-terminals.ts

@@ -0,0 +1,13 @@
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+
+export const listTerminals = defineRpcFunction({
+  name: 'vite:core:list-terminals',
+  type: 'action',
+  setup: (context) => {
+    return {
+      async handler() {
+        return Array.from(context.terminals.sessions.values())
+      },
+    }
+  },
+})

packages/kit/src/types/index.ts

@@ -1,6 +1,7 @@
 export * from './docks'
 export * from './rpc'
 export * from './rpc-augments'
+export * from './terminals'
 export * from './utils'
 export * from './views'
 export * from './vite-augment'

packages/kit/src/types/terminals.ts

@@ -0,0 +1,42 @@
+import type { ChildProcess } from 'node:child_process'
+
+export interface DevToolsTerminalHost {
+  readonly sessions: Map<string, DevToolsTerminalSession>
+
+  register: (session: DevToolsTerminalSession) => DevToolsTerminalSession
+  update: (session: DevToolsTerminalSession) => void
+
+  serialize: (session: DevToolsTerminalSession) => DevToolsTerminalSessionSerializable
+
+  startChildProcess: (options: DevToolsChildProcessTerminalOptions) => Promise<DevToolsChildProcessTerminalSession>
+}
+
+export type DevToolsTerminalStatus = 'running' | 'stopped' | 'error'
+
+export interface DevToolsTerminalSessionBase {
+  id: string
+  title: string
+  description?: string
+}
+
+export interface DevToolsTerminalSessionSerializable extends DevToolsTerminalSessionBase {
+  status: DevToolsTerminalStatus
+  buffer?: string[]
+}
+
+export interface DevToolsTerminalSession extends DevToolsTerminalSessionSerializable {
+  stream?: ReadableStream<string>
+}
+
+export interface DevToolsChildProcessTerminalOptions extends DevToolsTerminalSessionBase {
+  command: string
+  args: string[]
+  cwd?: string
+  env?: Record<string, string>
+}
+
+export interface DevToolsChildProcessTerminalSession extends DevToolsTerminalSession {
+  getChildProcess: () => ChildProcess | undefined
+  terminate: () => Promise<void>
+  restart: () => Promise<void>
+}

packages/kit/src/types/vite-plugin.ts

@@ -2,6 +2,7 @@ import type { ResolvedConfig, ViteDevServer } from 'vite'
 import type { DockClientScriptContext } from '../client'
 import type { ClientScriptEntry, DevToolsDockHost } from './docks'
 import type { RpcFunctionsHost } from './rpc'
+import type { DevToolsTerminalHost } from './terminals'
 import type { DevToolsViewHost } from './views'
 
 export interface DevToolsCapabilities {
@@ -26,6 +27,7 @@ export interface DevToolsNodeContext {
   docks: DevToolsDockHost
   views: DevToolsViewHost
   utils: DevToolsNodeUtils
+  terminals: DevToolsTerminalHost
 }
 
 export interface DevToolsNodeUtils {

packages/vite/package.json

@@ -70,6 +70,7 @@
     "@types/stream-json": "catalog:types",
     "@unocss/nuxt": "catalog:build",
     "@vueuse/components": "catalog:frontend",
+    "@vueuse/core": "catalog:frontend",
     "@vueuse/nuxt": "catalog:build",
     "@vueuse/router": "catalog:frontend",
     "codemirror": "catalog:frontend",