@gong-ym/ai-spec-auto 0.2.13 → 0.2.15

package/bin/telemetry/README.md

@@ -1,66 +1,66 @@
-# bin/telemetry
-
-可选的匿名遥测切面（aspect），用于向 `br-ai-spec-visual` 上报 CLI 安装与使用情况。
-
-## 设计原则
-
-- **零侵入**：主流程 (`bin/cli.js`、`bin/install-workflow.js` 等) 不依赖本目录。删除整个 `bin/telemetry/` 目录后 CLI 仍可正常工作。
-- **降级四重保护**：
-  1. `bin/cli.js` 中 `require('./telemetry')` 失败 → 使用透明 wrap，不上报。
-  2. `index.js` 再次 try/catch 保护，阻止任何异常冒泡。
-  3. **健康探测兜底**：上报前先 `HEAD /api/health`（500ms 超时），目标不可达直接跳过本次所有上报；探测失败时间记入本地缓存，60 秒冷却窗口内的后续 CLI 调用直接跳过探测。
-  4. 网络上报 fire-and-forget + `AbortController(2000ms)`，绝不阻塞 `process.exit`。
-- **可选依赖**：`node-machine-id` 放在 `optionalDependencies`，缺失时用纯 Node `os` 模块 + `sha256` 兜底。
-- **用户可关闭**：`AI_SPEC_TELEMETRY_DISABLED=1` 禁用；`AI_SPEC_VISUAL_URL` 未设置时不发网络请求。
-
-## 文件
-
-| 文件 | 作用 |
-| --- | --- |
-| `index.js` | 对外唯一入口，导出 `wrap(command, fn)`。 |
-| `aspect.js` | 切面实现：在命令前后异步上报 started / success / failed。 |
-| `reporter.js` | REST / WS 上报；AbortController + 超时 + 静默失败。 |
-| `identity.js` | 生成 installationId（node-machine-id → sha256(mac+user+host) 兜底）。 |
-| `collect.js` | 收集非敏感字段（hostname/platform/node/cliVersion/projectHash/profile…）。 |
-| `config.js` | 读取环境变量 + 用户配置 + 仓库默认，三层合并。 |
-| `defaults.json` | 仓库内默认配置（仅 `visualUrl` / `disabled`，**禁止写入 secret**）。 |
-| `healthcheck.js` | 发送前探测 `HEAD /api/health`（500ms 超时，进程内缓存，失败 60s 冷却）。 |
-| `safe.js` | 统一兜底工具 (safeCall, safeRequire)。 |
-
-## 配置来源（优先级由高到低）
-
-1. **环境变量**（临时调试、CI 注入首选）
-2. **`~/.ai-spec-auto/config.json`**（用户主目录，个人本地覆盖，可存 secret）
-3. **`bin/telemetry/defaults.json`**（仓库默认，跟随 npm 包发布；**仅放公开字段**）
-
-### 可配置字段
-
-| 字段 | 环境变量 | 用户配置 key | 仓库默认 | 说明 |
-| --- | --- | --- | --- | --- |
-| Visual 地址 | `AI_SPEC_VISUAL_URL` | `visualUrl` | `visualUrl` | 未设置/为空则不发请求 |
-| 总开关 | `AI_SPEC_TELEMETRY_DISABLED=1` | `disabled: true` | `disabled` | 任一源为 true 即关闭 |
-| 鉴权密钥 | `AI_SPEC_TELEMETRY_SECRET` | `secret` | **不支持** | 与服务端 `.env` 一致；仓库绝不写入 |
-| 调试输出 | `AI_SPEC_TELEMETRY_DEBUG=1` | — | — | 仅环境变量，便于排查 |
-
-### 用户配置示例
-
-```jsonc
-// ~/.ai-spec-auto/config.json
-{
-  "visualUrl": "http://127.0.0.1:3000",   // 本地联调时覆盖为本机
-  "secret": "与服务端 .env 中的 AI_SPEC_TELEMETRY_SECRET 一致",
-  "disabled": false
-}
-```
-
-- 文件不存在或格式错误 → 静默回退到仓库默认，不影响 CLI。
-- 权限建议：`chmod 600 ~/.ai-spec-auto/config.json`（含 secret 时）。
-
-### 典型场景
-
-| 场景 | 做法 |
-| --- | --- |
-| 使用线上 Visual（`82.156.14.216:3001`），无 secret | **什么都不用设**，装包即走仓库默认 |
-| 使用线上 Visual + 需要 secret | 在 `~/.ai-spec-auto/config.json` 写入 `secret`，或导出 `AI_SPEC_TELEMETRY_SECRET` |
-| 本地联调，想打到本机 Visual | `export AI_SPEC_VISUAL_URL=http://127.0.0.1:3000`（或写入用户配置） |
-| 不想参与匿名统计 | `export AI_SPEC_TELEMETRY_DISABLED=1`（或用户配置 `disabled: true`） |
+# bin/telemetry
+
+可选的匿名遥测切面（aspect），用于向 `br-ai-spec-visual` 上报 CLI 安装与使用情况。
+
+## 设计原则
+
+- **零侵入**：主流程 (`bin/cli.js`、`bin/install-workflow.js` 等) 不依赖本目录。删除整个 `bin/telemetry/` 目录后 CLI 仍可正常工作。
+- **降级四重保护**：
+  1. `bin/cli.js` 中 `require('./telemetry')` 失败 → 使用透明 wrap，不上报。
+  2. `index.js` 再次 try/catch 保护，阻止任何异常冒泡。
+  3. **健康探测兜底**：上报前先 `HEAD /api/health`（500ms 超时），目标不可达直接跳过本次所有上报；探测失败时间记入本地缓存，60 秒冷却窗口内的后续 CLI 调用直接跳过探测。
+  4. 网络上报 fire-and-forget + `AbortController(2000ms)`，绝不阻塞 `process.exit`。
+- **可选依赖**：`node-machine-id` 放在 `optionalDependencies`，缺失时用纯 Node `os` 模块 + `sha256` 兜底。
+- **用户可关闭**：`AI_SPEC_TELEMETRY_DISABLED=1` 禁用；`AI_SPEC_VISUAL_URL` 未设置时不发网络请求。
+
+## 文件
+
+| 文件 | 作用 |
+| --- | --- |
+| `index.js` | 对外唯一入口，导出 `wrap(command, fn)`。 |
+| `aspect.js` | 切面实现：在命令前后异步上报 started / success / failed。 |
+| `reporter.js` | REST / WS 上报；AbortController + 超时 + 静默失败。 |
+| `identity.js` | 生成 installationId（node-machine-id → sha256(mac+user+host) 兜底）。 |
+| `collect.js` | 收集非敏感字段（hostname/platform/node/cliVersion/projectHash/profile…）。 |
+| `config.js` | 读取环境变量 + 用户配置 + 仓库默认，三层合并。 |
+| `defaults.json` | 仓库内默认配置（仅 `visualUrl` / `disabled`，**禁止写入 secret**）。 |
+| `healthcheck.js` | 发送前探测 `HEAD /api/health`（500ms 超时，进程内缓存，失败 60s 冷却）。 |
+| `safe.js` | 统一兜底工具 (safeCall, safeRequire)。 |
+
+## 配置来源（优先级由高到低）
+
+1. **环境变量**（临时调试、CI 注入首选）
+2. **`~/.ai-spec-auto/config.json`**（用户主目录，个人本地覆盖，可存 secret）
+3. **`bin/telemetry/defaults.json`**（仓库默认，跟随 npm 包发布；**仅放公开字段**）
+
+### 可配置字段
+
+| 字段 | 环境变量 | 用户配置 key | 仓库默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| Visual 地址 | `AI_SPEC_VISUAL_URL` | `visualUrl` | `visualUrl` | 未设置/为空则不发请求 |
+| 总开关 | `AI_SPEC_TELEMETRY_DISABLED=1` | `disabled: true` | `disabled` | 任一源为 true 即关闭 |
+| 鉴权密钥 | `AI_SPEC_TELEMETRY_SECRET` | `secret` | **不支持** | 与服务端 `.env` 一致；仓库绝不写入 |
+| 调试输出 | `AI_SPEC_TELEMETRY_DEBUG=1` | — | — | 仅环境变量，便于排查 |
+
+### 用户配置示例
+
+```jsonc
+// ~/.ai-spec-auto/config.json
+{
+  "visualUrl": "http://127.0.0.1:3000",   // 本地联调时覆盖为本机
+  "secret": "与服务端 .env 中的 AI_SPEC_TELEMETRY_SECRET 一致",
+  "disabled": false
+}
+```
+
+- 文件不存在或格式错误 → 静默回退到仓库默认，不影响 CLI。
+- 权限建议：`chmod 600 ~/.ai-spec-auto/config.json`（含 secret 时）。
+
+### 典型场景
+
+| 场景 | 做法 |
+| --- | --- |
+| 使用线上 Visual（`82.156.14.216:3001`），无 secret | **什么都不用设**，装包即走仓库默认 |
+| 使用线上 Visual + 需要 secret | 在 `~/.ai-spec-auto/config.json` 写入 `secret`，或导出 `AI_SPEC_TELEMETRY_SECRET` |
+| 本地联调，想打到本机 Visual | `export AI_SPEC_VISUAL_URL=http://127.0.0.1:3000`（或写入用户配置） |
+| 不想参与匿名统计 | `export AI_SPEC_TELEMETRY_DISABLED=1`（或用户配置 `disabled: true`） |

package/bin/telemetry/aspect.js

@@ -1,153 +1,153 @@
-'use strict';
-
-const path = require('path');
-const { collectCommon } = require('./collect');
-const { getConfig, markNoticeShown } = require('./config');
-const { resolveInstallationId } = require('./identity');
-const { fireAndForget } = require('./reporter');
-const { debugLog, safeCall, safeRequire } = require('./safe');
-
-const healthcheck = safeRequire('./healthcheck');
-
-const PKG_ROOT = path.join(__dirname, '..', '..');
-
-function maybePrintFirstNotice(config) {
-  if (!config.enabled) return;
-  safeCall(function () {
-    if (markNoticeShown()) {
-      process.stderr.write(
-        '[ai-spec-auto] 已开启匿名使用统计（可通过 AI_SPEC_TELEMETRY_DISABLED=1 关闭）\n',
-      );
-    }
-  });
-}
-
-function buildPayload(command, status, extra) {
-  const base = collectCommon({ cwd: process.cwd(), pkgRoot: PKG_ROOT });
-  const payload = {
-    installationId: resolveInstallationId(),
-    command: String(command || 'unknown').slice(0, 64),
-    status: String(status).slice(0, 32),
-    hostname: base.hostname,
-    username: base.username,
-    platform: base.platform,
-    arch: base.arch,
-    osRelease: base.osRelease,
-    nodeVersion: base.nodeVersion,
-    cliVersion: base.cliVersion,
-    profile: base.profile,
-    ides: base.ides,
-    level: base.level,
-    projectHash: base.projectHash,
-    projectName: base.projectName,
-    occurredAt: new Date().toISOString(),
-  };
-  if (extra && typeof extra === 'object') {
-    if (typeof extra.durationMs === 'number') payload.durationMs = extra.durationMs;
-    if (typeof extra.errorMessage === 'string') {
-      payload.errorMessage = extra.errorMessage.slice(0, 2000);
-    }
-  }
-  return payload;
-}
-
-function wrap(command, fn) {
-  if (typeof fn !== 'function') {
-    throw new TypeError('telemetry.wrap: fn must be a function');
-  }
-  const config = getConfig();
-  if (!config.enabled) {
-    debugLog('wrap: telemetry disabled, pass-through');
-    return fn();
-  }
-
-  safeCall(function () {
-    maybePrintFirstNotice(config);
-  });
-
-  // 预热健康探测（不 await，结果会被 reporter 里的 ensureReachable 复用）。
-  // 这样 reporter 发 POST 前的健康查询要么已完成、要么已在进行中。
-  safeCall(function () {
-    if (healthcheck && typeof healthcheck.ensureReachable === 'function') {
-      const p = healthcheck.ensureReachable(config.visualUrl);
-      if (p && typeof p.catch === 'function') p.catch(function () {});
-    }
-  });
-
-  const pending = [];
-  function track(p) {
-    if (p && typeof p.then === 'function') pending.push(p);
-  }
-  function flushPending() {
-    if (pending.length === 0) return Promise.resolve();
-    const all = Promise.allSettled(pending.splice(0, pending.length));
-    // 上限 1500ms：覆盖 HEAD 健康探测（最多 500ms）+ POST 落地（一般 <500ms）
-    // 的组合路径，同时保证即使网络故障也不会明显拖慢 CLI 退出。
-    const env = process.env || {};
-    const raw = env.AI_SPEC_TELEMETRY_FLUSH_MS;
-    const parsed = raw ? parseInt(raw, 10) : NaN;
-    const cap = Number.isFinite(parsed) && parsed >= 100 && parsed <= 5000 ? parsed : 1500;
-    return Promise.race([
-      all,
-      new Promise(function (resolve) {
-        const t = setTimeout(resolve, cap);
-        if (typeof t.unref === 'function') t.unref();
-      }),
-    ]);
-  }
-
-  safeCall(function () {
-    track(fireAndForget(buildPayload(command, 'started')));
-  });
-
-  const startedAt = Date.now();
-  let result;
-  try {
-    result = fn();
-  } catch (error) {
-    safeCall(function () {
-      track(fireAndForget(
-        buildPayload(command, 'failed', {
-          durationMs: Date.now() - startedAt,
-          errorMessage: error && error.message ? String(error.message) : String(error),
-        }),
-      ));
-    });
-    return flushPending().then(function () { throw error; });
-  }
-
-  if (result && typeof result.then === 'function') {
-    return result.then(
-      function (value) {
-        safeCall(function () {
-          track(fireAndForget(
-            buildPayload(command, 'success', {
-              durationMs: Date.now() - startedAt,
-            }),
-          ));
-        });
-        return flushPending().then(function () { return value; });
-      },
-      function (error) {
-        safeCall(function () {
-          track(fireAndForget(
-            buildPayload(command, 'failed', {
-              durationMs: Date.now() - startedAt,
-              errorMessage: error && error.message ? String(error.message) : String(error),
-            }),
-          ));
-        });
-        return flushPending().then(function () { throw error; });
-      },
-    );
-  }
-
-  safeCall(function () {
-    track(fireAndForget(
-      buildPayload(command, 'success', { durationMs: Date.now() - startedAt }),
-    ));
-  });
-  return flushPending().then(function () { return result; });
-}
-
-module.exports = { wrap };
+'use strict';
+
+const path = require('path');
+const { collectCommon } = require('./collect');
+const { getConfig, markNoticeShown } = require('./config');
+const { resolveInstallationId } = require('./identity');
+const { fireAndForget } = require('./reporter');
+const { debugLog, safeCall, safeRequire } = require('./safe');
+
+const healthcheck = safeRequire('./healthcheck');
+
+const PKG_ROOT = path.join(__dirname, '..', '..');
+
+function maybePrintFirstNotice(config) {
+  if (!config.enabled) return;
+  safeCall(function () {
+    if (markNoticeShown()) {
+      process.stderr.write(
+        '[ai-spec-auto] 已开启匿名使用统计（可通过 AI_SPEC_TELEMETRY_DISABLED=1 关闭）\n',
+      );
+    }
+  });
+}
+
+function buildPayload(command, status, extra) {
+  const base = collectCommon({ cwd: process.cwd(), pkgRoot: PKG_ROOT });
+  const payload = {
+    installationId: resolveInstallationId(),
+    command: String(command || 'unknown').slice(0, 64),
+    status: String(status).slice(0, 32),
+    hostname: base.hostname,
+    username: base.username,
+    platform: base.platform,
+    arch: base.arch,
+    osRelease: base.osRelease,
+    nodeVersion: base.nodeVersion,
+    cliVersion: base.cliVersion,
+    profile: base.profile,
+    ides: base.ides,
+    level: base.level,
+    projectHash: base.projectHash,
+    projectName: base.projectName,
+    occurredAt: new Date().toISOString(),
+  };
+  if (extra && typeof extra === 'object') {
+    if (typeof extra.durationMs === 'number') payload.durationMs = extra.durationMs;
+    if (typeof extra.errorMessage === 'string') {
+      payload.errorMessage = extra.errorMessage.slice(0, 2000);
+    }
+  }
+  return payload;
+}
+
+function wrap(command, fn) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('telemetry.wrap: fn must be a function');
+  }
+  const config = getConfig();
+  if (!config.enabled) {
+    debugLog('wrap: telemetry disabled, pass-through');
+    return fn();
+  }
+
+  safeCall(function () {
+    maybePrintFirstNotice(config);
+  });
+
+  // 预热健康探测（不 await，结果会被 reporter 里的 ensureReachable 复用）。
+  // 这样 reporter 发 POST 前的健康查询要么已完成、要么已在进行中。
+  safeCall(function () {
+    if (healthcheck && typeof healthcheck.ensureReachable === 'function') {
+      const p = healthcheck.ensureReachable(config.visualUrl);
+      if (p && typeof p.catch === 'function') p.catch(function () {});
+    }
+  });
+
+  const pending = [];
+  function track(p) {
+    if (p && typeof p.then === 'function') pending.push(p);
+  }
+  function flushPending() {
+    if (pending.length === 0) return Promise.resolve();
+    const all = Promise.allSettled(pending.splice(0, pending.length));
+    // 上限 1500ms：覆盖 HEAD 健康探测（最多 500ms）+ POST 落地（一般 <500ms）
+    // 的组合路径，同时保证即使网络故障也不会明显拖慢 CLI 退出。
+    const env = process.env || {};
+    const raw = env.AI_SPEC_TELEMETRY_FLUSH_MS;
+    const parsed = raw ? parseInt(raw, 10) : NaN;
+    const cap = Number.isFinite(parsed) && parsed >= 100 && parsed <= 5000 ? parsed : 1500;
+    return Promise.race([
+      all,
+      new Promise(function (resolve) {
+        const t = setTimeout(resolve, cap);
+        if (typeof t.unref === 'function') t.unref();
+      }),
+    ]);
+  }
+
+  safeCall(function () {
+    track(fireAndForget(buildPayload(command, 'started')));
+  });
+
+  const startedAt = Date.now();
+  let result;
+  try {
+    result = fn();
+  } catch (error) {
+    safeCall(function () {
+      track(fireAndForget(
+        buildPayload(command, 'failed', {
+          durationMs: Date.now() - startedAt,
+          errorMessage: error && error.message ? String(error.message) : String(error),
+        }),
+      ));
+    });
+    return flushPending().then(function () { throw error; });
+  }
+
+  if (result && typeof result.then === 'function') {
+    return result.then(
+      function (value) {
+        safeCall(function () {
+          track(fireAndForget(
+            buildPayload(command, 'success', {
+              durationMs: Date.now() - startedAt,
+            }),
+          ));
+        });
+        return flushPending().then(function () { return value; });
+      },
+      function (error) {
+        safeCall(function () {
+          track(fireAndForget(
+            buildPayload(command, 'failed', {
+              durationMs: Date.now() - startedAt,
+              errorMessage: error && error.message ? String(error.message) : String(error),
+            }),
+          ));
+        });
+        return flushPending().then(function () { throw error; });
+      },
+    );
+  }
+
+  safeCall(function () {
+    track(fireAndForget(
+      buildPayload(command, 'success', { durationMs: Date.now() - startedAt }),
+    ));
+  });
+  return flushPending().then(function () { return result; });
+}
+
+module.exports = { wrap };

package/bin/telemetry/collect.js

@@ -1,67 +1,67 @@
-'use strict';
-
-const crypto = require('crypto');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { safeCall } = require('./safe');
-
-function readJson(file) {
-  return safeCall(function () {
-    const raw = fs.readFileSync(file, 'utf8');
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === 'object' ? parsed : null;
-  }, null);
-}
-
-function readCliVersion(pkgRoot) {
-  if (!pkgRoot) return null;
-  const pkg = readJson(path.join(pkgRoot, 'package.json'));
-  return pkg && typeof pkg.version === 'string' ? pkg.version : null;
-}
-
-function readProjectMeta(cwd) {
-  if (!cwd || typeof cwd !== 'string') {
-    return { projectHash: null, projectName: null };
-  }
-  const hash = crypto.createHash('sha256').update(cwd).digest('hex').slice(0, 32);
-  const pkg = readJson(path.join(cwd, 'package.json'));
-  const name = pkg && typeof pkg.name === 'string' ? pkg.name.slice(0, 200) : null;
-  return { projectHash: hash, projectName: name };
-}
-
-function readInstallState(cwd) {
-  if (!cwd) return null;
-  return readJson(path.join(cwd, '.ai-spec', 'install-state.json'));
-}
-
-function pickString(value) {
-  return typeof value === 'string' ? value : null;
-}
-
-function collectCommon(options) {
-  const opts = options || {};
-  const cwd = opts.cwd || process.cwd();
-  const userInfo = safeCall(function () {
-    return os.userInfo();
-  }, {});
-  const state = readInstallState(cwd);
-  const project = readProjectMeta(cwd);
-
-  return {
-    hostname: safeCall(function () { return os.hostname(); }, null),
-    username: userInfo && userInfo.username ? String(userInfo.username).slice(0, 128) : null,
-    platform: safeCall(function () { return os.platform(); }, null),
-    arch: safeCall(function () { return os.arch(); }, null),
-    osRelease: safeCall(function () { return os.release(); }, null),
-    nodeVersion: process.version,
-    cliVersion: readCliVersion(opts.pkgRoot),
-    profile: state ? pickString(state.profile) : null,
-    ides: state && Array.isArray(state.ides) ? state.ides : null,
-    level: state ? pickString(state.level) : null,
-    projectHash: project.projectHash,
-    projectName: project.projectName,
-  };
-}
-
-module.exports = { collectCommon };
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { safeCall } = require('./safe');
+
+function readJson(file) {
+  return safeCall(function () {
+    const raw = fs.readFileSync(file, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  }, null);
+}
+
+function readCliVersion(pkgRoot) {
+  if (!pkgRoot) return null;
+  const pkg = readJson(path.join(pkgRoot, 'package.json'));
+  return pkg && typeof pkg.version === 'string' ? pkg.version : null;
+}
+
+function readProjectMeta(cwd) {
+  if (!cwd || typeof cwd !== 'string') {
+    return { projectHash: null, projectName: null };
+  }
+  const hash = crypto.createHash('sha256').update(cwd).digest('hex').slice(0, 32);
+  const pkg = readJson(path.join(cwd, 'package.json'));
+  const name = pkg && typeof pkg.name === 'string' ? pkg.name.slice(0, 200) : null;
+  return { projectHash: hash, projectName: name };
+}
+
+function readInstallState(cwd) {
+  if (!cwd) return null;
+  return readJson(path.join(cwd, '.ai-spec', 'install-state.json'));
+}
+
+function pickString(value) {
+  return typeof value === 'string' ? value : null;
+}
+
+function collectCommon(options) {
+  const opts = options || {};
+  const cwd = opts.cwd || process.cwd();
+  const userInfo = safeCall(function () {
+    return os.userInfo();
+  }, {});
+  const state = readInstallState(cwd);
+  const project = readProjectMeta(cwd);
+
+  return {
+    hostname: safeCall(function () { return os.hostname(); }, null),
+    username: userInfo && userInfo.username ? String(userInfo.username).slice(0, 128) : null,
+    platform: safeCall(function () { return os.platform(); }, null),
+    arch: safeCall(function () { return os.arch(); }, null),
+    osRelease: safeCall(function () { return os.release(); }, null),
+    nodeVersion: process.version,
+    cliVersion: readCliVersion(opts.pkgRoot),
+    profile: state ? pickString(state.profile) : null,
+    ides: state && Array.isArray(state.ides) ? state.ides : null,
+    level: state ? pickString(state.level) : null,
+    projectHash: project.projectHash,
+    projectName: project.projectName,
+  };
+}
+
+module.exports = { collectCommon };