Skip to content

The Open Standard for Generative UI

8.3 KB
Raw Blame
import { styleText } from "node:util";

import { fetchSourceFile, type SourceRepo } from "../../../lib/checkout";
import { CreateError } from "../../../lib/errors";
import type { RetryAttemptInfo } from "../../../lib/retry";

export const EXAMPLES_CATALOG_PATH = "examples/examples.json";

/** GitHub owners whose repositories `--example repo:<owner>/<repo>[/<path>]` may clone. */
const ALLOWED_EXAMPLE_REPO_OWNERS = ["thesysdev"];

/** Catalog `path` prefix for an example outside the OpenUI repo: `repo:<owner>/<repo>[/<path>]`. */
const REPO_PATH_PREFIX = "repo:";

const REPO_SEGMENT_RE = /^[A-Za-z0-9_.-]+$/;

export type ExampleProject = {
  name: string;
  label: string;
  description: string;
  /** Path inside the source repo, e.g. `examples/app-frameworks/vue`; `""` is the repo root. */
  path: string;
  /** Source repository. Omitted means the OpenUI repo. */
  repo?: SourceRepo;
  env: {
    /** Environment file relative to the example root. */
    file: string;
    /** Primary env var to prompt for. Omit when the example needs several keys. */
    key?: string;
  };
  /** Show this example in the curated interactive picker. */
  featured?: boolean;
};

function catalogError(message: string): CreateError {
  return new CreateError("args_resolution", message, "invalid_input", "EXAMPLES_CATALOG_INVALID");
}

/** Parse `[repo:]<owner>/<repo>[/<path>]`; `undefined` when invalid or the owner is not allowed. */
function parseRepoSpec(spec: string): { repo: SourceRepo; subpath: string } | undefined {
  const withoutPrefix = spec.startsWith(REPO_PATH_PREFIX)
    ? spec.slice(REPO_PATH_PREFIX.length)
    : spec;
  const [owner = "", name = "", ...rest] = withoutPrefix.replace(/^\/+|\/+$/g, "").split("/");
  const subpath = rest.filter(Boolean);
  if (
    !REPO_SEGMENT_RE.test(owner) ||
    !REPO_SEGMENT_RE.test(name) ||
    !ALLOWED_EXAMPLE_REPO_OWNERS.includes(owner.toLowerCase()) ||
    subpath.some((part) => part === "." || part === "..")
  ) {
    return undefined;
  }
  return { repo: { owner, name }, subpath: subpath.join("/") };
}

function parseCatalogEntry(item: unknown): ExampleProject {
  const entry = item as {
    title?: unknown;
    description?: unknown;
    path?: unknown;
    env?: unknown;
    featured?: unknown;
  };
  if (
    typeof entry.title !== "string" ||
    typeof entry.description !== "string" ||
    typeof entry.path !== "string"
  ) {
    throw catalogError(
      `${EXAMPLES_CATALOG_PATH} has an example missing title, description, or path.`,
    );
  }
  if (entry.featured !== undefined && typeof entry.featured !== "boolean") {
    throw catalogError(`${EXAMPLES_CATALOG_PATH} has an example with an invalid featured flag.`);
  }
  let repo: SourceRepo | undefined;
  let relative = entry.path.replace(/^\/+/, "");
  if (relative.startsWith(REPO_PATH_PREFIX)) {
    const parsed = parseRepoSpec(relative);
    if (!parsed) {
      throw catalogError(
        `${EXAMPLES_CATALOG_PATH} has an invalid path "${entry.path}". Use ${REPO_PATH_PREFIX}<owner>/<repo>[/<path>] with a repository from ${ALLOWED_EXAMPLE_REPO_OWNERS.join(", ")}.`,
      );
    }
    repo = parsed.repo;
    relative = parsed.subpath;
  }
  const name = relative.split("/").filter(Boolean).at(-1) ?? repo?.name;
  if (!name) {
    throw catalogError(`${EXAMPLES_CATALOG_PATH} has an example with an empty path.`);
  }
  if (
    entry.env !== undefined &&
    (typeof entry.env !== "object" || entry.env === null || Array.isArray(entry.env))
  ) {
    throw catalogError(`${EXAMPLES_CATALOG_PATH} example "${name}" has an invalid env.`);
  }
  const env = (entry.env ?? {}) as { file?: unknown; key?: unknown };
  if (env.key !== undefined) {
    if (typeof env.key !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(env.key)) {
      throw catalogError(`${EXAMPLES_CATALOG_PATH} example "${name}" has an invalid env.key.`);
    }
  }
  const file = env.file ?? ".env";
  if (typeof file !== "string" || !/^(?:[A-Za-z0-9_-]+\/)*\.env(?:\.local)?$/.test(file)) {
    throw catalogError(`${EXAMPLES_CATALOG_PATH} example "${name}" has an invalid env.file.`);
  }
  return {
    name,
    label: entry.title,
    description: entry.description,
    path: repo || relative.startsWith("examples/") ? relative : `examples/${relative}`,
    repo,
    env: { file, key: typeof env.key === "string" ? env.key : undefined },
    featured: entry.featured === true,
  };
}

function parseExamplesCatalog(raw: string): ExampleProject[] {
  const parsed = JSON.parse(raw) as { examples?: unknown };
  if (!Array.isArray(parsed.examples) || parsed.examples.length === 0) {
    throw catalogError(`${EXAMPLES_CATALOG_PATH} must contain a non-empty "examples" array.`);
  }
  return parsed.examples.map(parseCatalogEntry);
}

/** Prefetch the examples catalog from GitHub. */
export async function loadExamplesCatalog(
  opts: {
    onRetry?: (info: RetryAttemptInfo) => void;
  } = {},
): Promise<ExampleProject[]> {
  const { content } = await fetchSourceFile(EXAMPLES_CATALOG_PATH, { onRetry: opts.onRetry });
  return parseExamplesCatalog(content);
}

/** Keep catalog order so curators control which five examples are shown. */
export function featuredExamples(examples: ExampleProject[]): ExampleProject[] {
  return examples.filter((example) => example.featured === true).slice(0, 5);
}

function sameRepo(a: SourceRepo | undefined, b: SourceRepo): boolean {
  const left = a ?? { owner: "thesysdev", name: "openui" };
  return (
    left.owner.toLowerCase() === b.owner.toLowerCase() &&
    left.name.toLowerCase() === b.name.toLowerCase()
  );
}

/** Resolve `repo:<owner>/<repo>[/<path>]`, preferring a matching catalog entry for its env setup. */
function findRepoExample(spec: string, examples: ExampleProject[]): ExampleProject {
  const parsed = parseRepoSpec(spec);
  if (!parsed) {
    throw new CreateError(
      "args_resolution",
      `unsupported example repository "${spec}". Use ${REPO_PATH_PREFIX}<owner>/<repo>[/<path>] with a repository from ${ALLOWED_EXAMPLE_REPO_OWNERS.join(", ")}, or an example name from ${EXAMPLES_CATALOG_PATH}.`,
      "invalid_input",
      "INVALID_EXAMPLE",
    );
  }
  const { repo, subpath } = parsed;
  const match = examples.find((entry) => sameRepo(entry.repo, repo) && entry.path === subpath);
  if (match) return match;
  return {
    name: subpath.split("/").at(-1) || repo.name,
    label: `${repo.owner}/${repo.name}${subpath ? `/${subpath}` : ""}`,
    description: "",
    path: subpath,
    repo,
    env: { file: ".env" },
  };
}

export function findExample(name: string, examples: ExampleProject[]): ExampleProject {
  if (name.startsWith(REPO_PATH_PREFIX) && name.includes("/")) {
    return findRepoExample(name, examples);
  }
  const normalized = name.toLowerCase();
  const match = examples.find((entry) => entry.name.toLowerCase() === normalized);
  if (!match) {
    const available = examples.map((entry) => entry.name).join(" | ") || "(none loaded)";
    throw new CreateError(
      "args_resolution",
      `unknown example "${name}". Use: ${available}.`,
      "invalid_input",
      "INVALID_EXAMPLE",
    );
  }
  return match;
}

export function rejectConflictingScaffoldSelectors(opts: {
  example?: string;
  backendFramework?: string;
}): void {
  if (opts.example && opts.backendFramework) {
    throw new CreateError(
      "bad_args",
      "Cannot use --example with --backend-framework. Choose one scaffold selector.",
      "invalid_input",
      "CONFLICTING_SCAFFOLD_SELECTORS",
    );
  }
}

function categoryLabel(key: string): string {
  return key
    .split("-")
    .map((part, index) => (index === 0 ? part.charAt(0).toUpperCase() + part.slice(1) : part))
    .join(" ");
}

export function groupedExampleChoices(
  examples: ExampleProject[],
  Separator: new (heading?: string) => object,
): unknown[] {
  const groups = new Map<string, ExampleProject[]>();
  for (const example of examples) {
    const key = example.repo
      ? "miscellaneous"
      : (example.path.replace(/^examples\//, "").split("/")[0] ?? "miscellaneous");
    const group = groups.get(key) ?? [];
    group.push(example);
    groups.set(key, group);
  }

  const choices: unknown[] = [];
  for (const [key, group] of groups) {
    choices.push(new Separator(styleText("bold", categoryLabel(key))));
    for (const project of group) {
      choices.push({
        value: project.name,
        name: project.label,
        description: project.description,
      });
    }
  }
  return choices;
}