ccus-cli 0.1.0

package/dist/lib/export.js

@@ -0,0 +1,275 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRawCsv = buildRawCsv;
+exports.buildAggregatedDetailCsv = buildAggregatedDetailCsv;
+exports.buildRawJsonl = buildRawJsonl;
+exports.buildWeeklySummaryJson = buildWeeklySummaryJson;
+exports.buildWeeklyExportBundleJson = buildWeeklyExportBundleJson;
+exports.buildSummaryRows = buildSummaryRows;
+exports.buildSummaryCsv = buildSummaryCsv;
+exports.buildAggregatedDailyCsv = buildAggregatedDailyCsv;
+exports.buildAggregatedWeeklyCsv = buildAggregatedWeeklyCsv;
+exports.writeTextFile = writeTextFile;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const time_1 = require("./time");
+/** CSV 字符串字段统一做转义，避免逗号和引号破坏列结构。 */
+function quoteCsv(value) {
+    return `"${value.replaceAll("\"", "\"\"")}"`;
+}
+/** token / context 计数统一换算成百万（M）单位，避免 CSV 里出现长串数字。 */
+function toMillions(value) {
+    return value === null ? null : (0, time_1.roundNumber)(value / 1_000_000, 6);
+}
+/**
+ * 清理控制字符，并防止 Excel/Sheets 把值解释成公式。
+ *
+ * 只对字符串字段生效，数字字段保持原样。
+ */
+function sanitizeCsvValue(value) {
+    const cleaned = value.replaceAll(/[\r\n\0]+/g, " ").trim();
+    if (/^[=+\-@]/.test(cleaned)) {
+        return `'${cleaned}`;
+    }
+    return cleaned;
+}
+/** 把一组值序列化成一行 CSV。 */
+function toCsvLine(values) {
+    return values
+        .map((value) => {
+        if (value === null || value === undefined) {
+            return "";
+        }
+        if (typeof value === "number") {
+            return String(value);
+        }
+        return quoteCsv(sanitizeCsvValue(value));
+    })
+        .join(",");
+}
+/**
+ * 导出原始事件明细，便于后续在 Excel、BI 或脚本里二次分析。
+ */
+function buildRawCsv(events) {
+    const header = [
+        "timestamp",
+        "sessionId",
+        "workspaceDir",
+        "workspaceName",
+        "modelName",
+        "gitUserName",
+        "gitUserEmail",
+        "fiveHourUsagePct",
+        "contextWindowPct",
+        "contextUsed",
+        "contextMax",
+        "statusLine",
+    ];
+    const rows = events.map((event) => toCsvLine([
+        event.timestamp,
+        event.sessionId,
+        event.workspaceDir,
+        event.workspaceName,
+        event.modelName,
+        event.gitUserName,
+        event.gitUserEmail,
+        event.usagePct,
+        event.contextWindowPct,
+        event.contextUsed,
+        event.contextMax,
+        event.statusLine,
+    ]));
+    return [header.join(","), ...rows].join("\n");
+}
+/** 多人汇总的 detail.csv。 */
+function buildAggregatedDetailCsv(events) {
+    const header = [
+        "personKey",
+        "timestamp",
+        "week",
+        "date",
+        "sessionId",
+        "workspaceName",
+        "modelName",
+        "fiveHourUsagePct",
+        "contextWindowPct",
+        "contextUsedM",
+        "contextMaxM",
+        "inputTokensM",
+        "outputTokensM",
+        "cacheReadInputTokensM",
+    ];
+    const rows = events.map((event) => toCsvLine([
+        event.personKey,
+        event.timestamp,
+        event.weekKey,
+        event.dateKey,
+        event.sessionId,
+        event.workspaceName,
+        event.modelName,
+        event.usagePct,
+        event.contextWindowPct,
+        toMillions(event.contextUsed),
+        toMillions(event.contextMax),
+        toMillions(event.inputTokens),
+        toMillions(event.outputTokens),
+        toMillions(event.cacheReadInputTokens),
+    ]));
+    return [header.join(","), ...rows].join("\n");
+}
+/** 原始 JSONL 导出适合程序继续消费。 */
+function buildRawJsonl(events) {
+    return events.map((event) => JSON.stringify(event)).join("\n");
+}
+/** 默认导出把本周汇总序列化成可读 JSON。 */
+function buildWeeklySummaryJson(summary) {
+    return `${JSON.stringify(summary, null, 2)}\n`;
+}
+/** 默认导出把原始事件与周汇总一起打包成一个 JSON 文件。 */
+function buildWeeklyExportBundleJson(bundle) {
+    return `${JSON.stringify(bundle, null, 2)}\n`;
+}
+/** 按天汇总 usage 数据，生成 summary 模式的中间结果。 */
+function buildSummaryRows(events) {
+    const grouped = new Map();
+    for (const event of events) {
+        const key = event.timestamp.slice(0, 10);
+        const items = grouped.get(key);
+        if (items) {
+            items.push(event);
+        }
+        else {
+            grouped.set(key, [event]);
+        }
+    }
+    return [...grouped.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([date, items]) => {
+        const usages = items.map((item) => item.usagePct).filter((value) => value !== null);
+        const sevenDayUsages = items.map((item) => item.sevenDayUsagePct).filter((value) => value !== null);
+        const latestUsage = [...items]
+            .sort((left, right) => new Date(right.timestamp).getTime() - new Date(left.timestamp).getTime())
+            .find((item) => item.usagePct !== null)?.usagePct ?? null;
+        const latestSevenDayUsage = [...items]
+            .sort((left, right) => new Date(right.timestamp).getTime() - new Date(left.timestamp).getTime())
+            .find((item) => item.sevenDayUsagePct !== null)?.sevenDayUsagePct ?? null;
+        return {
+            date,
+            sampleCount: items.length,
+            fiveHourPeakUsagePct: usages.length > 0 ? (0, time_1.roundNumber)(Math.max(...usages), 1) : null,
+            minimumUsagePct: usages.length > 0 ? (0, time_1.roundNumber)(Math.min(...usages), 1) : null,
+            fiveHourLatestUsagePct: latestUsage,
+            sevenDayLatestUsagePct: latestSevenDayUsage,
+            sevenDayPeakUsagePct: sevenDayUsages.length > 0 ? (0, time_1.roundNumber)(Math.max(...sevenDayUsages), 1) : null,
+            uniqueSessions: new Set(items.map((item) => item.sessionId).filter(Boolean)).size,
+            uniqueWorkspaces: new Set(items.map((item) => item.workspaceDir).filter(Boolean)).size,
+        };
+    });
+}
+/** 把 summary 结果导出为 CSV。 */
+function buildSummaryCsv(rows) {
+    const header = [
+        "date",
+        "sampleCount",
+        "fiveHourPeakUsagePct",
+        "minimumUsagePct",
+        "fiveHourLatestUsagePct",
+        "sevenDayPeakUsagePct",
+        "sevenDayLatestUsagePct",
+        "uniqueSessions",
+        "uniqueWorkspaces",
+    ];
+    const lines = rows.map((row) => toCsvLine([
+        row.date,
+        row.sampleCount,
+        row.fiveHourPeakUsagePct,
+        row.minimumUsagePct,
+        row.fiveHourLatestUsagePct,
+        row.sevenDayPeakUsagePct,
+        row.sevenDayLatestUsagePct,
+        row.uniqueSessions,
+        row.uniqueWorkspaces,
+    ]));
+    return [header.join(","), ...lines].join("\n");
+}
+/** 多人汇总的 daily.csv。 */
+function buildAggregatedDailyCsv(rows) {
+    const header = [
+        "personKey",
+        "date",
+        "userMessageCount",
+        "apiRequestCount",
+        "inputTokensM",
+        "outputTokensM",
+        "cacheReadInputTokensM",
+        "sampleCount",
+        "fiveHourPeakUsagePct",
+        "fiveHourLatestUsagePct",
+        "sevenDayPeakUsagePct",
+        "sevenDayLatestUsagePct",
+        "uniqueSessions",
+        "uniqueWorkspaces",
+    ];
+    const lines = rows.map((row) => toCsvLine([
+        row.personKey,
+        row.date,
+        row.userMessageCount,
+        row.apiRequestCount,
+        toMillions(row.inputTokens),
+        toMillions(row.outputTokens),
+        toMillions(row.cacheReadInputTokens),
+        row.sampleCount,
+        row.fiveHourPeakUsagePct,
+        row.fiveHourLatestUsagePct,
+        row.sevenDayPeakUsagePct,
+        row.sevenDayLatestUsagePct,
+        row.uniqueSessions,
+        row.uniqueWorkspaces,
+    ]));
+    return [header.join(","), ...lines].join("\n");
+}
+/** 多人汇总的 weekly.csv。 */
+function buildAggregatedWeeklyCsv(rows) {
+    const header = [
+        "personKey",
+        "week",
+        "userMessageCount",
+        "apiRequestCount",
+        "inputTokensM",
+        "outputTokensM",
+        "cacheReadInputTokensM",
+        "sampleCount",
+        "fiveHourPeakUsagePct",
+        "fiveHourLatestUsagePct",
+        "sevenDayPeakUsagePct",
+        "sevenDayLatestUsagePct",
+        "uniqueSessions",
+        "uniqueWorkspaces",
+    ];
+    const lines = rows.map((row) => toCsvLine([
+        row.personKey,
+        row.week,
+        row.userMessageCount,
+        row.apiRequestCount,
+        toMillions(row.inputTokens),
+        toMillions(row.outputTokens),
+        toMillions(row.cacheReadInputTokens),
+        row.sampleCount,
+        row.fiveHourPeakUsagePct,
+        row.fiveHourLatestUsagePct,
+        row.sevenDayPeakUsagePct,
+        row.sevenDayLatestUsagePct,
+        row.uniqueSessions,
+        row.uniqueWorkspaces,
+    ]));
+    return [header.join(","), ...lines].join("\n");
+}
+/** 统一负责写文本文件，顺带确保父目录存在。 */
+async function writeTextFile(outputPath, content) {
+    await promises_1.default.mkdir(node_path_1.default.dirname(outputPath), { recursive: true });
+    await promises_1.default.writeFile(outputPath, content, "utf8");
+}
+//# sourceMappingURL=export.js.map

package/dist/lib/git.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readGitIdentity = readGitIdentity;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+/** 去掉命令输出中的空白，空字符串视为 null。 */
+function normalizeGitValue(value) {
+    const trimmed = value.replaceAll(/[\r\n\0]+/g, " ").trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/** 读取一次全局 git config 键值。 */
+async function readGitConfigValue(args) {
+    try {
+        const { stdout } = await execFileAsync("git", args, {
+            windowsHide: true,
+        });
+        return normalizeGitValue(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 读取全局 Git 用户名和邮箱。
+ *
+ * 只读取全局 git config，不再读取仓库级配置。
+ */
+async function readGitIdentity() {
+    const [globalUserName, globalUserEmail] = await Promise.all([
+        readGitConfigValue(["config", "--global", "--get", "user.name"]),
+        readGitConfigValue(["config", "--global", "--get", "user.email"]),
+    ]);
+    return {
+        userName: globalUserName,
+        userEmail: globalUserEmail,
+    };
+}
+//# sourceMappingURL=git.js.map

package/dist/lib/install.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installStatusline = installStatusline;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+/** 把 settings.json 解析成对象；文件缺失或为空时返回空对象，无法解析时直接报错。 */
+async function readExistingSettings(settingsPath) {
+    let raw;
+    try {
+        raw = await promises_1.default.readFile(settingsPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { settings: {}, existed: false };
+        }
+        throw error;
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        return { settings: {}, existed: true };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        // 不要覆盖无法解析的配置文件，否则可能连带破坏用户的其它 Claude 设置。
+        throw new Error(`Cannot parse Claude settings as JSON: ${settingsPath}. Fix or remove it, then retry.`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Claude settings is not a JSON object: ${settingsPath}`);
+    }
+    return { settings: parsed, existed: true };
+}
+/** 读取现有 statusLine.command（如果有的话），用于回显被替换的旧值。 */
+function readStatuslineCommand(settings) {
+    const statusLine = settings.statusLine;
+    if (typeof statusLine !== "object" || statusLine === null || Array.isArray(statusLine)) {
+        return null;
+    }
+    const command = statusLine.command;
+    return typeof command === "string" ? command : null;
+}
+/**
+ * 把 ccus 的 statusLine 命令写进 Claude Code 的 settings.json。
+ *
+ * 只覆盖 statusLine 字段（并保留其下已有的其它键，如 padding），其它顶层设置原样保留。
+ */
+async function installStatusline(settingsPath, command) {
+    const { settings, existed } = await readExistingSettings(settingsPath);
+    const previousCommand = readStatuslineCommand(settings);
+    const existingStatusLine = typeof settings.statusLine === "object" && settings.statusLine !== null && !Array.isArray(settings.statusLine)
+        ? settings.statusLine
+        : {};
+    settings.statusLine = {
+        ...existingStatusLine,
+        type: "command",
+        command,
+    };
+    await promises_1.default.mkdir(node_path_1.default.dirname(settingsPath), { recursive: true });
+    await promises_1.default.writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+    return {
+        settingsPath,
+        command,
+        previousCommand,
+        created: !existed,
+        unchanged: previousCommand === command,
+    };
+}
+//# sourceMappingURL=install.js.map

package/dist/lib/io.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readStdin = readStdin;
+/**
+ * 读取完整 stdin 内容。
+ *
+ * Claude Code statusline 官方契约就是把 session JSON 通过 stdin 传给命令。
+ */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+//# sourceMappingURL=io.js.map

package/dist/lib/open.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openInBrowser = openInBrowser;
+const node_child_process_1 = require("node:child_process");
+/**
+ * 用系统默认浏览器打开生成好的 dashboard。
+ *
+ * 这里不拼接 shell 字符串，而是显式传参数，降低路径注入风险。
+ */
+async function openInBrowser(filePath) {
+    const command = process.platform === "win32"
+        ? { program: "cmd", args: ["/c", "start", "", filePath] }
+        : process.platform === "darwin"
+            ? { program: "open", args: [filePath] }
+            : { program: "xdg-open", args: [filePath] };
+    await new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)(command.program, command.args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.on("error", reject);
+        child.unref();
+        resolve();
+    });
+}
+//# sourceMappingURL=open.js.map

package/dist/lib/paths.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultDataDir = getDefaultDataDir;
+exports.getEventsDir = getEventsDir;
+exports.getDashboardDir = getDashboardDir;
+exports.getClaudeDataDir = getClaudeDataDir;
+exports.getClaudeSettingsPath = getClaudeSettingsPath;
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * 按平台推导默认数据目录，同时允许通过环境变量显式覆盖。
+ */
+function getDefaultDataDir() {
+    const appData = process.env.CCUS_DATA_DIR;
+    if (appData) {
+        return node_path_1.default.resolve(appData);
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA;
+        if (localAppData) {
+            return node_path_1.default.join(localAppData, "ccus");
+        }
+    }
+    if (process.platform === "darwin") {
+        return node_path_1.default.join(node_os_1.default.homedir(), "Library", "Application Support", "ccus");
+    }
+    const xdgDataHome = process.env.XDG_DATA_HOME;
+    if (xdgDataHome) {
+        return node_path_1.default.join(xdgDataHome, "ccus");
+    }
+    return node_path_1.default.join(node_os_1.default.homedir(), ".local", "share", "ccus");
+}
+/** 所有采样事件的根目录。 */
+function getEventsDir(dataDir) {
+    return node_path_1.default.join(dataDir, "events");
+}
+/** 生成 dashboard 文件的默认目录。 */
+function getDashboardDir(dataDir) {
+    return node_path_1.default.join(dataDir, "dashboard");
+}
+/** Claude Code 默认本地数据目录。 */
+function getClaudeDataDir() {
+    const configured = process.env.CCUS_CLAUDE_DATA_DIR;
+    if (configured) {
+        return node_path_1.default.resolve(configured);
+    }
+    return node_path_1.default.join(node_os_1.default.homedir(), ".claude");
+}
+/** Claude Code 用户级 settings.json 路径，install 命令会往里写 statusLine 配置。 */
+function getClaudeSettingsPath() {
+    return node_path_1.default.join(getClaudeDataDir(), "settings.json");
+}
+//# sourceMappingURL=paths.js.map