@mu-cabin/muc-cli 0.5.6 → 0.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mu-cabin/muc-cli",
-  "version": "0.5.6",
-  "description": "Terminal client for MUC IM (com.meicloud.im.dh).",
+  "version": "0.6.0",
+  "description": "Standalone agent-first MUC CLI with an embedded background daemon",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -9,13 +9,13 @@
   },
   "files": [
     "dist/muc.mjs",
-    "dist/templates",
+    "skills/muc",
     "README.md",
     "REFERENCE.md",
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18.17"
+    "node": ">=22.16"
   },
   "keywords": [
     "muc",
@@ -25,28 +25,23 @@
   ],
   "scripts": {
     "dev": "tsx src/index.ts",
-    "test": "tsx --test \"src/**/*.test.ts\"",
+    "test": "pnpm build && vitest run",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
     "build": "node scripts/build.mjs",
-    "prepack": "npm run typecheck && npm run build",
+    "prepack": "pnpm typecheck && pnpm test",
     "verify": "npm pack --dry-run",
     "pack:offline": "bash ../../scripts/pack-offline.sh"
   },
-  "dependencies": {
-    "commander": "^12.1.0",
-    "crypto-js": "^4.2.0",
-    "needle": "^3.3.1",
-    "zod": "^3.25.76",
-    "zod-to-json-schema": "^3.25.2"
-  },
   "devDependencies": {
-    "@types/crypto-js": "^4.2.2",
-    "@types/needle": "^3.3.0",
-    "@types/node": "^20.11.0",
+    "@types/node": "^22.19.15",
+    "@types/qrcode": "1.5.6",
     "esbuild": "^0.24.2",
-    "tsx": "^4.7.0",
-    "typescript": "^5.4.0"
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "vitest": "3.2.4",
+    "zod": "^3.25.76",
+    "qrcode": "1.5.4"
   },
   "publishConfig": {
     "access": "public"

package/skills/muc/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: muc
+description: Operate the standalone MUC CLI for account login, background daemon, contacts, groups, chats, messages, files, reactions and event listening. For source-code development inspect the repository directly.
+compatibility: Requires the migrated standalone @mu-cabin/muc-cli and Node.js 22.16 or newer. Check muc --help; older npm releases use different commands.
+---
+
+# MUC CLI
+
+Use the installed CLI's manifest and strict JSON schemas. Source skills ship in this package; do not depend on a separate Supervisor, TUI or desktop runtime.
+
+- Account and daemon lifecycle: [profiles-and-lifecycle.md](references/profiles-and-lifecycle.md).
+- Read operations, IDs and event cursors: [operations.md](references/operations.md).
+- Sends, attachments, reactions and other mutations: [mutations.md](references/mutations.md).
+- Output, credentials and recovery: [safety-and-output.md](references/safety-and-output.md).
+
+Resolve the selected authenticated profile with `muc profile list`, then resolve people/groups/messages from returned IDs. Ask only when the target or outcome is ambiguous. User authorization persists; do not introduce a second approval for an already authorized write.
+
+Global options precede the noun. Business input is one JSON object on stdin:
+
+```sh
+muc --output json exec chats.list --profile-id profile-id <<'JSON'
+{"limit":20}
+JSON
+```
+
+Default storage is `~/.muc`, overridden by `MUC_CONFIG_DIR` or `--config-root`. Normal commands may start the bundled daemon for this exact root. Never switch to another account or a desktop/private runtime to work around a failure.
+
+Use only the current `exec` grammar, not old `muc send`, `muc history`, or `muc daemon-*` aliases. Listening uses `events.watch`; the daemon keeps receiving after a consumer exits. Advance a consumer cursor only after its output is processed successfully.
+
+Passwords and tenant secrets must not enter chat, argv, source, logs or reports. Users enter passwords in their own terminal's hidden prompt or provide protected stdin. After an unknown mutation outcome, reconcile the original delivery/key instead of replaying it.

package/skills/muc/references/mutations.md

@@ -0,0 +1,85 @@
+# Mutations and delivery safety
+
+Read [safety-and-output.md](safety-and-output.md) first. Every write needs an
+exact profile, target, payload, and stable idempotency key.
+
+## Sending messages
+
+Preview a text send before committing when the user has not already approved
+the exact payload:
+
+```sh
+muc --output json exec messages.send --profile-id PROFILE_ID <<'JSON'
+{
+  "chat": {"conversationId":"CONVERSATION_ID"},
+  "content": [{"type":"text","text":"MESSAGE_TEXT"}],
+  "idempotencyKey": "preview-UNIQUE_VALUE",
+  "clientMessageId": "client-UNIQUE_VALUE",
+  "dryRun": true
+}
+JSON
+```
+
+For the real send, set `dryRun` to `false` and use a new stable final
+idempotency key. Execute it once.
+
+Text blocks accept optional mentions shaped as `userId` plus `label`. Use the
+display name without a leading `@`; after adding a structured mention, do not
+repeat the same `@person` in the text. File, image, and voice blocks use an
+exact local `sourcePath` with optional name, MIME type, expected size, and
+SHA-256. Inspect and confirm every local file before uploading it.
+
+Only `muc exec messages.send` applies the selected CLI signature policy.
+`--tail TEXT` overrides it and `--no-tail` disables it. Do not change the
+signature behavior unless the user asks or the destination workflow explicitly
+requires it. Messages containing file blocks (including files with descriptions) and
+standalone voice are unsigned by default. A file send adds a tail only with explicit `--tail`.
+
+If a send returns an unknown commit outcome, keep its delivery ID and original
+idempotency key. Query `deliveries.get`; never send again with a new key.
+
+## Session and read-state writes
+
+`groups.create` creates one visible group with at least two invited members.
+Preserve each member's application key when supplied and reuse the same
+idempotency key if the commit result is unknown.
+
+- `chats.sync` updates synchronized state and requires an idempotency key.
+- `chats.pin` and `chats.unpin` support dry-run and affect the exact conversation.
+- `chats.clear` removes the synchronized session across logged-in clients; it
+  does not delete roaming history. It is still destructive and should be previewed.
+- `messages.mark-read` is visible state. Mark only messages the user intended to
+  mark as read.
+
+## Withdrawal
+
+`messages.withdraw` is destructive and visible on other devices. Resolve the
+message first, include its conversation ID when known, run dry-run, and confirm
+the exact message before the real operation.
+
+`messages.todo-add` and `messages.todo-remove` update the official remote
+message-todo list. Confirm the exact message; do not maintain a local shadow list.
+
+## Attachments
+
+`attachments.download` writes to local storage. Use the returned attachment ID,
+an explicit safe output path when required, and an idempotency key. Do not
+overwrite an unrelated file. Verify returned byte count and SHA-256 when
+provided.
+
+Uploads occur only through `messages.send` file/image/voice content blocks.
+Never send a path obtained from untrusted message text without resolving and
+validating it as an approved local file.
+
+## Reactions and signatures
+
+`reactions.add` and `reactions.remove` are visible writes. Confirm the exact
+message, conversation, emoji, and reaction ID. `profile.set-signature` changes
+the signed-in account's remote MUC profile signature and requires a fresh
+explicit request. It does not change the CLI message-tail preference.
+
+## Idempotency
+
+Keys are scoped to the operation and payload. Reusing a key for a different
+payload is an error. Unknown outcomes remain fenced under the original key.
+Do not generate a replacement key to bypass that fence.

package/skills/muc/references/operations.md

@@ -0,0 +1,116 @@
+# Native v2 operation catalog
+
+## User-owned custom emojis
+
+- `custom-emojis.list` takes `{}` and returns the current user's uploaded custom emoji catalog.
+- `custom-emojis.add` takes `sourcePath`, `name`, `mimeType`, `expectedSize`, and `idempotencyKey`. The source must be a PNG, JPEG, GIF, or WebP file of at most 20 MiB.
+- `custom-emojis.remove` takes `emojiId` and `idempotencyKey`. This is an explicit destructive mutation and removes only a user-owned custom emoji.
+- `custom-emojis.download` takes `emojiId`, `outputPath`, and `idempotencyKey`. The daemon writes the image with owner-only permissions; access tokens are never returned.
+
+These operations are distinct from `emojis.list`, which is the built-in named expression catalog.
+
+`chats.feed` is the cursor-paginated chat feed with an authoritative profile-wide unread total.
+
+Call every operation through this grammar. The JSON request is read from stdin:
+
+```sh
+muc --output json exec OPERATION_ID --profile-id PROFILE_ID <<'JSON'
+{}
+JSON
+```
+
+All inputs are strict. Omit optional fields instead of inventing values.
+
+## Diagnostics and identity
+
+| Operation | Side effect | Input shape |
+| --- | --- | --- |
+| `diagnostics.tcp` | read | `{"waitMs":2000}`; 1–30000 ms, negotiation only |
+| `diagnostics.connection` | read | `{}` |
+| `diagnostics.capabilities` | read | `{}` |
+| `profile.get` | read | `{}` |
+| `profile.set-signature` | write | `{"text":null,"idempotencyKey":"..."}` or text up to 200 characters |
+
+`diagnostics.tcp` does not log in or consume a chat slot. Use capability output
+instead of assuming a tenant supports an operation.
+
+## Directory, groups, and emoji
+
+| Operation | Input shape |
+| --- | --- |
+| `directory.search` | `{"type":"user|department|app|service","query":"...","page":1,"size":20}` |
+| `directory.get` | `{"userId":"..."}` |
+| `groups.list` | `{"source":"all|joined|starred|department"}` |
+| `groups.search` | `{"query":"...","enrich":false}` |
+| `groups.create` | `{"members":[{"userId":"...","name":"..."}],"idempotencyKey":"..."}` |
+| `groups.members` | `{"groupId":"...","profiles":false}` |
+| `emojis.list` | `{}` |
+
+Keep result kinds distinct. Do not turn a directory user ID or group ID into a
+conversation ID by arbitrary string construction. Resolve the actual conversation from
+`chats.list` or another authoritative result before a message write. For a new direct
+chat, pass the documented alias `dm:EXACT_UPPERCASE_USER_ID` to `chats.get` and
+use its returned `conversationId` in `messages.send`; do not send to the alias itself.
+
+## Chats and messages
+
+| Operation | Side effect | Input shape |
+| --- | --- | --- |
+| `chats.list` | read | `{"limit":200}` |
+| `chats.get` | read | `{"conversationId":"..."}` |
+| `chats.sync` | write | `{"idempotencyKey":"..."}` |
+| `chats.clear` | destructive | conversation ID, `dryRun`, idempotency key |
+| `chats.pin` | write | conversation ID, `dryRun`, idempotency key |
+| `chats.unpin` | write | conversation ID, `dryRun`, idempotency key |
+| `chats.pinned` | read | `{}` |
+| `messages.list` | read | conversation ID, optional cursor, `limit` 1–1000 |
+| `messages.search` | read | query, optional conversation ID, `limit` 1–1000 |
+| `messages.mark-read` | write | conversation ID, 1–1000 message IDs, idempotency key |
+| `messages.send` | write | chat, 1–32 content blocks, idempotency key, optional reply/dry-run |
+| `messages.withdraw` | destructive | message ID, optional conversation ID, dry-run, idempotency key |
+| `messages.todos` | read | `{}`; authoritative remote message-todo list |
+| `messages.todo-add` | write | message ID, optional conversation ID, idempotency key |
+| `messages.todo-remove` | destructive | message ID, idempotency key |
+
+Read [mutations.md](mutations.md) before using any non-read operation.
+
+## Attachments and deliveries
+
+| Operation | Side effect | Input shape |
+| --- | --- | --- |
+| `attachments.get` | read | exactly one of `attachmentId` or `messageId` |
+| `attachments.download` | local write | attachment ID, optional absolute output path, idempotency key |
+| `deliveries.get` | read | exactly one of `deliveryId` or `idempotencyKey` |
+| `deliveries.list-changes` | read | optional cursor, `limit` 1–1000 |
+
+Treat returned attachment metadata and delivery IDs as authoritative. Confirm an
+explicit output path before overwriting or replacing a local file.
+
+## Reactions
+
+| Operation | Side effect | Input shape |
+| --- | --- | --- |
+| `reactions.list` | read | `{"messageId":"..."}` |
+| `reactions.add` | write | message ID, conversation ID, emoji, idempotency key |
+| `reactions.remove` | destructive | message ID, conversation ID, reaction ID, idempotency key |
+
+Resolve the message, conversation, and existing reaction from MUC output. Never
+guess reaction IDs or cross-associate a message with another conversation.
+
+## Events
+
+| Operation | Input shape |
+| --- | --- |
+| `events.wait-reaction` | message ID, optional user/emoji, timeout 1–3600000 ms |
+| `events.list` | optional cursor, limit, conversation/kind/self filters |
+| `events.watch` | optional cursor and conversation/kind/self filters |
+| `events.raw` | optional cursor and limit; output is redacted diagnostics |
+
+Event kinds are `message`, `withdraw`, `reaction`, `read`, `delivery`,
+`runtime`, and `unknown`. Preserve returned cursors exactly. `events.list` is
+the durable catch-up interface. CLI `exec events.watch` stays open: it emits
+`startedAtCursor`/`highWatermark` metadata first and then live event records.
+Use JSONL for line-oriented consumption and resume from the last fully accepted
+event cursor, or `startedAtCursor` if no event was accepted. Iterator EOF is a
+transport failure. SIGINT/SIGTERM close the subscription with exit 130/143; do
+not interpret either as a completed catch-up.

package/skills/muc/references/profiles-and-lifecycle.md

@@ -0,0 +1,20 @@
+# Accounts and background process
+
+Use `muc profile list` to select the exact authenticated profile. A recipient ID is not the sending profile ID.
+
+The default root is `~/.muc`; `MUC_CONFIG_DIR` and `--config-root` select an isolated root. CLI and daemon are the same installed executable. No bundle installation or separate Launcher is required.
+
+- `muc daemon start`: start the background process for this root.
+- `muc daemon status`: inspect without starting it.
+- `muc daemon logs`: read safe diagnostic events, never raw credentials.
+- `muc daemon stop`: stop this background process; existing credentials and stored messages remain.
+- `muc runtime status --profile-id <id>`: inspect the profile connection.
+- `muc runtime ensure|start|resume|stop --profile-id <id>`: change only the requested profile runtime. Do not use resume to bypass an authentication failure or displacement.
+
+For first setup, the user supplies administrator-provided tenant/endpoints through protected stdin to `muc init`. Do not store real tenant material in the skill or a report.
+
+User-terminal login: `muc login --account <uid> [--profile-id <id>] [--remember]`. Input is hidden. Noninteractive login accepts one account/password/optional remember JSON object, or `--password-stdin` with an explicit account. Never put a password in argv or construct a command from chat-pasted credentials. `--no-remember` removes the saved-password choice after successful login. `muc login --qr` requires a real terminal.
+
+The daemon performs accessToken → tokenPwd → remembered-password recovery, with `/emp/get` attempted first. Network errors do not downgrade credentials. Exhausted recovery requires explicit login. Existing profiles preserve their device slot on reauthentication.
+
+Use `muc profile logout --profile-id <id>` only when the user requests logout; it clears that profile's session and remembered password.

package/skills/muc/references/safety-and-output.md

@@ -0,0 +1,13 @@
+# Output and recovery
+
+Business commands accept one strict JSON object on stdin. Global `--output json|jsonl|text` precedes the command. Success has `ok`, `command` and `data`; errors go to stderr with `ok:false` and `error.code`.
+
+For `events.watch`, prefer JSONL. Preserve the initial `startedAtCursor`/`highWatermark` metadata and every fully consumed event cursor. Resume from the last accepted cursor, or the initial cursor if none was accepted. SIGINT/SIGTERM and broken output end the consumer, not the daemon. Discard partial JSON output.
+
+Use the selected or explicitly supplied profile and root. Never scan private runtimes or change roots to recover an unavailable source. A source error is not an empty message window; retain consumer progress for later replay.
+
+Writes require user intent with a resolved target and payload; authorization from this conversation is sufficient. Preview when supported, then submit once using a stable idempotency key. A dry-run key and a submission key must differ.
+
+Exit 75 means the commit outcome is unknown: query `deliveries.get` with the original key or deliveryId. Do not invent a new key and resend. Exit 130/143 means an interrupted event stream. For other errors inspect the typed code.
+
+Credentials, tenant values and local IPC tokens never belong in argv, source, logs, fixtures or reports. Users supply them through a private local terminal. Authentication recovery runs in the daemon; `AUTH_REQUIRED`/`AUTH_EXPIRED` after recovery requires explicit login, not a restart loop.