Skip to content

The Open Standard for Generative UI

8.3 KB
Raw Blame
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, writeAgentsGuide } from "../../lib/scaffold";
import { withSpinner } from "../../lib/spinner";
import { runCreateExample } from "./lib/create-example";
import type { CreateAppOptions } from "./lib/create-types";
import { runDevCommand } from "./lib/dev-server";
import { buildAppId, resolveCloudEnv, writeEnv } from "./lib/env";
import { installProjectDependencies, resolveInstallInvocation } from "./lib/install";
import { getStartedMessage, readmePath } from "./lib/messages";
import type { TemplateOverlay } from "./lib/overlays";
import {
  loadCreateCatalog,
  resolveCreateSelection,
  resolveImmediate,
  resolveProjectIdentity,
} from "./lib/resolve";
import { aiSetupFromTemplate, CreateTelemetryClient } from "./lib/telemetry";
import { findCatalogOverlay } from "./lib/templates-catalog";

export async function runCreateApp(options: CreateAppOptions, ctx: CliContext): Promise<void> {
  const tel = new CreateTelemetryClient(ctx.telemetry);
  const interactive = ctx.canPrompt;
  const agent = ctx.activeAgent;
  const packageManager = resolveInstallPackageManager();
  const t0 = Date.now();
  tel.registerContext({ package_manager: packageManager.name });
  tel.trackStarted({
    has_name_arg: Boolean(options.name),
    has_backend_framework_arg: Boolean(options.backendFramework),
    has_example_arg: Boolean(options.example),
    no_install: Boolean(options.noInstall),
    immediate_arg: options.immediate,
  });

  if (!localSourceDir()) await ensureGitAvailable();
  const sourceRetryReporter = tel.reportNetworkRetry("source_checkout");
  const catalog = await loadCreateCatalog({
    example: options.example,
    backendFramework: options.backendFramework,
    interactive,
    onRetry: sourceRetryReporter,
  });
  const { name, targetDir, dir } = await resolveProjectIdentity(options.name, interactive, tel);

  const selected = await resolveCreateSelection({
    backendFramework: options.backendFramework,
    example: options.example,
    examples: catalog.examples,
    overlays: catalog.templateEntry?.overlays ?? [],
    interactive,
  });
  if (selected.kind === "example") {
    await runCreateExample({
      options,
      interactive,
      agent,
      packageManager,
      t0,
      name,
      dir,
      targetDir,
      example: selected.example,
      tel,
      verbose: ctx.verbose,
    });
    return;
  }

  const template = catalog.template;
  const templateEntry = catalog.templateEntry;
  if (!template || !templateEntry) {
    throw new CreateError(
      "args_resolution",
      "The OpenUI Cloud template is missing from the template catalog.",
      "network",
      "TEMPLATE_NOT_FOUND",
    );
  }

  const backendFramework = selected.overlay;
  findCatalogOverlay(templateEntry, backendFramework);

  const aiSetup = aiSetupFromTemplate(template);
  tel.registerContext({ template, ai_setup: aiSetup, backend_framework: backendFramework });
  tel.trackAiSetupSelected({ template, ai_setup: aiSetup });
  tel.trackBackendFrameworkSelected({
    backend_framework: backendFramework,
    backend_framework_source: options.backendFramework
      ? "flag"
      : interactive
        ? "prompt"
        : "default",
  });

  tel.trackEnvResolutionStarted({ template, ai_setup: aiSetup });
  const envResult = await resolveCloudEnv(name, options, interactive, agent, tel);

  const immediateResolution = resolveImmediate(options.immediate, options.noInstall, interactive);
  const apiKeyEnv = "THESYS_API_KEY";
  const apiKeyAvailable = envResult.envWritten || Boolean(process.env[apiKeyEnv]?.trim());
  const devStartBlockedByMissingApiKey = immediateResolution.immediate && !apiKeyAvailable;
  tel.trackImmediateSelected({
    immediate: immediateResolution.immediate,
    dependency_install_requested: immediateResolution.installDependencies,
    selection_source: immediateResolution.source,
  });

  let overlay: TemplateOverlay | undefined;
  const runScaffold = async () => {
    const { dir: templateDir } = await resolveTemplateSource(template, {
      onRetry: sourceRetryReporter,
    });
    tel.trackScaffoldStarted({ template, ai_setup: aiSetup });
    try {
      overlay = applyScaffoldFiles({
        templateDir,
        targetDir,
        name,
        packageManager: packageManager.name,
        backendFramework,
      });
      await writeEnv(targetDir, envResult, buildAppId(name));
      if (!options.noSkill) await writeAgentsGuide(targetDir, { onRetry: sourceRetryReporter });
    } catch (err) {
      const properties = cliErrorProperties(err, {
        failure_stage: "scaffold",
        error_class: "filesystem",
        error_code: "SCAFFOLD_FAILED",
      });
      tel.trackScaffoldFailed({ template, ai_setup: aiSetup, ...properties });
      throw new CreateError(
        properties.failure_stage,
        err instanceof Error ? err.message : String(err),
        properties.error_class,
        properties.error_code,
      );
    } finally {
      fs.rmSync(templateDir, { recursive: true, force: true });
    }
  };

  console.info();
  if (ctx.verbose) {
    console.info(`Scaffolding ${template} into "${name}"...\n`);
    await runScaffold();
  } else {
    await withSpinner("Scaffolding...", runScaffold);
    console.info("✓ Scaffolded");
  }
  tel.trackScaffoldSucceeded({ template, ai_setup: aiSetup });
  tel.trackEnvResolved({
    template,
    ai_setup: aiSetup,
    env_written: envResult.envWritten,
    auth_method: envResult.authMethod,
    auth_succeeded: envResult.authSucceeded,
  });

  const { installCmd, installArgs } = resolveInstallInvocation({
    backendFramework,
    packageManager,
    targetDir,
  });
  const dependencyInstalled = await installProjectDependencies({
    tel,
    verbose: ctx.verbose,
    targetDir,
    template,
    aiSetup,
    packageManager,
    installCmd,
    installArgs,
    installDependencies: immediateResolution.installDependencies,
  });

  const devCmd = packageManager.runCmd;
  const startDev =
    immediateResolution.immediate && dependencyInstalled && !devStartBlockedByMissingApiKey;

  tel.trackCreateSucceeded({
    template,
    ai_setup: aiSetup,
    duration_ms: Date.now() - t0,
    env_written: envResult.envWritten,
    dependency_installed: dependencyInstalled,
  });
  console.info(
    getStartedMessage({
      name,
      dir,
      devCmd,
      dlxCmd: packageManager.dlxCmd,
      backendGettingStarted: overlay?.manifest.gettingStarted,
      envWritten: envResult.envWritten,
      apiKeyAvailable,
      startDev,
      installCmd,
      dependencyInstalled,
      agentReadmePath: agent ? readmePath(targetDir) : undefined,
      skillHint: options.noSkill,
    }),
  );

  if (devStartBlockedByMissingApiKey) {
    tel.trackDevCommandSkipped({
      skip_reason: "missing_api_key",
      required_env: apiKeyEnv,
    });
    return;
  }

  if (!startDev) {
    tel.trackDevCommandSkipped({
      skip_reason: options.noInstall ? "dependencies_not_installed" : "not_immediate",
    });
    return;
  }

  tel.trackDevCommandStarted({
    package_manager: packageManager.name,
  });
  const devResult = await runDevCommand(devCmd, targetDir);
  const stoppedNormally =
    devResult.status === 0 ||
    devResult.status === 130 ||
    devResult.status === 143 ||
    devResult.signal === "SIGINT" ||
    devResult.signal === "SIGTERM";

  if (stoppedNormally) {
    tel.trackDevCommandStopped({
      package_manager: packageManager.name,
      duration_ms: devResult.durationMs,
      exit_code: devResult.status,
      failure_signal: devResult.signal,
    });
  } else {
    const exitCode = devResult.status ?? 1;
    const properties = processErrorProperties(devResult, "dev_server", {
      error_class: "process",
      error_code: "NONZERO_EXIT",
    });
    tel.trackDevCommandFailed({
      package_manager: packageManager.name,
      failure_reason: devResult.error ? "spawn_error" : "nonzero_exit",
      ...properties,
    });
    console.error(
      `\nDevelopment server exited. Retry with:\n\n> cd ${name}\n> ${devCmd} run dev\n`,
    );
    process.exitCode = exitCode;
  }
}