kld-sdd 2.6.16 → 2.6.21

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

@@ -0,0 +1,276 @@
+// kld-T01 — CLI 使用统计上报契约
+// 集中定义：七值 skill 枚举、Device Flow 信封、ApiResponse 解包、
+// Node 14 兼容的 URL/HTTP 基础函数。与 kb-sdd 跨仓契约保持一致。
+'use strict';
+
+const http = require('node:http');
+const https = require('node:https');
+
+/**
+ * 七值使用统计 skill 枚举。
+ * test / explore 不属于统计范围，永不映射。
+ */
+const USAGE_SKILLS = Object.freeze([
+  'propose',
+  'spec',
+  'design',
+  'task',
+  'check',
+  'apply',
+  'archive',
+]);
+
+const USAGE_SKILL_SET = new Set(USAGE_SKILLS);
+
+/**
+ * 将 opsx 命令映射到使用统计 skill。
+ * @param {string} command
+ * @returns {string|null} 七值之一；非七值返回 null
+ */
+function mapCommandToUsageSkill(command) {
+  if (typeof command !== 'string' || !command) return null;
+  return USAGE_SKILL_SET.has(command) ? command : null;
+}
+
+/**
+ * 规范化 server URL：只接受 http/https，去尾斜杠，去首尾空白。
+ * @param {string} raw
+ * @returns {string|null} 规范化后的 base URL；非法返回 null
+ */
+function normalizeServerUrl(raw) {
+  if (typeof raw !== 'string') return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+  // 重组：protocol + // + host + pathname（去尾斜杠），忽略 search/hash
+  const path = parsed.pathname.replace(/\/+$/, '');
+  return `${parsed.protocol}//${parsed.host}${path}`;
+}
+
+/**
+ * 解开 ApiResponse 信封：{ code, message, data } → data；code 非 0 抛错。
+ * @param {object} body — 已 JSON.parse 的响应体
+ * @returns {*} data 字段内容
+ * @throws {Error} code 非 0、非对象、缺 code 字段
+ */
+function unwrapApiResponse(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    throw new Error('ApiResponse must be an object');
+  }
+  if (typeof body.code !== 'number') {
+    throw new Error('ApiResponse missing numeric code');
+  }
+  if (body.code !== 0) {
+    const msg = typeof body.message === 'string' && body.message
+      ? body.message
+      : `server error code ${body.code}`;
+    throw new Error(msg);
+  }
+  return body.data === undefined ? null : body.data;
+}
+
+/**
+ * 解析 Device Flow code 响应。
+ * kb-sdd 契约：{ deviceCode, userCode, verificationUri, verificationUriComplete?, expiresIn?, interval? }
+ * @param {object} body
+ * @returns {{deviceCode:string,userCode:string,verificationUri:string,verificationUriComplete:string|null,expiresIn:number,interval:number}|null}
+ */
+function parseDeviceCodeResponse(body) {
+  if (!body || typeof body !== 'object') return null;
+  if (typeof body.deviceCode !== 'string' || !body.deviceCode) return null;
+  if (typeof body.userCode !== 'string' || !body.userCode) return null;
+  if (typeof body.verificationUri !== 'string' || !body.verificationUri) return null;
+  const expiresIn = Number.isFinite(body.expiresIn) && body.expiresIn > 0
+    ? Math.floor(body.expiresIn)
+    : 600;
+  const interval = Number.isFinite(body.interval) && body.interval > 0
+    ? Math.floor(body.interval)
+    : 2;
+  return {
+    deviceCode: body.deviceCode,
+    userCode: body.userCode,
+    verificationUri: body.verificationUri,
+    verificationUriComplete: typeof body.verificationUriComplete === 'string' && body.verificationUriComplete
+      ? body.verificationUriComplete
+      : null,
+    expiresIn,
+    interval,
+  };
+}
+
+/**
+ * 分类 Device Flow poll 响应。
+ * kb-sdd 主契约：{ status: 'pending'|'authorized'|'expired'|'denied', token?, user? }
+ * 兼容 RFC 8628：{ error: 'authorization_pending'|'slow_down'|'expired_token'|'access_denied' }
+ *
+ * @param {number|null} statusCode — HTTP 状态码；网络错误为 null
+ * @param {object|null} body — 已解析 JSON；解析失败为 null
+ * @returns {{kind:'authorized',token:string,user:*}|{kind:'pending'}|{kind:'slow_down'}|{kind:'expired'}|{kind:'denied'}|{kind:'error',message?:string}}
+ */
+function classifyDevicePollResponse(statusCode, body) {
+  const payload = body && typeof body === 'object' ? body : {};
+  // kb-sdd 主契约：status 字段
+  if (typeof payload.status === 'string') {
+    const s = payload.status;
+    if (s === 'authorized') {
+      if (typeof payload.token === 'string' && payload.token) {
+        return { kind: 'authorized', token: payload.token, user: payload.user === undefined ? null : payload.user };
+      }
+      return { kind: 'error', message: 'authorized but missing token' };
+    }
+    if (s === 'pending') return { kind: 'pending' };
+    if (s === 'expired') return { kind: 'expired' };
+    if (s === 'denied') return { kind: 'denied' };
+    return { kind: 'error', message: `unknown status: ${s}` };
+  }
+  // RFC 8628 兼容：error 字段
+  if (typeof payload.error === 'string') {
+    const e = payload.error;
+    if (e === 'authorization_pending') return { kind: 'pending' };
+    if (e === 'slow_down') return { kind: 'slow_down' };
+    if (e === 'expired_token') return { kind: 'expired' };
+    if (e === 'access_denied') return { kind: 'denied' };
+    return { kind: 'error', message: e };
+  }
+  // 无识别字段：网络错误或 HTTP 异常
+  if (statusCode == null) return { kind: 'error', message: 'network error' };
+  if (statusCode >= 400) return { kind: 'error', message: `HTTP ${statusCode}` };
+  return { kind: 'error', message: 'unrecognized response' };
+}
+
+/**
+ * 分类 usage 上报响应。
+ * - confirmed: 2xx/204，服务端已确认，可从 pending 队列移除
+ * - unauthorized: 401，token 失效；调用方应原子删除本地 token 并提示一次
+ * - retry: 网络错误 / 429 / 5xx / timeout；保留在 pending 队列
+ * - drop: 其他 4xx；不再重试但不上抛
+ *
+ * @param {number|null} statusCode
+ * @returns {'confirmed'|'unauthorized'|'retry'|'drop'}
+ */
+function classifyUsageSubmitResponse(statusCode) {
+  if (statusCode == null || statusCode === 0) return 'retry';
+  if (statusCode >= 200 && statusCode < 300) return 'confirmed';
+  if (statusCode === 401) return 'unauthorized';
+  if (statusCode === 429) return 'retry';
+  if (statusCode >= 500) return 'retry';
+  return 'drop';
+}
+
+/**
+ * Node 14 兼容的 POST JSON 实现。
+ * - 仅用核心 http/https，不依赖全局 fetch
+ * - 任何网络/解析错误均不抛，返回 statusCode=null 让调用方分类
+ * - 4xx/5xx 不抛错，返回 statusCode + body 供分类
+ *
+ * @param {string} url — 完整 URL（必须 http/https）
+ * @param {object} payload — 请求体（JSON 序列化）
+ * @param {{token?:string,timeoutMs?:number,headers?:object}} [options]
+ * @returns {Promise<{statusCode:number|null,body:*,data:*,error:*}>}
+ *   statusCode: HTTP 状态码，网络错误为 null
+ *   body: 原始解析后的 JSON 对象（如可解析）
+ *   data: 若为 ApiResponse 信封且 code=0，则为解包后的 data；否则为 undefined
+ *   error: 仅在 statusCode=null 时携带 Error；否则为 null
+ */
+function postJson(url, payload, options = {}) {
+  return new Promise((resolve, reject) => {
+    let target;
+    try {
+      target = new URL(url);
+    } catch (err) {
+      reject(new Error(`invalid url: ${err.message}`));
+      return;
+    }
+    if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+      reject(new Error(`only http/https supported, got ${target.protocol}`));
+      return;
+    }
+    const transport = target.protocol === 'https:' ? https : http;
+    const token = options && typeof options.token === 'string' && options.token ? options.token : null;
+    const timeoutMs = Number.isFinite(options && options.timeoutMs) && options.timeoutMs > 0
+      ? Math.floor(options.timeoutMs)
+      : 30000;
+
+    let body;
+    try {
+      body = JSON.stringify(payload === undefined ? {} : payload);
+    } catch (err) {
+      reject(new Error(`payload serialization error: ${err.message}`));
+      return;
+    }
+
+    const headers = Object.assign(
+      {
+        Accept: 'application/json',
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': Buffer.byteLength(body),
+      },
+      options && options.headers && typeof options.headers === 'object' ? options.headers : {},
+    );
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const request = transport.request(
+      {
+        hostname: target.hostname,
+        port: target.port || (target.protocol === 'https:' ? 443 : 80),
+        path: target.pathname + target.search,
+        method: 'POST',
+        headers,
+        timeout: timeoutMs,
+      },
+      (response) => {
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('end', () => {
+          const raw = Buffer.concat(chunks).toString('utf8');
+          let parsedBody = null;
+          if (raw) {
+            try {
+              parsedBody = JSON.parse(raw);
+            } catch {
+              parsedBody = null;
+            }
+          }
+          let data;
+          if (parsedBody && typeof parsedBody === 'object' && parsedBody.code === 0) {
+            try {
+              data = unwrapApiResponse(parsedBody);
+            } catch {
+              data = undefined;
+            }
+          }
+          resolve({
+            statusCode: response.statusCode == null ? null : response.statusCode,
+            body: parsedBody,
+            data,
+            error: null,
+          });
+        });
+      },
+    );
+    request.on('timeout', () => {
+      request.destroy(new Error(`request timeout after ${timeoutMs}ms`));
+    });
+    request.on('error', (err) => {
+      resolve({ statusCode: null, body: null, data: undefined, error: err });
+    });
+    request.end(body);
+  });
+}
+
+module.exports = {
+  USAGE_SKILLS,
+  mapCommandToUsageSkill,
+  normalizeServerUrl,
+  unwrapApiResponse,
+  parseDeviceCodeResponse,
+  classifyDevicePollResponse,
+  classifyUsageSubmitResponse,
+  postJson,
+};

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,
+};