vxtalent-hr-cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
-
-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.
+# vxTalent HR CLI
+
+Zero-dependency Node.js CLI that turns the remote `hr-tools` MCP into a local stdio MCP server for WorkBuddy, Qwen Work, and other MCP agents.
+
+## Requirements
+
+- Node.js 18.17+
+- Public OAuth client: `vxtalent-hr-cli`
+- Registered loopback redirect URI: `http://127.0.0.1/callback`
+- Remote MCP transport: Streamable HTTP (`MCP_TRANSPORT=streamable-http`)
+- The CLI package must be published to npm before `npx -y vxtalent-hr-cli` works outside this repository.
+
+## One-command Install
+
+```bash
+npx -y vxtalent-hr-cli install \
+  --issuer https://mcp.vxhcm.com \
+  --platform workbuddy \
+  --write \
+  --auth
+```
+
+The command writes this connector config:
+
+```json
+{
+  "mcpServers": {
+    "vxtalent-hr": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "vxtalent-hr-cli", "mcp"],
+      "env": {
+        "VXTALENT_ISSUER": "https://mcp.vxhcm.com",
+        "VXTALENT_MCP_URL": "https://mcp.vxhcm.com/mcp",
+        "VXTALENT_CLIENT_ID": "vxtalent-hr-cli"
+      }
+    }
+  }
+}
+```
+
+## Supported Platforms
+
+| Platform | Config path | `--platform` value |
+|---|---|---|
+| WorkBuddy | `~/.workbuddy/mcp.json` | `workbuddy` |
+| Qwen Work (千问办公) | `~/.qwen-work/mcp.json` | `qwen-work` |
+| Doubao Work (豆包工作) | `~/.doubao-work/mcp.json` | `doubao-work` |
+| Custom | (via `--config <path>`) | `custom` |
+
+## Commands
+
+```bash
+npx -y vxtalent-hr-cli auth --issuer https://mcp.vxhcm.com
+npx -y vxtalent-hr-cli status --issuer https://mcp.vxhcm.com
+npx -y vxtalent-hr-cli logout --issuer https://mcp.vxhcm.com
+npx -y vxtalent-hr-cli mcp --issuer https://mcp.vxhcm.com
+```
+
+The CLI uses Authorization Code + PKCE S256. Tokens are stored in `~/.vxtalent/auth.json`, and the access token is refreshed automatically five minutes before expiry.
+
+## Authorization & Logout
+
+The stdio bridge exposes two extra chat tools so end users do not need the
+terminal:
+
+- `auth_status` ? show whether this device is authorized and when the token expires.
+- `auth_logout` ? revoke the local token and delete `~/.vxtalent/auth.json`. After
+  logout the next tool call triggers a fresh browser authorization automatically.
+
+Automatic browser authorization is **on by default**: whenever the local token
+is missing or expired, the bridge opens the OAuth consent page. Pass
+`--no-auto-auth` to disable this and fail with a clear message instead.
+
+## Platform-Specific Quick Start
+
+### WorkBuddy
+
+```bash
+npx -y vxtalent-hr-cli install \
+  --issuer https://mcp.vxhcm.com \
+  --platform workbuddy \
+  --write --auth
+```
+
+### Qwen Work (千问办公)
+
+```bash
+npx -y vxtalent-hr-cli install \
+  --issuer https://mcp.vxhcm.com \
+  --platform qwen-work \
+  --write --auth
+```
+
+## Doubao Work (豆包工作)
+
+Doubao's "自定义连接器" dialog supports both STDIO and HTTP transports:
+
+- STDIO: 服务器名称 `vxtalent-hr`，传输类型 STDIO，命令填 `node`（或
+  `vxtalent-hr-cli`），参数填 `D:/.../cli/index.mjs mcp`（或 `mcp`），环境变量
+  填 `VXTALENT_ISSUER` / `VXTALENT_MCP_URL` / `VXTALENT_CLIENT_ID`。
+- HTTP: 传输类型 Streamable HTTP，地址填 `https://mcp.vxhcm.com/mcp`，
+  认证选 OAuth，scope 填 `hr:read`（与 WorkBuddy 同一路径，无需 CLI）。
+
+```bash
+node cli/index.mjs install --issuer https://mcp.vxhcm.com --platform doubao-work --write
+```

package/index.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { runAuth } from "./lib/auth.mjs";
+import { install } from "./lib/install.mjs";
+import { startMcpServer } from "./lib/mcp-server.mjs";
+import { clearTokens, loadTokens, revokeTokens } from "./lib/token-manager.mjs";
+import { resolveOptions } from "./lib/config.mjs";
+
+function printHelp() {
+  console.log(`vxTalent HR MCP CLI
+
+Usage:
+  vxtalent-hr-cli auth [options]              Login and authorize this device
+  vxtalent-hr-cli install [options]           Generate or write agent MCP config
+  vxtalent-hr-cli mcp [options]               Run as a stdio MCP bridge (spawned by an agent, not for direct terminal use)
+  vxtalent-hr-cli status [options]            Show authorization status
+  vxtalent-hr-cli logout [options]            Revoke and remove local tokens
+
+Options:
+  --issuer <url>       OAuth/API base URL, or VXTALENT_ISSUER
+  --mcp-url <url>      Remote MCP Streamable HTTP URL, or VXTALENT_MCP_URL
+  --client-id <id>     OAuth public client ID, or VXTALENT_CLIENT_ID
+  --scope <scopes>     OAuth scopes, default: hr:read
+  --platform <name>    workbuddy | qwen-work | doubao-work | custom
+  --config <path>      Agent MCP config path
+  --write              Write config instead of only printing it
+  --local              Use this local checkout instead of npx (for dev/testing)
+  --no-auto-auth       Disable automatic browser authorization when token is missing (default: on)
+  --auth               Start browser authorization after install
+  --help, -h           Show help
+
+Examples:
+  vxtalent-hr-cli install --issuer https://hr.example.com --platform workbuddy --write --auth
+  vxtalent-hr-cli mcp --issuer https://hr.example.com --mcp-url https://hr.example.com/mcp
+`);
+}
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const value = argv[i];
+    const next = argv[i + 1];
+    if (value === "--help" || value === "-h") {
+      args.help = true;
+    } else if (value === "--write") {
+      args.write = true;
+    } else if (value === "--auth") {
+      args.auth = true;
+    } else if (value.startsWith("--")) {
+      const key = value.slice(2);
+      if (next === undefined || next.startsWith("--")) {
+        args[key] = true;
+      } else {
+        args[key] = next;
+        i += 1;
+      }
+    } else {
+      args._.push(value);
+    }
+  }
+  return args;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const first = argv[0];
+  const command = first === "mcp" || argv.length === 0 ? "mcp" : first && !first.startsWith("--") ? first : "help";
+  const args = parseArgs(command === "mcp" ? argv.slice(first === "mcp" ? 1 : 0) : argv);
+
+  if (args.help || command === "help") {
+    printHelp();
+    return;
+  }
+
+  const options = resolveOptions(args);
+  if (command === "auth") {
+    await runAuth(options);
+  } else if (command === "install") {
+    await install(options, args);
+  } else if (command === "status") {
+    const tokens = loadTokens(options);
+    if (!tokens) {
+      console.log("Not authorized. Run: vxtalent-hr-cli auth --issuer <url>");
+      return;
+    }
+    const expiresAt = new Date(tokens.expires_at);
+    console.log(`Issuer: ${tokens.issuer}`);
+    console.log(`Client: ${tokens.client_id}`);
+    console.log(`Expires: ${expiresAt.toISOString()}`);
+    console.log(`Status: ${expiresAt.getTime() > Date.now() ? "valid" : "needs refresh"}`);
+  } else if (command === "logout") {
+    await revokeTokens(options);
+    clearTokens(options);
+    console.log("Local authorization removed.");
+  } else if (command === "mcp") {
+    await startMcpServer(options);
+  } else {
+    console.error(`Unknown command: ${command}`);
+    printHelp();
+    process.exitCode = 1;
+  }
+}
+
+main().catch((error) => {
+  console.error(`[vxtalent-hr-cli] ${error.message}`);
+  process.exit(1);
+});

package/lib/auth.mjs

@@ -0,0 +1,130 @@
+import crypto from "node:crypto";
+import http from "node:http";
+import { spawn } from "node:child_process";
+import { saveTokens } from "./token-manager.mjs";
+
+function randomBase64Url(size) {
+  return crypto.randomBytes(size).toString("base64url");
+}
+
+function createPkce() {
+  const verifier = randomBase64Url(48);
+  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+
+function openBrowser(url) {
+  return new Promise((resolve) => {
+    const platform = process.platform;
+    let child;
+    if (platform === "win32") {
+      // Keep the URL quoted: cmd interprets an unquoted & as a command separator,
+      // which truncates OAuth query parameters such as client_id and redirect_uri.
+      child = spawn("cmd.exe", ["/d", "/s", "/c", `start "" "${url}"`], {
+        detached: true,
+        stdio: "ignore",
+        windowsVerbatimArguments: true,
+      });
+    } else {
+      const command = platform === "darwin" ? "open" : "xdg-open";
+      child = spawn(command, [url], { detached: true, stdio: "ignore", shell: false });
+    }
+    child.once("error", () => resolve(false));
+    child.once("spawn", () => {
+      child.unref();
+      resolve(true);
+    });
+  });
+}
+
+function htmlPage(title, message) {
+  return `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><title>${title}</title>
+<style>body{margin:0;min-height:100vh;display:grid;place-items:center;background:#f3f6f8;color:#182230;font-family:"Segoe UI","Microsoft YaHei",sans-serif}main{width:min(420px,90vw);background:#fff;border:1px solid #dbe2ea;border-radius:8px;padding:28px}h1{font-size:22px;margin:0 0 10px}p{color:#65758a;line-height:1.6;margin:0}</style>
+</head><body><main><h1>${title}</h1><p>${message}</p></main></body></html>`;
+}
+
+async function exchangeCode(options, code, redirectUri, verifier) {
+  const response = await fetch(`${options.issuer}/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri,
+      client_id: options.clientId,
+      code_verifier: verifier,
+    }),
+    signal: AbortSignal.timeout(30000),
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(payload.error_description || `Token exchange failed (${response.status})`);
+  }
+  return payload;
+}
+
+export async function runAuth(options) {
+  const { verifier, challenge } = createPkce();
+  const state = randomBase64Url(24);
+
+  const server = http.createServer();
+  const callbackResult = new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.on("request", async (request, response) => {
+      const url = new URL(request.url || "/", "http://127.0.0.1");
+      if (url.pathname !== "/callback") {
+        response.writeHead(404).end();
+        return;
+      }
+      const code = url.searchParams.get("code") || "";
+      const returnedState = url.searchParams.get("state") || "";
+      const oauthError = url.searchParams.get("error") || "";
+      try {
+        if (oauthError) throw new Error(url.searchParams.get("error_description") || oauthError);
+        if (returnedState !== state) throw new Error("OAuth state mismatch");
+        if (!code) throw new Error("Authorization code is missing");
+        const tokens = await exchangeCode(options, code, redirectUri, verifier);
+        saveTokens(options, tokens);
+        response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        response.end(htmlPage("授权成功", "vxTalent HR 授权完成，可以关闭此页面。"));
+        resolve(tokens);
+      } catch (error) {
+        response.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+        response.end(htmlPage("授权失败", error.message));
+        reject(error);
+      } finally {
+        server.close();
+      }
+    });
+  });
+
+  await new Promise((resolve, reject) => server.listen(0, "127.0.0.1", resolve).once("error", reject));
+  const port = server.address().port;
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const authorizeUrl = new URL(`${options.issuer}/oauth/authorize`);
+  authorizeUrl.searchParams.set("response_type", "code");
+  authorizeUrl.searchParams.set("client_id", options.clientId);
+  authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+  authorizeUrl.searchParams.set("scope", options.scope);
+  authorizeUrl.searchParams.set("state", state);
+  authorizeUrl.searchParams.set("code_challenge", challenge);
+  authorizeUrl.searchParams.set("code_challenge_method", "S256");
+
+  const timeout = setTimeout(() => {
+    server.close();
+    reject(new Error("Authorization timed out after 5 minutes."));
+  }, 5 * 60 * 1000);
+
+  console.error(`Opening authorization page: ${authorizeUrl.toString()}`);
+  const opened = await openBrowser(authorizeUrl.toString());
+  if (!opened) console.error("Could not open the browser automatically. Copy the URL above into a browser.");
+
+  try {
+    const tokens = await callbackResult;
+    clearTimeout(timeout);
+    console.error(`Authorized successfully. Token expires in ${tokens.expires_in} seconds.`);
+  } finally {
+    clearTimeout(timeout);
+    server.close();
+  }
+}

package/lib/config.mjs

@@ -0,0 +1,36 @@
+import path from "node:path";
+
+export const DEFAULT_CLIENT_ID = "vxtalent-hr-cli";
+export const DEFAULT_SCOPE = "hr:read";
+
+function normalizeBase(value) {
+  const url = new URL(value);
+  url.hash = "";
+  url.search = "";
+  return url.toString().replace(/\/$/, "");
+}
+
+export function resolveOptions(args = {}) {
+  const issuer = args.issuer || process.env.VXTALENT_ISSUER || "";
+  if (!issuer) {
+    throw new Error("Missing issuer. Pass --issuer <url> or set VXTALENT_ISSUER.");
+  }
+  const normalizedIssuer = normalizeBase(issuer);
+  return {
+    issuer: normalizedIssuer,
+    clientId: args["client-id"] || process.env.VXTALENT_CLIENT_ID || DEFAULT_CLIENT_ID,
+    scope: args.scope || process.env.VXTALENT_SCOPE || DEFAULT_SCOPE,
+    mcpUrl:
+      args["mcp-url"] ||
+      process.env.VXTALENT_MCP_URL ||
+      `${normalizedIssuer}/mcp`,
+    autoAuth: args["no-auto-auth"] ? false : true,
+  };
+}
+
+export function platformConfigPath(platform, home) {
+  if (platform === "workbuddy") return path.join(home, ".workbuddy", "mcp.json");
+  if (platform === "qwen-work") return path.join(home, ".qwen-work", "mcp.json");
+  if (platform === "doubao-work") return path.join(home, ".doubao-work", "mcp.json");
+  return null;
+}

package/lib/install.mjs

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { platformConfigPath } from "./config.mjs";
+import { runAuth } from "./auth.mjs";
+
+function mcpConfig(options, localScript) {
+  if (localScript) {
+    // Local checkout mode: point directly at the local Node executable and
+    // script so agents can use the CLI before it is published to npm.
+    return {
+      type: "stdio",
+      command: process.execPath,
+      args: [localScript, "mcp"],
+      env: {
+        VXTALENT_ISSUER: options.issuer,
+        VXTALENT_MCP_URL: options.mcpUrl,
+        VXTALENT_CLIENT_ID: options.clientId,
+      },
+    };
+  }
+  return {
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "vxtalent-hr-cli", "mcp"],
+    env: {
+      VXTALENT_ISSUER: options.issuer,
+      VXTALENT_MCP_URL: options.mcpUrl,
+      VXTALENT_CLIENT_ID: options.clientId,
+    },
+  };
+}
+
+export async function install(options, args) {
+  const platform = args.platform || "custom";
+  const configPath = args.config || platformConfigPath(platform, os.homedir());
+  const useLocal = Boolean(args["local"] ?? args["node"]);
+  const localScript = useLocal ? fileURLToPath(new URL("../index.mjs", import.meta.url)) : "";
+  const entry = mcpConfig(options, localScript);
+  let config = { mcpServers: {} };
+
+  if (args.write) {
+    if (!configPath) throw new Error("Pass --config <path> when using --write without a known platform.");
+    if (fs.existsSync(configPath)) {
+      config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+      if (typeof config !== "object" || config === null) throw new Error("Existing agent config is not a JSON object.");
+      config.mcpServers = config.mcpServers && typeof config.mcpServers === "object" ? config.mcpServers : {};
+    }
+    config.mcpServers["vxtalent-hr"] = entry;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    console.log(`Wrote MCP config: ${configPath}`);
+  } else {
+    console.log("Agent MCP config (copy this JSON):");
+    console.log(JSON.stringify({ mcpServers: { "vxtalent-hr": entry } }, null, 2));
+  }
+
+  if (configPath && !args.write) {
+    console.log(`Suggested config path: ${configPath}`);
+  }
+  if (args.auth) {
+    console.error("Starting authorization...");
+    await runAuth(options);
+  }
+}

package/lib/mcp-server.mjs

@@ -0,0 +1,203 @@
+import readline from "node:readline";
+import { clearTokens, getValidAccessToken, loadTokens, revokeTokens } from "./token-manager.mjs";
+import { runAuth } from "./auth.mjs";
+
+function writeMessage(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function errorResponse(id, code, message) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: { code, message },
+  };
+}
+
+// Local-only tools injected into tools/list so users can manage the CLI
+// authorization directly from the agent chat (no terminal required).
+const LOCAL_TOOLS = [
+  {
+    name: "auth_status",
+    description: "查看 vxTalent HR 本机授权状态（是否已登录、token 过期时间）。",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "auth_logout",
+    description:
+      "退出 vxTalent HR 登录：撤销本机 token 并删除本地授权记录。调用后需要重新授权才能继续使用 HR 工具。",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+];
+
+function mergeLocalTools(response, message) {
+  if (message.method === "tools/list" && response.result && Array.isArray(response.result.tools)) {
+    const names = new Set(response.result.tools.map((tool) => tool.name));
+    const extra = LOCAL_TOOLS.filter((tool) => !names.has(tool.name));
+    if (extra.length > 0) {
+      response.result.tools = [...response.result.tools, ...extra];
+    }
+  }
+  return response;
+}
+
+function parseSseBody(body) {
+  const messages = [];
+  let data = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (line === "") {
+      if (data.length > 0) {
+        try {
+          messages.push(JSON.parse(data.join("\n")));
+        } catch {
+          // Ignore keep-alive comments and non-JSON events.
+        }
+      }
+      data = [];
+    } else if (line.startsWith("data:")) {
+      data.push(line.slice(5).trimStart());
+    }
+  }
+  if (data.length > 0) {
+    try {
+      messages.push(JSON.parse(data.join("\n")));
+    } catch {
+      // Ignore incomplete event data.
+    }
+  }
+  return messages;
+}
+
+async function postToRemote(options, message, sessionId, ensureToken) {
+  const accessToken = await ensureToken();
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
+    Authorization: `Bearer ${accessToken}`,
+  };
+  if (sessionId) headers["Mcp-Session-Id"] = sessionId;
+
+  const response = await fetch(options.mcpUrl, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(message),
+    signal: AbortSignal.timeout(120000),
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    const detail = text.slice(0, 500);
+    throw new Error(`Remote MCP returned ${response.status}: ${detail}`);
+  }
+
+  const contentType = response.headers.get("content-type") || "";
+  const messages = contentType.includes("text/event-stream")
+    ? parseSseBody(text)
+    : text.trim()
+      ? [JSON.parse(text)]
+      : [];
+  return { messages, sessionId: response.headers.get("mcp-session-id") || sessionId };
+}
+
+export async function startMcpServer(options) {
+  let sessionId = "";
+  let initialized = false;
+  let authTried = false;
+  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+  let queue = Promise.resolve();
+
+  console.error("[vxtalent-hr-cli] MCP stdio bridge started. Waiting for JSON-RPC messages on stdin...");
+
+  async function ensureToken() {
+    try {
+      return await getValidAccessToken(options);
+    } catch (error) {
+      if (options.autoAuth && !authTried) {
+        authTried = true;
+        console.error("[vxtalent-hr-cli] No valid token; starting browser authorization...");
+        await runAuth(options);
+        return await getValidAccessToken(options);
+      }
+      throw error;
+    }
+  }
+
+  async function handleLocalTool(message, name) {
+    try {
+      let text;
+      if (name === "auth_logout") {
+        await revokeTokens(options);
+        clearTokens(options);
+        text = "已退出登录，本机授权已撤销。如需继续使用 HR 工具，请重新授权。";
+      } else {
+        const tokens = loadTokens(options);
+        text = tokens
+          ? `已登录。token 过期时间：${new Date(tokens.expires_at).toISOString()}`
+          : "未登录。需要先完成授权才能使用 HR 工具。";
+      }
+      writeMessage({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: { content: [{ type: "text", text }] },
+      });
+    } catch (error) {
+      writeMessage(errorResponse(message.id, -32603, error.message));
+    }
+  }
+
+  rl.on("line", async (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+
+    queue = queue.then(async () => {
+      const isNotification = message.id === undefined;
+      const isInitialize = message.method === "initialize";
+      // Local tools are handled here so users can log out from the chat.
+      if (message.method === "tools/call" && message.params?.name === "auth_logout") {
+        await handleLocalTool(message, "auth_logout");
+        return;
+      }
+      if (message.method === "tools/call" && message.params?.name === "auth_status") {
+        await handleLocalTool(message, "auth_status");
+        return;
+      }
+      try {
+        const result = await postToRemote(options, message, sessionId, ensureToken);
+        if (isInitialize && result.sessionId) {
+          sessionId = result.sessionId;
+        }
+        if (isInitialize) {
+          initialized = true;
+        }
+        for (const response of result.messages) {
+          // The remote replies to initialize with the server info; it may also
+          // emit a "notifications/initialized" notification (no id). Notifications
+          // must not be forwarded as responses.
+          if (response.id === undefined && response.method === "notifications/initialized") {
+            continue;
+          }
+          writeMessage(mergeLocalTools(response, message));
+        }
+      } catch (error) {
+        if (!isNotification) {
+          const code = error.message.includes("Not authorized") ? 401 : -32603;
+          writeMessage(errorResponse(message.id, code, error.message));
+        } else {
+          console.error(`[vxtalent-hr-cli] ${error.message}`);
+        }
+        if (error.message.includes("Not authorized")) {
+          console.error(`[vxtalent-hr-cli] Authorization missing or expired. Run: vxtalent-hr-cli auth --issuer ${options.issuer}`);
+        }
+      }
+    });
+  });
+
+  await new Promise((resolve) => rl.once("close", resolve));
+  // Drain any in-flight request before exiting (stdin may close right after
+  // the last piped message while the remote call is still pending).
+  await queue;
+}

package/lib/token-manager.mjs

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const TOKEN_BUFFER_MS = 5 * 60 * 1000;
+
+function authFile(options) {
+  return path.join(os.homedir(), ".vxtalent", "auth.json");
+}
+
+export function loadTokens(options) {
+  const file = authFile(options);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const tokens = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (tokens.issuer !== options.issuer) return null;
+    return tokens;
+  } catch {
+    return null;
+  }
+}
+
+export function saveTokens(options, tokens) {
+  const file = authFile(options);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const record = {
+    version: 1,
+    issuer: options.issuer,
+    client_id: options.clientId,
+    scope: tokens.scope || options.scope,
+    access_token: tokens.access_token,
+    refresh_token: tokens.refresh_token || "",
+    expires_at: Date.now() + Number(tokens.expires_in || 0) * 1000,
+  };
+  const tempFile = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tempFile, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tempFile, file);
+  fs.chmodSync(file, 0o600);
+  return record;
+}
+
+export function clearTokens(options) {
+  const file = authFile(options);
+  fs.rmSync(file, { force: true });
+}
+
+export async function getValidAccessToken(options) {
+  const tokens = loadTokens(options);
+  if (!tokens) {
+    throw new Error("Not authorized. Run: vxtalent-hr-cli auth --issuer <url>");
+  }
+  if (tokens.expires_at - TOKEN_BUFFER_MS > Date.now()) {
+    return tokens.access_token;
+  }
+  if (!tokens.refresh_token) {
+    throw new Error("Authorization expired and no refresh token exists. Re-run auth.");
+  }
+
+  const response = await fetch(`${options.issuer}/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: tokens.refresh_token,
+      client_id: options.clientId,
+    }),
+    signal: AbortSignal.timeout(30000),
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    clearTokens(options);
+    throw new Error(payload.error_description || "Token refresh failed. Re-run auth.");
+  }
+  const refreshed = saveTokens(options, { ...tokens, ...payload });
+  return refreshed.access_token;
+}
+
+export async function revokeTokens(options) {
+  const tokens = loadTokens(options);
+  if (!tokens) return;
+  try {
+    await fetch(`${options.issuer}/oauth/revoke`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        token: tokens.access_token,
+        client_id: options.clientId,
+      }),
+      signal: AbortSignal.timeout(30000),
+    });
+  } catch (error) {
+    console.error(`[vxtalent-hr-cli] Revocation request failed: ${error.message}`);
+  }
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "vxtalent-hr-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "vxTalent HR MCP CLI for WorkBuddy, Qwen Work, Doubao Work and other MCP agents",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "bin": {
+    "vxtalent-hr-cli": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "lib",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "oauth",
+    "hr",
+    "cli",
+    "workbuddy",
+    "qwen-work",
+    "doubao-work"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://your-git-host/vxTalent-AI/Backend-qwenagent.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }