cli: preflight git check and network retries in openui create (#1223)

* cli: add create preflight and network retries

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* cli: drop unit tests from create preflight/retry change

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* cli: move retry telemetry reporter to base Telemetry

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* cli: rename Telemetry.retryReporter to reportRetry

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* cli: extract retry default constants

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* cli: split withRetry consumers into fn and options

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* cli: rename templateSourceError to throwTemplateSourceError

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* cli: inline trackNetworkRetry into reportRetry

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* cli: rename reportRetry to reportNetworkRetry

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* cli: withRetry(label, fn, options?) with network-only default

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* cli: simplify fetch failure message

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* cli: reuse throwCommandFailure for dependency install errors

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

---------

Co-authored-by: Zahle Khan <zahle@thesys.dev>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: devin-ai-integration[bot]

.changeset/cli-create-preflight-retry.md

@@ -0,0 +1,5 @@
+---
+"@openuidev/cli": patch
+---
+
+Add a preflight git check with per-OS install hints, retry network failures with backoff during source checkout, catalog fetch, and dependency installation, and record retry attempts in failure telemetry alongside a new `cli_network_retry` event.

packages/openui-cli/src/commands/create/lib/create-example.ts

@@ -57,6 +57,7 @@ export async function runCreateExample(params: {
         targetDir,
         name,
         packageManager: packageManager.name,
+        onRetry: tel.reportNetworkRetry("source_checkout"),
       });
     layout = verbose ? await runScaffold() : await withSpinner("Scaffolding...", runScaffold);
     if (!verbose) {

packages/openui-cli/src/commands/create/lib/examples-catalog.ts

@@ -2,6 +2,7 @@ import { styleText } from "node:util";
 
 import { fetchSourceFile } from "../../../lib/checkout";
 import { CreateError } from "../../../lib/errors";
+import type { RetryAttemptInfo } from "../../../lib/retry";
 
 export const EXAMPLES_CATALOG_PATH = "examples/examples.json";
 
@@ -65,8 +66,12 @@ function parseExamplesCatalog(raw: string): ExampleProject[] {
 }
 
 /** Prefetch the examples catalog from GitHub. */
-export async function loadExamplesCatalog(): Promise<ExampleProject[]> {
-  const { content } = await fetchSourceFile(EXAMPLES_CATALOG_PATH);
+export async function loadExamplesCatalog(
+  opts: {
+    onRetry?: (info: RetryAttemptInfo) => void;
+  } = {},
+): Promise<ExampleProject[]> {
+  const { content } = await fetchSourceFile(EXAMPLES_CATALOG_PATH, { onRetry: opts.onRetry });
   return parseExamplesCatalog(content);
 }
 

packages/openui-cli/src/commands/create/lib/install.ts

@@ -3,8 +3,9 @@ import * as path from "node:path";
 
 import { printLogTail, QUIET_COMMAND_CAPTURE_LIMIT } from "../../../lib/command-output";
 import type { PackageManager } from "../../../lib/detect-package-manager";
-import { CliCancelledError, CreateError, processErrorProperties } from "../../../lib/errors";
+import { CliCancelledError, cliErrorProperties, throwCommandFailure } from "../../../lib/errors";
 import { mutedNpmEnv, runCommand } from "../../../lib/process-runner";
+import { withRetry } from "../../../lib/retry";
 import { withSpinner } from "../../../lib/spinner";
 import type { OverlayName, TemplateName } from "./create-types";
 import type { CreateTelemetryClient } from "./telemetry";
@@ -82,53 +83,47 @@ export async function installProjectDependencies(params: {
   if (verbose) {
     console.info(`Installing dependencies with: ${installCmd}\n`);
   }
-  const installResult = verbose
-    ? await runInstall()
-    : await withSpinner("Installing dependencies...", runInstall);
-  if (!installResult.error && installResult.status === 0) {
+  const attemptInstall = async () => {
+    const result = await runInstall();
+    if (!result.error && result.status === 0) return result;
+
     if (!verbose) {
-      console.info("✓ Dependencies installed");
+      printLogTail(result.diagnosticTail, "install log (tail)");
     }
-    tel.trackDependencyInstallSucceeded({
-      template,
-      ai_setup: aiSetup,
-      dependency_installed: true,
+    throwCommandFailure(result, "dependency_install", "dependency install failed", {
+      error_class: "dependency",
+      error_code: "NONZERO_EXIT",
     });
-    return true;
-  }
+  };
 
-  if (!verbose) {
-    printLogTail(installResult.diagnosticTail, "install log (tail)");
-  }
-  const properties = processErrorProperties(installResult, "dependency_install", {
-    error_class: "dependency",
-    error_code: "NONZERO_EXIT",
-  });
-  if (properties.error_class === "user_cancelled") {
-    tel.trackDependencyInstallCancelled({
+  try {
+    const runWithRetry = () =>
+      withRetry("Dependency install", attemptInstall, {
+        onRetry: tel.reportNetworkRetry("dependency_install"),
+      });
+    await (verbose ? runWithRetry() : withSpinner("Installing dependencies...", runWithRetry));
+  } catch (err) {
+    const properties = {
       template,
       ai_setup: aiSetup,
       dependency_installed: false,
-      ...properties,
-    });
-    throw new CliCancelledError(
-      "dependency_install",
-      properties.cancellation_exit_code ?? 0,
-      properties,
-    );
+      ...cliErrorProperties(err),
+    };
+    if (err instanceof CliCancelledError) {
+      tel.trackDependencyInstallCancelled(properties);
+    } else {
+      tel.trackDependencyInstallFailed(properties);
+    }
+    throw err;
+  }
+
+  if (!verbose) {
+    console.info("✓ Dependencies installed");
   }
-  tel.trackDependencyInstallFailed({
+  tel.trackDependencyInstallSucceeded({
     template,
     ai_setup: aiSetup,
-    dependency_installed: false,
-    ...properties,
+    dependency_installed: true,
   });
-  const { failure_stage, error_class, error_code, ...metadata } = properties;
-  throw new CreateError(
-    failure_stage,
-    "dependency install failed",
-    error_class,
-    error_code,
-    metadata,
-  );
+  return true;
 }

packages/openui-cli/src/commands/create/lib/resolve.ts

@@ -1,5 +1,6 @@
 import { CliCancelledError, CreateError } from "../../../lib/errors";
 import { resolveArgs } from "../../../lib/resolve-args";
+import type { RetryAttemptInfo } from "../../../lib/retry";
 import type { OverlayName, TemplateName } from "./create-types";
 import {
   findExample,
@@ -40,8 +41,9 @@ export async function loadCreateCatalog(params: {
   template?: TemplateName;
   backendFramework?: OverlayName;
   interactive: boolean;
+  onRetry?: (info: RetryAttemptInfo) => void;
 }): Promise<CreateCatalog> {
-  const { example, template: requestedTemplate, backendFramework, interactive } = params;
+  const { example, template: requestedTemplate, backendFramework, interactive, onRetry } = params;
 
   rejectConflictingScaffoldSelectors({
     example,
@@ -61,13 +63,16 @@ export async function loadCreateCatalog(params: {
   }
 
   if (example) {
-    const examples = await loadExamplesCatalog();
+    const examples = await loadExamplesCatalog({ onRetry });
     findExample(example, examples);
     return { examples };
   }
 
   if (interactive) {
-    const [catalog, examples] = await Promise.all([loadTemplatesCatalog(), loadExamplesCatalog()]);
+    const [catalog, examples] = await Promise.all([
+      loadTemplatesCatalog({ onRetry }),
+      loadExamplesCatalog({ onRetry }),
+    ]);
     const template = requestedTemplate ?? DEFAULT_TEMPLATE_KEY;
     const templateEntry = findCatalogTemplate(catalog, template);
     if (backendFramework) {
@@ -76,7 +81,7 @@ export async function loadCreateCatalog(params: {
     return { examples, template, templateEntry };
   }
 
-  const catalog = await loadTemplatesCatalog();
+  const catalog = await loadTemplatesCatalog({ onRetry });
   const template = requestedTemplate ?? DEFAULT_TEMPLATE_KEY;
   const templateEntry = findCatalogTemplate(catalog, template);
   if (backendFramework) {

packages/openui-cli/src/commands/create/lib/scaffold-example.ts

@@ -5,6 +5,7 @@ import * as path from "node:path";
 import { checkoutSource } from "../../../lib/checkout";
 import type { PackageManagerName } from "../../../lib/detect-package-manager";
 import { CreateError } from "../../../lib/errors";
+import type { RetryAttemptInfo } from "../../../lib/retry";
 import type { ExampleProject } from "./examples-catalog";
 
 const ARTIFACT_DIRS = new Set(["node_modules", ".next", ".turbo", "dist", ".nuxt", ".svelte-kit"]);
@@ -159,11 +160,12 @@ export async function scaffoldExample(params: {
   targetDir: string;
   name: string;
   packageManager: PackageManagerName;
+  onRetry?: (info: RetryAttemptInfo) => void;
 }): Promise<ExampleLayout> {
-  const { example, targetDir, name, packageManager } = params;
+  const { example, targetDir, name, packageManager, onRetry } = params;
 
   try {
-    await checkoutSource(example.path, { dest: targetDir });
+    await checkoutSource(example.path, { dest: targetDir, onRetry });
   } catch (err) {
     if (err instanceof CreateError) throw err;
     throw new CreateError(

packages/openui-cli/src/commands/create/lib/templates-catalog.ts

@@ -1,5 +1,6 @@
 import { fetchSourceFile } from "../../../lib/checkout";
 import { CreateError } from "../../../lib/errors";
+import type { RetryAttemptInfo } from "../../../lib/retry";
 
 export const TEMPLATES_CATALOG_PATH = "templates/templates.json";
 
@@ -62,8 +63,12 @@ function parseTemplatesCatalog(raw: string): CatalogTemplate[] {
 }
 
 /** Prefetch the template catalog from GitHub. */
-export async function loadTemplatesCatalog(): Promise<CatalogTemplate[]> {
-  const { content } = await fetchSourceFile(TEMPLATES_CATALOG_PATH);
+export async function loadTemplatesCatalog(
+  opts: {
+    onRetry?: (info: RetryAttemptInfo) => void;
+  } = {},
+): Promise<CatalogTemplate[]> {
+  const { content } = await fetchSourceFile(TEMPLATES_CATALOG_PATH, { onRetry: opts.onRetry });
   return parseTemplatesCatalog(content);
 }
 

packages/openui-cli/src/commands/create/run.ts

@@ -1,8 +1,10 @@
 import * as fs from "node:fs";
 
+import { localSourceDir } from "../../lib/checkout";
 import type { CliContext } from "../../lib/context";
 import { resolveInstallPackageManager } from "../../lib/detect-package-manager";
 import { cliErrorProperties, CreateError, processErrorProperties } from "../../lib/errors";
+import { ensureGitAvailable } from "../../lib/git-preflight";
 import { applyScaffoldFiles, resolveTemplateSource } from "../../lib/scaffold";
 import { withSpinner } from "../../lib/spinner";
 import { runCreateExample } from "./lib/create-example";
@@ -46,11 +48,14 @@ export async function runCreateApp(options: CreateAppOptions, ctx: CliContext):
     immediate_arg: options.immediate,
   });
 
+  if (!localSourceDir()) await ensureGitAvailable();
+  const sourceRetryReporter = tel.reportNetworkRetry("source_checkout");
   const catalog = await loadCreateCatalog({
     example: options.example,
     template: options.template,
     backendFramework: options.backendFramework,
     interactive,
+    onRetry: sourceRetryReporter,
   });
   const { name, targetDir } = await resolveProjectIdentity(options.name, interactive, tel);
 
@@ -123,7 +128,9 @@ export async function runCreateApp(options: CreateAppOptions, ctx: CliContext):
 
   let overlay: TemplateOverlay | undefined;
   const runScaffold = async () => {
-    const { dir: templateDir } = await resolveTemplateSource(template);
+    const { dir: templateDir } = await resolveTemplateSource(template, {
+      onRetry: sourceRetryReporter,
+    });
     tel.trackScaffoldStarted({ template, ai_setup: aiSetup });
     try {
       overlay = applyScaffoldFiles({