pty-serv 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# pty-serve
+
+Spawns a command in a [node-pty](https://github.com/microsoft/node-pty) pseudo-terminal and exposes an HTTP endpoint to interact with it at runtime.
+
+## Installation
+
+```bash
+npm install -g pty-serve
+```
+
+## Usage
+
+Run a shell, then send a command from another process:
+
+```bash
+# Terminal 1 – start the PTY server
+pty-serve -s /tmp/pty-serve-0.sock -- bash
+
+# Terminal 2 – interact with it
+curl --unix-socket /tmp/pty-serve-0.sock 'http://[::]/write' --data $'echo hello\r'
+```
+
+### CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `-s, --socket <path>` | Unix socket path to listen on |
+| `-p, --port <number>` | TCP port to listen on |
+| `-h, --hostname <string>` | Hostname for TCP listener (default: all interfaces) |
+| `-o, --options <json>` | JSON options forwarded to [node-pty](https://github.com/microsoft/node-pty) |
+
+### HTTP Endpoint
+
+#### `POST /write`
+
+Write raw data to the PTY's stdin. The request body is streamed directly to the PTY.
+
+```bash
+curl 'http://[::]/write' -d $'ls\r'
+```
+
+#### `POST /resize`
+
+Resize the PTY window.
+
+```bash
+curl 'http://[::]/resize' -d '{"cols":220,"rows":50}'
+```
+
+#### `POST /kill`
+
+Send a signal to the PTY process.
+
+```bash
+curl 'http://[::]/kill' -d '{"signal":"SIGTERM"}'
+```
+
+#### `POST /clear`
+
+Clear the PTY screen buffer.
+
+```bash
+curl 'http://[::]/clear' -X POST
+```
+
+#### `POST /pause` / `POST /resume`
+
+Pause or resume data flow from the PTY.
+
+```bash
+curl 'http://[::]/pause' -X POST
+curl 'http://[::]/resume' -X POST
+```

package/bin/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/cli.js';

package/dist/cli.js

@@ -0,0 +1,88 @@
+import { createServer } from 'node:http';
+import { program } from 'commander';
+import * as pty from 'node-pty';
+program
+    .option('-o, --options <string>', 'JSON options forwarded to `node-pty`')
+    .option('-s, --socket <string>', 'Unix socket path to listen on')
+    .option('-h, --hostname <string>', 'Hostname for TCP listener')
+    .option('-p, --port <number>', 'TCP port to listen on')
+    .allowExcessArguments()
+    .parse();
+const opts = program.opts();
+const server = createServer();
+const ptyProcess = pty.spawn(program.args[0], program.args.slice(1), opts.options && JSON.parse(opts.options));
+console.log('PTY spawned with PID:', ptyProcess.pid);
+ptyProcess.onData((chunk) => {
+    process.stdout.write(chunk);
+});
+let hasExit = false;
+ptyProcess.onExit((info) => {
+    hasExit = true;
+    server.close();
+    process.exit(info.exitCode);
+});
+const EXIT_SIGNALS = ['SIGINT', 'SIGTERM'];
+EXIT_SIGNALS.forEach((signal) => {
+    process.on(signal, () => {
+        if (!hasExit) {
+            ptyProcess.kill(process.platform === 'win32' ? undefined : signal);
+        }
+        server.close();
+        process.exit(0);
+    });
+});
+server.on('request', async (req, res) => {
+    try {
+        await handleRequest(req);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ code: 0 }));
+    }
+    catch (error) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ code: -1, message: String(error) }));
+    }
+});
+if (opts.socket) {
+    server.listen(opts.socket);
+}
+else {
+    server.listen(opts.port, opts.hostname);
+}
+async function handleRequest(req) {
+    switch (req.url) {
+        case '/resize': {
+            const data = await parseBody(req);
+            ptyProcess.resize(data.cols, data.rows);
+            return;
+        }
+        case '/clear':
+            ptyProcess.clear();
+            return;
+        case '/write':
+            for await (const chunk of req) {
+                ptyProcess.write(chunk);
+            }
+            return;
+        case '/kill': {
+            const data = await parseBody(req);
+            ptyProcess.kill(data.signal);
+            return;
+        }
+        case '/pause':
+            ptyProcess.pause();
+            return;
+        case '/resume':
+            ptyProcess.resume();
+            return;
+    }
+}
+async function parseBody(req) {
+    if (req.method !== 'POST') {
+        throw new Error(`Can't parse body for ${req.method} request`);
+    }
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(chunk);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString());
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "pty-serv",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gzzhanghao/node-pty-serve.git"
+  },
+  "type": "module",
+  "bin": {
+    "pty-serve": "./dist/index.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --import tsx/esm --experimental-test-coverage --test src/cli.test.ts"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.0",
+    "eslint": "^10.0.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1",
+    "rolldown": "1.0.0-rc.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1"
+  },
+  "packageManager": "pnpm@10.30.3"
+}