Skip to content

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.md
new file mode 100644
index 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.ts
index 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.json
index 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.ts
index 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.ts
index 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.ts
index 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 });
}