@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/github/source-control/write-files.mjs

@@ -0,0 +1,468 @@
+// @ts-check
+import { createHash } from "node:crypto";
+
+/**
+ * @file Writes files into a GitHub repository through a saved custom credential, in ONE commit on top
+ * of exactly the tree the human confirmed. Moved out of core
+ * (`apps/website/src/features/custom-credentials/github-write-files.ts`) unchanged in behavior; the
+ * low-level helpers here are shared with `backup-push.mjs`.
+ *
+ * Two phases. `planFileWrite` is read-only reconnaissance run BEFORE the confirmation dialog: the
+ * branch tip, its tree, and whether each path already exists (so the dialog can say "update" or
+ * "create"). `commitFiles` runs only after the human confirms, and builds on the plan's parent commit
+ * and tree, so a branch that moved in between answers 422 on the (unforced) ref update and is
+ * reported `diverged`, never overwritten.
+ *
+ * Every request goes through core's guarded HTTP client (`kit.httpClient`, egress policy applied)
+ * with the `Authorization` header core built from the saved connection. A thrown send is
+ * `network-unreachable` with fixed caller-safe text (an egress refusal says so); its detail is
+ * `logDetail`, for the server log only.
+ *
+ * @typedef {import("./github.mjs").Kit} Kit
+ * @typedef {{ baseUrl: string, authorization: string, owner: string, repo: string }} Target
+ * @typedef {{ path: string, content: string }} WriteFile
+ * @typedef {{ status: number, bodyText: string, headers?: Record<string, string> }} HttpResponse
+ * @typedef {{ ok: false, code: "provider-error", message: string }
+ *   | { ok: false, code: "network-unreachable", message: string, logDetail: string }} Failure
+ */
+
+const PROVIDER_ERROR = "provider-error";
+const GITHUB_API_VERSION = "2026-03-10";
+const GITHUB_WRITE_FILES_TIMEOUT_MS = 30_000;
+/** The Contents API lists at most this many entries per directory; a full listing may be truncated. */
+const CONTENTS_API_DIRECTORY_LISTING_CAP = 1000;
+const GITHUB_UNREACHABLE_MESSAGE = "GitHub could not be reached: the request failed before any response arrived (a network error or timeout).";
+
+/** @param {string} value */
+export function enc(value) {
+  return encodeURIComponent(value);
+}
+
+/** @param {string} path */
+export function encPath(path) {
+  return path.split("/").map(enc).join("/");
+}
+
+/** `<baseUrl>/repos/<owner>/<repo>`. @param {Target} target */
+export function repoPathOf(target) {
+  const base = target.baseUrl.endsWith("/") ? target.baseUrl.slice(0, -1) : target.baseUrl;
+  return `${base}/repos/${enc(target.owner)}/${enc(target.repo)}`;
+}
+
+/** @param {HttpResponse} response */
+export function isOk(response) {
+  return response.status >= 200 && response.status < 300;
+}
+
+/** @param {unknown} value @param {string} field */
+export function extractStringField(value, field) {
+  if (typeof value !== "object" || value === null) return "";
+  const candidate = /** @type {Record<string, unknown>} */ (value)[field];
+  return typeof candidate === "string" ? candidate : "";
+}
+
+/** @param {HttpResponse} response @returns {{ ok: true, json: any } | { ok: false, message: string }} */
+export function parseJsonBody(response) {
+  try {
+    return { ok: true, json: JSON.parse(response.bodyText) };
+  } catch {
+    return { ok: false, message: "GitHub returned a non-JSON response." };
+  }
+}
+
+/** @param {HttpResponse} response @param {string} fallback */
+export function providerErrorMessage(response, fallback) {
+  const body = parseJsonBody(response);
+  const providerMessage = body.ok && typeof body.json?.message === "string" ? body.json.message : undefined;
+  return providerMessage ? `${fallback}: ${providerMessage}` : `${fallback} (status ${response.status})`;
+}
+
+/** @param {string} path @returns {Failure} */
+function notRegularFileFailure(path) {
+  return { ok: false, code: PROVIDER_ERROR, message: `'${path}' already exists on the branch but is not a regular file — refusing to overwrite it with a blob` };
+}
+
+/** @param {string} path */
+function splitRepoPath(path) {
+  const idx = path.lastIndexOf("/");
+  return idx === -1 ? { dir: "", name: path } : { dir: path.slice(0, idx), name: path.slice(idx + 1) };
+}
+
+/** A regular file, not a symlink or submodule (both report `download_url: null`). @param {unknown} entry */
+function isRegularFileEntry(entry) {
+  if (extractStringField(entry, "type") !== "file") return false;
+  return !(entry !== null && typeof entry === "object" && /** @type {Record<string, unknown>} */ (entry).download_url === null);
+}
+
+/** GitHub's own words for its secondary (abuse) rate limit, in a 403 body that carries no header. */
+const SECONDARY_RATE_LIMIT_PATTERN = /secondary rate limit|abuse detection/i;
+
+/** @param {HttpResponse} response @param {string} name */
+function headerOf(response, name) {
+  const headers = response.headers ?? {};
+  const found = Object.keys(headers).find((key) => key.toLowerCase() === name);
+  return found === undefined ? undefined : headers[found];
+}
+
+/** @param {{ response: HttpResponse, status: number }} required */
+function isGitHubRateLimited({ response, status }, _options = {}) {
+  if (status === 429) return true;
+  if (status !== 403) return false;
+  return headerOf(response, "retry-after") !== undefined || headerOf(response, "x-ratelimit-remaining") === "0" || SECONDARY_RATE_LIMIT_PATTERN.test(response.bodyText);
+}
+
+/** @param {{ response: HttpResponse, retryAfter: number, policy: RetryPolicy }} required */
+function gitHubRateLimitDelay({ response, retryAfter, policy }, _options = {}) {
+  if (Number.isFinite(retryAfter) && retryAfter >= 0) return retryAfter * 1000;
+  const reset = Number(headerOf(response, "x-ratelimit-reset"));
+  if (headerOf(response, "x-ratelimit-remaining") === "0" && Number.isFinite(reset)) return Math.max(0, reset * 1000 - Date.now()) + 1000;
+  return policy.rateLimitWaitMs;
+}
+
+/**
+ * How long to wait before retrying a request GitHub may answer differently next time, or
+ * `undefined` when it will not: an egress refusal, or a 4xx that is not a rate limit, is final.
+ * GitHub's documented order: `retry-after` (seconds) first, then `x-ratelimit-reset` when
+ * `x-ratelimit-remaining` is 0, then at least a minute for a secondary limit without either.
+ *
+ * @param {{ kind: "response", response: HttpResponse } | { kind: "network-unreachable", refused: boolean }} result
+ * @param {number} attempt - 1 for the first retry.
+ * @param {RetryPolicy} policy
+ * @returns {number | undefined}
+ * @complexity O(headers).
+ */
+export function retryDelayMs(result, attempt, policy) {
+  const backoff = Math.min(policy.maxBackoffMs, policy.baseBackoffMs * 2 ** (attempt - 1));
+  if (result.kind !== "response") return result.refused ? undefined : backoff;
+  const { status } = result.response;
+  const retryAfter = Number(headerOf(result.response, "retry-after"));
+  const rateLimited = isGitHubRateLimited({ response: result.response, status });
+  if (!rateLimited) return status >= 500 && status <= 599 ? backoff : undefined;
+  return gitHubRateLimitDelay({ response: result.response, retryAfter, policy });
+}
+
+/**
+ * @typedef {{ maxAttempts: number, baseBackoffMs: number, maxBackoffMs: number, rateLimitWaitMs: number, maxWaitMs: number }} RetryPolicy
+ * `maxWaitMs` caps one wait: GitHub asking for longer (an hourly limit) is reported, not slept on.
+ */
+
+/**
+ * The credentialed GitHub calls, bound to one kit.
+ *
+ * @param {Kit} kit
+ * @param {{ timeoutMs?: number, retry?: RetryPolicy }} [options] - `timeoutMs` is each request's
+ *   socket-idle budget (the egress policy may cap it lower). `retry` re-sends a request that failed
+ *   transiently ({@link retryDelayMs}); every GitHub Git Data write is safe to repeat (a blob or tree
+ *   is addressed by its content, and a non-force ref update to the same commit is a no-op). Without
+ *   it a request is sent once, as `custom_credential_write_files` always has.
+ */
+export function createGitDataClient(kit, options = {}) {
+  const timeoutMs = options.timeoutMs ?? GITHUB_WRITE_FILES_TIMEOUT_MS;
+  const sleep = kit.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+
+  /**
+   * @param {Target} target @param {{ method: "GET" | "POST" | "PATCH", url: string, body?: string }} request
+   * @returns {Promise<{ kind: "response", response: HttpResponse } | { kind: "network-unreachable", message: string, logDetail: string }>}
+   */
+  async function send(target, request) {
+    let result = await sendOnce(target, request);
+    const policy = options.retry;
+    for (let attempt = 1; policy !== undefined && attempt < policy.maxAttempts; attempt++) {
+      const waitMs = retryDelayMs(result, attempt, policy);
+      if (waitMs === undefined || waitMs > policy.maxWaitMs) break;
+      await sleep(waitMs);
+      result = await sendOnce(target, request);
+    }
+    if (result.kind === "response") return result;
+    return { kind: "network-unreachable", message: result.message, logDetail: result.logDetail };
+  }
+
+  /**
+   * @param {Target} target @param {{ method: "GET" | "POST" | "PATCH", url: string, body?: string }} request
+   * @returns {Promise<{ kind: "response", response: HttpResponse } | { kind: "network-unreachable", refused: boolean, message: string, logDetail: string }>}
+   */
+  async function sendOnce(target, request) {
+    try {
+      const response = await kit.httpClient.send({
+        method: request.method,
+        url: request.url,
+        headers: {
+          Authorization: target.authorization,
+          Accept: "application/vnd.github+json",
+          "X-GitHub-Api-Version": GITHUB_API_VERSION,
+          ...(request.body !== undefined ? { "Content-Type": "application/json" } : {}),
+        },
+        timeoutMs,
+        ...(request.body !== undefined ? { body: request.body } : {}),
+      });
+      return { kind: "response", response };
+    } catch (err) {
+      const described = kit.describeTransportError(err);
+      const refused = described.refusal !== undefined;
+      const message = refused ? `the request to GitHub was refused: ${described.refusal}` : GITHUB_UNREACHABLE_MESSAGE;
+      return { kind: "network-unreachable", refused, message, logDetail: described.logDetail };
+    }
+  }
+
+  /** @param {{ message: string, logDetail: string }} result @returns {Failure} */
+  function nonResponseFailure(result) {
+    return { ok: false, code: "network-unreachable", message: result.message, logDetail: result.logDetail };
+  }
+
+  /** A 404 is `found: false`, not a failure. @param {Target} target @param {string} url @param {string} failureFallback
+   *  @returns {Promise<{ ok: true, found: false } | { ok: true, found: true, json: any } | Failure>} */
+  async function getJson(target, url, failureFallback) {
+    const result = await send(target, { method: "GET", url });
+    if (result.kind !== "response") return nonResponseFailure(result);
+    if (result.response.status === 404) return { ok: true, found: false };
+    if (!isOk(result.response)) return { ok: false, code: PROVIDER_ERROR, message: providerErrorMessage(result.response, failureFallback) };
+    const body = parseJsonBody(result.response);
+    if (!body.ok) return { ok: false, code: PROVIDER_ERROR, message: body.message };
+    return { ok: true, found: true, json: body.json };
+  }
+
+  /** @param {Target} target @param {string} url @param {Record<string, unknown>} body @param {string} failureFallback
+   *  @returns {Promise<{ ok: true, json: any } | Failure>} */
+  async function postJson(target, url, body, failureFallback) {
+    const result = await send(target, { method: "POST", url, body: JSON.stringify(body) });
+    if (result.kind !== "response") return nonResponseFailure(result);
+    if (!isOk(result.response)) return { ok: false, code: PROVIDER_ERROR, message: providerErrorMessage(result.response, failureFallback) };
+    const parsed = parseJsonBody(result.response);
+    if (!parsed.ok) return { ok: false, code: PROVIDER_ERROR, message: parsed.message };
+    return { ok: true, json: parsed.json };
+  }
+
+  /** @param {Target} target @param {string | Uint8Array} content @returns {Promise<{ ok: true, sha: string } | Failure>} */
+  async function createBlob(target, content) {
+    const bytes = typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content.buffer, content.byteOffset, content.byteLength);
+    const result = await postJson(target, `${repoPathOf(target)}/git/blobs`, { content: bytes.toString("base64"), encoding: "base64" }, "GitHub blob creation failed");
+    if (!result.ok) return result;
+    const sha = extractStringField(result.json, "sha");
+    if (!sha) return { ok: false, code: PROVIDER_ERROR, message: "GitHub blob creation response did not include a sha" };
+    return { ok: true, sha };
+  }
+
+  /** Unforced: a 422 means the branch moved. @param {Target} target @param {string} branch @param {string} sha
+   *  @returns {Promise<{ ok: true } | { ok: false, code: "diverged", message: string } | Failure>} */
+  async function updateRef(target, branch, sha) {
+    const result = await send(target, { method: "PATCH", url: `${repoPathOf(target)}/git/refs/heads/${encPath(branch)}`, body: JSON.stringify({ sha }) });
+    if (result.kind !== "response") return nonResponseFailure(result);
+    if (result.response.status === 422) {
+      return { ok: false, code: "diverged", message: "the branch has moved since this write was confirmed — refusing to overwrite it" };
+    }
+    if (!isOk(result.response)) return { ok: false, code: PROVIDER_ERROR, message: providerErrorMessage(result.response, "GitHub branch update failed") };
+    return { ok: true };
+  }
+
+  return { send, nonResponseFailure, getJson, postJson, createBlob, updateRef };
+}
+
+/** @typedef {ReturnType<typeof createGitDataClient>} GitDataClient */
+
+/** The two write-files operations. @param {GitDataClient} git */
+export function createFileWriter(git) {
+  /** @param {Target} target @param {string} branch @param {string} path */
+  async function checkOneFileExistence(target, branch, path) {
+    const result = await git.getJson(target, `${repoPathOf(target)}/contents/${encPath(path)}?ref=${enc(branch)}`, `GitHub lookup of '${path}' failed`);
+    if (!result.ok) return result;
+    if (!result.found) return { ok: true, state: { path, exists: false } };
+    if (Array.isArray(result.json) || result.json.type !== "file") return notRegularFileFailure(path);
+    return { ok: true, state: { path, exists: true } };
+  }
+
+  /** @param {string} path @param {unknown} entry */
+  function stateFromListingEntry(path, entry) {
+    if (entry === undefined) return { ok: true, state: { path, exists: false } };
+    if (!isRegularFileEntry(entry)) return notRegularFileFailure(path);
+    return { ok: true, state: { path, exists: true } };
+  }
+
+  /** @param {{ files: readonly WriteFile[] }} required */
+  function groupWriteFilesByDirectory({ files }, _options = {}) {
+    /** @type {Map<string, WriteFile[]>} */
+    const filesByDir = new Map();
+    for (const file of files) {
+      const { dir } = splitRepoPath(file.path);
+      const bucket = filesByDir.get(dir);
+      if (bucket) bucket.push(file);
+      else filesByDir.set(dir, [file]);
+    }
+
+    return filesByDir;
+  }
+
+  /** @param {{ target: Target, branch: string, dirFiles: WriteFile[], entries: any[], stateByPath: Map<string, { path: string, exists: boolean }> }} required */
+  async function resolveDirectoryFileStates({ target, branch, dirFiles, entries, stateByPath }, _options = {}) {
+    const entryByName = new Map(entries.map((entry) => [extractStringField(entry, "name"), entry]));
+    const listingMayBeIncomplete = entries.length >= CONTENTS_API_DIRECTORY_LISTING_CAP;
+    for (const file of dirFiles) {
+      const entry = entryByName.get(splitRepoPath(file.path).name);
+      const resolved = entry || !listingMayBeIncomplete ? stateFromListingEntry(file.path, entry) : await checkOneFileExistence(target, branch, file.path);
+      if (!resolved.ok) return resolved;
+      stateByPath.set(file.path, resolved.state);
+    }
+    return { ok: true };
+  }
+
+  /** @param {{ target: Target, branch: string, dir: string, dirFiles: WriteFile[], stateByPath: Map<string, { path: string, exists: boolean }> }} required */
+  async function checkDirectoryFileExistence({ target, branch, dir, dirFiles, stateByPath }, _options = {}) {
+    const directoryPath = dir ? `/${encPath(dir)}` : "";
+    const listUrl = `${repoPathOf(target)}/contents${directoryPath}?ref=${enc(branch)}`;
+    const listResult = await git.getJson(target, listUrl, `GitHub directory lookup of '${dir}' failed`);
+    if (!listResult.ok) return listResult;
+    if (!listResult.found) {
+      for (const file of dirFiles) stateByPath.set(file.path, { path: file.path, exists: false });
+      return { ok: true };
+    }
+    const entries = listResult.json;
+    if (!Array.isArray(entries)) {
+      return { ok: false, code: PROVIDER_ERROR, message: `'${dir}' is a file on the branch, not a directory` };
+    }
+    return resolveDirectoryFileStates({ target, branch, dirFiles, entries, stateByPath });
+  }
+
+  /** One directory listing per distinct parent directory, falling back to a per-file lookup only when
+   *  a listing may be truncated. @param {Target} target @param {string} branch @param {readonly WriteFile[]} files */
+  async function checkFileExistence(target, branch, files) {
+    const filesByDir = groupWriteFilesByDirectory({ files });
+
+    /** @type {Map<string, { path: string, exists: boolean }>} */
+    const stateByPath = new Map();
+    for (const [dir, dirFiles] of filesByDir) {
+      const resolved = await checkDirectoryFileExistence({ target, branch, dir, dirFiles, stateByPath });
+      if (!resolved.ok) return resolved;
+    }
+    return { ok: true, fileStates: files.map((file) => stateByPath.get(file.path)) };
+  }
+
+  /** @param {Target & { branch: string, files: readonly WriteFile[] }} input */
+  async function planFileWrite(input) {
+    const repoPath = repoPathOf(input);
+    const refJson = await git.getJson(input, `${repoPath}/git/ref/heads/${encPath(input.branch)}`, "GitHub branch lookup failed");
+    if (!refJson.ok) return refJson;
+    if (!refJson.found) return { ok: false, code: "branch-not-found", message: `branch '${input.branch}' does not exist in ${input.owner}/${input.repo}` };
+    const parentCommitSha = extractStringField(refJson.json.object, "sha");
+    if (!parentCommitSha) return { ok: false, code: PROVIDER_ERROR, message: "GitHub branch lookup response did not include a sha" };
+
+    const commitJson = await git.getJson(input, `${repoPath}/git/commits/${enc(parentCommitSha)}`, "GitHub parent-commit lookup failed");
+    if (!commitJson.ok) return commitJson;
+    if (!commitJson.found) return { ok: false, code: PROVIDER_ERROR, message: "GitHub parent-commit lookup returned 404 for a sha this call just resolved" };
+    const baseTreeSha = extractStringField(commitJson.json.tree, "sha");
+    if (!baseTreeSha) return { ok: false, code: PROVIDER_ERROR, message: "GitHub parent-commit response did not include a tree sha" };
+
+    const existence = await checkFileExistence(input, input.branch, input.files);
+    if (!existence.ok) return existence;
+    return { ok: true, plan: { parentCommitSha, baseTreeSha, fileStates: existence.fileStates } };
+  }
+
+  /** @param {{ target: Target, treeSha: string, trees: Map<string, any[]> }} required */
+  async function readModeTree({ target, treeSha, trees }, _options = {}) {
+    let tree = trees.get(treeSha);
+    if (!tree) {
+      const result = await git.getJson(target, `${repoPathOf(target)}/git/trees/${enc(treeSha)}`, "GitHub file-mode lookup failed");
+      if (!result.ok) return result;
+      if (!result.found || !Array.isArray(result.json.tree) || result.json.truncated === true) {
+        return { ok: false, code: PROVIDER_ERROR, message: "GitHub returned an incomplete tree — refusing to guess file modes" };
+      }
+      tree = result.json.tree;
+      trees.set(treeSha, tree);
+    }
+    return { ok: true, tree };
+  }
+
+  /** @param {{ entry: any }} required */
+  function isModeDirectory({ entry }, _options = {}) {
+    return entry.type === "tree" && typeof entry.sha === "string" && !!entry.sha;
+  }
+
+  /** @param {{ entry: any, path: string }} required */
+  function modeFromBlobEntry({ entry, path }, _options = {}) {
+    if (entry.type !== "blob" || !["100644", "100755"].includes(entry.mode)) return notRegularFileFailure(path);
+    return { ok: true, mode: entry.mode };
+  }
+
+  /** @param {{ target: Target, baseTreeSha: string, file: WriteFile, trees: Map<string, any[]> }} required */
+  async function readFileMode({ target, baseTreeSha, file, trees }, _options = {}) {
+    let treeSha = baseTreeSha;
+    const segments = file.path.split("/");
+    for (let index = 0; index < segments.length; index++) {
+      const loaded = await readModeTree({ target, treeSha, trees });
+      if (!loaded.ok) return loaded;
+      const entry = loaded.tree.find(entry => entry.path === segments[index]);
+      if (!entry) break;
+      if (index === segments.length - 1) return modeFromBlobEntry({ entry, path: file.path });
+      if (!isModeDirectory({ entry })) return notRegularFileFailure(file.path);
+      treeSha = entry.sha;
+    }
+    return { ok: true, mode: "100644" };
+  }
+
+  /** Read each directory of the CONFIRMED tree, never the mutable branch. Non-recursive
+   * lookups avoid GitHub's recursive-tree truncation limit and preserve executable blobs.
+   * @param {{ target: Target, baseTreeSha: string, files: readonly WriteFile[] }} required */
+  async function readFileModes({ target, baseTreeSha, files }) {
+    /** @type {Map<string, any[]>} */
+    const trees = new Map();
+    /** @type {Map<string, string>} */
+    const modes = new Map();
+    for (const file of files) {
+      const result = await readFileMode({ target, baseTreeSha, file, trees });
+      if (!result.ok) return result;
+      modes.set(file.path, result.mode);
+    }
+    return { ok: true, modes };
+  }
+
+  /** @param {{ input: Target & { files: readonly WriteFile[] }, modes: Map<string, string> }} required */
+  async function buildWriteBlobEntries({ input, modes }, _options = {}) {
+    /** @type {Map<string, string>} */
+    const blobShaByHash = new Map();
+    /** @type {Record<string, unknown>[]} */
+    const entries = [];
+    for (const file of input.files) {
+      const hash = createHash("sha256").update(Buffer.from(file.content, "utf8")).digest("hex");
+      let blobSha = blobShaByHash.get(hash);
+      if (!blobSha) {
+        const blobResult = await git.createBlob(input, file.content);
+        if (!blobResult.ok) return blobResult;
+        blobSha = blobResult.sha;
+        blobShaByHash.set(hash, blobSha);
+      }
+      entries.push({ path: file.path, mode: modes.get(file.path), type: "blob", sha: blobSha });
+    }
+    return { ok: true, entries };
+  }
+
+  /**
+   * @param {Target & { branch: string, commitMessage: string, files: readonly WriteFile[] }} input
+   * @param {{ parentCommitSha: string, baseTreeSha: string }} plan
+   */
+  async function commitFiles(input, plan) {
+    const repoPath = repoPathOf(input);
+    const fileModes = await readFileModes({ target: input, baseTreeSha: plan.baseTreeSha, files: input.files });
+    if (!fileModes.ok) return fileModes;
+    const blobs = await buildWriteBlobEntries({ input, modes: fileModes.modes });
+    if (!blobs.ok) return blobs;
+
+    const treeResult = await git.postJson(input, `${repoPath}/git/trees`, { tree: blobs.entries, base_tree: plan.baseTreeSha }, "GitHub tree creation failed");
+    if (!treeResult.ok) return treeResult;
+    const newTreeSha = extractStringField(treeResult.json, "sha");
+    if (!newTreeSha) return { ok: false, code: PROVIDER_ERROR, message: "GitHub tree creation response did not include a sha" };
+
+    const commitResult = await git.postJson(
+      input,
+      `${repoPath}/git/commits`,
+      { message: input.commitMessage, tree: newTreeSha, parents: [plan.parentCommitSha] },
+      "GitHub commit creation failed"
+    );
+    if (!commitResult.ok) return commitResult;
+    const commitSha = extractStringField(commitResult.json, "sha");
+    if (!commitSha) return { ok: false, code: PROVIDER_ERROR, message: "GitHub commit creation response did not include a sha" };
+
+    const refResult = await git.updateRef(input, input.branch, commitSha);
+    if (!refResult.ok) return refResult;
+    return { ok: true, commitSha, commitUrl: `https://github.com/${input.owner}/${input.repo}/commit/${commitSha}` };
+  }
+
+  return { planFileWrite, commitFiles };
+}

package/github/tovu-deploy-ops.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "platforms": [
+    {
+      "id": "github-actions",
+      "label": "GitHub Actions",
+      "module": "deploy-ops/github-actions.mjs",
+      "hosts": [
+        "api.github.com"
+      ]
+    }
+  ]
+}

package/github/tovu-source-control.json

@@ -0,0 +1,117 @@
+{
+  "schemaVersion": 1,
+  "providers": [
+    {
+      "id": "github",
+      "label": "GitHub",
+      "apiOrigin": "https://api.github.com",
+      "maxFileBytes": 104857600,
+      "reservedPaths": [
+        ".github"
+      ],
+      "workflowPaths": [
+        ".github/workflows"
+      ],
+      "module": "source-control/github.mjs",
+      "credential": {
+        "tokenPageUrl": "https://github.com/settings/personal-access-tokens/new",
+        "help": "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.",
+        "tokenField": "token",
+        "fields": [
+          {
+            "name": "token",
+            "label": "Access token",
+            "required": true,
+            "secret": true
+          }
+        ]
+      },
+      "i18n": {
+        "es": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "Necesita un token de acceso personal de grano fino limitado a este repositorio, con el permiso Contents configurado en Read and write. Un token clásico con el permiso \"repo\" también funciona, pero alcanza todos los repositorios a los que esta cuenta tiene acceso: se prefiere el token de grano fino.",
+          "Access token": "Token de acceso"
+        },
+        "id": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "Memerlukan token akses pribadi fine-grained yang dibatasi hanya untuk repositori ini, dengan izin Contents diatur ke Read and write. Token klasik dengan cakupan \"repo\" juga berfungsi, tetapi menjangkau setiap repositori yang dapat diakses akun ini — token fine-grained lebih disarankan.",
+          "Access token": "Token akses"
+        },
+        "de": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "Benötigt ein fein abgestuftes Personal Access Token, das auf genau dieses Repository beschränkt ist, mit der Berechtigung Contents auf Read and write gesetzt. Ein klassisches Token mit dem Bereich \"repo\" funktioniert ebenfalls, erreicht aber jedes Repository, auf das dieses Konto Zugriff hat — das fein abgestufte Token wird bevorzugt.",
+          "Access token": "Zugriffstoken"
+        },
+        "zh-CN": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "需要仅限于此仓库的 fine-grained 个人访问令牌，并将 Contents 权限设置为 Read and write。具有 \"repo\" 范围的经典令牌也可以使用，但它会涉及此账户可访问的每个仓库 — 建议优先使用 fine-grained 令牌。",
+          "Access token": "访问令牌"
+        },
+        "zh-TW": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "需要僅限於此儲存庫的 fine-grained 個人存取權杖，並將 Contents 權限設為 Read and write。具有 \"repo\" 範圍的傳統權杖也可使用，但會涉及此帳戶可存取的每個儲存庫 — 建議優先使用 fine-grained 權杖。",
+          "Access token": "存取權杖"
+        },
+        "pt-BR": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "Precisa de um token de acesso pessoal refinado, restrito apenas a este repositório, com a permissão Contents definida como Read and write. Um token clássico com o escopo \"repo\" também funciona, mas alcança todos os repositórios aos quais esta conta tem acesso — prefira o token refinado.",
+          "Access token": "Token de acesso"
+        },
+        "ru": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "Требуется детализированный (fine-grained) персональный токен доступа, ограниченный только этим репозиторием, с разрешением Contents, установленным на Read and write. Классический токен с областью действия \"repo\" тоже подойдёт, но он охватывает каждый репозиторий, доступный этой учётной записи — предпочтителен детализированный токен.",
+          "Access token": "Токен доступа"
+        },
+        "fa": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "به یک توکن دسترسی شخصی fine-grained نیاز دارد که فقط محدود به این مخزن باشد، با مجوز Contents تنظیم‌شده روی Read and write. یک توکن کلاسیک با دامنه \"repo\" هم کار می‌کند، اما به هر مخزنی که این حساب به آن دسترسی دارد می‌رسد — توکن fine-grained ترجیح داده می‌شود.",
+          "Access token": "توکن دسترسی"
+        },
+        "ar": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "يتطلب رمز وصول شخصي دقيق التحبب (fine-grained) مقتصرًا على هذا المستودع فقط، بصلاحية Contents مضبوطة على Read and write. يعمل أيضًا رمز كلاسيكي بنطاق \"repo\"، لكنه يصل إلى كل مستودع يمكن لهذا الحساب الوصول إليه — يُفضَّل الرمز دقيق التحبب.",
+          "Access token": "رمز الوصول"
+        },
+        "ja": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "このリポジトリのみに限定され、Contents権限をRead and writeに設定したfine-grainedパーソナルアクセストークンが必要です。\"repo\" スコープを持つクラシックトークンも機能しますが、このアカウントがアクセスできるすべてのリポジトリに及びます — fine-grainedトークンを推奨します。",
+          "Access token": "アクセストークン"
+        },
+        "ko": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "이 저장소로만 범위가 제한되고 Contents 권한이 Read and write로 설정된 fine-grained 개인 액세스 토큰이 필요합니다. \"repo\" 범위를 가진 클래식 토큰도 작동하지만 이 계정이 액세스할 수 있는 모든 저장소에 미칩니다 — fine-grained 토큰을 권장합니다.",
+          "Access token": "액세스 토큰"
+        },
+        "pl": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "Wymaga precyzyjnego osobistego tokena dostępu ograniczonego tylko do tego repozytorium, z uprawnieniem Contents ustawionym na Read and write. Token klasyczny z zakresem \"repo\" również działa, ale obejmuje każde repozytorium dostępne dla tego konta — preferowany jest token precyzyjny.",
+          "Access token": "Token dostępu"
+        },
+        "hu": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "Finomhangolt személyes hozzáférési token szükséges, amely csak erre az egy tárolóra korlátozódik, a Contents jogosultsággal Read and write értékre állítva. A klasszikus token a \"repo\" hatókörrel is működik, de minden tárolót elér, amelyhez ez a fiók hozzáfér — a finomhangolt token az előnyben részesített.",
+          "Access token": "Hozzáférési token"
+        },
+        "fr": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "Nécessite un jeton d'accès personnel fin limité à ce seul dépôt, avec la permission Contents définie sur Read and write. Un jeton classique avec le champ d'application \"repo\" fonctionne aussi, mais atteint tous les dépôts accessibles à ce compte — préférez le jeton fin.",
+          "Access token": "Jeton d'accès"
+        },
+        "uk": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "Потрібен деталізований (fine-grained) персональний токен доступу, обмежений лише цим репозиторієм, із дозволом Contents, встановленим на Read and write. Класичний токен з областю дії \"repo\" також працює, але охоплює кожен репозиторій, доступний цьому обліковому запису — деталізований токен є пріоритетним.",
+          "Access token": "Токен доступу"
+        },
+        "tr": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "Yalnızca bu depoyla sınırlı, Contents izni Read and write olarak ayarlanmış ince taneli (fine-grained) bir kişisel erişim jetonu gerekir. \"repo\" kapsamına sahip klasik bir jeton da çalışır, ancak bu hesabın erişebildiği her depoya ulaşır — ince taneli jeton tercih edilmelidir.",
+          "Access token": "Erişim jetonu"
+        },
+        "th": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "ต้องใช้โทเคนการเข้าถึงส่วนบุคคลแบบ fine-grained ที่จำกัดเฉพาะที่เก็บนี้เท่านั้น โดยตั้งค่าสิทธิ์ Contents เป็น Read and write โทเคนแบบคลาสสิกที่มีขอบเขต \"repo\" ก็ใช้งานได้เช่นกัน แต่จะเข้าถึงทุกที่เก็บที่บัญชีนี้เข้าถึงได้ — แนะนำให้ใช้โทเคนแบบ fine-grained",
+          "Access token": "โทเคนการเข้าถึง"
+        },
+        "it": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "Richiede un token di accesso personale granulare limitato a questo solo repository, con il permesso Contents impostato su Read and write. Funziona anche un token classico con l'ambito \"repo\", ma raggiunge ogni repository a cui questo account ha accesso — preferisci il token granulare.",
+          "Access token": "Token di accesso"
+        },
+        "hi": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "केवल इस रिपॉज़िटरी तक सीमित एक fine-grained व्यक्तिगत एक्सेस टोकन चाहिए, जिसमें Contents अनुमति Read and write पर सेट हो। \"repo\" स्कोप वाला क्लासिक टोकन भी काम करता है, लेकिन वह इस खाते द्वारा एक्सेस की जा सकने वाली हर रिपॉज़िटरी तक पहुंचता है — fine-grained टोकन को प्राथमिकता दें।",
+          "Access token": "एक्सेस टोकन"
+        },
+        "ur": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "صرف اسی ریپوزٹری تک محدود ایک fine-grained پرسنل ایکسیس ٹوکن درکار ہے، جس میں Contents اجازت Read and write پر سیٹ ہو۔ \"repo\" اسکوپ کے ساتھ کلاسک ٹوکن بھی کام کرتا ہے، لیکن یہ اس اکاؤنٹ کی رسائی میں آنے والی ہر ریپوزٹری تک پہنچتا ہے — fine-grained ٹوکن کو ترجیح دی جاتی ہے۔",
+          "Access token": "رسائی ٹوکن"
+        },
+        "bn": {
+          "Needs a fine-grained personal access token scoped to just this repository, with Contents permission set to Read and write. A classic token with the \"repo\" scope also works, but reaches every repository this account can access — prefer the fine-grained token.": "শুধুমাত্র এই রিপোজিটরির মধ্যে সীমাবদ্ধ একটি fine-grained পার্সোনাল অ্যাক্সেস টোকেন প্রয়োজন, যেখানে Contents অনুমতি Read and write-এ সেট থাকে। \"repo\" স্কোপসহ একটি ক্লাসিক টোকেনও কাজ করে, তবে এটি এই অ্যাকাউন্টের অ্যাক্সেসযোগ্য প্রতিটি রিপোজিটরিতে পৌঁছায় — fine-grained টোকেন অগ্রাধিকারযোগ্য।",
+          "Access token": "অ্যাক্সেস টোকেন"
+        }
+      }
+    }
+  ]
+}

package/github-pages/NOTES.md

@@ -0,0 +1,19 @@
+# GitHub Pages — implementation notes
+
+Host-specific notes moved out of the first host's core comments (2026-10-22, vendor-to-plugins). Core describes these
+behaviours generically; the vendor detail lives here.
+
+- **Base path.** A GitHub Pages *project* site is served at `https://<owner>.github.io/<repo>/`, not the
+  domain root, so a publish rewrites the export for `/<repo>` (core: `site-export/site-exporter.ts`
+  base-path support; `static-publish/types.ts` echoes the base path back).
+- **Publish history.** `owner`/`repo`/`branch`/`commitSha` in core's publish-history rows are this
+  target's fields; its `deploymentId` is the same commit sha `commitSha` carries.
+- **Account label.** The verified account label is the GitHub `login`; the assistant defaults a GitHub
+  Pages publish's `owner` to it instead of guessing (2026-08-16, Defect 1).
+- **Credentials.** A bare token is never enough: `owner`/`repo` are required.
+- **Security headers.** GitHub Pages has no header config file, so an export carries only what HTML can
+  say (core `withSecurityMeta`). Its 404 convention is `404.html` at the output root.
+- **Deploy poll.** A publish blocks on the Pages build poll (up to about a minute), which is why the
+  admin publish route is trigger+status.
+- **Default branch.** An omitted `config.branch` publishes to `gh-pages`; core's `publish_history.branch`
+  column records the branch actually used.

package/github-pages/mcp.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {}
+}