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

package/README.md

@@ -1,3 +1,277 @@
-# Temporary Holding Version
+# dsh-node-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`dshnc` — the node side of [dsh-nodes](https://github.com/unera/dsh-nodes):
+it connects a machine to a DSH server, fetches commands, runs them inside a
+sandbox and reports back.
+
+Zero runtime dependencies. One foreground process, systemd-friendly, no daemon
+libraries.
+
+## Install
+
+```sh
+npm install -g @dr-co/dsh-node-client
+systemctl --user restart dshnc
+```
+
+## Connect
+
+```sh
+dshnc connect 'https://host/dsh-nodes/pair?v=<code>'   # pairing link
+dshnc daemon                                            # serve every configured server
+```
+
+## Built-in APIs
+
+Everything the client can do lives in a plugin. Two ship in the box.
+
+**`bash`** — run a shell command.
+
+```
+exec(command, cwd?, timeout?) → stdout, stderr, {"code":…,"signal":…,"cwd":…,"sandbox":{…}}
+```
+
+Output above 48 KiB is truncated with a visible marker. A command that outlives
+its timeout is killed. The `sandbox` block in the last result is the client's
+honest report: the mode it actually ran in, whether the kernel denied something
+and under which signature (`read-only file system` and the like).
+
+**`job`** — long-running processes.
+
+```
+start(command, cwd?, timeout?) → {id, status}
+output(id, offset?)            → {status, code, stdout, stderr, offset, sandbox}
+kill(id, signal?)              → SIGTERM to the whole process group
+list()                        → what runs and how it ended
+```
+
+A job runs through the same sandbox as `exec`: the mode that would confine a
+command confines its background process too. Output is kept in a ring (256 KiB)
+and read by absolute offsets; `sandbox` in the answer says whether isolation was
+applied. Jobs die with the daemon: sandboxed ones through `--die-with-parent`,
+the rest through `stopAll()` on SIGTERM.
+
+**`files`** — reading and writing without a shell.
+
+```
+read(path, offset?, limit?)                     → {text, version, size, truncated}
+write(path, content, ifVersion?, createDirs?)   → {version, bytes}
+edit(path, old, new, replaceAll?, ifVersion?)   → {version, replaced}
+list(path)                                      → {entries: [{name, type, size, mtime}]}
+stat(path)                                      → {exists, type, size, version}
+```
+
+Paths are checked against `roots` **before** touching the disk: `/etc/hostname`
+answers `path_denied`, not "read it anyway". Writes are atomic (temp file plus
+`rename`), and `ifVersion` turns a silent overwrite into a `stale` error.
+`edit` refuses ambiguity: a string found twice without `replaceAll` gives
+`ambiguous_edit`.
+
+**`session`** — session state on the node, version 4.
+
+```
+chdir(path)              → move the session workdir inside the allowed roots
+mkdir(path, mode?)       → create a directory for the session
+cwd()                    → where the session currently is
+approve(id, text, mode)  → ask the human on this machine; returns ok/cancel
+ping()                   → {pong, sentAt, rttMs, upSeconds, platform, version}
+```
+
+`ping` is the cheap liveness check: the node answers with its own clock and
+uptime, and the server fills `rttMs` and `clockSkewMs` — the node cannot time a
+round trip because it has never seen the server clock. It answers even on a node
+without a session store, and the server caps it at 15 seconds: a hung node must
+not hold the model for its full timeout.
+
+The tool is started with these variables, so a dialog can show what is being
+asked and remember a standing answer:
+
+| variable | meaning |
+|---|---|
+| `DSHNC_APPROVAL_ID` | id of this question |
+| `DSHNC_APPROVAL_MODE` | mode that is being requested |
+| `DSHNC_SESSION` | model session; "answer yes until the end of this session" |
+| `DSHNC_QUESTION` | root call of the turn; "until the end of this question" |
+| `DSHNC_CALL` | the exact call, for logs |
+
+`approve` is deliberately not a shell command: it runs the tool configured in
+`ask.local.tool` (a `zenity` dialog, a script, anything), never goes through the
+sandbox, and cannot be denied by the kernel. Without a configured tool it fails
+with `no_local_approver` instead of pretending a question was asked.
+
+Bump the API version whenever its contract changes. The version is the
+**contract** version: nodes announcing different versions of the same name stay
+separate, and fusing them would make the server use whichever schema it saw
+first.
+
+## Write your own plugin
+
+Drop a directory into `~/.dshnc/plugins/<name>/index.mjs`; it is loaded at
+startup and its API is announced to the server.
+
+```js
+export const api = {
+  name: 'lamp',                 // what the server will see
+  version: '1',                 // bump with the contract
+  description: 'Desk lamp',
+  methods: [{
+    method: 'set',
+    description: 'Turn on or off',
+    args: {
+      type: 'object',
+      properties: { state: { type: 'string', enum: ['on', 'off'] } },
+      required: ['state'],
+      additionalProperties: false,
+    },
+  }],
+}
+
+export async function handle (command, ctx) {
+  if (command.method !== 'set') {
+    return { ok: false, code: 'unknown_method', message: `no method ${command.method}` }
+  }
+  return { ok: true, results: [{ type: 'text', text: `lamp ${command.args.state}` }] }
+}
+```
+
+`args` is mandatory (at least `{ type: 'object' }`): the server refuses an
+announcement without a schema. `handle` returns `{ok: true, results: [...]}` or
+`{ok: false, code, message}` with a code from the server's vocabulary
+(`bad_args`, `timeout`, `internal`, …). `ctx` carries `shell`, `signal`
+(cancellation of that call), `sandbox`, `sessions` and `approver`.
+
+A plugin that throws is dropped with a warning; the rest keep working. A plugin
+claiming a name that is already taken is skipped.
+
+## Sandbox and policy
+
+The owner of the machine decides what the server may do. Policy lives on the
+node, not on the server:
+
+```json
+{
+  "max": "full",        // absolute ceiling, never exceeded
+  "base": "rw",         // mode a command starts in; approved commands skip it
+  "approver": "local",  // local | server | none
+  "roots": ["/home/unera/work/ai"],
+  "workdir": "/home/unera/work/ai/.dsh",
+  "ask": {
+    "local": { "enabled": true, "tool": { "type": "external", "command": "zenity --text-info --width=600" } }
+  }
+}
+```
+
+`dshnc policy` reads and edits it:
+
+```sh
+dshnc policy https://host/dsh-nodes max=full base=rw approver=local \
+  tool="zenity --text-info --width=600"
+```
+
+The template in `ask.local.tool` either contains `%s` (the question is
+substituted into an argument) or not (the question goes to stdin, as
+`zenity --text-info` expects — then its length is unbounded). Structured data
+travelling with the question arrives in `DSHNC_APPROVAL_ID` and
+`DSHNC_APPROVAL_MODE`. The command is started without a shell, so nothing from
+the question can become shell syntax.
+
+Sandboxing uses `bwrap` when it is available: `ro` is a read-only bind of `/`,
+`rw` adds writable binds for `roots`, `full` runs unconfined. `no_new_privs` is
+set, so `sudo` and setuid do not work inside. Network is unshared in `ro`/`rw`.
+
+## Audit
+
+Commands executed without a sandbox leave a trace:
+
+```sh
+dshnc audit 20
+```
+
+Rows are kept in a ring (2000 rows, 7 days) — a node that lives for months must
+not fill the disk with a log nobody reads.
+
+## Control channel
+
+Polling pulls batches over HTTP; a WebSocket (`/v1/ws`, token in the
+subprotocol, never in the URL) tells the client that work exists, so it does not
+wait for the next poll. Without the socket the client still works, just with
+poll latency.
+
+Batches run in parallel with a cap (`maxConcurrent`, default 5): one model turn
+can produce a dozen calls, and a node must not be flooded. `session.chdir` is
+applied first and in order — it changes the session working directory, so the
+rest of the batch must start in the new one. `session.approve` runs outside the
+pool: a dialog may hang for a day and must not hold a slot.
+
+## MCP (planned)
+
+The client is a natural place to bridge MCP servers: a local MCP server becomes
+one more API on the node, and the model reaches it through `nodes_call` without
+learning new tools. Two transports are wanted:
+
+| transport | how it is configured | note |
+|---|---|---|
+| stdio | `command` + `args`, client spawns the process | works for `npx @modelcontextprotocol/server-*`, no network |
+| `host:port` | URL of an HTTP/SSE endpoint | the server may live elsewhere, the node only proxies |
+
+An MCP server named `files` would be announced as API `mcp-files` with one
+method per MCP tool, the tool's JSON Schema reused as `args`. Nothing in the
+protocol changes: the server already passes arbitrary schemas through.
+
+Not implemented yet. When it is, the section will say so plainly instead of
+describing intentions.
+
+## First-run setup
+
+`dshnc onboard` is a menu-driven wizard: it asks one section at a time and
+explains what each answer means, because the answers are policy — who may do what
+on this machine — not cosmetics.
+
+- current values are shown in brackets and an empty answer keeps them, so the
+  wizard never silently changes a node that already works;
+- `доступ` — name, session directory, allowed directories, ceiling (`ro`/`rw`/
+  `full`), starting mode, who answers questions, and the command used to ask
+  (any tool that exits 0 on "yes", not just `zenity`);
+- `связь` — periodic polling, socket ping interval and how far it may stretch;
+- `автозапуск` — delegates to the systemd unit wizard;
+- before writing, it prints the resulting config and asks for confirmation.
+
+`dshnc config key=value` changes top-level settings, `dshnc policy <url> key=value`
+changes per-server rules; both edit the file in place and keep its comments.
+
+## Install
+
+```
+npm install -g @dr-co/dsh-node-client
+```
+
+The same thing straight from git, without npm:
+
+```
+npm install -g unera/dsh-node-client
+```
+
+Both give you the `dshnc` binary. The git form follows `main`, the npm form gives
+you a tagged release — pick npm for a node that has to keep working.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `dshnc connect <url>` | pairing link — at once, otherwise a request pending approval |
+| `dshnc daemon [url...]` | announce APIs, fetch commands, answer; no arguments — every configured server |
+| `dshnc status` | client id and saved servers |
+| `dshnc policy [url] [key=value…]` | show or change policy for one server |
+| `dshnc audit [n]` | commands executed without the sandbox |
+| `dshnc workdir [path]` | show or set the session working directory |
+
+One client serves several servers: token, cursor and epoch are kept **per URL**.
+
+## Development
+
+```sh
+npm test     # node --test, sequential: integration tests start real servers
+```
+
+The Russian guide is in [`docs/guide.ru.md`](docs/guide.ru.md); storage rules,
+policy and sandbox notes are in [`STORAGE.md`](STORAGE.md).

package/bin/dshnc.mjs

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/**
+ * dshnc — клиент dsh-nodes.
+ *
+ *   dshnc help
+ *   dshnc connect <url>        заявка на сервере и ожидание одобрения
+ *   dshnc daemon [url...]      держать соединения и исполнять команды
+ *   dshnc status               что сохранено в ~/.dshnc
+ *   dshnc version              версия клиента и версия протокола
+ *
+ * Один клиент может работать с несколькими серверами: состояние соединений
+ * (токен, курсор, epoch) хранится per URL.
+ */
+import { join } from 'node:path'
+import { loadConfig, normalizeUrl } from '../lib/config.mjs'
+import { enrollServer, pairServer, runServer } from '../lib/runner.mjs'
+import * as jobPlugin from '../lib/plugins/job.mjs'
+import { loadPlugins } from '../lib/plugins/index.mjs'
+import { detectLang, setLang, t } from '../lib/i18n.mjs'
+import { applyAutostartAnswers, resolveExecStart, runAutostart } from '../lib/autostart.mjs'
+import { formatQuestion } from '../lib/ask.mjs'
+import { home, openStore } from '../lib/store.mjs'
+import { PROTO, VERSION } from '../lib/api.mjs'
+import { createInterface } from 'node:readline/promises'
+import { mkdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const HELP = () => [
+  t('help.title', { home: home() }),
+  '',
+  '  ' + t('help.connect'),
+  '  ' + t('help.connect2'),
+  '  ' + t('help.daemon'),
+  '  ' + t('help.daemon2'),
+  '  ' + t('help.daemon3'),
+  '  ' + t('help.foreground'),
+  '  ' + t('help.onboard'),
+  '  ' + t('help.config'),
+  '  ' + t('help.policy'),
+  '  ' + t('help.audit'),
+  '  ' + t('help.workdir'),
+  '  ' + t('help.autostart'),
+  '  ' + t('help.status'),
+  '  ' + t('help.version'),
+  '  ' + t('help.help'),
+  '',
+  '  ' + t('help.env'),
+  '',
+].join('\n')
+
+const out = (line) => process.stdout.write(`${line}\n`)
+
+async function main (argv) {
+  setLang(detectLang())
+  const [command, ...rest] = argv
+  const config = loadConfig()
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    out(HELP())
+    return 0
+  }
+
+  // Мастер настройки: меню, а не поток вопросов. Ведёт себя как «первичная
+  // настройка», но годится и для правок: текущие значения он предлагает по
+  // умолчанию, поэтому пустой ответ ничего не меняет.
+  if (command === 'onboard') {
+    const store = openStore()
+    const { runOnboard, pickPolicy } = await import('../lib/onboard.mjs')
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    const ask = async (question) => {
+      const answer = await rl.question(question)
+      return answer
+    }
+    try {
+      await runOnboard({
+        ask,
+        print: (line) => out(line),
+        load: () => openStore().settings ?? {},
+        save: (patch) => openStore().saveSettings(patch),
+        autostart: async (cfg) => {
+          const answers = await runAutostart({
+            ask,
+            print: (line) => out(line),
+            config: cfg ?? {},
+            execStart: resolveExecStart(process.argv[1]),
+            hasSudo: process.env.DSHNC_SUDO === '1',
+          })
+          applyAutostartAnswers(cfg ?? {}, answers)
+        },
+        status: (cfg) => {
+          const { url, policy } = pickPolicy(cfg ?? {})
+          return [
+            `узел: ${cfg?.name ?? '—'}`,
+            `сервер: ${url ?? 'не подключён'}`,
+            `каталоги: ${(policy.roots ?? cfg?.roots ?? []).join(', ') || '—'}`,
+            `режимы: base ${policy.base ?? '—'}, потолок ${policy.max ?? '—'}, вопросы ${policy.approver ?? '—'}`,
+            `связь: опрос ${cfg?.pollIdleMs ?? 0} мс, пинг ${cfg?.pingInterval ?? 0} с`,
+          ]
+        },
+      })
+    } finally {
+      rl.close()
+    }
+    return 0
+  }
+
+  if (command === 'autostart') {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    const ask = async (question, fallback) => {
+      const answer = await rl.question(formatQuestion(question, fallback))
+      return answer.trim() || fallback || ''
+    }
+    try {
+      const result = await runAutostart({
+        ask,
+        print: out,
+        config,
+        execStart: resolveExecStart(process.argv[1]),
+        hasSudo: process.env.DSHNC_SUDO === '1',
+      })
+      applyAutostartAnswers(config, result)
+      openStore().saveSettings({ name: config.name, aliases: config.aliases })
+      out(t('auto.nodeSummary', { name: config.name })
+        + (config.aliases?.length ? t('auto.aliasesSuffix', { aliases: config.aliases.join(', ') }) : ''))
+    } finally {
+      rl.close()
+    }
+    return 0
+  }
+
+  if (command === 'version' || command === '--version' || command === '-v') {
+    out(t('version.line', { version: VERSION, proto: PROTO }))
+    return 0
+  }
+
+  if (command === 'workdir') {
+    if (rest[0]) {
+      const dir = resolve(rest[0])
+      mkdirSync(dir, { recursive: true })
+      try {
+        openStore().saveSettings({ workdir: dir })
+      } catch (error) {
+        process.stderr.write(t('err.writeState', { message: error.message }) + '\n')
+        return 1
+      }
+      config.workdir = dir
+      out(t('workdir.set', { dir: config.workdir }))
+    } else {
+      out(config.workdir ?? t('workdir.none'))
+    }
+    return 0
+  }
+
+  if (command === 'policy') {
+    const store = openStore()
+    const [url, ...pairs] = rest
+    if (!url) {
+      out(t('policy.current', { access: JSON.stringify(config.access ?? {}), roots: (config.roots ?? []).join(', ') || '—' }))
+      for (const [key, value] of Object.entries(config.policy ?? {})) {
+        out(`${key}: ${JSON.stringify(value)}`)
+      }
+      return 0
+    }
+    const target = normalizeUrl(url)
+    const patch = {}
+    for (const pair of pairs) {
+      // делим по первому «=»: значение само может содержать «=» (zenity --width=600)
+      const at = pair.indexOf('=')
+      if (at < 0) continue
+      const key = pair.slice(0, at)
+      const value = pair.slice(at + 1)
+      if (!value) continue
+      if (key === 'max') patch.max = value
+      if (key === 'ask') patch.ask = value === 'true' || value === '1'
+      if (key === 'roots') patch.roots = value.split(':').filter(Boolean)
+      if (key === 'base') patch.base = value
+      if (key === 'approver') patch.approver = value
+      if (key === 'tool') {
+        // внешний инструмент локального апрува: включаем канал и запоминаем команду
+        patch.ask = { local: { enabled: true, tool: { type: 'external', command: value } } }
+      }
+      if (key === 'workdir') patch.workdir = resolve(value)
+    }
+    if (!Object.keys(patch).length) {
+      out(JSON.stringify(config.policy?.[target] ?? {}, null, 2))
+      return 0
+    }
+    config.policy ??= {}
+    config.policy[target] = { ...(config.policy[target] ?? {}), ...patch }
+    try {
+      store.saveSettings({ policy: config.policy })
+    } catch (error) {
+      // частая причина — попытка поменять политику изнутри песочницы: писать
+      // в ~/.dshnc там нельзя, и молчать об этом нельзя тоже
+      process.stderr.write(t('err.writeState', { message: error.message }) + '\n')
+      return 1
+    }
+    out(t('policy.saved', { url: target, patch: JSON.stringify(patch) }))
+    return 0
+  }
+
+  // Настройки верхнего уровня: то, что относится к самому клиенту, а не к
+  // конкретному серверу. Нужны, чтобы менять поведение без правки файла руками
+  // (и без риска сломать YAML-комментарии).
+  if (command === 'config') {
+    const store = openStore()
+    const pairs = rest
+    if (!pairs.length) {
+      const plain = { ...config }
+      delete plain.servers
+      delete plain.policy
+      out(JSON.stringify(plain, null, 2))
+      return 0
+    }
+    const patch = {}
+    for (const pair of pairs) {
+      const at = pair.indexOf('=')
+      if (at < 0) continue
+      const key = pair.slice(0, at)
+      const raw = pair.slice(at + 1)
+      if (!key || raw === '') continue
+      const value = /^-?\d+(\.\d+)?$/.test(raw) ? Number(raw) : raw === 'true' ? true : raw === 'false' ? false : raw
+      patch[key] = value
+    }
+    if (!Object.keys(patch).length) {
+      out(t('config.usage'))
+      return 1
+    }
+    try {
+      store.saveSettings(patch)
+    } catch (error) {
+      process.stderr.write(t('err.writeState', { message: error.message }) + '\n')
+      return 1
+    }
+    out(t('config.saved', { patch: JSON.stringify(patch) }))
+    return 0
+  }
+
+  if (command === 'audit') {
+    const limit = Number(rest[0]) > 0 ? Number(rest[0]) : 20
+    const rows = openStore().readAudit(limit)
+    if (!rows.length) {
+      out(t('audit.empty'))
+      return 0
+    }
+    for (const row of rows) {
+      // локальное время: аудит читает человек, а не машина
+      const when = new Date(row.at).toLocaleString('sv-SE').replace('T', ' ')
+      const session = (row.session ?? '—').replace(/^session-/, '').slice(0, 8)
+      out(`${when}  ${row.mode}  код ${row.code ?? '—'}  ${session}  ${row.command.replace(/\s+/g, ' ').slice(0, 120)}`)
+    }
+    return 0
+  }
+
+  if (command === 'status') {
+    out(t('status.id', { id: config.id }))
+    out(t('status.name', { name: config.name }))
+    const store = openStore()
+    const servers = store.servers()
+    if (!servers.length) {
+      out(t('status.none'))
+      return 0
+    }
+    for (const url of servers) {
+      const state = { ...store.readState(url), token: store.token(url) }
+      out(t('status.server', {
+        url,
+        token: state.token ? t('status.token.yes') : t('status.token.no'),
+        cursor: state.cursor ?? '—',
+        epoch: state.epoch ?? '—',
+        alias: state.alias ? t('status.alias', { alias: state.alias }) : '',
+      }))
+    }
+    return 0
+  }
+
+  if (command === 'connect') {
+    const url = rest[0]
+    if (!url) {
+      process.stderr.write(t('err.needUrl') + '\n')
+      return 2
+    }
+    const withCode = url.includes('?')
+    const state = withCode
+      ? await pairServer({ url, config, print: out })
+      : await enrollServer({ url: normalizeUrl(url), config, print: out })
+    out(t('connect.done'))
+    return state ? 0 : 1
+  }
+
+  if (command === 'daemon') {
+    const urls = rest.filter((arg) => !arg.startsWith('--'))
+    const targets = urls.length ? urls.map(normalizeUrl) : openStore().servers()
+    if (!targets.length) {
+      process.stderr.write(t('err.nothingToServe') + '\n')
+      return 2
+    }
+    const controller = new AbortController()
+    const stop = () => {
+      out(t('daemon.stopping'))
+      // фоновые процессы умирают вместе с демоном: иначе после остановки
+      // сервиса на машине остаются работать задания, о которых никто не знает
+      try {
+        jobPlugin.stopAll()
+      } catch {}
+      controller.abort()
+    }
+    process.on('SIGINT', stop)
+    process.on('SIGTERM', stop)
+    // SIGHUP обрабатывает сам раннер: он же будит спящий цикл и переобъявляет
+    // API. Здесь ничего не делаем, чтобы не было двух источников правды.
+    const plugins = await loadPlugins({ dir: join(home(), 'plugins'), log: (level, message) => out(message) })
+    out(t('version.line', { version: VERSION, proto: PROTO }))
+    out(t('daemon.servers', { servers: targets.join(', ') }))
+    out(t('daemon.plugins', { plugins: plugins.map((plugin) => plugin.api.name).join(', ') }))
+    const shell = process.env.DSHNC_SHELL ?? '/bin/sh'
+    await Promise.all(targets.map((url) => runServer({
+      url,
+      config,
+      print: (line) => out(line),
+      signal: controller.signal,
+      shell,
+      plugins,
+    }).catch((error) => {
+      if (error.message !== 'aborted') process.stderr.write(`${url}: ${error.message}\n`)
+    })))
+    return 0
+  }
+
+  process.stderr.write(t('cmd.unknown', { command }) + '\n\n' + HELP())
+  return 2
+}
+
+main(process.argv.slice(2)).then((code) => process.exit(code)).catch((error) => {
+  process.stderr.write(t('err.generic', { message: error.message }) + '\n')
+  process.exit(1)
+})