@agent-native/core 0.153.10 → 0.154.0

package/dist/server/agent-chat-plugin.js

@@ -125,6 +125,15 @@ export { loadResourcesForPrompt };
 export { _agentChatPromptSectionsForTests };
 export { buildPublicAgentA2ASkills };
 export { assembleA2AFinalResponse };
+export function buildLeanSystemPrompt(input) {
+    return (input.basePrompt +
+        (input.additionalFramework ?? "") +
+        (input.cacheSplit ?? "") +
+        input.resources +
+        (input.extra ?? "") +
+        (input.modelOverlay ?? "") +
+        (input.runtimeContext ?? ""));
+}
 export { runA2AAgentLoop };
 export { runMCPAgentLoop };
 export { createA2AEngineToolSurface };
@@ -2601,20 +2610,25 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     // so everything after it can change without a cache write.
                     if (leanPrompt) {
                         const leanRunPolicyPrompt = buildLeanRunPolicyPrompt(codeEditingSurfaceRestriction, prodCodeExecPromptNote);
+                        const resources = await loadResourcesForPrompt(owner, true, options?.appId, undefined, { disabledFrameworkGroups });
                         await emitContextXraySystemSections(event, {
                             frameworkPrompt: leanBasePrompt.slice(0, Math.max(0, leanBasePrompt.length - leanActionsPrompt.length)),
                             actionsPrompt: leanActionsPrompt,
                             additionalFramework: leanRunPolicyPrompt,
+                            resources,
                             extra,
                             modelOverlay,
                             runtimeContext,
                         });
-                        return setSystemPromptOnContext(leanBasePrompt +
-                            leanRunPolicyPrompt +
-                            SYSTEM_PROMPT_CACHE_SPLIT +
-                            extra +
-                            modelOverlay +
-                            runtimeContext);
+                        return setSystemPromptOnContext(buildLeanSystemPrompt({
+                            basePrompt: leanBasePrompt,
+                            additionalFramework: leanRunPolicyPrompt,
+                            cacheSplit: SYSTEM_PROMPT_CACHE_SPLIT,
+                            resources,
+                            extra,
+                            modelOverlay,
+                            runtimeContext,
+                        }));
                     }
                     const resources = await loadResourcesForPrompt(owner, lazyContext, options?.appId, undefined, { disabledFrameworkGroups });
                     // In lazy context mode, skip embedding the full schema. When database
@@ -2840,14 +2854,22 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         // cached prompt prefix as possible. See the prod handler above
                         // for the same pattern.
                         if (leanPrompt) {
+                            const resources = await loadResourcesForPrompt(owner, true, options?.appId, undefined, { disabledFrameworkGroups });
                             await emitContextXraySystemSections(event, {
                                 frameworkPrompt: leanBasePrompt.slice(0, Math.max(0, leanBasePrompt.length - leanActionsPrompt.length)),
                                 actionsPrompt: leanActionsPrompt,
+                                resources,
                                 extra,
                                 modelOverlay,
                                 runtimeContext,
                             });
-                            return setSystemPromptOnContext(leanBasePrompt + extra + modelOverlay + runtimeContext);
+                            return setSystemPromptOnContext(buildLeanSystemPrompt({
+                                basePrompt: leanBasePrompt,
+                                resources,
+                                extra,
+                                modelOverlay,
+                                runtimeContext,
+                            }));
                         }
                         const resources = await loadResourcesForPrompt(owner, lazyContext, options?.appId, undefined, { disabledFrameworkGroups });
                         const schemaBlock = lazyContext || !databaseToolsEnabled

package/dist/server/builder-design-systems.d.ts

@@ -39,6 +39,8 @@ export interface BuilderDesignSystemProxyFieldsOptions {
     description?: string;
     surface: "design" | "slides";
     sourceKind?: BuilderDesignSystemSourceKind;
+    githubSources?: BuilderDesignSystemGitHubSource[];
+    syncedAt?: string;
 }
 export type BuilderDesignSystemSourceKind = "figma" | "code" | "github" | "mixed";
 export interface BuilderDesignSystemProxyFields {
@@ -55,6 +57,8 @@ export interface BuilderDesignSystemProxyReference {
     builderProjectId?: string;
     builderUrl?: string;
     builderStatus?: string;
+    githubSources?: BuilderDesignSystemGitHubSource[];
+    syncedAt?: string;
 }
 export interface BuilderDesignSystemDocsOptions {
     page?: number;
@@ -82,11 +86,20 @@ export interface BuilderDesignSystemIndexOptions {
     projectName?: string;
     description?: string;
     githubRepoUrl?: string;
+    githubRepos?: BuilderDesignSystemGitHubSource[];
     connectedProjectId?: string;
     files?: BuilderDesignSystemIndexFile[];
     selection?: Record<string, string[]>;
     devToolsVersion?: string;
 }
+/** A durable, replayable GitHub source configuration for a Builder DSI kit. */
+export interface BuilderDesignSystemGitHubSource {
+    repoUrl: string;
+    ref?: string;
+    include?: string[];
+    exclude?: string[];
+    instructions?: string;
+}
 export interface BuilderDesignSystemIndexResult {
     ok: true;
     source: "builder";
@@ -124,6 +137,25 @@ export interface BuilderDesignSystemDecodeJobStatus {
     createdAt: number;
     updatedAt: number;
 }
+export interface BuilderDesignSystemGitHubFile {
+    path: string;
+    content: string;
+}
+export interface BuilderDesignSystemGitHubFileCollection {
+    source: BuilderDesignSystemGitHubSource;
+    owner: string;
+    repo: string;
+    ref?: string;
+    files: BuilderDesignSystemGitHubFile[];
+    totalBytes: number;
+    truncated: boolean;
+}
+/**
+ * Resolve an explicitly scoped/ref'd GitHub source into bounded file uploads.
+ * Native Builder public-repo sources are preferred for unscoped public repos;
+ * this path exists so branch, folder, and private-repo imports are replayable.
+ */
+export declare function collectBuilderDesignSystemGitHubFiles(input: BuilderDesignSystemGitHubSource): Promise<BuilderDesignSystemGitHubFileCollection>;
 export declare function fetchBuilderDesignSystemDecodeJobStatus(jobId: string): Promise<BuilderDesignSystemDecodeJobStatus>;
 export declare function getBuilderDesignSystemsBaseUrl(): string;
 export declare function mimeTypeForBuilderDesignSystemFilename(filename: string, explicit?: string): string;
@@ -131,7 +163,7 @@ export declare function buildBuilderDesignSystemIndexFiles({ codeFiles, designMd
 export declare function builderDesignSystemUrl(designSystemId?: string | null): string;
 export declare function builderProjectBranchUrl(projectId?: string | null, branchName?: string | null): string | undefined;
 export declare function localBuilderDesignSystemId(builderDesignSystemId: string): string;
-export declare function createBuilderDesignSystemProxyFields({ result, projectName, description, surface, sourceKind, }: BuilderDesignSystemProxyFieldsOptions): BuilderDesignSystemProxyFields;
+export declare function createBuilderDesignSystemProxyFields({ result, projectName, description, surface, sourceKind, githubSources, syncedAt, }: BuilderDesignSystemProxyFieldsOptions): BuilderDesignSystemProxyFields;
 export declare function parseBuilderDesignSystemProxyReference(data: unknown): BuilderDesignSystemProxyReference | null;
 export declare function fetchBuilderDesignSystemDocs(designSystemId: string, options?: BuilderDesignSystemDocsOptions): Promise<BuilderDesignSystemDocument[]>;
 export declare function hydrateBuilderDesignSystemReference(reference: BuilderDesignSystemProxyReference, options?: BuilderDesignSystemDocsOptions): Promise<BuilderDesignSystemHydratedReference>;

package/dist/server/builder-design-systems.js

@@ -1,6 +1,7 @@
 import { withBuilderUtmTrackingParams } from "../shared/builder-link-tracking.js";
 import { FeatureNotConfiguredError } from "./credential-provider.js";
-import { getBuilderProxyOrigin, resolveBuilderCredentials, } from "./credential-provider.js";
+import { getBuilderProxyOrigin, resolveSecret, resolveBuilderCredentials, } from "./credential-provider.js";
+import { canonicalGitHubRepoUrl, fetchGitHubJsonResult, fetchGitHubRaw, parseGitHubRepoReference, } from "./design-token-utils.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
 // GCS resumable uploads require every chunk except the last to be a multiple
 // of 256 KiB. 16 MiB is the recommended default and keeps very large `.fig`
@@ -10,6 +11,186 @@ const MAX_CHUNK_RETRIES = 5;
 const DEFAULT_MAX_CODE_FILES = 50;
 const DEFAULT_MAX_TOTAL_CODE_BYTES = 2 * 1024 * 1024;
 const MAX_DOC_CONTENT_CHARS = 4_000;
+const MAX_GITHUB_FILES = 50;
+const MAX_GITHUB_TOTAL_BYTES = 2 * 1024 * 1024;
+const MAX_GITHUB_FILE_BYTES = 512 * 1024;
+const MAX_GITHUB_DIRECTORIES = 250;
+const SKIPPED_GITHUB_DIRECTORIES = new Set([
+    ".git",
+    ".next",
+    ".turbo",
+    ".cache",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "vendor",
+]);
+function normalizeGitHubPath(value) {
+    const normalized = value.trim().replace(/^\/+|\/+$/g, "");
+    if (normalized.split("/").some((segment) => segment === "." || segment === "..")) {
+        throw new Error("GitHub file and folder scopes cannot contain . or .. segments.");
+    }
+    return normalized;
+}
+function pathMatchesScope(path, scope) {
+    const normalizedPath = normalizeGitHubPath(path);
+    const normalizedScope = normalizeGitHubPath(scope);
+    return (normalizedPath === normalizedScope ||
+        normalizedPath.startsWith(`${normalizedScope}/`));
+}
+function pathIsExcluded(path, excludes) {
+    return excludes.some((scope) => pathMatchesScope(path, scope));
+}
+function isIndexableGitHubFile(path) {
+    const name = path.split("/").pop()?.toLowerCase() ?? path.toLowerCase();
+    return (name === "package.json" ||
+        /\.(css|scss|sass|less|ts|tsx|js|jsx|json|html|svg|xml|md|markdown|mdx|txt)$/.test(name) ||
+        /(?:tailwind|postcss|theme|tokens|design)\.config\.[^/]+$/.test(name));
+}
+function isSkippedGitHubDirectory(path) {
+    const name = path.split("/").pop()?.toLowerCase() ?? "";
+    return SKIPPED_GITHUB_DIRECTORIES.has(name);
+}
+function githubSourceAccessError(owner, repo, status, hasToken, message) {
+    const suffix = message ? ` GitHub said: ${message}` : "";
+    if (!hasToken && (status === 401 || status === 403 || status === 404)) {
+        return new Error(`Could not access ${owner}/${repo}. Public repositories work without setup; private repositories require a fine-grained GitHub personal access token saved as GITHUB_TOKEN in Settings > Secrets with Repository permissions > Contents: Read-only.${suffix}`);
+    }
+    if (hasToken && (status === 401 || status === 403 || status === 404)) {
+        return new Error(`Could not access ${owner}/${repo} with the saved GITHUB_TOKEN. Check that the token is valid, the repository is selected, organization SSO/approval is complete, and Contents is Read-only.${suffix}`);
+    }
+    if (status === 429) {
+        return new Error(`GitHub rate-limited requests for ${owner}/${repo}. Save a GITHUB_TOKEN in Settings > Secrets or try again after the rate limit resets.${suffix}`);
+    }
+    return new Error(`Could not read ${owner}/${repo} from GitHub (status ${status || "unknown"}).${suffix}`);
+}
+function normalizedGitHubSource(source) {
+    const reference = parseGitHubRepoReference(source.repoUrl);
+    const ref = source.ref?.trim() || reference.ref;
+    const impliedPath = reference.subpath ? [reference.subpath] : [];
+    const include = [
+        ...impliedPath,
+        ...(source.include ?? []).map(normalizeGitHubPath).filter(Boolean),
+    ];
+    const uniqueInclude = [...new Set(include)];
+    const exclude = [
+        ...(source.exclude ?? []).map(normalizeGitHubPath).filter(Boolean),
+    ];
+    const normalized = {
+        repoUrl: canonicalGitHubRepoUrl(source.repoUrl),
+        ...(ref ? { ref } : {}),
+        ...(uniqueInclude.length > 0 ? { include: uniqueInclude } : {}),
+        ...(exclude.length > 0 ? { exclude: [...new Set(exclude)] } : {}),
+        ...(source.instructions?.trim()
+            ? { instructions: source.instructions.trim() }
+            : {}),
+    };
+    return { source: normalized, reference: { ...reference, ref } };
+}
+/**
+ * Resolve an explicitly scoped/ref'd GitHub source into bounded file uploads.
+ * Native Builder public-repo sources are preferred for unscoped public repos;
+ * this path exists so branch, folder, and private-repo imports are replayable.
+ */
+export async function collectBuilderDesignSystemGitHubFiles(input) {
+    const { source, reference } = normalizedGitHubSource(input);
+    const githubToken = await resolveSecret("GITHUB_TOKEN");
+    const include = source.include ?? [];
+    const explicitScope = include.length > 0 || Boolean(source.ref);
+    const queue = [...(include.length > 0 ? include : [""])];
+    const visited = new Set();
+    const files = [];
+    let totalBytes = 0;
+    let directoriesVisited = 0;
+    let truncated = false;
+    while (queue.length > 0) {
+        const path = normalizeGitHubPath(queue.shift() ?? "");
+        if (visited.has(path) || pathIsExcluded(path, source.exclude ?? [])) {
+            continue;
+        }
+        visited.add(path);
+        directoriesVisited++;
+        if (directoriesVisited > MAX_GITHUB_DIRECTORIES) {
+            truncated = true;
+            break;
+        }
+        const result = await fetchGitHubJsonResult(reference.owner, reference.repo, path, {
+            token: githubToken,
+            ref: reference.ref,
+        });
+        if (!result.ok) {
+            throw githubSourceAccessError(reference.owner, reference.repo, result.status, Boolean(githubToken), result.message);
+        }
+        const entries = Array.isArray(result.data)
+            ? result.data
+            : result.data
+                ? [result.data]
+                : [];
+        for (const entry of entries) {
+            const entryPath = normalizeGitHubPath(entry?.path ?? entry?.name ?? "");
+            if (!entryPath || pathIsExcluded(entryPath, source.exclude ?? [])) {
+                continue;
+            }
+            if (entry.type === "dir") {
+                if (isSkippedGitHubDirectory(entryPath))
+                    continue;
+                queue.push(entryPath);
+                continue;
+            }
+            if (entry.type !== "file")
+                continue;
+            if (include.length > 0 &&
+                !include.some((scope) => pathMatchesScope(entryPath, scope))) {
+                continue;
+            }
+            if (!explicitScope && !isIndexableGitHubFile(entryPath))
+                continue;
+            if (files.length >= MAX_GITHUB_FILES) {
+                truncated = true;
+                break;
+            }
+            if ((entry.size ?? 0) > MAX_GITHUB_FILE_BYTES)
+                continue;
+            const content = await fetchGitHubRaw(reference.owner, reference.repo, entryPath, { token: githubToken, ref: reference.ref });
+            if (content === null) {
+                throw new Error(`Could not read ${entryPath} from ${reference.owner}/${reference.repo}${source.ref ? ` at ref ${source.ref}` : ""}. Check the repository Contents permission and file size.`);
+            }
+            const bytes = new TextEncoder().encode(content).byteLength;
+            if (totalBytes + bytes > MAX_GITHUB_TOTAL_BYTES) {
+                truncated = true;
+                break;
+            }
+            files.push({ path: entryPath, content });
+            totalBytes += bytes;
+        }
+        if (truncated)
+            break;
+    }
+    if (files.length === 0) {
+        throw new Error(`No readable design-system files were found in ${reference.owner}/${reference.repo}${source.ref ? ` at ref ${source.ref}` : ""}. Select a folder or file that contains code, styles, tokens, or design.md.`);
+    }
+    if (truncated) {
+        throw new Error(`The selected GitHub source ${reference.owner}/${reference.repo} is larger than the safe inline indexing limit. Select a narrower folder or file set and try again.`);
+    }
+    return {
+        source,
+        owner: reference.owner,
+        repo: reference.repo,
+        ...(reference.ref ? { ref: reference.ref } : {}),
+        files,
+        totalBytes,
+        truncated,
+    };
+}
+async function isPublicGitHubSource(reference) {
+    const result = await fetchGitHubJsonResult(reference.owner, reference.repo, "", {
+        ref: reference.ref,
+    });
+    return result.ok
+        ? { ok: true }
+        : { ok: false, status: result.status, message: result.message };
+}
 export async function fetchBuilderDesignSystemDecodeJobStatus(jobId) {
     const credentials = await resolveBuilderDesignSystemCredentials();
     const url = makeBuilderDesignSystemUrl("decode-jobs/" + encodeURIComponent(jobId), credentials);
@@ -287,14 +468,19 @@ export function localBuilderDesignSystemId(builderDesignSystemId) {
         .slice(0, 96);
     return `builder-${slug || "design-system"}`;
 }
-export function createBuilderDesignSystemProxyFields({ result, projectName, description, surface, sourceKind, }) {
+export function createBuilderDesignSystemProxyFields({ result, projectName, description, surface, sourceKind, githubSources, syncedAt, }) {
     const title = projectName?.trim() || "Builder indexed design system";
+    const normalizedGithubSources = githubSources?.map((source) => normalizedGitHubSource(source).source);
     const fallbackDescription = description ?? `Builder indexed design system ${result.designSystemId}`;
     const surfaceNoun = surface === "slides" ? "slides" : "designs";
     const spacingKey = surface === "slides" ? "slidePadding" : "pagePadding";
     const data = JSON.stringify({
         source: "builder",
         ...(sourceKind ? { sourceKind } : {}),
+        ...(normalizedGithubSources?.length
+            ? { githubSources: normalizedGithubSources }
+            : {}),
+        ...(syncedAt ? { syncedAt } : {}),
         builderDesignSystemId: result.designSystemId,
         builderJobId: result.jobId,
         builderProjectId: result.projectId,
@@ -328,6 +514,9 @@ export function createBuilderDesignSystemProxyFields({ result, projectName, desc
             projectName ? `Requested name: ${projectName}` : "",
             description ? `Context: ${description}` : "",
             "Builder Design System Intelligence is the source of truth for indexed tokens, components, assets, and usage guidance.",
+            normalizedGithubSources?.length
+                ? "GitHub source scope is persisted so this design system can be synced without reconfiguring it."
+                : "",
         ]
             .filter(Boolean)
             .join("\n"),
@@ -340,6 +529,9 @@ export function createBuilderDesignSystemProxyFields({ result, projectName, desc
         `Builder URL: ${result.builderUrl}`,
         `When generating ${surfaceNoun}, treat Builder DSI as the source of truth for indexed tokens, components, assets, and usage guidance.`,
         "Call get-design-system for this local id before generation and use the returned builder docs and token values when available.",
+        normalizedGithubSources?.length
+            ? "Use sync-design-system-with-builder to refresh the persisted GitHub source scope before generating when the repository changed."
+            : "",
     ].join("\n");
     return {
         title,
@@ -375,6 +567,48 @@ export function parseBuilderDesignSystemProxyReference(data) {
         sourceKind !== "mixed") {
         return null;
     }
+    let invalidGithubSource = false;
+    const githubSources = Array.isArray(value.githubSources)
+        ? value.githubSources.flatMap((source) => {
+            if (!source || typeof source !== "object") {
+                invalidGithubSource = true;
+                return [];
+            }
+            const candidate = source;
+            if (typeof candidate.repoUrl !== "string") {
+                invalidGithubSource = true;
+                return [];
+            }
+            try {
+                const normalized = normalizedGitHubSource({
+                    repoUrl: candidate.repoUrl,
+                    ...(typeof candidate.ref === "string"
+                        ? { ref: candidate.ref }
+                        : {}),
+                    ...(Array.isArray(candidate.include)
+                        ? {
+                            include: candidate.include.filter((path) => typeof path === "string"),
+                        }
+                        : {}),
+                    ...(Array.isArray(candidate.exclude)
+                        ? {
+                            exclude: candidate.exclude.filter((path) => typeof path === "string"),
+                        }
+                        : {}),
+                    ...(typeof candidate.instructions === "string"
+                        ? { instructions: candidate.instructions }
+                        : {}),
+                });
+                return [normalized.source];
+            }
+            catch {
+                invalidGithubSource = true;
+                return [];
+            }
+        })
+        : undefined;
+    if (invalidGithubSource)
+        return null;
     return {
         source: "builder",
         ...(sourceKind ? { sourceKind } : {}),
@@ -385,6 +619,8 @@ export function parseBuilderDesignSystemProxyReference(data) {
             : undefined,
         builderUrl: typeof value.builderUrl === "string" ? value.builderUrl : undefined,
         builderStatus: typeof value.builderStatus === "string" ? value.builderStatus : undefined,
+        ...(githubSources?.length ? { githubSources } : {}),
+        ...(typeof value.syncedAt === "string" ? { syncedAt: value.syncedAt } : {}),
     };
 }
 function truncateDocContent(content) {
@@ -435,8 +671,9 @@ export async function fetchBuilderDesignSystemDocs(designSystemId, options = {})
     });
     await assertOk(response, "Builder design-system docs fetch failed");
     const json = (await response.json());
-    if (!Array.isArray(json))
-        return [];
+    if (!Array.isArray(json)) {
+        throw new Error("Builder design-system docs fetch returned an invalid response.");
+    }
     return json.map(normalizeBuilderDesignSystemDocument);
 }
 export async function hydrateBuilderDesignSystemReference(reference, options = { page: 0, pageSize: 40 }) {
@@ -555,10 +792,56 @@ export async function startBuilderDesignSystemIndex(options) {
     }
     if (files.length === 0 &&
         !options.githubRepoUrl &&
+        !(options.githubRepos && options.githubRepos.length > 0) &&
         !options.connectedProjectId) {
         throw new Error("Provide at least one .fig/code/text file or a GitHub repository URL to index with Builder.");
     }
     const sources = [];
+    const fileInstructions = new Map();
+    function appendGitHubCollection(collection) {
+        for (const file of collection.files) {
+            const name = `github/${collection.owner}/${collection.repo}/${file.path}`;
+            files.push({
+                name,
+                data: new TextEncoder().encode(file.content),
+                mimeType: mimeTypeForBuilderDesignSystemFilename(file.path),
+            });
+            if (collection.source.instructions) {
+                fileInstructions.set(name, collection.source.instructions);
+            }
+        }
+    }
+    const githubSources = options.githubRepos?.length
+        ? options.githubRepos
+        : options.githubRepoUrl?.trim()
+            ? [{ repoUrl: options.githubRepoUrl.trim() }]
+            : [];
+    for (const input of githubSources) {
+        const { source, reference } = normalizedGitHubSource(input);
+        const hasExplicitScope = Boolean(source.ref) ||
+            Boolean(source.include?.length) ||
+            Boolean(source.exclude?.length);
+        if (hasExplicitScope) {
+            const collection = await collectBuilderDesignSystemGitHubFiles(source);
+            appendGitHubCollection(collection);
+            continue;
+        }
+        const publicAccess = await isPublicGitHubSource(reference);
+        if (publicAccess.ok) {
+            sources.push({
+                kind: "public-repo",
+                repoUrl: source.repoUrl,
+                ...(source.instructions ? { instructions: source.instructions } : {}),
+            });
+            continue;
+        }
+        if (await resolveSecret("GITHUB_TOKEN")) {
+            const collection = await collectBuilderDesignSystemGitHubFiles(source);
+            appendGitHubCollection(collection);
+            continue;
+        }
+        throw githubSourceAccessError(reference.owner, reference.repo, publicAccess.status, false, publicAccess.message);
+    }
     if (files.length > 0) {
         const slots = await startBuilderDesignSystemUpload(files.map((file) => ({
             name: file.name,
@@ -568,23 +851,22 @@ export async function startBuilderDesignSystemIndex(options) {
         for (let i = 0; i < slots.length; i++) {
             await uploadToResumableUrl(slots[i], files[i]);
         }
+        const fileSources = [];
         for (let i = 0; i < slots.length; i++) {
             const name = files[i].name;
             const fileSelection = options.selection?.[name];
-            sources.push({
+            fileSources.push({
                 kind: "file",
                 uploadToken: slots[i].uploadToken,
+                ...(fileInstructions.get(name)
+                    ? { instructions: fileInstructions.get(name) }
+                    : {}),
                 ...(fileSelection && fileSelection.length > 0
                     ? { selection: { [name]: fileSelection } }
                     : {}),
             });
         }
-    }
-    if (options.githubRepoUrl?.trim()) {
-        sources.push({
-            kind: "public-repo",
-            repoUrl: options.githubRepoUrl.trim(),
-        });
+        sources.unshift(...fileSources);
     }
     if (options.connectedProjectId?.trim()) {
         sources.push({

package/dist/server/design-token-utils.d.ts

@@ -101,6 +101,14 @@ export interface UrlExtractionResult {
 }
 export interface GitHubFetchOptions {
     token?: string | null;
+    /** Branch, tag, or commit to read from. */
+    ref?: string;
+}
+export interface GitHubRepoReference {
+    owner: string;
+    repo: string;
+    ref?: string;
+    subpath?: string;
 }
 export interface GitHubJsonResult<T = unknown> {
     ok: boolean;
@@ -117,11 +125,14 @@ export interface GitHubJsonResult<T = unknown> {
  * clear early error for literal private hosts, ssrfSafeFetch is the backstop.
  */
 export declare function validateUrl(url: string): void;
+/** Parse a GitHub URL or "org/repo" shorthand, retaining an optional ref/path. */
+export declare function parseGitHubRepoReference(raw: string): GitHubRepoReference;
 /** Parse a GitHub URL or "org/repo" shorthand into owner + repo. */
 export declare function parseOwnerRepo(raw: string): {
     owner: string;
     repo: string;
 };
+export declare function canonicalGitHubRepoUrl(raw: string): string;
 /** Fetch a path from the GitHub Contents API as JSON with status details. */
 export declare function fetchGitHubJsonResult<T = unknown>(owner: string, repo: string, path: string, options?: GitHubFetchOptions): Promise<GitHubJsonResult<T>>;
 /** Fetch a path from the GitHub Contents API as JSON. Returns null on error. */