fix(skills): skip the index on GitHub transport errors instead of failing the build (#108)

PR #95 rewrote the generator and dropped the deploy-safe error handling
from PR #89, so any GitHub outage, 5xx, or exhausted rate limit aborted
the whole production build via bun run generate.

Restore the intended two-tier split:

- Transport errors (fetch network failures, non-ok GitHub responses,
  rate limits) are classified as GitHubTransportError. The entrypoint
  warns and exits 0, leaving the index absent for that deploy.
- Schema, packaging, validation, and filesystem errors still throw and
  fail the build, so a malformed index can never ship.

The script writes nothing before every artifact validates, so skipping
on a transport error leaves no partial output behind.

Author: nibzard

scripts/generate-agent-skills-index.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 // ABOUTME: Generates the Agent Skills discovery index and complete skill archives.
-// ABOUTME: Reads one commit-pinned steel-dev/skills snapshot and fails the build on errors.
+// ABOUTME: Skips the index when GitHub is unreachable; fails the build on validation errors.
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
@@ -282,6 +282,24 @@ export async function buildSkillArtifactsFromRepositoryArchive(
   return artifacts;
 }
 
+/**
+ * GitHub was unreachable or unhealthy: a network failure, a non-ok response,
+ * or an exhausted rate limit. The entrypoint treats these as skippable because
+ * a docs deploy should not hinge on GitHub; every other error stays fatal.
+ */
+export class GitHubTransportError extends Error {}
+
+/** Fetches from GitHub, classifying network failures as transport errors. */
+export async function githubFetch(url: string, headers: Record<string, string>): Promise<Response> {
+  try {
+    return await fetch(url, { headers });
+  } catch (error) {
+    throw new GitHubTransportError(
+      `Could not reach ${url}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
 function githubAuthorizationHeaders(): Record<string, string> {
   const token = process.env.GITHUB_TOKEN?.trim();
   return token ? { Authorization: `Bearer ${token}` } : {};
@@ -295,7 +313,7 @@ function githubApiHeaders(): Record<string, string> {
   };
 }
 
-function githubRequestError(action: string, response: Response): Error {
+export function githubRequestError(action: string, response: Response): GitHubTransportError {
   const remaining = response.headers.get('x-ratelimit-remaining');
   const reset = response.headers.get('x-ratelimit-reset');
   let guidance = '';
@@ -310,13 +328,14 @@ function githubRequestError(action: string, response: Response): Error {
     guidance = `; GitHub API rate limit exhausted until ${resetAt}, set GITHUB_TOKEN`;
   }
 
-  return new Error(`${action}: GitHub returned ${response.status}${guidance}`);
+  return new GitHubTransportError(`${action}: GitHub returned ${response.status}${guidance}`);
 }
 
 async function resolveHeadCommit(): Promise<string> {
-  const response = await fetch(`https://api.github.com/repos/${SKILLS_REPO}/commits/main`, {
-    headers: githubApiHeaders(),
-  });
+  const response = await githubFetch(
+    `https://api.github.com/repos/${SKILLS_REPO}/commits/main`,
+    githubApiHeaders(),
+  );
 
   if (!response.ok) {
     throw githubRequestError(`Could not resolve ${SKILLS_REPO}@main`, response);
@@ -332,7 +351,7 @@ async function resolveHeadCommit(): Promise<string> {
 
 async function fetchRepositoryArchive(commit: string): Promise<Buffer> {
   const url = `https://codeload.github.com/${SKILLS_REPO}/tar.gz/${commit}`;
-  const response = await fetch(url, { headers: githubAuthorizationHeaders() });
+  const response = await githubFetch(url, githubAuthorizationHeaders());
 
   if (!response.ok) {
     throw githubRequestError(`Could not fetch ${SKILLS_REPO}@${commit}`, response);
@@ -364,5 +383,14 @@ async function main(): Promise<void> {
 }
 
 if (import.meta.main) {
-  await main();
+  try {
+    await main();
+  } catch (error) {
+    if (!(error instanceof GitHubTransportError)) throw error;
+    // A docs deploy should not hinge on GitHub being reachable. Skipping leaves
+    // the index absent, which is honest, rather than stale or unverifiable.
+    // main() writes nothing before every artifact validates, so no partial
+    // output can deploy; validation and filesystem errors rethrow above.
+    console.warn(`⚠️ Skipped the Agent Skills index: ${error.message}`);
+  }
 }

tests/agent-skills-index.test.ts

@@ -7,6 +7,9 @@ import {
   AGENT_SKILLS_SCHEMA,
   buildAgentSkillsIndex,
   buildSkillArtifactsFromRepositoryArchive,
+  GitHubTransportError,
+  githubFetch,
+  githubRequestError,
   MAX_SKILL_ARCHIVE_CONTENT_BYTES,
   type SkillArtifact,
 } from '../scripts/generate-agent-skills-index';
@@ -275,3 +278,59 @@ describe('buildAgentSkillsIndex', () => {
     expect(() => buildAgentSkillsIndex([])).toThrow(/skill/i);
   });
 });
+
+describe('GitHub transport error classification', () => {
+  test('classifies non-ok GitHub responses as skippable transport errors', () => {
+    const error = githubRequestError(
+      'Could not resolve steel-dev/skills@main',
+      new Response(null, { status: 502 }),
+    );
+
+    expect(error).toBeInstanceOf(GitHubTransportError);
+    expect(error.message).toContain('502');
+  });
+
+  test('classifies exhausted rate limits as skippable transport errors', () => {
+    const error = githubRequestError(
+      'Could not resolve steel-dev/skills@main',
+      new Response(null, {
+        status: 403,
+        headers: { 'x-ratelimit-remaining': '0', 'x-ratelimit-reset': '1767225600' },
+      }),
+    );
+
+    expect(error).toBeInstanceOf(GitHubTransportError);
+    expect(error.message).toContain('rate limit');
+  });
+
+  test('classifies fetch network failures as skippable transport errors', async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (() =>
+      Promise.reject(new TypeError('Unable to connect'))) as typeof globalThis.fetch;
+
+    try {
+      const error = await githubFetch('https://api.github.com/repos/steel-dev/skills', {}).catch(
+        (caught: unknown) => caught,
+      );
+
+      expect(error).toBeInstanceOf(GitHubTransportError);
+      expect((error as Error).message).toContain('Unable to connect');
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test('validation errors are not classified as skippable transport errors', async () => {
+    const indexError = await Promise.resolve()
+      .then(() => buildAgentSkillsIndex([]))
+      .catch((caught: unknown) => caught);
+    const packagingError = await buildSkillArtifactsFromRepositoryArchive(
+      await repositoryArchive({ skillMd: null }),
+    ).catch((caught: unknown) => caught);
+
+    expect(indexError).toBeInstanceOf(Error);
+    expect(indexError).not.toBeInstanceOf(GitHubTransportError);
+    expect(packagingError).toBeInstanceOf(Error);
+    expect(packagingError).not.toBeInstanceOf(GitHubTransportError);
+  });
+});