@codetelemetry/connect 0.1.0

package/dist/src/deviceClient.d.ts

@@ -0,0 +1,32 @@
+import type { FetchLike } from "./otlp.ts";
+import type { Endpoints } from "./config.ts";
+export type DeviceCodeResponse = {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    expiresIn: number;
+    interval: number;
+};
+export declare function requestDeviceCode(endpoints: Endpoints, fetchImpl?: FetchLike, timeoutMs?: number): Promise<DeviceCodeResponse>;
+export type DeviceKey = {
+    apiKey: string;
+    ingestEndpoint: string;
+};
+export type PollOnce = {
+    status: "authorized";
+    apiKey: string;
+    ingestEndpoint: string;
+} | {
+    status: "pending";
+} | {
+    status: "error";
+    error: string;
+};
+export declare function pollOnce(endpoints: Endpoints, deviceCode: string, fetchImpl?: FetchLike, timeoutMs?: number): Promise<PollOnce>;
+export declare function pollForKey(endpoints: Endpoints, deviceCode: string, opts?: {
+    intervalMs?: number;
+    timeoutMs?: number;
+    fetchImpl?: FetchLike;
+    now?: () => number;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): Promise<DeviceKey>;

package/dist/src/deviceClient.js

@@ -0,0 +1,112 @@
+const TERMINAL_ERRORS = new Set(["expired_token", "invalid_grant", "access_denied"]);
+export async function requestDeviceCode(endpoints, fetchImpl = fetch, timeoutMs = 10_000) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), Math.max(1, timeoutMs));
+    try {
+        let res;
+        try {
+            res = await fetchImpl(endpoints.deviceCodeUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ client: "codetelemetry-connect" }),
+                signal: ac.signal,
+            });
+        }
+        catch (error) {
+            if (ac.signal.aborted)
+                throw new Error("device authorization request timed out");
+            throw error;
+        }
+        if (!res.ok)
+            throw new Error(`device authorization failed (HTTP ${res.status})`);
+        let j;
+        try {
+            j = (await res.json());
+        }
+        catch (error) {
+            if (ac.signal.aborted)
+                throw new Error("device authorization request timed out");
+            throw error;
+        }
+        return {
+            deviceCode: String(j.device_code),
+            userCode: String(j.user_code),
+            verificationUri: String(j.verification_uri ?? endpoints.verificationUri),
+            expiresIn: Number(j.expires_in ?? 600),
+            interval: Number(j.interval ?? 2),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function tokenRequest(endpoints, deviceCode, fetchImpl, timeoutMs) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), Math.max(1, timeoutMs));
+    try {
+        let response;
+        try {
+            response = await fetchImpl(endpoints.deviceTokenUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ device_code: deviceCode }),
+                signal: ac.signal,
+            });
+        }
+        catch (error) {
+            if (ac.signal.aborted)
+                return null;
+            throw error;
+        }
+        const body = (await response.json().catch(() => ({})));
+        return { response, body };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function pollOnce(endpoints, deviceCode, fetchImpl = fetch, timeoutMs = 8_000) {
+    const result = await tokenRequest(endpoints, deviceCode, fetchImpl, timeoutMs);
+    if (result === null)
+        return { status: "pending" };
+    const { response: res, body: j } = result;
+    if (res.ok && j.api_key) {
+        return { status: "authorized", apiKey: String(j.api_key), ingestEndpoint: String(j.ingest_endpoint) };
+    }
+    const error = String(j.error ?? "authorization_pending");
+    return TERMINAL_ERRORS.has(error) ? { status: "error", error } : { status: "pending" };
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function pollForKey(endpoints, deviceCode, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const now = opts.now ?? (() => Date.now());
+    const napFor = opts.sleepImpl ?? sleep;
+    let interval = opts.intervalMs ?? 2_000;
+    const timeout = opts.timeoutMs ?? 10 * 60 * 1000;
+    const start = now();
+    while (true) {
+        const remaining = timeout - (now() - start);
+        if (remaining <= 0) {
+            throw new Error("device authorization timed out — approval not completed in time");
+        }
+        const result = await tokenRequest(endpoints, deviceCode, fetchImpl, remaining);
+        if (result === null) {
+            throw new Error("device authorization timed out — approval not completed in time");
+        }
+        const { response: res, body: j } = result;
+        if (res.ok && j.api_key) {
+            return { apiKey: String(j.api_key), ingestEndpoint: String(j.ingest_endpoint) };
+        }
+        const error = String(j.error ?? (res.status >= 500 ? "server_error" : "authorization_pending"));
+        if (TERMINAL_ERRORS.has(error)) {
+            throw new Error(`device authorization ${error}`);
+        }
+        if (error === "slow_down") {
+            interval += 2_000;
+        }
+        if (now() - start + interval >= timeout) {
+            throw new Error("device authorization timed out — approval not completed in time");
+        }
+        await napFor(interval);
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export { onboard, type OnboardClient, type OnboardOptions, type OnboardResult } from "./onboard.ts";
+export { resolveEndpoints, type Endpoints, type SettingsScope } from "./config.ts";
+export { writeSettings, buildEnvBlock } from "./settings.ts";
+export { writeCodexConfig, buildOtelSection, readCodexKey } from "./codexConfig.ts";
+export { sendTestEvent } from "./otlp.ts";
+export { confirmLanded } from "./connectivity.ts";
+export { requestDeviceCode, pollForKey, pollOnce } from "./deviceClient.ts";
+export { looksLikeKey, mask, keyHash } from "./keys.ts";

package/dist/src/index.js

@@ -0,0 +1,8 @@
+export { onboard } from "./onboard.js";
+export { resolveEndpoints } from "./config.js";
+export { writeSettings, buildEnvBlock } from "./settings.js";
+export { writeCodexConfig, buildOtelSection, readCodexKey } from "./codexConfig.js";
+export { sendTestEvent } from "./otlp.js";
+export { confirmLanded } from "./connectivity.js";
+export { requestDeviceCode, pollForKey, pollOnce } from "./deviceClient.js";
+export { looksLikeKey, mask, keyHash } from "./keys.js";

package/dist/src/keys.d.ts

@@ -0,0 +1,5 @@
+export declare function looksLikeKey(value: unknown): value is string;
+export declare function assertKey(value: unknown): string;
+export declare function mask(value: unknown): string;
+export declare function keyHash(value: string): string;
+export declare function scrub(text: string): string;

package/dist/src/keys.js

@@ -0,0 +1,24 @@
+import { createHash } from "node:crypto";
+const KEY_RE = /^cot_[A-Za-z0-9_-]{16,}$/;
+const SECRET_RE = /cot_[A-Za-z0-9_-]{12,}/g;
+export function looksLikeKey(value) {
+    return typeof value === "string" && KEY_RE.test(value.trim());
+}
+export function assertKey(value) {
+    if (!looksLikeKey(value)) {
+        throw new Error("not a valid CodeTelemetry ingest key (expected cot_…)");
+    }
+    return value.trim();
+}
+export function mask(value) {
+    if (typeof value !== "string" || !value.startsWith("cot_") || value.length < 8) {
+        return "cot_…";
+    }
+    return `cot_…${value.slice(-4)}`;
+}
+export function keyHash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function scrub(text) {
+    return text.replace(SECRET_RE, (m) => mask(m));
+}

package/dist/src/onboard.d.ts

@@ -0,0 +1,47 @@
+import { type SettingsScope } from "./config.ts";
+import { type WriteResult } from "./settings.ts";
+import { type SendTestResult, type FetchLike } from "./otlp.ts";
+import { type ConfirmResult } from "./connectivity.ts";
+export type OnboardStep = {
+    name: string;
+    ok: boolean;
+    detail: string;
+};
+export type OnboardResult = {
+    ok: boolean;
+    key: {
+        masked: string;
+        keyHash: string;
+    };
+    settings: WriteResult;
+    test: SendTestResult | null;
+    verify: ConfirmResult | null;
+    steps: OnboardStep[];
+};
+export type OnboardClient = "claude" | "codex";
+export type OnboardOptions = {
+    key?: string;
+    getKey?: () => Promise<{
+        apiKey: string;
+        ingestEndpoint?: string;
+    }>;
+    client?: OnboardClient;
+    endpoints?: Partial<{
+        apiBase: string;
+        ingestEndpoint: string;
+    }>;
+    settings?: {
+        scope?: SettingsScope;
+        path?: string;
+        enrich?: boolean;
+        repositoryObservation?: boolean;
+        backup?: boolean;
+    };
+    sendTest?: boolean;
+    verify?: boolean;
+    verifyTimeoutMs?: number;
+    verifyIntervalMs?: number;
+    fetchImpl?: FetchLike;
+    logger?: (msg: string) => void;
+};
+export declare function onboard(opts: OnboardOptions): Promise<OnboardResult>;

package/dist/src/onboard.js

@@ -0,0 +1,84 @@
+import { resolveEndpoints, resolveSettingsPath } from "./config.js";
+import { writeSettings } from "./settings.js";
+import { resolveCodexConfigPath, writeCodexConfig } from "./codexConfig.js";
+import { sendTestEvent } from "./otlp.js";
+import { confirmLanded } from "./connectivity.js";
+import { keyHash, mask, assertKey } from "./keys.js";
+export async function onboard(opts) {
+    const log = opts.logger ?? (() => { });
+    const steps = [];
+    let apiKey;
+    let deviceIngest;
+    if (opts.key) {
+        apiKey = assertKey(opts.key);
+        steps.push({ name: "authenticate", ok: true, detail: "used provided ingest key" });
+    }
+    else if (opts.getKey) {
+        const got = await opts.getKey();
+        apiKey = assertKey(got.apiKey);
+        deviceIngest = got.ingestEndpoint;
+        steps.push({ name: "authenticate", ok: true, detail: "obtained ingest key via device flow" });
+    }
+    else {
+        throw new Error("onboard requires either `key` or `getKey`");
+    }
+    const endpoints = resolveEndpoints({
+        apiBase: opts.endpoints?.apiBase,
+        ingestEndpoint: deviceIngest ?? opts.endpoints?.ingestEndpoint,
+    });
+    log(`Using ingest key ${mask(apiKey)} → ${endpoints.ingestEndpoint}`);
+    const settings = opts.client === "codex"
+        ? writeCodexConfig({
+            key: apiKey,
+            ingestEndpoint: endpoints.ingestEndpoint,
+            configPath: resolveCodexConfigPath({ path: opts.settings?.path }),
+            enrich: opts.settings?.enrich,
+            repositoryObservation: opts.settings?.repositoryObservation,
+            backup: opts.settings?.backup,
+        })
+        : writeSettings({
+            key: apiKey,
+            ingestEndpoint: endpoints.ingestEndpoint,
+            settingsPath: resolveSettingsPath({ scope: opts.settings?.scope, path: opts.settings?.path }),
+            enrich: opts.settings?.enrich,
+            repositoryObservation: opts.settings?.repositoryObservation,
+            backup: opts.settings?.backup,
+        });
+    const varsNoun = opts.client === "codex" ? "OTEL keys" : "OTEL vars";
+    steps.push({
+        name: "write_config",
+        ok: true,
+        detail: `${settings.created ? "created" : "updated"} ${settings.path} (${settings.wrote.length} ${varsNoun})`,
+    });
+    log(`Wrote ${settings.wrote.length} ${varsNoun} to ${settings.path}${settings.backupPath ? ` (backup: ${settings.backupPath})` : ""}`);
+    let test = null;
+    if (opts.sendTest !== false) {
+        test = await sendTestEvent({ key: apiKey, ingestEndpoint: endpoints.ingestEndpoint, fetchImpl: opts.fetchImpl });
+        steps.push({
+            name: "send_test_event",
+            ok: test.ok,
+            detail: test.ok ? `probe accepted (HTTP ${test.httpStatus})` : `ingest returned HTTP ${test.httpStatus}`,
+        });
+        log(test.ok ? `Test event accepted (probe ${test.probeId})` : `Test event rejected (HTTP ${test.httpStatus})`);
+    }
+    let verify = null;
+    if (opts.verify !== false && test?.ok) {
+        log("Waiting for the probe to land…");
+        verify = await confirmLanded({
+            key: apiKey,
+            connectivityUrl: endpoints.connectivityUrl,
+            probeId: test.probeId,
+            fetchImpl: opts.fetchImpl,
+            timeoutMs: opts.verifyTimeoutMs,
+            intervalMs: opts.verifyIntervalMs,
+        });
+        steps.push({
+            name: "verify_telemetry",
+            ok: verify.landed,
+            detail: verify.landed ? `landed in ${verify.elapsedMs}ms` : `not seen within timeout (${verify.elapsedMs}ms)`,
+        });
+        log(verify.landed ? `✓ Telemetry landed in ${verify.elapsedMs}ms` : "Telemetry not confirmed yet — it can take a moment to appear");
+    }
+    const ok = steps.every((s) => s.ok);
+    return { ok, key: { masked: mask(apiKey), keyHash: keyHash(apiKey) }, settings, test, verify, steps };
+}

package/dist/src/otlp.d.ts

@@ -0,0 +1,18 @@
+export type FetchLike = typeof fetch;
+export declare const PROBE_ATTR = "codetelemetry.probe.id";
+export declare const PROBE_EVENT = "codetelemetry_probe";
+export declare const PROBE_SERVICE = "codetelemetry-connect";
+export declare function buildProbeLog(probeId: string, nowMs?: number): unknown;
+export type SendTestResult = {
+    probeId: string;
+    httpStatus: number;
+    ok: boolean;
+};
+export type SendTestOptions = {
+    key: string;
+    ingestEndpoint: string;
+    probeId?: string;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+};
+export declare function sendTestEvent(opts: SendTestOptions): Promise<SendTestResult>;

package/dist/src/otlp.js

@@ -0,0 +1,60 @@
+import { randomUUID } from "node:crypto";
+import { assertKey } from "./keys.js";
+export const PROBE_ATTR = "codetelemetry.probe.id";
+export const PROBE_EVENT = "codetelemetry_probe";
+export const PROBE_SERVICE = "codetelemetry-connect";
+export function buildProbeLog(probeId, nowMs = Date.now()) {
+    const nano = String(BigInt(Math.floor(nowMs)) * 1000000n);
+    return {
+        resourceLogs: [
+            {
+                resource: {
+                    attributes: [
+                        { key: "service.name", value: { stringValue: PROBE_SERVICE } },
+                    ],
+                },
+                scopeLogs: [
+                    {
+                        scope: { name: PROBE_SERVICE },
+                        logRecords: [
+                            {
+                                timeUnixNano: nano,
+                                observedTimeUnixNano: nano,
+                                severityNumber: 9,
+                                severityText: "INFO",
+                                body: { stringValue: "CodeTelemetry onboarding connectivity probe" },
+                                attributes: [
+                                    { key: "event.name", value: { stringValue: PROBE_EVENT } },
+                                    { key: PROBE_ATTR, value: { stringValue: probeId } },
+                                ],
+                            },
+                        ],
+                    },
+                ],
+            },
+        ],
+    };
+}
+export async function sendTestEvent(opts) {
+    const key = assertKey(opts.key);
+    const probeId = opts.probeId ?? randomUUID();
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const url = `${opts.ingestEndpoint.replace(/\/$/, "")}/v1/logs`;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), opts.timeoutMs ?? 10_000);
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${key}`,
+            },
+            body: JSON.stringify(buildProbeLog(probeId)),
+            signal: ac.signal,
+        });
+        return { probeId, httpStatus: res.status, ok: res.status >= 200 && res.status < 300 };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/src/repositoryHook.d.ts

@@ -0,0 +1,17 @@
+export declare const REPOSITORY_HOOK_MARKER = "codetelemetry-repository-observation";
+export declare const REPOSITORY_HOOK_FILE = "codetelemetry-repository-hook.cjs";
+export declare const REPOSITORY_HOOK_STATE_FILE = "codetelemetry-repository-hook-state.json";
+export declare const REPOSITORY_HOOK_STATE_MAX_ENTRIES = 64;
+export declare const CODEX_HOOKS_FILE = "hooks.json";
+export declare function normalizeRepositoryRemote(value: string): string;
+export declare function selectCodexOtelExporterLine(raw: string): string;
+export declare function repositoryHookSource(options?: {
+    codexConfigPath?: string;
+}): string;
+export declare function quotedCommand(filePath: string, platform?: string): string;
+export declare function validateCodexRepositoryObservationHook(configPath: string): void;
+export declare function installCodexRepositoryObservationHook(configPath: string): void;
+export declare function removeCodexRepositoryObservationHook(configPath: string): void;
+export declare function installRepositoryObservationHook(settings: Record<string, unknown>, settingsPath: string): Record<string, unknown>;
+export declare function removeRepositoryObservationHook(settings: Record<string, unknown>): Record<string, unknown>;
+export declare function removeRepositoryObservationFiles(settingsPath: string): void;