@cantinasecurity/apex-cli 0.1.9 → 0.1.11

package/dist/telemetry.js

@@ -0,0 +1,755 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { loadConfig, saveConfig } from "./config.js";
+import { APEX_CLI_VERSION } from "./version.js";
+const TELEMETRY_ENDPOINT_PATH = "/api/cli/v1/telemetry/events";
+const TELEMETRY_SESSION_ID = randomUUID();
+const TELEMETRY_TIMEOUT_MS = 750;
+const telemetryContext = new AsyncLocalStorage();
+const KNOWN_CLI_FLAG_NAMES = [
+    "comment",
+    "company",
+    "content",
+    "dismissal-reason",
+    "fix-pr-url",
+    "force",
+    "format",
+    "help",
+    "json",
+    "label",
+    "limit",
+    "mode",
+    "no-open",
+    "non-interactive",
+    "output",
+    "parent-comment",
+    "pr",
+    "pr-path",
+    "repo",
+    "scan",
+    "source-mode",
+    "status",
+    "suggested-severity",
+    "workspace-name",
+];
+const KNOWN_CLI_COMMANDS = [
+    "cancel-scan",
+    "connect",
+    "credits",
+    "doctor",
+    "export",
+    "findings",
+    "help",
+    "interactive-shell",
+    "login",
+    "logout",
+    "mcp",
+    "scan",
+    "scans",
+    "setup",
+    "status",
+    "telemetry",
+    "update",
+    "workspace",
+    "workspaces",
+];
+let cachedParentProcesses = null;
+let volatileTelemetryInstallId = null;
+function boolEnv(value) {
+    if (!value)
+        return false;
+    return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+function getDisabledEnvName() {
+    for (const name of [
+        "APEX_TELEMETRY_DISABLED",
+        "APEX_DISABLE_TELEMETRY",
+        "DO_NOT_TRACK",
+    ]) {
+        if (boolEnv(process.env[name])) {
+            return name;
+        }
+    }
+    return null;
+}
+function safeToken(value, fallback = "unknown") {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return fallback;
+    const normalized = trimmed
+        .slice(0, 80)
+        .replace(/[^A-Za-z0-9_.:-]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return normalized || fallback;
+}
+function safeHeader(value) {
+    const token = safeToken(value, "");
+    return token.length > 0 ? token.slice(0, 120) : null;
+}
+function stringFlag(flags, key) {
+    const value = flags[key];
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function flagCount(flags, key) {
+    const value = flags[key];
+    if (Array.isArray(value))
+        return value.length;
+    return typeof value === "string" && value.trim().length > 0 ? 1 : 0;
+}
+function boolFlag(flags, key) {
+    return flags[key] === true;
+}
+function safeEnum(value, allowed) {
+    return allowed.includes(value) ? value : null;
+}
+function bucketCount(count) {
+    if (count <= 0)
+        return "0";
+    if (count === 1)
+        return "1";
+    if (count <= 5)
+        return "2-5";
+    if (count <= 20)
+        return "6-20";
+    return "21+";
+}
+function bucketLength(value) {
+    if (typeof value !== "string")
+        return null;
+    const length = value.length;
+    if (length === 0)
+        return "0";
+    if (length <= 80)
+        return "1-80";
+    if (length <= 500)
+        return "81-500";
+    if (length <= 2_000)
+        return "501-2000";
+    return "2001+";
+}
+function bucketLimit(value) {
+    const numeric = typeof value === "number"
+        ? value
+        : typeof value === "string"
+            ? Number(value)
+            : Number.NaN;
+    if (!Number.isFinite(numeric))
+        return null;
+    if (numeric <= 0)
+        return "0";
+    if (numeric <= 10)
+        return "1-10";
+    if (numeric <= 50)
+        return "11-50";
+    if (numeric <= 100)
+        return "51-100";
+    return "101+";
+}
+function sanitizeFlagNames(flags) {
+    return Object.keys(flags)
+        .filter((key) => KNOWN_CLI_FLAG_NAMES.includes(key))
+        .map((key) => safeToken(key))
+        .sort();
+}
+function unknownFlagCount(flags) {
+    return Object.keys(flags).filter((key) => !KNOWN_CLI_FLAG_NAMES.includes(key)).length;
+}
+function sanitizeCliFlags(flags) {
+    return {
+        flagNames: sanitizeFlagNames(flags),
+        unknownFlagCount: unknownFlagCount(flags),
+        json: boolFlag(flags, "json"),
+        force: boolFlag(flags, "force"),
+        nonInteractive: boolFlag(flags, "non-interactive"),
+        noOpen: boolFlag(flags, "no-open"),
+        companyProvided: stringFlag(flags, "company") !== null,
+        workspaceNameProvided: stringFlag(flags, "workspace-name") !== null,
+        scanIdProvided: stringFlag(flags, "scan") !== null,
+        outputProvided: stringFlag(flags, "output") !== null,
+        contentProvided: stringFlag(flags, "content") !== null,
+        commentProvided: stringFlag(flags, "comment") !== null,
+        parentCommentProvided: stringFlag(flags, "parent-comment") !== null,
+        mode: safeEnum(stringFlag(flags, "mode"), ["standard", "audit", "ultra", "pr"]),
+        sourceMode: safeEnum(stringFlag(flags, "source-mode"), ["auto", "remote", "local"]),
+        format: safeEnum(stringFlag(flags, "format"), ["markdown", "json", "gitlab-sast"]),
+        feedbackStatus: safeEnum(stringFlag(flags, "status"), ["valid", "invalid"]),
+        dismissalReason: safeEnum(stringFlag(flags, "dismissal-reason"), [
+            "false-positive",
+            "by-design",
+            "not-relevant",
+        ]),
+        suggestedSeverity: safeEnum(stringFlag(flags, "suggested-severity"), [
+            "extreme",
+            "critical",
+            "high",
+            "medium",
+            "low",
+            "informational",
+        ]),
+        repoCount: flagCount(flags, "repo"),
+        prCount: flagCount(flags, "pr"),
+        prPathCount: flagCount(flags, "pr-path"),
+        labelCount: flagCount(flags, "label"),
+        fixPrUrlCount: flagCount(flags, "fix-pr-url"),
+        limitBucket: bucketLimit(flags.limit),
+    };
+}
+function sanitizeShellArgs(parsed) {
+    switch (parsed.command) {
+        case "cancel":
+        case "cancel-scan":
+        case "export":
+        case "status":
+            return {
+                scanIdProvided: parsed.args.length > 0,
+            };
+        case "company":
+            return {
+                companyProvided: parsed.args.length > 0,
+            };
+        case "connect":
+            return {
+                provider: safeEnum(parsed.args[0] ?? null, ["github", "gitlab"]),
+            };
+        case "findings": {
+            const action = parsed.args[0] ?? null;
+            if (!action)
+                return {};
+            if (action === "comment") {
+                return {
+                    findingRefProvided: Boolean(parsed.args[1]),
+                    commentLengthBucket: bucketLength(parsed.args.slice(2).join(" ")),
+                };
+            }
+            if (action === "feedback") {
+                const feedbackStatus = safeEnum(parsed.args[2] ?? null, ["valid", "invalid"]);
+                return {
+                    findingRefProvided: Boolean(parsed.args[1]),
+                    feedbackStatus,
+                    dismissalReason: feedbackStatus === "invalid"
+                        ? safeEnum(parsed.args[3] ?? null, [
+                            "false-positive",
+                            "by-design",
+                            "not-relevant",
+                        ])
+                        : null,
+                    commentLengthBucket: bucketLength(parsed.args.slice(feedbackStatus === "invalid" ? 4 : 3).join(" ")),
+                };
+            }
+            if (action === "fix-review") {
+                return {
+                    findingRefProvided: Boolean(parsed.args[1]),
+                };
+            }
+            return {
+                scanIdProvided: true,
+            };
+        }
+        case "scan": {
+            const mode = safeEnum(parsed.args[0] ?? "default", [
+                "standard",
+                "audit",
+                "ultra",
+                "pr",
+            ]);
+            return {
+                mode,
+                prCount: mode === "pr" && parsed.args[1] ? 1 : 0,
+            };
+        }
+        case "telemetry":
+            return {
+                telemetryAction: safeEnum(parsed.args[0] ?? "status", [
+                    "status",
+                    "enable",
+                    "disable",
+                ]),
+            };
+        case "workspace":
+            return {
+                workspaceRefProvided: parsed.args[0] === "use" && parsed.args.length > 1,
+                workspaceNameProvided: parsed.args[0] === "name" ? parsed.args.length > 1 : parsed.args.length > 0,
+            };
+        default:
+            return {};
+    }
+}
+function safeCliSubcommand(parsed) {
+    const subcommand = parsed.subcommand?.trim();
+    if (!subcommand)
+        return null;
+    switch (parsed.command) {
+        case "connect":
+            return safeEnum(subcommand, ["github", "gitlab"]);
+        case "export":
+            return safeEnum(subcommand, ["findings"]);
+        case "findings":
+            return safeEnum(subcommand, ["comment", "feedback", "fix-review"]);
+        case "setup":
+            return safeEnum(subcommand, ["all", "codex", "claude", "copilot"]);
+        case "telemetry":
+            return safeEnum(subcommand, ["status", "enable", "disable"]);
+        case "workspace":
+            return safeEnum(subcommand, ["use"]);
+        default:
+            return null;
+    }
+}
+function safeCliCommand(parsed) {
+    const command = parsed.command ?? "interactive-shell";
+    return KNOWN_CLI_COMMANDS.includes(command) ? command : "unknown";
+}
+function getInputKeys(input) {
+    return Object.entries(input)
+        .filter(([, value]) => value !== undefined)
+        .map(([key]) => safeToken(key))
+        .sort();
+}
+function arrayLength(value) {
+    return Array.isArray(value) ? value.length : 0;
+}
+function pullRequestPathCount(value) {
+    if (!Array.isArray(value))
+        return 0;
+    return value.reduce((count, item) => {
+        if (!item || typeof item !== "object")
+            return count;
+        const paths = item.paths;
+        return count + (Array.isArray(paths) ? paths.length : 0);
+    }, 0);
+}
+export function sanitizeMcpInput(input = {}) {
+    return {
+        inputKeys: getInputKeys(input),
+        cwdProvided: typeof input.cwd === "string" && input.cwd.trim().length > 0,
+        companyProvided: typeof input.company === "string" && input.company.trim().length > 0,
+        workspaceNameProvided: typeof input.workspaceName === "string" && input.workspaceName.trim().length > 0,
+        workspaceRefProvided: typeof input.workspaceRef === "string" && input.workspaceRef.trim().length > 0,
+        scanIdProvided: typeof input.scanId === "string" && input.scanId.trim().length > 0,
+        findingRefProvided: typeof input.findingRef === "string" && input.findingRef.trim().length > 0,
+        outputProvided: typeof input.output === "string" && input.output.trim().length > 0,
+        force: input.force === true,
+        mode: safeEnum(typeof input.mode === "string" ? input.mode : null, [
+            "standard",
+            "audit",
+            "ultra",
+            "pr",
+        ]),
+        sourceMode: safeEnum(typeof input.sourceMode === "string" ? input.sourceMode : null, [
+            "auto",
+            "remote",
+            "local",
+        ]),
+        format: safeEnum(typeof input.format === "string" ? input.format : null, [
+            "markdown",
+            "json",
+            "gitlab-sast",
+        ]),
+        provider: safeEnum(typeof input.provider === "string" ? input.provider : null, [
+            "github",
+            "gitlab",
+        ]),
+        feedbackStatus: safeEnum(typeof input.status === "string" ? input.status : null, [
+            "valid",
+            "invalid",
+        ]),
+        dismissalReason: safeEnum(typeof input.dismissalReason === "string" ? input.dismissalReason : null, ["false-positive", "by-design", "not-relevant"]),
+        suggestedSeverity: safeEnum(typeof input.suggestedSeverity === "string" ? input.suggestedSeverity : null, ["extreme", "critical", "high", "medium", "low", "informational"]),
+        repoCount: arrayLength(input.repoPaths),
+        pullRequestCount: arrayLength(input.pullRequests),
+        pullRequestPathCount: pullRequestPathCount(input.pullRequests),
+        labelCount: arrayLength(input.labels),
+        fixPrUrlCount: arrayLength(input.fixPrUrls),
+        contentLengthBucket: bucketLength(input.content),
+        commentLengthBucket: bucketLength(input.comment),
+        limitBucket: bucketLimit(input.limit),
+    };
+}
+function getEnvHints() {
+    return [
+        "APEX_MCP_CLIENT",
+        "APEX_CLIENT_INTEGRATION",
+        "APEX_CLIENT_NAME",
+        "CODEX_HOME",
+        "CODEX_SANDBOX",
+        "CLAUDECODE",
+        "CLAUDE_CODE_ENTRYPOINT",
+        "COPILOT_HOME",
+        "CURSOR_TRACE_ID",
+        "VSCODE_PID",
+        "CI",
+    ].filter((name) => process.env[name] !== undefined);
+}
+function getLauncher() {
+    const candidates = [
+        process.env.npm_execpath ? path.basename(process.env.npm_execpath) : null,
+        process.env._ ? path.basename(process.env._) : null,
+        process.argv[1] ? path.basename(process.argv[1]) : null,
+    ];
+    return candidates.find((candidate) => candidate && candidate.length > 0) ?? null;
+}
+function readProcessInfo(pid) {
+    try {
+        const output = execFileSync("ps", ["-o", "ppid=", "-o", "comm=", "-p", String(pid)], {
+            encoding: "utf8",
+            timeout: 100,
+        }).trim();
+        const match = output.match(/^(\d+)\s+(.+)$/);
+        if (!match?.[1] || !match[2])
+            return null;
+        return {
+            ppid: Number(match[1]),
+            name: safeToken(path.basename(match[2])),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function getParentProcesses() {
+    if (cachedParentProcesses)
+        return cachedParentProcesses;
+    const processes = [];
+    let pid = process.ppid;
+    for (let index = 0; index < 4; index += 1) {
+        if (!pid || pid <= 1)
+            break;
+        const info = readProcessInfo(pid);
+        if (!info)
+            break;
+        processes.push(info.name);
+        pid = info.ppid;
+    }
+    cachedParentProcesses = processes;
+    return processes;
+}
+function inferIntegrationFromProcessNames(parentProcesses) {
+    const joined = parentProcesses.join(" ").toLowerCase();
+    if (joined.includes("codex"))
+        return "codex";
+    if (joined.includes("claude"))
+        return "claude";
+    if (joined.includes("copilot"))
+        return "copilot";
+    if (joined.includes("cursor"))
+        return "cursor";
+    if (joined.includes("code") || joined.includes("vscode"))
+        return "vscode";
+    return null;
+}
+function getExplicitIntegration() {
+    const explicit = process.env.APEX_MCP_CLIENT ??
+        process.env.APEX_CLIENT_INTEGRATION ??
+        process.env.APEX_CLIENT_NAME ??
+        null;
+    return explicit ? safeToken(explicit) : null;
+}
+export function getTelemetryClientContext(surface) {
+    const envHints = getEnvHints();
+    const parentProcesses = getParentProcesses();
+    const explicit = getExplicitIntegration();
+    let integration = explicit;
+    let integrationSource = explicit ? "env" : "unknown";
+    if (!integration) {
+        if (process.env.CODEX_HOME || process.env.CODEX_SANDBOX) {
+            integration = "codex";
+            integrationSource = "env";
+        }
+        else if (process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT) {
+            integration = "claude";
+            integrationSource = "env";
+        }
+        else if (process.env.COPILOT_HOME) {
+            integration = "copilot";
+            integrationSource = "env";
+        }
+        else if (process.env.CURSOR_TRACE_ID) {
+            integration = "cursor";
+            integrationSource = "env";
+        }
+        else if (process.env.VSCODE_PID) {
+            integration = "vscode";
+            integrationSource = "env";
+        }
+    }
+    if (!integration) {
+        const inferred = inferIntegrationFromProcessNames(parentProcesses);
+        if (inferred) {
+            integration = inferred;
+            integrationSource = "process";
+        }
+    }
+    if (!integration && surface !== "mcp" && process.stdin.isTTY && process.stdout.isTTY) {
+        integration = "terminal";
+        integrationSource = "tty";
+    }
+    return {
+        integration: integration ?? "unknown",
+        integrationSource,
+        envHints,
+        launcher: getLauncher(),
+        parentProcesses,
+        isTty: process.stdin.isTTY === true && process.stdout.isTTY === true,
+        isCi: boolEnv(process.env.CI),
+    };
+}
+function createInvocation(params) {
+    return {
+        id: randomUUID(),
+        surface: params.surface,
+        command: safeToken(params.command),
+        subcommand: params.subcommand ? safeToken(params.subcommand) : null,
+        mcpTool: params.mcpTool ? safeToken(params.mcpTool) : null,
+        metadata: params.metadata ?? {},
+        startedAtMs: Date.now(),
+        startedAt: new Date().toISOString(),
+        client: getTelemetryClientContext(params.surface),
+    };
+}
+export function createCliTelemetryInvocation(parsed) {
+    return createInvocation({
+        surface: "cli",
+        command: safeCliCommand(parsed),
+        subcommand: safeCliSubcommand(parsed),
+        metadata: {
+            argCount: parsed.args.length,
+            ...sanitizeCliFlags(parsed.flags),
+        },
+    });
+}
+export function createShellTelemetryInvocation(parsed, flags) {
+    const shellMode = parsed.command === "scan"
+        ? safeEnum(parsed.args[0] ?? "default", ["standard", "audit", "ultra", "pr"]) ??
+            (parsed.args[0] ? "other" : "default")
+        : null;
+    return createInvocation({
+        surface: "interactive_shell",
+        command: parsed.command,
+        metadata: {
+            argCount: parsed.args.length,
+            ...sanitizeCliFlags(flags),
+            ...sanitizeShellArgs(parsed),
+            shellMode,
+        },
+    });
+}
+export function createMcpTelemetryInvocation(toolName, input = {}) {
+    return createInvocation({
+        surface: "mcp",
+        command: toolName,
+        mcpTool: toolName,
+        metadata: sanitizeMcpInput(input),
+    });
+}
+export function createMcpServerTelemetryInvocation() {
+    return createInvocation({
+        surface: "mcp",
+        command: "server",
+        subcommand: "start",
+        metadata: {},
+    });
+}
+export async function withTelemetryContext(invocation, action) {
+    return telemetryContext.run(invocation, action);
+}
+function currentInvocation() {
+    return telemetryContext.getStore() ?? null;
+}
+function getTelemetryDisabled(config) {
+    const disabledEnv = getDisabledEnvName();
+    if (disabledEnv)
+        return `env:${disabledEnv}`;
+    return config.telemetryDisabled === true ? "config" : null;
+}
+function isUuid(value) {
+    return Boolean(value &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value));
+}
+async function getTelemetryStatusInternal(options) {
+    const config = await loadConfig();
+    const disabledBy = getTelemetryDisabled(config);
+    let installId = isUuid(config.telemetryInstallId)
+        ? config.telemetryInstallId
+        : volatileTelemetryInstallId;
+    if (!disabledBy && !installId && options.createInstallId) {
+        installId = randomUUID();
+        volatileTelemetryInstallId = installId;
+        try {
+            await saveConfig({
+                ...config,
+                telemetryInstallId: installId,
+            });
+        }
+        catch {
+            // Telemetry-only ID creation must not break normal CLI/API behavior.
+        }
+    }
+    return {
+        enabled: disabledBy === null,
+        disabledBy,
+        installId,
+        sessionId: TELEMETRY_SESSION_ID,
+        endpointPath: TELEMETRY_ENDPOINT_PATH,
+        client: getTelemetryClientContext(options.surface),
+        baseUrl: config.baseUrl,
+    };
+}
+export async function getTelemetryStatus(surface = "cli", options = {}) {
+    const { baseUrl: _baseUrl, ...status } = await getTelemetryStatusInternal({
+        createInstallId: options.createInstallId === true,
+        surface,
+    });
+    return status;
+}
+export async function setTelemetryEnabled(enabled) {
+    const config = await loadConfig();
+    await saveConfig({
+        ...config,
+        telemetryDisabled: enabled ? false : true,
+    });
+    return getTelemetryStatus("cli", { createInstallId: enabled });
+}
+function runtimePayload() {
+    return {
+        nodeMajor: Number(process.versions.node.split(".")[0] ?? "0") || null,
+        platform: process.platform,
+        arch: process.arch,
+        shell: process.env.SHELL ? safeToken(path.basename(process.env.SHELL)) : null,
+        termProgram: process.env.TERM_PROGRAM ? safeToken(process.env.TERM_PROGRAM) : null,
+        packageManager: process.env.npm_config_user_agent
+            ? safeToken(process.env.npm_config_user_agent.split(" ")[0])
+            : null,
+    };
+}
+function errorPayload(error) {
+    if (!error || typeof error !== "object") {
+        return {
+            name: typeof error,
+            category: "unknown",
+        };
+    }
+    const maybeError = error;
+    const status = typeof maybeError.status === "number" ? maybeError.status : null;
+    return {
+        name: typeof maybeError.name === "string" ? safeToken(maybeError.name) : "Error",
+        status,
+        code: typeof maybeError.code === "string" ? safeToken(maybeError.code) : null,
+        category: status ? `http_${status}` : "error",
+    };
+}
+function buildPayload(event, invocation, installId, outcome) {
+    return {
+        schemaVersion: 1,
+        event,
+        occurredAt: new Date().toISOString(),
+        sessionId: TELEMETRY_SESSION_ID,
+        installId,
+        cliVersion: APEX_CLI_VERSION,
+        invocation: {
+            id: invocation.id,
+            surface: invocation.surface,
+            command: invocation.command,
+            subcommand: invocation.subcommand,
+            mcpTool: invocation.mcpTool,
+            startedAt: invocation.startedAt,
+            metadata: invocation.metadata,
+        },
+        client: invocation.client,
+        runtime: runtimePayload(),
+        outcome: outcome ?? null,
+    };
+}
+async function postTelemetry(payload, baseUrl) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+    try {
+        const invocationPayload = payload.invocation;
+        const clientPayload = payload.client;
+        const headers = new Headers({
+            "Content-Type": "application/json",
+            "X-Apex-Client-Surface": safeToken(String(invocationPayload?.surface)),
+            "X-Apex-Client-Version": APEX_CLI_VERSION,
+            "X-Apex-Client-Integration": safeToken(String(clientPayload?.integration)),
+            "X-Apex-Telemetry-Schema": "1",
+        });
+        await fetch(new URL(TELEMETRY_ENDPOINT_PATH, baseUrl), {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ events: [payload] }),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        // Telemetry must never affect CLI/MCP behavior.
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function emitTelemetry(event, invocation, outcome) {
+    const status = await getTelemetryStatusInternal({
+        createInstallId: true,
+        surface: invocation.surface,
+    });
+    if (!status.enabled)
+        return;
+    const payload = buildPayload(event, invocation, status.installId, outcome);
+    await postTelemetry(payload, status.baseUrl);
+}
+export function emitInvocationStarted(invocation) {
+    void emitTelemetry("apex.invocation.started", invocation);
+}
+export function emitInvocationCompleted(invocation, error) {
+    const durationMs = Math.max(0, Date.now() - invocation.startedAtMs);
+    void emitTelemetry("apex.invocation.completed", invocation, {
+        success: error === undefined,
+        durationMs,
+        ...(error === undefined ? {} : { error: errorPayload(error) }),
+    });
+}
+export function emitMcpServerStarted(invocation) {
+    void emitTelemetry("apex.mcp.server.started", invocation);
+}
+export async function getTelemetryRequestHeaders() {
+    const invocation = currentInvocation();
+    const status = await getTelemetryStatusInternal({
+        createInstallId: true,
+        surface: invocation?.surface ?? "cli",
+    });
+    if (!status.enabled)
+        return {};
+    const client = invocation?.client ?? status.client;
+    const headers = {
+        "X-Apex-Client-Surface": invocation?.surface ?? "cli",
+        "X-Apex-Client-Version": APEX_CLI_VERSION,
+        "X-Apex-Client-Integration": client.integration,
+        "X-Apex-Client-Session-Id": TELEMETRY_SESSION_ID,
+        "X-Apex-Telemetry-Schema": "1",
+    };
+    if (status.installId) {
+        headers["X-Apex-Client-Install-Id"] = status.installId;
+    }
+    if (invocation) {
+        headers["X-Apex-Invocation-Id"] = invocation.id;
+        headers["X-Apex-Invocation-Command"] = invocation.command;
+        if (invocation.subcommand) {
+            headers["X-Apex-Invocation-Subcommand"] = invocation.subcommand;
+        }
+        if (invocation.mcpTool) {
+            headers["X-Apex-Mcp-Tool"] = invocation.mcpTool;
+        }
+    }
+    return Object.fromEntries(Object.entries(headers).flatMap(([key, value]) => {
+        const safe = safeHeader(value);
+        return safe ? [[key, safe]] : [];
+    }));
+}
+export const testing = {
+    bucketCount,
+    bucketLength,
+    getTelemetryClientContext,
+    sanitizeCliFlags,
+    sanitizeMcpInput,
+};