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.mdxindex 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. Eithervalue 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 alsodiff --git a/packages/openui-cli/README.md b/packages/openui-cli/README.mdindex 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 accounWhen 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`.```bashopenui create --no-telemetrydiff --git a/packages/openui-cli/src/auth/mint.ts b/packages/openui-cli/src/auth/mint.tsindex 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.tsindex 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): Pasync 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.tsindex 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");});programdiff --git a/packages/openui-cli/src/lib/create-telemetry.ts b/packages/openui-cli/src/lib/create-telemetry.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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",);}