The Open Standard for Generative UI
import { spawn } from "node:child_process";
import * as fs from "node:fs";
import * as os from "node:os";
import * as path from "node:path";
import { isTruthyEnv } from "./env";
import { CreateError } from "./errors";
import { gitMissingMessage } from "./git-preflight";
import { type RetryAttemptInfo, withRetry } from "./retry";
const GIT_TIMEOUT_MS = 60_000;
const FETCH_TIMEOUT_MS = 30_000;
const SOURCE_OWNER = "thesysdev";
const SOURCE_REPO = "openui";
const SOURCE_REF = "main";
/** 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
* instead of fetching `main` from GitHub, so CI can scaffold the templates of
* the commit under test. Undocumented: requires `OPENUI_DEBUG`.
*/
export function localSourceDir(): string | undefined {
if (!isTruthyEnv(process.env["OPENUI_DEBUG"])) return undefined;
const dir = process.env["OPENUI_SOURCE_DIR"]?.trim();
return dir || undefined;
}
function localSourcePath(sourceDir: string, normalizedPath: string): string {
const resolved = path.join(sourceDir, ...normalizedPath.split("/"));
if (!fs.existsSync(resolved)) {
throw new CreateError(
"source_checkout",
`Path "${normalizedPath}" was not in OPENUI_SOURCE_DIR (${sourceDir}).`,
"filesystem",
"SOURCE_MISSING",
);
}
return resolved;
}
export type SourceFetchOptions = {
dest?: string;
repo?: SourceRepo;
onRetry?: (info: RetryAttemptInfo) => void;
};
export type FetchedFile = {
content: string;
};
export type CheckedOutSource = {
dir: string;
};
function posixRepoPath(repoPath: string): string {
return repoPath.replace(/\\/g, "/").replace(/^\/+/, "");
}
function runGit(
args: string[],
options: { cwd?: string; timeoutMs?: number } = {},
): Promise<string> {
return new Promise((resolve, reject) => {
const child = spawn("git", args, {
cwd: options.cwd,
env: {
...process.env,
GIT_TERMINAL_PROMPT: "0",
},
stdio: ["ignore", "pipe", "pipe"],
});
let stdout = "";
let stderr = "";
const timeout = setTimeout(() => {
child.kill("SIGKILL");
reject(
new CreateError(
"source_checkout",
`git ${args[0]} timed out.`,
"network",
"CHECKOUT_FAILED",
),
);
}, options.timeoutMs ?? GIT_TIMEOUT_MS);
timeout.unref();
child.stdout?.on("data", (chunk: Buffer) => {
stdout += chunk.toString("utf8");
});
child.stderr?.on("data", (chunk: Buffer) => {
stderr += chunk.toString("utf8");
});
child.once("error", (error: NodeJS.ErrnoException) => {
clearTimeout(timeout);
if (error.code === "ENOENT") {
reject(new CreateError("source_checkout", gitMissingMessage(), "process", "GIT_MISSING"));
return;
}
reject(error);
});
child.once("close", (code) => {
clearTimeout(timeout);
if (code === 0) {
resolve(stdout.trim());
return;
}
const detail = stderr.trim().split("\n").at(-1) ?? `exit ${code}`;
reject(
new CreateError(
"source_checkout",
`git ${args[0]} failed: ${detail}. Check your network connection and try again.`,
"network",
"CHECKOUT_FAILED",
),
);
});
});
}
export async function fetchSourceFile(
repoPath: string,
opts: { repo?: SourceRepo; onRetry?: (info: RetryAttemptInfo) => void } = {},
): Promise<FetchedFile> {
const normalizedPath = posixRepoPath(repoPath);
const { owner, name: repoName, ref } = resolveSourceRepo(opts.repo);
const sourceDir = ref === SOURCE_REF ? localSourceDir() : undefined;
if (sourceDir) {
return { content: fs.readFileSync(localSourcePath(sourceDir, normalizedPath), "utf8") };
}
const fetchOnce = async (): Promise<FetchedFile> => {
const url = `https://raw.githubusercontent.com/${owner}/${repoName}/${ref}/${normalizedPath}`;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
try {
const response = await fetch(url, {
headers: { Accept: "text/plain" },
signal: controller.signal,
});
if (!response.ok) {
throw new CreateError(
"source_checkout",
`Failed to fetch ${normalizedPath} (${response.status}).`,
response.status === 404 ? "filesystem" : "network",
response.status === 404 ? "SOURCE_MISSING" : "CHECKOUT_FAILED",
);
}
return { content: await response.text() };
} catch (error) {
if (error instanceof CreateError) throw error;
const aborted = error instanceof Error && error.name === "AbortError";
throw new CreateError(
"source_checkout",
`${aborted ? "Timed out fetching" : "Failed to fetch"} ${normalizedPath} from GitHub. Check your network connection and try again.`,
"network",
"CHECKOUT_FAILED",
);
} finally {
clearTimeout(timer);
}
};
return withRetry(`Fetching ${normalizedPath}`, fetchOnce, { onRetry: opts.onRetry });
}
export async function checkoutSource(
repoPath: string,
opts: SourceFetchOptions = {},
): Promise<CheckedOutSource> {
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);
return { dir: dest };
}
const checkoutOnce = async (): Promise<CheckedOutSource> => {
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openui-src-"));
try {
await runGit(["init", "--quiet"], { cwd: tmpDir });
await runGit(["remote", "add", "origin", `https://github.com/${owner}/${repoName}.git`], {
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 = normalizedPath ? path.join(tmpDir, ...normalizedPath.split("/")) : tmpDir;
if (!fs.existsSync(extracted)) {
throw new CreateError(
"source_checkout",
`Path "${normalizedPath}" was not in ${repoLabel}.`,
"filesystem",
"SOURCE_MISSING",
);
}
const dest = opts.dest ?? fs.mkdtempSync(path.join(os.tmpdir(), "openui-src-"));
copyDir(extracted, dest);
return { dir: dest };
} finally {
fs.rmSync(tmpDir, { recursive: true, force: true });
}
};
return withRetry("Source checkout", checkoutOnce, { onRetry: opts.onRetry });
}
function copyDir(from: string, to: string) {
fs.rmSync(to, { recursive: true, force: true });
fs.mkdirSync(path.dirname(to), { recursive: true });
const gitDir = path.join(from, ".git");
fs.cpSync(from, to, { recursive: true, filter: (src) => src !== gitDir });
}