@geoqiao/pi-usage 0.1.0

package/extensions/usage-report.js

@@ -0,0 +1,36 @@
+import { fileURLToPath } from 'node:url';
+
+export default function usageReport(pi) {
+  let running;
+  pi.on('session_shutdown', () => running?.abort());
+  pi.registerCommand('usage-report', {
+    description: '生成本地用量 HTML 报告：/usage-report [天数，默认 90]；不上传统计数据',
+    handler: async (args, ctx) => {
+      const days = args.trim() || '90';
+      if (!/^\d+$/.test(days) || Number(days) < 1 || Number(days) > 3660) {
+        ctx.ui.notify('用法：/usage-report [1–3660]；高级筛选与本地价格覆盖请使用 pi-usage --help。', 'error');
+        return;
+      }
+      if (running) { ctx.ui.notify('报告正在生成，请等待完成。', 'warning'); return; }
+      const controller = new AbortController();
+      running = controller;
+      ctx.ui.setStatus('pi-usage', '正在生成本地用量报告…');
+      try {
+        const result = await pi.exec(process.execPath, [fileURLToPath(new URL('../bin/pi-usage.js', import.meta.url)), '--days', days], {
+          cwd: ctx.cwd, signal: controller.signal, timeout: 900_000,
+        });
+        if (result.code !== 0 || result.killed) throw new Error('报告生成失败或已取消；请运行 pi-usage 查看错误。');
+        const file = result.stdout.trim().split('\n').at(-1);
+        // UI only. Never send the report, data or costs to the conversation/model.
+        ctx.ui.notify(`本地报告：${file}`, 'info');
+        ctx.ui.setWidget('pi-usage-report', [`本地用量报告：${file}`]);
+        if (result.stderr.includes('注意：')) ctx.ui.notify('部分数据源不完整，请查看报告内的数据源状态。', 'warning');
+      } catch (error) {
+        if (!controller.signal.aborted) ctx.ui.notify(error.message, 'error');
+      } finally {
+        if (running === controller) running = undefined;
+        ctx.ui.setStatus('pi-usage', undefined);
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@geoqiao/pi-usage",
+  "version": "0.1.0",
+  "description": "AI coding usage analytics with private, self-contained HTML reports. No usage uploads.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "usage",
+    "tokens",
+    "analytics",
+    "local-first"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "web",
+    "data",
+    "vendor/vibe-usage/src",
+    "vendor/vibe-usage/NOTICE.md",
+    "vendor/vibe-usage/upstream-files.json",
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "pi-usage": "bin/pi-usage.js"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/usage-report.js"
+    ]
+  },
+  "engines": {
+    "node": ">=22.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geoqiao/pi-tools.git",
+    "directory": "packages/pi-usage"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js vendor/vibe-usage/test/*.test.js",
+    "typecheck": "node scripts/check.js",
+    "pack:check": "npm pack --dry-run"
+  }
+}

package/src/analytics.js

@@ -0,0 +1,189 @@
+// Shared by Node and the self-contained report. No filesystem or network access.
+export const TOKEN_FIELDS = ['inputTokens', 'cachedInputTokens', 'outputTokens', 'reasoningOutputTokens'];
+export const DIMENSIONS = ['source', 'model', 'project', 'hostname', 'requestType'];
+export const REQUEST_TYPES = { non_tool: '非工具调用请求', tool: '含工具调用请求', other: '其他（无法判定）' };
+export const QUANTILES = [0.25, 0.5, 0.75, 0.9];
+
+export function requestTypeFor(message) {
+  const stop = message.stopReason ?? message.stop_reason;
+  if (['toolUse', 'tool_use'].includes(stop) || (Array.isArray(message.content) && message.content.some(block => ['toolCall', 'tool_use', 'server_tool_use'].includes(block?.type)))) return 'tool';
+  return Array.isArray(message.content) && ['stop', 'end_turn', 'stop_sequence'].includes(stop) ? 'non_tool' : 'other';
+}
+
+// Multiple fragments/copies can carry one request's usage. Positive tool evidence wins.
+export function mergeRequestTypes(a, b) {
+  return [a, b].includes('tool') ? 'tool' : [a, b].includes('non_tool') ? 'non_tool' : 'other';
+}
+
+const dateFormatters = new Map();
+export function dateKey(value, timeZone) {
+  if (!dateFormatters.has(timeZone)) dateFormatters.set(timeZone, new Intl.DateTimeFormat('en-US', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }));
+  const parts = dateFormatters.get(timeZone).formatToParts(new Date(value));
+  const get = type => parts.find(p => p.type === type).value;
+  return `${get('year')}-${get('month')}-${get('day')}`;
+}
+
+export function shiftDate(day, amount) {
+  const d = new Date(`${day}T12:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + amount);
+  return d.toISOString().slice(0, 10);
+}
+
+export function quantile(values, p) {
+  if (!values.length) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = (sorted.length - 1) * p;
+  const lower = Math.floor(index);
+  return sorted[lower] + (sorted[Math.ceil(index)] - sorted[lower]) * (index - lower);
+}
+
+export function validatePrices(models) {
+  if (!models || typeof models !== 'object' || Array.isArray(models)) throw new Error('价格表 models 必须是对象');
+  for (const [id, rate] of Object.entries(models)) {
+    if (!id || !rate || typeof rate !== 'object' || Array.isArray(rate)) throw new Error(`无效价格：${id}`);
+    for (const key of ['input', 'output', 'cacheRead', 'reasoning']) {
+      if (key === 'cacheRead' && rate[key] === null) continue;
+      if (typeof rate[key] !== 'number' || !Number.isFinite(rate[key]) || rate[key] < 0) throw new Error(`${id}.${key} 必须是非负有限数值（美元 / 百万 token）`);
+    }
+  }
+  return models;
+}
+
+export function findRate(model, models) {
+  // Whole identifiers only: never discard service-tier suffixes or match by substring.
+  if (Object.hasOwn(models, model)) return models[model];
+  const matches = Object.keys(models).filter(id => id.toLowerCase() === model.toLowerCase());
+  return matches.length === 1 ? models[matches[0]] : null;
+}
+
+export function priceTokens(row, rate) {
+  if (!rate || (row.cachedInputTokens > 0 && rate.cacheRead == null)) return null;
+  const costs = {
+    inputCost: row.inputTokens * rate.input / 1e6,
+    cacheCost: row.cachedInputTokens * (rate.cacheRead ?? 0) / 1e6,
+    outputCost: row.outputTokens * rate.output / 1e6,
+    reasoningCost: row.reasoningOutputTokens * rate.reasoning / 1e6,
+  };
+  return { ...costs, estimatedCost: Object.values(costs).reduce((a, b) => a + b, 0) };
+}
+
+function text(value, fallback = 'unknown') {
+  return typeof value === 'string' && value ? value.slice(0, 500) : fallback;
+}
+function count(value) {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) throw new Error('无效计数：必须是非负安全整数');
+  return value;
+}
+function iso(value) {
+  if (typeof value !== 'string' || !Number.isFinite(Date.parse(value))) throw new Error('无效时间戳');
+  return new Date(value).toISOString();
+}
+
+export function normalizeData(raw, { timeZone, hostname = 'unknown', prices }) {
+  if (!Array.isArray(raw?.buckets) || !Array.isArray(raw?.sessions)) throw new Error('输入需要 buckets 和 sessions 数组');
+  // Allow-list fields: no prompts, message bodies, credentials or arbitrary parser payloads in exports.
+  const buckets = raw.buckets.map(row => {
+    const b = Object.fromEntries(DIMENSIONS.map(k => [k, text(row[k], k === 'hostname' ? hostname : 'unknown')]));
+    if (row.requestType != null && !Object.hasOwn(REQUEST_TYPES, row.requestType)) throw new Error('无效请求类型');
+    b.requestType = row.requestType ?? 'other';
+    b.bucketStart = iso(row.bucketStart);
+    b.date = dateKey(b.bucketStart, timeZone);
+    for (const k of TOKEN_FIELDS) b[k] = count(row[k] ?? 0);
+    b.totalTokens = count(b.inputTokens + b.outputTokens + b.reasoningOutputTokens);
+    b.allTokens = count(b.totalTokens + b.cachedInputTokens);
+    const priced = priceTokens(b, findRate(b.model, prices));
+    return { ...b, ...(priced || { inputCost: null, cacheCost: null, outputCost: null, reasoningCost: null, estimatedCost: null }) };
+  });
+  const sessions = raw.sessions.map(row => {
+    const s = Object.fromEntries(['source', 'project', 'hostname'].map(k => [k, text(row[k], k === 'hostname' ? hostname : 'unknown')]));
+    s.firstMessageAt = iso(row.firstMessageAt);
+    s.lastMessageAt = iso(row.lastMessageAt);
+    if (s.lastMessageAt < s.firstMessageAt) throw new Error('会话结束时间早于开始时间');
+    s.date = dateKey(s.firstMessageAt, timeZone);
+    s.sessionHash = text(row.sessionHash, 'unknown');
+    for (const k of ['durationSeconds', 'activeSeconds', 'messageCount', 'userMessageCount']) s[k] = count(row[k] ?? 0);
+    return s;
+  });
+  return { buckets, sessions };
+}
+
+export function summarize(rows) {
+  const out = Object.fromEntries([...TOKEN_FIELDS, 'totalTokens', 'allTokens', 'knownCost', 'pricedTokens', 'inputCost', 'cacheCost', 'outputCost', 'reasoningCost'].map(k => [k, 0]));
+  out.unpricedRows = 0;
+  for (const row of rows) {
+    for (const k of [...TOKEN_FIELDS, 'totalTokens', 'allTokens']) out[k] += row[k];
+    if (row.estimatedCost == null && row.allTokens > 0) out.unpricedRows++;
+    else {
+      out.knownCost += row.estimatedCost || 0;
+      out.pricedTokens += row.allTokens;
+      for (const k of ['inputCost', 'cacheCost', 'outputCost', 'reasoningCost']) out[k] += row[k] || 0;
+    }
+  }
+  out.estimatedCost = out.unpricedRows ? null : out.knownCost;
+  out.coverage = out.allTokens ? out.pricedTokens / out.allTokens : null;
+  return out;
+}
+
+export function groupRows(rows, key) {
+  const groups = new Map();
+  for (const row of rows) {
+    const id = typeof key === 'function' ? key(row) : row[key];
+    if (!groups.has(id)) groups.set(id, []);
+    groups.get(id).push(row);
+  }
+  return [...groups].map(([name, items]) => ({ name, ...summarize(items) }));
+}
+
+export function detailRows(rows) {
+  const keys = ['date', ...DIMENSIONS];
+  return groupRows(rows, row => JSON.stringify(keys.map(key => row[key]))).map(({ name, ...totals }) => {
+    const values = JSON.parse(name);
+    return { ...Object.fromEntries(keys.map((key, i) => [key, values[i]])), ...totals };
+  });
+}
+
+export function selectData(data, filters) {
+  const matches = row => row.date >= filters.from && row.date <= filters.to
+    && DIMENSIONS.every(k => !filters[k] || row[k] === filters[k]);
+  return {
+    buckets: data.buckets.filter(matches),
+    // Upstream sessions have no model: suppress instead of inventing a join.
+    sessions: filters.model || filters.requestType ? [] : data.sessions.filter(matches),
+  };
+}
+
+export function dailyRows(rows, from, to, includeZero = false) {
+  const days = new Map(groupRows(rows, 'date').map(r => [r.name, { ...r, recorded: true }]));
+  if (includeZero) {
+    for (let day = from; day <= to; day = shiftDate(day, 1)) {
+      if (!days.has(day)) days.set(day, { name: day, ...summarize([]), recorded: false });
+    }
+  }
+  return [...days.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function percentileRows(days) {
+  return [...TOKEN_FIELDS, 'totalTokens', 'allTokens', 'estimatedCost'].map(metric => {
+    // Never present partial known-cost subtotals as the distribution of full daily cost.
+    const values = days.map(d => d[metric]).filter(v => v != null);
+    return { metric, sampleDays: values.length, min: quantile(values, 0), max: quantile(values, 1), values: QUANTILES.map(p => quantile(values, p)) };
+  });
+}
+
+export function simulateModels(days, modelIds, prices) {
+  return [...new Set(modelIds)].sort().map(model => {
+    const rate = findRate(model, prices);
+    const repriced = days.map(day => priceTokens(day, rate)?.estimatedCost ?? null);
+    const complete = rate && repriced.length && repriced.every(v => v != null);
+    return { model, rate, sampleDays: days.length, min: complete ? quantile(repriced, 0) : null, max: complete ? quantile(repriced, 1) : null, values: QUANTILES.map(p => complete ? quantile(repriced, p) : null) };
+  });
+}
+
+export function toCsv(rows, columns) {
+  const cell = value => {
+    let s = value == null ? '' : String(value);
+    if (typeof value === 'string' && /^[\s]*[=+\-@\t\r\n]/.test(s)) s = `'${s}`;
+    return `"${s.replaceAll('"', '""')}"`;
+  };
+  return '\uFEFF' + [columns.map(cell).join(','), ...rows.map(r => columns.map(k => cell(r[k])).join(','))].join('\r\n') + '\r\n';
+}

package/src/collect.js

@@ -0,0 +1,34 @@
+import { hostname } from 'node:os';
+import { parsers } from '../vendor/vibe-usage/src/parsers/index.js';
+import { normalizeParserResult } from '../vendor/vibe-usage/src/parsers/contract.js';
+import { normalizeData } from './analytics.js';
+
+export const SOURCES = Object.keys(parsers);
+
+export async function collect({ sources = SOURCES, timeZone, prices, onProgress = () => {} }) {
+  const result = { buckets: [], sessions: [], statuses: [] };
+  for (const source of sources) {
+    if (!Object.hasOwn(parsers, source)) throw new Error(`未知数据源：${source}`);
+    onProgress(source);
+    try {
+      const raw = normalizeParserResult(source, await parsers[source]());
+      const data = normalizeData(raw, { timeZone, prices, hostname: hostname() });
+      result.buckets.push(...data.buckets);
+      result.sessions.push(...data.sessions);
+      result.statuses.push({
+        source, state: raw.skipped ? 'partial' : data.buckets.length || data.sessions.length ? 'ok' : 'empty',
+        buckets: data.buckets.length, sessions: data.sessions.length,
+        warningCount: raw.warnings.length,
+        // Do not embed arbitrary upstream exception strings or private filesystem paths.
+        note: raw.indexing ? 'Codex 索引尚未完成；再次生成报告可从本地缓存继续。'
+          : raw.skipped || raw.warnings.length ? '部分记录不可读取或数据源暂不可用；请检查本地文件权限、工具版本或来源登录状态。' : '',
+      });
+    } catch {
+      result.statuses.push({ source, state: 'error', buckets: 0, sessions: 0, warningCount: 1,
+        note: '解析失败；请检查数据源版本、文件权限、SQLite / zstd 支持；Cursor 请检查登录状态。' });
+    }
+    // Let CLI/host process pending cancellation between synchronous legacy parsers.
+    await new Promise(resolve => setImmediate(resolve));
+  }
+  return result;
+}

package/src/network.js

@@ -0,0 +1,25 @@
+// The only network boundary: retrieve source data, never send collected usage.
+export async function sourceFetch(input, options = {}) {
+  if (process.env.PI_USAGE_OFFLINE === '1') throw new Error('离线模式：已禁用数据源网络请求');
+  const url = new URL(input);
+  const method = (options.method || 'GET').toUpperCase();
+  const cursor = url.origin === 'https://cursor.com'
+    && url.pathname === '/api/dashboard/export-usage-events-csv'
+    && url.search === '?strategy=tokens'
+    && method === 'GET' && options.body == null;
+  const rpc = url.protocol === 'http:' && url.hostname === '127.0.0.1'
+    && /^\/exa\.language_server_pb\.LanguageServerService\/(GetWorkspaceInfos|GetCascadeTrajectory)$/.test(url.pathname)
+    && !url.search && method === 'POST';
+  if (url.username || url.password || url.hash || (!cursor && !rpc)) {
+    throw new Error('已阻止非数据源请求');
+  }
+  if (rpc) {
+    const body = JSON.parse(options.body || '{}');
+    const keys = Object.keys(body);
+    if (url.pathname.endsWith('/GetWorkspaceInfos') ? keys.length !== 0
+      : keys.length !== 1 || typeof body.cascadeId !== 'string') {
+      throw new Error('已阻止非只读 RPC 参数');
+    }
+  }
+  return fetch(url, { ...options, redirect: 'error' });
+}

package/src/report.js

@@ -0,0 +1,43 @@
+import { readFile, writeFile, mkdir, mkdtemp, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { toCsv } from './analytics.js';
+
+export const DETAIL_COLUMNS = ['date', 'source', 'model', 'project', 'hostname', 'requestType', 'bucketStart', 'inputTokens', 'cachedInputTokens', 'outputTokens', 'reasoningOutputTokens', 'totalTokens', 'allTokens', 'inputCost', 'cacheCost', 'outputCost', 'reasoningCost', 'estimatedCost'];
+export const SESSION_COLUMNS = ['source', 'project', 'hostname', 'sessionHash', 'firstMessageAt', 'lastMessageAt', 'durationSeconds', 'activeSeconds', 'messageCount', 'userMessageCount'];
+
+export async function renderReport(data) {
+  const load = path => readFile(new URL(path, import.meta.url), 'utf8');
+  const [template, css, analytics, app] = await Promise.all([
+    load('../web/report.html'), load('../web/report.css'), load('./analytics.js'), load('../web/report.js'),
+  ]);
+  const serialized = JSON.stringify(data).replaceAll('<', '\\u003c').replaceAll('\u2028', '\\u2028').replaceAll('\u2029', '\\u2029');
+  const js = `(() => {\n${analytics.replace(/^export /gm, '')}\nconst DATA = ${serialized};\n${app}\n})();`;
+  const hash = createHash('sha256').update(js).digest('base64');
+  // Hash-authorized script; no network, frames, forms, remote fonts or images.
+  const csp = `default-src 'none'; script-src 'sha256-${hash}'; style-src 'unsafe-inline'; img-src data:; connect-src 'none'; base-uri 'none'; form-action 'none'; object-src 'none'`;
+  return template.replace('<!--CSP-->', () => `<meta http-equiv="Content-Security-Policy" content="${csp}">`)
+    .replace('/*STYLE*/', () => css).replace('/*SCRIPT*/', () => js);
+}
+
+export async function writeReport(data, out) {
+  let directory;
+  if (out) {
+    directory = resolve(out);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    if ((await readdir(directory)).length) throw new Error('输出目录必须为空，避免覆盖已有报告');
+  } else {
+    const root = join(homedir(), '.pi', 'usage', 'reports');
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    directory = await mkdtemp(join(root, 'report-'));
+  }
+  // Exclusive writes and HTML last: an interrupted run never exposes a finished-looking report.
+  const save = (name, content) => writeFile(join(directory, name), content, { flag: 'wx', mode: 0o600 });
+  const html = await renderReport(data);
+  await save('usage.json', JSON.stringify(data) + '\n');
+  await save('details.csv', toCsv(data.buckets, DETAIL_COLUMNS));
+  await save('sessions.csv', toCsv(data.sessions, SESSION_COLUMNS));
+  await save('index.html', html);
+  return join(directory, 'index.html');
+}

package/vendor/vibe-usage/NOTICE.md

@@ -0,0 +1,58 @@
+# Vibe Usage parser attribution
+
+Source: https://github.com/vibe-cafe/vibe-usage
+Version: 0.10.21
+Commit: `8f8d88fd70612b3853363eb0bd2ff3ba6ae2ef79`
+License: MIT (declared in upstream package.json and README; that commit has no standalone LICENSE file).
+Attribution: Vibe Usage contributors / vibe-cafe.
+
+Only the transitive parser dependency closure is included (46 source files).
+The upload API, sync orchestrator, account configuration, daemon, reset, CLI router and
+server-backed summary are deliberately absent. This is an independent package, not an official VibeCafé client.
+
+Local patches:
+
+| File | Change |
+|---|---|
+| src/parsers/cursor.js | Fixed cursor.com export URL; use the restricted sourceFetch boundary; reject redirects. |
+| src/parsers/antigravity.js | Route loopback read RPC through the same restricted boundary. |
+| src/parsers/codex-cache.js | Separate PI_USAGE_CACHE_DIR / ~/.pi/usage/cache from the upstream upload client's storage; parser algorithm v4 invalidates pre-classification results and tails. |
+| src/parsers/codex.js | Classify complete per-request response intervals; validate optional completion-ledger usage/IDs; retain unknown for ambiguous/cumulative evidence. Preserve requestType through file and tail aggregation without changing usage/replay accounting. |
+| src/parsers/zcode.js | Join tool parts by message_id using EXISTS; require finish=stop for non-tool responses; retain unknown with missing part schema or malformed evidence. |
+| src/parsers/kimi-code.js | Match current step UUID/turn/usage and legacy completed-step evidence; isolate retry/compaction/subagent output and merge classification across existing message-ID deduplication. |
+| src/parsers/aggregate.js | Preserve requestType in bucket grouping; use collision-safe tuple keys. |
+| src/parsers/pi-session-jsonl.js | Classify response usage by tool evidence / completion; preserve classification across duplicate records. |
+| src/parsers/claude-code.js | Classify response usage; merge tool evidence across content fragments without counting usage again. |
+
+`upstream-files.json` preserves original source SHA-256 hashes. Other source files are copied
+unchanged. Retained upstream parser tests use PI_USAGE_CACHE_DIR instead of VIBE_USAGE_CACHE_DIR.
+Upload/sync tests do not apply and are not included. Tests are not in the published tarball.
+
+## Classification evidence
+
+- Codex: OpenAI Codex commit `89208f09f819c0ff00c2608a33422a5f6b885c76`, `codex-rs/core/src/session/turn.rs` (`ResponseEvent::Completed`, `drain_in_flight`, `send_token_count_event`) and `session/mod.rs` (`record_observed_response_completed`). Completed output items precede per-response usage; tool results are drained before token_count. The newer token_usage_record is used only as corroborating completion evidence, not added again as billed usage. Compaction/cumulative bookkeeping is not assumed to represent one response.
+- Legacy Kimi: MoonshotAI/kimi-cli commit `86f136422a0aae6b217ea49e7ea1d2e8a1defcd2`, `src/kimi_cli/soul/kimisoul.py`: StepBegin / StepRetry bound an attempt; StatusUpdate.token_usage is emitted after kosong.step returns the response and before awaiting tool results. SubagentEvent is a separate nested stream.
+- Current Kimi: locally verified wire structure: context.append_loop_event step.begin/step.end share UUID, turnId and step; tool.call has stepUuid; step.end.usage matches the following usage.record. No inference from usageScope alone; session-scoped compaction records without this link remain unknown.
+- ZCode: local message/part schema; tool part.message_id links to the assistant message. tool_usage execution metrics are not model token usage.
+
+Only synthetic records are retained in regression tests; no private log bodies are vendored.
+
+## MIT permission notice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/vibe-usage/src/cindy-roots.js

@@ -0,0 +1,85 @@
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { delimiter, dirname, join, posix, resolve, win32 } from 'node:path';
+import { homedir } from 'node:os';
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+/**
+ * Cindy keeps Mainland China and Global installs in separate Electron user-data
+ * roots. Scan both because the two editions can be installed side by side.
+ */
+export function getCindyDataRoots(
+  env = process.env,
+  platform = process.platform,
+  home = homedir(),
+) {
+  const override = env.VIBE_USAGE_CINDY_DIRS?.trim();
+  if (override) {
+    return unique(
+      override
+        .split(delimiter)
+        .map((value) => value.trim())
+        .filter(Boolean)
+        .map((value) => resolve(value)),
+    );
+  }
+
+  const pathImpl = platform === 'win32' ? win32 : posix;
+  let base;
+  if (platform === 'darwin') {
+    base = pathImpl.join(home, 'Library', 'Application Support');
+  } else if (platform === 'win32') {
+    base = env.APPDATA?.trim() || pathImpl.join(home, 'AppData', 'Roaming');
+  } else {
+    base = env.XDG_CONFIG_HOME?.trim() || pathImpl.join(home, '.config');
+  }
+  return [pathImpl.join(base, 'CindyGlobal'), pathImpl.join(base, 'Cindy')];
+}
+
+function canonicalPath(value) {
+  try {
+    return realpathSync(value);
+  } catch {
+    return value;
+  }
+}
+
+/** Find every active per-owner `cindy-<owner>.db` database. */
+export function findCindyDbPaths(options = {}) {
+  const roots = getCindyDataRoots(options.env, options.platform, options.home);
+  const paths = [];
+
+  for (const root of roots) {
+    let stat;
+    try {
+      stat = statSync(root);
+    } catch {
+      continue;
+    }
+
+    if (stat.isFile()) {
+      if (root.endsWith('.db')) paths.push(canonicalPath(root));
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+
+    let entries;
+    try {
+      entries = readdirSync(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !/^cindy-.+\.db$/.test(entry.name)) continue;
+      paths.push(canonicalPath(join(root, entry.name)));
+    }
+  }
+
+  return unique(paths).sort();
+}
+
+export function findCindyDataDirs(options = {}) {
+  return unique(findCindyDbPaths(options).map(dirname)).filter(existsSync);
+}