@mezzanine-stack/git-provider-github 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @mezzanine-stack/git-provider-github
+
+`@mezzanine-stack/cms-core` の `GitProvider` を GitHub REST API で実装するアダプタです。
+
+## 責務
+
+- Markdown エントリの一覧/取得/保存/削除
+- `public/uploads/` 配下のアセット一覧取得
+- 画像・ファイルのアップロード
+- GitHub blob SHA を使った楽観的排他制御
+
+## 主要 API
+
+- `GitHubProvider`
+- `GitHubProviderOptions`
+- `GitHubApiError`
+
+## 利用例
+
+```typescript
+import { GitHubProvider } from "@mezzanine-stack/git-provider-github";
+
+const provider = new GitHubProvider({
+  token: process.env.GITHUB_TOKEN!,
+  owner: "your-org",
+  repo: "your-site-repo",
+  branch: "main",
+});
+```
+
+## 依存関係
+
+- `@mezzanine-stack/cms-core`
+

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@mezzanine-stack/git-provider-github",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@mezzanine-stack/cms-core": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/github-provider.test.ts

@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { GitHubProvider } from "./github-provider.js";
+
+describe("GitHubProvider", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("saveEntry sends PUT request and returns revision", async () => {
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          content: { sha: "new-sha", path: "src/content/blog/hello.md" },
+          commit: { sha: "commit-sha" },
+        }),
+        { status: 200 },
+      ),
+    );
+
+    const provider = new GitHubProvider({
+      token: "token",
+      owner: "owner",
+      repo: "repo",
+      branch: "main",
+    });
+
+    const result = await provider.saveEntry("src/content/blog/hello.md", "hello", {
+      message: "save",
+      sha: "old-sha",
+    });
+
+    expect(result).toEqual({ revision: "new-sha" });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0] ?? [];
+    expect(String(url)).toContain("/contents/src/content/blog/hello.md");
+    expect((init as RequestInit).method).toBe("PUT");
+  });
+
+  it("listAssets returns empty array when folder is missing", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("not found", { status: 404 }));
+
+    const provider = new GitHubProvider({
+      token: "token",
+      owner: "owner",
+      repo: "repo",
+    });
+
+    const assets = await provider.listAssets("public/uploads");
+    expect(assets).toEqual([]);
+  });
+});
+

package/src/github-provider.ts

@@ -0,0 +1,370 @@
+/**
+ * GitHub REST API を使った GitProvider 実装。
+ *
+ * v1 の保存先は default branch への直接 commit に限定する。
+ * asset upload (uploadAsset) は CP 4-2 で実装する。
+ */
+
+import type { AssetItem, CatalogEntry, GitProvider, SaveResult } from "@mezzanine-stack/cms-core";
+
+/** GitHub REST API のベース URL（末尾スラッシュなし） */
+const GITHUB_REST_API_ORIGIN = "https://api.github.com";
+
+// ---------------------------------------------------------------------------
+// GitHub API レスポンス型 (必要最小限)
+// ---------------------------------------------------------------------------
+
+interface GitHubContentItem {
+  type: "file" | "dir" | "symlink" | "submodule";
+  name: string;
+  path: string;
+  sha: string;
+  size: number;
+  download_url: string | null;
+}
+
+interface GitHubFileContent {
+  type: "file";
+  name: string;
+  path: string;
+  sha: string;
+  size: number;
+  content: string;   // base64 encoded
+  encoding: "base64";
+}
+
+interface GitHubPutResponse {
+  content: {
+    sha: string;
+    path: string;
+  };
+  commit: {
+    sha: string;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// GitHubProvider
+// ---------------------------------------------------------------------------
+
+export interface GitHubProviderOptions {
+  /** GitHub personal access token または OAuth access token */
+  token: string;
+  /** リポジトリオーナー (ユーザ名 or Org 名) */
+  owner: string;
+  /** リポジトリ名 */
+  repo: string;
+  /** 保存先ブランチ (デフォルト: "main") */
+  branch?: string;
+}
+
+export class GitHubProvider implements GitProvider {
+  private readonly token: string;
+  private readonly owner: string;
+  private readonly repo: string;
+  private readonly branch: string;
+  private readonly baseUrl: string;
+
+  constructor(options: GitHubProviderOptions) {
+    this.token = options.token;
+    this.owner = options.owner;
+    this.repo = options.repo;
+    this.branch = options.branch ?? "main";
+    this.baseUrl = `${GITHUB_REST_API_ORIGIN}/repos/${this.owner}/${this.repo}`;
+  }
+
+  // -------------------------------------------------------------------------
+  // listEntries
+  // -------------------------------------------------------------------------
+
+  async listEntries(folder: string): Promise<CatalogEntry[]> {
+    const url = `${this.baseUrl}/contents/${folder}?ref=${this.branch}`;
+    const items = await this.get<GitHubContentItem[]>(url);
+
+    const mdFiles = items.filter(
+      (item) =>
+        item.type === "file" &&
+        (item.name.endsWith(".md") || item.name.endsWith(".mdx"))
+    );
+
+    // 各ファイルの frontmatter から title / draft / date を取得する。
+    // 並列フェッチで N+1 を最小化する。
+    const entries = await Promise.all(
+      mdFiles.map(async (item): Promise<CatalogEntry> => {
+        try {
+          const { content, revision } = await this.getEntry(item.path);
+          const { title, draft, date } = extractFrontmatterMeta(content);
+          const slug = item.name.replace(/\.(md|mdx)$/, "");
+          return {
+            entryId: slug,
+            title: title ?? slug,
+            draft,
+            updatedAt: date,
+            sourcePath: item.path,
+            revision,
+          };
+        } catch {
+          // フェッチ失敗時はファイル名をフォールバックとして返す
+          const slug = item.name.replace(/\.(md|mdx)$/, "");
+          return {
+            entryId: slug,
+            sourcePath: item.path,
+            revision: item.sha,
+          };
+        }
+      })
+    );
+
+    return entries;
+  }
+
+  // -------------------------------------------------------------------------
+  // getEntry
+  // -------------------------------------------------------------------------
+
+  async getEntry(
+    sourcePath: string
+  ): Promise<{ content: string; revision: string }> {
+    const url = `${this.baseUrl}/contents/${sourcePath}?ref=${this.branch}`;
+    const data = await this.get<GitHubFileContent>(url);
+
+    const content = decodeBase64(data.content);
+    return { content, revision: data.sha };
+  }
+
+  // -------------------------------------------------------------------------
+  // saveEntry
+  // -------------------------------------------------------------------------
+
+  async saveEntry(
+    sourcePath: string,
+    content: string,
+    options: { sha?: string; message: string }
+  ): Promise<SaveResult> {
+    const url = `${this.baseUrl}/contents/${sourcePath}`;
+    const body: Record<string, unknown> = {
+      message: options.message,
+      content: encodeBase64(content),
+      branch: this.branch,
+    };
+    if (options.sha) {
+      body.sha = options.sha;
+    }
+
+    const data = await this.put<GitHubPutResponse>(url, body);
+    return { revision: data.content.sha };
+  }
+
+  // -------------------------------------------------------------------------
+  // deleteEntry
+  // -------------------------------------------------------------------------
+
+  async deleteEntry(
+    sourcePath: string,
+    sha: string,
+    message: string
+  ): Promise<void> {
+    const url = `${this.baseUrl}/contents/${sourcePath}`;
+    await this.delete(url, { message, sha, branch: this.branch });
+  }
+
+  // -------------------------------------------------------------------------
+  // listAssets
+  // -------------------------------------------------------------------------
+
+  /**
+   * 指定ディレクトリ配下のアセット一覧を返す。
+   * ディレクトリが存在しない場合は空配列を返す。
+   */
+  async listAssets(folder: string): Promise<AssetItem[]> {
+    const url = `${this.baseUrl}/contents/${folder}?ref=${this.branch}`;
+    let items: GitHubContentItem[];
+    try {
+      items = await this.get<GitHubContentItem[]>(url);
+    } catch (err) {
+      if (err instanceof GitHubApiError && err.status === 404) {
+        return [];
+      }
+      throw err;
+    }
+
+    // ファイルのみを返す（ディレクトリは除外）
+    return items
+      .filter((item) => item.type === "file")
+      .map((item) => {
+        // "public/uploads/foo.jpg" → "/uploads/foo.jpg"
+        const publicPath = folder.startsWith("public")
+          ? item.path.slice("public".length)
+          : `/${item.path}`;
+        return {
+          name: item.name,
+          path: item.path,
+          publicPath,
+          size: item.size,
+        };
+      });
+  }
+
+  // -------------------------------------------------------------------------
+  // uploadAsset
+  // -------------------------------------------------------------------------
+
+  /**
+   * バイナリアセットを GitHub リポジトリにアップロードする。
+   * 既存ファイルが存在する場合は SHA を取得して上書きする。
+   * @returns アップロード先のリポジトリ内パス
+   */
+  async uploadAsset(
+    sourcePath: string,
+    content: Uint8Array,
+    message: string
+  ): Promise<string> {
+    const url = `${this.baseUrl}/contents/${sourcePath}`;
+    const base64 = uint8ArrayToBase64(content);
+
+    // 既存ファイルの SHA を取得して楽観的排他を維持する
+    let existingSha: string | undefined;
+    try {
+      const existing = await this.get<GitHubFileContent>(
+        `${url}?ref=${this.branch}`
+      );
+      existingSha = existing.sha;
+    } catch {
+      // 404 = 新規ファイル、それ以外は無視して続行
+    }
+
+    const body: Record<string, unknown> = {
+      message,
+      content: base64,
+      branch: this.branch,
+    };
+    if (existingSha) {
+      body.sha = existingSha;
+    }
+
+    await this.put<GitHubPutResponse>(url, body);
+    return sourcePath;
+  }
+
+  // -------------------------------------------------------------------------
+  // HTTP ヘルパー
+  // -------------------------------------------------------------------------
+
+  private headers(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.token}`,
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      "Content-Type": "application/json",
+    };
+  }
+
+  private async get<T>(url: string): Promise<T> {
+    const res = await fetch(url, { headers: this.headers() });
+    if (!res.ok) {
+      throw new GitHubApiError(res.status, await res.text(), "GET", url);
+    }
+    return res.json() as Promise<T>;
+  }
+
+  private async put<T>(url: string, body: unknown): Promise<T> {
+    const res = await fetch(url, {
+      method: "PUT",
+      headers: this.headers(),
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      throw new GitHubApiError(res.status, await res.text(), "PUT", url);
+    }
+    return res.json() as Promise<T>;
+  }
+
+  private async delete(url: string, body: unknown): Promise<void> {
+    const res = await fetch(url, {
+      method: "DELETE",
+      headers: this.headers(),
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      throw new GitHubApiError(res.status, await res.text(), "DELETE", url);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// エラー型
+// ---------------------------------------------------------------------------
+
+export class GitHubApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: string,
+    public readonly method: string,
+    public readonly url: string
+  ) {
+    super(`GitHub API ${method} ${url} failed with ${status}: ${body}`);
+    this.name = "GitHubApiError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ユーティリティ
+// ---------------------------------------------------------------------------
+
+/** GitHub API の base64 文字列 (改行含む) をデコードする */
+function decodeBase64(encoded: string): string {
+  const cleaned = encoded.replace(/\n/g, "");
+  const binary = atob(cleaned);
+  const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+  return new TextDecoder("utf-8").decode(bytes);
+}
+
+/** テキストを base64 にエンコードする */
+function encodeBase64(text: string): string {
+  return btoa(unescape(encodeURIComponent(text)));
+}
+
+/** Uint8Array を base64 文字列に変換する */
+function uint8ArrayToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Markdown テキストから frontmatter の title / draft / date を簡易抽出する。
+ * 完全な YAML パースは cms-core の deserializeMarkdown に委ねるが、
+ * listEntries の軽量化のためにここでは行単位の簡易抽出を使う。
+ */
+function extractFrontmatterMeta(content: string): {
+  title?: string;
+  draft?: boolean;
+  date?: string;
+} {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return {};
+
+  const result: { title?: string; draft?: boolean; date?: string } = {};
+
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line?.trim() === "---") break;
+
+    const match = line?.match(/^(\w+):\s*(.+)$/);
+    if (!match) continue;
+    const [, key, val] = match;
+    const value = val?.trim() ?? "";
+
+    if (key === "title") {
+      result.title = value.replace(/^["']|["']$/g, "");
+    } else if (key === "draft") {
+      result.draft = value === "true";
+    } else if (key === "date") {
+      result.date = value.replace(/^["']|["']$/g, "");
+    }
+  }
+
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// git-provider-github 公開 API
+
+export {
+  GitHubProvider,
+  GitHubApiError,
+  type GitHubProviderOptions,
+} from "./github-provider.js";

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+  },
+});
+