@agent-native/core 0.153.10 → 0.154.1

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. */

package/dist/server/design-token-utils.js

@@ -108,26 +108,78 @@ export function validateUrl(url) {
 // ---------------------------------------------------------------------------
 // GitHub helpers
 // ---------------------------------------------------------------------------
-/** Parse a GitHub URL or "org/repo" shorthand into owner + repo. */
-export function parseOwnerRepo(raw) {
+/** Parse a GitHub URL or "org/repo" shorthand, retaining an optional ref/path. */
+export function parseGitHubRepoReference(raw) {
     const cleaned = raw
         .trim()
         .replace(/[?#].*$/, "")
         .replace(/\/+$/, "");
+    if (!cleaned)
+        throw new Error("GitHub repository reference cannot be empty.");
     const sshMatch = cleaned.match(/^(?:ssh:\/\/)?git@github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
-    if (sshMatch) {
+    if (sshMatch)
         return { owner: sshMatch[1], repo: sshMatch[2] };
-    }
     const shorthand = cleaned.match(/^([^/\s]+)\/([^/\s]+?)(?:\.git)?$/);
-    if (shorthand) {
+    if (shorthand)
         return { owner: shorthand[1], repo: shorthand[2] };
+    let parsed;
+    try {
+        parsed = new URL(cleaned);
+    }
+    catch {
+        throw new Error("Could not parse GitHub owner/repo from URL. " +
+            'Expected format: "https://github.com/org/repo", "org/repo", or "git@github.com:org/repo.git"');
+    }
+    if (parsed.hostname.toLowerCase() !== "github.com") {
+        throw new Error("GitHub repository URL must use github.com.");
     }
-    const urlMatch = cleaned.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?(?:\/.*)?$/);
-    if (urlMatch) {
-        return { owner: urlMatch[1], repo: urlMatch[2] };
+    const parts = parsed.pathname
+        .split("/")
+        .filter(Boolean)
+        .map((part) => {
+        try {
+            return decodeURIComponent(part);
+        }
+        catch {
+            return part;
+        }
+    });
+    const owner = parts[0];
+    const repo = parts[1]?.replace(/\.git$/, "");
+    if (!owner || !repo) {
+        throw new Error("Could not parse GitHub owner/repo from URL. " +
+            'Expected format: "https://github.com/org/repo", "org/repo", or "git@github.com:org/repo.git"');
+    }
+    const kind = parts[2];
+    if ((kind === "tree" || kind === "blob") && parts[3]) {
+        return {
+            owner,
+            repo,
+            ref: parts[3],
+            ...(parts.length > 4 ? { subpath: parts.slice(4).join("/") } : {}),
+        };
     }
-    throw new Error("Could not parse GitHub owner/repo from URL. " +
-        'Expected format: "https://github.com/org/repo", "org/repo", or "git@github.com:org/repo.git"');
+    return { owner, repo };
+}
+/** Parse a GitHub URL or "org/repo" shorthand into owner + repo. */
+export function parseOwnerRepo(raw) {
+    const { owner, repo } = parseGitHubRepoReference(raw);
+    return { owner, repo };
+}
+export function canonicalGitHubRepoUrl(raw) {
+    const { owner, repo } = parseGitHubRepoReference(raw);
+    return `https://github.com/${owner}/${repo}`;
+}
+function githubContentsUrl(owner, repo, path, ref) {
+    const encodedPath = path
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+    const url = new URL(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/contents/${encodedPath}`);
+    if (ref?.trim())
+        url.searchParams.set("ref", ref.trim());
+    return url;
 }
 /** Fetch a path from the GitHub Contents API as JSON. Returns null on error. */
 function githubHeaders(accept, options = {}) {
@@ -139,9 +191,9 @@ function githubHeaders(accept, options = {}) {
 }
 /** Fetch a path from the GitHub Contents API as JSON with status details. */
 export async function fetchGitHubJsonResult(owner, repo, path, options = {}) {
-    const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path}`;
-    validateUrl(url);
-    const res = await ssrfSafeFetch(url, {
+    const url = githubContentsUrl(owner, repo, path, options.ref);
+    validateUrl(url.toString());
+    const res = await ssrfSafeFetch(url.toString(), {
         headers: githubHeaders("application/vnd.github.v3+json", options),
         signal: AbortSignal.timeout(FETCH_TIMEOUT),
     });
@@ -173,9 +225,9 @@ export async function fetchGitHubJson(owner, repo, path, options = {}) {
 }
 /** Fetch raw file content from the GitHub Contents API. Returns null on error or oversize. */
 export async function fetchGitHubRaw(owner, repo, path, options = {}) {
-    const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path}`;
-    validateUrl(url);
-    const res = await ssrfSafeFetch(url, {
+    const url = githubContentsUrl(owner, repo, path, options.ref);
+    validateUrl(url.toString());
+    const res = await ssrfSafeFetch(url.toString(), {
         headers: githubHeaders("application/vnd.github.v3.raw", options),
         signal: AbortSignal.timeout(FETCH_TIMEOUT),
     });

package/dist/server/index.d.ts

@@ -69,7 +69,7 @@ export { createIntegrationsPlugin, defaultIntegrationsPlugin, enqueueRemoteComma
 export { isElectron, isMobile, getOrigin, getAppBasePath, getAppUrl, resolveOAuthRedirectUri, isAllowedOAuthRedirectUri, encodeOAuthState, decodeOAuthState, resolveOAuthOwner, createOAuthSession, oauthCallbackResponse, oauthErrorPage, oauthDesktopExchangePage, type OAuthStatePayload, type OAuthOwnerResult, type OAuthSessionResult, } from "./google-oauth.js";
 export { buildWorkspaceProviderAuthorizationUrl, createWorkspaceProviderOAuthHandler, exchangeWorkspaceProviderOAuthCode, handleWorkspaceProviderOAuthCallback, handleWorkspaceProviderOAuthStart, isWorkspaceProviderOAuthFlowValid, mergeWorkspaceOAuthValues, resolveWorkspaceProviderIdentity, workspaceProviderOAuthPath, type GenericWorkspaceOAuthProvider, type WorkspaceProviderOAuthFlow, } from "./workspace-provider-oauth.js";
 export { FeatureNotConfiguredError, hasBuilderPrivateKey, isBuilderEnvManaged, getBuilderProxyOrigin, getBuilderImageGenerationBaseUrl, getBuilderWebSearchBaseUrl, getBuilderAuthHeader, resolveBuilderPrivateKey, resolveBuilderAuthHeader, resolveHasBuilderPrivateKey, resolveHasCompleteBuilderConnection, resolveBuilderCredentials, resolveBuilderCredentialsDetailed, resolveBuilderCredentialSource, resolveBuilderCredential, readDeployCredentialEnv, writeBuilderCredentials, deleteBuilderCredentials, resolveSecret, type BuilderCredentialsDetailed, } from "./credential-provider.js";
-export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, type BuildBuilderDesignSystemIndexFilesOptions, type BuilderDesignSystemCodeFileInput, type BuilderDesignSystemDecodeJobStatus, type BuilderDesignSystemDocsOptions, type BuilderDesignSystemDocument, type BuilderDesignSystemHydratedReference, type BuilderDesignSystemIndexFile, type BuilderDesignSystemIndexFromSourcesOptions, type BuilderDesignSystemIndexOptions, type BuilderDesignSystemIndexResult, type BuilderDesignSystemUploadAttachment, type BuilderDesignSystemUploadSlot, type BuilderDesignSystemProxyFields, type BuilderDesignSystemProxyFieldsOptions, type BuilderDesignSystemProxyReference, type BuilderDesignSystemSourceKind, } from "./builder-design-systems.js";
+export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, type BuildBuilderDesignSystemIndexFilesOptions, type BuilderDesignSystemCodeFileInput, type BuilderDesignSystemDecodeJobStatus, type BuilderDesignSystemDocsOptions, type BuilderDesignSystemDocument, type BuilderDesignSystemHydratedReference, type BuilderDesignSystemIndexFile, type BuilderDesignSystemIndexFromSourcesOptions, type BuilderDesignSystemIndexOptions, type BuilderDesignSystemIndexResult, type BuilderDesignSystemGitHubFile, type BuilderDesignSystemGitHubFileCollection, type BuilderDesignSystemGitHubSource, type BuilderDesignSystemUploadAttachment, type BuilderDesignSystemUploadSlot, type BuilderDesignSystemProxyFields, type BuilderDesignSystemProxyFieldsOptions, type BuilderDesignSystemProxyReference, type BuilderDesignSystemSourceKind, } from "./builder-design-systems.js";
 export { createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, runBuilderAgent, type BuilderProjectResult, type RunBuilderAgentResult, } from "./builder-browser.js";
 export { ensureFusionContainer, sendFusionBranchMessage, pushFusionBranch, reserveFusionHostingSlug, deployFusionProject, getFusionDeploys, getFusionBranchEditorUrl, getFusionHostingUrl, type FusionBranchRef, type EnsureFusionContainerResult, type SendFusionMessageResult, } from "./fusion-app.js";
 export { sendEmail, isEmailConfigured, getEmailReadiness, getEmailProvider, type EmailAttachment, type EmailReadiness, type EmailProvider, type SendEmailArgs, } from "./email.js";

package/dist/server/index.js

@@ -74,7 +74,7 @@ export { createIntegrationsPlugin, defaultIntegrationsPlugin, enqueueRemoteComma
 export { isElectron, isMobile, getOrigin, getAppBasePath, getAppUrl, resolveOAuthRedirectUri, isAllowedOAuthRedirectUri, encodeOAuthState, decodeOAuthState, resolveOAuthOwner, createOAuthSession, oauthCallbackResponse, oauthErrorPage, oauthDesktopExchangePage, } from "./google-oauth.js";
 export { buildWorkspaceProviderAuthorizationUrl, createWorkspaceProviderOAuthHandler, exchangeWorkspaceProviderOAuthCode, handleWorkspaceProviderOAuthCallback, handleWorkspaceProviderOAuthStart, isWorkspaceProviderOAuthFlowValid, mergeWorkspaceOAuthValues, resolveWorkspaceProviderIdentity, workspaceProviderOAuthPath, } from "./workspace-provider-oauth.js";
 export { FeatureNotConfiguredError, hasBuilderPrivateKey, isBuilderEnvManaged, getBuilderProxyOrigin, getBuilderImageGenerationBaseUrl, getBuilderWebSearchBaseUrl, getBuilderAuthHeader, resolveBuilderPrivateKey, resolveBuilderAuthHeader, resolveHasBuilderPrivateKey, resolveHasCompleteBuilderConnection, resolveBuilderCredentials, resolveBuilderCredentialsDetailed, resolveBuilderCredentialSource, resolveBuilderCredential, readDeployCredentialEnv, writeBuilderCredentials, deleteBuilderCredentials, resolveSecret, } from "./credential-provider.js";
-export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, } from "./builder-design-systems.js";
+export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, } from "./builder-design-systems.js";
 export { createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, runBuilderAgent, } from "./builder-browser.js";
 export { ensureFusionContainer, sendFusionBranchMessage, pushFusionBranch, reserveFusionHostingSlug, deployFusionProject, getFusionDeploys, getFusionBranchEditorUrl, getFusionHostingUrl, } from "./fusion-app.js";
 export { sendEmail, isEmailConfigured, getEmailReadiness, getEmailProvider, } from "./email.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.153.10",
+  "version": "0.154.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -421,7 +421,7 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/toolkit": "^0.14.1",
+    "@agent-native/toolkit": "^0.14.2",
     "@agent-native/recap-cli": "0.5.4"
   },
   "devDependencies": {