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

package/lib/plugins/files.mjs

@@ -0,0 +1,327 @@
+/**
+ * Плагин `files`: чтение и запись файлов на узле без запуска оболочки.
+ *
+ * Смысл именно в том, что это не `shell`: путь проверяется по разрешённым
+ * каталогам до любого обращения к диску, операция атомарна, а запись и правка
+ * требуют версии файла — если файл изменился между чтением и записью, правка
+ * не пройдёт молча. Так же устроен `dsh-fs` в DSH: сервис называет, что можно
+ * сделать с файлом, и никогда — как именно он это делает.
+ *
+ * @module dsh-node-client/plugins/files
+ */
+import { createHash } from 'node:crypto'
+import { chmodSync, closeSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+
+import { assertInside, canonicalPath } from '../sessions.mjs'
+import { t } from '../i18n.mjs'
+
+/** Сколько байт отдаём за одно чтение, если не просили больше. */
+const READ_LIMIT = 256 * 1024
+
+export function api () {
+  return {
+    name: 'files',
+    // контракт вырос: куски для копирования больших файлов
+    version: '2',
+    description: t('files.api.description'),
+    methods: [
+      {
+        method: 'read',
+        description: t('files.read.description'),
+        args: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            offset: { type: 'number', description: t('files.arg.offset') },
+            limit: { type: 'number', description: t('files.arg.limit') },
+          },
+          required: ['path'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'write',
+        description: t('files.write.description'),
+        args: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            content: { type: 'string' },
+            ifVersion: { type: 'string', description: t('files.arg.version') },
+            createDirs: { type: 'boolean', description: t('files.arg.dirs') },
+          },
+          required: ['path', 'content'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'edit',
+        description: t('files.edit.description'),
+        args: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            old: { type: 'string' },
+            new: { type: 'string' },
+            replaceAll: { type: 'boolean' },
+            ifVersion: { type: 'string', description: t('files.arg.version') },
+          },
+          required: ['path', 'old', 'new'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'readChunk',
+        description: t('files.readChunk.description'),
+        args: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            offset: { type: 'number' },
+            size: { type: 'number' },
+          },
+          required: ['path'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'writeChunk',
+        description: t('files.writeChunk.description'),
+        args: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            offset: { type: 'number' },
+            data: { type: 'string', description: t('files.arg.base64') },
+            final: { type: 'boolean', description: t('files.arg.final') },
+          },
+          required: ['path', 'data'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'sha256',
+        description: t('files.sha256.description'),
+        args: {
+          type: 'object',
+          properties: { path: { type: 'string' } },
+          required: ['path'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'list',
+        description: t('files.list.description'),
+        args: {
+          type: 'object',
+          properties: { path: { type: 'string' } },
+          required: ['path'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'stat',
+        description: t('files.stat.description'),
+        args: {
+          type: 'object',
+          properties: { path: { type: 'string' } },
+          required: ['path'],
+          additionalProperties: false,
+        },
+      },
+    ],
+  }
+}
+
+/** Версия файла: размер и время правки. Дешёвая, но достаточная защита. */
+function versionOf (stat) {
+  return `${stat.size}-${Math.round(stat.mtimeMs)}`
+}
+
+function fail (code, message) {
+  return { ok: false, code, message }
+}
+
+function text (payload) {
+  return { ok: true, results: [{ type: 'text', text: JSON.stringify(payload) }] }
+}
+
+/** Разрешить путь: только внутри roots, иначе отказ до чтения диска. */
+function resolve (path, ctx) {
+  // только явно разрешённые каталоги: если ничего не настроено — отказ, потому
+  // что «/» в этом месте означал бы «читай что хочешь»
+  const roots = ctx.fileRoots ?? ctx.roots ?? []
+  if (!roots.length) {
+    throw Object.assign(new Error('каталоги не настроены: задай roots или workdir в конфиге узла'), { code: 'path_denied' })
+  }
+  return assertInside(path, roots)
+}
+
+export async function handle (command, ctx = {}) {
+  const args = command.args ?? {}
+  let target
+  try {
+    target = resolve(args.path, ctx)
+  } catch (error) {
+    return fail('path_denied', error.message)
+  }
+
+  try {
+    switch (command.method) {
+      case 'read': {
+        const stat = statSync(target)
+        if (stat.isDirectory()) return fail('bad_args', `это каталог: ${target} (используй list)`)
+        const offset = Math.max(0, Number(args.offset) || 0)
+        const limit = Math.max(1, Number(args.limit) || READ_LIMIT)
+        const buffer = readFileSync(target)
+        const slice = buffer.subarray(offset, offset + limit)
+        return text({
+          path: target,
+          version: versionOf(stat),
+          size: buffer.length,
+          offset,
+          text: slice.toString('utf8'),
+          truncated: offset + slice.length < buffer.length,
+        })
+      }
+      case 'write': {
+        // версия проверяется до записи: иначе «правка» молча затрёт чужую
+        if (args.ifVersion) {
+          let current = null
+          try {
+            current = versionOf(statSync(target))
+          } catch {}
+          if (current !== args.ifVersion) {
+            return fail('stale', `файл изменился: ожидали версию ${args.ifVersion}, на диске ${current ?? 'нет файла'}`)
+          }
+        }
+        if (args.createDirs !== false) mkdirSync(dirname(target), { recursive: true })
+        // режим берём у существующего файла: перезапись конфига не должна
+        // молча делать его 0600 вместо 0644
+        let mode = 0o600
+        try {
+          mode = statSync(target).mode
+        } catch {}
+        // атомарно: соседний временный файл и rename, чтобы не оставить половину
+        const temp = `${target}.dshnc-${process.pid}-${Date.now()}`
+        try {
+          writeFileSync(temp, args.content, { mode })
+          renameSync(temp, target)
+        } catch (error) {
+          try {
+            unlinkSync(temp)
+          } catch {}
+          throw error
+        }
+        return text({ path: target, version: versionOf(statSync(target)), bytes: Buffer.byteLength(args.content) })
+      }
+      case 'edit': {
+        const stat = statSync(target)
+        const version = versionOf(stat)
+        if (args.ifVersion && args.ifVersion !== version) {
+          return fail('stale', `файл изменился: ожидали ${args.ifVersion}, на диске ${version}`)
+        }
+        const original = readFileSync(target, 'utf8')
+        const occurrences = original.split(args.old).length - 1
+        if (!occurrences) return fail('not_found', `строка не найдена в ${target}`)
+        if (occurrences > 1 && args.replaceAll !== true) {
+          return fail('ambiguous_edit', `строка встречается ${occurrences} раз; уточни или поставь replaceAll`)
+        }
+        const updated = args.replaceAll === true
+          ? original.split(args.old).join(args.new)
+          : original.replace(args.old, args.new)
+        const temp = `${target}.dshnc-${process.pid}-${Date.now()}`
+        writeFileSync(temp, updated, { mode: stat.mode })
+        renameSync(temp, target)
+        return text({ path: target, version: versionOf(statSync(target)), replaced: args.replaceAll === true ? occurrences : 1 })
+      }
+      case 'readChunk': {
+        // двоичные куски: base64, потому что текст испортит байты вне UTF-8
+        const buffer = readFileSync(target)
+        const offset = Math.max(0, Number(args.offset) || 0)
+        const size = Math.max(1, Number(args.size) || 1024 * 1024)
+        const slice = buffer.subarray(offset, offset + size)
+        return text({
+          path: target,
+          offset,
+          size: slice.length,
+          total: buffer.length,
+          eof: offset + slice.length >= buffer.length,
+          data: slice.toString('base64'),
+        })
+      }
+      case 'writeChunk': {
+        // пишем в `${path}.inprogress` и переименовываем только последним куском:
+        // файл либо появляется целиком, либо не появляется вовсе
+        const part = `${target}.inprogress`
+        const offset = Math.max(0, Number(args.offset) || 0)
+        const chunk = Buffer.from(String(args.data ?? ''), 'base64')
+        let fd = null
+        try {
+          fd = openSync(part, offset === 0 ? 'w' : 'r+')
+        } catch {
+          if (args.createDirs !== false) mkdirSync(dirname(part), { recursive: true })
+          fd = openSync(part, 'w')
+        }
+        try {
+          writeSync(fd, chunk, 0, chunk.length, offset)
+        } finally {
+          closeSync(fd)
+        }
+        if (args.final === true) {
+          let mode
+          try {
+            mode = statSync(target).mode
+          } catch {}
+          if (mode) chmodSync(part, mode & 0o777)
+          renameSync(part, target)
+          return text({ path: target, bytes: statSync(target).size, version: versionOf(statSync(target)), complete: true })
+        }
+        return text({ path: target, part, written: chunk.length, offset })
+      }
+      case 'sha256': {
+        const hash = createHash('sha256').update(readFileSync(target)).digest('hex')
+        return text({ path: target, sha256: hash, size: statSync(target).size })
+      }
+      case 'list': {
+        const stat = statSync(target)
+        if (!stat.isDirectory()) return fail('bad_args', `это файл, а не каталог: ${target}`)
+        const entries = readdirSync(target, { withFileTypes: true }).map((entry) => {
+          const full = join(target, entry.name)
+          let size = null
+          let mtime = null
+          try {
+            const info = statSync(full)
+            size = info.size
+            mtime = Math.round(info.mtimeMs)
+          } catch {}
+          return { name: entry.name, type: entry.isDirectory() ? 'dir' : 'file', size, mtime }
+        })
+        return text({ path: target, entries })
+      }
+      case 'stat': {
+        try {
+          const info = statSync(target)
+          return text({
+            path: target,
+            exists: true,
+            type: info.isDirectory() ? 'dir' : 'file',
+            size: info.size,
+            mtime: Math.round(info.mtimeMs),
+            version: versionOf(info),
+          })
+        } catch (error) {
+          if (error.code === 'EACCES' || error.code === 'EPERM') return fail('path_denied', `нет доступа к ${target}`)
+          return text({ path: target, exists: false })
+        }
+      }
+      default:
+        return fail('unknown_method', `files: unknown method ${command.method}`)
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') return fail('not_found', `нет файла ${target}`)
+    if (error.code === 'EACCES' || error.code === 'EPERM') return fail('path_denied', `нет доступа к ${target}`)
+    return fail('internal', error.message)
+  }
+}

package/lib/plugins/index.mjs

@@ -0,0 +1,116 @@
+/**
+ * Загрузка плагинов клиента.
+ *
+ * Два источника, одинаковый контракт:
+ *   1. встроенные — `lib/plugins/*.mjs` в составе пакета (`bash` первый);
+ *   2. пользовательские — `~/.dshnc/plugins/<имя>/index.mjs`.
+ *
+ * Пользовательский плагин — это файл, который экспортирует `api` и `handle`
+ * (или `default` с этими полями). Ошибка в одном плагине не должна уносить
+ * остальные: он просто выпадает с предупреждением в лог.
+ *
+ * @module dsh-node-client/plugins
+ */
+import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { t } from '../i18n.mjs'
+import * as filesPlugin from './files.mjs'
+import * as jobPlugin from './job.mjs'
+import * as sessionPlugin from './session.mjs'
+import * as shellPlugin from './shell.mjs'
+
+// `session` — внутренний плагин: он не инструмент, а реконфиг сессии,
+// поэтому едет рядом с bash и всегда первым (bash тоже должен его видеть)
+// `shell` — исполнение команд, `job` — фоновые процессы, `session` — состояние сессии.
+// Старое имя `bash` больше не объявляем: два одинаковых API путали и модель, и
+// админку. Старые клиенты объявляют его сами, сервер к этому готов.
+const BUILTIN = [shellPlugin, jobPlugin, filesPlugin, sessionPlugin]
+
+/** Проверить, что модуль похож на плагин. */
+function asPlugin (module, label) {
+  const candidate = module?.api ? module : module?.default
+  if (candidate && typeof candidate.api === 'function') {
+    const factory = candidate.api
+    return asPlugin({ ...candidate, api: factory() }, label)
+  }
+  if (!candidate?.api?.name) throw new Error(t('plugins.noName', { label }))
+  if (typeof candidate.api.name !== 'string') throw new Error(t('plugins.nameType', { label }))
+  if (!Array.isArray(candidate.api.methods) || !candidate.api.methods.length) {
+    throw new Error(t('plugins.noMethods', { label }))
+  }
+  if (typeof candidate.handle !== 'function') throw new Error(t('plugins.noHandle', { label }))
+  for (const method of candidate.api.methods) {
+    if (typeof method?.method !== 'string') throw new Error(t('plugins.methodNoName', { label }))
+    if (!method.args || typeof method.args !== 'object') throw new Error(t('plugins.methodNoArgs', { label, method: method.method }))
+  }
+  return { api: candidate.api, handle: candidate.handle, builtin: true, label }
+}
+
+/**
+ * Загрузить плагины.
+ * @param {object} options
+ * @param {string} options.dir каталог пользовательских плагинов
+ * @param {(level: string, message: string) => void} [options.log]
+ * @returns {Promise<Array<{api: object, handle: Function}>>}
+ */
+export async function loadPlugins ({ dir, log = () => {} }) {
+  const plugins = []
+  const seen = new Set()
+
+  for (const module of BUILTIN) {
+    const plugin = asPlugin(module, 'builtin')
+    plugin.label = `builtin ${plugin.api.name}`
+    plugins.push(plugin)
+    seen.add(plugin.api.name)
+  }
+
+  mkdirSync(dir, { recursive: true })
+  let entries = []
+  try {
+    entries = readdirSync(dir)
+  } catch (error) {
+    log('warn', t('plugins.directory', { message: error.message }))
+  }
+
+  for (const entry of entries.sort()) {
+    const full = join(dir, entry)
+    const file = statSync(full).isDirectory() ? join(full, 'index.mjs') : full
+    if (!file.endsWith('.mjs') || !existsSync(file)) continue
+    try {
+      const module = await import(pathToFileURL(file).href)
+      const plugin = asPlugin(module, entry)
+      if (seen.has(plugin.api.name)) {
+        log('warn', t('plugins.taken', { entry, name: plugin.api.name }))
+        continue
+      }
+      plugin.builtin = false
+      plugin.label = `plugin ${entry}`
+      plugins.push(plugin)
+      seen.add(plugin.api.name)
+    } catch (error) {
+      log('warn', t('plugins.failed', { entry, message: error.message }))
+    }
+  }
+
+  return plugins
+}
+
+/** Список API для `/announce`. */
+export function apisOf (plugins) {
+  return plugins.map((plugin) => plugin.api)
+}
+
+/**
+ * Найти плагин для команды. Сначала по номеру API, который выдал сервер,
+ * потом — по имени метода (сервер мог перезапуститься и нумерация сменилась).
+ */
+export function resolvePlugin (plugins, command, apiIds = {}) {
+  const byId = Object.entries(apiIds).find(([, id]) => id === command.api)
+  if (byId) {
+    const found = plugins.find((plugin) => plugin.api.name === byId[0])
+    if (found) return found
+  }
+  return plugins.find((plugin) => plugin.api.methods.some((method) => method.method === command.method)) ?? null
+}

package/lib/plugins/job.mjs

@@ -0,0 +1,111 @@
+/**
+ * Плагин `job`: долгоиграющие процессы на узле.
+ *
+ * Отдельный API, а не режим `exec`: у фоновой работы другой контракт — ответ
+ * сразу, чтение вывода по смещению, явное убийство группы.
+ *
+ * @module dsh-node-client/plugins/job
+ */
+import { createJobRegistry } from '../jobs.mjs'
+import { t } from '../i18n.mjs'
+
+/** Реестр один на клиента: `dshnc daemon` живёт долго, процессов много. */
+let registry = null
+function jobs () {
+  registry ??= createJobRegistry()
+  return registry
+}
+
+export function api () {
+  return {
+    name: 'job',
+    version: '1',
+    description: t('job.api.description'),
+    methods: [
+      {
+        method: 'start',
+        description: t('job.start.description'),
+        args: {
+          type: 'object',
+          properties: {
+            command: { type: 'string' },
+            cwd: { type: 'string' },
+            timeout: { type: 'number', description: t('job.arg.timeout') },
+          },
+          required: ['command'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'output',
+        description: t('job.output.description'),
+        args: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            offset: { type: 'number', description: t('job.arg.offset') },
+          },
+          required: ['id'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'kill',
+        description: t('job.kill.description'),
+        args: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            signal: { type: 'string', enum: ['SIGTERM', 'SIGKILL'] },
+          },
+          required: ['id'],
+          additionalProperties: false,
+        },
+      },
+      {
+        method: 'list',
+        description: t('job.list.description'),
+        args: { type: 'object', properties: {}, additionalProperties: false },
+      },
+    ],
+  }
+}
+
+export async function handle (command, ctx = {}) {
+  const args = command.args ?? {}
+  const registry = jobs()
+  switch (command.method) {
+    case 'start': {
+      // каталог: явный → каталог сессии, как у `shell.exec`
+      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 registry.start({
+        command: args.command,
+        cwd,
+        shell: ctx.shell,
+        timeout: args.timeout ?? command.timeout,
+        // та же песочница, что у exec: политика узла распространяется и на фоновые процессы
+        sandbox: ctx.sandbox ?? null,
+      })
+    }
+    case 'output':
+      return registry.output(args.id, args.offset)
+    case 'kill':
+      return registry.kill(args.id, args.signal ?? 'SIGTERM')
+    case 'list':
+      return registry.list()
+    default:
+      return { ok: false, code: 'unknown_method', message: `job: unknown method ${command.method}` }
+  }
+}
+
+/** Убить всё при остановке демона: процессы не должны пережить клиента. */
+export function stopAll () {
+  registry?.stopAll()
+}