patchxnote-agent 0.2.6 → 0.2.8

package/README.md

@@ -2,26 +2,60 @@
 
 [English README](https://github.com/ZsTs119/patchxnote-agent#readme) | [简体中文说明](https://github.com/ZsTs119/patchxnote-agent/blob/main/README.zh-CN.md) | [飞书公开使用指南](https://patchx2025.feishu.cn/wiki/PnVRwYT7IirFPckairGcWPnHnCd)
 
-This npm package is the installer wrapper for PatchXNote Agent. It downloads the matching native `patchxnote` CLI binary from GitHub Releases, verifies `checksums.txt`, and installs it into a user-writable directory.
+This npm package is the installer and thin launcher wrapper for PatchXNote Agent. It downloads or verifies the matching native `patchxnote` CLI binary from GitHub Releases, verifies `checksums.txt`, and installs it into a user-writable directory before delegating runtime commands to that binary.
 
 PatchXNote Agent is the local AI assistant connector for PatchXNote. It lets an MCP-capable AI assistant find PatchXNote records, inspect AI-generated results, create Markdown drafts, and manually send user-approved messages to Feishu, DingTalk, or another webhook.
 
 Give this one-line prompt to a local-command-capable AI assistant:
 
 ```text
-Install and connect PatchXNote Agent by following the public guide at https://patchx2025.feishu.cn/wiki/PnVRwYT7IirFPckairGcWPnHnCd: run npx -y patchxnote-agent install --print-config, guide me through patchxnote login, and add the printed MCP JSON config to this AI assistant. Do not ask me to paste OTP codes, access tokens, or refresh tokens into chat. GitHub repository: https://github.com/ZsTs119/patchxnote-agent
+Connect PatchXNote Agent by following the public guide at https://patchx2025.feishu.cn/wiki/PnVRwYT7IirFPckairGcWPnHnCd: run npx -y patchxnote-agent@latest setup --client <my-client>, keep MCP config secret-free, and guide me through login in the same runtime that will launch the MCP server. Do not ask me to paste OTP codes, access tokens, or refresh tokens into chat. GitHub repository: https://github.com/ZsTs119/patchxnote-agent
 ```
 
-Or run the install command manually:
+Run setup for a supported local client:
 
 ```sh
-npx -y patchxnote-agent@0.2.6 install --print-config
+npx -y patchxnote-agent@latest setup --client cursor
+npx -y patchxnote-agent@latest setup --client vscode
+npx -y patchxnote-agent@latest setup --client codex
 ```
 
-PatchXNote Agent runs a local stdio MCP server:
+Log in with browser OAuth, then check or clear the MCP login state:
 
 ```sh
-patchxnote mcp serve
+npx -y patchxnote-agent@latest mcp login
+npx -y patchxnote-agent@latest mcp status
+npx -y patchxnote-agent@latest mcp logout --local-only
+```
+
+Print the generic MCP config manually:
+
+```sh
+npx -y patchxnote-agent@latest mcp config
+```
+
+The generated config uses this universal local stdio MCP command:
+
+```sh
+npx -y patchxnote-agent@latest mcp serve
+```
+
+The older terminal Agent login remains available for legacy local CLI/MCP fallback:
+
+```sh
+npx -y patchxnote-agent@latest login
+```
+
+`setup` reuses the same `mcp login` browser OAuth flow. The GoServer website owns phone OTP input; the local Agent owns the loopback callback, token exchange, secure storage, and stdio bridge. `mcp serve` never opens a browser during editor startup. It stores credentials in the OS-native keychain and keeps MCP config free of phone numbers, OTP codes, access tokens, and refresh tokens.
+
+P0 local client IDs: `vscode`, `cursor`, `codex`, `claude-code`, `claude-desktop`, `windsurf`, `trae`, `qoder`, `workbuddy`.
+
+Platform clients such as Feishu Aily, Doubao Work Partner, Tencent Agent Development Platform, and enterprise WorkBuddy need the hosted remote MCP gateway plus platform-console acceptance; local `npx` setup is for desktop and terminal clients.
+
+If a client rejects `npx` or times out during first binary download, run the stable absolute-path fallback:
+
+```sh
+npx -y patchxnote-agent@latest install --print-config
 ```
 
 It currently exposes 19 MCP tools grouped around account/record lookup, webhook configuration and sending, and explicit AI result inspection.
@@ -38,7 +72,7 @@ patchxnote webhook send --target "Product Feishu" --file ./message.md
 
 Webhook aliases can contain Chinese text, spaces, and dots.
 
-Server-backed PatchXNote data access remains read-only through dedicated `/v1/agent/**` APIs. Record lookup can include formal saved results and readable model-generated outputs returned by the server. Local webhook tools can configure named targets and perform explicit manual sends. AI result tools can inspect source text, AI response, parsed result, and final result when explicitly called. The CLI stores credentials and webhook secrets in the OS-native keychain when available, never lists webhook URLs or signing secrets back, and does not expose raw audio, audio downloads, hardware write actions, payment flows, or Admin APIs.
+Server-backed PatchXNote data access remains read-only through dedicated `/v1/agent/**` APIs. Record lookup can include formal saved results and readable model-generated outputs returned by the server. Local webhook tools can configure named targets and perform explicit manual sends. AI result tools can inspect source text, AI response, parsed result, and final result when explicitly called. MCP config contains no phone number, OTP, access token, refresh token, webhook secret, or base URL by default. The CLI stores credentials and webhook secrets in the OS-native keychain when available, never lists webhook URLs or signing secrets back, and does not expose raw audio, audio downloads, hardware write actions, payment flows, or Admin APIs.
 
 For full installation, MCP setup, security notes, and troubleshooting, read the GitHub documentation:
 

package/bin/patchxnote-agent.js

@@ -6,19 +6,110 @@ const fs = require("fs");
 const https = require("https");
 const os = require("os");
 const path = require("path");
+const { spawn, spawnSync } = require("child_process");
 
 const packageRoot = path.resolve(__dirname, "..");
 const packageJSON = require(path.join(packageRoot, "package.json"));
 const repo = "ZsTs119/patchxnote-agent";
+const lockTimeoutMs = 10000;
+const staleLockMs = 10 * 60 * 1000;
 
 async function main(argv) {
   const parsed = parseArgs(argv);
-  if (!["install", "update", "uninstall"].includes(parsed.command)) {
-    throw new Error("usage: patchxnote-agent <install|update|uninstall> [--dry-run] [--print-config] [--install-dir <path>]");
+
+  if (parsed.command === "install" || parsed.command === "update") {
+    await runInstall(parsed);
+    return;
+  }
+  if (parsed.command === "uninstall") {
+    await runUninstall(parsed);
+    return;
+  }
+  if (parsed.command === "login") {
+    await runLogin(parsed);
+    return;
+  }
+  if (parsed.command === "setup") {
+    await runSetup(parsed);
+    return;
+  }
+  if (parsed.command === "mcp" && parsed.subcommand === "config") {
+    printUniversalMCPConfig();
+    return;
   }
+  if (parsed.command === "mcp" && ["login", "status", "logout"].includes(parsed.subcommand)) {
+    await runMCPSubcommand(parsed);
+    return;
+  }
+  if (parsed.command === "mcp" && parsed.subcommand === "serve") {
+    await runMCPServe(parsed);
+    return;
+  }
+
+  throw new Error(usage());
+}
 
-  const target = resolveTarget(parsed.options.platform || process.platform, parsed.options.arch || process.arch);
-  const installDir = parsed.options.installDir || defaultInstallDir(process.platform);
+async function runInstall(parsed) {
+  const plan = createInstallPlan(parsed.command, parsed.options);
+  if (parsed.options.dryRun) {
+    printPlan(plan);
+    if (parsed.options.printConfig) {
+      printMCPConfig(plan.install_path);
+    }
+    return;
+  }
+  await withInstallLock(plan, async () => installBinary(plan, parsed.options));
+  console.log(`Installed PatchXNote Agent ${plan.version} to ${plan.install_path}`);
+  printPathGuidance(plan.install_dir, plan.platform);
+  if (parsed.options.printConfig) {
+    printMCPConfig(plan.install_path);
+  } else {
+    console.log("Run: patchxnote login");
+    console.log("MCP config: patchxnote mcp serve");
+  }
+}
+
+async function runUninstall(parsed) {
+  const plan = createInstallPlan(parsed.command, parsed.options);
+  await uninstall(plan, parsed.options);
+}
+
+async function runLogin(parsed) {
+  const plan = await ensureBinary(parsed.options, { stderr: process.stderr });
+  const code = await spawnAndWait(plan.install_path, ["login", ...parsed.passthroughArgs], {
+    stdio: "inherit"
+  });
+  process.exitCode = code;
+}
+
+async function runSetup(parsed) {
+  const plan = await ensureBinary(parsed.options, { stderr: process.stderr });
+  const code = await spawnAndWait(plan.install_path, ["setup", ...parsed.passthroughArgs], {
+    stdio: "inherit"
+  });
+  process.exitCode = code;
+}
+
+async function runMCPServe(parsed) {
+  const plan = await ensureBinary(parsed.options, { stderr: process.stderr });
+  const code = await spawnAndWait(plan.install_path, ["mcp", "serve", ...parsed.passthroughArgs], {
+    stdio: ["pipe", "inherit", "inherit"],
+    pipeStdin: true
+  });
+  process.exitCode = code;
+}
+
+async function runMCPSubcommand(parsed) {
+  const plan = await ensureBinary(parsed.options, { stderr: process.stderr });
+  const code = await spawnAndWait(plan.install_path, ["mcp", parsed.subcommand, ...parsed.passthroughArgs], {
+    stdio: "inherit"
+  });
+  process.exitCode = code;
+}
+
+function createInstallPlan(command, options = {}) {
+  const target = resolveTarget(options.platform || process.platform, options.arch || process.arch);
+  const installDir = options.installDir || defaultInstallDir(process.platform);
   const binaryName = target.platform === "windows" ? "patchxnote.exe" : "patchxnote";
   const installPath = joinInstallPath(installDir, binaryName, target.platform);
   const version = packageJSON.version;
@@ -37,48 +128,65 @@ async function main(argv) {
     install_path: installPath,
     install_dir_on_path: isInstallDirOnPath(installDir, process.env.PATH || "", target.platform),
     path_hint: pathHint(installDir, target.platform),
+    asset_name: assetName,
     asset_url: assetURL,
     checksums_url: checksumsURL,
-    action: parsed.command,
-    dry_run: Boolean(parsed.options.dryRun)
+    action: command,
+    dry_run: Boolean(options.dryRun)
   };
+  return plan;
+}
 
-  if (parsed.command === "uninstall") {
-    await uninstall(plan, parsed.options);
-    return;
+async function installBinary(plan, options = {}) {
+  let binary;
+  if (options.fromLocal) {
+    binary = await fs.promises.readFile(options.fromLocal);
+  } else {
+    binary = await download(plan.asset_url);
+    const checksums = await download(plan.checksums_url, "utf8");
+    verifyChecksum(binary, plan.asset_name, checksums);
   }
 
-  if (parsed.options.dryRun) {
-    printPlan(plan);
-    if (parsed.options.printConfig) {
-      printMCPConfig(installPath);
+  await fs.promises.mkdir(plan.install_dir, { recursive: true, mode: 0o755 });
+  const tempPath = `${plan.install_path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await fs.promises.writeFile(tempPath, binary, { mode: plan.platform === "windows" ? 0o644 : 0o755 });
+    if (plan.platform !== "windows") {
+      await fs.promises.chmod(tempPath, 0o755);
+      await assertExecutable(tempPath);
     }
-    return;
+    await replaceInstalledBinary(tempPath, plan.install_path);
+    if (plan.platform !== "windows") {
+      await assertExecutable(plan.install_path);
+    }
+  } finally {
+    await fs.promises.rm(tempPath, { force: true }).catch(() => {});
   }
+}
 
-  let binary;
-  if (parsed.options.fromLocal) {
-    binary = await fs.promises.readFile(parsed.options.fromLocal);
-  } else {
-    binary = await download(assetURL);
-    const checksums = await download(checksumsURL, "utf8");
-    verifyChecksum(binary, assetName, checksums);
+async function replaceInstalledBinary(tempPath, installPath) {
+  const backupPath = `${installPath}.bak-${process.pid}-${Date.now()}`;
+  let hasBackup = false;
+  try {
+    await fs.promises.rename(installPath, backupPath);
+    hasBackup = true;
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
   }
 
-  await fs.promises.mkdir(installDir, { recursive: true, mode: 0o755 });
-  await fs.promises.writeFile(installPath, binary, { mode: target.platform === "windows" ? 0o644 : 0o755 });
-  if (target.platform !== "windows") {
-    await fs.promises.chmod(installPath, 0o755);
-    await assertExecutable(installPath);
+  try {
+    await fs.promises.rename(tempPath, installPath);
+  } catch (error) {
+    if (hasBackup) {
+      await fs.promises.rename(backupPath, installPath).catch(() => {});
+    }
+    throw error;
   }
 
-  console.log(`Installed PatchXNote Agent ${version} to ${installPath}`);
-  printPathGuidance(installDir, target.platform);
-  if (parsed.options.printConfig) {
-    printMCPConfig(installPath);
-  } else {
-    console.log("Run: patchxnote login");
-    console.log("MCP config: patchxnote mcp serve");
+  if (hasBackup) {
+    await fs.promises.rm(backupPath, { force: true }).catch(() => {});
   }
 }
 
@@ -98,8 +206,218 @@ async function assertExecutable(installPath) {
   }
 }
 
+async function ensureBinary(options = {}, io = {}) {
+  const plan = createInstallPlan("install", options);
+  return withInstallLock(plan, async () => {
+    const inspected = inspectInstalledBinary(plan);
+    if (inspected.ok && inspected.version === plan.version) {
+      return plan;
+    }
+
+    if (!inspected.exists) {
+      writeDiagnostic(io, `PatchXNote Agent binary missing; installing ${plan.version}.\n`);
+    } else if (inspected.ok) {
+      writeDiagnostic(io, `PatchXNote Agent binary version ${inspected.version} does not match package ${plan.version}; reinstalling.\n`);
+    } else {
+      writeDiagnostic(io, `PatchXNote Agent binary preflight failed; reinstalling ${plan.version}.\n`);
+    }
+
+    await installBinary(plan, options);
+    const afterInstall = inspectInstalledBinary(plan);
+    if (!afterInstall.ok) {
+      throw new Error(`installed PatchXNote Agent binary failed preflight: ${afterInstall.reason}`);
+    }
+    if (afterInstall.version !== plan.version) {
+      throw new Error(`installed PatchXNote Agent binary version ${afterInstall.version} does not match package ${plan.version}`);
+    }
+    return plan;
+  });
+}
+
+function inspectInstalledBinary(plan) {
+  if (!fs.existsSync(plan.install_path)) {
+    return { exists: false, ok: false, reason: "missing" };
+  }
+  const result = spawnSync(plan.install_path, ["version", "--output", "json"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 5000,
+    windowsHide: true,
+    maxBuffer: 1024 * 1024
+  });
+  if (result.error) {
+    return { exists: true, ok: false, reason: result.error.message };
+  }
+  if (result.status !== 0) {
+    return { exists: true, ok: false, reason: `exit ${result.status}` };
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(result.stdout.trim());
+  } catch (error) {
+    return { exists: true, ok: false, reason: "invalid version output" };
+  }
+  return { exists: true, ok: true, version: String(decoded.version || "") };
+}
+
+async function withInstallLock(plan, action) {
+  await fs.promises.mkdir(plan.install_dir, { recursive: true, mode: 0o755 });
+  const release = await acquireInstallLock(`${plan.install_path}.lock`);
+  try {
+    return await action();
+  } finally {
+    await release();
+  }
+}
+
+async function acquireInstallLock(lockDir) {
+  const startedAt = Date.now();
+  for (;;) {
+    try {
+      await fs.promises.mkdir(lockDir);
+      return async () => {
+        await fs.promises.rmdir(lockDir).catch(() => {});
+      };
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+      await removeStaleLock(lockDir).catch(() => {});
+      if (Date.now() - startedAt > lockTimeoutMs) {
+        throw new Error(`install lock timed out: ${lockDir}`);
+      }
+      await delay(100);
+    }
+  }
+}
+
+async function removeStaleLock(lockDir) {
+  const stat = await fs.promises.stat(lockDir);
+  if (Date.now() - stat.mtimeMs > staleLockMs) {
+    await fs.promises.rmdir(lockDir);
+  }
+}
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function writeDiagnostic(io, message) {
+  if (io.stderr && typeof io.stderr.write === "function") {
+    io.stderr.write(message);
+  }
+}
+
+function spawnAndWait(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: options.stdio || "inherit",
+      windowsHide: true
+    });
+    let settled = false;
+    let stdinEndHandler;
+    let stdinErrorHandler;
+    let exitHandler;
+
+    const cleanup = () => {
+      for (const [signal, handler] of signalHandlers) {
+        process.off(signal, handler);
+      }
+      if (stdinEndHandler) {
+        process.stdin.off("end", stdinEndHandler);
+      }
+      if (stdinErrorHandler) {
+        process.stdin.off("error", stdinErrorHandler);
+      }
+      if (exitHandler) {
+        process.off("exit", exitHandler);
+      }
+    };
+
+    const signalHandlers = ["SIGINT", "SIGTERM"].map(signal => {
+      const handler = () => {
+        if (!child.killed) {
+          child.kill(signal);
+        }
+      };
+      process.on(signal, handler);
+      return [signal, handler];
+    });
+
+    if (options.pipeStdin && child.stdin) {
+      child.stdin.on("error", () => {});
+      stdinEndHandler = () => child.stdin.end();
+      stdinErrorHandler = () => child.stdin.destroy();
+      process.stdin.on("end", stdinEndHandler);
+      process.stdin.on("error", stdinErrorHandler);
+      process.stdin.pipe(child.stdin);
+    }
+
+    exitHandler = () => {
+      if (!settled && !child.killed) {
+        child.kill();
+      }
+    };
+    process.on("exit", exitHandler);
+
+    child.on("error", error => {
+      settled = true;
+      cleanup();
+      reject(error);
+    });
+    child.on("exit", (code, signal) => {
+      settled = true;
+      cleanup();
+      resolve(code == null ? signalExitCode(signal) : code);
+    });
+  });
+}
+
+function signalExitCode(signal) {
+  if (signal === "SIGINT") {
+    return 130;
+  }
+  if (signal === "SIGTERM") {
+    return 143;
+  }
+  return 1;
+}
+
 function parseArgs(argv) {
   const [command, ...rest] = argv;
+  if (!command) {
+    throw new Error(usage());
+  }
+  if (["install", "update", "uninstall"].includes(command)) {
+    return { command, options: parseInstallOptions(command, rest), passthroughArgs: [] };
+  }
+  if (command === "login") {
+    const launcher = parseLauncherOptions(rest, { allowPassthrough: true, rejectPrintConfig: true });
+    return { command, options: launcher.options, passthroughArgs: launcher.passthroughArgs };
+  }
+  if (command === "setup") {
+    const launcher = parseLauncherOptions(rest, {
+      allowPassthrough: true,
+      passThroughDryRun: true,
+      passThroughPrintConfig: true
+    });
+    return { command, options: launcher.options, passthroughArgs: launcher.passthroughArgs };
+  }
+  if (command === "mcp") {
+    const [subcommand, ...subcommandArgs] = rest;
+    if (!["serve", "config", "login", "status", "logout"].includes(subcommand)) {
+      throw new Error(mcpUsage());
+    }
+    const launcher = parseLauncherOptions(subcommandArgs, {
+      allowPassthrough: subcommand !== "config",
+      rejectPrintConfig: true
+    });
+    return { command, subcommand, options: launcher.options, passthroughArgs: launcher.passthroughArgs };
+  }
+  throw new Error(usage());
+}
+
+function parseInstallOptions(command, rest) {
   const options = {};
   for (let index = 0; index < rest.length; index += 1) {
     const arg = rest[index];
@@ -129,7 +447,58 @@ function parseArgs(argv) {
         throw new Error(`unknown option ${arg}`);
     }
   }
-  return { command, options };
+  return options;
+}
+
+function parseLauncherOptions(rest, settings = {}) {
+  const options = {};
+  const passthroughArgs = [];
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    switch (arg) {
+      case "--":
+        if (settings.allowPassthrough) {
+          passthroughArgs.push(...rest.slice(index + 1));
+          index = rest.length;
+          break;
+        }
+        throw new Error(`unknown option ${arg}`);
+      case "--dry-run":
+        if (settings.passThroughDryRun) {
+          passthroughArgs.push(arg);
+          break;
+        }
+        throw new Error("--dry-run is only valid for install/update/uninstall");
+      case "--print-config":
+        if (settings.passThroughPrintConfig) {
+          passthroughArgs.push(arg);
+          break;
+        }
+        if (settings.rejectPrintConfig) {
+          throw new Error("--print-config is not valid for this command");
+        }
+        options.printConfig = true;
+        break;
+      case "--install-dir":
+        options.installDir = requireValue(rest, ++index, arg);
+        break;
+      case "--from-local":
+        options.fromLocal = requireValue(rest, ++index, arg);
+        break;
+      case "--platform":
+        options.platform = requireValue(rest, ++index, arg);
+        break;
+      case "--arch":
+        options.arch = requireValue(rest, ++index, arg);
+        break;
+      default:
+        if (!settings.allowPassthrough) {
+          throw new Error(`unknown option ${arg}`);
+        }
+        passthroughArgs.push(arg);
+    }
+  }
+  return { options, passthroughArgs };
 }
 
 function requireValue(values, index, option) {
@@ -195,6 +564,21 @@ function printMCPConfig(commandPath) {
   }, null, 2));
 }
 
+function printUniversalMCPConfig() {
+  console.log(JSON.stringify(universalMCPConfig(), null, 2));
+}
+
+function universalMCPConfig() {
+  return {
+    mcpServers: {
+      patchxnote: {
+        command: "npx",
+        args: ["-y", "patchxnote-agent@latest", "mcp", "serve"]
+      }
+    }
+  };
+}
+
 function isInstallDirOnPath(installDir, pathValue, targetPlatform) {
   if (!pathValue) {
     return false;
@@ -284,6 +668,14 @@ function verifyChecksum(binary, assetName, checksumsText) {
   }
 }
 
+function usage() {
+  return "usage: patchxnote-agent <install|update|uninstall|login|setup|mcp> [options]";
+}
+
+function mcpUsage() {
+  return "usage: patchxnote-agent mcp <serve|config|login|status|logout> [options]";
+}
+
 if (require.main === module) {
   main(process.argv.slice(2)).catch(error => {
     console.error(error.message);
@@ -292,12 +684,16 @@ if (require.main === module) {
 }
 
 module.exports = {
+  createInstallPlan,
   defaultInstallDir,
+  inspectInstalledBinary,
+  parseLauncherOptions,
   parseArgs,
   resolveTarget,
   joinInstallPath,
   isInstallDirOnPath,
   pathHint,
   resolveRedirectURL,
+  universalMCPConfig,
   verifyChecksum
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchxnote-agent",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Installer wrapper for the PatchXNote Agent CLI and local MCP server.",
   "repository": {
     "type": "git",