#moonbit-community/pty

#API

@async.with_task_group(group => {
  let pty = @pty.spawn(group, ["/bin/sh", "-c", "echo hello"])
  defer pty.close()

  let reader = pty.reader()               // @raw_fd.RawFd
  pty.write(@utf8.encode("ls\n"))         // async
  pty.resize(cols=120, rows=40)
  let pid : Int = pty.pid()
  let exit_code : Int = pty.wait()
})

#Errors

try {
  @async.with_task_group(group => {
    @pty.spawn(group, ["/bin/missing"])
  })
} catch {
  err is @os_error.OSError if err.is_ENOENT() => ...
  err => raise err
}

#Platform strategies

#Windows: ConPTY process startup

1. Create two synchronous pipes:
   • input pipe: parent writes keyboard input to inputWriteSide; ConPTY reads from inputReadSide
   • output pipe: ConPTY writes screen output to outputWriteSide; parent reads from outputReadSide
2. Call CreatePseudoConsole(size, inputReadSide, outputWriteSide, ...).
3. Prepare STARTUPINFOEX with PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE.
4. Call CreateProcessA(..., EXTENDED_STARTUPINFO_PRESENT, ...).
5. After CreateProcessA succeeds, close inputReadSide and outputWriteSide in the parent. The parent keeps only inputWriteSide and outputReadSide for async I/O.

#Why STARTF_USESTDHANDLES is set

• microsoft/node-pty sets STARTF_USESTDHANDLES, passes null stdio handles, and creates the child with bInheritHandles=false.
• wezterm/portable-pty sets STARTF_USESTDHANDLES and uses invalid stdio handles to prevent the child from inheriting redirected parent output handles.

#Current Windows argv limitations

#macOS: the mimalloc + fork problem

#Unix: the self-helper pattern

1. openpty() creates a PTY pair (master + slave fd).
2. The parent creates two pipes — argv_pipe (parent → helper) and err_pipe (helper → parent) — and a dummy pipe write end whose fd is rebound to the PTY slave with dup2(slave, dummy_write.fd()).
3. spawn launches the current command inside the caller's task group with:
   • stdin=argv_pipe.read
   • stdout=dummy_write (now the PTY slave fd)
   • stderr=err_pipe.write
   • MOONBIT_PTY_EXEC=stdio
4. The constructor detects helper mode, duplicates stderr to keep the error pipe, treats fd 0 as argv input and fd 1 as the PTY slave, then calls login_tty(1).
5. The parent streams the target argv (flattened as arg0\0arg1\0…argN\0) into argv_pipe and closes its write end.
6. The constructor reads argv from argv_pipe until EOF, arms FD_CLOEXEC on its copy of the error pipe, and execvp()s. A successful exec auto-closes the error pipe so the parent sees EOF; any pre-exec failure writes the errno to the pipe and _exit()s.
7. The parent reads from the error pipe: 4 bytes → failure with that errno, EOF → success.

#Why argv must be copied