@twinsearth/w2m-dsh-plugin 0.47.0 → 0.49.0

package/CHANGELOG.md

@@ -4,6 +4,123 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.49.0] — 2026-10-15
+
+**Every message now gets an answer. Five inputs were being silently dropped, and two of the three input
+types the request asked me to advertise are not supported.**
+
+### What was silent, measured before it was changed
+
+```
+文字 /run node --version  → dispatch
+文字 /run --ask 你好       → reply
+文字 你好                  → ignore   why=not a /run line
+图片 (type 2)             → ignore   why=not a text message
+语音 (type 3)             → ignore   why=not a text message
+空 item_list              → ignore   why=not a text message
+```
+
+**Five inputs, no answer.** A bot that reads messages and replies to none of them is
+**indistinguishable from a bot that is broken**, and the operator's only move was to send the command again.
+
+### The one silence that survived, and why it had to
+
+`no sender` and `no context_token` still return `ignore`. **With no sender or no context token there is
+nowhere to send an answer**, so returning `reply` would be a plan that lies about what the caller can do.
+**That is the reason the vocabulary still contains `ignore` at all** — collapsing it into `reply` would have
+made every plan look successful while nothing was sent.
+
+### The request asked the help to advertise "text, voice and images". I refused two of the three.
+
+`textOf` reads only `item type: 1` — **measured, not inferred: an image and a voice note both answer
+`not a text message`.** So the help says:
+
+> 支持：文字。中文可以。
+> 不支持：语音、图片、文件、表情——它们只会得到这条帮助。
+
+**A help text that promised a capability the bridge does not have would be read as a bug the first time
+somebody sent a photo**, and the bug report would be about the bridge rather than about the promise.
+
+### The three sections are asserted by heading
+
+`【1】开关指令` · `【2】指令规则与格式` · `【3】参考与边界` — asserted by name rather than by "the text mentions
+commands", because **a help text that loses a section still reads fine.**
+
+Two of the seven new assertions are worth naming:
+
+* **`--ask` is in the help.** It was reachable only by reading the source, which is the entire
+  discoverability defect this section exists to close. If it ever leaves the help, the defect is back.
+* **every `/run` example in the help is put through the real parser.** The help cannot drift into
+  advertising syntax that is refused.
+
+### The activation instruction, answered honestly
+
+*"If refused, provide the activation instruction"* — and the honest answer is that **a chat window cannot
+activate itself**. The help says the capabilities are granted by whoever starts the bridge, through
+`W2M_CAPABILITIES`, and that a refusal names the missing capability. **Implying otherwise would have sent
+the operator looking for a command that does not exist.**
+
+**Three existing tests demanded `ignore` and now demand `reply`.** They were right about the rule — a typo
+must never become a fleet execution — and wrong about how the rule is expressed. They were updated rather
+than deleted, because **the old expectation is the record of what changed.**
+
+**7 new tests, 0 failures.**
+
+## [0.48.0] — 2026-10-15
+
+**`--dry-run` dispatched. Two dry runs sent a command to five machines, and one made a real task.**
+
+### The defect, measured before it was described
+
+The bridge guarded exactly one thing under `--dry-run`: the **reply**. The dispatch ran unconditionally.
+
+```
+[15:13:57] dry run     : true
+[15:15:00]   dispatched task 01M50231AYJYDD41WSPMS9PRM3
+[15:15:50]   verdict for …: partial
+```
+
+**That is a real task record with five real leases, produced by a run whose flag promised nothing would
+happen.** A rehearsal executed commands on production machines — and it was found by accident, while draining
+a message queue, not by a test.
+
+### Why the fix is "skip the dispatch" and not "rename the flag"
+
+**This repository already fixes the meaning of the word.** `update-install`'s `dryRun` is asserted to **call no
+package manager and write nothing**, and `auto-update`'s is asserted to **write nothing to the profile**. So a
+second `dry-run` meaning "do the dangerous part anyway" is not a naming preference — **it is two flags with one
+name and opposite meanings, and the bridge held the unsafe one.**
+
+**Renaming would have left the flag. Aligning keeps the word and removes the hazard**, and a reader who knows
+`dryRun` from anywhere else in this project is now already right about this one.
+
+### Why the guard is a function in `lib`, not an `if` in the script
+
+`scripts/` is **not in `package.json#files`**, so nothing there is covered by a test that ships. A safety
+property expressed as one line inside an untested script is a property nobody re-checks. `dryRunPolicy` is
+exported and asserted beside the wire shapes — **a script is not where a guard should live if the guard is the
+point.**
+
+The guard sits at the **top of the only function that reaches `fleet.run`**, not at its call site, because a
+guard at the call site is one edit away from being bypassed by a second caller.
+
+### A name collision that made my own test wrong
+
+I asserted that `dryRun: 'true'` must not dispatch. **It does dispatch — the code was right and the test was
+wrong**, and the cause is two different things sharing one word:
+
+| | meaning |
+|---|---|
+| the CLI **flag** `--dry-run` | **present-means-true** (`argv.includes('--dry-run')`) |
+| the **parameter** `dryRun` | **defaults to false**, which is what `update-install` means by it |
+
+`dryRunPolicy` takes the parameter, and the script always hands it a boolean. The assertion is now the strict
+one — **only `true` turns the dispatch off, so a future caller cannot open the path with a truthy value.**
+
+**5 new tests, 0 failures.** One of them reads the script and asserts the guard appears **before** the only
+call that can reach the fleet — because a test of the pure function alone would pass while the script still
+dispatched, **which is precisely the shape of the original defect.**
+
 ## [0.47.0] — 2026-10-15
 
 **Correcting my own counts: 0.46.0 said 54/32/22, the table says 61/53/8.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "DSH: Windows2MacOS — drive the same project on online Windows and macOS machines from one DeepSeek account, across networks and regions. P2P hole punching is the default path (relay + shared server as rendezvous, ledger and fallback), with a bundled STUN responder, Tailscale/public-VPS/tunnel shapes, Rabbit relay + per-machine Localside + eight DSH tools (replicate / split), nine aggregate verdicts and signed requests.",
   "type": "module",
   "main": "lib/index.js",

package/src/chatops/ilink-fleet-bridge.mjs

@@ -25,6 +25,47 @@
 
 import { parseInvocation, renderVerdict, renderDispatchFailure } from './run-command.mjs';
 
+/**
+ * What a run with `--dry-run` set is allowed to do.
+ *
+ * ## The defect this exists to make unreachable
+ *
+ * `scripts/ilink-fleet-bridge.mjs` guarded exactly one thing under `--dry-run`: the **reply**. The
+ * dispatch itself ran unconditionally, so **two dry runs sent `node--version` to all five machines**
+ * — and one of them produced a real task record with five real leases. The flag's name promises that
+ * nothing happens, and the promise was false in the direction that matters: **a rehearsal executed
+ * commands on production machines.**
+ *
+ * ## Why "skip the dispatch" rather than "rename the flag"
+ *
+ * This repository already fixes the meaning of the word. `update-install`'s `dryRun` is asserted to
+ * **write nothing and call no package manager**, and `auto-update`'s is asserted to **write nothing to
+ * the profile**. So a second `dry-run` that means "do the dangerous part anyway" is not a naming
+ * preference — it is two flags with one name and opposite meanings, and the bridge held the unsafe one.
+ *
+ * **Renaming would have left the flag. Aligning keeps the word and removes the hazard**, and it means
+ * a reader who knows `dryRun` from anywhere else in this project is already right about this one.
+ *
+ * ## Why this is a function rather than an `if` in the script
+ *
+ * `scripts/` is not in `package.json#files`, so nothing there is covered by a test that ships. A safety
+ * property expressed as one line inside an untested script is a property nobody re-checks. As an
+ * exported function with a name, it is asserted in `chatops-ilink-fleet-bridge.test.mjs` beside the
+ * wire shapes — **a script is not where a guard should live if the guard is the point.**
+ *
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{ dispatch: boolean, reply: boolean, reason: string|null }}
+ */
+export function dryRunPolicy(options = {}) {
+  if (options.dryRun !== true) return { dispatch: true, reply: true, reason: null };
+  return {
+    dispatch: false,
+    reply: false,
+    // Carried so the caller logs *why* nothing happened rather than printing a bare "[dry-run]".
+    reason: 'dry run: the fleet was not dispatched to, and no reply was sent',
+  };
+}
+
 /** The header every authenticated call needs; undocumented and mandatory. */
 export const AUTH_TYPE = 'ilink_bot_token';
 export const APP_ID = 'bot';
@@ -99,6 +140,64 @@ export function sendSucceeded(response) {
   return response.ret === 0 || response.errcode === 0;
 }
 
+/**
+ * What to say when a message is not a command.
+ *
+ * ## The requirement this satisfies, and the part of it that had to be refused
+ *
+ * *"Every sentence from WeChat must get a reply; a mistake must get help."* Before this, **five measured
+ * inputs were silently dropped**: a plain sentence, an image, a voice note, an empty `item_list`, and an
+ * empty string. The operator sees a bot that reads messages and answers nothing, which is
+ * indistinguishable from a bot that is broken.
+ *
+ * The request also asked the help to advertise *"text, voice and images"*. **Two of those three are not
+ * supported**, and `textOf` reading only `type: 1` is the proof: an image and a voice note both answer
+ * `not a text message`. So the boundary section says what is true — **a help text that promises a
+ * capability the bridge does not have would be read as a bug the first time somebody sent a photo.**
+ *
+ * ## Why the boundary is a section rather than a footnote
+ *
+ * A user cannot discover a limitation they are never told about. **"Voice is not supported" arriving in
+ * the same breath as the command syntax is the difference between a limitation and a mystery.**
+ *
+ * @param {{reason?: string|null}} [context]
+ * @returns {string}
+ */
+export function helpText(context = {}) {
+  const why = typeof context.reason === 'string' && context.reason !== '' ? context.reason : null;
+  const lines = [];
+  if (why !== null) lines.push(`没有执行这条消息：${why}`, '');
+
+  lines.push(
+    '【1】开关指令',
+    '  /run <命令>            把一个命令派发到编队（默认所有在线机器）',
+    '  /run --ask <一句话>    问一句话，不执行任何东西',
+    '  /run --on <机器> <命令>  只派发到指定机器（逗号分隔）',
+    '  /run --timeout <毫秒> <命令>  覆盖等待上限',
+    '  /run --mode <模式> <命令>  replicate | split | broadcast | pipeline',
+    '',
+    '  —— 关于权限：这个窗口当前的能力是 operate、fleet.dispatch。',
+    '     若被拒绝，回复里会写明缺哪一个能力；能力由启动桥接的人通过',
+    '     W2M_CAPABILITIES 授予，聊天窗口本身不能自行激活。',
+    '',
+    '【2】指令规则与格式',
+    '  · 只能以 /run 开头，其余文字一律当作普通消息并回这条帮助。',
+    '  · /run 之后是 argv（逐个词），不是 shell 字符串：',
+    '    管道 | 、重定向 > 、&& 都不会生效，会被拒绝。',
+    '  · 每个词里的空格要用引号包起来。',
+    '  · 举例： /run node --version',
+    '          /run git rev-parse --short HEAD',
+    '          /run --ask 现在编队里有几台机器在线？',
+    '',
+    '【3】参考与边界',
+    '  · 支持：文字。中文可以。',
+    '  · 不支持：语音、图片、文件、表情——它们只会得到这条帮助。',
+    '  · 命令是否被允许由目标机器自己的允许清单决定；',
+    '    被拒绝时回复会带上原因码（如 COMMAND_NOT_ALLOWED）。',
+  );
+  return lines.join('\n');
+}
+
 /**
  * Decide what to do with one inbound message.
  *
@@ -117,14 +216,34 @@ export function planMessage({ message, authorize }) {
   const contextToken = message?.context_token;
   const text = textOf(message);
 
+  /**
+   * The only two real silences, and both are structural rather than a decision.
+   *
+   * With no `from_user_id` or no `context_token` there is nowhere to send an answer to — so a `reply`
+   * here would be a promise the caller cannot keep. **These stay `ignore`, and they are the reason the
+   * vocabulary still has one**: collapsing them into `reply` would make the plan lie about what the
+   * script can do. Everything below this line gets an answer, because it can.
+   */
   if (typeof from !== 'string' || from === '') return { act: 'ignore', why: 'no sender' };
   if (typeof contextToken !== 'string' || contextToken === '') return { act: 'ignore', why: 'no context_token' };
-  if (text === null) return { act: 'ignore', why: 'not a text message' };
+
+  // A non-text message is answered rather than dropped: "every sentence must get a reply" includes the
+  // sentences the bridge cannot read.
+  if (text === null) {
+    return { act: 'reply', to: from, contextToken, text: helpText({ reason: '这条消息不是文字（语音/图片/文件暂不支持）' }) };
+  }
 
   const trimmed = text.trim();
-  // Only the exact `/run` prefix is an action. Everything else is conversation, which is what keeps
-  // a typo from becoming a fleet execution.
-  if (!/^\/run(\s|$)/i.test(trimmed)) return { act: 'ignore', why: 'not a /run line' };
+  // Only the exact `/run` prefix is an action, and that rule is unchanged: a typo must never become a
+  // fleet execution. What changed is that it now gets an answer instead of silence.
+  if (!/^\/run(\s|$)/i.test(trimmed)) {
+    return {
+      act: 'reply',
+      to: from,
+      contextToken,
+      text: helpText({ reason: trimmed === '' ? '空消息' : '这条消息没有以 /run 开头' }),
+    };
+  }
 
   const body = trimmed.replace(/^\/run\s*/i, '');
   const invocation = parseInvocation(body);

package/src/plugin/tools.mjs

@@ -208,7 +208,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '0.47.0';
+const PLUGIN_VERSION = '0.49.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;