@pulsemcp/air-provider-github 0.0.1

package/README.md

@@ -0,0 +1,79 @@
+# @pulsemcp/air-provider-github
+
+AIR catalog provider for GitHub. Resolves `github://` URIs in `air.json` by fetching file content from the GitHub REST API.
+
+## Installation
+
+```bash
+npm install @pulsemcp/air-provider-github
+```
+
+## Usage
+
+### In air.json
+
+Reference remote artifact indexes using `github://` URIs:
+
+```json
+{
+  "name": "my-team",
+  "skills": [
+    "github://acme/air-org/skills/skills.json",
+    "./skills/skills.json"
+  ],
+  "mcp": [
+    "github://acme/air-org/mcp/mcp.json",
+    "./mcp/mcp.json"
+  ]
+}
+```
+
+### Programmatic
+
+```typescript
+import { resolveArtifacts } from "@pulsemcp/air-core";
+import { GitHubCatalogProvider } from "@pulsemcp/air-provider-github";
+
+const provider = new GitHubCatalogProvider();
+// Or with a token for private repos:
+// const provider = new GitHubCatalogProvider({ token: "ghp_..." });
+
+const artifacts = await resolveArtifacts("./air.json", {
+  providers: [provider],
+});
+```
+
+## URI Format
+
+```
+github://owner/repo/path/to/file.json
+github://owner/repo/path/to/file.json@ref
+```
+
+| Component | Description |
+|-----------|-------------|
+| `owner` | GitHub organization or user |
+| `repo` | Repository name |
+| `path` | Path to the JSON file within the repo |
+| `@ref` | Optional git ref (branch, tag, commit SHA) |
+
+Examples:
+- `github://acme/air-org/skills/skills.json` — latest from default branch
+- `github://acme/air-org/mcp/mcp.json@v1.0.0` — pinned to a tag
+- `github://acme/air-org/mcp/mcp.json@main` — explicit branch
+
+## Authentication
+
+| Scenario | Auth Required? | How |
+|----------|---------------|-----|
+| Public repository | No | Works out of the box |
+| Private repository | Yes | Set `AIR_GITHUB_TOKEN` env var or pass `token` option |
+| Higher rate limits | Optional | Authenticated requests get 5,000 req/hr vs 60 |
+
+```bash
+export AIR_GITHUB_TOKEN=ghp_your_token_here
+```
+
+## Caching
+
+Fetched files are cached locally at `~/.air/cache/github/{owner}/{repo}/{ref}/{path}`. Delete the cache directory to force a re-fetch.

package/dist/github-provider.d.ts

@@ -0,0 +1,43 @@
+import type { CatalogProvider } from "@pulsemcp/air-core";
+export interface GitHubUri {
+    owner: string;
+    repo: string;
+    path: string;
+    ref?: string;
+}
+export interface GitHubProviderOptions {
+    /**
+     * GitHub personal access token for authenticating API requests.
+     * Required for private repositories. Optional for public repos
+     * (unauthenticated requests have lower rate limits).
+     *
+     * Can also be set via the AIR_GITHUB_TOKEN environment variable.
+     */
+    token?: string;
+}
+/**
+ * Parse a github:// URI into its components.
+ *
+ * Format: github://owner/repo/path/to/file.json
+ * With ref: github://owner/repo/path/to/file.json@ref
+ */
+export declare function parseGitHubUri(uri: string): GitHubUri;
+/**
+ * Get the local cache directory for GitHub content.
+ */
+export declare function getCacheDir(): string;
+/**
+ * GitHub catalog provider — resolves github:// URIs by fetching
+ * file content from the GitHub REST API.
+ *
+ * Works without authentication for public repositories. Pass a token
+ * (or set AIR_GITHUB_TOKEN) for private repos or higher rate limits.
+ */
+export declare class GitHubCatalogProvider implements CatalogProvider {
+    scheme: string;
+    private token;
+    constructor(options?: GitHubProviderOptions);
+    resolve(uri: string, _baseDir: string): Promise<Record<string, unknown>>;
+    private fetchFromGitHub;
+}
+//# sourceMappingURL=github-provider.d.ts.map

package/dist/github-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-provider.d.ts","sourceRoot":"","sources":["../src/github-provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAuBrD;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAGpC;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,MAAM,SAAY;IAClB,OAAO,CAAC,KAAK,CAAqB;gBAEtB,OAAO,CAAC,EAAE,qBAAqB;IAIrC,OAAO,CACX,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAuBrB,eAAe;CAkD9B"}

package/dist/github-provider.js

@@ -0,0 +1,104 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+/**
+ * Parse a github:// URI into its components.
+ *
+ * Format: github://owner/repo/path/to/file.json
+ * With ref: github://owner/repo/path/to/file.json@ref
+ */
+export function parseGitHubUri(uri) {
+    const withoutScheme = uri.replace(/^github:\/\//, "");
+    const parts = withoutScheme.split("/");
+    if (parts.length < 3) {
+        throw new Error(`Invalid github:// URI: "${uri}". Expected format: github://owner/repo/path/to/file.json`);
+    }
+    const owner = parts[0];
+    const repo = parts[1];
+    let filePath = parts.slice(2).join("/");
+    // Extract optional @ref from the last segment
+    let ref;
+    const atIndex = filePath.lastIndexOf("@");
+    if (atIndex > 0) {
+        ref = filePath.slice(atIndex + 1);
+        filePath = filePath.slice(0, atIndex);
+    }
+    return { owner, repo, path: filePath, ref };
+}
+/**
+ * Get the local cache directory for GitHub content.
+ */
+export function getCacheDir() {
+    const home = process.env.HOME || process.env.USERPROFILE || "~";
+    return resolve(home, ".air", "cache", "github");
+}
+/**
+ * GitHub catalog provider — resolves github:// URIs by fetching
+ * file content from the GitHub REST API.
+ *
+ * Works without authentication for public repositories. Pass a token
+ * (or set AIR_GITHUB_TOKEN) for private repos or higher rate limits.
+ */
+export class GitHubCatalogProvider {
+    scheme = "github";
+    token;
+    constructor(options) {
+        this.token = options?.token || process.env.AIR_GITHUB_TOKEN;
+    }
+    async resolve(uri, _baseDir) {
+        const parsed = parseGitHubUri(uri);
+        const ref = parsed.ref || "HEAD";
+        const cacheDir = getCacheDir();
+        const cacheKey = `${parsed.owner}/${parsed.repo}/${ref}/${parsed.path}`;
+        const cachePath = resolve(cacheDir, cacheKey);
+        // Check cache first
+        if (existsSync(cachePath)) {
+            const content = readFileSync(cachePath, "utf-8");
+            return JSON.parse(content);
+        }
+        const content = await this.fetchFromGitHub(parsed);
+        // Write to cache
+        const cacheFileDir = resolve(cachePath, "..");
+        mkdirSync(cacheFileDir, { recursive: true });
+        writeFileSync(cachePath, content);
+        return JSON.parse(content);
+    }
+    async fetchFromGitHub(parsed) {
+        const repoSlug = `${parsed.owner}/${parsed.repo}`;
+        let url = `https://api.github.com/repos/${repoSlug}/contents/${parsed.path}`;
+        if (parsed.ref) {
+            url += `?ref=${encodeURIComponent(parsed.ref)}`;
+        }
+        const headers = {
+            Accept: "application/vnd.github.v3+json",
+            "User-Agent": "air-provider-github",
+        };
+        if (this.token) {
+            headers["Authorization"] = `Bearer ${this.token}`;
+        }
+        let response;
+        try {
+            response = await fetch(url, { headers });
+        }
+        catch (err) {
+            throw new Error(`Network error fetching ${url}.\n` +
+                (err instanceof Error ? `  Error: ${err.message}` : ""));
+        }
+        if (!response.ok) {
+            const hint = response.status === 404
+                ? " (repository may be private — set AIR_GITHUB_TOKEN or pass token option)"
+                : response.status === 403
+                    ? " (rate limit exceeded — set AIR_GITHUB_TOKEN for higher limits)"
+                    : "";
+            throw new Error(`GitHub API returned ${response.status} for ${url}${hint}\n` +
+                `  Repository: ${repoSlug}\n` +
+                `  Path: ${parsed.path}`);
+        }
+        const data = (await response.json());
+        if (!data.content || data.encoding !== "base64") {
+            throw new Error(`Unexpected response format from GitHub API for ${url}.\n` +
+                `  Expected base64-encoded content, got encoding="${data.encoding}".`);
+        }
+        return Buffer.from(data.content, "base64").toString("utf-8");
+    }
+}
+//# sourceMappingURL=github-provider.js.map

package/dist/github-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-provider.js","sourceRoot":"","sources":["../src/github-provider.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { AirExtension } from "@pulsemcp/air-core";
+export { GitHubCatalogProvider, parseGitHubUri, getCacheDir } from "./github-provider.js";
+export type { GitHubUri, GitHubProviderOptions } from "./github-provider.js";
+declare const extension: AirExtension;
+export default extension;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC1F,YAAY,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7E,QAAA,MAAM,SAAS,EAAE,YAIhB,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+import { GitHubCatalogProvider } from "./github-provider.js";
+export { GitHubCatalogProvider, parseGitHubUri, getCacheDir } from "./github-provider.js";
+const extension = {
+    name: "github",
+    type: "provider",
+    provider: new GitHubCatalogProvider(),
+};
+export default extension;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAG1F,MAAM,SAAS,GAAiB;IAC9B,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE,IAAI,qBAAqB,EAAE;CACtC,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@pulsemcp/air-provider-github",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pulsemcp/air.git",
+    "directory": "packages/extensions/provider-github"
+  },
+  "description": "AIR catalog provider for GitHub — resolves github:// URIs to artifact indexes",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@pulsemcp/air-core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}