dsh-lan-peers 0.8.1 → 0.8.2

package/client/cli-dispatch.test.mjs

@@ -0,0 +1,226 @@
+// dsh-lan-peers · CLI 的群内派单可见面（v0.8.2-α，契约 §1/§4/§5）。
+//
+// 真进程跑 cli.mjs：hub 在本进程里起（所以子进程必须异步跑），本机 host 的管理接口
+// 用一个小 HTTP 桩代替 —— 派单执行在 host 里（Lane X），CLI 只负责「发完消息再去触发」。
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createPeerServer } from '../host/server.mjs';
+import { makeTempStateDir, peerFixture, seedPeers, writeJson0600 } from '../host/test/helpers.mjs';
+
+const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.mjs');
+const MEMBER = peerFixture('peer-cli-dispatch');
+
+function runAsync(args) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [CLI, ...args], { encoding: 'utf8' }, (error, stdout, stderr) => {
+      resolve({ status: error ? error.code : 0, stdout, stderr });
+    });
+  });
+}
+
+async function startHub(t, overrides = {}) {
+  const stateDir = makeTempStateDir();
+  seedPeers(stateDir, overrides.peers ?? [MEMBER]);
+  const server = createPeerServer({
+    listenHost: '127.0.0.1',
+    stateDir,
+    // 这个文件测的是 CLI 行为：quorum:none = 写本地即提交，不牵扯选举投票。
+    group: { enabled: true, autoJoin: true, quorum: 'none' },
+    ...overrides,
+  });
+  const info = await server.listen(0, '127.0.0.1');
+  t.after(async () => {
+    await server.close();
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  });
+  return { server, baseUrl: info.url, stateDir };
+}
+
+function memberStateDir(t, { baseUrl, hubInstanceId, identity = MEMBER, peerName = 'hub' }) {
+  const dir = makeTempStateDir('dsh-lan-peers-cli-dispatch-');
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  writeJson0600(path.join(dir, 'state.json'), {
+    instanceId: identity.peerId,
+    name: identity.name,
+    createdAt: new Date().toISOString(),
+  });
+  writeJson0600(path.join(dir, 'peers.json'), {
+    peers: {
+      [hubInstanceId]: {
+        name: peerName,
+        baseUrl,
+        secret: identity.inboundSecret,
+        inboundSecret: 'unused-outbound',
+        addedAt: new Date().toISOString(),
+        lastSeen: null,
+      },
+    },
+  });
+  return dir;
+}
+
+/** 本机 host 的管理接口桩：只实现 group/dispatch 与 group/accept，记录每一次请求。 */
+async function startAdminStub(t, handler) {
+  const requests = [];
+  const server = http.createServer((req, res) => {
+    let raw = '';
+    req.on('data', (chunk) => { raw += chunk; });
+    req.on('end', () => {
+      const payload = raw === '' ? null : JSON.parse(raw);
+      requests.push({ method: req.method, url: String(req.url), payload });
+      let answer = {};
+      try {
+        answer = handler({ url: String(req.url), payload }) || {};
+      } catch (error) {
+        answer = { status: 500, json: { error: String(error.message || error) } };
+      }
+      res.writeHead(Number(answer.status) || 200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(answer.json ?? {}));
+    });
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  t.after(() => new Promise((resolve) => server.close(resolve)));
+  return { requests, url: 'http://127.0.0.1:' + server.address().port };
+}
+
+/** 一条到 hub 的、已入群的成员 state-dir */
+async function joinedMember(t) {
+  const hub = await startHub(t);
+  const dir = memberStateDir(t, { baseUrl: hub.baseUrl, hubInstanceId: hub.server.store.instanceId });
+  const joined = await runAsync(['group', 'join', '--peer', 'hub', '--state-dir', dir]);
+  assert.equal(joined.status, 0, joined.stderr);
+  return { hub, dir };
+}
+
+const DONE = {
+  ok: true,
+  dispatch: { target: 'nas-box', targetName: 'nas-box', status: 'done', reason: '', elapsedMs: 1234, replyChars: 56 },
+};
+
+test('group --help 列出 dispatch 与 accept 两个新子命令', async () => {
+  const out = await runAsync(['group', '--help']);
+  assert.match(out.stdout, /dispatch <目标> <任务\.\.\.>/);
+  assert.match(out.stdout, /accept on\|off/);
+  assert.match(out.stdout, /@!名字 时作者侧自动派单/);
+});
+
+test('group dispatch <目标> <任务>：等价发一条 @!目标 任务，再触发本机派单并打印摘要', async (t) => {
+  const { hub, dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, ({ url }) => (url.includes('/group/dispatch') ? { json: DONE } : { json: { ok: true } }));
+
+  const out = await runAsync([
+    'group', 'dispatch', 'nas-box', '跑', '回归', '--peer', 'hub', '--state-dir', dir, '--url', admin.url,
+  ]);
+  assert.equal(out.status, 0, out.stderr);
+  assert.match(out.stdout, /已发送 seq=\d+/);
+  assert.match(out.stdout, /派单 → nas-box：done（1234ms \/ 56字）/);
+
+  const dispatched = admin.requests.filter((request) => request.url === '/api/lan-peers/group/dispatch');
+  assert.equal(dispatched.length, 1);
+  assert.deepEqual(dispatched[0].payload, { target: 'nas-box', task: '跑 回归', extraTargets: 0 });
+
+  // 群消息先入库，且内容就是 "@!目标 任务"
+  const history = await runAsync(['group', 'history', '--peer', 'hub', '--state-dir', dir]);
+  assert.equal(history.status, 0, history.stderr);
+  assert.match(history.stdout, /@!nas-box 跑 回归/);
+  assert.ok(hub.server, 'hub 必须还活着');
+});
+
+test('group post --text "@!X 任务"：自动派单；普通消息一次都不打派单接口', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, ({ url }) => (url.includes('/group/dispatch') ? { json: DONE } : { json: { ok: true } }));
+
+  const withBang = await runAsync([
+    'group', 'post', '--text', '@!nas-box 修 CI', '--peer', 'hub', '--state-dir', dir, '--url', admin.url,
+  ]);
+  assert.equal(withBang.status, 0, withBang.stderr);
+  assert.match(withBang.stdout, /派单 → nas-box：done/);
+  assert.equal(admin.requests.length, 1);
+  assert.deepEqual(admin.requests[0].payload, { target: 'nas-box', task: '修 CI', extraTargets: 0 });
+
+  const plain = await runAsync([
+    'group', 'post', '--text', '@nas-box 只是提及', '--peer', 'hub', '--state-dir', dir, '--url', admin.url,
+  ]);
+  assert.equal(plain.status, 0, plain.stderr);
+  assert.equal(admin.requests.length, 1, '没有 @! 就一次派单请求都不发');
+});
+
+test('本机没有 host：消息照发，但派单未触发要如实报错 exit 2（不静默当普通消息）', async (t) => {
+  const { dir } = await joinedMember(t);
+  // 默认 --url 指向 127.0.0.1:7788：本测试里那里没有 host
+  const out = await runAsync([
+    'group', 'post', '--text', '@!nas-box 跑回归', '--peer', 'hub', '--state-dir', dir,
+    '--url', 'http://127.0.0.1:1',
+  ]);
+  assert.equal(out.status, 2);
+  assert.match(out.stdout, /已发送 seq=\d+/, '群消息确实发出去了');
+  assert.match(out.stderr, /派单未触发/);
+  assert.match(out.stderr, /本机 host 未响应/);
+});
+
+test('skipped（没有 @! 目标）显示未派单，不算完成也不算失败', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, () => ({ json: { ok: false, dispatch: { status: 'skipped', reason: 'no-target' } } }));
+  const out = await runAsync([
+    'group', 'dispatch', 'nas-box', '任务', '--peer', 'hub', '--state-dir', dir, '--url', admin.url,
+  ]);
+  assert.equal(out.status, 0, '零动作不是失败');
+  assert.match(out.stdout, /未派单（消息里没有 @! 目标）: no-target/);
+});
+
+test('派单失败（failed）打印 reason 并 exit 1', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, () => ({
+    json: { ok: false, dispatch: { target: 'nas-box', status: 'failed', reason: 'not-accepting', elapsedMs: 12 } },
+  }));
+  const out = await runAsync([
+    'group', 'dispatch', 'nas-box', '任务', '--peer', 'hub', '--state-dir', dir, '--url', admin.url,
+  ]);
+  assert.equal(out.status, 1);
+  assert.match(out.stdout, /派单 → nas-box：failed（not-accepting \/ 12ms）/);
+});
+
+test('group accept off：打本机管理接口并打印新状态', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, ({ payload }) => ({
+    json: { ok: true, acceptDispatch: payload.acceptDispatch, persisted: true },
+  }));
+  const off = await runAsync(['group', 'accept', 'off', '--state-dir', dir, '--url', admin.url]);
+  assert.equal(off.status, 0, off.stderr);
+  assert.match(off.stdout, /本机接单：已关闭/);
+  assert.deepEqual(admin.requests[0].payload, { acceptDispatch: false });
+
+  const on = await runAsync(['group', 'accept', 'on', '--state-dir', dir, '--url', admin.url]);
+  assert.equal(on.status, 0, on.stderr);
+  assert.match(on.stdout, /本机接单：接单中/);
+  assert.deepEqual(admin.requests[1].payload, { acceptDispatch: true });
+});
+
+test('group accept：host 未接线（501）→ exit 2 且说清原因', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, () => ({ status: 501, json: { error: 'accept-toggle-unsupported' } }));
+  const out = await runAsync(['group', 'accept', 'off', '--state-dir', dir, '--url', admin.url]);
+  assert.equal(out.status, 2);
+  assert.match(out.stderr, /切换接单失败/);
+  assert.match(out.stderr, /accept-toggle-unsupported/);
+});
+
+test('group accept 参数必须是 on|off；persisted=false 要如实说「重启后回原值」', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, ({ payload }) => ({
+    json: { ok: true, acceptDispatch: payload.acceptDispatch, persisted: false },
+  }));
+  const bad = await runAsync(['group', 'accept', 'toggle', '--state-dir', dir, '--url', admin.url]);
+  assert.equal(bad.status, 1);
+  assert.match(bad.stderr, /group accept on\|off/);
+  assert.equal(admin.requests.length, 0, '参数不对时一个请求都不发');
+
+  const ok = await runAsync(['group', 'accept', 'off', '--state-dir', dir, '--url', admin.url]);
+  assert.equal(ok.status, 0, ok.stderr);
+  assert.match(ok.stdout, /重启后回到配置值/);
+});

package/client/cli.mjs

@@ -23,6 +23,9 @@ import {
   probePeer,
 } from './peer-call.mjs';
 import { readPeerEvents } from './sse.mjs';
+// v0.8.2-α（契约 §1/§5）：@! 的解析口径与面板共用一份 —— 解析属于协议，不属于某一端。
+// 面板在管理接口里解析，CLI 在发完消息后解析，两边落在同一个函数上。
+import { parseGroupDispatchCommand } from '../lib/admin.mjs';
 import {
   GROUP_APPLY_POLL_INTERVAL_MS,
   GROUP_APPLY_POLL_TIMEOUT_MS,
@@ -137,6 +140,9 @@ const GROUP_USAGE = [
   '子命令:',
   '  state                     群信息 + 成员表（会拿到 groupKey，但不打印内容）',
   '  post --text "..."         发一条消息 [--kind chat|progress|result|system]',
+  '                            正文含 @!名字 时作者侧自动派单（由本机 host 执行并打印回执摘要）',
+  '  dispatch <目标> <任务...>  等价发一条 "@!目标 任务" 并派单，打印回执摘要',
+  '  accept on|off             切换本机接单（写 profile 配置，热生效）',
   '  history [--since N]       取历史消息 [--limit 1..200]',
   '  tail [--since N]          跟随事件流并逐条打印 [--duration 秒]',
   '  join [--name 显示名]      向 hub 自助加入（hub 开了 autoJoin 才成功）',
@@ -703,8 +709,68 @@ async function cmdGroupState(dir, args) {
   console.log('groupKey: 已在 group-key.json（32B，不显示）');
 }
 
-async function cmdGroupPost(dir, args) {
-  const text = String(args.text ?? args._.slice(1).join(' ') ?? '').trim();
+/**
+ * 契约 §3 的回执摘要（CLI 口径，与面板同形）：派单 → 目标：done/failed（reason / 耗时 / 字数）。
+ * skipped 是第三种终态：这条消息没有 @! 目标 —— 零消息写入，不能说成完成也不能说成失败。
+ */
+function formatDispatchLine(dispatch) {
+  const data = dispatch && typeof dispatch === 'object' ? dispatch : {};
+  const status = String(data.status ?? '');
+  const who = String(data.targetName ?? '') || String(data.target ?? '') || '—';
+  if (status === 'skipped') return '未派单（消息里没有 @! 目标）: ' + String(data.reason ?? 'no-target');
+  const parts = [];
+  // done 也可能带 reason（契约 §1：多个 @! 只取第一个，reason=multi-target-ignored）。
+  const reason = String(data.reason ?? '');
+  if (reason !== '') parts.push(reason);
+  else if (status !== 'done') parts.push('error');
+  const elapsed = Number(data.elapsedMs);
+  if (Number.isFinite(elapsed) && elapsed >= 0) parts.push(Math.round(elapsed) + 'ms');
+  const chars = Number(data.replyChars);
+  if (Number.isFinite(chars) && chars >= 0) parts.push(Math.round(chars) + '字');
+  return '派单 → ' + who + '：' + (status === 'done' ? 'done' : 'failed')
+    + (parts.length ? '（' + parts.join(' / ') + '）' : '');
+}
+
+/**
+ * 契约 §5：作者侧派单的执行口 = 本机回环的 POST /api/lan-peers/group/dispatch。
+ * 派单要开 1:1 会话、要往群里写 progress/result，只有本机 host 做得到；CLI 直连 hub
+ * 发消息，所以这里必须再打一次本机管理接口。
+ *
+ * 本机没有 host（纯 CLI 节点、host 没起）→ **如实报错并 exit 2**：
+ * 静默把 "@!X 任务" 当成一条普普通通的群消息发出去，是最坏的一种失败。
+ */
+async function triggerDispatch(args, command) {
+  const url = String(args.url ?? '').trim() || ADMIN_DEFAULT_URL;
+  let out;
+  try {
+    out = await adminCall(url, 'group/dispatch', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        target: command.target,
+        task: command.task,
+        extraTargets: command.extraTargets,
+      }),
+    });
+  } catch (error) {
+    const reason = String(error?.message ?? error);
+    process.stderr.write('消息已发出，但派单未触发：本机 host 未响应 ' + url + '（' + reason + '）\n'
+      + '修法：先起本机 host（或对 --url 指向的管理接口重试 group dispatch）\n');
+    process.exitCode = 2;
+    return;
+  }
+  const dispatch = out && out.dispatch && typeof out.dispatch === 'object' ? out.dispatch : null;
+  if (!dispatch) {
+    process.stderr.write('派单未返回结果：本机 host 未按契约回 dispatch 摘要\n');
+    process.exitCode = 2;
+    return;
+  }
+  console.log(formatDispatchLine(dispatch));
+  if (dispatch.status === 'failed') process.exitCode = 1;
+}
+
+/** 发一条群消息（post 与 dispatch 共用）；作者侧在 POST 之后按契约 §1 解析 @! 并派单。 */
+async function postGroupText(dir, args, text) {
   if (!text) throw new Error(GROUP_USAGE);
   if (Array.from(text).length > GROUP_TEXT_MAX_CHARS) {
     throw new Error('text 超过 ' + GROUP_TEXT_MAX_CHARS + ' 字符上限（hub 会回 413 payload-too-large）');
@@ -726,6 +792,53 @@ async function cmdGroupPost(dir, args) {
     '已发送 seq=' + sent.seq + ' ts=' + new Date(Number(sent.ts)).toISOString()
       + (channel.mode === 'group' ? '（群级签名直连 ' + channel.key.baseUrl + '）' : ''),
   );
+  // 只有 chat 参与解析：progress/result 本身就是回执，再解析一遍等于自己派自己。
+  if (kind !== 'chat') return;
+  const command = parseGroupDispatchCommand(text);
+  if (!command) return;
+  await triggerDispatch(args, command);
+}
+
+async function cmdGroupPost(dir, args) {
+  const text = String(args.text ?? args._.slice(1).join(' ') ?? '').trim();
+  await postGroupText(dir, args, text);
+}
+
+/** 契约 §5：显式入口 —— 等价发一条 "@!目标 任务" 再派单（消息先入库，回执摘要打印出来）。 */
+async function cmdGroupDispatch(dir, args) {
+  const target = String(args._[1] ?? '').trim();
+  const task = args._.slice(2).join(' ').trim() || String(args.text ?? '').trim();
+  if (target === '' || task === '') {
+    throw new Error('用法: dsh-lan-peers group dispatch <目标> <任务...>\n' + GROUP_USAGE);
+  }
+  await postGroupText(dir, args, '@!' + target + ' ' + task);
+}
+
+/** 契约 §4/§5：切换本机接单开关（写 profile 配置、热生效；结果以 host 回的为准）。 */
+async function cmdGroupAccept(dir, args) {
+  const wanted = String(args._[1] ?? '').trim().toLowerCase();
+  const value = wanted === 'on' ? true : (wanted === 'off' ? false : null);
+  if (value === null) {
+    throw new Error('用法: dsh-lan-peers group accept on|off\n' + GROUP_USAGE);
+  }
+  const url = String(args.url ?? '').trim() || ADMIN_DEFAULT_URL;
+  let out;
+  try {
+    out = await adminCall(url, 'group/accept', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ acceptDispatch: value }),
+    });
+  } catch (error) {
+    const reason = String(error?.message ?? error);
+    process.stderr.write('切换接单失败：本机 host 未接受 ' + url + '（' + reason + '）\n'
+      + '修法：确认本机 host 在跑且群功能已启用（' + reason + ' 为 501 表示 host 还没接线）\n');
+    process.exitCode = /^(40[39]|501)\b/.test(reason) ? 2 : 1;
+    return;
+  }
+  const applied = !(out && out.acceptDispatch === false);
+  console.log('本机接单：' + (applied ? '接单中' : '已关闭')
+    + (out && out.persisted === false ? '（仅本进程生效，重启后回到配置值）' : ''));
 }
 
 async function cmdGroupHistory(dir, args) {
@@ -1340,6 +1453,8 @@ async function cmdGroup(args) {
   const handlers = {
     state: cmdGroupState,
     post: cmdGroupPost,
+    dispatch: cmdGroupDispatch,
+    accept: cmdGroupAccept,
     history: cmdGroupHistory,
     tail: cmdGroupTail,
     join: cmdGroupJoin,