@mu-cabin/muc-cli 0.2.2 → 0.3.1

package/README.md

@@ -13,11 +13,14 @@ with real devices; see [Coexistence](#coexistence) below before sending.
 
 A single command (`muc`) packaging:
 
-- **Send** — 1:1 and group text, files, images, and voice clips.
+- **Send** — 1:1 and group text, files, images, and voice clips. Add and
+  remove emoticon reactions on existing messages.
 - **Read** — server-side chat history, profile lookups, group lists, sticker
-  packs, and directory search (people, departments, apps, service numbers).
+  packs, directory search (people, departments, apps, service numbers), and
+  long-lived `listen` tail of inbound messages with sender/keyword filters.
 - **Manage** — login / token refresh, withdraw a message, clear a session,
-  download a chat-attached file.
+  download a chat-attached file, wait for a human emoticon reaction before
+  proceeding (`wait-react`).
 - **Self-describe** — every command has a `--json` mode emitting a stable
   envelope; `muc manifest --json` returns the full command graph + per-command
   output JSON Schema for agent / script consumers.
@@ -186,6 +189,9 @@ MUC_ACCOUNT=WANGLULU8 MUC_PASSWORD='…' muc login
 | `muc emoticons` | Sticker packages installed on your account. |
 | `muc history --peer UID \| --team TEAM_ID \| --to-self` | Server-side chat history via the roaming-messages endpoint. Stateless: each call fetches from the server. Default window: 30 days, 50 messages newest-first. |
 | `muc download --file-key <key> [--out <path>]` | Download a chat-attached file from the V5 file server (TCP 6101). **Read-only** — opens a fresh per-request session, no chat login, doesn't kick anyone. Pass `--mid <mid>` instead of `--file-key` plus `--peer/--team/--to-self` to look the file up via roaming history. Verifies md5 on completion. |
+| `muc react --mid <MID> --sticker-id <id> [target]` | Add an emoticon reaction to an existing message. **Visible.** Defaults to `--to-self`; non-self chats need `--yes-not-self`. By default assumes the original message was sent by the current user; pass `--src-sender-id <UID>` (and `--src-sender-app <appkey>`) to react to someone else's message. |
+| `muc reactions --mid <MID>` | List all emoticon reactions on a single message. Read-only. |
+| `muc unreact --emoticon-id <id> [target]` | Revoke one of your own reactions (id from `muc react` or `muc reactions`). |
 | `muc manifest` | Print the full command graph + per-command output JSON Schema. Pair with `--json` for agents. |
 
 `history` flags: scope with one of `--peer UID`, `--team TEAM_ID`,
@@ -214,10 +220,18 @@ muc history --team 9009876543210000 --before 2026-04-20 --json | jq .
 | `muc send-voice <file> --duration <ms> [target]` | Same as `send-file` but as `MESSAGE_CHAT_AUDIO` (subType=9). `--duration <ms>` is required (the desktop renders the bubble's clip length from this metadata, not from the file). |
 | `muc withdraw --mid <MID> [target]` | Recall a sent message. Original gets replaced server-side with "您撤回了一条消息". Target flag must match the original message's chat. |
 | `muc clear-session [target]` | Delete a session from your client-side history (syncs to all your devices). **Doesn't delete server-side history** — `history` still returns the messages. |
-
-`--os` defaults to `iOS`. Valid values: `Windows`, `OS X`, `Mac`, `iOS`,
-`Android`. **`--os` does not provide coexistence — read the section below
-before using any chat-channel command if you have a real device logged in.**
+| `muc wait-react --mid <MID> [--from-uid UID] [--sticker-id ID] [--timeout 300]` | Block until someone reacts with an emoticon to `--mid`, then exit. Useful as a "human-in-the-loop approval" gate after `muc send`. Exits with `TIMEOUT` (exit 5) if no matching reaction arrives within `--timeout` seconds. |
+| `muc listen [--from-uid UID] [--team TEAM] [--peer UID] [--contains TEXT] [--regex …] [--at-me] [--max N]` | Long-lived TCP tap that emits one **NDJSON line per matching inbound message** (in `--json` mode each line is the standard envelope; in human mode it's a one-line summary). Supports repeatable filters (OR semantics within each kind, AND across kinds), `--at-me` to restrict to group messages where another user @-mentions you (implies excluding self), `--include-self` to include your own sends, `--include-reactions` to also surface type=3 sub=300/301 frames, `--max N` to exit after N matches. Stop with `^C`. |
+
+`--os` resolves as **per-call `--os` → `defaultChatOs` in `~/.muc/config.json`
+→ built-in `iOS`**. Valid values: `Windows`, `OS X`, `Mac`, `iOS`, `Android`.
+Set the per-machine default once with `muc init --default-os <os>` (or the
+`MUC_DEFAULT_OS` env var, or the interactive prompt during `muc init`). Useful
+if your real device is an iPhone — flip the CLI default to `windows` so
+chat-channel commands park on the PC slot instead of kicking your phone.
+**`--os` / `defaultChatOs` does not provide coexistence — read the section
+below before using any chat-channel command if you have a real device
+logged in.**
 
 Sending to anyone other than yourself requires the explicit `--yes-not-self`
 flag — a guard against accidentally messaging real humans during testing.
@@ -278,7 +292,9 @@ in as `iOS` (Mobile slot).
 
 The CLI defaults to `--os iOS` so it coexists with a Mac desktop. If your
 iPhone is also signed in, both slots are taken and any TCP command will
-kick one of them — fall back to REST-only commands.
+kick one of them — fall back to REST-only commands, or run
+`muc init --default-os windows` to flip the per-machine default to the PC
+slot (which kicks the desktop instead of the phone).
 
 `tcp-ping` only does TCP connect + NEGOTIATE (no `auth/login`), so it can't
 kick anything. Run it first to confirm the wire protocol is happy on your
@@ -351,6 +367,34 @@ $ muc emoticons
 Both files share the `~/.muc/` parent (mode 700). The CLI creates them on
 first use; you should never need to edit them by hand.
 
+## Changelog
+
+#### `0.3.1`
+`2026.04.29`
+- Add `defaultChatOs` to `~/.muc/config.json`: per-machine fallback for the chat-channel `--os` slot. Configure via `muc init --default-os <windows|osx|mac|ios|android>`, the `MUC_DEFAULT_OS` env var, or the interactive prompt during `muc init`. Resolution order: per-call `--os` → `defaultChatOs` → built-in `iOS`. Use this when your real device is on the Mobile slot (e.g. iPhone) so chat-channel commands park on PC instead of kicking your phone.
+
+#### `0.3.0`
+`2026.04.29`
+- Add `muc react` / `muc unreact` / `muc reactions` to add, revoke, and list emoticon reactions on existing messages
+- Add `muc wait-react` to block until a human reacts to a given mid; useful as a "human-in-the-loop approval" gate after `muc send`
+- Add `muc listen`, a long-lived TCP tap with sender / chat / keyword / `--at-me` filters, one NDJSON line per match
+- Exit code `5` now also covers `TIMEOUT` and `KICKED`
+
+#### `0.2.2`
+`2026.04.28`
+- `muc send` plain-text now appends an idempotent signature tail by default; override via `--tail` / `--no-tail`, `muc init --message-tail`, or `messageTail` in `~/.muc/config.json`
+
+#### `0.2.1`
+`2026.04.28`
+- Skills unified across macOS / Linux / Windows
+- On Windows, file mode `600` is silently ignored — use NTFS ACLs on shared hosts to protect `~/.muc/`
+
+#### `0.2.0`
+`2026.04.27`
+- Add `muc init`: extract `appKey` / `appId` / signing secrets out of source code, write to `~/.muc/config.json` (mode 600)
+- Companion subcommands: `muc init --check` / `--show` / `--reset`
+- License changed to MIT; package published to npm with public access
+
 ## What it can't do (yet)
 
 - **Richtext messages** (`subType=11`, mixed text + image + @-mention in one
@@ -360,8 +404,6 @@ first use; you should never need to edit them by hand.
 - **Forwarded / merged messages** (`subType=26`).
 - **SSO / scan-to-login.** REST username+password works; the SSO flow is
   not wired up.
-- **Live push streaming.** Use `muc history` for server-side message
-  retrieval; there is no long-lived `talk/msg` listener wired up.
 - **Image thumbnails.** The upload step asks the server to make `tn1`/`tn5`
   thumbs, but `muc download` only fetches the original `fileKey`.
 - **End-to-end-encrypted file content.** Not active on the default tenant
@@ -404,7 +446,7 @@ first use; you should never need to edit them by hand.
 | 2 | USAGE |
 | 3 | AUTH_REQUIRED, AUTH_EXPIRED |
 | 4 | NOT_FOUND |
-| 5 | REMOTE_ERROR, NETWORK |
+| 5 | REMOTE_ERROR, NETWORK, TIMEOUT, KICKED |
 | 6 | CONFIG_MISSING |
 | 7 | CONFIG_INVALID |