kld-sdd 2.6.17 → 2.6.21

package/skywalk-sdd/lib/usage-reporter.cjs

@@ -0,0 +1,354 @@
+// kld-T04 — 使用事件 reporter（kld-fixback RED#2/#4/#9 重构版）
+// 职责：单一 3s deadline；pending JSONL 原子追加；100 条上限；1MB 淘汰；
+//       HTTP 状态分类（confirmed/retry/unauthorized/drop）；401 原子清除 token；
+//       并发安全（appendFileSync O_APPEND + 事件 id 差集提交）；不改原业务退出码。
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const {
+  normalizeServerUrl,
+  classifyUsageSubmitResponse,
+  postJson,
+  mapCommandToUsageSkill,
+} = require('./usage-contract.cjs');
+const {
+  readUserConfig,
+  clearUserToken,
+} = require('./user-config.cjs');
+
+const PENDING_FILE_NAME = 'pending-usage.jsonl';
+const PENDING_MAX_BYTES = 1024 * 1024; // 1 MB
+const FLUSH_MAX_COUNT = 100;
+const SHARED_DEADLINE_MS = 3000;
+// 单行事件 JSON 的安全上限（小于 4KB 以保证 appendFileSync 在 POSIX/Windows 都原子）
+const SINGLE_EVENT_MAX_BYTES = 4096;
+
+function pendingPathFor(homeDir) {
+  const envHome = typeof process !== 'undefined' && process && process.env
+    ? process.env.KLD_SDD_HOME
+    : undefined;
+  const home = homeDir || envHome || require('node:os').homedir();
+  return path.join(home, '.kld-sdd', PENDING_FILE_NAME);
+}
+
+/**
+ * 生成事件唯一 id（基于时间戳 + pid + 随机字节）。
+ * 用于 flush 提交时按 id 差集删除已确认行，避免 read-modify-write 覆盖并发 append。
+ */
+function generateEventId() {
+  return `ue_${Date.now().toString(36)}_${process.pid.toString(36)}_${crypto.randomBytes(4).toString('hex')}`;
+}
+
+/**
+ * 为没有 id 字段的旧事件规范化一个 id（基于内容 hash）。
+ * 同一行多次读出会得到同一个 id，使 flush 差集提交对旧 fixture 兼容。
+ */
+function ensureEventId(event) {
+  if (event && typeof event === 'object') {
+    if (typeof event.id === 'string' && event.id) return event;
+    const hash = crypto
+      .createHash('sha1')
+      .update(JSON.stringify(event))
+      .digest('hex')
+      .slice(0, 12);
+    return Object.assign({}, event, { id: `legacy_${hash}` });
+  }
+  return event;
+}
+
+/**
+ * 读取 pending 队列。
+ * - 尾部半行 / 损坏行被隔离：跳过但不污染合法记录
+ * - 没有 id 的旧事件会被规范化一个内容 hash id
+ * - 返回 { events, corrupted }
+ */
+function readPending(filePath) {
+  if (!fs.existsSync(filePath)) return { events: [], corrupted: 0 };
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return { events: [], corrupted: 0 };
+  }
+  if (!raw) return { events: [], corrupted: 0 };
+  const lines = raw.split('\n');
+  const events = [];
+  let corrupted = 0;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed && typeof parsed === 'object' && typeof parsed.skill === 'string') {
+        events.push(ensureEventId(parsed));
+      } else {
+        corrupted += 1;
+      }
+    } catch {
+      corrupted += 1;
+    }
+  }
+  return { events, corrupted };
+}
+
+/**
+ * 原子重写 pending 文件：先 temp 后 rename。
+ * 仅在 flush 提交时调用；并发 append 的新行必须在重写前重新读入并按 id 保留。
+ */
+function writePendingAtomic(filePath, events) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  if (!events || events.length === 0) {
+    try { fs.unlinkSync(filePath); } catch { /* ignore */ }
+    return;
+  }
+  const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+  const payload = events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+  fs.writeFileSync(tmp, payload, 'utf8');
+  try {
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+/**
+ * 追加事件到 pending 队列。
+ * - 用 fs.appendFileSync 单行追加：POSIX O_APPEND 对小行原子；Windows 对 <4KB append 也原子
+ * - 超 1MB 时先重读并按需淘汰最旧完整行（O(n)：先算总大小，每次 shift 只减对应字节）
+ * - 事件自动补 id（如未含）
+ */
+function appendPending(event, filePath) {
+  if (!event || typeof event !== 'object') return;
+  const target = filePath || pendingPathFor();
+  const dir = path.dirname(target);
+  fs.mkdirSync(dir, { recursive: true });
+
+  // 自动补 id（用于 flush 差集删除）
+  const toAppend = Object.assign({}, event);
+  if (typeof toAppend.id !== 'string' || !toAppend.id) {
+    toAppend.id = generateEventId();
+  }
+  const line = JSON.stringify(toAppend) + '\n';
+  const lineBytes = Buffer.byteLength(line, 'utf8');
+  if (lineBytes > SINGLE_EVENT_MAX_BYTES) {
+    // 防御：单行超 4KB 直接丢弃（不应发生；正常事件 <200 字节）
+    return;
+  }
+
+  // 先检查追加后是否超 1MB；超则先淘汰
+  let existingSize = 0;
+  let existingEvents = [];
+  if (fs.existsSync(target)) {
+    const { events } = readPending(target);
+    existingEvents = events;
+    for (const e of events) {
+      existingSize += Buffer.byteLength(JSON.stringify(e), 'utf8') + 1;
+    }
+  }
+  if (existingSize + lineBytes > PENDING_MAX_BYTES) {
+    // O(n) 淘汰：先算总大小，每次 shift 只减对应字节
+    let currentSize = existingSize;
+    let dropCount = 0;
+    while (dropCount < existingEvents.length && currentSize + lineBytes > PENDING_MAX_BYTES) {
+      const evicted = existingEvents[dropCount];
+      currentSize -= (Buffer.byteLength(JSON.stringify(evicted), 'utf8') + 1);
+      dropCount += 1;
+    }
+    if (dropCount > 0) {
+      const retained = existingEvents.slice(dropCount);
+      // 原子重写（淘汰后才需要 rewrite；此后 append 当前行）
+      writePendingAtomic(target, retained);
+    }
+  }
+  // 原子 append（POSIX O_APPEND；Windows 单行 <4KB 也原子）
+  try {
+    fs.appendFileSync(target, line, 'utf8');
+  } catch {
+    // append 失败时静默（不改原业务退出码）
+  }
+}
+
+/**
+ * 提交单条事件；返回分类。
+ * @returns {Promise<'confirmed'|'unauthorized'|'retry'|'drop'>}
+ */
+async function submitOne(server, token, event, timeoutMs) {
+  // 提交时剔除内部 id（不上传给服务端）
+  const outgoing = Object.assign({}, event);
+  delete outgoing.id;
+  const result = await postJson(
+    `${server}/api/v1/usage-events`,
+    outgoing,
+    { token, timeoutMs },
+  );
+  return classifyUsageSubmitResponse(result.statusCode);
+}
+
+/**
+ * 上报一次使用事件（主入口）。任何失败均不抛。
+ *
+ * @param {object} options
+ * @param {string} options.skill — 七值之一；非七值立即返回
+ * @param {string} [options.startedAt] — ISO8601；缺省取当前
+ * @param {string} [options.homeDir] — 测试注入
+ * @param {Function} [options.onNotify] — 401 等用户提示
+ * @returns {Promise<{submitted:number,enqueued:boolean,tokenCleared:boolean,skipped:boolean}>}
+ */
+async function reportUsageOnce(options = {}) {
+  const result = { submitted: 0, enqueued: false, tokenCleared: false, skipped: false };
+  const skill = mapCommandToUsageSkill(options.skill);
+  if (!skill) {
+    result.skipped = true;
+    return result;
+  }
+  const onNotify = typeof options.onNotify === 'function' ? options.onNotify : () => {};
+
+  try {
+    const config = readUserConfig(options.homeDir);
+    if (!config || typeof config.token !== 'string' || !config.token) {
+      result.skipped = true;
+      return result;
+    }
+    const server = normalizeServerUrl(config.server || '');
+    if (!server) {
+      result.skipped = true;
+      return result;
+    }
+    const token = config.token;
+
+    const startedAt = typeof options.startedAt === 'string' && options.startedAt
+      ? options.startedAt
+      : new Date().toISOString();
+    const currentEvent = { skill, startedAt, id: generateEventId() };
+
+    const pendingFile = pendingPathFor(options.homeDir);
+    const deadline = Date.now() + SHARED_DEADLINE_MS;
+    const MAX_TIMEOUT_SKEW_MS = 500; // 调度容差
+
+    // 1. 先冲刷 pending（最多 100 条）
+    const { events: pendingEvents } = readPending(pendingFile);
+    const confirmedIds = new Set();   // 已成功的事件 id
+    const droppedIds = new Set();     // 4xx 永久失败的事件 id
+    const failedEarly = { hit: false, kind: null }; // 提前终止标记（unauthorized/retry）
+
+    let flushed = 0;
+    for (let i = 0; i < pendingEvents.length; i++) {
+      const ev = pendingEvents[i];
+      const remaining = deadline - Date.now();
+      if (flushed >= FLUSH_MAX_COUNT || remaining <= 0) break;
+
+      const timeoutMs = Math.max(50, remaining);
+      let classification;
+      try {
+        classification = await submitOne(server, token, ev, timeoutMs);
+      } catch {
+        classification = 'retry';
+      }
+
+      if (classification === 'confirmed') {
+        flushed += 1;
+        result.submitted += 1;
+        if (ev.id) confirmedIds.add(ev.id);
+        continue;
+      }
+      if (classification === 'unauthorized') {
+        // 401：原子清除 token；本次及后续不再请求
+        try {
+          if (clearUserToken(options.homeDir)) {
+            result.tokenCleared = true;
+            onNotify('检测到平台凭证已失效，请运行 `kld-sdd auth login` 重新绑定。');
+          }
+        } catch { /* ignore */ }
+        failedEarly.hit = true;
+        failedEarly.kind = 'unauthorized';
+        break;
+      }
+      if (classification === 'drop') {
+        // kld-fixback YELLOW#4: drop 丢弃该条，不 retained、不 break，继续下一条
+        if (ev.id) droppedIds.add(ev.id);
+        continue;
+      }
+      // retry：网络/5xx/429/timeout，本次及后续保留
+      failedEarly.hit = true;
+      failedEarly.kind = 'retry';
+      break;
+    }
+
+    // 2. 发当前事件（若仍有预算且未提前失败）
+    // kld-fixback-review#2 RED: flush 提前失败时当前事件必须入队（与 design
+    // 『网络/超时/429/5xx 将事件追加或保留在 pending 队列』一致），不得静默丢弃。
+    let currentOutcome = 'pending'; // 'confirmed' | 'enqueued' | 'dropped' | 'pending'
+    if (failedEarly.hit) {
+      currentOutcome = 'enqueued';
+    } else {
+      const remaining = deadline - Date.now();
+      if (remaining > MAX_TIMEOUT_SKEW_MS) {
+        let classification;
+        try {
+          classification = await submitOne(server, token, currentEvent, remaining);
+        } catch {
+          classification = 'retry';
+        }
+        if (classification === 'confirmed') {
+          result.submitted += 1;
+          currentOutcome = 'confirmed';
+        } else if (classification === 'unauthorized') {
+          try {
+            if (clearUserToken(options.homeDir)) {
+              result.tokenCleared = true;
+              onNotify('检测到平台凭证已失效，请运行 `kld-sdd auth login` 重新绑定。');
+            }
+          } catch { /* ignore */ }
+          currentOutcome = 'enqueued';
+          failedEarly.hit = true;
+          failedEarly.kind = 'unauthorized';
+        } else if (classification === 'drop') {
+          // kld-fixback YELLOW#4: 当前事件 drop 直接丢弃不入队
+          currentOutcome = 'dropped';
+        } else {
+          currentOutcome = 'enqueued';
+        }
+      } else {
+        currentOutcome = 'enqueued';
+      }
+    }
+
+    // 3. 原子提交队列变化（按 id 差集删除已确认 + 已丢弃；append 当前事件若需要）
+    // 关键：rewrite 前必须重新读文件，把并发 append 的新行合并进来
+    try {
+      if (confirmedIds.size > 0 || droppedIds.size > 0) {
+        const { events: latestEvents } = readPending(pendingFile);
+        const retained = latestEvents.filter((e) => {
+          if (e.id && confirmedIds.has(e.id)) return false;
+          if (e.id && droppedIds.has(e.id)) return false;
+          return true;
+        });
+        writePendingAtomic(pendingFile, retained);
+      }
+      if (currentOutcome === 'enqueued') {
+        appendPending(currentEvent, pendingFile);
+        result.enqueued = true;
+      }
+    } catch { /* ignore */ }
+
+    return result;
+  } catch {
+    // 兜底：永不抛到调用方
+    return result;
+  }
+}
+
+module.exports = {
+  reportUsageOnce,
+  appendPending,
+  readPending,
+  PENDING_FILE_NAME,
+  PENDING_MAX_BYTES,
+  FLUSH_MAX_COUNT,
+  SHARED_DEADLINE_MS,
+};

package/skywalk-sdd/lib/user-config.cjs

@@ -0,0 +1,157 @@
+// kld-T02 — ~/.kld-sdd/config.json 用户级配置管理
+// 职责：读取、规范化、原子写、0600/Windows ACL、401 token 清除、敏感信息脱敏。
+// 与 kb-sdd 跨仓契约对齐：cli_token 仅存于此，不进入 Archive/Knowledge 请求。
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const USER_CONFIG_VERSION = 1;
+const CONFIG_DIR_NAME = '.kld-sdd';
+const CONFIG_FILE_NAME = 'config.json';
+
+/**
+ * 返回用户配置目录路径。
+ * @param {string} [homeDir] — 注入的 home 目录（测试用）；缺省取 env.KLD_SDD_HOME 或 os.homedir()
+ */
+function getConfigDir(homeDir) {
+  const envHome = typeof process !== 'undefined' && process && process.env
+    ? process.env.KLD_SDD_HOME
+    : undefined;
+  const home = (typeof homeDir === 'string' && homeDir)
+    || (typeof envHome === 'string' && envHome)
+    || os.homedir();
+  return path.join(home, CONFIG_DIR_NAME);
+}
+
+/**
+ * 返回用户配置文件完整路径。
+ */
+function getConfigPath(homeDir) {
+  return path.join(getConfigDir(homeDir), CONFIG_FILE_NAME);
+}
+
+/**
+ * 读取用户配置。
+ * - 文件不存在 / 损坏 JSON / 非对象 → 返回 null（不抛）
+ * - 返回新引用；调用方修改不影响后续读取
+ *
+ * @param {string} [homeDir]
+ * @returns {object|null}
+ */
+function readUserConfig(homeDir) {
+  const file = getConfigPath(homeDir);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  // 深拷贝隔离
+  try {
+    return JSON.parse(JSON.stringify(parsed));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * POSIX 平台设置 0600/0700；Windows 平台尝试通过 icacls 收紧 ACL（best-effort）。
+ * @param {string} target — 文件或目录路径
+ * @param {'file'|'dir'} kind
+ */
+function hardenPermissions(target, kind) {
+  if (process.platform === 'win32') {
+    // Windows：依赖 Node 默认 ACL 通常已限当前用户，无需显式 icacls；
+    // 实际收紧在更高层以同步子进程完成，避免引入异步依赖。
+    return;
+  }
+  try {
+    fs.chmodSync(target, kind === 'dir' ? 0o700 : 0o600);
+  } catch {
+    // best-effort：无法 chmod 时静默（例如某些 FS 不支持）
+  }
+}
+
+/**
+ * 原子写入用户配置：先 temp 后 rename，目录与文件均设置权限。
+ * @param {object} config — 必须含 version 字段
+ * @param {string} [homeDir]
+ * @throws {Error} config 非法 / 缺 version
+ */
+function writeUserConfig(config, homeDir) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('user config must be an object');
+  }
+  if (typeof config.version !== 'number') {
+    throw new Error('user config requires numeric version');
+  }
+  const dir = getConfigDir(homeDir);
+  const file = getConfigPath(homeDir);
+  fs.mkdirSync(dir, { recursive: true });
+  hardenPermissions(dir, 'dir');
+
+  const tmp = path.join(dir, `.${CONFIG_FILE_NAME}.${process.pid}.${Date.now()}.tmp`);
+  const payload = JSON.stringify(config, null, 2);
+  fs.writeFileSync(tmp, payload, { encoding: 'utf8', mode: 0o600 });
+  hardenPermissions(tmp, 'file');
+  try {
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+  hardenPermissions(file, 'file');
+}
+
+/**
+ * 原子清除 token 字段，保留其他所有字段。
+ * - 文件不存在 / 损坏 / 已无 token → 幂等返回 false
+ * - 成功清除返回 true
+ *
+ * @param {string} [homeDir]
+ * @returns {boolean}
+ */
+function clearUserToken(homeDir) {
+  const file = getConfigPath(homeDir);
+  if (!fs.existsSync(file)) return false;
+  const current = readUserConfig(homeDir);
+  if (!current) return false;
+  if (!Object.prototype.hasOwnProperty.call(current, 'token')) return false;
+  delete current.token;
+  writeUserConfig(current, homeDir);
+  return true;
+}
+
+/**
+ * 敏感信息脱敏：任何非空字符串 token 一律返回 '***'。
+ * - 空字符串保持空字符串
+ * - 非字符串原样返回
+ * - 永不抛出
+ *
+ * @param {*} value
+ * @returns {*}
+ */
+function redactToken(value) {
+  if (typeof value !== 'string') return value;
+  if (value.length === 0) return '';
+  return '***';
+}
+
+module.exports = {
+  USER_CONFIG_VERSION,
+  getConfigDir,
+  getConfigPath,
+  readUserConfig,
+  writeUserConfig,
+  clearUserToken,
+  redactToken,
+};