feat(hub): expose PTY session results

Author: dvcolomban

docs/content/5.add-ons/1.devframes/6.terminals.md

@@ -61,7 +61,7 @@ Mounted into a hub, the devframe spawns on its own channel (`devframes:plugin:te
 
 `ctx.terminals` is the source of truth; the devframe, the sole PTY provider, duck-types a minimal `register` / `update` / `events` shape to run without `@devframes/hub`.
 
-`startChildProcess()` sessions carry a `getResult()` accessor (`tinyexec`'s `Result`: `await`able `{ stdout, stderr, exitCode }`, plus live getters and `kill()`).
+Both spawned session types carry a `getResult()` accessor. A `startChildProcess()` result is an `await`able `{ stdout, stderr, exitCode }` with live process getters and `kill()`. A `startPtySession()` result captures its merged terminal stream as an `await`able `{ output, exitCode, signal }` with live `pid`, `exitCode`, and `killed` getters.
 
 ## Focusing a session
 

packages/hub/src/node/__tests__/host-terminals.test.ts

@@ -418,6 +418,118 @@ describe('devframeTerminalHost interactive PTY sessions', () => {
     })
   })
 
+  itPty('getResult() resolves merged PTY output after natural exit', async () => {
+    const { host } = createTerminalHost()
+
+    const session = await host.startPtySession({
+      command: NODE,
+      args: ['-e', 'process.stdout.write("out"); process.stderr.write("err")'],
+    }, { id: 'pty-result', title: 'PTY result' })
+    const result = session.getResult()
+
+    expect(result.pid).toBeTypeOf('number')
+    expect(result.exitCode).toBeUndefined()
+    expect(result.killed).toBe(false)
+
+    const output = await result
+    expect(output.output).toContain('out')
+    expect(output.output).toContain('err')
+    expect(output.exitCode).toBe(0)
+    expect(output.signal).toBeUndefined()
+    expect(result.exitCode).toBe(0)
+    expect(result.killed).toBe(false)
+  })
+
+  itPty('getResult() preserves a non-zero PTY exit code', async () => {
+    const { host } = createTerminalHost()
+
+    const session = await host.startPtySession({
+      command: NODE,
+      args: ['-e', 'process.stdout.write("failed"); process.exit(3)'],
+    }, { id: 'pty-result-error', title: 'PTY result error' })
+    const result = session.getResult()
+
+    await expect(result).resolves.toMatchObject({
+      output: expect.stringContaining('failed'),
+      exitCode: 3,
+      signal: undefined,
+    })
+    expect(result.exitCode).toBe(3)
+    expect(result.killed).toBe(false)
+  })
+
+  itPty('getResult() marks a terminated PTY run as killed', async () => {
+    const { host } = createTerminalHost()
+
+    const session = await host.startPtySession({
+      command: NODE,
+      args: ['-e', 'process.stdout.write("started"); setInterval(() => {}, 4000)'],
+    }, { id: 'pty-result-terminate', title: 'PTY result terminate' })
+    const result = session.getResult()
+    await waitUntil(() => {
+      expect(session.buffer?.join('')).toContain('started')
+    })
+
+    await session.terminate()
+
+    expect(result.killed).toBe(true)
+    expect(result.exitCode).toBeUndefined()
+    await expect(result).resolves.toMatchObject({
+      output: expect.stringContaining('started'),
+      exitCode: undefined,
+      signal: expect.any(Number),
+    })
+  })
+
+  itPty('isolates getResult() output between independently spawned PTY sessions', async () => {
+    const { host } = createTerminalHost()
+
+    const firstSession = await host.startPtySession({
+      command: NODE,
+      args: ['-e', 'process.stdout.write("first-run")'],
+    }, { id: 'pty-result-first', title: 'First PTY result' })
+    const secondSession = await host.startPtySession({
+      command: NODE,
+      args: ['-e', 'process.stdout.write("second-run")'],
+    }, { id: 'pty-result-second', title: 'Second PTY result' })
+
+    const [firstOutput, secondOutput] = await Promise.all([firstSession.getResult(), secondSession.getResult()])
+    expect(firstOutput.output).toContain('first-run')
+    expect(firstOutput.output).not.toContain('second-run')
+    expect(secondOutput.output).toContain('second-run')
+    expect(secondOutput.output).not.toContain('first-run')
+  })
+
+  itPty('getResult() isolates the previous PTY run after restart()', async () => {
+    const { host } = createTerminalHost()
+
+    const session = await host.startPtySession({
+      command: NODE,
+      args: ['-e', 'process.stdout.write("run:" + process.pid); setInterval(() => {}, 4000)'],
+    }, { id: 'pty-result-restart', title: 'PTY result restart' })
+    const firstResult = session.getResult()
+    await waitUntil(() => {
+      expect(session.buffer?.join('')).toContain(`run:${firstResult.pid}`)
+    })
+
+    await session.restart()
+    const secondResult = session.getResult()
+    expect(secondResult).not.toBe(firstResult)
+    expect(secondResult.pid).not.toBe(firstResult.pid)
+    await waitUntil(() => {
+      expect(session.buffer?.join('')).toContain(`run:${secondResult.pid}`)
+    })
+
+    await session.terminate()
+    const [firstOutput, secondOutput] = await Promise.all([firstResult, secondResult])
+    expect(firstResult.killed).toBe(true)
+    expect(secondResult.killed).toBe(true)
+    expect(firstOutput.output).toContain(`run:${firstResult.pid}`)
+    expect(firstOutput.output).not.toContain(`run:${secondResult.pid}`)
+    expect(secondOutput.output).toContain(`run:${secondResult.pid}`)
+    expect(secondOutput.output).not.toContain(`run:${firstResult.pid}`)
+  })
+
   itPty('does not accept resize after termination without throwing', async () => {
     const { host } = createTerminalHost()
 

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

@@ -8,6 +8,8 @@ import type {
   DevframeChildProcessResult,
   DevframeChildProcessTerminalSession,
   DevframePtyExecuteOptions,
+  DevframePtyOutput,
+  DevframePtyResult,
   DevframePtyTerminalSession,
   DevframeTerminalSession,
   DevframeTerminalSessionBase,
@@ -365,6 +367,8 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
 
     let controller: ReadableStreamDefaultController<string> | undefined
     let pty: IPty | undefined
+    let currentResult: DevframePtyResult | undefined
+    let killCurrentRun: (() => void) | undefined
     let runId = 0
     let streamClosed = false
     let session: DevframePtyTerminalSession
@@ -409,7 +413,7 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
         controller = _controller
       },
       cancel() {
-        pty?.kill()
+        killCurrentRun?.()
         pty = undefined
         closeStream()
       },
@@ -430,12 +434,36 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
           ...(executeOptions.env ?? {}),
         },
       })
-      proc.onData((data) => {
-        if (streamClosed || currentRun !== runId)
+      const outputChunks: string[] = []
+      let killed = false
+      let settled = false
+      let settledExitCode: number | undefined
+      let resolveOutput!: (output: DevframePtyOutput) => void
+      const outputPromise = new Promise<DevframePtyOutput>((resolve) => {
+        resolveOutput = resolve
+      })
+
+      const settle = (exitCode: number, signal: number): void => {
+        if (settled)
           return
-        controller?.enqueue(typeof data === 'string' ? data : data.toString('utf8'))
+        settled = true
+        killed ||= signal !== 0
+        settledExitCode = killed ? undefined : exitCode
+        resolveOutput({
+          output: outputChunks.join(''),
+          exitCode: settledExitCode,
+          signal: signal === 0 ? undefined : signal,
+        })
+      }
+
+      proc.onData((data) => {
+        const text = typeof data === 'string' ? data : data.toString('utf8')
+        outputChunks.push(text)
+        if (!streamClosed && currentRun === runId)
+          controller?.enqueue(text)
       })
       proc.onExit(({ exitCode, signal }) => {
+        settle(exitCode, signal)
         if (currentRun !== runId)
           return
         closeStream()
@@ -444,6 +472,24 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
         // code is a crash, matching the child-process comment above.
         markStatus(signal === 0 && exitCode !== 0 ? 'error' : 'stopped')
       })
+      currentResult = {
+        get pid() {
+          return proc.pid
+        },
+        get exitCode() {
+          return killed ? undefined : (proc.exitCode ?? settledExitCode)
+        },
+        get killed() {
+          return killed
+        },
+        then: (onfulfilled, onrejected) => outputPromise.then(onfulfilled, onrejected),
+      }
+      killCurrentRun = () => {
+        if (proc.exitCode !== null)
+          return
+        killed = true
+        proc.kill()
+      }
       return proc
     }
 
@@ -490,16 +536,17 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
           return undefined
         }
       },
+      getResult: () => currentResult!,
       terminate: async () => {
-        pty?.kill()
+        killCurrentRun?.()
         pty = undefined
         closeStream()
         markStatus('stopped')
       },
       restart: async () => {
         if (streamClosed)
           throw diagnostics.DF8206({ id: terminal.id })
-        pty?.kill()
+        killCurrentRun?.()
         pty = spawnPty()
         markStatus('running')
       },

packages/hub/src/types/terminals.ts

@@ -129,6 +129,25 @@ export interface DevframePtyExecuteOptions {
   rows?: number
 }
 
+/**
+ * The settled outcome of a {@link DevframePtyTerminalSession} run. PTYs merge
+ * stdout and stderr into one terminal output stream, so the captured text is
+ * exposed as a single `output` value.
+ */
+export interface DevframePtyOutput {
+  output: string
+  exitCode: number | undefined
+  signal: number | undefined
+}
+
+/** A live handle on the current PTY run's merged output and process state. */
+export interface DevframePtyResult extends PromiseLike<DevframePtyOutput> {
+  readonly pid: number | undefined
+  /** `undefined` while the process is running or after a signal kill. */
+  readonly exitCode: number | undefined
+  readonly killed: boolean
+}
+
 export interface DevframePtyTerminalSession extends DevframeTerminalSession {
   type: 'pty'
   interactive: true
@@ -139,6 +158,11 @@ export interface DevframePtyTerminalSession extends DevframeTerminalSession {
   resize: (cols: number, rows: number) => void
   /** Current foreground process name, when the backend can resolve it. */
   getProcessName: () => string | undefined
+  /**
+   * Get a live handle on the current run's outcome. Call it again after
+   * `restart()` to track the new run.
+   */
+  getResult: () => DevframePtyResult
   terminate: () => Promise<void>
   /** Throws `DF8206` once the session's output stream has closed (after a natural exit or `terminate()`) — drop it with `ctx.terminals.remove(session)` and start a fresh session instead. */
   restart: () => Promise<void>

tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts

@@ -229,13 +229,24 @@ export interface DevframePtyExecuteOptions {
   cols?: number;
   rows?: number;
 }
+export interface DevframePtyOutput {
+  output: string;
+  exitCode: number | undefined;
+  signal: number | undefined;
+}
+export interface DevframePtyResult extends PromiseLike<DevframePtyOutput> {
+  readonly pid: number | undefined;
+  readonly exitCode: number | undefined;
+  readonly killed: boolean;
+}
 export interface DevframePtyTerminalSession extends DevframeTerminalSession {
   type: 'pty';
   interactive: true;
   executeOptions: DevframePtyExecuteOptions;
   write: (_: string) => void;
   resize: (_: number, _: number) => void;
   getProcessName: () => string | undefined;
+  getResult: () => DevframePtyResult;
   terminate: () => Promise<void>;
   restart: () => Promise<void>;
 }

tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts

@@ -52,6 +52,8 @@ export { DevframeMessagesLevelShortcuts }
 export { DevframeMessagesListDelta }
 export { DevframeNodeRpcSession }
 export { DevframePtyExecuteOptions }
+export { DevframePtyOutput }
+export { DevframePtyResult }
 export { DevframePtyTerminalSession }
 export { DevframeRpcClientFunctions }
 export { DevframeRpcServerFunctions }