The Open Standard for Generative UI
feat(cli): scaffold examples from thesysdev repositories with --example repo:<owner>/<repo> (#1342)
devin-ai-integration[bot]9aa077167a97
diff --git a/.changeset/example-repos.md b/.changeset/example-repos.mdnew file mode 100644index 000000000..a9ab950bf--- /dev/null+++ b/.changeset/example-repos.md@@ -0,0 +1,5 @@+---+"@openuidev/cli": patch+---++Let `create --example` scaffold from other `thesysdev` GitHub repositories, and add Open Intelligent UI to the example catalog.diff --git a/docs/lib/examples-catalog.ts b/docs/lib/examples-catalog.tsindex 20da5bee4..d125542fb 100644--- a/docs/lib/examples-catalog.ts+++ b/docs/lib/examples-catalog.ts@@ -76,7 +76,9 @@ export type RepoExample = {env?: { file: string; key?: string };};-export const REPO_EXAMPLES: RepoExample[] = catalog.examples.map((example) => {+export const REPO_EXAMPLES: RepoExample[] = catalog.examples.flatMap((example) => {+ // `repo:` paths live in another repository, outside `examples/`.+ if (example.path.startsWith("repo:")) return [];const [category, name] = example.path.split("/") as [ExampleCategoryId, string];return {diff --git a/examples/examples.json b/examples/examples.jsonindex 679f69600..d0813fce7 100644--- a/examples/examples.json+++ b/examples/examples.json@@ -18,6 +18,16 @@"key": "THESYS_API_KEY"}},+ {+ "title": "Open Intelligent UI",+ "description": "An open-source take on ChatGPT's Intelligent UI.",+ "path": "repo:thesysdev/open-intelligent-ui",+ "env": {+ "file": ".env",+ "key": "THESYS_API_KEY"+ },+ "featured": true+ },{"title": "Mastra","description": "A Mastra agent connected to OpenUI through AG-UI.",diff --git a/packages/openui-cli/src/commands/create/lib/examples-catalog.ts b/packages/openui-cli/src/commands/create/lib/examples-catalog.tsindex 37d63eaa3..84d6be357 100644--- a/packages/openui-cli/src/commands/create/lib/examples-catalog.ts+++ b/packages/openui-cli/src/commands/create/lib/examples-catalog.ts@@ -1,17 +1,27 @@import { styleText } from "node:util";-import { fetchSourceFile } from "../../../lib/checkout";+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 OpenUI repo, e.g. `examples/app-frameworks/vue`. */+ /** 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;@@ -26,6 +36,24 @@ 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;@@ -46,8 +74,19 @@ function parseCatalogEntry(item: unknown): ExampleProject {if (entry.featured !== undefined && typeof entry.featured !== "boolean") {throw catalogError(`${EXAMPLES_CATALOG_PATH} has an example with an invalid featured flag.`);}- const relative = entry.path.replace(/^\/+/, "");- const name = relative.split("/").filter(Boolean).at(-1);+ 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.`);}@@ -71,7 +110,8 @@ function parseCatalogEntry(item: unknown): ExampleProject {name,label: entry.title,description: entry.description,- path: relative.startsWith("examples/") ? relative : `examples/${relative}`,+ path: repo || relative.startsWith("examples/") ? relative : `examples/${relative}`,+ repo,env: { file, key: typeof env.key === "string" ? env.key : undefined },featured: entry.featured === true,};@@ -100,7 +140,42 @@ 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) {@@ -151,7 +226,9 @@ export function groupedExampleChoices(): unknown[] {const groups = new Map<string, ExampleProject[]>();for (const example of examples) {- const key = example.path.replace(/^examples\//, "").split("/")[0] ?? "miscellaneous";+ const key = example.repo+ ? "miscellaneous"+ : (example.path.replace(/^examples\//, "").split("/")[0] ?? "miscellaneous");const group = groups.get(key) ?? [];group.push(example);groups.set(key, group);diff --git a/packages/openui-cli/src/commands/create/lib/scaffold-example.ts b/packages/openui-cli/src/commands/create/lib/scaffold-example.tsindex 7ba210c8d..e238c188b 100644--- a/packages/openui-cli/src/commands/create/lib/scaffold-example.ts+++ b/packages/openui-cli/src/commands/create/lib/scaffold-example.ts@@ -165,7 +165,7 @@ export async function scaffoldExample(params: {const { example, targetDir, name, packageManager, onRetry } = params;try {- await checkoutSource(example.path, { dest: targetDir, onRetry });+ await checkoutSource(example.path, { dest: targetDir, repo: example.repo, onRetry });} catch (err) {if (err instanceof CreateError) throw err;throw new CreateError(@@ -180,7 +180,7 @@ export async function scaffoldExample(params: {if (layout.jsPackages.length === 0 && layout.pythonPackages.length === 0) {throw new CreateError("scaffold",- `Example "${example.name}" was not found at ${example.path}.`,+ `Example "${example.name}" was not found at ${example.repo ? `${example.repo.owner}/${example.repo.name}/${example.path}`.replace(/\/$/, "") : example.path}.`,"filesystem","EXAMPLE_MISSING",);diff --git a/packages/openui-cli/src/lib/checkout.ts b/packages/openui-cli/src/lib/checkout.tsindex 6cb16e188..5ade4ee3a 100644--- a/packages/openui-cli/src/lib/checkout.ts+++ b/packages/openui-cli/src/lib/checkout.ts@@ -14,7 +14,23 @@ const FETCH_TIMEOUT_MS = 30_000;const SOURCE_OWNER = "thesysdev";const SOURCE_REPO = "openui";const SOURCE_REF = "main";-const SOURCE_GIT_URL = `https://github.com/${SOURCE_OWNER}/${SOURCE_REPO}.git`;++/** A GitHub repository to read from. Omitted means `thesysdev/openui@main`. */+export type SourceRepo = {+ owner: string;+ name: string;+};++function resolveSourceRepo(repo: SourceRepo | undefined): SourceRepo & { ref: string } {+ if (+ !repo ||+ (repo.owner.toLowerCase() === SOURCE_OWNER && repo.name.toLowerCase() === SOURCE_REPO)+ ) {+ return { owner: SOURCE_OWNER, name: SOURCE_REPO, ref: SOURCE_REF };+ }+ // Other repositories are read from their default branch.+ return { ...repo, ref: "HEAD" };+}/*** Absolute path to a source-repository checkout to read templates from@@ -42,6 +58,7 @@ function localSourcePath(sourceDir: string, normalizedPath: string): string {export type SourceFetchOptions = {dest?: string;+ repo?: SourceRepo;onRetry?: (info: RetryAttemptInfo) => void;};@@ -164,8 +181,11 @@ export async function checkoutSource(repoPath: string,opts: SourceFetchOptions = {},): Promise<CheckedOutSource> {- const normalizedPath = posixRepoPath(repoPath);- const sourceDir = localSourceDir();+ const normalizedPath = posixRepoPath(repoPath).replace(/\/+$/, "");+ const { owner, name: repoName, ref } = resolveSourceRepo(opts.repo);+ const isOpenui = ref === SOURCE_REF;+ const repoLabel = isOpenui ? `${owner}/${repoName}@${ref}` : `${owner}/${repoName}`;+ const sourceDir = isOpenui ? localSourceDir() : undefined;if (sourceDir) {const dest = opts.dest ?? fs.mkdtempSync(path.join(os.tmpdir(), "openui-src-"));copyDir(localSourcePath(sourceDir, normalizedPath), dest);@@ -175,18 +195,22 @@ export async function checkoutSource(const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openui-src-"));try {await runGit(["init", "--quiet"], { cwd: tmpDir });- await runGit(["remote", "add", "origin", SOURCE_GIT_URL], { cwd: tmpDir });- await runGit(["fetch", "--depth", "1", "--filter=blob:none", "origin", SOURCE_REF], {+ await runGit(["remote", "add", "origin", `https://github.com/${owner}/${repoName}.git`], {cwd: tmpDir,});- await runGit(["sparse-checkout", "set", "--cone", normalizedPath], { cwd: tmpDir });+ await runGit(["fetch", "--depth", "1", "--filter=blob:none", "origin", ref], {+ cwd: tmpDir,+ });+ if (normalizedPath) {+ await runGit(["sparse-checkout", "set", "--cone", normalizedPath], { cwd: tmpDir });+ }await runGit(["checkout", "--quiet", "FETCH_HEAD"], { cwd: tmpDir });- const extracted = path.join(tmpDir, ...normalizedPath.split("/"));+ const extracted = normalizedPath ? path.join(tmpDir, ...normalizedPath.split("/")) : tmpDir;if (!fs.existsSync(extracted)) {throw new CreateError("source_checkout",- `Path "${normalizedPath}" was not in ${SOURCE_OWNER}/${SOURCE_REPO}@${SOURCE_REF}.`,+ `Path "${normalizedPath}" was not in ${repoLabel}.`,"filesystem","SOURCE_MISSING",);@@ -205,5 +229,6 @@ export async function checkoutSource(function copyDir(from: string, to: string) {fs.rmSync(to, { recursive: true, force: true });fs.mkdirSync(path.dirname(to), { recursive: true });- fs.cpSync(from, to, { recursive: true });+ const gitDir = path.join(from, ".git");+ fs.cpSync(from, to, { recursive: true, filter: (src) => src !== gitDir });}