@clinebot/core 0.0.5 → 0.0.7

package/src/storage/provider-settings-legacy-migration.ts

@@ -162,6 +162,53 @@ export interface MigrateLegacyProviderSettingsResult {
 	lastUsedProvider?: string;
 }
 
+export type LegacyClineUserInfo = {
+	idToken: string;
+	expiresAt: number;
+	refreshToken: string;
+	userInfo: {
+		id: string;
+		email: string;
+		displayName: string;
+		termsAcceptedAt: string;
+		clineBenchConsent: boolean;
+		createdAt: string;
+		updatedAt: string;
+	};
+	provider: string;
+	startedAt: number;
+};
+
+/**
+ * Resolves legacy Cline account auth data from the raw `cline:clineAccountId`
+ * secret string into the auth fields used by `ProviderSettings`.
+ *
+ * Returns `undefined` when the input is missing, empty, whitespace-only, or
+ * unparseable JSON.
+ */
+export function resolveLegacyClineAuth(
+	rawAccountData: string | undefined,
+): ProviderSettings["auth"] | undefined {
+	const trimmed = rawAccountData?.trim();
+	if (!trimmed) {
+		return undefined;
+	}
+	try {
+		const data = JSON.parse(trimmed) as LegacyClineUserInfo;
+		if (!data) {
+			return undefined;
+		}
+		return {
+			accessToken: data.idToken,
+			refreshToken: data.refreshToken,
+			expiresAt: data.expiresAt,
+			accountId: data.userInfo?.id,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
 function trimNonEmpty(value: string | undefined): string | undefined {
 	const trimmed = value?.trim();
 	return trimmed ? trimmed : undefined;
@@ -400,14 +447,19 @@ function buildLegacyProviderSettings(
 		Object.assign(providerSpecific, resolveLegacyCodexAuth(legacySecrets));
 	}
 	if (providerId === "cline") {
-		const accountId = trimNonEmpty(
-			legacySecrets["cline:clineAccountId"] ?? legacySecrets.clineAccountId,
-		);
-		if (accountId) {
-			providerSpecific.auth = {
-				...(providerSpecific.auth ?? {}),
-				accountId,
-			};
+		try {
+			const legacyAuthString = trimNonEmpty(
+				legacySecrets["cline:clineAccountId"],
+			);
+
+			if (legacyAuthString) {
+				providerSpecific.auth = {
+					...(providerSpecific.auth ?? {}),
+					...resolveLegacyClineAuth(legacyAuthString),
+				};
+			}
+		} catch {
+			// Failed to parse stored cline auth data
 		}
 	}
 	if (providerId === "openai" && legacyGlobalState.openAiHeaders) {

package/src/telemetry/ITelemetryAdapter.ts

@@ -0,0 +1,94 @@
+/**
+ * Telemetry adapter interface for the @clinebot/core SDK.
+ *
+ * This is the SDK-side counterpart to the extension's ITelemetryProvider.
+ * It is intentionally free of VS Code / host-provider dependencies so that
+ * any consumer (CLI, tests, third-party integrations) can plug in their own
+ * backend without pulling in the full extension runtime.
+ */
+
+import type { TelemetryProperties } from "@clinebot/shared";
+
+export type {
+	TelemetryArray,
+	TelemetryMetadata,
+	TelemetryObject,
+	TelemetryPrimitive,
+	TelemetryProperties,
+	TelemetryValue,
+} from "@clinebot/shared";
+
+// ---------------------------------------------------------------------------
+// Adapter interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Telemetry adapter that an SDK consumer implements (or uses via the
+ * provided {@link OpenTelemetryAdapter}) to receive Cline telemetry events.
+ *
+ * The interface intentionally mirrors ITelemetryProvider from the extension
+ * so that shared logic can be re-used or compared easily.
+ */
+export interface ITelemetryAdapter {
+	/** Human-readable adapter name used for logging / diagnostics. */
+	readonly name: string;
+
+	/**
+	 * Emit a standard telemetry event.
+	 * Implementations may silently drop events when telemetry is disabled.
+	 */
+	emit(event: string, properties?: TelemetryProperties): void;
+
+	/**
+	 * Emit a *required* telemetry event that must not be suppressed by
+	 * user opt-out settings (e.g. final opt-out confirmation events).
+	 */
+	emitRequired(event: string, properties?: TelemetryProperties): void;
+
+	/**
+	 * Record a monotonically-increasing counter metric.
+	 * Implementations that do not support metrics may treat this as a no-op.
+	 */
+	recordCounter(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void;
+
+	/**
+	 * Record a histogram (distribution) metric.
+	 * Implementations that do not support metrics may treat this as a no-op.
+	 */
+	recordHistogram(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void;
+
+	/**
+	 * Record a gauge (point-in-time) metric.
+	 * Pass `null` as `value` to retire the series identified by
+	 * `name + attributes` and prevent stale gauge entries.
+	 * Implementations that do not support metrics may treat this as a no-op.
+	 */
+	recordGauge(
+		name: string,
+		value: number | null,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void;
+
+	/** Returns whether the adapter is currently accepting events. */
+	isEnabled(): boolean;
+
+	/** Flush any buffered events/metrics to the backend. */
+	flush(): Promise<void>;
+
+	/** Release all resources held by the adapter. */
+	dispose(): Promise<void>;
+}

package/src/telemetry/LoggerTelemetryAdapter.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from "vitest";
+import { LoggerTelemetryAdapter } from "./LoggerTelemetryAdapter";
+
+describe("LoggerTelemetryAdapter", () => {
+	it("logs events and metrics through the provided logger", async () => {
+		const logger = {
+			debug: vi.fn(),
+			info: vi.fn(),
+			warn: vi.fn(),
+		};
+		const adapter = new LoggerTelemetryAdapter({ logger });
+
+		adapter.emit("session.started", { sessionId: "s1" });
+		adapter.emitRequired("user.opt_out", { reason: "manual" });
+		adapter.recordCounter("cline.session.starts.total", 1, {
+			sessionId: "s1",
+		});
+
+		expect(logger.info).toHaveBeenCalledWith("telemetry.event", {
+			adapter: "LoggerTelemetryAdapter",
+			event: "session.started",
+			properties: { sessionId: "s1" },
+		});
+		expect(logger.warn).toHaveBeenCalledWith("telemetry.required_event", {
+			adapter: "LoggerTelemetryAdapter",
+			event: "user.opt_out",
+			properties: { reason: "manual" },
+		});
+		expect(logger.debug).toHaveBeenCalledWith("telemetry.metric", {
+			adapter: "LoggerTelemetryAdapter",
+			instrument: "counter",
+			name: "cline.session.starts.total",
+			value: 1,
+			attributes: { sessionId: "s1" },
+			description: undefined,
+			required: false,
+		});
+
+		await adapter.flush();
+		await adapter.dispose();
+	});
+});

package/src/telemetry/LoggerTelemetryAdapter.ts

@@ -0,0 +1,114 @@
+import type { BasicLogger } from "@clinebot/shared";
+import type {
+	ITelemetryAdapter,
+	TelemetryProperties,
+} from "./ITelemetryAdapter";
+
+export interface LoggerTelemetryAdapterOptions {
+	logger?: BasicLogger;
+	name?: string;
+	enabled?: boolean | (() => boolean);
+}
+
+export class LoggerTelemetryAdapter implements ITelemetryAdapter {
+	readonly name: string;
+
+	private readonly logger?: BasicLogger;
+	private readonly enabled: boolean | (() => boolean);
+
+	constructor(options: LoggerTelemetryAdapterOptions = {}) {
+		this.name = options.name ?? "LoggerTelemetryAdapter";
+		this.logger = options.logger;
+		this.enabled = options.enabled ?? true;
+	}
+
+	emit(event: string, properties?: TelemetryProperties): void {
+		if (!this.isEnabled()) {
+			return;
+		}
+		this.logger?.info?.("telemetry.event", {
+			adapter: this.name,
+			event,
+			properties,
+		});
+	}
+
+	emitRequired(event: string, properties?: TelemetryProperties): void {
+		this.logger?.warn?.("telemetry.required_event", {
+			adapter: this.name,
+			event,
+			properties,
+		});
+	}
+
+	recordCounter(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void {
+		if (!required && !this.isEnabled()) {
+			return;
+		}
+		this.logger?.debug?.("telemetry.metric", {
+			adapter: this.name,
+			instrument: "counter",
+			name,
+			value,
+			attributes,
+			description,
+			required: required === true,
+		});
+	}
+
+	recordHistogram(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void {
+		if (!required && !this.isEnabled()) {
+			return;
+		}
+		this.logger?.debug?.("telemetry.metric", {
+			adapter: this.name,
+			instrument: "histogram",
+			name,
+			value,
+			attributes,
+			description,
+			required: required === true,
+		});
+	}
+
+	recordGauge(
+		name: string,
+		value: number | null,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void {
+		if (!required && !this.isEnabled()) {
+			return;
+		}
+		this.logger?.debug?.("telemetry.metric", {
+			adapter: this.name,
+			instrument: "gauge",
+			name,
+			value,
+			attributes,
+			description,
+			required: required === true,
+		});
+	}
+
+	isEnabled(): boolean {
+		return typeof this.enabled === "function" ? this.enabled() : this.enabled;
+	}
+
+	async flush(): Promise<void> {}
+
+	async dispose(): Promise<void> {}
+}

package/src/telemetry/OpenTelemetryAdapter.test.ts

@@ -0,0 +1,157 @@
+import type { LoggerProvider } from "@opentelemetry/sdk-logs";
+import type { MeterProvider } from "@opentelemetry/sdk-metrics";
+import { describe, expect, it, vi } from "vitest";
+import { OpenTelemetryAdapter } from "./OpenTelemetryAdapter";
+
+describe("OpenTelemetryAdapter", () => {
+	it("emits events in the telemetry service log format", () => {
+		const emit = vi.fn();
+		const adapter = new OpenTelemetryAdapter({
+			metadata: makeMetadata(),
+			distinctId: "user-123",
+			commonProperties: {
+				organization_id: "org-1",
+			},
+			loggerProvider: {
+				getLogger: () => ({ emit }),
+			} as unknown as LoggerProvider,
+		});
+
+		adapter.emit("task.created", {
+			ulid: "01HXYZ",
+			nested: {
+				mode: "act",
+			},
+			items: ["a", "b"],
+			nullable: null,
+		});
+
+		expect(emit).toHaveBeenCalledWith({
+			severityText: "INFO",
+			body: "task.created",
+			attributes: expect.objectContaining({
+				ulid: "01HXYZ",
+				"nested.mode": "act",
+				items: JSON.stringify(["a", "b"]),
+				nullable: "null",
+				distinct_id: "user-123",
+				organization_id: "org-1",
+				extension_version: "1.2.3",
+				cline_type: "cli",
+				platform: "terminal",
+			}),
+		});
+	});
+
+	it("marks required events with the expected flag", () => {
+		const emit = vi.fn();
+		const adapter = new OpenTelemetryAdapter({
+			metadata: makeMetadata(),
+			loggerProvider: {
+				getLogger: () => ({ emit }),
+			} as unknown as LoggerProvider,
+			enabled: false,
+		});
+
+		adapter.emitRequired("user.opt_out");
+
+		expect(emit).toHaveBeenCalledWith({
+			severityText: "INFO",
+			body: "user.opt_out",
+			attributes: expect.objectContaining({
+				_required: true,
+			}),
+		});
+	});
+
+	it("records metrics with merged telemetry attributes and retires gauge series", () => {
+		const counterAdd = vi.fn();
+		const histogramRecord = vi.fn();
+		let gaugeCallback:
+			| ((result: {
+					observe: (
+						value: number,
+						attributes?: Record<string, string | number | boolean>,
+					) => void;
+			  }) => void)
+			| undefined;
+
+		const forceFlush = vi.fn().mockResolvedValue(undefined);
+		const shutdown = vi.fn().mockResolvedValue(undefined);
+
+		const adapter = new OpenTelemetryAdapter({
+			metadata: makeMetadata(),
+			distinctId: "user-123",
+			meterProvider: {
+				getMeter: () =>
+					({
+						createCounter: () => ({ add: counterAdd }),
+						createHistogram: () => ({ record: histogramRecord }),
+						createObservableGauge: () => ({
+							addCallback: (callback: typeof gaugeCallback) => {
+								gaugeCallback = callback;
+							},
+						}),
+					}) as never,
+				forceFlush,
+				shutdown,
+			} as unknown as MeterProvider,
+		});
+
+		adapter.recordCounter("cline.turns.total", 2, { ulid: "01HXYZ" });
+		adapter.recordHistogram("cline.api.duration.seconds", 1.5, {
+			ulid: "01HXYZ",
+		});
+		adapter.recordGauge("cline.workspace.active_roots", 3, { workspace: "a" });
+
+		expect(counterAdd).toHaveBeenCalledWith(
+			2,
+			expect.objectContaining({
+				ulid: "01HXYZ",
+				distinct_id: "user-123",
+				extension_version: "1.2.3",
+			}),
+		);
+		expect(histogramRecord).toHaveBeenCalledWith(
+			1.5,
+			expect.objectContaining({
+				ulid: "01HXYZ",
+				distinct_id: "user-123",
+			}),
+		);
+
+		const observe = vi.fn();
+		gaugeCallback?.({ observe });
+		expect(observe).toHaveBeenCalledWith(
+			3,
+			expect.objectContaining({
+				workspace: "a",
+				distinct_id: "user-123",
+			}),
+		);
+
+		adapter.recordGauge("cline.workspace.active_roots", null, {
+			workspace: "a",
+		});
+		const observeAfterRetire = vi.fn();
+		gaugeCallback?.({ observe: observeAfterRetire });
+		expect(observeAfterRetire).not.toHaveBeenCalled();
+
+		return Promise.all([adapter.flush(), adapter.dispose()]).then(() => {
+			expect(forceFlush).toHaveBeenCalledTimes(1);
+			expect(shutdown).toHaveBeenCalledTimes(1);
+		});
+	});
+});
+
+function makeMetadata() {
+	return {
+		extension_version: "1.2.3",
+		cline_type: "cli",
+		platform: "terminal",
+		platform_version: "1.0.0",
+		os_type: "darwin",
+		os_version: "24.0.0",
+		is_dev: "true",
+	};
+}