Skip to content

The Open Standard for Generative UI

Standardize telemetry code and bug fixes (#1475)

Zahle Khan3d4d83cd9d71
diff --git a/.github/workflows/cli-e2e.yml b/.github/workflows/cli-e2e.yml
index 9e3710698..3d55d35eb 100644
--- a/.github/workflows/cli-e2e.yml
+++ b/.github/workflows/cli-e2e.yml
@@ -7,6 +7,8 @@ on:
- ".github/actions/cli-scaffold-e2e/action.yml"
- ".github/workflows/cli-e2e.yml"
- "packages/openui-cli/**"
+ - "scripts/copy-telemetry-state.mjs"
+ - "shared/telemetry/**"
- "templates/**"
- "tsconfig.json"
pull_request:
@@ -15,6 +17,8 @@ on:
- ".github/actions/cli-scaffold-e2e/action.yml"
- ".github/workflows/cli-e2e.yml"
- "packages/openui-cli/**"
+ - "scripts/copy-telemetry-state.mjs"
+ - "shared/telemetry/**"
- "templates/**"
- "tsconfig.json"
diff --git a/packages/lang-core/src/telemetry/install.ts b/packages/lang-core/src/telemetry/install.ts
index 9041632dc..e2aaa5a7f 100644
--- a/packages/lang-core/src/telemetry/install.ts
+++ b/packages/lang-core/src/telemetry/install.ts
@@ -16,10 +16,16 @@
*/
import { id as ciInfoId, isCI as ciInfoIsCI } from "ci-info";
import { execFileSync } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, type WriteFileOptions } from "node:fs";
-import { homedir, release } from "node:os";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { release } from "node:os";
import path from "node:path";
+import {
+ createTelemetryStateIO,
+ loadTelemetryState,
+ saveTelemetryState,
+ type TelemetryStateIO,
+} from "../../../../shared/telemetry/telemetry-state.cjs";
import {
getPostHogConfig,
isTelemetryDisabled,
@@ -59,17 +65,12 @@ export interface InstallTelemetryPayload {
properties: InstallTelemetryProperties;
}
-export interface InstallTelemetryIO {
+export interface InstallTelemetryIO extends TelemetryStateIO {
cwd(): string;
- homedir(): string;
- readFile(file: string): string;
- writeFile(file: string, contents: string, options?: WriteFileOptions): void;
- mkdir(directory: string): void;
getGitOrigin(projectRoot: string): string | undefined;
platform: string;
architecture: string;
release(): string;
- randomUUID(): string;
isDocker(): boolean;
stdout(message: string): void;
stderr(message: string): void;
@@ -92,11 +93,6 @@ export type RunInstallTelemetryResult =
| { status: "sent"; payload: InstallTelemetryPayload }
| { status: "failed"; payload?: InstallTelemetryPayload };
-interface StoredTelemetryState extends Record<string, unknown> {
- distinctId: string;
- langCorePostinstallNoticeShown?: boolean;
-}
-
interface ProjectIdentity {
value: string;
source: ProjectIdSource;
@@ -134,8 +130,18 @@ export async function runInstallTelemetry(
let payload: InstallTelemetryPayload | undefined;
try {
const io = createInstallTelemetryIO(options.io);
- const stateFile = getTelemetryStateFile(env, io);
- const state = loadOrCreateState(stateFile, io);
+ let telemetryState = loadTelemetryState({ env, io });
+ let { state, changed } = telemetryState;
+ if (state["langCorePostinstallNoticeShown"] !== true) {
+ io.stderr(INSTALL_NOTICE);
+ state = { ...state, langCorePostinstallNoticeShown: true };
+ changed = true;
+ }
+ if (changed) {
+ telemetryState = saveTelemetryState(telemetryState, state, io);
+ state = telemetryState.state;
+ }
+
const projectRoot = path.resolve(env["INIT_CWD"] || io.cwd());
const projectIdentity = resolveProjectIdentity(projectRoot, env, io);
const packageManager = detectPackageManager(env);
@@ -161,12 +167,6 @@ export async function runInstallTelemetry(
},
};
- if (!state.langCorePostinstallNoticeShown) {
- io.stderr(INSTALL_NOTICE);
- state.langCorePostinstallNoticeShown = true;
- }
- persistState(stateFile, state, io);
-
if (isTruthyEnv(env["OPENUI_TELEMETRY_DEBUG"])) {
io.stdout(`[OpenUI telemetry debug]\n${JSON.stringify(payload, null, 2)}\n`);
return { status: "debug", payload };
@@ -181,16 +181,12 @@ export async function runInstallTelemetry(
function createInstallTelemetryIO(overrides: Partial<InstallTelemetryIO> = {}): InstallTelemetryIO {
return {
+ ...createTelemetryStateIO(),
cwd: () => process.cwd(),
- homedir,
- readFile: (file) => readFileSync(file, "utf8"),
- writeFile: (file, contents, options) => writeFileSync(file, contents, options),
- mkdir: (directory) => mkdirSync(directory, { recursive: true, mode: 0o700 }),
getGitOrigin: defaultGetGitOrigin,
platform: process.platform,
architecture: process.arch,
release,
- randomUUID,
isDocker: defaultIsDocker,
stdout: (message) => process.stdout.write(message),
stderr: (message) => process.stderr.write(message),
@@ -198,43 +194,6 @@ function createInstallTelemetryIO(overrides: Partial<InstallTelemetryIO> = {}):
};
}
-function getTelemetryStateFile(env: NodeJS.ProcessEnv, io: InstallTelemetryIO): string {
- const configRoot = env["XDG_CONFIG_HOME"] || path.join(io.homedir(), ".config");
- return path.join(configRoot, "openui", "telemetry.json");
-}
-
-function loadOrCreateState(stateFile: string, io: InstallTelemetryIO): StoredTelemetryState {
- let stored: Record<string, unknown> = {};
- try {
- const parsed = JSON.parse(io.readFile(stateFile)) as unknown;
- if (isRecord(parsed)) stored = parsed;
- } catch {
- // Missing or corrupt state is replaced with a new best-effort state.
- }
-
- return {
- ...stored,
- distinctId:
- typeof stored["distinctId"] === "string" && stored["distinctId"]
- ? stored["distinctId"]
- : io.randomUUID(),
- langCorePostinstallNoticeShown: stored["langCorePostinstallNoticeShown"] === true,
- };
-}
-
-function persistState(
- stateFile: string,
- state: StoredTelemetryState,
- io: InstallTelemetryIO,
-): void {
- try {
- io.mkdir(path.dirname(stateFile));
- io.writeFile(stateFile, JSON.stringify(state), { mode: 0o600 });
- } catch {
- // Read-only or ephemeral environments use the in-memory state for this run.
- }
-}
-
function resolveProjectIdentity(
projectRoot: string,
env: NodeJS.ProcessEnv,
@@ -277,10 +236,6 @@ function defaultIsDocker(): boolean {
}
}
-function isRecord(value: unknown): value is Record<string, unknown> {
- return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
async function sendToPostHog(
payload: InstallTelemetryPayload,
env: NodeJS.ProcessEnv,
diff --git a/packages/openui-cli/package.json b/packages/openui-cli/package.json
index d1f7f0408..6240de281 100644
--- a/packages/openui-cli/package.json
+++ b/packages/openui-cli/package.json
@@ -10,7 +10,7 @@
"README.md"
],
"scripts": {
- "build:cli": "tsc -p .",
+ "build:cli": "tsc -p . && node ../../scripts/copy-telemetry-state.mjs",
"build": "pnpm run build:cli",
"build:exec": "node dist/index.js",
"lint:check": "eslint ./src",
@@ -60,5 +60,8 @@
"open": "^10.1.0",
"openid-client": "^6.1.7",
"posthog-node": "^5.35.6"
+ },
+ "imports": {
+ "#openui-telemetry-state": "./dist/telemetry-state.cjs"
}
}
diff --git a/packages/openui-cli/src/lib/telemetry.ts b/packages/openui-cli/src/lib/telemetry.ts
index e25c90e15..6669f6406 100644
--- a/packages/openui-cli/src/lib/telemetry.ts
+++ b/packages/openui-cli/src/lib/telemetry.ts
@@ -1,6 +1,5 @@
-import * as fs from "node:fs";
+import { loadTelemetryState, saveTelemetryState } from "#openui-telemetry-state";
import * as os from "node:os";
-import * as path from "node:path";
import type { PostHog } from "posthog-node";
import { isTruthyEnv } from "./env";
@@ -11,8 +10,6 @@ import type { RetryAttemptInfo } from "./retry";
const SHUTDOWN_TIMEOUT_MS = 2000;
const isTelemetryDebug = () => process.env["OPENUI_TELEMETRY_DEBUG"] === "1";
-const configDir = () =>
- path.join(process.env["XDG_CONFIG_HOME"] ?? path.join(os.homedir(), ".config"), "openui");
const isCi = () => {
const e = process.env;
return isTruthyEnv(e["CI"]) || !!e["GITHUB_ACTIONS"] || !!e["GITLAB_CI"] || !!e["BUILDKITE"];
@@ -23,37 +20,6 @@ const debugLogPostHogFailure = (stage: string, error: unknown) => {
console.warn(`[OpenUI telemetry] PostHog ${stage} failed: ${message}`);
};
-type Stored = { distinctId: string; firstRunNoticeShown?: boolean };
-
-function loadOrCreateState() {
- const file = path.join(configDir(), "telemetry.json");
- try {
- const raw = JSON.parse(fs.readFileSync(file, "utf8")) as Stored;
- return {
- distinctId: raw.distinctId,
- isFirstRun: !raw.firstRunNoticeShown,
- persist: () => writeState(file, { ...raw, firstRunNoticeShown: true }),
- };
- } catch {
- /* missing/corrupt → create */
- }
- const fresh: Stored = { distinctId: crypto.randomUUID(), firstRunNoticeShown: false };
- return {
- distinctId: fresh.distinctId,
- isFirstRun: true,
- persist: () => writeState(file, { ...fresh, firstRunNoticeShown: true }),
- };
-}
-
-function writeState(file: string, s: Stored) {
- try {
- fs.mkdirSync(path.dirname(file), { recursive: true });
- fs.writeFileSync(file, JSON.stringify(s));
- } catch {
- /* read-only fs / CI: best-effort */
- }
-}
-
type Session = {
client?: PostHog;
distinctId: string;
@@ -83,8 +49,11 @@ export class Telemetry {
isTruthyEnv(process.env["OPENUI_TELEMETRY_DISABLED"]) ||
opts.flagEnabled === false;
if (optedOut) return; // enabled stays false → all capture() are no-ops
- const state = loadOrCreateState();
- this.session.distinctId = state.distinctId;
+ let telemetryState = loadTelemetryState();
+ if (telemetryState.changed) {
+ telemetryState = saveTelemetryState(telemetryState, telemetryState.state);
+ }
+ this.session.distinctId = telemetryState.state.distinctId;
this.session.superProps = {
cli_version: opts.cliVersion,
os: process.platform,
@@ -116,12 +85,12 @@ export class Telemetry {
origError(...args);
};
if (isTelemetryDebug()) this.session.client.debug();
- if (state.isFirstRun) {
+ if (telemetryState.state["firstRunNoticeShown"] !== true) {
process.stderr.write(
"\n◆ OpenUI CLI collects usage analytics; OAuth sign-ins may link usage to your OIDC account ID.\n" +
" No code, prompts, API keys, email, or personal name are collected. Opt out: set DO_NOT_TRACK=1 or pass --no-telemetry.\n\n",
);
- state.persist();
+ saveTelemetryState(telemetryState, { ...telemetryState.state, firstRunNoticeShown: true });
}
}
diff --git a/packages/openui-cli/tsconfig.json b/packages/openui-cli/tsconfig.json
index 07421f2f0..b220e9a15 100644
--- a/packages/openui-cli/tsconfig.json
+++ b/packages/openui-cli/tsconfig.json
@@ -10,6 +10,9 @@
"moduleResolution": "node16",
"outDir": "./dist",
"rootDir": "./src",
- "types": ["node"]
+ "types": ["node"],
+ "paths": {
+ "#openui-telemetry-state": ["../../shared/telemetry/telemetry-state.d.cts"]
+ }
}
}
diff --git a/scripts/copy-telemetry-state.mjs b/scripts/copy-telemetry-state.mjs
new file mode 100644
index 000000000..ccad12110
--- /dev/null
+++ b/scripts/copy-telemetry-state.mjs
@@ -0,0 +1,10 @@
+import { copyFileSync, mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// The CLI is compiled with plain tsc, which does not bundle the shared telemetry state module.
+const destination = new URL("../packages/openui-cli/dist/", import.meta.url);
+mkdirSync(destination, { recursive: true });
+copyFileSync(
+ fileURLToPath(new URL("../shared/telemetry/telemetry-state.cjs", import.meta.url)),
+ fileURLToPath(new URL("telemetry-state.cjs", destination)),
+);
diff --git a/shared/telemetry/telemetry-state.cjs b/shared/telemetry/telemetry-state.cjs
new file mode 100644
index 000000000..431996cac
--- /dev/null
+++ b/shared/telemetry/telemetry-state.cjs
@@ -0,0 +1,132 @@
+"use strict";
+
+// Shared by Lang Core's installation telemetry and the OpenUI CLI so both read and write
+// the telemetry state file the same way.
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+function createTelemetryStateIO(overrides = {}) {
+ return {
+ homedir: os.homedir,
+ readFile: (file) => fs.readFileSync(file, "utf8"),
+ writeFile: (file, contents, options) => fs.writeFileSync(file, contents, options),
+ mkdir: (directory) => fs.mkdirSync(directory, { recursive: true, mode: 0o700 }),
+ rename: fs.renameSync,
+ link: fs.linkSync,
+ unlink: fs.unlinkSync,
+ randomUUID: crypto.randomUUID,
+ ...overrides,
+ };
+}
+
+function getTelemetryStateFile(env, io) {
+ const configRoot = env["XDG_CONFIG_HOME"] || path.join(io.homedir(), ".config");
+ return path.join(configRoot, "openui", "telemetry.json");
+}
+
+function readStoredState(file, io) {
+ let contents;
+ try {
+ contents = io.readFile(file);
+ } catch (error) {
+ // State that exists but cannot be read is left untouched.
+ return { stored: {}, status: hasErrorCode(error, "ENOENT") ? "missing" : "unreadable" };
+ }
+
+ try {
+ const parsed = JSON.parse(contents);
+ return { stored: isRecord(parsed) ? parsed : {}, status: "readable" };
+ } catch {
+ // Corrupt state is replaced with a new best-effort state.
+ return { stored: {}, status: "readable" };
+ }
+}
+
+function getStoredDistinctId(stored) {
+ const distinctId = stored["distinctId"];
+ return typeof distinctId === "string" && distinctId ? distinctId : undefined;
+}
+
+function loadTelemetryState(options = {}) {
+ const env = options.env ?? process.env;
+ const io = createTelemetryStateIO(options.io);
+ const file = getTelemetryStateFile(env, io);
+ const { stored, status } = readStoredState(file, io);
+ const storedDistinctId = getStoredDistinctId(stored);
+
+ return {
+ file,
+ status,
+ state: { ...stored, distinctId: storedDistinctId ?? io.randomUUID() },
+ // Only a newly created identity needs to be written back.
+ changed: !storedDistinctId,
+ };
+}
+
+/**
+ * Writes the state without exposing partial files to concurrent processes. New state is published
+ * only if no other process created it first; otherwise that process's identity is reused.
+ */
+function saveTelemetryState(context, state, overrides) {
+ if (context.status === "unreadable") return { ...context, state, changed: false };
+
+ const io = createTelemetryStateIO(overrides);
+ const contents = JSON.stringify(state);
+ const temporaryFile = `${context.file}.${io.randomUUID()}.tmp`;
+ const saved = (savedState) => ({
+ ...context,
+ status: "readable",
+ state: savedState,
+ changed: false,
+ });
+
+ try {
+ io.mkdir(path.dirname(context.file));
+ io.writeFile(temporaryFile, contents, { mode: 0o600, flag: "wx" });
+
+ if (context.status === "readable") {
+ io.rename(temporaryFile, context.file);
+ return saved(state);
+ }
+
+ try {
+ io.link(temporaryFile, context.file);
+ return saved(state);
+ } catch (error) {
+ if (!hasErrorCode(error, "EEXIST")) {
+ // Filesystems without hard links still get a create-only write.
+ try {
+ io.writeFile(context.file, contents, { mode: 0o600, flag: "wx" });
+ return saved(state);
+ } catch (fallbackError) {
+ if (!hasErrorCode(fallbackError, "EEXIST")) throw fallbackError;
+ }
+ }
+ }
+
+ const winner = readStoredState(context.file, io).stored;
+ const winnerDistinctId = getStoredDistinctId(winner);
+ return winnerDistinctId ? saved({ ...winner, distinctId: winnerDistinctId }) : saved(state);
+ } catch {
+ // Read-only or ephemeral environments use the in-memory state for this run.
+ return { ...context, state, changed: false };
+ } finally {
+ try {
+ io.unlink(temporaryFile);
+ } catch {
+ // The temporary file was renamed into place or never created.
+ }
+ }
+}
+
+function hasErrorCode(error, code) {
+ return isRecord(error) && error["code"] === code;
+}
+
+function isRecord(value) {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+module.exports = { createTelemetryStateIO, loadTelemetryState, saveTelemetryState };
diff --git a/shared/telemetry/telemetry-state.d.cts b/shared/telemetry/telemetry-state.d.cts
new file mode 100644
index 000000000..294f186d4
--- /dev/null
+++ b/shared/telemetry/telemetry-state.d.cts
@@ -0,0 +1,38 @@
+import type { WriteFileOptions } from "node:fs";
+
+export interface TelemetryStateIO {
+ homedir(): string;
+ readFile(file: string): string;
+ writeFile(file: string, contents: string, options?: WriteFileOptions): void;
+ mkdir(directory: string): void;
+ rename(from: string, to: string): void;
+ link(existing: string, target: string): void;
+ unlink(file: string): void;
+ randomUUID(): string;
+}
+
+export interface TelemetryState extends Record<string, unknown> {
+ distinctId: string;
+}
+
+export type TelemetryStateStatus = "missing" | "readable" | "unreadable";
+
+export interface TelemetryStateContext {
+ file: string;
+ status: TelemetryStateStatus;
+ state: TelemetryState;
+ changed: boolean;
+}
+
+export function createTelemetryStateIO(overrides?: Partial<TelemetryStateIO>): TelemetryStateIO;
+
+export function loadTelemetryState(options?: {
+ env?: Readonly<Record<string, string | undefined>>;
+ io?: Partial<TelemetryStateIO>;
+}): TelemetryStateContext;
+
+export function saveTelemetryState(
+ context: TelemetryStateContext,
+ state: TelemetryState,
+ io?: Partial<TelemetryStateIO>,
+): TelemetryStateContext;