tmailcli 0.0.0-stage → 0.1.4

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# tmailcli npm 包
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+这个 npm 包内置 `tmailcli` Go 二进制，支持 Windows x64、macOS arm64 和
+Linux x64。安装时由 npm 生命周期脚本选择当前平台的二进制，不需要访问
+公共二进制镜像。
+
+## 安装
+
+需要 Node.js 18+。从私有源安装已发布的包：
+
+```sh
+npm install --global tmailcli --registry https://nexus.tul.cn/repository/npm-releases/
+tmailcli --version
+tmailcli --help
+```
+
+从私有源安装无需 npm 认证。官方源版本经维护者批准上线后，也可以使用：
+
+```sh
+npm install --global tmailcli --registry https://registry.npmjs.org/
+```
+
+## 正式默认配置
+
+- 授权平台：`https://ai.tul.cn/tmail/`
+- U-Mail API：`https://mail.tul.com.cn/api/v1`
+- OAuth 客户端 ID：`tmailcli`
+
+环境变量名称和默认客户端 ID：
+
+```sh
+export TMAILCLI_PLATFORM_URL="https://ai.tul.cn/tmail/"
+export TMAILCLI_URL="https://mail.tul.com.cn/api/v1"
+export TMAILCLI_CLIENT_ID="tmailcli"
+```
+
+如需绑定或解绑邮箱，或查看中转平台侧的邮箱绑定情况，请替用户打开中转平台：
+<https://ai.tul.cn/tmail/>。CLI 授权命令管理本机客户端授权记录，不替代中转平台的绑定页面。
+必须使用用户本机的操作系统默认浏览器，不使用 agent 内置浏览器、网页工具或远程浏览器。
+
+## 多邮箱授权
+
+```sh
+tmailcli auth add
+tmailcli auth ls
+tmailcli auth su work@example.com
+tmailcli auth whoami
+tmailcli auth status
+tmailcli --account work@example.com msg ls
+tmailcli auth rm work@example.com
+```
+
+`auth add` 通过浏览器授权添加邮箱并切为当前邮箱；同一地址再次授权会更新
+凭据。`auth ls` 标记当前邮箱，`auth su <addr>` 持久切换，`auth whoami`
+输出生效邮箱 JSON，`auth status` 查看详细授权状态。
+`--account <addr>` 临时指定邮件命令、`auth status` 或 `auth whoami` 使用的
+邮箱。`auth rm <addr>` 撤销远端授权并删除本地凭据；删除当前邮箱后需
+重新选择。升级后运行 `auth add` 重新添加邮箱，旧单邮箱凭据保留在原存储中。
+
+使用 `auth --help` 查看授权命令。旧裸 `auth`、`auth login`、`auth logout`
+以及 `TMAILCLI_PROFILE`、`UMAIL_PROFILE` 已弃用；选择邮箱使用 `auth su`
+或 `--account`。
+
+## 源码构建与发布
+
+构建和发布需要完整源码仓库，操作步骤见源码仓库根目录的 `README.md`，
+其中包含私有源发布和官方源 staged publishing 的手动流程。
+源码仓库中的 `npm/` 是分发包目录；打包脚本位于仓库根目录的 `scripts/`。
+
+## Skill 安装
+
+调用方 agent 必须按本节指令安装 `tmailcli` skill，并在使用 CLI 前读取安装后的
+`tmailcli/SKILL.md`。只安装 npm 二进制而跳过 skill 安装是不完整的集成。
+
+`postinstall` 会调用内置 CLI 安装 `tmailcli` skill，过程无需联网。
+建议调用方 agent 显式传入自己的 skills 根目录：
+
+```sh
+tmailcli install-skill --dir /path/to/agent/skills
+```
+
+skill 写入该目录下的 `tmailcli/`。目录优先使用 `--dir`，其次使用
+`TMAILCLI_SKILLS_DIR`；默认安装到 `~/.agents/skills` 及已检测到的
+Claude、OpenClaw skills 目录，并遵循显式配置的 `CODEX_HOME`。
+
+npm 安装时可设置 `TMAILCLI_SKILLS_DIR` 指定目录，或设置
+`TMAILCLI_SKIP_SKILLS=1` 跳过 skill 安装。使用 `npm --ignore-scripts` 后，
+可运行上述命令补装。skill 安装失败会使 `postinstall` 失败；按报错修复
+目录权限或指定可写目录后，重新安装 npm 包或手动补装即可。

package/bin/tmailcli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const targets = {
+  'win32-x64': 'win32-x64/tmailcli.exe',
+  'darwin-arm64': 'darwin-arm64/tmailcli',
+  'linux-x64': 'linux-x64/tmailcli',
+};
+
+const target = targets[`${process.platform}-${process.arch}`];
+if (!target) {
+  console.error(`tmailcli does not provide a binary for ${process.platform}/${process.arch}`);
+  process.exit(1);
+}
+
+const executable = path.join(__dirname, target);
+if (!fs.existsSync(executable)) {
+  console.error(`The tmailcli package is missing its ${process.platform}/${process.arch} binary.`);
+  console.error('Reinstall tmailcli from your npm registry for this platform.');
+  process.exit(1);
+}
+
+const result = spawnSync(executable, process.argv.slice(2), { stdio: 'inherit' });
+if (result.error) {
+  console.error(`Cannot start tmailcli: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "tmailcli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "description": "Command-line client for U-Mail",
+  "bin": {
+    "tmailcli": "bin/tmailcli.js"
+  },
+  "files": [
+    "bin",
+    "scripts/install.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://nexus.tul.cn/repository/npm-releases/"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,34 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const target = `${process.platform}-${process.arch}`;
+const files = {
+  'win32-x64': 'win32-x64/tmailcli.exe',
+  'darwin-arm64': 'darwin-arm64/tmailcli',
+  'linux-x64': 'linux-x64/tmailcli',
+};
+const relativePath = files[target];
+
+if (!relativePath) {
+  throw new Error(`tmailcli does not provide a binary for ${process.platform}/${process.arch}`);
+}
+
+const executable = path.join(__dirname, '..', 'bin', relativePath);
+if (!fs.existsSync(executable)) {
+  throw new Error(`The tmailcli package is missing its ${target} binary`);
+}
+
+if (process.platform !== 'win32') {
+  fs.chmodSync(executable, 0o755);
+}
+
+if (process.env.TMAILCLI_SKIP_SKILLS !== '1') {
+  const result = spawnSync(executable, ['install-skill'], { stdio: 'inherit' });
+  if (result.error || result.status !== 0) {
+    console.error(`Cannot install tmailcli skills: ${result.error ? result.error.message : `exit code ${result.status}`}`);
+    console.error('Retry with tmailcli install-skill --dir <your-agent-skills-directory>.');
+    console.error('Set TMAILCLI_SKIP_SKILLS=1 to install the npm package without skills.');
+    process.exit(result.status || 1);
+  }
+}