@hellolynk-ai/codex-plugin 0.2.100 → 0.2.102-macos.1

package/README.md

@@ -35,35 +35,35 @@
 
 Codex、OpenClaw、TRAE Work、WorkBuddy。装哪个客户端，就选哪个包。同一个账号下，它们共用你的灵信号。
 
-源码见 [Codex 客户端源码](https://github.com/haoyun18881-beep/HelloLynk/tree/main/clients/codex)，完整介绍见 [HelloLynk on GitHub](https://github.com/haoyun18881-beep/HelloLynk)。
+源码见 [Codex 客户端源码](https://github.com/haoyun18881-beep/HelloLynk/tree/main/clients/codex-macos)，完整介绍见 [HelloLynk on GitHub](https://github.com/haoyun18881-beep/HelloLynk)。
 
 ## 前提
 
-Windows 10/11、Node.js 22.16 或更高版本、PowerShell 7，以及打开过一次的 Codex。
+Apple 芯片、macOS 13 或更高版本、Node.js 22.16 或更高版本，以及安装在「应用程序」中的 ChatGPT（已打开过 Codex）。
 
 ## 安装
 
 1. 打开 [HelloLynk 官网（Official site）](https://hellolynk.com)。新用户注册账号；已有账号登录后，查看自己的公开灵信号。
 2. 两种装法任选一种。
 
-   用安装包，在官网或 [GitHub Release](https://github.com/haoyun18881-beep/HelloLynk/releases) 下载 Codex 安装包，完整解压，在包含 `package` 文件夹的目录打开 PowerShell，运行：
+   推荐用 npm，在终端运行：
 
-   ```powershell
-   node .\package\bin\hellolynk-client-setup.mjs init
+   ```sh
+   npm install -g @hellolynk-ai/codex-plugin@macos
+   hellolynk-codex init
    ```
 
-   用 npm，在 PowerShell 运行：
+   用安装包，在官网或 [GitHub Release](https://github.com/haoyun18881-beep/HelloLynk/releases) 下载 Codex for Mac 安装包，完整解压，在包含 `package` 文件夹的目录打开 终端，运行：
 
-   ```powershell
-   npm install -g @hellolynk-ai/codex-plugin
-   hellolynk-codex init
+   ```sh
+   node ./package/bin/hellolynk-client-setup.mjs init
    ```
 
 3. 完全退出并重新打开 Codex。
 
 可以把本说明交给你的本地 AI，请它帮你安装；用安装包时，把解压目录也告诉它。
 
-下文命令按安装包写法给出。用 npm 装的，把 `node .\package\bin\hellolynk-client-setup.mjs` 换成 `hellolynk-codex`，在任意目录运行。
+下文命令按安装包写法给出。用 npm 装的，把 `node ./package/bin/hellolynk-client-setup.mjs` 换成 `hellolynk-codex`，在任意目录运行。
 
 ## 首次连接
 
@@ -73,8 +73,8 @@ Windows 10/11、Node.js 22.16 或更高版本、PowerShell 7，以及打开过
 
 也可以让 AI 用命令连接，把示例换成自己的公开灵信号：
 
-```powershell
-node .\package\bin\hellolynk-client-setup.mjs connect --hellolynk-id hellolynk:intl:your-name
+```sh
+node ./package/bin/hellolynk-client-setup.mjs connect --hellolynk-id hellolynk:intl:your-name
 ```
 
 首次连接这台电脑时，命令会给出官网确认链接。AI 把链接给用户；用户确认后，AI 继续执行同一条连接命令。
@@ -83,20 +83,20 @@ node .\package\bin\hellolynk-client-setup.mjs connect --hellolynk-id hellolynk:i
 
 插件会自动更新，不用操作。要手动更新，下载新版安装包，在包含 `package` 文件夹的目录运行：
 
-```powershell
-node .\package\bin\hellolynk-client-setup.mjs setup
+```sh
+node ./package/bin/hellolynk-client-setup.mjs setup
 ```
 
-用 npm 装的，先运行 `npm install -g @hellolynk-ai/codex-plugin` 装上新版，再运行 `hellolynk-codex setup`。
+用 npm 装的，先运行 `npm install -g @hellolynk-ai/codex-plugin@macos` 装上新版，再运行 `hellolynk-codex setup`。
 
 ## 卸载
 
-在包含 `package` 文件夹的目录运行 `node .\package\bin\hellolynk-client-setup.mjs uninstall`。账号、联系人和聊天记录留在这台电脑上，重新安装后不用重新连接。
+在包含 `package` 文件夹的目录运行 `node ./package/bin/hellolynk-client-setup.mjs uninstall`。账号、联系人和聊天记录留在这台电脑上，重新安装后不用重新连接。
 
 用 npm 装的，运行 `hellolynk-codex uninstall`，再运行 `npm uninstall -g @hellolynk-ai/codex-plugin`。
 
 ## 求助
 
-运行 `node .\package\bin\hellolynk-client-setup.mjs doctor` 检查安装，把结果和错误码发到 [haoyun18881@gmail.com](mailto:haoyun18881@gmail.com)。
+运行 `node ./package/bin/hellolynk-client-setup.mjs doctor` 检查安装，把结果和错误码发到 [haoyun18881@gmail.com](mailto:haoyun18881@gmail.com)。
 
 许可：PolyForm Shield License 1.0.0，只覆盖本包内的客户端源码，完整条款见 LICENSE。

package/bin/hellolynk-client-setup.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import crypto from "node:crypto";
-import { lstatSync, realpathSync, writeSync } from "node:fs";
+import { constants, lstatSync, realpathSync, writeSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -21,6 +21,8 @@ const CHINESE = /^zh\b/i.test(Intl.DateTimeFormat().resolvedOptions().locale);
 const CLIENT_NAMES = Object.freeze({ codex: "Codex", openclaw: "OpenClaw", "trae-work": "TRAE Work",
   workbuddy: "WorkBuddy", cursor: "Cursor", dsh: "DSH" });
 const { packageJson, metadata } = await readPackage();
+const macPackage = metadata.client === "codex" && packageJson.os?.[0] === "darwin"
+  && packageJson.cpu?.[0] === "arm64";
 const commandArguments = process.argv.slice(2).filter((value) => value !== "--json");
 const command = String(commandArguments.shift() || "help").toLowerCase();
 const waitForPending = command === "--wait-for-pending";
@@ -61,8 +63,14 @@ try {
       "--expected-manifest-sha256", sourceRelease.outerManifestSha256,
     ]);
   } else {
-  const originalLocations = resolveLocations();
   const accountModule = await importStableCore(PACKAGE_ROOT, "hellolynk-client-account.mjs", "hellolynk_npm_account_runtime_invalid");
+  const originalLocations = resolveLocations(accountModule.clientAccountBaseRoot);
+  if (macPackage && command !== "uninstall") {
+    const config = await readJson(path.join(sourceReleaseRoot, ".mcp.json"), "hellolynk_npm_release_invalid", true);
+    const commandPath = config.mcpServers?.["hellolynk-codex"]?.command;
+    if (typeof commandPath !== "string" || !path.isAbsolute(commandPath)) fail("hellolynk_npm_release_invalid");
+    await fs.access(commandPath, constants.X_OK).catch(() => fail("hellolynk_npm_codex_mac_node_required"));
+  }
   const baseRoot = accountModule.clientAccountBaseRoot(originalLocations.hostRoot);
   const packageLocations = { ...originalLocations, hostRoot: baseRoot, finalCurrentRoot: path.dirname(baseRoot) };
   const accounts = accountModule.createClientAccountActions({ client: metadata.client, storeRoot: baseRoot });
@@ -84,6 +92,13 @@ try {
   if (mutating) {
     await prepareFinalClientRoot(locations);
     installed = await installStablePackage({ packageClosure, sourceRelease, locations: packageLocations });
+    if (metadata.client === "codex") {
+      // The invoking updater can still be B255 code. Stop its old cleanup
+      // before switching the binding/cache to a release with process records.
+      const cleanup = await importStableCore(installed.packageRoot, "hellolynk-release-retention.mjs", "hellolynk_release_retention_unavailable");
+      await cleanup.protectRetentionReceipt({ releasesRoot: path.dirname(installed.packageRoot),
+        client: "codex", currentRelease: installed.packageRoot });
+    }
   }
   const activation = await inspectActivation(locations.hostRoot, metadata.profileId);
   // Both public install commands use the actual account state. Native recovery
@@ -422,7 +437,8 @@ async function uninstallClient(locations) {
     if (receiverConfigured) await receiver.configureTraeNativeTaskWorker({ storeRoot: locations.hostRoot, enabled: false });
   }
   // A binding names the release it starts, so it cannot outlive the releases removed below.
-  if (await exists(path.join(locations.hostRoot, "capabilities-v1.dpapi.clixml"))) {
+  const protectedFile = macPackage ? "protected-v1.sqlite" : "capabilities-v1.dpapi.clixml";
+  if (await exists(path.join(locations.hostRoot, protectedFile))) {
     const store = await importStableCore(PACKAGE_ROOT, "hellolynk-host-protected-store.mjs", "hellolynk_npm_binding_invalid");
     await store.createHostProtectedStore({ root: locations.hostRoot, followClientAccount: false }).disconnectLocalClient(metadata.client);
   }
@@ -831,17 +847,20 @@ async function verifyRelease(releaseRoot, packageRoot, expectedMetadata = metada
   return Object.freeze({ manifestSha256, outerManifestSha256 });
 }
 
-function resolveLocations() {
-  if (process.platform !== "win32") fail("hellolynk_npm_windows_only");
-  const home = path.resolve(process.env.USERPROFILE || os.homedir());
-  const localAppData = path.resolve(process.env.LOCALAPPDATA || path.join(home, "AppData", "Local"));
-  const appData = path.resolve(process.env.APPDATA || path.join(home, "AppData", "Roaming"));
+function resolveLocations(getDefaultHostRoot) {
+  if (macPackage) {
+    if (process.platform !== "darwin" || process.arch !== "arm64") fail("hellolynk_npm_platform_unsupported");
+  } else if (process.platform !== "win32") fail("hellolynk_npm_windows_only");
+  const home = path.resolve((macPackage ? process.env.HOME : process.env.USERPROFILE) || os.homedir());
+  const localAppData = macPackage ? path.join(home, "Library", "Application Support")
+    : path.resolve(process.env.LOCALAPPDATA || path.join(home, "AppData", "Local"));
+  const appData = macPackage ? localAppData : path.resolve(process.env.APPDATA || path.join(home, "AppData", "Roaming"));
   const configuredCodexHome = String(process.env.CODEX_HOME || "");
   if (configuredCodexHome && !path.isAbsolute(configuredCodexHome)) fail("hellolynk_npm_codex_home_invalid");
   const codexHome = path.resolve(configuredCodexHome || path.join(home, ".codex"));
   const configuredHostRoot = String(process.env.HELLOLYNK_NEUTRAL_STORE_ROOT || "").trim();
   if (configuredHostRoot && !path.isAbsolute(configuredHostRoot)) fail("hellolynk_npm_store_root_invalid");
-  const hostRoot = path.resolve(configuredHostRoot || path.join(localAppData, "HelloLynk", "host"));
+  const hostRoot = path.resolve(configuredHostRoot || getDefaultHostRoot());
   if (configuredHostRoot && path.basename(hostRoot).toLowerCase() !== "host") {
     fail("hellolynk_npm_store_root_invalid");
   }
@@ -997,6 +1016,12 @@ async function startHostWhenAbsent(runtime, binding) {
 }
 
 async function secureStableReleaseTree(locations, releaseId, options = {}) {
+  const releasePath = path.resolve(locations.finalCurrentRoot, "releases", releaseId);
+  // An existing AppData root can be shared while a new release is redirected
+  // into one desktop app's private cache. Other clients cannot use that release.
+  if (process.platform === "win32" && realpathSync.native(releasePath).toLowerCase() !== releasePath.toLowerCase()) {
+    fail("client_root_alias_rejected");
+  }
   const module = await importCore(
     "hellolynk-platform-credential-store.mjs",
     "hellolynk_npm_client_root_security_unavailable",
@@ -2239,6 +2264,13 @@ function runCodexJson(args, code, codexHome) {
 }
 
 function minimalEnv({ codexHome = null } = {}) {
+  if (macPackage) return Object.freeze({
+    PATH: process.env.PATH || "/usr/bin:/bin",
+    HOME: process.env.HOME || os.homedir(),
+    TMPDIR: process.env.TMPDIR || os.tmpdir(),
+    LANG: process.env.LANG || "en_US.UTF-8",
+    ...(codexHome ? { CODEX_HOME: codexHome } : {}),
+  });
   return Object.freeze({
     PATH: process.env.Path || process.env.PATH || "",
     PATHEXT: process.env.PATHEXT || "",
@@ -2254,13 +2286,18 @@ function minimalEnv({ codexHome = null } = {}) {
 
 function resolveCodexRunner(codexHome) {
   if (resolvedCodexRunner) return resolvedCodexRunner;
-  const searchPath = String(process.env.Path || process.env.PATH || "");
+  const searchPath = String((macPackage ? process.env.PATH : process.env.Path || process.env.PATH) || "");
   let sawLoaderCandidate = false;
   let sawNativeCandidate = false;
   for (const rawEntry of searchPath.split(path.delimiter)) {
     try {
       const logical = rawEntry.trim().replace(/^"(.*)"$/, "$1");
       if (!logical || !path.isAbsolute(logical)) continue;
+      if (macPackage) {
+        const runner = probeMacCodex(path.join(logical, "codex"), codexHome);
+        if (runner) return (resolvedCodexRunner = runner);
+        continue;
+      }
       // nvm/fnm and user profile mappings can put a junction on PATH. Resolve
       // that directory once, then retain the ordinary-file checks below it.
       const entry = realpathSync(path.resolve(logical));
@@ -2314,6 +2351,15 @@ function resolveCodexRunner(codexHome) {
 }
 
 function resolveCodexDesktopRunner(codexHome) {
+  if (macPackage) {
+    for (const directory of ["/Applications", path.join(os.homedir(), "Applications")]) {
+      for (const app of ["ChatGPT.app", "Codex.app"]) {
+        const runner = probeMacCodex(path.join(directory, app, "Contents", "Resources", "codex"), codexHome);
+        if (runner) return runner;
+      }
+    }
+    return null;
+  }
   if (process.platform !== "win32") return null;
   const systemRoot = process.env.SystemRoot || process.env.SYSTEMROOT;
   if (!systemRoot || !path.isAbsolute(systemRoot)) return null;
@@ -2341,6 +2387,22 @@ function resolveCodexDesktopRunner(codexHome) {
   return null;
 }
 
+function probeMacCodex(logicalPath, codexHome) {
+  // npm and Homebrew commonly expose a symlink. Execute the canonical file directly.
+  try {
+    const command = realpathSync(logicalPath);
+    const metadata = lstatSync(command);
+    if (!metadata.isFile() || !(metadata.mode & 0o111)) return null;
+    const result = spawnSync(command, ["--version"], {
+      encoding: "utf8", shell: false, timeout: 5000, env: minimalEnv({ codexHome }),
+    });
+    if (result.status === 0 && /^codex-cli\s+\d+\.\d+\.\d+/u.test(String(result.stdout || "").trim())) {
+      return Object.freeze({ command, argsPrefix: Object.freeze([]), kind: "native" });
+    }
+  } catch { /* Missing or unusable CLI. */ }
+  return null;
+}
+
 function resolveRegularDescendantSync(anchor, anchorRealPath, segments) {
   let observed = anchor;
   for (let index = 0; index < segments.length; index += 1) {
@@ -2520,6 +2582,7 @@ function samePath(left, right) {
     const resolved = normalizeWindowsNamespacePath(value);
     let canonical = resolved;
     try { canonical = realpathSync(resolved); } catch { /* comparison can still reject a missing path */ }
+    if (macPackage) return canonical;
     return normalizeWindowsNamespacePath(canonical).replace(/[\\/]+$/u, "").toLowerCase();
   };
   return normalize(left) === normalize(right);
@@ -2639,7 +2702,9 @@ function helpText() {
     : [[say("安装", "Install"), "init"], [say("连接账号", "Connect an account"), connect],
       [say("更新或修复", "Update or repair"), "setup"], [say("检查", "Check"), "doctor"],
       [say("卸载", "Uninstall"), "uninstall"]];
-  return `${[`HelloLynk for ${CLIENT_NAMES[metadata.client]}${say("（Windows，Node.js 22.16.0+）", " (Windows, Node.js 22.16.0+)")}`,
+  const platform = macPackage ? " (macOS arm64, Node.js 22.16.0+)"
+    : say("（Windows，Node.js 22.16.0+）", " (Windows, Node.js 22.16.0+)");
+  return `${[`HelloLynk for ${CLIENT_NAMES[metadata.client]}${platform}`,
     ...rows.map(([label, args]) => `${label}${say("：", ": ")}${run} ${args}`),
     say("加 --json 输出一行 JSON。", "Add --json for one line of JSON.")].join("\n")}\n`;
 }
@@ -2713,6 +2778,9 @@ function failureText(failure) {
 function failureReason(code, name) {
   if (code === "hellolynk_node_22_16_required") return say("需要 Node.js 22.16 或更高版本。", "Node.js 22.16 or later is required.");
   if (code === "hellolynk_npm_windows_only") return say("只支持 Windows。", "Windows only.");
+  if (code === "hellolynk_npm_platform_unsupported") return say("此安装包适用于 Apple 芯片的 Mac。", "This package requires an Apple silicon Mac.");
+  if (code === "hellolynk_npm_codex_mac_node_required") return say("请将 ChatGPT 安装到「应用程序」，打开 Codex 后再试。",
+    "Install ChatGPT in Applications, open Codex, and try again.");
   if (code === "hellolynk_npm_connect_id_invalid") {
     return say("灵信号不对。请从官网复制从 hellolynk: 开始的完整灵信号。",
       "This HelloLynk ID is not valid. Copy the complete ID, starting with hellolynk:, from the website.");