Skip to content

The Open Standard for Generative UI

Improve CLI error telemetry (#928)

Zahle Khan4e6e0ea08278
diff --git a/docs/content/docs/api-reference/cli.mdx b/docs/content/docs/api-reference/cli.mdx
index 3f84f1cab..5dfd4b1f4 100644
--- a/docs/content/docs/api-reference/cli.mdx
+++ b/docs/content/docs/api-reference/cli.mdx
@@ -330,10 +330,16 @@ value. Humans can omit the option; its default is `unknown`.
Usage analytics include two independent properties: `agent_name`, declared through the option,
and `detected_agent_name`, inferred best-effort from known product environment markers. Either
value can be spoofed, inherited, missing, or ambiguous, so neither should be treated as an
-authentication or security signal. For `create`, analytics also include `package_manager`, the
-immediate-start selection, and best-effort dev-command start and result events. Dev-command events
-contain status, duration, exit code, and signal—not project paths, command output, code, or
-environment values. Use `--no-telemetry` or `DO_NOT_TRACK=1` to disable collection.
+authentication or security signal. Every invocation gets an ephemeral, unpersisted `cli_run_id` so
+its events can be correlated. For `create`, analytics also include `package_manager`, the
+immediate-start selection, and best-effort dev-command start and result events. Failure events use
+bounded `failure_stage`, `error_class`, and `error_code` values instead of raw error messages.
+Dependency failures distinguish peer, registry, network, install-script, workspace, and
+package-compatibility errors. Process failures include duration, exit code, and signal; Cloud-auth
+failures include a bounded auth substage and HTTP status when known; cancellations use separate
+events. Dev-command events contain status, duration, exit code, and signal—not project paths,
+command output, code, or environment values. Use `--no-telemetry` or `DO_NOT_TRACK=1` to disable
+collection.
## See also
diff --git a/packages/openui-cli/README.md b/packages/openui-cli/README.md
index a429794c4..22466ab1e 100644
--- a/packages/openui-cli/README.md
+++ b/packages/openui-cli/README.md
@@ -201,7 +201,7 @@ The CLI sends usage analytics; OAuth sign-ins may link usage to your OIDC accoun
When a coding agent invokes the CLI, it should pass `--agent-name` using its stable, lowercase kebab-case product slug—for example, `codex`, `claude-code`, `cline`, `factory-droid`, or `pi`. Do not pass a model/version, user name, session ID, or other unique value. Humans can omit the flag; it defaults to `unknown`.
-Telemetry includes both `agent_name` (the CLI declaration) and `detected_agent_name` (best-effort environment detection). Either can be spoofed, inherited, missing, or ambiguous; neither is an authentication signal. For `create`, telemetry also includes `package_manager`, the immediate-start selection, and best-effort dev-command start and result events. Dev-command events contain status, duration, exit code, and signal—not project paths, command output, code, or environment values. Disable telemetry with `--no-telemetry` or `DO_NOT_TRACK=1`.
+Telemetry includes both `agent_name` (the CLI declaration) and `detected_agent_name` (best-effort environment detection). Either can be spoofed, inherited, missing, or ambiguous; neither is an authentication signal. Every invocation gets an ephemeral, unpersisted `cli_run_id` so its events can be correlated. Failure events include bounded `failure_stage`, `error_class`, and `error_code` values, never raw error messages. Dependency failures distinguish peer, registry, network, install-script, workspace, and package-compatibility errors. Process failures include duration, exit code, and signal; Cloud-auth failures include a bounded auth substage and HTTP status when known; cancellations use separate events. For `create`, telemetry also includes `package_manager`, the immediate-start selection, and best-effort dev-command start and result events. Dev-command events contain status, duration, exit code, and signal—not project paths, command output, code, or environment values. Disable telemetry with `--no-telemetry` or `DO_NOT_TRACK=1`.
```bash
openui create --no-telemetry
diff --git a/packages/openui-cli/src/auth/mint.ts b/packages/openui-cli/src/auth/mint.ts
index fb26e3056..eab12073e 100644
--- a/packages/openui-cli/src/auth/mint.ts
+++ b/packages/openui-cli/src/auth/mint.ts
@@ -1,5 +1,5 @@
import { createFunnelProps } from "../lib/create-telemetry";
-import { telemetry } from "../lib/telemetry";
+import { CliCancelledError, CreateError, telemetry } from "../lib/telemetry";
import { Authenticator } from "./authenticator";
// Thesys console OAuth + key mint (same flow as create-c1-app). The OpenUI Cloud
@@ -13,6 +13,66 @@ export type CloudAuthMethod = "oauth" | "manual" | "skip";
/** How the cloud key was obtained (for telemetry) — auth method + the `--api-key` flag case. */
export type ResolvedAuthMethod = CloudAuthMethod | "apikey-flag";
+type CloudAuthFailureStage =
+ | "method_resolution"
+ | "manual_key_prompt"
+ | "oidc_discovery"
+ | "browser_auth"
+ | "userinfo"
+ | "organization"
+ | "key_mint_request"
+ | "key_mint_response";
+
+export class CloudAuthError extends CreateError {
+ constructor(
+ authFailureStage: CloudAuthFailureStage,
+ errorCode: string,
+ message: string,
+ httpStatus?: number,
+ ) {
+ super("cloud_auth", message, "authentication", errorCode, {
+ auth_failure_stage: authFailureStage,
+ ...(httpStatus ? { http_status: httpStatus } : {}),
+ });
+ this.name = "CloudAuthError";
+ }
+}
+
+async function cloudAuthStep<T>(
+ stage: CloudAuthFailureStage,
+ errorCode: string,
+ action: () => Promise<T>,
+): Promise<T> {
+ try {
+ return await action();
+ } catch (error) {
+ if (error instanceof CloudAuthError || error instanceof CliCancelledError) throw error;
+ throw new CloudAuthError(
+ stage,
+ errorCode,
+ error instanceof Error ? error.message : String(error),
+ );
+ }
+}
+
+async function cloudAuthPrompt<T>(
+ stage: "method_resolution" | "manual_key_prompt",
+ errorCode: string,
+ action: () => Promise<T>,
+): Promise<T> {
+ try {
+ return await action();
+ } catch (error) {
+ const { ExitPromptError } = await import("@inquirer/core");
+ if (error instanceof ExitPromptError) throw new CliCancelledError("cloud_auth");
+ throw new CloudAuthError(
+ stage,
+ errorCode,
+ error instanceof Error ? error.message : String(error),
+ );
+ }
+}
+
/** Sign in via the browser and mint an OpenUI Cloud API key for the user's org. */
export async function mintCloudApiKey(projectName: string): Promise<string> {
const auth = new Authenticator({ issuerUrl: THESYS_ISSUER_URL, clientId: THESYS_CLIENT_ID });
@@ -20,35 +80,60 @@ export async function mintCloudApiKey(projectName: string): Promise<string> {
...createFunnelProps("cloud_auth_started"),
auth_method: "oauth",
});
- await auth.initialize();
- const { accessToken, userInfo } = await auth.authenticate();
+ await cloudAuthStep("oidc_discovery", "OIDC_DISCOVERY_FAILED", () => auth.initialize());
+ const { accessToken, userInfo } = await cloudAuthStep("browser_auth", "OIDC_FAILED", () =>
+ auth.authenticate(),
+ );
const { fetchUserInfo } = await import("openid-client");
- const profile = await fetchUserInfo(
- auth.getClientConfig(),
- accessToken,
- (userInfo?.["sub"] as string | undefined) ?? "",
+ const profile = await cloudAuthStep("userinfo", "USERINFO_FAILED", () =>
+ fetchUserInfo(
+ auth.getClientConfig(),
+ accessToken,
+ (userInfo?.["sub"] as string | undefined) ?? "",
+ ),
);
const orgId = (profile["org_claims"] as { orgId: string }[] | undefined)?.[0]?.orgId;
if (!orgId) {
- throw new Error(`No organization found for your account. Create a key at ${THESYS_KEYS_URL}.`);
+ throw new CloudAuthError(
+ "organization",
+ "ORG_NOT_FOUND",
+ `No organization found for your account. Create a key at ${THESYS_KEYS_URL}.`,
+ );
}
console.info("🔑 Creating an OpenUI Cloud API key…");
- const res = await fetch(`${THESYS_API_URL}/application/application.createApiKeyWithOidc`, {
- method: "POST",
- headers: {
- Authorization: `Bearer ${accessToken}`,
- "Content-Type": "application/json",
- Accept: "application/json",
- },
- body: JSON.stringify({ name: projectName || "OpenUI Cloud App", orgId, usageType: "C1" }),
- });
+ const res = await cloudAuthStep("key_mint_request", "API_KEY_MINT_FAILED", () =>
+ fetch(`${THESYS_API_URL}/application/application.createApiKeyWithOidc`, {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ Accept: "application/json",
+ },
+ body: JSON.stringify({ name: projectName || "OpenUI Cloud App", orgId, usageType: "C1" }),
+ }),
+ );
if (!res.ok) {
- throw new Error(`Failed to create API key (HTTP ${res.status}): ${await res.text()}`);
+ throw new CloudAuthError(
+ "key_mint_request",
+ `HTTP_${res.status}`,
+ `Failed to create API key (HTTP ${res.status}): ${await res.text()}`,
+ res.status,
+ );
+ }
+ const data = await cloudAuthStep(
+ "key_mint_response",
+ "API_KEY_RESPONSE_INVALID",
+ async () => res.json() as Promise<{ apiKey?: string }>,
+ );
+ if (!data.apiKey) {
+ throw new CloudAuthError(
+ "key_mint_response",
+ "API_KEY_MISSING",
+ "The server did not return an API key.",
+ );
}
- const data = (await res.json()) as { apiKey?: string };
- if (!data.apiKey) throw new Error("The server did not return an API key.");
const oidcSub =
(profile["sub"] as string | undefined) ?? (userInfo?.["sub"] as string | undefined);
@@ -74,19 +159,26 @@ export async function resolveCloudApiKey(opts: {
let method = opts.auth;
if (!method) {
if (!opts.interactive) {
- throw new Error(
+ throw new CloudAuthError(
+ "method_resolution",
+ "AUTH_REQUIRED",
`An API key is required in non-interactive mode. Pass --api-key <key> ` +
`(get one at ${THESYS_KEYS_URL}).`,
);
}
const { select } = await import("@inquirer/prompts");
- method = (await select({
- message: "Connect to OpenUI Cloud:",
- choices: [
- { name: "Sign in with Thesys (opens a browser, mints a key)", value: "oauth" },
- { name: "Skip — add THESYS_API_KEY to .env later", value: "skip" },
- ],
- })) as CloudAuthMethod;
+ method = await cloudAuthPrompt(
+ "method_resolution",
+ "AUTH_METHOD_PROMPT_FAILED",
+ () =>
+ select({
+ message: "Connect to OpenUI Cloud:",
+ choices: [
+ { name: "Sign in with Thesys (opens a browser, mints a key)", value: "oauth" },
+ { name: "Skip — add THESYS_API_KEY to .env later", value: "skip" },
+ ],
+ }) as Promise<CloudAuthMethod>,
+ );
}
if (method === "skip") return { key: null, method: "skip" };
@@ -96,10 +188,10 @@ export async function resolveCloudApiKey(opts: {
"⚠ --auth manual is deprecated. Use browser sign-in or pass --api-key for scripted setup.",
);
const { password } = await import("@inquirer/prompts");
- const key = (
- await password({ message: "Paste your OpenUI Cloud API key:", mask: true })
- ).trim();
- return { key: key || null, method: "manual" };
+ const key = await cloudAuthPrompt("manual_key_prompt", "MANUAL_KEY_PROMPT_FAILED", () =>
+ password({ message: "Paste your OpenUI Cloud API key:", mask: true }),
+ );
+ return { key: key.trim() || null, method: "manual" };
}
return { key: await mintCloudApiKey(opts.projectName), method: "oauth" };
diff --git a/packages/openui-cli/src/commands/create-app.ts b/packages/openui-cli/src/commands/create-app.ts
index 01fa566ce..b70151b80 100644
--- a/packages/openui-cli/src/commands/create-app.ts
+++ b/packages/openui-cli/src/commands/create-app.ts
@@ -1,4 +1,3 @@
-import spawn from "cross-spawn";
import * as fs from "node:fs";
import * as os from "node:os";
import * as path from "node:path";
@@ -11,17 +10,10 @@ import {
type PackageManagerName,
} from "../lib/detect-package-manager";
import { runSkillInstall, shouldInstallSkill } from "../lib/install-skill";
+import { runCommand } from "../lib/process-runner";
import { resolveArgs } from "../lib/resolve-args";
-import { CreateError, telemetry } from "../lib/telemetry";
-
-function runCommand(command: string, args: string[], cwd: string) {
- return spawn.sync(command, args, { cwd, stdio: "inherit" });
-}
-
-function errorCode(error: Error): string {
- const code = (error as NodeJS.ErrnoException).code;
- return typeof code === "string" ? code : "UNKNOWN";
-}
+import { CliCancelledError, CreateError, telemetry } from "../lib/telemetry";
+import { cliErrorProperties, processErrorProperties } from "../lib/utils";
function shouldCopyTemplatePath(templateDir: string, src: string): boolean {
const rel = path.relative(templateDir, src);
@@ -171,25 +163,24 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
const targetDir = path.resolve(process.cwd(), name);
if (fs.existsSync(targetDir)) {
- throw new CreateError("dir_exists", `Directory "${name}" already exists.`);
+ throw new CreateError(
+ "preflight",
+ `Directory "${name}" already exists.`,
+ "filesystem",
+ "TARGET_EXISTS",
+ );
}
const templateDir = path.join(__dirname, "..", "templates", template);
if (!fs.existsSync(templateDir)) {
throw new CreateError(
- "template_missing",
+ "preflight",
`Template "${template}" not found. Rebuild the CLI with \`pnpm build\`.`,
+ "filesystem",
+ "TEMPLATE_MISSING",
);
}
- const captureScaffoldFailed = () => {
- telemetry.capture("cli_scaffold_failed", {
- ...createFunnelProps("scaffold_failed"),
- template,
- ai_setup: aiSetup,
- });
- };
-
telemetry.capture("cli_env_resolution_started", {
...createFunnelProps("env_resolution_started"),
template,
@@ -242,8 +233,23 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
fs.rmSync(path.join(targetDir, "pnpm-workspace.yaml"), { force: true });
}
} catch (err) {
- captureScaffoldFailed();
- throw err;
+ const properties = cliErrorProperties(err, {
+ failure_stage: "scaffold",
+ error_class: "filesystem",
+ error_code: "SCAFFOLD_FAILED",
+ });
+ telemetry.capture("cli_scaffold_failed", {
+ ...createFunnelProps("scaffold_failed"),
+ template,
+ ai_setup: aiSetup,
+ ...properties,
+ });
+ throw new CreateError(
+ properties.failure_stage,
+ err instanceof Error ? err.message : String(err),
+ properties.error_class,
+ properties.error_code,
+ );
}
telemetry.capture("cli_scaffold_succeeded", {
...createFunnelProps("scaffold_succeeded"),
@@ -251,7 +257,25 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
ai_setup: aiSetup,
});
- await writeEnv(targetDir, envResult, template === "openui-cloud" ? buildAppId(name) : undefined);
+ try {
+ await writeEnv(
+ targetDir,
+ envResult,
+ template === "openui-cloud" ? buildAppId(name) : undefined,
+ );
+ } catch (err) {
+ const properties = cliErrorProperties(err, {
+ failure_stage: "environment_write",
+ error_class: "filesystem",
+ error_code: "WRITE_FAILED",
+ });
+ throw new CreateError(
+ properties.failure_stage,
+ err instanceof Error ? err.message : String(err),
+ properties.error_class,
+ properties.error_code,
+ );
+ }
telemetry.capture("cli_env_resolved", {
...createFunnelProps("env_written"),
template,
@@ -261,16 +285,49 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
auth_succeeded: envResult.authSucceeded,
});
+ let skillInstalled = false;
if (installSkill) {
telemetry.capture("cli_skill_install_started", {
...createFunnelProps("skill_install_started"),
skill_installed: installSkill,
});
- runSkillInstall(targetDir);
- telemetry.capture("cli_skill_install_finished", {
- ...createFunnelProps("skill_install_finished"),
- skill_installed: installSkill,
- });
+ const skillResult = await runSkillInstall(targetDir);
+ skillInstalled = !skillResult.error && skillResult.status === 0;
+ if (skillInstalled) {
+ telemetry.capture("cli_skill_install_finished", {
+ ...createFunnelProps("skill_install_finished"),
+ skill_installed: true,
+ duration_ms: skillResult.durationMs,
+ exit_code: skillResult.status,
+ });
+ } else {
+ const properties = processErrorProperties(skillResult, "skill_install", {
+ error_class: "dependency",
+ error_code: "SKILL_INSTALL_FAILED",
+ });
+ if (properties.error_class === "user_cancelled") {
+ telemetry.capture("cli_skill_install_cancelled", {
+ ...createFunnelProps("skill_install_cancelled"),
+ skill_installed: false,
+ ...properties,
+ });
+ throw new CliCancelledError(
+ "skill_install",
+ properties.cancellation_exit_code ?? 0,
+ properties,
+ );
+ }
+ telemetry.capture("cli_skill_install_failed", {
+ ...createFunnelProps("skill_install_failed"),
+ skill_installed: false,
+ ...properties,
+ });
+ console.warn(
+ "\nCould not install the OpenUI agent skill automatically.\n" +
+ "You can install it manually later with:\n\n" +
+ " npx skills add thesysdev/skills --skill openui\n",
+ );
+ }
}
const installCmd = packageManager.installCmd;
@@ -288,7 +345,11 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
template,
ai_setup: aiSetup,
});
- const installResult = runCommand(packageManager.runCmd, packageManager.installArgs, targetDir);
+ const installResult = await runCommand(
+ packageManager.runCmd,
+ packageManager.installArgs,
+ targetDir,
+ );
if (!installResult.error && installResult.status === 0) {
dependencyInstalled = true;
telemetry.capture("cli_dependency_install_succeeded", {
@@ -298,13 +359,39 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
dependency_installed: dependencyInstalled,
});
} else {
+ const properties = processErrorProperties(installResult, "dependency_install", {
+ error_class: "dependency",
+ error_code: "NONZERO_EXIT",
+ });
+ if (properties.error_class === "user_cancelled") {
+ telemetry.capture("cli_dependency_install_cancelled", {
+ ...createFunnelProps("dependency_install_cancelled"),
+ template,
+ ai_setup: aiSetup,
+ dependency_installed: false,
+ ...properties,
+ });
+ throw new CliCancelledError(
+ "dependency_install",
+ properties.cancellation_exit_code ?? 0,
+ properties,
+ );
+ }
telemetry.capture("cli_dependency_install_failed", {
...createFunnelProps("dependency_install_failed"),
template,
ai_setup: aiSetup,
dependency_installed: dependencyInstalled,
+ ...properties,
});
- throw new CreateError("install_deps", "dependency install failed");
+ const { failure_stage, error_class, error_code, ...metadata } = properties;
+ throw new CreateError(
+ failure_stage,
+ "dependency install failed",
+ error_class,
+ error_code,
+ metadata,
+ );
}
}
@@ -316,7 +403,7 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
template,
ai_setup: aiSetup,
duration_ms: Date.now() - t0,
- skill_installed: installSkill,
+ skill_installed: skillInstalled,
env_written: envResult.envWritten,
dependency_installed: dependencyInstalled,
});
@@ -325,7 +412,7 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
name,
devCmd,
template,
- skillInstalled: installSkill,
+ skillInstalled,
envWritten: envResult.envWritten,
startDev,
installCmd,
@@ -340,12 +427,10 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
return;
}
- const devStartedAt = Date.now();
telemetry.capture("cli_dev_command_started", {
package_manager: packageManager.name,
});
- const devResult = runCommand(devCmd, ["run", "dev"], targetDir);
- const durationMs = Math.max(0, Date.now() - devStartedAt);
+ const devResult = await runCommand(devCmd, ["run", "dev"], targetDir);
const stoppedNormally =
devResult.status === 0 ||
devResult.status === 130 ||
@@ -356,19 +441,20 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
if (stoppedNormally) {
telemetry.capture("cli_dev_command_stopped", {
package_manager: packageManager.name,
- duration_ms: durationMs,
+ duration_ms: devResult.durationMs,
exit_code: devResult.status,
- signal: devResult.signal,
+ failure_signal: devResult.signal,
});
} else {
const exitCode = devResult.status ?? 1;
+ const properties = processErrorProperties(devResult, "dev_server", {
+ error_class: "process",
+ error_code: "NONZERO_EXIT",
+ });
telemetry.capture("cli_dev_command_failed", {
package_manager: packageManager.name,
- duration_ms: durationMs,
failure_reason: devResult.error ? "spawn_error" : "nonzero_exit",
- exit_code: exitCode,
- signal: devResult.signal,
- ...(devResult.error ? { error_code: errorCode(devResult.error) } : {}),
+ ...properties,
});
console.error(
`\nDevelopment server exited. Retry with:\n\n> cd ${name}\n> ${devCmd} run dev\n`,
@@ -419,7 +505,7 @@ async function resolveImmediate(
};
} catch (error) {
const { ExitPromptError } = await import("@inquirer/core");
- if (error instanceof ExitPromptError) process.exit(0);
+ if (error instanceof ExitPromptError) throw new CliCancelledError("immediate_prompt");
throw error;
}
}
@@ -436,14 +522,22 @@ async function writeEnv(targetDir: string, result: EnvResult, appId?: string): P
async function resolveChatEnv(interactive: boolean): Promise<EnvResult> {
if (!interactive) return { envWritten: false };
- const { input } = await import("@inquirer/prompts");
- const apiKey = (
- await input({
- message: "Enter your OpenAI-compatible provider API key (leave blank to skip):",
- })
- ).trim();
- if (!apiKey) return { envWritten: false };
- return { envWritten: true, envContent: `OPENAI_API_KEY=${apiKey}\n` };
+ try {
+ const { input } = await import("@inquirer/prompts");
+ const apiKey = (
+ await input({
+ message: "Enter your OpenAI-compatible provider API key (leave blank to skip):",
+ })
+ ).trim();
+ if (!apiKey) return { envWritten: false };
+ return { envWritten: true, envContent: `OPENAI_API_KEY=${apiKey}\n` };
+ } catch (error) {
+ const { ExitPromptError } = await import("@inquirer/core");
+ if (error instanceof ExitPromptError) {
+ throw new CliCancelledError("environment_resolution");
+ }
+ throw error;
+ }
}
async function resolveCloudEnv(
@@ -472,11 +566,26 @@ async function resolveCloudEnv(
auth_succeeded: apiKey != null,
});
} catch (err) {
+ if (err instanceof CliCancelledError) {
+ telemetry.capture("cli_cloud_auth_cancelled", {
+ ...createFunnelProps("cloud_auth_cancelled"),
+ auth_method: options.auth ?? (options.apiKey ? "apikey-flag" : undefined),
+ auth_succeeded: false,
+ ...cliErrorProperties(err),
+ });
+ throw err;
+ }
const msg = err instanceof Error ? err.message : String(err);
+ const properties = cliErrorProperties(err, {
+ failure_stage: "cloud_auth",
+ error_class: "authentication",
+ error_code: "AUTH_FAILED",
+ });
telemetry.capture("cli_cloud_auth_failed", {
- ...createFunnelProps("cloud_auth_resolved"),
+ ...createFunnelProps("cloud_auth_failed"),
auth_method: options.auth ?? (options.apiKey ? "apikey-flag" : undefined),
auth_succeeded: false,
+ ...properties,
});
console.error(`\n⚠ Could not obtain an API key: ${msg}`);
console.error(` Add THESYS_API_KEY to .env later (keys: ${THESYS_KEYS_URL}).\n`);
diff --git a/packages/openui-cli/src/index.ts b/packages/openui-cli/src/index.ts
index 541180751..90ce63fd8 100644
--- a/packages/openui-cli/src/index.ts
+++ b/packages/openui-cli/src/index.ts
@@ -1,5 +1,6 @@
#!/usr/bin/env node
+import { randomUUID } from "node:crypto";
import * as fs from "node:fs";
import * as path from "node:path";
@@ -33,12 +34,15 @@ program.configureHelp({ showGlobalOptions: true });
// Init telemetry once, just before any command runs (honors --no-telemetry / DO_NOT_TRACK).
program.hook("preAction", (_thisCommand, actionCommand) => {
const globalOptions = program.opts<{ agentName: string; telemetry?: boolean }>();
+ const command = actionCommand.name();
telemetry.init({ cliVersion, flagEnabled: globalOptions.telemetry !== false });
telemetry.register({
agent_name: globalOptions.agentName,
detected_agent_name: detectAgent(),
+ cli_run_id: randomUUID(),
+ command,
});
- telemetry.capture("cli_invoked", { command: actionCommand.name() });
+ telemetry.capture("cli_invoked");
});
program
diff --git a/packages/openui-cli/src/lib/create-telemetry.ts b/packages/openui-cli/src/lib/create-telemetry.ts
index 671b4aa82..816f398ca 100644
--- a/packages/openui-cli/src/lib/create-telemetry.ts
+++ b/packages/openui-cli/src/lib/create-telemetry.ts
@@ -14,15 +14,21 @@ const createFunnelSteps = {
env_resolution_started: "0400",
cloud_auth_started: "0410",
cloud_auth_resolved: "0420",
+ cloud_auth_failed: "0425",
+ cloud_auth_cancelled: "0426",
env_written: "0430",
skill_prompt_resolved: "0500",
skill_install_started: "0510",
skill_install_finished: "0520",
+ skill_install_failed: "0525",
+ skill_install_cancelled: "0526",
dependency_install_started: "0600",
dependency_install_succeeded: "0610",
dependency_install_failed: "0620",
+ dependency_install_cancelled: "0625",
create_succeeded: "0700",
create_failed: "9000",
+ create_cancelled: "9010",
} as const;
type CreateFunnelStep = keyof typeof createFunnelSteps;
diff --git a/packages/openui-cli/src/lib/install-skill.ts b/packages/openui-cli/src/lib/install-skill.ts
index ba4a2a50c..465341420 100644
--- a/packages/openui-cli/src/lib/install-skill.ts
+++ b/packages/openui-cli/src/lib/install-skill.ts
@@ -1,4 +1,5 @@
-import { execSync } from "child_process";
+import { runCommand, type CommandResult } from "./process-runner";
+import { CliCancelledError } from "./telemetry";
const OPENUI_SKILL_SOURCE = "thesysdev/skills";
@@ -18,24 +19,17 @@ export async function shouldInstallSkill(
} catch (err) {
const { ExitPromptError } = await import("@inquirer/core");
if (err instanceof ExitPromptError) {
- process.exit(0);
+ throw new CliCancelledError("skill_prompt");
}
throw err;
}
}
-export function runSkillInstall(targetDir: string): void {
+export async function runSkillInstall(targetDir: string): Promise<CommandResult> {
console.info("\nInstalling OpenUI agent skill...\n");
- try {
- execSync(`npx -y skills add ${OPENUI_SKILL_SOURCE} --skill openui -y`, {
- stdio: "inherit",
- cwd: targetDir,
- });
- } catch {
- console.warn(
- "\nCould not install the OpenUI agent skill automatically.\n" +
- "You can install it manually later with:\n\n" +
- ` npx skills add ${OPENUI_SKILL_SOURCE} --skill openui\n`,
- );
- }
+ return runCommand(
+ "npx",
+ ["-y", "skills", "add", OPENUI_SKILL_SOURCE, "--skill", "openui", "-y"],
+ targetDir,
+ );
}
diff --git a/packages/openui-cli/src/lib/process-runner.ts b/packages/openui-cli/src/lib/process-runner.ts
new file mode 100644
index 000000000..d3a160dd1
--- /dev/null
+++ b/packages/openui-cli/src/lib/process-runner.ts
@@ -0,0 +1,79 @@
+import spawn from "cross-spawn";
+
+const DIAGNOSTIC_TAIL_LIMIT = 16 * 1024;
+
+export type CommandResult = {
+ durationMs: number;
+ status: number | null;
+ signal: NodeJS.Signals | null;
+ error?: Error;
+ diagnosticTail: string;
+};
+
+/**
+ * `spawn.sync(..., { stdio: "inherit" })` exposes exit status but not the output
+ * needed to distinguish dependency, workspace, and package-compatibility failures.
+ * This runner preserves normal terminal streaming while retaining only a bounded
+ * local tail for allowlisted classification. The tail must never be sent to telemetry.
+ *
+ * Running asynchronously also lets the parent forward SIGINT/SIGTERM, wait for the
+ * child to close, and return cancellation metadata before telemetry is flushed.
+ */
+export function runCommand(command: string, args: string[], cwd: string): Promise<CommandResult> {
+ return new Promise((resolve) => {
+ const startedAt = Date.now();
+ const child = spawn(command, args, {
+ cwd,
+ stdio: ["inherit", "pipe", "pipe"],
+ });
+ let diagnosticTail = "";
+ let settled = false;
+ let forwardedSignal: NodeJS.Signals | null = null;
+ let forceKillTimer: NodeJS.Timeout | undefined;
+
+ const observe = (chunk: Buffer) => {
+ diagnosticTail = (diagnosticTail + chunk.toString("utf8")).slice(-DIAGNOSTIC_TAIL_LIMIT);
+ };
+ child.stdout?.on("data", (chunk: Buffer) => {
+ process.stdout.write(chunk);
+ observe(chunk);
+ });
+ child.stderr?.on("data", (chunk: Buffer) => {
+ process.stderr.write(chunk);
+ observe(chunk);
+ });
+
+ const finish = (result: Omit<CommandResult, "diagnosticTail" | "durationMs">) => {
+ if (settled) return;
+ settled = true;
+ process.off("SIGINT", onSigint);
+ process.off("SIGTERM", onSigterm);
+ if (forceKillTimer) clearTimeout(forceKillTimer);
+ resolve({
+ ...result,
+ diagnosticTail,
+ durationMs: Math.max(0, Date.now() - startedAt),
+ });
+ };
+
+ // Prevent the parent from exiting before the child reports which signal stopped it.
+ const forwardSignal = (signal: NodeJS.Signals) => {
+ if (forwardedSignal) {
+ child.kill("SIGKILL");
+ return;
+ }
+ forwardedSignal = signal;
+ child.kill(signal);
+ // Do not hang indefinitely when a child ignores the forwarded signal.
+ forceKillTimer = setTimeout(() => child.kill("SIGKILL"), 5000);
+ forceKillTimer.unref();
+ };
+ const onSigint = () => forwardSignal("SIGINT");
+ const onSigterm = () => forwardSignal("SIGTERM");
+
+ process.on("SIGINT", onSigint);
+ process.on("SIGTERM", onSigterm);
+ child.once("error", (error) => finish({ status: null, signal: forwardedSignal, error }));
+ child.once("close", (status, signal) => finish({ status, signal: forwardedSignal ?? signal }));
+ });
+}
diff --git a/packages/openui-cli/src/lib/resolve-args.ts b/packages/openui-cli/src/lib/resolve-args.ts
index 00fe8b5b7..565e936f3 100644
--- a/packages/openui-cli/src/lib/resolve-args.ts
+++ b/packages/openui-cli/src/lib/resolve-args.ts
@@ -1,4 +1,4 @@
-import { CreateError } from "./telemetry";
+import { CliCancelledError, CreateError } from "./telemetry";
type InputPromptConfig = {
type: "input";
@@ -41,7 +41,12 @@ export async function resolveArgs<T extends Record<string, ArgDef<unknown>>>(
}
if (!interactive) {
- throw new CreateError("missing_required_arg", `Missing required argument --${key}`);
+ throw new CreateError(
+ "args_resolution",
+ `Missing required argument --${key}`,
+ "invalid_input",
+ "MISSING_REQUIRED_ARG",
+ );
}
try {
@@ -49,7 +54,7 @@ export async function resolveArgs<T extends Record<string, ArgDef<unknown>>>(
} catch (err) {
const { ExitPromptError } = await import("@inquirer/core");
if (err instanceof ExitPromptError) {
- process.exit(0);
+ throw new CliCancelledError("args_resolution");
}
throw err;
}
diff --git a/packages/openui-cli/src/lib/telemetry.ts b/packages/openui-cli/src/lib/telemetry.ts
index 88e2e624e..3dbcea54b 100644
--- a/packages/openui-cli/src/lib/telemetry.ts
+++ b/packages/openui-cli/src/lib/telemetry.ts
@@ -55,16 +55,61 @@ function writeState(file: string, s: Stored) {
}
/** Thrown by command funnels so the index wrapper can attribute the failure stage + drain once. */
+export type CliErrorClass =
+ | "invalid_input"
+ | "filesystem"
+ | "authentication"
+ | "dependency"
+ | "peer_dependency"
+ | "registry_auth"
+ | "network"
+ | "package_compatibility"
+ | "workspace_config"
+ | "install_script"
+ | "process"
+ | "user_cancelled"
+ | "generation"
+ | "unknown";
+
+export type CliErrorMetadata = {
+ duration_ms?: number;
+ exit_code?: number;
+ failure_signal?: NodeJS.Signals;
+ http_status?: number;
+ cancellation_exit_code?: number;
+ auth_failure_stage?: string;
+};
+
export class CreateError extends Error {
constructor(
public stage: string,
message: string,
+ public errorClass: CliErrorClass = "unknown",
+ public errorCode = "UNKNOWN",
+ public errorMetadata: CliErrorMetadata = {},
) {
super(message);
this.name = "CreateError";
}
}
+export class CliCancelledError extends CreateError {
+ constructor(
+ stage: string,
+ public exitCode = 0,
+ metadata: CliErrorMetadata = {},
+ ) {
+ super(
+ stage,
+ "Operation cancelled.",
+ "user_cancelled",
+ exitCode === 0 ? "USER_CANCELLED" : exitCode === 143 ? "TERMINATED" : "INTERRUPTED",
+ { ...metadata, cancellation_exit_code: exitCode },
+ );
+ this.name = "CliCancelledError";
+ }
+}
+
export class Telemetry {
private client?: PostHog;
private distinctId = "anonymous";
diff --git a/packages/openui-cli/src/lib/utils.ts b/packages/openui-cli/src/lib/utils.ts
index 681ae6220..9f4c6fc47 100644
--- a/packages/openui-cli/src/lib/utils.ts
+++ b/packages/openui-cli/src/lib/utils.ts
@@ -1,33 +1,225 @@
import type { CloudAuthMethod } from "../auth/mint";
import { createFunnelProps } from "./create-telemetry";
import type { TemplateName } from "./create-types";
-import { CreateError, telemetry as defaultTelemetry, type Telemetry } from "./telemetry";
+import type { CommandResult } from "./process-runner";
+import {
+ CliCancelledError,
+ CreateError,
+ telemetry as defaultTelemetry,
+ type CliErrorClass,
+ type CliErrorMetadata,
+ type Telemetry,
+} from "./telemetry";
/** ASCII Record Separator — Untypeable in prompt text and always
* escaped by JSON.stringify, so it can never collide with either artifact. */
export const SEPARATION_DELIMITER = "\u001E";
+export type CliErrorProperties = CliErrorMetadata & {
+ failure_stage: string;
+ error_class: CliErrorClass;
+ error_code: string;
+};
+
+const errnoTelemetry: Record<string, Pick<CliErrorProperties, "error_class" | "error_code">> = {
+ EACCES: { error_class: "filesystem", error_code: "PERMISSION_DENIED" },
+ EPERM: { error_class: "filesystem", error_code: "PERMISSION_DENIED" },
+ ENOENT: { error_class: "filesystem", error_code: "NOT_FOUND" },
+ ENOSPC: { error_class: "filesystem", error_code: "DISK_FULL" },
+};
+
+/** Return only bounded values; never forward an error message or stack. */
+export function cliErrorProperties(
+ error: unknown,
+ fallback: CliErrorProperties = {
+ failure_stage: "unknown",
+ error_class: "unknown",
+ error_code: "UNKNOWN",
+ },
+): CliErrorProperties {
+ if (error instanceof CreateError) {
+ return {
+ failure_stage: error.stage,
+ error_class: error.errorClass,
+ error_code: error.errorCode,
+ ...error.errorMetadata,
+ };
+ }
+
+ const errno = error instanceof Error ? (error as NodeJS.ErrnoException).code : undefined;
+ const classified = errno ? errnoTelemetry[errno] : undefined;
+ return classified ? { ...fallback, ...classified } : fallback;
+}
+
+type ProcessFailureRule = {
+ fingerprints: readonly string[];
+ prefixes?: readonly string[];
+ errorClass: CliErrorClass;
+ errorCode: string;
+};
+
+const processFailureRules = [
+ {
+ fingerprints: ["ERR_PNPM_PEER_DEP_ISSUES", "YN0002", "YN0060", "ERESOLVE"],
+ errorClass: "peer_dependency",
+ errorCode: "PEER_DEPENDENCY",
+ },
+ {
+ fingerprints: ["ERR_PNPM_FETCH_401", "E401", "ENEEDAUTH"],
+ errorClass: "registry_auth",
+ errorCode: "REGISTRY_401",
+ },
+ {
+ fingerprints: ["ERR_PNPM_FETCH_403", "E403"],
+ errorClass: "registry_auth",
+ errorCode: "REGISTRY_403",
+ },
+ {
+ fingerprints: ["ERR_PNPM_FETCH_404", "E404"],
+ errorClass: "dependency",
+ errorCode: "PACKAGE_NOT_FOUND",
+ },
+ {
+ fingerprints: ["ENOTFOUND", "EAI_AGAIN"],
+ errorClass: "network",
+ errorCode: "DNS_FAILED",
+ },
+ {
+ fingerprints: ["ETIMEDOUT", "ESOCKETTIMEDOUT", "ERR_SOCKET_TIMEOUT"],
+ errorClass: "network",
+ errorCode: "NETWORK_TIMEOUT",
+ },
+ {
+ fingerprints: ["ECONNRESET", "ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH"],
+ errorClass: "network",
+ errorCode: "NETWORK_FAILED",
+ },
+ {
+ fingerprints: [
+ "ERR_PNPM_UNSUPPORTED_ENGINE",
+ "ERR_PNPM_BAD_PM_VERSION",
+ "EBADENGINE",
+ "YN0009",
+ ],
+ errorClass: "package_compatibility",
+ errorCode: "ENGINE_MISMATCH",
+ },
+ {
+ fingerprints: ["ERR_PNPM_NO_MATCHING_VERSION", "ETARGET"],
+ errorClass: "package_compatibility",
+ errorCode: "NO_MATCHING_VERSION",
+ },
+ {
+ fingerprints: ["ERR_PNPM_OUTDATED_LOCKFILE", "ERR_PNPM_LOCKFILE_BREAKING_CHANGE"],
+ errorClass: "workspace_config",
+ errorCode: "LOCKFILE_INCOMPATIBLE",
+ },
+ {
+ fingerprints: ["ERR_PNPM_NO_MATCHING_VERSION_INSIDE_WORKSPACE"],
+ prefixes: ["ERR_PNPM_WORKSPACE_"],
+ errorClass: "workspace_config",
+ errorCode: "WORKSPACE_CONFIG_INVALID",
+ },
+ {
+ fingerprints: ["ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL", "ELIFECYCLE"],
+ errorClass: "install_script",
+ errorCode: "INSTALL_SCRIPT_FAILED",
+ },
+ {
+ fingerprints: ["EACCES", "EPERM"],
+ errorClass: "filesystem",
+ errorCode: "PERMISSION_DENIED",
+ },
+ {
+ fingerprints: ["ENOSPC", "EDQUOT"],
+ errorClass: "filesystem",
+ errorCode: "DISK_FULL",
+ },
+] satisfies readonly ProcessFailureRule[];
+
+function classifyProcessDiagnostic(diagnostic: string): ProcessFailureRule | undefined {
+ const tokens = diagnostic.toUpperCase().match(/\b[A-Z][A-Z0-9_]{2,}\b/g) ?? [];
+ const tokenSet = new Set(tokens);
+ return processFailureRules.find(
+ ({ fingerprints, prefixes }) =>
+ fingerprints.some((fingerprint) => tokenSet.has(fingerprint)) ||
+ prefixes?.some((prefix) => tokens.some((token) => token.startsWith(prefix))),
+ );
+}
+
+export function processErrorProperties(
+ result: CommandResult,
+ failureStage: string,
+ fallback: Pick<CliErrorProperties, "error_class" | "error_code">,
+): CliErrorProperties {
+ const metadata: CliErrorMetadata = {
+ duration_ms: result.durationMs,
+ ...(typeof result.status === "number" ? { exit_code: result.status } : {}),
+ ...(result.signal ? { failure_signal: result.signal } : {}),
+ };
+ const cancellationExitCode =
+ result.signal === "SIGINT" || result.status === 130
+ ? 130
+ : result.signal === "SIGTERM" || result.status === 143
+ ? 143
+ : undefined;
+ if (cancellationExitCode) {
+ return {
+ failure_stage: failureStage,
+ error_class: "user_cancelled",
+ error_code: cancellationExitCode === 130 ? "INTERRUPTED" : "TERMINATED",
+ ...metadata,
+ cancellation_exit_code: cancellationExitCode,
+ };
+ }
+
+ const diagnostic = `${result.error?.message ?? ""}\n${result.diagnosticTail}`;
+ const rule = classifyProcessDiagnostic(diagnostic);
+ if (rule) {
+ return {
+ failure_stage: failureStage,
+ error_class: rule.errorClass,
+ error_code: rule.errorCode,
+ ...metadata,
+ };
+ }
+
+ const spawnCode = result.error ? (result.error as NodeJS.ErrnoException).code : undefined;
+ if (spawnCode === "ENOENT") {
+ return {
+ failure_stage: failureStage,
+ error_class: "process",
+ error_code: "COMMAND_NOT_FOUND",
+ ...metadata,
+ };
+ }
+
+ return { failure_stage: failureStage, ...fallback, ...metadata };
+}
+
export function handleCliError(
e: unknown,
event: string,
telemetry: Telemetry = defaultTelemetry,
): void {
- const known = e instanceof CreateError;
+ const cancelled = e instanceof CliCancelledError;
const message = e instanceof Error ? e.message : String(e);
- console.error(known ? `Error: ${message}` : message);
+ if (cancelled) console.info("Cancelled.");
+ else console.error(e instanceof CreateError ? `Error: ${message}` : message);
+
+ const errorProperties = cliErrorProperties(e);
+ const capturedEvent = cancelled ? event.replace(/_failed$/, "_cancelled") : event;
if (event === "cli_create_failed") {
- // Do not send raw create error messages: they can include user-entered
- // project names or paths. The funnel rank is enough to count this drop-off.
- telemetry.capture(event, createFunnelProps("create_failed"));
- } else {
- telemetry.capture(event, {
- stage: known ? e.stage : "unknown",
- error: message.slice(0, 200),
+ telemetry.capture(capturedEvent, {
+ ...createFunnelProps(cancelled ? "create_cancelled" : "create_failed"),
+ ...errorProperties,
});
+ } else {
+ telemetry.capture(capturedEvent, errorProperties);
}
- process.exitCode = 1;
+ process.exitCode = cancelled ? e.exitCode : 1;
}
export function normalizeTemplate(t?: string): TemplateName | undefined {
@@ -36,8 +228,10 @@ export function normalizeTemplate(t?: string): TemplateName | undefined {
if (v === "self-hosted" || v === "openui-self-hosted") return "openui-self-hosted";
if (v === "cloud" || v === "openui-cloud") return "openui-cloud";
throw new CreateError(
- "bad_args",
+ "args_resolution",
`unknown template "${t}". Use: openui-self-hosted | openui-cloud.`,
+ "invalid_input",
+ "INVALID_TEMPLATE",
);
}
@@ -46,7 +240,9 @@ export function normalizeAuth(a?: string): CloudAuthMethod | undefined {
const v = a.toLowerCase();
if (v === "oauth" || v === "manual" || v === "skip") return v;
throw new CreateError(
- "bad_args",
+ "args_resolution",
`unknown --auth "${a}". Use: oauth | skip (manual is deprecated).`,
+ "invalid_input",
+ "INVALID_AUTH",
);
}