@agent-wechat/cli 0.16.0 → 1.0.0-beta.2

package/README.md

@@ -1,214 +1,90 @@
 # @agent-wechat/cli
 
-Command-line tool for managing agent-wechat containers and interacting with WeChat.
+`wx` is the native Rust client and foreground daemon. The npm package installs a matching release executable; it does not implement the native protocol in JavaScript. The supported distribution targets are Linux x64 and ARM64 with glibc 2.36+. macOS, Windows and musl do not have a native release. Clients on other systems can use the HTTP API of a supported Linux daemon. `wx --json version` and `/v1/status` expose the runtime and account capabilities; unsupported official schemas fail explicitly.
 
-**[Documentation](https://thisnick.github.io/agent-wechat/getting-started/cli/commands/)**
+## Installation
 
-## Install
+After a matching release has been published:
 
 ```bash
-npm install -g @agent-wechat/cli
+npm install -g @agent-wechat/cli@VERSION
+wx --json version
 ```
 
-This installs the `wx` command globally.
+During the native beta series, use a published exact version such as `1.0.0-beta.0`, or `@agent-wechat/cli@beta`. The stable `latest` channel retains the old container CLI until promotion. See the beta release instructions before assuming a beta has been published.
 
-## Prerequisites
+The explicit npm installation downloads one exact-version asset over verified HTTPS. Its size and SHA-256 must match `native-release.json` inside the npm package, then a bounded local identity check must report the same version, native backend, Rust target and serve capability before atomic installation. Normal command invocation never downloads a missing runtime. A missing manifest, unsupported platform, corrupt asset or wrong backend is an error.
 
-- [Docker](https://docs.docker.com/get-docker/) installed and running
-
-`wx up` automatically pulls the Docker image from ghcr.io if it isn't found locally.
-
-> **Note:** agent-wechat requires `SYS_PTRACE` and `seccomp=unconfined` to interact with the WeChat desktop process. It cannot run in serverless or restricted container environments (AWS Fargate, Cloud Run, etc.). Use a VM or bare-metal Docker host.
-
-## Quick Start
+Installers that disable lifecycle scripts are supported:
 
 ```bash
-# Start the container
-wx up
-
-# Check status
-wx status
-
-# Log in (displays QR code in terminal)
-wx auth login
-
-# List chats
-wx chats list
-
-# Send a message
-wx messages send <chatId> --text "Hello"
+npm install -g --ignore-scripts @agent-wechat/cli@VERSION
+wx-native-install
 ```
 
-## Commands
-
-### Container
-
-| Command | Description |
-|---------|-------------|
-| `wx up [--proxy user:pass@host:port]` | Start the agent-wechat container |
-| `wx down` | Stop and remove the container |
-| `wx logs` | Tail container logs |
-| `wx status` | Show container up/down status and login status (when available) |
-
-### Auth
-
-| Command | Description |
-|---------|-------------|
-| `wx auth login` | Log in to WeChat (shows QR code) |
-| `wx auth logout` | Log out of WeChat |
-| `wx auth status` | Check login status |
-| `wx auth token` | Show current auth token |
-| `wx auth token --regenerate` | Generate a new auth token |
-
-Login options:
-- `--timeout <seconds>` — login timeout (default: 300)
-- `--new` — switch to a new account instead of existing
-
-### Chats
-
-| Command | Description |
-|---------|-------------|
-| `wx chats list` | List chats from WeChat |
-| `wx chats get <chatId>` | Get details for a specific chat |
-| `wx chats find <name>` | Search chats by display name |
-| `wx chats open <chatId>` | Open a chat in the WeChat UI |
-
-Options: `--limit <n>`, `--offset <n>`, `--json`
-
-### Messages
-
-| Command | Description |
-|---------|-------------|
-| `wx messages list <chatId>` | List messages in a chat |
-| `wx messages send <chatId>` | Send a message |
-| `wx messages media <chatId> <localId>` | Download a media attachment |
-
-Send options:
-- `--text "message"` — send text
-- `--image photo.jpg` — send an image
-- `--file document.pdf` — send a file
+For offline deployment, provision the release binary and its `wx-vVERSION-checksums.json` into one local directory, then run:
 
-Media options:
-- `--output <path>` — save to a specific file path
-- `--full` — require an original-resolution image
-- `--thumbnail` — save the cached preview
-- `--best` — explicitly choose the default best-available image behavior
-
-Media retrieval does not open a chat. Use `wx chats open <chatId>` separately
-if WeChat needs to cache a regular photo's standard-size copy.
-
-### Sessions
-
-| Command | Description |
-|---------|-------------|
-| `wx session list` | List all sessions |
-| `wx session create <name>` | Create a new session |
-| `wx session start <id>` | Start a session |
-| `wx session stop <id>` | Stop a session |
-| `wx session delete <id>` | Delete a session |
-
-### Debug
-
-| Command | Description |
-|---------|-------------|
-| `wx screenshot [file]` | Save a screenshot (default: screenshot.png) |
-| `wx a11y` | Dump the accessibility tree (`--format json|aria`) |
-
-## Global Options
-
-| Option | Description |
-|--------|-------------|
-| `-s, --session <name>` | Use a specific session (default: "default") |
-| `-V, --version` | Show version |
-| `-h, --help` | Show help |
-
-## Configuration
-
-The CLI reads configuration from environment variables and a local token file:
-
-| Source | Description |
-|--------|-------------|
-| `AGENT_WECHAT_URL` | Server URL (default: `http://localhost:6174`) |
-| `AGENT_WECHAT_TOKEN` | Auth token (overrides token file) |
-| `~/.config/agent-wechat/token` | Auto-generated auth token |
+```bash
+AGENT_WECHAT_NATIVE_ARTIFACT_DIR=/absolute/release-assets wx-native-install
+```
 
-The auth token is generated automatically on first run and shared with the container via a read-only volume mount.
+The offline manifest must agree with the npm-bundled manifest. Alternatively, provision a trusted executable yourself and set `AGENT_WECHAT_NATIVE_BINARY=/absolute/path/to/wx`; the launcher verifies its native identity/version rather than downloading. This explicit override trusts the operator-provisioned bytes and does not assert they are identical to a release asset. `AGENT_WECHAT_SKIP_NATIVE_INSTALL=1` defers installation during image/package provisioning; commands remain unavailable until the runtime is provided. Do not disable TLS verification.
 
-## Running the Container
+The OpenClaw plugin uses an already installed global native `wx` or a configured absolute executable. It never downloads binaries or relies on its plugin installer running npm lifecycle scripts. For managed processes, prefer the actual release executable path to avoid an extra launcher process; the npm launcher also forwards arguments, standard streams, exit codes and termination signals.
 
-There are two ways to run the agent-wechat container.
+## Configuration and storage
 
-> **Note:** agent-wechat requires `SYS_PTRACE` and `seccomp=unconfined` because it uses ptrace to interact with the WeChat desktop process. It cannot run in serverless or restricted container environments (AWS Fargate, Cloud Run, Azure Container Instances, etc.). Use a VM or bare-metal Docker host.
+```bash
+wx config show
+wx serve --server-config /absolute/server/config.toml
+```
 
-### Option 1: `wx up` (local development)
+The default server configuration is `$XDG_CONFIG_HOME/agent-wechat/server/config.toml`, or `~/.config/agent-wechat/server/config.toml`. The durable root defaults to `$XDG_DATA_HOME/agent-wechat`, or `~/.local/share/agent-wechat`. `wx serve --data-dir PATH` and `AGENT_WECHAT_DATA_DIR` override it. Server config can select `listen`, `dataDir` and `tokenFile`; relative references resolve against the config file. Paths are not credentials.
 
-The simplest way. `wx up` pulls/starts the container with the right flags, volume mounts, and auth token:
+The initial workflow takes over an existing official profile in place. Close the official app, start `wx serve`, then use a second terminal:
 
 ```bash
-wx up
+wx auth login --official
+# Or choose a specific path on the daemon host:
+wx auth login --official=/absolute/official-profile
 ```
 
-This starts a container named `agent-wechat` with:
-- **Port 6174** — REST API + VNC web viewer at `/vnc/` (exposed to all interfaces)
-- Persistent volumes for data and WeChat home directory
-- Auth token from `~/.config/agent-wechat/token` (auto-generated on first run)
+The daemon binds the stored identity, attempts saved-device login and derives verified database keys after authentication. The official app stays closed while this daemon owns the files.
 
-To route all container traffic through a proxy:
+Lower-level registration and experimental profile copies are also available:
 
 ```bash
-wx up --proxy user:pass@host:port
+# Only use an explicitly stopped/quiescent profile; never share a writer.
+wx store attach --account example --path /absolute/official-profile --source-stopped
+wx store import --account copied --source /absolute/stopped-profile --source-stopped
+wx store export --account copied --destination /absolute/new-export --source-stopped
 ```
 
-This sets up a transparent proxy (redsocks + iptables) inside the container — invisible to WeChat. Prefix with `socks5://` for SOCKS5 proxies.
-
-### Option 2: Docker Compose (production / networked)
-
-For production or when running alongside other services (e.g., OpenClaw), use the `docker-compose.yml` in the repo root as a reference:
-
-```yaml
-services:
-  agent-wechat:
-    image: ghcr.io/thisnick/agent-wechat:latest
-    container_name: agent-wechat
-    security_opt:
-      - seccomp=unconfined
-    cap_add:
-      - SYS_PTRACE
-      - NET_ADMIN
-    ports:
-      - "6174:6174"
-    volumes:
-      - agent-wechat-data:/data
-      - agent-wechat-home:/home/wechat
-      - ~/.config/agent-wechat/token:/data/auth-token:ro
-    environment:
-      - PROXY=${PROXY:-}    # optional: user:pass@host:port
-    restart: unless-stopped
-
-volumes:
-  agent-wechat-data:
-  agent-wechat-home:
-```
+Direct mode keeps official profile bytes at the selected path and daemon-only state under `dataDir`. Fresh creation, export and returning files to the official app are outside the initial supported takeover scope. Import/export copy the same format; they do not convert schema or refresh login trust. Use `--help` for the implemented command surface. Never copy or attach a running production profile implicitly.
+
+## Build and validate without deployment
 
-Generate a token before starting:
+From the repository root:
 
 ```bash
-mkdir -p ~/.config/agent-wechat
-openssl rand -hex 32 > ~/.config/agent-wechat/token
-chmod 600 ~/.config/agent-wechat/token
+pnpm --filter @agent-wechat/cli... build
+pnpm --filter @agent-wechat/cli test
+pnpm native:build
+pnpm native:test
+pnpm native:release:build
+node scripts/native-package-smoke.mjs artifacts/native
+# Substitute the exact artifact version emitted by the build:
+python3 scripts/native-cli-smoke.py artifacts/native/wx-vVERSION-linux-x64-gnu
+python3 scripts/native-cli-fixture-test.py artifacts/native/wx-vVERSION-linux-x64-gnu
+python3 scripts/native-export-smoke.py artifacts/native/wx-vVERSION-linux-x64-gnu
 ```
 
-If running alongside OpenClaw on the same Docker network, set `serverUrl` to `http://agent-wechat:6174` in your OpenClaw config.
+Source-workspace postinstall defers release installation; run the Rust binary from its target directory or use an explicit trusted executable override. The local release builder tests the Rust workspace, verifies executable identity and creates versioned assets; it does not publish, deploy or log an account in. The package smoke test packs/unpacks an actual npm tarball and installs from local artifacts into a temporary directory.
 
-### Building locally
+Deployment examples and the deliberate release preparation sequence are in [deploy/native](../../deploy/native/README.md). The previous container CLI and Wechaty packages are retired; see the [migration guide](../../docs/src/content/docs/getting-started/migration.mdx).
 
-To build the Docker image from source instead of pulling from ghcr.io:
+## Package helper scripts
 
-```bash
-# From the repo root — auto-detects host architecture
-pnpm build:image
+`native-install.mjs` runs during npm installation, or through `wx-native-install` for offline/disabled-script installs. It selects the host architecture, checks the npm-bundled hash and verifies executable identity before atomic installation. `native-launcher.mjs` only runs an already installed executable.
 
-# Or specify architecture
-pnpm build:image:arm64
-pnpm build:image:amd64
-```
+`native-check-package.mjs` is the prepack/prepublish gate. It checks version/source/target/checksum metadata; before publication it additionally requires both architecture assets to exist and match the package's manifest. A local pack smoke can use one architecture fragment; publication requires the complete matrix. These helpers belong to the existing CLI package, not additional npm packages.

package/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,82 @@
+Native wx third-party notices
+
+NOTICE
+
+The AES-GCM known-answer fixture in src/mmtls.rs is reproduced from
+code/outer.py in Citizen Lab's wechat-security-report repository:
+https://github.com/citizenlab/wechat-security-report
+
+Copyright (c) 2025 Mona Wang
+Used under the MIT License; see fixtures/LICENSE-CITIZENLAB.
+
+The public MMTLS verification pins and business ECDH/signature pins are public
+protocol constants from the Linux 4.1.13.26 default configuration. They are not
+account credentials. Reference artifact SHA-256:
+2749535f299ba67feb8ef80cab898bb0531fa8f376b16f8a72db706811c84132
+
+Other test vectors contain synthetic inputs, RFC 5869 test-case 1 data, or
+independently generated Python cryptography/zlib ciphertext. No private capture,
+account identity, token, device state, message, or runtime executable is shipped.
+
+The portable SILK SDK sources under vendor/silk are from kn007/silk-v3-decoder,
+pinned commit 507be6bca8ce1fb977a061481f1d79e8c610e309:
+https://github.com/kn007/silk-v3-decoder
+
+The wrapper project is MIT licensed; the SILK SDK sources retain their Skype
+BSD-style notices. Full license text and an allowlist of SHA-256 source hashes
+are in vendor/silk/LICENSE-MIT, LICENSE-SDK and SOURCE.json. Only portable C and
+headers are included. No codec binary from the official client is loaded.
+
+
+vendor/silk/LICENSE-MIT
+
+The MIT License (MIT)
+
+Copyright (c) 2020 Karl Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+vendor/silk/LICENSE-SDK
+
+Copyright (c) 2006-2012, Skype Limited. All rights reserved. 
+Redistribution and use in source and binary forms, with or without 
+modification, (subject to the limitations in the disclaimer below) 
+are permitted provided that the following conditions are met:
+- Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+- Redistributions in binary form must reproduce the above copyright 
+notice, this list of conditions and the following disclaimer in the 
+documentation and/or other materials provided with the distribution.
+- Neither the name of Skype Limited, nor the names of specific 
+contributors, may be used to endorse or promote products derived from 
+this software without specific prior written permission.
+NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED 
+BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 
+CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
+COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 
+USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

package/native-release.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "version": "1.0.0-beta.2",
+  "repository": "thisnick/agent-wechat",
+  "sourceCommit": "63c7ce5bac1dade4ee11f2e7c6364a733724c117",
+  "sourceTreeDirty": false,
+  "assets": [
+    {
+      "name": "wx-v1.0.0-beta.2-linux-arm64-gnu",
+      "platform": "linux",
+      "arch": "arm64",
+      "libc": "gnu",
+      "minimumGlibc": "2.36",
+      "rustTarget": "aarch64-unknown-linux-gnu",
+      "bytes": 26300152,
+      "sha256": "6fff9ad299be969a24ce7dbce409a29ce86fa2abc2de4f93fef5222ce9cfae77"
+    },
+    {
+      "name": "wx-v1.0.0-beta.2-linux-x64-gnu",
+      "platform": "linux",
+      "arch": "x64",
+      "libc": "gnu",
+      "minimumGlibc": "2.36",
+      "rustTarget": "x86_64-unknown-linux-gnu",
+      "bytes": 27987976,
+      "sha256": "2b9de3ad043868b084bfac64fe01a5dd039b1aaae5eb1499c438bd65983cddc2"
+    }
+  ]
+}

package/package.json

@@ -1,24 +1,16 @@
 {
   "name": "@agent-wechat/cli",
-  "version": "0.16.0",
+  "version": "1.0.0-beta.2",
   "type": "module",
   "bin": {
-    "wx": "./dist/cli.js"
+    "wx": "./scripts/native-launcher.mjs",
+    "wx-native-install": "./scripts/native-install.mjs"
   },
   "files": [
-    "dist"
+    "scripts",
+    "native-release.json",
+    "THIRD_PARTY_NOTICES.txt"
   ],
-  "dependencies": {
-    "qrcode-terminal": "^0.12.0"
-  },
-  "devDependencies": {
-    "commander": "^14.0.3",
-    "esbuild": "^0.25.0",
-    "@types/node": "^22",
-    "@types/qrcode-terminal": "^0.12.2",
-    "typescript": "^5.4.5",
-    "@agent-wechat/shared": "0.3.1"
-  },
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -28,9 +20,14 @@
     "url": "git+https://github.com/thisnick/agent-wechat.git",
     "directory": "packages/cli"
   },
+  "engines": {
+    "node": ">=24.16"
+  },
+  "description": "Standalone native WeChat CLI and daemon launcher",
   "scripts": {
     "build": "node build.js",
-    "typecheck": "tsc --noEmit",
-    "test": "node --test --experimental-strip-types src/lib/*.test.mjs"
+    "typecheck": "node build.js",
+    "test": "node --test test/*.test.mjs",
+    "postinstall": "node scripts/native-install.mjs --postinstall"
   }
 }

package/scripts/native-check-package.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// prepack checks bundled metadata; prepublishOnly additionally verifies the
+// complete, already published executable matrix before npm can be published.
+import { fetchBytes, manifestName, readManifest, releaseUrl, validateManifest, verifyBytes } from './native-runtime.mjs';
+const { manifest, asset } = await readManifest();
+if (process.env.GITHUB_SHA && manifest.sourceCommit !== process.env.GITHUB_SHA) throw new Error('Native manifest source commit differs from publication commit');
+if (process.argv.includes('--publication')) {
+  if (manifest.sourceTreeDirty === true) throw new Error('Dirty local validation artifacts cannot be published');
+  // Manual npm publication must enforce the same asset-before-package ordering
+  // as the normal release workflow; local pack/offline smoke does not fetch.
+  const remote = JSON.parse(await fetchBytes(releaseUrl(manifest.version, manifestName(manifest.version)), 65536));
+  validateManifest(manifest, manifest.version, { requireAllTargets: true });
+  validateManifest(remote, manifest.version, { requireAllTargets: true });
+  if (remote.sourceCommit !== manifest.sourceCommit || remote.sourceTreeDirty === true) throw new Error('Prepared release differs from this npm package');
+  for (const item of manifest.assets) {
+    const published = remote.assets.find(candidate => candidate.arch === item.arch);
+    if (published.sha256 !== item.sha256 || published.bytes !== item.bytes) throw new Error('Prepared release differs from this npm package');
+    verifyBytes(await fetchBytes(releaseUrl(manifest.version, item.name), item.bytes), item);
+  }
+}
+console.error(`Verified bundled native release manifest for ${manifest.version}.`);

package/scripts/native-install.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// npm postinstall (or explicit offline provisioning) installs a verified runtime.
+// The wx launcher only runs an already installed executable; it never downloads.
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { installNative, packageRoot, resolveNative } from './native-runtime.mjs';
+try {
+  if (process.env.AGENT_WECHAT_SKIP_NATIVE_INSTALL === '1') {
+    console.error('Native installation skipped explicitly; provision wx before use.');
+  } else {
+    let workspace = false;
+    try { await access(join(packageRoot, '../../pnpm-workspace.yaml')); workspace = true; } catch {}
+    if (workspace && process.argv.includes('--postinstall')) {
+      console.error('Source workspace: native release installation deferred. Build Rust wx explicitly.');
+    } else if (process.env.AGENT_WECHAT_NATIVE_BINARY) {
+      console.error(`Verified separately provisioned native runtime: ${await resolveNative()}`);
+    } else {
+      console.error(`Installed native runtime: ${await installNative({ artifactDir: process.env.AGENT_WECHAT_NATIVE_ARTIFACT_DIR })}`);
+    }
+  }
+} catch (error) { console.error(error.message); process.exitCode = 1; }

package/scripts/native-launcher.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { resolveNative, runNative } from './native-runtime.mjs';
+try { runNative(await resolveNative(), process.argv.slice(2)); }
+catch (error) { console.error(error.message); process.exitCode = 1; }