dsh-ssh-workbench 0.0.0-stage → 1.6.4

package/lib/core/activity.js

@@ -0,0 +1,83 @@
+/**
+ * Local, bounded activity log for the overview page (not an audit log).
+ *
+ * This is NOT an audit system: entries are best-effort, newest-first, and
+ * capped so the file cannot grow without bound. A failed write never fails the
+ * operation that produced the entry.
+ */
+import { activityPath, readTextFile, writePrivateFile } from './paths.js'
+
+export const MAX_ACTIVITY_ENTRIES = 200
+
+/**
+ * Human-readable activity outcome for one command result.
+ *
+ * The overview must distinguish "the command ran and returned non-zero" from
+ * "the transport failed": `cat missing-file` is `exit 1`, `docker` on a host
+ * without Docker is `exit 127 (COMMAND_NOT_FOUND)`, while a dropped connection
+ * is `failed (CONNECT_TIMEOUT)`. Without this, benign non-zero exits look like
+ * remote failures.
+ */
+export function describeResultOutcome(result) {
+  if (!result || typeof result !== 'object') return 'unknown'
+  if (result.outcome === 'success') return 'success'
+  const code = typeof result.errorCode === 'string' && result.errorCode ? result.errorCode : ''
+  const hasExit = result.exitCode !== null && result.exitCode !== undefined
+  if (hasExit) return code && code !== 'EXEC_FAILED' ? `exit ${result.exitCode} (${code})` : `exit ${result.exitCode}`
+  if (code) return `${result.outcome ?? 'failed'} (${code})`
+  return String(result.outcome ?? 'failed')
+}
+
+export function createActivityStore({ file = activityPath(), maxEntries = MAX_ACTIVITY_ENTRIES } = {}) {
+  if (!Number.isSafeInteger(maxEntries) || maxEntries <= 0) throw new Error('maxEntries must be a positive safe integer')
+
+  function load() {
+    const text = readTextFile(file, '[]')
+    try {
+      const parsed = JSON.parse(text)
+      return Array.isArray(parsed) ? parsed.filter((entry) => entry && typeof entry === 'object') : []
+    } catch {
+      return []
+    }
+  }
+
+  function save(entries) {
+    try {
+      writePrivateFile(file, `${JSON.stringify(entries, null, 2)}\n`)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Prepend one entry. `at` defaults to now; unknown fields are kept so callers
+   * can add outcome/latency without touching the store.
+   * @returns the normalized entry (even when the write failed).
+   */
+  function append(entry) {
+    const normalized = {
+      at: typeof entry?.at === 'string' ? entry.at : new Date().toISOString(),
+      kind: String(entry?.kind ?? 'operation'),
+      ...(Array.isArray(entry?.servers) ? { servers: entry.servers.map(String) } : {}),
+      ...(entry?.server !== undefined ? { server: String(entry.server) } : {}),
+      ...(entry?.summary !== undefined ? { summary: String(entry.summary) } : {}),
+      ...(entry?.outcome !== undefined ? { outcome: String(entry.outcome) } : {}),
+    }
+    const next = [normalized, ...load()].slice(0, maxEntries)
+    save(next)
+    return normalized
+  }
+
+  /** @returns newest-first entries, at most `limit`. */
+  function list(limit = 20) {
+    const bounded = Number.isSafeInteger(limit) && limit > 0 ? Math.min(limit, maxEntries) : 20
+    return load().slice(0, bounded)
+  }
+
+  function clear() {
+    return save([])
+  }
+
+  return { append, list, clear, maxEntries }
+}

package/lib/core/background.js

@@ -0,0 +1,69 @@
+/**
+ * Detached ("background") remote commands.
+ *
+ * A remote process cannot be registered in DSH's local job registry, so a
+ * background start returns the only facts that stay true across transports:
+ * the remote pid and a log file. The model reads output with `tail` /
+ * `Get-Content` and stops the process with `kill` / `Stop-Process`; that keeps
+ * the behaviour identical on POSIX and Windows targets without pretending the
+ * local `job_*` tools manage a remote process.
+ *
+ * The launcher itself must finish quickly and print machine-readable markers,
+ * so the caller can distinguish "started" from "never started".
+ */
+import { quotePosix } from './posix-quote.js'
+
+export const BG_PID_MARKER = '__SDH_BG_PID__'
+export const BG_LOG_MARKER = '__SDH_BG_LOG__'
+export const BG_ERR_MARKER = '__SDH_BG_ERR__'
+
+/** Parse the marker lines out of the launcher's stdout. */
+export function parseBackgroundStart(stdout) {
+  const text = String(stdout ?? '')
+  const pidMatch = /__SDH_BG_PID__(\d+)/.exec(text)
+  const logMatch = /__SDH_BG_LOG__([^\r\n]+)/.exec(text)
+  const errMatch = /__SDH_BG_ERR__([^\r\n]+)/.exec(text)
+  const pid = pidMatch ? Number.parseInt(pidMatch[1], 10) : undefined
+  const log = logMatch ? logMatch[1].trim() : undefined
+  const errLog = errMatch ? errMatch[1].trim() : undefined
+  return {
+    pid: Number.isInteger(pid) && pid > 0 ? pid : undefined,
+    log: log || undefined,
+    errLog: errLog || undefined,
+  }
+}
+
+/**
+ * Build one POSIX launcher for an already workdir-prefixed command.
+ *
+ * `nohup` + redirected stdio is what keeps the child alive after the SSH
+ * channel closes; the whole launcher runs under `sh -c` so a fish/csh login
+ * shell only has to parse the simple outer command.
+ */
+export function buildPosixBackgroundCommand(builtCommand) {
+  const script = [
+    'LOG=$(mktemp /tmp/dsh-ssh-workbench-bg.XXXXXX 2>/dev/null || echo /tmp/dsh-ssh-workbench-bg-$$-$(date +%s).log)',
+    `nohup "\${SHELL:-/bin/sh}" -lc ${quotePosix(builtCommand)} >"$LOG" 2>&1 &`,
+    `echo "${BG_PID_MARKER}$!"`,
+    `echo "${BG_LOG_MARKER}$LOG"`,
+  ].join('\n')
+  return `sh -c ${quotePosix(script)}`
+}
+
+/** One model-facing description of a started background process. */
+export function renderBackgroundStart({ pid, log, errLog, target, command, dialect = 'posix' }) {
+  const windows = dialect === 'windows'
+  const lines = [`background: started${target ? ` on ${target}` : ''}`, `command: ${command}`]
+  if (pid !== undefined) lines.push(`pid: ${pid}`)
+  if (log) lines.push(`log: ${log}`)
+  if (errLog) lines.push(`stderr log: ${errLog}`)
+  const logPath = log ?? '<log path from the launcher output>'
+  lines.push(
+    windows
+      ? `read output: Get-Content -LiteralPath '${logPath.replace(/'/g, "''")}' -Wait`
+      : `read output: tail -f ${quotePosix(logPath)}`,
+  )
+  if (pid !== undefined) lines.push(windows ? `stop: Stop-Process -Id ${pid} -Force` : `stop: kill ${pid}`)
+  lines.push('The process is detached from this tool call: timeoutMs does not apply and it keeps running until it exits or is stopped.')
+  return lines.join('\n')
+}