app/lib/editor/github.server.ts

Functions

Imports

It imports app/lib/bytes.mjs, app/lib/editor/contents-cap.mjs. Imported by app/kb/editor.server.ts, app/kb/procedures/primer-dependents.server.ts, app/kb/procedures/save.server.ts, app/kb/registry/host.server.ts, app/kb/registry/save.server.ts, app/lib/admin/posts-actions.server.ts, app/lib/carrel/cv-handler.server.ts, app/lib/carrel/dictionary-handler.server.ts, app/lib/carrel/document-handler.server.ts, app/lib/carrel/errors.server.ts, app/lib/carrel/page-handler.server.ts, app/lib/carrel/phage-handler.server.ts, app/lib/carrel/procedure-handler.server.ts, app/lib/carrel/publication-handler.server.ts, app/lib/carrel/registry-handler.server.ts, app/lib/carrel/roster-handler.server.ts, app/lib/carrel/site-adapter.server.ts, app/lib/cv/save.server.ts, app/lib/dictionary/save.server.ts, app/lib/editor/preview-link-action.server.ts, app/lib/editor/publish.server.ts, app/lib/editor/write-path.server.ts, app/lib/health/checks.server.ts, app/lib/llms/save.server.ts, app/lib/operator/api.server.ts, app/lib/operator/sync-tools.server.ts, app/lib/pages/save.server.ts, app/lib/phages/save.server.ts, app/lib/publications/save.server.ts, app/lib/roster/save.server.ts, app/routes/admin.posts.$slug.edit.tsx, app/routes/admin.posts.$slug.history.tsx, app/routes/admin.posts.$slug.revisions.tsx.

Source

1// The Git Data API commit shape stays because it carries the expectedHeadSha conflict guard, which
2// the Contents API write path has no seam for.
3
4import { base64ToBytes } from "../bytes.mjs";
5import { contentsCapMessage } from "./contents-cap.mjs";
6
7const API = "https://api.github.com";
8const OWNER = "DrDustinEdwards";
9const REPO = "dustinedwards-info";
10const BRANCH = "main";
11
12export class GitHubError extends Error {
13  status: number;
14  conflict: boolean;
15
16  constructor(message: string, status: number, conflict = false) {
17    super(message);
18    this.name = "GitHubError";
19    this.status = status;
20    this.conflict = conflict;
21  }
22}
23
24/** GITHUB_TOKEN is a secret, which wrangler types does not know about. */
25type GhEnv = Env & { GITHUB_TOKEN?: string };
26
27function token(env: GhEnv) {
28  const value = env.GITHUB_TOKEN;
29  if (!value) {
30    throw new GitHubError(
31      "GITHUB_TOKEN is not configured on this Worker, so the editor cannot commit.",
32      500,
33    );
34  }
35  return value;
36}
37
38async function gh<T>(
39  env: GhEnv,
40  path: string,
41  init: RequestInit & { method?: string } = {},
42): Promise<T> {
43  const response = await fetch(`${API}${path}`, {
44    ...init,
45    headers: {
46      accept: "application/vnd.github+json",
47      authorization: `Bearer ${token(env)}`,
48      "content-type": "application/json",
49      // GitHub rejects requests without one.
50      "user-agent": "dustinedwards-info-editor",
51      "x-github-api-version": "2022-11-28",
52      ...init.headers,
53    },
54  });
55
56  if (!response.ok) {
57    let detail = "";
58    try {
59      const body = (await response.json()) as { message?: string };
60      detail = body.message ? `: ${body.message}` : "";
61    } catch {
62      detail = "";
63    }
64    throw new GitHubError(
65      `GitHub ${init.method ?? "GET"} ${path} failed with ${response.status}${detail}`,
66      response.status,
67    );
68  }
69
70  return (await response.json()) as T;
71}
72
73export async function getHead(env: GhEnv) {
74  const ref = await gh<{ object: { sha: string } }>(
75    env,
76    `/repos/${OWNER}/${REPO}/git/ref/heads/${BRANCH}`,
77  );
78  const commit = await gh<{ tree: { sha: string } }>(
79    env,
80    `/repos/${OWNER}/${REPO}/git/commits/${ref.object.sha}`,
81  );
82  return { commitSha: ref.object.sha, treeSha: commit.tree.sha };
83}
84
85/** Null on 404, so a caller can tell "absent" (create a post) from "failed" (an outage). */
86export async function readFile(env: GhEnv, path: string, ref = BRANCH) {
87  try {
88    const file = await gh<{
89      content: string;
90      encoding: string;
91      sha: string;
92      size: number;
93    }>(env, `/repos/${OWNER}/${REPO}/contents/${encodeURI(path)}?ref=${ref}`);
94    const capped = contentsCapMessage(file, path);
95    if (capped) {
96      throw new GitHubError(capped, 422);
97    }
98    const content =
99      file.encoding === "base64"
100        ? new TextDecoder().decode(base64ToBytes(file.content))
101        : file.content;
102    return { content, sha: file.sha };
103  } catch (error) {
104    if (error instanceof GitHubError && error.status === 404) return null;
105    throw error;
106  }
107}
108
109/** Not recursive: content/posts/ is flat. The directory form caps at 1000 entries, hence the guard. */
110export async function listDirectory(env: GhEnv, path: string, ref = BRANCH) {
111  const entries = await gh<
112    Array<{ name: string; path: string; sha: string; type: string; size: number }>
113  >(env, `/repos/${OWNER}/${REPO}/contents/${encodeURI(path)}?ref=${ref}`);
114
115  if (!Array.isArray(entries)) {
116    // A file path answers with an object. Refuse rather than iterate its keys.
117    throw new GitHubError(`"${path}" is not a directory at ${ref}.`, 422);
118  }
119  if (entries.length >= 1000) {
120    throw new GitHubError(
121      `"${path}" returned ${entries.length} entries, at the Contents API's ` +
122        `1000-entry directory cap; the listing may be truncated. Move the ` +
123        `rebuild to the Trees API before trusting it again.`,
124      422,
125    );
126  }
127  return entries;
128}
129
130/**
131 * A static asset's directory entry, by its site path, or null when the repository has none: existence and
132 * size, never the bytes, which can pass the Contents API's 1 MB cap. The PDFs and the roster photographs
133 * are checked through it.
134 */
135export async function publicFileEntry(env: GhEnv, sitePath: string) {
136  const at = sitePath.lastIndexOf("/");
137  const dir = `public${sitePath.slice(0, at)}`;
138  const name = sitePath.slice(at + 1);
139  try {
140    const entry = (await listDirectory(env, dir)).find((e) => e.type === "file" && e.name === name);
141    return entry ? { size: entry.size } : null;
142  } catch (error) {
143    if (error instanceof GitHubError && error.status === 404) return null;
144    throw error;
145  }
146}
147
148/** The repository's posts: each `content/posts/*.md` file, with the slug its name carries. */
149export async function listPostFiles(env: GhEnv) {
150  const entries = await listDirectory(env, "content/posts");
151  return entries
152    .filter((e) => e.type === "file" && e.name.endsWith(".md"))
153    .map((e) => ({ ...e, slug: e.name.slice(0, -".md".length) }));
154}
155
156/** Raw bytes: readFile's TextDecoder replaces invalid UTF-8, so an image would come back a different length. */
157export async function readBinaryFile(env: GhEnv, path: string, ref = BRANCH) {
158  try {
159    const file = await gh<{ content: string; encoding: string; size: number }>(
160      env,
161      `/repos/${OWNER}/${REPO}/contents/${encodeURI(path)}?ref=${ref}`,
162    );
163    const capped = contentsCapMessage(file, path);
164    if (capped) {
165      throw new GitHubError(capped, 422);
166    }
167    return base64ToBytes(file.content);
168  } catch (error) {
169    if (error instanceof GitHubError && error.status === 404) return null;
170    throw error;
171  }
172}
173
174type FileChange =
175  | { path: string; content: string }
176  | { path: string; content: null };
177
178/**
179 * `commitFiles`' expectedBlobs for one file, or undefined when the caller named no version. Carrel's version of
180 * a file-backed item is its blob sha, so a save is refused only when THAT file changed.
181 */
182export function blobGuard(path: string, expectedBlobSha: string | null | undefined) {
183  return expectedBlobSha === undefined ? undefined : { [path]: expectedBlobSha };
184}
185
186/**
187 * expectedHeadSha is the conflict gate: if main moved since the editor loaded, the save is refused,
188 * checked up front so it fails with a clean message before any blob exists.
189 */
190export async function commitFiles(
191  env: GhEnv,
192  options: {
193    changes: FileChange[];
194    message: string;
195    expectedHeadSha?: string | null;
196    /**
197     * Per path, the blob sha the caller loaded (null: the path must not exist). A path that holds anything
198     * else at the head this commit is built on is refused, so a writer is stopped by a change to ITS file
199     * and not by any other commit. Checked against the same head the commit is parented on, and the ref
200     * update below is never forced, so a change that lands in between still cannot be overwritten.
201     */
202    expectedBlobs?: Record<string, string | null>;
203  },
204) {
205  const head = await getHead(env);
206
207  if (options.expectedHeadSha && options.expectedHeadSha !== head.commitSha) {
208    throw new GitHubError(
209      `The repository changed since this post was opened (main is now ${head.commitSha.slice(0, 7)}, ` +
210        `you loaded ${options.expectedHeadSha.slice(0, 7)}). Reload and reapply your edit.`,
211      409,
212      true,
213    );
214  }
215
216  for (const [path, expected] of Object.entries(options.expectedBlobs ?? {})) {
217    const current = (await readFile(env, path, head.commitSha))?.sha ?? null;
218    if (current !== expected) {
219      throw new GitHubError(
220        `${path} changed since it was opened (it is now ${current ? current.slice(0, 7) : "absent"}, ` +
221          `you loaded ${expected ? expected.slice(0, 7) : "none"}). Reload and reapply your edit.`,
222        409,
223        true,
224      );
225    }
226  }
227
228  // A tree entry with sha: null deletes the path.
229  const tree = await Promise.all(
230    options.changes.map(async (change) => {
231      if (change.content === null) {
232        return { path: change.path, mode: "100644", type: "blob", sha: null };
233      }
234      const blob = await gh<{ sha: string }>(
235        env,
236        `/repos/${OWNER}/${REPO}/git/blobs`,
237        {
238          method: "POST",
239          body: JSON.stringify({ content: change.content, encoding: "utf-8" }),
240        },
241      );
242      return { path: change.path, mode: "100644", type: "blob", sha: blob.sha };
243    }),
244  );
245
246  const newTree = await gh<{ sha: string }>(
247    env,
248    `/repos/${OWNER}/${REPO}/git/trees`,
249    {
250      method: "POST",
251      body: JSON.stringify({ base_tree: head.treeSha, tree }),
252    },
253  );
254
255  const commit = await gh<{ sha: string }>(
256    env,
257    `/repos/${OWNER}/${REPO}/git/commits`,
258    {
259      method: "POST",
260      body: JSON.stringify({
261        message: options.message,
262        tree: newTree.sha,
263        parents: [head.commitSha],
264      }),
265    },
266  );
267
268  await gh(env, `/repos/${OWNER}/${REPO}/git/refs/heads/${BRANCH}`, {
269    method: "PATCH",
270    // Never force: a rejection means main moved since the check, and losing that race must not cost a commit.
271    body: JSON.stringify({ sha: commit.sha, force: false }),
272  });
273
274  // Content-addressed, so each equals gitBlobSha() of the same bytes; renderAndWrite relies on that.
275  const blobShas: Record<string, string | null> = {};
276  for (const entry of tree) blobShas[entry.path] = entry.sha;
277
278  return { commitSha: commit.sha, blobShas };
279}
280
281type PostCommit = {
282  sha: string;
283  message: string;
284  author: string;
285  date: string;
286};
287
288export async function listCommitsForPath(
289  env: GhEnv,
290  path: string,
291  limit = 20,
292): Promise<PostCommit[]> {
293  const commits = await gh<
294    Array<{
295      sha: string;
296      commit: { message: string; author: { name: string; date: string } };
297    }>
298  >(
299    env,
300    `/repos/${OWNER}/${REPO}/commits?path=${encodeURIComponent(path)}` +
301      `&sha=${BRANCH}&per_page=${limit}`,
302  );
303
304  return commits.map((entry) => ({
305    sha: entry.sha,
306    message: entry.commit.message.split("\n")[0] ?? "",
307    author: entry.commit.author.name,
308    date: entry.commit.author.date,
309  }));
310}
311
312const COMMIT_SHA = /^[0-9a-f]{7,40}$/i;
313
314/** Carrel's revision list for one file: null when the file (or the id's owner) is absent. */
315export async function fileRevisions(env: GhEnv, path: string | null) {
316  if (!path || !(await readFile(env, path))) return null;
317  const commits = await listCommitsForPath(env, path, 50);
318  return commits.map((c) => ({
319    version: c.sha,
320    at: new Date(c.date).toISOString(),
321    author: c.author.slice(0, 200),
322    message: c.message.slice(0, 2000),
323  }));
324}
325
326/** One file as it stood at a commit, for Carrel: null for an absent path, a malformed version or an unknown ref. */
327export async function fileRevisionSource(env: GhEnv, path: string | null, version: string) {
328  if (!path || !COMMIT_SHA.test(version)) return null;
329  try {
330    return (await readFile(env, path, version))?.content ?? null;
331  } catch (error) {
332    // An unknown ref is a missing version, not a failure of the site.
333    if (error instanceof GitHubError && error.status === 422) return null;
334    throw error;
335  }
336}
337
338export async function getCommitPatch(env: GhEnv, sha: string, path: string) {
339  const commit = await gh<{
340    files?: Array<{ filename: string; patch?: string; status: string }>;
341  }>(env, `/repos/${OWNER}/${REPO}/commits/${sha}`);
342
343  const file = commit.files?.find((entry) => entry.filename === path);
344  return file ? { patch: file.patch ?? null, status: file.status } : null;
345}