@dr-co/dsh-node-client 0.0.0-stage → 0.0.60

package/lib/plugins/session.mjs

@@ -0,0 +1,192 @@
+/**
+ * Встроенный плагин `session`: переключение рабочего каталога сессии.
+ *
+ * Это не внешний инструмент, а реконфиг сессии: модель говорит «дальше работаем
+ * в каталоге foobar», и все последующие команды этой сессии стартуют там. Нужно
+ * ровно для удобства — чтобы модель не повторяла `cd` в каждой команде.
+ *
+ * Каталог проверяется по списку `roots` из настроек узла: вне их переключение
+ * запрещено, иначе песочница потеряла бы смысл.
+ *
+ * @module dsh-node-client/plugins/session
+ */
+import { CLIENT_VERSION } from '../api.mjs'
+import { preciseNow } from '../shell.mjs'
+import { t } from '../i18n.mjs'
+
+export function api () {
+  return {
+    name: 'session',
+    // контракт изменился (chdir стал строгим, добавился mkdir) — версия обязана
+    // вырасти, иначе узлы с разными схемами слипнутся в одну запись
+    // контракт снова вырос: добавлен метод ping
+    version: '4',
+    description: t('session.api.description'),
+    methods: [
+      {
+        method: 'chdir',
+        description: t('session.chdir.description'),
+        args: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: t('session.chdir.arg.path') },
+          },
+          required: ['path'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'mkdir',
+        description: t('session.mkdir.description'),
+        args: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: t('session.mkdir.arg.path') },
+            mode: { type: 'string', description: t('session.mkdir.arg.mode') },
+          },
+          required: ['path'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'ping',
+        description: t('session.ping.description'),
+        args: { type: 'object', properties: {}, additionalProperties: false },
+      },
+      {
+        method: 'approve',
+        description: t('session.approve.description'),
+        args: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: t('session.approve.arg.id') },
+            text: { type: 'string', description: t('session.approve.arg.text') },
+            mode: { type: 'string', description: t('session.approve.arg.mode') },
+          },
+          required: ['id', 'text'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'cwd',
+        description: t('session.cwd.description'),
+        args: {
+          type: 'object',
+          properties: {
+            session: { type: 'string', description: t('session.arg.session') },
+          },
+          additionalProperties: false,
+        },
+      },
+    ],
+  }
+}
+
+/**
+ * Выполнить команду плагина.
+ * @param {{method: string, args: object}} command
+ * @param {{session: string, sessions?: object, roots?: string[], workdir?: string}} ctx
+ */
+export async function handle (command, ctx = {}) {
+  // Проверка связи не зависит ни от сессии, ни от каталогов: отвечаем раньше
+  // любых проверок, иначе `ping` на узле без сессий звучал бы как поломка.
+  if (command.method === 'ping') {
+    // Возвращаем отметку сервера обратно и добавляем свою: по этой паре
+    // сервер считает и время отклика, и разницу часов между машинами.
+    return {
+      ok: true,
+      results: [{
+        type: 'text',
+        text: JSON.stringify({
+          pong: preciseNow(),
+          // Поле объявлено, но не заполняется: узел не знает, сколько занял
+          // раундтрип по часам сервера. Сервер подставит значение сам.
+          rttMs: null,
+          sentAt: command.issuedAt ?? null,
+          upSeconds: Math.round(process.uptime()),
+          platform: process.platform,
+          version: CLIENT_VERSION,
+        }),
+      }],
+    }
+  }
+
+  const session = command.args?.session ?? ctx.session
+  const sessions = ctx.sessions
+  if (!sessions) {
+    return { ok: false, code: 'session_unavailable', message: t('session.noStore'), results: null }
+  }
+  if (!session) {
+    return { ok: false, code: 'bad_session', message: t('session.noSession'), results: null }
+  }
+
+  if (command.method === 'cwd') {
+    try {
+      const dir = sessions.cwd(session, { workdir: ctx.workdir, roots: ctx.roots })
+      return { ok: true, code: 'cwd', message: dir, results: [{ type: 'text', text: dir }] }
+    } catch (error) {
+      return { ok: false, code: error.code ?? 'workdir_invalid', message: error.message, results: null }
+    }
+  }
+
+  // Апрув — внутренняя команда: она не ходит через `bash`, поэтому песочница её
+  // не касается и отказать ей некому. Спрашиваем человека инструментом из
+  // настроек узла; нет инструмента — честная ошибка, а не тишина.
+  if (command.method === 'approve') {
+    const tool = ctx.approver?.command
+    if (!tool) {
+      return { ok: false, code: 'no_local_approver', message: t('session.approve.noTool'), results: null }
+    }
+    const prompt = String(command.args.text ?? '')
+    // Идентификаторы для инструмента вопроса: по ним диалог может запомнить
+    // «отвечать да до конца вопроса» и «до конца сессии».
+    const payload = JSON.stringify({
+      id: command.args.id,
+      mode: command.args.mode ?? null,
+      text: prompt,
+      session: command.session ?? null,
+      question: command.question ?? null,
+    })
+    const started = Date.now()
+    try {
+      const verdict = await ctx.approver.run({ tool, prompt, payload, signal: ctx.signal, timeout: command.timeout })
+      return {
+        ok: true,
+        code: verdict ? 'approved' : 'cancelled',
+        message: verdict ? 'ok' : 'cancel',
+        results: [{ type: 'text', text: JSON.stringify({ approved: Boolean(verdict), seconds: Math.round((Date.now() - started) / 1000) }) }],
+      }
+    } catch (error) {
+      return { ok: false, code: error.code ?? 'approve_failed', message: error.message, results: null }
+    }
+  }
+
+  if (command.method === 'mkdir') {
+    try {
+      const mode = typeof command.args.mode === 'string' ? Number.parseInt(command.args.mode, 8) : undefined
+      const result = sessions.mkdir(session, command.args.path, {
+        roots: ctx.roots,
+        mode: Number.isFinite(mode) ? mode : undefined,
+      })
+      return {
+        ok: true,
+        code: 'mkdir',
+        message: result.dir,
+        results: [{ type: 'text', text: `${result.dir}${result.created ? t('session.created') : t('session.exists')}` }],
+      }
+    } catch (error) {
+      return { ok: false, code: error.code ?? 'workdir_denied', message: error.message, results: null }
+    }
+  }
+
+  if (command.method !== 'chdir') {
+    return { ok: false, code: 'unknown_method', message: `session: unknown method ${command.method}`, results: null }
+  }
+
+  try {
+    const result = sessions.chdir(session, command.args.path, { roots: ctx.roots })
+    return { ok: true, code: 'chdir', message: result.dir, results: [{ type: 'text', text: result.dir }] }
+  } catch (error) {
+    return { ok: false, code: error.code ?? 'workdir_denied', message: error.message, results: null }
+  }
+}

package/lib/plugins/shell.mjs

@@ -0,0 +1,71 @@
+/**
+ * Плагин `shell`: выполнить команду на узле и вернуть результат.
+ *
+ * Раньше API назывался `bash`, что было правдой только на POSIX: на Windows та
+ * же команда уходит в PowerShell. Имя `shell` честнее, а старое имя осталось
+ * отдельным плагином-алиасом, чтобы не ломать уже настроенные серверы.
+ *
+ * @module dsh-node-client/plugins/shell
+ */
+import { runBash } from '../bash.mjs'
+import { t } from '../i18n.mjs'
+
+/** Общее описание метода: один и тот же exec для shell и для старого bash. */
+export function execMethod () {
+  return {
+    method: 'exec',
+    description: t('bash.exec.description'),
+    args: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: t('bash.arg.command') },
+        cwd: { type: 'string', description: t('bash.arg.cwd') },
+        timeout: { type: 'number', description: t('bash.arg.timeout') },
+        stdin: { type: 'string', description: t('bash.arg.stdin') },
+      },
+      required: ['command'],
+      additionalProperties: false,
+    },
+  }
+}
+
+export function api () {
+  return {
+    name: 'shell',
+    version: '1',
+    description: t('bash.api.description'),
+    methods: [execMethod()],
+  }
+}
+
+/**
+ * Исполнить команду.
+ * @param {{method: string, args: object, timeout?: number}} command
+ * @param {{shell?: string, signal?: AbortSignal}} ctx
+ */
+export async function handle (command, ctx = {}) {
+  if (command.method !== 'exec') {
+    return { ok: false, code: 'unknown_method', message: `shell: unknown method ${command.method}` }
+  }
+  const args = command.args ?? {}
+  // Приоритет: явный cwd в аргументах → каталог сессии → ничего (наследуем).
+  let cwd = args.cwd
+  if (!cwd && ctx.sessions && ctx.session) {
+    try {
+      cwd = ctx.sessions.cwd(ctx.session, { workdir: ctx.workdir, roots: ctx.roots })
+    } catch (error) {
+      // каталог сессии не сделали — лучше сказать прямо, чем исполнить команду
+      // в чужом каталоге и сделать вид, что так и надо
+      return { ok: false, code: error.code ?? 'bad_session', message: error.message }
+    }
+  }
+  return runBash({
+    command: args.command,
+    cwd,
+    timeout: command.timeout ?? args.timeout,
+    stdin: args.stdin,
+    sandbox: ctx.sandbox ?? null,
+    shell: ctx.shell,
+    signal: ctx.signal,
+  })
+}

package/lib/presence.mjs

@@ -0,0 +1,171 @@
+/**
+ * Присутствие клиента: WebSocket с `hello`, `alive` и кадром `state`.
+ *
+ * Токен едет подпротоколом — заголовком `Sec-WebSocket-Protocol`, а не в URL.
+ * Клиент не обязан держать соединение: без него он работает опросом, просто
+ * узнаёт о работе с задержкой до периода опроса.
+ *
+ * @module dsh-node-client/presence
+ */
+import { PROTO } from './api.mjs'
+import { pingDelay } from './ping-policy.mjs'
+import { t } from './i18n.mjs'
+
+/**
+ * Открыть присутствие.
+ * @param {object} options
+ * @param {string} options.base адрес сервера, например `https://dsh.example/dsh-nodes`
+ * @param {string} options.token токен узла
+ * @param {string|null} options.epoch поколение, которое клиент помнит
+ * @param {number|null} options.known курсор узла
+ * @param {(event: object) => void} options.onEvent `state` | `hello-ok` | `closed`
+ * @param {number} [options.aliveMs] период `alive`
+ * @param {(level: string, message: string) => void} [options.log]
+ * @returns {{sendAlive: (known: number|null) => void, close: () => void, epoch: () => number|null}}
+ */
+export function openPresence ({ base, token, epoch = null, known = null, getKnown = null, onEvent, workdir = null,
+  access = null, allowEscalation = true, uptimeSeconds = null, approver = null, aliveMs = 20_000,
+  pingInterval = 0, maxPingIntervalFactor = 0, startMode = null, log = () => {} }) {
+  const wsUrl = base.replace(/^http/, 'ws') + '/v1/ws'
+  let serverEpoch = null
+  let closed = false
+  let socket
+  let aliveTimer
+  // Расписание прикладного пинга: см. lib/ping-policy.mjs. Здесь только
+  // исполнение — арифметика живёт в чистой функции и проверяется тестом.
+  let pingTimer = null
+  let pongWatchdog = null
+  let lastSeenAt = Date.now()
+  let ticksWithoutCommands = 0
+  let pingSeq = 0
+  let awaitingPong = null
+  let connected = false
+  /** Что клиент знает о последнем номере команды прямо сейчас. */
+  const currentKnown = () => (typeof getKnown === 'function' ? getKnown() : known) ?? null
+
+  const send = (payload) => {
+    if (closed || socket?.readyState !== 1) return
+    try {
+      socket.send(JSON.stringify(payload))
+    } catch (error) {
+      log('warn', t('presence.sendFailed', { message: error.message }))
+    }
+  }
+
+  try {
+    socket = new WebSocket(wsUrl, [token])
+  } catch (error) {
+    log('warn', t('presence.openFailed', { message: error.message }))
+    return { sendAlive: () => {}, close: () => {}, epoch: () => null }
+  }
+
+  /**
+   * Поставить пинг на паузу по правилам (арифметика — в ping-policy.mjs).
+   *
+   * Пауза отсчитывается от последнего успешного общения: если сервер только что
+   * ответил, пинг не нужен — таймер перезапустится.
+   */
+  function schedulePing () {
+    if (pingTimer) clearTimeout(pingTimer)
+    const delay = pingDelay({ pingInterval, factor: maxPingIntervalFactor, ticks: ticksWithoutCommands })
+    if (!delay) return
+    const elapsed = Date.now() - lastSeenAt
+    pingTimer = setTimeout(() => {
+      if (Date.now() - lastSeenAt < delay) return schedulePing()
+      const id = ++pingSeq
+      awaitingPong = id
+      send({ t: 'ping', id })
+      pongWatchdog = setTimeout(() => {
+        log('warn', t('presence.pongTimeout', { seconds: Math.round(delay / 1000) }))
+        try {
+          socket.close(4002, 'нет понга')
+        } catch {}
+      }, delay)
+      if (typeof pongWatchdog.unref === 'function') pongWatchdog.unref()
+    }, Math.max(0, delay - elapsed))
+    if (typeof pingTimer.unref === 'function') pingTimer.unref()
+  }
+
+  /** Любое успешное общение с сервером сдвигает отсчёт пинга. */
+  function noteSeen () {
+    lastSeenAt = Date.now()
+    if (pongWatchdog) {
+      clearTimeout(pongWatchdog)
+      pongWatchdog = null
+    }
+    schedulePing()
+  }
+
+  /** Сервер прислал команды: растягивать паузу больше не за что. */
+  function noteCommands () {
+    ticksWithoutCommands = 0
+    noteSeen()
+  }
+
+  socket.addEventListener('open', () => {
+    connected = true
+    // workdir едет в hello: сервер покажет его в админке и будет знать,
+    // где у узла корень рабочих каталогов сессий
+    send({ t: 'hello', epoch, known, proto: PROTO, workdir: workdir ?? null, access: access ?? null, allowEscalation: allowEscalation ?? true, uptimeSeconds: uptimeSeconds ?? null, approver: approver ?? null, base: startMode ?? null })
+    // номер берём в момент отправки: иначе клиент вечно рапортует то, что знал
+    // при подключении, и сервер каждый раз считает его отставшим
+    aliveTimer = setInterval(() => send({ t: 'check_state', known: currentKnown() }), aliveMs)
+    if (typeof aliveTimer.unref === 'function') aliveTimer.unref()
+    schedulePing()
+  })
+
+  socket.addEventListener('message', (event) => {
+    let frame
+    try {
+      frame = JSON.parse(String(event.data))
+    } catch {
+      return log('warn', t('presence.badFrame'))
+    }
+    if (frame.t === 'hello-ok') {
+      serverEpoch = frame.epoch ?? null
+      // сразу заявляем ожидание: иначе сервер, у которого уже есть работа, не
+      // имеет права присылать кадр (он шлёт только ждущим)
+      send({ t: 'check_state', known: currentKnown() })
+      onEvent?.({ type: 'hello-ok', ...frame })
+      return
+    }
+    if (frame.t === 'pong') {
+      if (awaitingPong !== null && frame.id === awaitingPong) awaitingPong = null
+      ticksWithoutCommands += 1
+      noteSeen()
+      return
+    }
+    if (frame.t === 'state') {
+      if (frame.epoch != null) serverEpoch = frame.epoch
+      noteSeen()
+      onEvent?.({ type: 'state', ...frame })
+    }
+  })
+
+  socket.addEventListener('close', (event) => {
+    closed = true
+    clearInterval(aliveTimer)
+    onEvent?.({ type: 'closed', code: event.code, reason: event.reason })
+  })
+
+  socket.addEventListener('error', () => {
+    // close всё равно придёт; здесь только чтобы не падало
+  })
+
+  return {
+    sendAlive: (value) => send({ t: 'check_state', known: value ?? currentKnown() }),
+    online: () => connected,
+    // демон сообщает presence о жизни: после каждого удачного HTTP-ответа и
+    // после каждой пачки команд
+    noteSeen,
+    noteCommands,
+    close: () => {
+      closed = true
+      clearInterval(aliveTimer)
+      try {
+        socket.close(1000, 'bye')
+      } catch {}
+    },
+    epoch: () => serverEpoch,
+  }
+}