rterm-cli 3.2.10 → 3.2.12

package/README.md

@@ -34,6 +34,7 @@ rterm version                              # backend version + method count
 rterm methods [--category terminal]        # self-describing RPC surface
 rterm call <method> [json-params]          # raw JSON-RPC call
 rterm terminals                            # list terminal tabs
+rterm connections                          # list saved SSH/WinRM/Serial connections
 rterm open <saved-connection-name>         # open a tab for a saved connection
 rterm close <tabIdOrName>                  # close a terminal tab
 rterm run <tabIdOrName> <command>          # run a command in a tab (waits)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rterm-cli",
-  "version": "3.2.10",
-  "description": "rterm — zero-dependency command CLI for the RTerm / neuralOS backend WebSocket gateway (ping, terminals, run, fleet, chat, dashboard, metrics, raw call)",
+  "version": "3.2.12",
+  "description": "rterm — zero-dependency command CLI for the RTerm / neuralOS backend WebSocket gateway (ping, terminals, connections, open, run, fleet, chat, dashboard, metrics, raw call)",
   "type": "module",
   "bin": {
     "rterm": "./rterm-cli.mjs",

package/rterm-cli.mjs

@@ -2,21 +2,14 @@
 /**
  * rterm-cli — a `gyll`-style command CLI for the RTerm / neuralOS backend.
  *
- * Speaks the backend's WebSocket JSON-RPC gateway natively (ws://host:17888):
- *   rterm ping
- *   rterm methods [--category cat] [--prefix p]
- *   rterm call <method> [json-params]
- *   rterm terminals
- *   rterm open <saved-connection-name>
- *   rterm run <tabIdOrName> <command>
- *   rterm chat <sessionId> <message>       (blocking; prints the final answer)
- *   rterm sessions
- *   rterm dashboard
- *   rterm metrics [--format prometheus|summary]
- *   rterm fleet <tab1,tab2> <command>
+ * Speaks the backend's WebSocket JSON-RPC gateway natively (ws://host:17888).
+ * Zero runtime dependencies: Node's built-in WebSocket (>= 21) with a `ws`
+ * package fallback.
  *
- * Zero runtime dependencies: uses Node's built-in WebSocket (Node >= 21) and
- * falls back to the `ws` package from the backend install when present.
+ * Commands:
+ *   rterm ping | version | methods | call | terminals | connections
+ *   rterm open <name> | close <tab> | run <tab> <cmd> | fleet <tabs> <cmd>
+ *   rterm sessions | chat <session> <msg> | dashboard | metrics
  */
 
 import { readFileSync, existsSync } from 'node:fs'
@@ -50,6 +43,25 @@ function parseArgs(argv) {
   return { positional, flags }
 }
 
+// ── error formatting (fix: errors used to print "[object Object]") ──────────
+
+/** Extract a readable message from any thrown/rejected value. */
+function errorMessage(value) {
+  if (value instanceof Error) return value.message
+  if (typeof value === 'string') return value
+  if (value && typeof value === 'object') {
+    // Gateway errors arrive as { code, message } or Error with .cause.
+    if (typeof value.message === 'string' && value.message) {
+      return value.code ? `${value.code}: ${value.message}` : value.message
+    }
+    if (typeof value.error === 'object' && value.error?.message) {
+      return `${value.error.code || 'ERROR'}: ${value.error.message}`
+    }
+    try { return JSON.stringify(value) } catch { return String(value) }
+  }
+  return String(value)
+}
+
 // ── gateway client ──────────────────────────────────────────────────────────
 
 let nextId = 1
@@ -73,8 +85,8 @@ function loadToken() {
   return null
 }
 
-async function openSocket(url) {
-  // Node >= 21 ships a native WebSocket client.
+async function openSocket(url, token) {
+  const headers = token ? { Authorization: `Bearer ${token}` } : undefined
   if (typeof globalThis.WebSocket === 'function') {
     return await new Promise((resolve, reject) => {
       const ws = new globalThis.WebSocket(url)
@@ -82,13 +94,12 @@ async function openSocket(url) {
       ws.onerror = () => reject(new Error(`Cannot connect to ${url}. Is the backend running? (gybackend)`))
     })
   }
-  // Fallback: the `ws` package (present in a backend checkout/install).
   try {
     const { createRequire } = await import('node:module')
     const require = createRequire(import.meta.url)
     const WS = require('ws')
     return await new Promise((resolve, reject) => {
-      const ws = new WS(url)
+      const ws = new WS(url, { headers })
       ws.on('open', () => resolve(ws))
       ws.on('error', () => reject(new Error(`Cannot connect to ${url}. Is the backend running? (gybackend)`)))
     })
@@ -97,8 +108,8 @@ async function openSocket(url) {
   }
 }
 
-async function call(url, method, params) {
-  const ws = await openSocket(url)
+async function call(url, method, params, token) {
+  const ws = await openSocket(url, token)
   const id = String(nextId++)
   return await new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
@@ -112,14 +123,15 @@ async function call(url, method, params) {
           clearTimeout(timer)
           try { ws.close() } catch { /* ignore */ }
           if (frame.ok) resolve(frame.result)
-          else reject(new Error(frame.error || `gateway error: ${method}`))
+          else reject(frame.error || new Error(`gateway error: ${method}`))
         }
       } catch { /* ignore non-JSON frames */ }
     }
-    const onClose = () => { clearTimeout(timer); reject(new Error('Connection closed before response.')) }
+    const onClose = () => {
+      clearTimeout(timer)
+      reject(new Error('Connection closed before response. Is the backend still running?'))
+    }
 
-    // Normalize the native WebSocket (addEventListener) and the `ws` package
-    // (on/on('message')) behind one interface.
     if (typeof ws.addEventListener === 'function') {
       ws.addEventListener('message', (event) => onMessage(event.data))
       ws.addEventListener('close', onClose)
@@ -138,6 +150,13 @@ async function call(url, method, params) {
   })
 }
 
+/** Client bound to a URL + token, so commands don't repeat them. */
+function makeClient(url, token) {
+  return {
+    call: (method, params) => call(url, method, params, token),
+  }
+}
+
 // ── output helpers ──────────────────────────────────────────────────────────
 
 function printJson(value) {
@@ -145,7 +164,7 @@ function printJson(value) {
 }
 
 function fail(message) {
-  console.error(`Error: ${message}`)
+  console.error(`Error: ${errorMessage(message)}`)
   process.exit(1)
 }
 
@@ -153,9 +172,11 @@ const HELP = `rterm — command CLI for the RTerm / neuralOS backend gateway
 
 Usage:
   rterm ping                                Liveness check
+  rterm version                             Backend version + method count
   rterm methods [--category c] [--prefix p] List gateway RPC methods
   rterm call <method> [json]                Raw JSON-RPC call (params as JSON)
   rterm terminals                           List terminal tabs
+  rterm connections                         List saved SSH/WinRM/Serial connections
   rterm open <connection-name>              Open a terminal tab for a saved connection
   rterm close <tabIdOrName>                 Close a terminal tab
   rterm run <tabIdOrName> <command>         Run a command in a terminal tab (waits)
@@ -164,7 +185,6 @@ Usage:
   rterm chat <sessionId> <message>          Send a message to the agent (blocking)
   rterm dashboard                           Print the live dashboard state
   rterm metrics [--format prometheus]       Host metrics
-  rterm version                             Backend version + method count
 
 Options:
   --url ws://host:port    Gateway URL (default ${DEFAULT_URL}, env RTERM_URL)
@@ -174,12 +194,121 @@ Environment:
   RTERM_URL, RTERM_HOST, RTERM_PORT, RTERM_TOKEN
 `
 
+// ── command helpers ─────────────────────────────────────────────────────────
+
+const ANSI_RE = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g
+
+function stripAnsi(text) {
+  return text.replace(ANSI_RE, '')
+}
+
+/**
+ * Resolve a saved connection by name or id across ssh/winrm/serial and build
+ * an inline terminal config the backend accepts (createTab does NOT resolve
+ * saved-connection names itself).
+ */
+function connectionToConfig(entry, kind) {
+  if (kind === 'ssh') {
+    return {
+      type: 'ssh',
+      host: entry.host,
+      port: entry.port ?? 22,
+      username: entry.username,
+      ...(entry.authMethod === 'privateKey'
+        ? { privateKey: entry.privateKey }
+        : { password: entry.password }),
+      ...(entry.algorithmsPreset ? { algorithmsPreset: entry.algorithmsPreset } : {}),
+      ...(entry.termType ? { termType: entry.termType } : {}),
+    }
+  }
+  if (kind === 'winrm') {
+    return {
+      type: 'winrm',
+      host: entry.host,
+      port: entry.port ?? 5985,
+      username: entry.username,
+      password: entry.password,
+      ...(entry.transport ? { transport: entry.transport } : {}),
+    }
+  }
+  return {
+    type: 'serial',
+    path: entry.path,
+    baudRate: entry.baudRate ?? 9600,
+  }
+}
+
+async function fetchConnections(client) {
+  const settings = await client.call('settings:get', {})
+  const conns = settings?.connections || {}
+  return {
+    ssh: Array.isArray(conns.ssh) ? conns.ssh : [],
+    winrm: Array.isArray(conns.winrm) ? conns.winrm : [],
+    serial: Array.isArray(conns.serial) ? conns.serial : [],
+  }
+}
+
+async function resolveConnection(client, nameOrId) {
+  const { ssh, winrm, serial } = await fetchConnections(client)
+  const pools = [['ssh', ssh], ['winrm', winrm], ['serial', serial]]
+  for (const [kind, list] of pools) {
+    const hit = list.find((c) => c.id === nameOrId || c.name === nameOrId)
+    if (hit) return { kind, entry: hit }
+  }
+  return null
+}
+
+/** Resolve a tab id-or-name to a real tab id via terminal:list. */
+async function resolveTabId(client, tabIdOrName) {
+  const result = await client.call('terminal:list', {})
+  const terminals = result?.terminals || []
+  const hit = terminals.find((t) => t.id === tabIdOrName || t.title === tabIdOrName)
+  return hit?.id || null
+}
+
+/**
+ * Run a command in a tab via write + buffer-delta polling; returns output.
+ * Validates the tab exists first — the gateway silently returns empty output
+ * for unknown terminal ids, which would otherwise look like success.
+ */
+async function runInTab(client, tabIdOrName, commandText) {
+  const tabId = await resolveTabId(client, tabIdOrName)
+  if (!tabId) {
+    const result = await client.call('terminal:list', {})
+    const known = (result?.terminals || []).map((t) => `${t.id} (${t.title})`).join(', ')
+    throw new Error(`No terminal tab "${tabIdOrName}". Open tabs: ${known || '(none)'}`)
+  }
+  const before = await client.call('terminal:getBufferDelta', { terminalId: tabId, fromOffset: 0 })
+  const startOffset = Number(before?.offset ?? 0)
+  await client.call('terminal:write', { terminalId: tabId, data: `${commandText}\n` })
+  let output = ''
+  let lastOffset = startOffset
+  let stable = 0
+  const deadline = Date.now() + 30_000
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 400))
+    const delta = await client.call('terminal:getBufferDelta', { terminalId: tabId, fromOffset: lastOffset })
+    const data = typeof delta?.data === 'string' ? delta.data : ''
+    const offset = Number(delta?.offset ?? lastOffset)
+    if (data) output += data
+    if (offset === lastOffset && !data) {
+      stable += 1
+      if (stable >= 3) break
+    } else {
+      stable = 0
+    }
+    lastOffset = offset
+  }
+  return stripAnsi(output).trimEnd()
+}
+
 // ── commands ────────────────────────────────────────────────────────────────
 
 async function main() {
   const argv = process.argv.slice(2)
   const { positional, flags } = parseArgs(argv)
   const url = (typeof flags.url === 'string' && flags.url) || DEFAULT_URL
+  const token = (typeof flags.token === 'string' && flags.token) || loadToken()
   const command = positional[0]
 
   if (!command || command === 'help' || flags.help) {
@@ -187,15 +316,16 @@ async function main() {
     process.exit(0)
   }
 
+  const client = makeClient(url, token)
+
   try {
     switch (command) {
       case 'ping': {
-        const result = await call(url, 'gateway:ping')
-        printJson(result)
+        printJson(await client.call('gateway:ping'))
         break
       }
       case 'version': {
-        const result = await call(url, 'gateway:describe')
+        const result = await client.call('gateway:describe')
         printJson({ version: result.version, methodCount: result.count, categories: result.categories })
         break
       }
@@ -203,7 +333,7 @@ async function main() {
         const params = {}
         if (typeof flags.category === 'string') params.category = flags.category
         if (typeof flags.prefix === 'string') params.prefix = flags.prefix
-        const result = await call(url, 'gateway:describe', params)
+        const result = await client.call('gateway:describe', params)
         printJson(result.methods)
         break
       }
@@ -214,57 +344,58 @@ async function main() {
         if (positional[2]) {
           try { params = JSON.parse(positional[2]) } catch { fail('params must be valid JSON') }
         }
-        const result = await call(url, method, params)
-        printJson(result)
+        printJson(await client.call(method, params))
         break
       }
       case 'terminals': {
-        const result = await call(url, 'terminal:list')
-        printJson(result)
+        printJson(await client.call('terminal:list'))
+        break
+      }
+      case 'connections': {
+        const { ssh, winrm, serial } = await fetchConnections(client)
+        const out = { connections: [] }
+        for (const kind of ['ssh', 'winrm', 'serial']) {
+          const list = kind === 'ssh' ? ssh : kind === 'winrm' ? winrm : serial
+          for (const c of list) {
+            out.connections.push({
+              kind,
+              name: c.name,
+              id: c.id,
+              host: c.host || c.path || '',
+              port: c.port ?? c.baudRate ?? '',
+              username: c.username || '',
+            })
+          }
+        }
+        printJson(out)
         break
       }
       case 'open': {
         const name = positional[1]
         if (!name) fail('open needs a saved connection name: rterm open <name>')
-        const result = await call(url, 'terminal:createTab', { config: { savedConnectionName: name } })
-        printJson(result)
+        const found = await resolveConnection(client, name)
+        if (!found) {
+          const { ssh, winrm, serial } = await fetchConnections(client)
+          const names = [...ssh, ...winrm, ...serial].map((c) => c.name).filter(Boolean)
+          fail(`No saved connection named "${name}". Available: ${names.join(', ') || '(none)'}`)
+        }
+        const config = connectionToConfig(found.entry, found.kind)
+        const result = await client.call('terminal:createTab', { config })
+        printJson({ opened: name, kind: found.kind, ...result })
         break
       }
       case 'close': {
         const tab = positional[1]
         if (!tab) fail('close needs a tab id or name: rterm close <tabIdOrName>')
-        const result = await call(url, 'terminal:kill', { terminalId: tab })
-        printJson(result)
+        const tabId = (await resolveTabId(client, tab)) || tab
+        printJson(await client.call('terminal:kill', { terminalId: tabId }))
         break
       }
       case 'run': {
         const tab = positional[1]
         const commandText = positional.slice(2).join(' ')
         if (!tab || !commandText) fail('run needs: rterm run <tabIdOrName> <command>')
-        // The gateway's terminal surface is write + buffer-delta: send the
-        // command with a newline, then poll the buffer until it settles.
-        const before = await call(url, 'terminal:getBufferDelta', { terminalId: tab, fromOffset: 0 })
-        const startOffset = Number(before?.offset ?? 0)
-        await call(url, 'terminal:write', { terminalId: tab, data: `${commandText}\n` })
-        let output = ''
-        let lastOffset = startOffset
-        let stable = 0
-        const deadline = Date.now() + 30_000
-        while (Date.now() < deadline) {
-          await new Promise((resolve) => setTimeout(resolve, 400))
-          const delta = await call(url, 'terminal:getBufferDelta', { terminalId: tab, fromOffset: lastOffset })
-          const data = typeof delta?.data === 'string' ? delta.data : ''
-          const offset = Number(delta?.offset ?? lastOffset)
-          if (data) output += data
-          if (offset === lastOffset && !data) {
-            stable += 1
-            if (stable >= 3) break
-          } else {
-            stable = 0
-          }
-          lastOffset = offset
-        }
-        console.log(output.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '').trimEnd())
+        console.log(await runInTab(client, tab, commandText))
         break
       }
       case 'fleet': {
@@ -274,56 +405,32 @@ async function main() {
         for (const tab of tabs) {
           console.log(`── ${tab} ──`)
           try {
-            const before = await call(url, 'terminal:getBufferDelta', { terminalId: tab, fromOffset: 0 })
-            const startOffset = Number(before?.offset ?? 0)
-            await call(url, 'terminal:write', { terminalId: tab, data: `${commandText}\n` })
-            let output = ''
-            let lastOffset = startOffset
-            let stable = 0
-            const deadline = Date.now() + 30_000
-            while (Date.now() < deadline) {
-              await new Promise((resolve) => setTimeout(resolve, 400))
-              const delta = await call(url, 'terminal:getBufferDelta', { terminalId: tab, fromOffset: lastOffset })
-              const data = typeof delta?.data === 'string' ? delta.data : ''
-              const offset = Number(delta?.offset ?? lastOffset)
-              if (data) output += data
-              if (offset === lastOffset && !data) {
-                stable += 1
-                if (stable >= 3) break
-              } else {
-                stable = 0
-              }
-              lastOffset = offset
-            }
-            console.log(output.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '').trimEnd())
+            console.log(await runInTab(client, tab, commandText))
           } catch (error) {
-            console.log(`Error: ${error instanceof Error ? error.message : String(error)}`)
+            console.log(`Error: ${errorMessage(error)}`)
             process.exitCode = 2
           }
         }
         break
       }
       case 'sessions': {
-        const result = await call(url, 'session:list')
-        printJson(result)
+        printJson(await client.call('session:list'))
         break
       }
       case 'chat': {
         const sessionId = positional[1]
         const message = positional.slice(2).join(' ')
         if (!sessionId || !message) fail('chat needs: rterm chat <sessionId> <message>')
-        const result = await call(url, 'agent:startTask', { sessionId, userInput: message })
-        printJson(result)
+        printJson(await client.call('agent:startTask', { sessionId, userInput: message }))
         break
       }
       case 'dashboard': {
-        const result = await call(url, 'observability:liveDashboardState')
-        printJson(result)
+        printJson(await client.call('observability:liveDashboardState'))
         break
       }
       case 'metrics': {
         const format = flags.format === 'prometheus' ? 'prometheus' : 'summary'
-        const result = await call(url, 'observability:metricsPrometheus', { format })
+        const result = await client.call('observability:metricsPrometheus', { format })
         console.log(typeof result === 'string' ? result : JSON.stringify(result, null, 2))
         break
       }
@@ -331,7 +438,7 @@ async function main() {
         fail(`Unknown command: ${command}. Run "rterm help".`)
     }
   } catch (error) {
-    fail(error instanceof Error ? error.message : String(error))
+    fail(error)
   }
 }