@zan_team/cli 0.0.2 → 0.0.3

package/README.md

@@ -360,15 +360,31 @@ zan project rpc-key pull
 ```
 
 命令写入当前工作目录中固定的 `ZAN_API_KEY`：已存在时替换，缺少时追加，文件
-不存在时创建。实际生效的测试覆盖 Key 优先，否则从加密 Endpoint 缓存中提取
-服务端下发的 Project Key；不要求选择 Network。命令不接受 Key、stdin、变量名
+不存在时创建。API Key 按环境和 Project ID 独立保存在系统凭据库（macOS Keychain
+等），与 Endpoint 缓存的加密密钥、手动覆盖值分别存储。`pull` 优先使用手动覆盖值，
+否则直接读取所选 Project 已保存的 API Key，不需要读取网络缓存或请求后端。
+
+首次缺失时，CLI 请求该 Project 的网络列表，从首个可识别的 RPC 地址提取 API Key
+并保存到系统凭据库；现有后端接口通过地址携带 Key。刷新网络列表时同步更新保存的
+API Key，服务端不再返回可识别 Key 时移除旧记录。`zan project cache clear` 会同时
+清理当前项目保存的 API Key；退出登录会清理当前环境各项目的 Key 和覆盖值。
+
+API Key 属于所选 Project，不要求选择 Network。未选择 Project 时，交互终端会
+列出项目供选择，非交互模式需使用 `--project <id>` 或先执行 `zan project use <id>`。
+命令不接受 Key、stdin、变量名
 或输出路径，也不会在人工输出、JSON 输出、错误或日志中包含 Key。新文件及更新
 后的文件在 POSIX 系统上使用 `0600` 权限，并通过文件锁和原子替换写入；符号链接
 或非普通 `.env` 会被拒绝。
 
-`pull` 只写 `.env`，不会修改其他环境配置文件。
-它不会检查 Git 跟踪状态或自动更新 `.gitignore`，请自行确保 `.env`
-不会被提交。写入后，任何拥有当前目录读取权限的进程或 Agent 都可能读取这个明文
+`pull` 会确保 `.env` 被 Git 忽略：已有生效规则（包括父目录、通配符和全局规则）时
+不修改 `.gitignore`，否则在当前目录的 `.gitignore` 末尾追加 `/.env`。尚未初始化 Git
+仓库的目录也支持此行为，不会自动创建项目仓库。此检查使用本机 Git；Git 不可用时会提示风险。
+
+若 `.env` 已被 Git 跟踪，或无法检查、更新忽略规则，命令仍写入 Key，并在终端提示
+误提交 Key 的风险；JSON 结果通过 `warnings` 返回同样的提示。已跟踪时可执行
+`git rm --cached -- .env` 取消跟踪，并在提交前检查暂存内容；CLI 不会自动修改 Git
+索引，忽略规则也不能清除历史提交中的内容。其他环境配置文件不会被修改。
+写入后，任何拥有当前目录读取权限的进程或 Agent 都可能读取这个明文
 文件；“不泄露”保证只覆盖该命令自身的参数、输出、错误和日志边界。
 
 管理默认 Project 和 Network：

package/dist/cli.js

@@ -1809,6 +1809,10 @@ function registerProject(program, outputWriter, getRuntimeContext, input, rpcKey
   rpcKey.command("pull").description("Write the active Project RPC API Key to .env").action(async () => {
     const { rpcKeyPullService } = await getRuntimeContext();
     const result = await rpcKeyPullService.pull();
+    for (const warning of result.warnings ?? []) {
+      outputWriter.writeStderr(`Warning: ${warning}
+`);
+    }
     outputWriter.success(
       result,
       "ZAN_API_KEY was written to .env"
@@ -1891,7 +1895,7 @@ function registerSign(program, outputWriter, getRuntimeContext) {
 }
 
 // src/version.ts
-var CLI_VERSION = true ? "0.0.2" : pkg.version;
+var CLI_VERSION = true ? "0.0.3" : pkg.version;
 
 // src/commands/version.ts
 function registerVersion(program, outputWriter) {
@@ -2166,7 +2170,7 @@ var ReadlineProjectPrompt = class {
 
 // src/runtime/context.ts
 import { homedir as readHomedir2 } from "os";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/auth/session-metadata-store.ts
 import { z as z8 } from "zod";
@@ -2630,9 +2634,9 @@ var BrowserFlow = class {
 // src/auth/browser-opener.ts
 import { execFile as nodeExecFile } from "child_process";
 var BrowserOpener = class {
-  constructor(platform = process.platform, execFile = nodeExecFile) {
+  constructor(platform = process.platform, execFile2 = nodeExecFile) {
     this.platform = platform;
-    this.execFile = execFile;
+    this.execFile = execFile2;
   }
   platform;
   execFile;
@@ -5133,7 +5137,7 @@ var NetworkSelector = class {
 };
 
 // src/projects/dotenv-api-key-writer.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 import {
   chmod as nodeChmod2,
   lstat as nodeLstat2,
@@ -5142,7 +5146,111 @@ import {
   rename as nodeRename,
   unlink as nodeUnlink
 } from "fs/promises";
-import { isAbsolute as isAbsolute3, join as join4 } from "path";
+import { isAbsolute as isAbsolute3, join as join5 } from "path";
+
+// src/projects/dotenv-gitignore.ts
+import { execFile } from "child_process";
+import { randomUUID as randomUUID3 } from "crypto";
+import { lstat as lstat4, mkdtemp as mkdtemp2, open as open2, readFile as readFile3, rename as rename2, rm as rm2 } from "fs/promises";
+import { tmpdir } from "os";
+import { join as join4 } from "path";
+import { promisify } from "util";
+var execute = promisify(execFile);
+var UNCONFIRMED_WARNING = "Unable to confirm .env is ignored by Git; there is a risk of committing the API Key. Check Git and .gitignore before committing.";
+function protectionFailure() {
+  return new Error("Unable to verify Git ignore rules.");
+}
+async function appendRule(directory) {
+  const filename = join4(directory, ".gitignore");
+  let current = "";
+  let mode = 420;
+  try {
+    const info = await lstat4(filename);
+    if (!info.isFile() || info.isSymbolicLink()) throw protectionFailure();
+    mode = info.mode & 511;
+    current = await readFile3(filename, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const newline = current.includes("\r\n") ? "\r\n" : "\n";
+  const separator = current.length === 0 || current.endsWith("\n") ? "" : newline;
+  const temporary = join4(directory, `.gitignore.${randomUUID3()}.tmp`);
+  try {
+    const handle = await open2(temporary, "wx", mode);
+    try {
+      await handle.writeFile(`${current}${separator}/.env${newline}`, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename2(temporary, filename);
+  } finally {
+    await rm2(temporary, { force: true });
+  }
+}
+async function ensureDotenvIgnored(directory) {
+  const warnings = [];
+  const env = { ...process.env, LC_ALL: "C" };
+  for (const name of ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR", "GIT_PREFIX"]) {
+    delete env[name];
+  }
+  const git = async (args) => {
+    try {
+      return { code: 0, ...await execute("git", args, {
+        cwd: directory,
+        env,
+        encoding: "utf8",
+        timeout: 1e4,
+        maxBuffer: 64 * 1024
+      }) };
+    } catch (error) {
+      const failure = error;
+      if (typeof failure.code !== "number") throw protectionFailure();
+      return { code: failure.code, stdout: failure.stdout ?? "", stderr: failure.stderr ?? "" };
+    }
+  };
+  let temporaryRepository;
+  try {
+    const repository = await git(["rev-parse", "--is-inside-work-tree"]);
+    let prefix = [];
+    if (repository.code === 0 && repository.stdout.trim() === "true") {
+      const tracked = await git(["ls-files", "--error-unmatch", "--", ".env"]);
+      if (tracked.code === 0) {
+        warnings.push(
+          ".env is already tracked by Git; there is a risk of committing the API Key even with .gitignore. Run: git rm --cached -- .env, and review staged changes before committing."
+        );
+      } else if (tracked.code !== 1) {
+        throw protectionFailure();
+      }
+    } else if (repository.code === 128 && repository.stderr.includes("not a git repository")) {
+      temporaryRepository = await mkdtemp2(join4(tmpdir(), "zan-ignore-"));
+      const initialized = await git(["init", "--bare", "--quiet", "--template=", temporaryRepository]);
+      if (initialized.code !== 0) throw protectionFailure();
+      prefix = [`--git-dir=${temporaryRepository}`, `--work-tree=${directory}`, "-c", "core.bare=false"];
+    } else {
+      throw protectionFailure();
+    }
+    const ignored = await git([...prefix, "check-ignore", "--quiet", "--no-index", "--", ".env"]);
+    if (ignored.code === 0) return warnings;
+    if (ignored.code !== 1) throw protectionFailure();
+    await appendRule(directory);
+    const verified = await git([...prefix, "check-ignore", "--quiet", "--no-index", "--", ".env"]);
+    if (verified.code !== 0) throw protectionFailure();
+  } catch {
+    warnings.push(UNCONFIRMED_WARNING);
+  } finally {
+    if (temporaryRepository !== void 0) {
+      try {
+        await rm2(temporaryRepository, { recursive: true, force: true });
+      } catch {
+        warnings.push("Temporary Git metadata could not be removed; review the system temporary directory.");
+      }
+    }
+  }
+  return warnings;
+}
+
+// src/projects/dotenv-api-key-writer.ts
 var API_KEY_ASSIGNMENT = /^[ \t]*(?:export[ \t]+)?ZAN_API_KEY[ \t]*=/u;
 function unsafeKeyFailure() {
   return new CliFailure(
@@ -5220,7 +5328,7 @@ var DotenvApiKeyWriter = class {
     this.options = options;
     this.platform = options.platform ?? process.platform;
     this.fileSystem = options.fileSystem ?? nodeDotenvApiKeyFileSystem;
-    this.createTemporaryId = options.createTemporaryId ?? randomUUID3;
+    this.createTemporaryId = options.createTemporaryId ?? randomUUID4;
   }
   options;
   platform;
@@ -5234,8 +5342,9 @@ var DotenvApiKeyWriter = class {
     if (!isAbsolute3(this.options.directory)) {
       throw unsafeDotenvPathFailure();
     }
-    const lockPath = join4(this.options.directory, ".env.zan.lock");
+    const lockPath = join5(this.options.directory, ".env.zan.lock");
     let renamed = false;
+    let warnings = [];
     try {
       await this.assertSafeOptionalPath(lockPath);
       const lock = new FileLock(lockPath, {
@@ -5244,11 +5353,15 @@ var DotenvApiKeyWriter = class {
       await lock.withLock(async () => {
         const current = await this.readExistingFile();
         const next = updateApiKeyAssignment(current, parsed.data);
+        warnings = await ensureDotenvIgnored(this.options.directory);
         await this.replaceAtomically(next, () => {
           renamed = true;
         });
       });
     } catch (error) {
+      if (error instanceof CliFailure) {
+        throw error;
+      }
       if (error instanceof UnsafeDotenvPathError) {
         throw unsafeDotenvPathFailure();
       }
@@ -5257,6 +5370,9 @@ var DotenvApiKeyWriter = class {
       }
       throw dotenvWriteFailure();
     }
+    if (warnings.length > 0) {
+      return { warnings };
+    }
   }
   async assertSafeOptionalPath(path) {
     try {
@@ -5272,7 +5388,7 @@ var DotenvApiKeyWriter = class {
     }
   }
   async readExistingFile() {
-    const filename = join4(this.options.directory, ".env");
+    const filename = join5(this.options.directory, ".env");
     await this.assertSafeOptionalPath(filename);
     try {
       return await this.fileSystem.readFile(filename, "utf8");
@@ -5284,8 +5400,8 @@ var DotenvApiKeyWriter = class {
     }
   }
   async replaceAtomically(content, onRenamed) {
-    const filename = join4(this.options.directory, ".env");
-    const temporaryFile = join4(
+    const filename = join5(this.options.directory, ".env");
+    const temporaryFile = join5(
       this.options.directory,
       `.env.${process.pid}.${this.createTemporaryId()}.tmp`
     );
@@ -5479,22 +5595,22 @@ import { posix, win32 } from "path";
 // src/storage/atomic-json.ts
 import {
   chmod as chmod3,
-  lstat as lstat4,
+  lstat as lstat5,
   mkdir as mkdir3,
-  open as open2,
-  readFile as readFile3,
-  rename as rename2,
+  open as open3,
+  readFile as readFile4,
+  rename as rename3,
   unlink as unlink2
 } from "fs/promises";
 import { dirname as dirname2 } from "path";
-import { randomUUID as randomUUID4 } from "crypto";
+import { randomUUID as randomUUID5 } from "crypto";
 var nodeAtomicJsonFileSystem = Object.freeze({
   chmod: chmod3,
-  lstat: lstat4,
+  lstat: lstat5,
   mkdir: mkdir3,
-  open: open2,
-  readFile: readFile3,
-  rename: rename2,
+  open: open3,
+  readFile: readFile4,
+  rename: rename3,
   unlink: unlink2
 });
 function hasErrorCode5(error, code) {
@@ -5538,7 +5654,7 @@ var AtomicJsonStore = class {
     this.filename = filename;
     this.fileSystem = options.fileSystem ?? nodeAtomicJsonFileSystem;
     this.platform = options.platform ?? process.platform;
-    this.createTemporaryId = options.createTemporaryId ?? randomUUID4;
+    this.createTemporaryId = options.createTemporaryId ?? randomUUID5;
   }
   schema;
   filename;
@@ -5840,6 +5956,13 @@ var ProjectEndpointCache = class {
     ).toString("base64url");
     return `endpoint-cache-key-${scope}`;
   }
+  apiKeyAccount(projectId) {
+    const scope = Buffer6.from(
+      `${this.options.environment}:${projectId}`,
+      "utf8"
+    ).toString("base64url");
+    return `project-rpc-key-${scope}`;
+  }
   overrideAccount(projectId) {
     const scope = Buffer6.from(
       `${this.options.environment}:${projectId}`,
@@ -5895,6 +6018,18 @@ var ProjectEndpointCache = class {
       }
       throw error;
     }
+    let apiKey;
+    for (const network of networks) {
+      apiKey = this.extractCredential(network.endpoints.https);
+      if (apiKey !== void 0) {
+        break;
+      }
+    }
+    if (apiKey === void 0) {
+      await this.options.secretStore.delete(this.apiKeyAccount(projectId));
+    } else {
+      await this.options.secretStore.write(this.apiKeyAccount(projectId), apiKey);
+    }
     return networks;
   }
   status(projectId) {
@@ -5903,7 +6038,8 @@ var ProjectEndpointCache = class {
   async clear(projectId) {
     const results = await Promise.allSettled([
       this.options.store.delete(projectId),
-      this.options.secretStore.delete(this.cacheKeyAccount(projectId))
+      this.options.secretStore.delete(this.cacheKeyAccount(projectId)),
+      this.options.secretStore.delete(this.apiKeyAccount(projectId))
     ]);
     const failure = results.find(
       (result) => result.status === "rejected"
@@ -5962,20 +6098,23 @@ var ProjectEndpointCache = class {
       this.overrideAccount(projectId)
     );
     if (override !== null) {
-      const parsed = rpcApiKeySchema.safeParse(override);
-      if (!parsed.success) {
+      const parsed2 = rpcApiKeySchema.safeParse(override);
+      if (!parsed2.success) {
         throw unavailableApiKey();
       }
-      return parsed.data;
+      return parsed2.data;
     }
-    const candidates = (await this.list(projectId)).map(
-      (network) => this.extractCredential(network)
-    );
-    const unique = new Set(candidates);
-    if (candidates.length === 0 || unique.size !== 1) {
+    const account = this.apiKeyAccount(projectId);
+    let key = await this.options.secretStore.read(account);
+    if (key === null) {
+      await this.refresh(projectId);
+      key = await this.options.secretStore.read(account);
+    }
+    const parsed = rpcApiKeySchema.safeParse(key);
+    if (!parsed.success) {
       throw unavailableApiKey();
     }
-    return candidates[0];
+    return parsed.data;
   }
   async applyOverride(projectId, network) {
     const key = await this.options.secretStore.read(
@@ -6032,33 +6171,39 @@ var ProjectEndpointCache = class {
       );
     }
   }
-  extractCredential(network) {
+  extractCredential(endpoint) {
     try {
-      const url = new URL(network.endpoints.https);
+      const url = new URL(endpoint);
       const trustedHost = url.hostname === "zan.top" || url.hostname.endsWith(".zan.top");
       const segments = url.pathname.slice(1).split("/");
       if (url.protocol !== "https:" || !trustedHost || url.port.length > 0 || url.username.length > 0 || url.password.length > 0 || url.search.length > 0 || url.hash.length > 0 || !url.pathname.startsWith("/") || segments.some((segment) => segment.length === 0) || url.pathname !== `/${segments.join("/")}`) {
         throw new Error("unsafe");
       }
-      let candidate;
-      if (network.ecosystem === "hyperliquid") {
-        if (segments.length !== 6 || segments[0] !== "node" || segments[1] !== "v1" || segments[2] !== "hyperliquid" || segments[3] !== network.network || segments[5] !== "evm") {
-          throw new Error("unsafe");
-        }
-        candidate = segments[4];
-      } else {
-        if (segments.length !== 5 || segments[0] !== "node" || segments[1] !== "v1" || !networkIdSchema.safeParse(segments[2]).success || segments[3] !== network.network) {
-          throw new Error("unsafe");
-        }
-        candidate = segments[4];
+      if (segments[0] !== "node" || segments[1] !== "v1" || !networkIdSchema.safeParse(segments[2]).success || !networkIdSchema.safeParse(segments[3]).success) {
+        return void 0;
+      }
+      let suffix = "";
+      switch (segments[2]) {
+        case "hyperliquid":
+          suffix = "evm";
+          break;
+        case "avax":
+          suffix = "ext/bc/C/rpc";
+          break;
+        case "tron":
+          suffix = "jsonrpc";
+          break;
       }
-      const parsed = rpcApiKeySchema.safeParse(candidate);
+      if (segments.slice(5).join("/") !== suffix) {
+        return void 0;
+      }
+      const parsed = rpcApiKeySchema.safeParse(segments[4]);
       if (!parsed.success) {
         throw new Error("unsafe");
       }
       return parsed.data;
     } catch {
-      throw unavailableApiKey();
+      return void 0;
     }
   }
 };
@@ -6072,21 +6217,22 @@ var RpcKeyPullService = class {
   async pull() {
     const projectId = await this.dependencies.projects.activeId();
     const key = await this.dependencies.keys.effectiveApiKey(projectId);
-    await this.dependencies.writer.write(key);
+    const result = await this.dependencies.writer.write(key);
     return {
       file: ".env",
       variable: "ZAN_API_KEY",
-      updated: true
+      updated: true,
+      ...result?.warnings.length ? { warnings: result.warnings } : {}
     };
   }
 };
 
 // src/projects/project-service.ts
-import { randomUUID as randomUUID5 } from "crypto";
+import { randomUUID as randomUUID6 } from "crypto";
 var ProjectService = class {
   constructor(options) {
     this.options = options;
-    this.createIdempotencyKey = options.createIdempotencyKey ?? randomUUID5;
+    this.createIdempotencyKey = options.createIdempotencyKey ?? randomUUID6;
   }
   options;
   createIdempotencyKey;
@@ -6480,7 +6626,7 @@ var SettingsStore = class {
 };
 
 // src/settings/paths.ts
-import { join as join5, posix as posix2, win32 as win322 } from "path";
+import { join as join6, posix as posix2, win32 as win322 } from "path";
 function nonEmpty(value) {
   return value === void 0 || value.length === 0 ? void 0 : value;
 }
@@ -6513,7 +6659,7 @@ function resolveZanHome(env, platform, homedir2) {
   }
   if (platform === "darwin") {
     return validateHomePath(
-      join5(readHomedir(homedir2), "Library", "Application Support", "zan"),
+      join6(readHomedir(homedir2), "Library", "Application Support", "zan"),
       platform
     );
   }
@@ -7336,7 +7482,7 @@ function createRuntimeContext(input) {
     walletService ??= new WalletService({
       index: new AtomicJsonStore(
         walletIndexSchema,
-        join6(home, "wallets.json"),
+        join7(home, "wallets.json"),
         { platform }
       ),
       secrets: secretStore,
@@ -7652,4 +7798,3 @@ export {
   isMainModule,
   runCli
 };
-//# sourceMappingURL=cli.js.map

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@zan_team/cli",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Unified ZAN command-line interface for developers, automation, and AI agents",
   "type": "module",
   "bin": {
     "zan": "./dist/cli.js"
   },
   "files": [
-    "dist",
+    "dist/cli.js",
     "skills",
     "README.md"
   ],