Context7 Platform -- Up-to-date docs for AI agents
fix(cli): fall back to direct SKILL.md fetch when GitHub tree API is unreachable (#2938)
Fahreddin Özcanc82cc8afa055
diff --git a/.changeset/fix-codex-skill-install.md b/.changeset/fix-codex-skill-install.mdnew file mode 100644index 00000000..660ed9b2--- /dev/null+++ b/.changeset/fix-codex-skill-install.md@@ -0,0 +1,5 @@+---+"ctx7": patch+---++Fix `ctx7 setup` skill install failing with "fetch failed" when the GitHub git tree API (`api.github.com`) is blocked or unreachable. Skill download now falls back to fetching the single `SKILL.md` directly from `raw.githubusercontent.com` — the URL the docs API already resolves — so setup succeeds in environments where only the docs/raw hosts are reachable.diff --git a/packages/cli/src/__tests__/github.test.ts b/packages/cli/src/__tests__/github.test.tsindex 32f3941b..d6417881 100644--- a/packages/cli/src/__tests__/github.test.ts+++ b/packages/cli/src/__tests__/github.test.ts@@ -4,7 +4,14 @@ const execFileSync = vi.hoisted(() => vi.fn());vi.mock("node:child_process", () => ({ execFileSync }));-import { listSkillsFromGitHub } from "../utils/github.js";+import { downloadSkillFromGitHub, listSkillsFromGitHub } from "../utils/github.js";++const SKILL = {+ name: "context7-mcp",+ description: "desc",+ project: "/upstash/context7",+ url: "https://raw.githubusercontent.com/upstash/context7/refs/heads/master/plugins/codex/context7/skills/context7-mcp/SKILL.md",+};beforeEach(() => {// resetAllMocks, not clearAllMocks: the latter keeps implementations, so a@@ -86,3 +93,74 @@ describe("GitHub authentication", () => {expect(headers).not.toHaveProperty("Authorization");});});++describe("downloadSkillFromGitHub", () => {+ test("downloads every file in the skill directory when the tree API works", async () => {+ vi.stubGlobal(+ "fetch",+ vi.fn((url: string) => {+ if (url.includes("api.github.com")) {+ return Promise.resolve({+ ok: true,+ json: () =>+ Promise.resolve({+ sha: "s",+ truncated: false,+ tree: [+ { type: "tree", path: "plugins/codex/context7/skills/context7-mcp" },+ {+ type: "blob",+ path: "plugins/codex/context7/skills/context7-mcp/SKILL.md",+ },+ {+ type: "blob",+ path: "plugins/codex/context7/skills/context7-mcp/references/guide.md",+ },+ ],+ }),+ });+ }+ return Promise.resolve({ ok: true, text: () => Promise.resolve(`raw:${url}`) });+ })+ );++ const result = await downloadSkillFromGitHub(SKILL);++ expect(result.error).toBeUndefined();+ expect(result.files.map((f) => f.path).sort()).toEqual(["SKILL.md", "references/guide.md"]);+ });++ test("falls back to the single SKILL.md when the tree API is unreachable (#2936)", async () => {+ vi.stubGlobal(+ "fetch",+ vi.fn((url: string) => {+ if (url.includes("api.github.com")) {+ return Promise.reject(new TypeError("fetch failed"));+ }+ return Promise.resolve({ ok: true, text: () => Promise.resolve("# Context7 skill") });+ })+ );++ const result = await downloadSkillFromGitHub(SKILL);++ expect(result.error).toBeUndefined();+ expect(result.files).toEqual([{ path: "SKILL.md", content: "# Context7 skill" }]);+ });++ test("surfaces the tree error when both the tree API and the direct fetch fail", async () => {+ vi.stubGlobal(+ "fetch",+ vi.fn((url: string) => {+ if (url.includes("api.github.com")) {+ return Promise.reject(new TypeError("fetch failed"));+ }+ return Promise.resolve({ ok: false, status: 404 });+ })+ );++ const result = await downloadSkillFromGitHub(SKILL);++ expect(result.files).toEqual([]);+ expect(result.error).toBe("fetch failed");+ });+});diff --git a/packages/cli/src/utils/github.ts b/packages/cli/src/utils/github.tsindex 05f36f96..8242f9a7 100644--- a/packages/cli/src/utils/github.ts+++ b/packages/cli/src/utils/github.ts@@ -253,65 +253,102 @@ export async function getSkillFromGitHub(return { ...result, skill };}-export async function downloadSkillFromGitHub(- skill: Skill & { project: string }+async function downloadSkillTree(+ owner: string,+ repo: string,+ branch: string,+ skillPath: string,+ ghHeaders: Record<string, string>): Promise<{ files: SkillFile[]; error?: string }> {- try {- const parsed = parseGitHubUrl(skill.url);+ const treeData = await fetchRepoTree(owner, repo, branch, ghHeaders);+ if ("error" in treeData) {+ const hint =+ !ghHeaders["Authorization"] && /403|429|rate/.test(treeData.error)+ ? " — run `gh auth login` or set the GITHUB_TOKEN env var to increase rate limits"+ : "";+ return { files: [], error: `GitHub API error: ${treeData.error}${hint}` };+ }- if (!parsed) {- return { files: [], error: `Invalid GitHub URL: ${skill.url}` };- }+ const skillFiles = treeData.tree.filter(+ (item) => item.type === "blob" && item.path.startsWith(skillPath + "/")+ );- const { owner, repo, branch, path: skillPath } = parsed;+ if (skillFiles.length === 0) {+ return { files: [], error: `No files found in ${skillPath}` };+ }- const ghHeaders = getGitHubHeaders();+ const files: SkillFile[] = [];+ for (const item of skillFiles) {+ const rawUrl = `${GITHUB_RAW}/${owner}/${repo}/${branch}/${item.path}`;+ const fileResponse = await fetch(rawUrl, { headers: ghHeaders });- const treeData = await fetchRepoTree(owner, repo, branch, ghHeaders);- if ("error" in treeData) {- const hint =- !ghHeaders["Authorization"] && /403|429|rate/.test(treeData.error)- ? " — run `gh auth login` or set the GITHUB_TOKEN env var to increase rate limits"- : "";- return { files: [], error: `GitHub API error: ${treeData.error}${hint}` };+ if (!fileResponse.ok) {+ console.warn(`Failed to fetch ${item.path}: ${fileResponse.status}`);+ continue;}- const skillFiles = treeData.tree.filter(- (item) => item.type === "blob" && item.path.startsWith(skillPath + "/")- );+ const content = await fileResponse.text();+ const relativePath = item.path.slice(skillPath.length + 1);- if (skillFiles.length === 0) {- return { files: [], error: `No files found in ${skillPath}` };+ // Reject paths that attempt directory traversal+ if (relativePath.includes("..")) {+ console.warn(`Skipping file with unsafe path: ${item.path}`);+ continue;}- const files: SkillFile[] = [];- for (const item of skillFiles) {- const rawUrl = `${GITHUB_RAW}/${owner}/${repo}/${branch}/${item.path}`;- const fileResponse = await fetch(rawUrl, { headers: ghHeaders });+ files.push({+ path: relativePath,+ content,+ });+ }- if (!fileResponse.ok) {- console.warn(`Failed to fetch ${item.path}: ${fileResponse.status}`);- continue;- }+ return { files };+}- const content = await fileResponse.text();- const relativePath = item.path.slice(skillPath.length + 1);+async function downloadSingleSkillFile(+ skillUrl: string,+ ghHeaders: Record<string, string>+): Promise<SkillFile[] | null> {+ let fileName: string;+ try {+ const url = new URL(skillUrl);+ const last = url.pathname.split("/").filter(Boolean).pop();+ if (url.hostname !== "raw.githubusercontent.com" || !last || !last.includes(".")) {+ return null;+ }+ fileName = last;+ } catch {+ return null;+ }- // Reject paths that attempt directory traversal- if (relativePath.includes("..")) {- console.warn(`Skipping file with unsafe path: ${item.path}`);- continue;- }+ const response = await fetch(skillUrl, { headers: ghHeaders });+ if (!response.ok) return null;+ const content = await response.text();+ return [{ path: fileName, content }];+}- files.push({- path: relativePath,- content,- });- }+export async function downloadSkillFromGitHub(+ skill: Skill & { project: string }+): Promise<{ files: SkillFile[]; error?: string }> {+ const parsed = parseGitHubUrl(skill.url);+ if (!parsed) {+ return { files: [], error: `Invalid GitHub URL: ${skill.url}` };+ }++ const { owner, repo, branch, path: skillPath } = parsed;+ const ghHeaders = getGitHubHeaders();- return { files };+ let treeError: string | undefined;+ try {+ const result = await downloadSkillTree(owner, repo, branch, skillPath, ghHeaders);+ if (result.files.length > 0) return { files: result.files };+ treeError = result.error;} catch (err) {- const message = err instanceof Error ? err.message : String(err);- return { files: [], error: message };+ treeError = err instanceof Error ? err.message : String(err);}++ const single = await downloadSingleSkillFile(skill.url, ghHeaders).catch(() => null);+ if (single) return { files: single };++ return { files: [], error: treeError ?? `No files found in ${skillPath}` };}