@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/github/skills/github/references/repo-files.md

@@ -0,0 +1,135 @@
+# Writing and updating files in a repository
+
+`custom_credential_write_files` is the only way to put a file in a GitHub repository from here.
+Never shell out to `git`, and never hand-roll the Contents API through
+`custom_credential_make_request` — this tool exists so you do not have to, and it carries a human
+confirmation the raw API call would skip.
+
+---
+
+## The call
+
+```
+custom_credential_write_files({
+  label: "github",
+  owner: "<owner>",
+  repo: "<repo>",
+  branch: "<branch>",
+  commitMessage: "<message>",
+  files: [
+    { path: "path/relative/to/repo/root", content: "<the file's exact full text>" }
+  ]
+})
+```
+
+**One call does everything.** It resolves the branch's real current state, raises an interactive
+confirmation, and **waits** — it does not return until the human answers. There is no second call
+to make, and calling again while one is pending raises a second, separate dialog rather than
+answering the first.
+
+On confirm, every file lands in **one atomic commit**, never one commit per file, built directly on
+the branch's current tree. Nothing else on the branch is touched, moved, or deleted.
+
+### What comes back
+
+| Result | Meaning |
+|---|---|
+| `{ executed: true, commitSha, commitUrl, filesWritten }` | Written. Report the SHA and URL — do not describe what you believe happened. |
+| `{ executed: false, cancelled: true }` | The human declined. Nothing was written. This is a real outcome; say so and stop. |
+| `{ executed: false, cancelled: false, reason: "expired" \| "abandoned" }` | Nobody answered in time, or the run ended first. Nothing was written. |
+| `{ executed: false, cancelled: false, reason: "error", message }` | GitHub rejected the write, or the branch moved since this call started. Nothing was written — **never a half-commit.** Retry fresh; never assume partial success. |
+
+A branch that moved mid-write is refused rather than force-pushed. That is deliberate: the loser of
+a race is told, never silently overwritten. Re-read the file, rebuild your content on what is now
+there, and call again.
+
+---
+
+## The rules this tool enforces for you
+
+**The branch must already exist.** This tool never creates one, and it does **not** default to the
+repository's default branch. Name it explicitly. If you are unsure what exists, look it up
+(`GET /repos/{owner}/{repo}/branches`) or ask — a wrong branch name is refused before anything is
+written, but a *valid-but-wrong* branch name is not.
+
+**Paths are repository-relative.** Never absolute, never containing a `..` segment, never naming or
+nesting under `.git`. Refused before any confirmation or network call.
+
+**Limits:** at most 25 files per call, 1 MiB per file, 4 MiB total, no two files naming the same
+path. Exceeding any of these is a refusal with a reason that names which one.
+
+Every refusal above happens **before** the dialog is raised and before any network call. So a
+refusal costs the human nothing — but it also means a refusal is a real signal to read, not a
+transient error to retry.
+
+---
+
+## Updating a file that already exists
+
+This is where the damage happens. Read `Rule 4` in `SKILL.md` first; this is the procedure it
+requires.
+
+**`custom_credential_write_files` replaces a file's entire content. It does not patch.** Whatever
+you do not carry forward is gone.
+
+1. **Read what is actually there.**
+   ```
+   custom_credential_make_request({
+     label: "github",
+     method: "GET",
+     url: "https://api.github.com/repos/<owner>/<repo>/contents/<path>?ref=<branch>"
+   })
+   ```
+   The response's `content` is base64. For a large file, `Accept: application/vnd.github.raw` gets
+   you the text directly.
+
+2. **Build the new content from that**, never from memory and never from a template you assume
+   matches what is on the branch.
+
+3. **State every line you removed.** Not "updated the workflow" — the actual removals. A dropped
+   build flag reads as nothing at all in a summary that only lists what was added.
+
+The confirmation dialog labels each path a **create** (new path) or an **update** (already exists
+on the branch), resolved against the branch's real state, never guessed. **An "update" label is
+your warning** that a full-content replacement is about to happen. If you expected a create and see
+an update, stop: something is already at that path and you are about to overwrite it.
+
+---
+
+## Workflow files get an extra warning, and they have earned it
+
+If any path is inside `.github/workflows/`, the confirmation dialog carries a **second, more
+prominent warning** naming every such path, because a workflow file controls what code runs
+automatically on every future push to that repository.
+
+Do not treat that warning as noise to talk the human past. When you write a workflow:
+
+- **Say what the workflow will do**, in plain terms, before they confirm — what it triggers on,
+  what it runs, what credentials it will use.
+- **Name every secret it references**, so they can confirm each one is actually set. See
+  `auth-and-tokens.md`: setting them is their step, always.
+- **Do not silently regenerate a workflow from a template** when one already exists. That is the
+  exact shape of the force-push that dropped two build arguments and broke two deploys.
+
+---
+
+## Templates and placeholders
+
+A plugin that ships a template file expects it to be read off disk and written into the human's
+repository, with every placeholder replaced.
+
+After you write, **re-read what you wrote and confirm no placeholder marker survived.** A leftover
+placeholder is, at best, a confusing failure — and at worst a run that succeeds against the wrong
+target. Then **say which values you left at a default**: an unverified default the human never
+chose is a fact they need, not an implementation detail.
+
+---
+
+## What is happening underneath
+
+Worth knowing because it explains the guarantees above: one blob per distinct file content, one
+tree built on top of the branch's current tree (`base_tree`, always — so every path you did not
+name is inherited unchanged), one commit object, and one **non-force** ref update.
+
+That last step is the only irreversible one, and GitHub itself rejects it with 422 if the branch
+moved. Which is why "diverged" is a refusal here rather than a lost commit.

package/github/skills/github/references/site-backup.md

@@ -0,0 +1,159 @@
+# Backing up the site itself to a private repository
+
+`site_backup_plan` and `site_backup_push` copy **this site** into one folder of a private GitHub
+repository, in one commit: its database, media, themes, installed plugins and skills, and settings.
+Both are native host tools. They push with the same saved credential `custom_credential_*` uses:
+the plugin’s card: `credential_save {kind:"plugin-provider",target:"github"}`.
+
+---
+
+## Which tool
+
+Three tools can put the site's things in a repository. They do three different jobs.
+
+| The human wants… | Use |
+|---|---|
+| A copy of the site itself (content, members, media, settings) to keep or restore from | `site_backup_plan`, then `site_backup_push` |
+| The site's **rendered** HTML published into a repository (Pages, a static host) | `source_control_execute_commit` — see `source-control.md` |
+| A few named files: a config, a workflow, a script | `custom_credential_write_files` — see `repo-files.md` |
+
+The rendered export holds no database. It is what the site *looks like*, not the site, and nothing
+can be restored from it. Going the other way, `custom_credential_write_files` cannot carry a backup:
+25 files and 1 MiB each, and every byte would pass through your context. The database holds members
+and admin accounts, so that is not a size problem. It is a reason never to try.
+
+---
+
+## Plan, then push
+
+```
+site_backup_plan({
+  owner: "<owner>",
+  repo: "<repo>",
+  // all optional:
+  credential: "github",          // needed only when more than one saved credential points at GitHub
+  branch: "<branch>",            // default: the repository's default branch; must already exist
+  folder: "<folder>",            // default: the site's folder name; replaced as a whole on each backup
+  include: { media: false },     // database, media, themes, plugins, settings: each defaults to true
+  commitMessage: "<message>"     // default: the host's backup message with the site name and time
+})
+```
+
+**The plan writes nothing.** It checks the credential, that the repository is private, that the
+credential can push, and that the branch exists. Then it snapshots the database, lists every file
+with its size, and checks the limits. It returns a `planId`, which is **single-use and valid for
+10 minutes**, plus everything the human needs to see.
+
+**Show the human the plan before you push:** repository, branch, folder, and whether that folder
+already exists (it will be replaced). Also what is included, the file count and total size, and
+anything in `skipped` or `notes`. Then:
+
+```
+site_backup_push({ planId: "<planId>" })
+```
+
+**No dialog: the push starts at once.** The plan you showed is the human's review, so show it
+first. The push re-checks the repository (still private, branch not moved, files unchanged) before
+the first upload.
+
+A large site can take longer than one call. The push waits about 4 minutes; if the upload is still
+running then, it returns `{ pushed: false, cancelled: false, inProgress: true, planId, progress,
+message }`, where `progress` is `{ filesDone, filesTotal, bytesDone, bytesTotal }`. Tell the human
+how far it got, then **call `site_backup_push` again with the same `planId`** to keep waiting. That
+does not start a second upload, and nothing is committed until every file is up: the backup is
+still one commit. Keep re-calling while it answers `inProgress`.
+
+The `planId` is used up when its push finishes, whatever the outcome. After a failure, a second
+attempt starts with a fresh `site_backup_plan`. A server restart drops a running push; nothing is
+committed, so plan again.
+
+GitHub hiccups (a timeout, a 5xx, a rate limit) are retried inside the push with backoff, up to 5
+tries per request. A failure that reaches you is final, and its message names the file it stopped at.
+
+---
+
+## Private repositories only
+
+A public or internal repository is refused (`REPOSITORY_NOT_PRIVATE`) at plan time, and checked
+again at push time. The database holds members, form submissions, admin accounts and saved
+credentials. That is not a warning to talk the human past. Never suggest a public repository.
+
+The repository must also **already have one commit**. An empty repository is refused
+(`REPOSITORY_EMPTY`). The fix is on GitHub: add a README, then plan again.
+
+---
+
+## What the push returns
+
+| Result | Meaning |
+|---|---|
+| `{ pushed: true, commitSha, commitUrl, repository, branch, folder, filesWritten, totalBytes }` | Written. Report the SHA and URL. |
+| `{ pushed: false, cancelled: false, inProgress: true, planId, progress, message }` | Still uploading. Report the progress, then call `site_backup_push` again with the same `planId`. |
+| `{ pushed: false, cancelled: false, reason: "abandoned" }` | The run ended while the push was waiting. The upload stopped and nothing was committed. Plan again. |
+| `{ pushed: false, cancelled: false, code, message }` | Refused. See the codes below. Nothing was written. |
+
+---
+
+## Limits
+
+- **100 MiB per file.** That is GitHub's own limit. A media, theme or plugin file over it is **left
+  out** of the backup and listed in the plan's `skipped` with its size, **never truncated or
+  split**; tell the human which files those are. A database snapshot over it fails the plan
+  (`LIMIT_EXCEEDED`), because a backup without its database is not a backup.
+- **At most 3000 files and 1 GiB in total.**
+
+Every limit is checked by the plan, before anything is uploaded (`LIMIT_EXCEEDED`). Relay the
+message. The fix is to remove or shrink the named files, or leave out the scope that holds them.
+Media usually holds the most files and the most bytes. A backup without media is a different
+backup, so say plainly that media would be left out and get the human's agreement before you plan
+with `include: { media: false }`.
+
+When media lives in object storage rather than on this server, `notes` says so: those files are
+not in the backup, though the database still lists every media item. Pass that on.
+
+**Never in a backup, by design:** chat history and chat attachments, the rendered export, MCP
+server config files (they can hold tokens), plugin OAuth data, and `.git`. Symbolic links are never
+followed; each is listed in `skipped`. The Site key is not in the backup either. The saved
+credentials inside the database are encrypted with it, so the human needs to keep it safe on their
+own.
+
+---
+
+## The codes, and what to tell the human
+
+| Code | What it means | What to tell them |
+|---|---|---|
+| `CREDENTIAL_NOT_FOUND` | No saved credential has that label, or none points at `https://api.github.com` | Open `credential_save {kind:"plugin-provider",target:"github"}`, or name the right label with `credential`. Never have a token typed into the chat. |
+| `CREDENTIAL_AMBIGUOUS` | More than one saved credential points at GitHub | Ask which one, then plan with `credential` |
+| `CREDENTIAL_UNREADABLE` | The credential **is saved** but this server cannot decrypt it | Not a bad GitHub token, so replacing it is the wrong first move. It starts with the **Site key**, and the message names which case applies. No Site key: start the host with it (the host guidance names how). Malformed: fix it in the host's Site key setting. A different Site key from the one the credential was saved under: check that setting, or save the credential again. |
+| `REPOSITORY_NOT_FOUND` | This credential cannot see that `owner/repo` | Confirm the names, then the token's repository access |
+| `REPOSITORY_NOT_PRIVATE` | Public or internal | Back up to a private repository. Never offer a public one |
+| `NO_PUSH_PERMISSION` | The token can read the repository but not push to it | The token needs write access to the repository's contents. That change is made on GitHub. |
+| `REPOSITORY_EMPTY` | No commits yet | Add a first commit (a README) on GitHub, then plan again |
+| `BRANCH_NOT_FOUND` | The named branch does not exist | Name an existing branch, or leave `branch` out for the default |
+| `FOLDER_IS_FILE` | The folder's path is a file on that branch | Choose another `folder` |
+| `LIMIT_EXCEEDED` | Over a limit above | See **Limits** |
+| `DATABASE_SNAPSHOT_FAILED` | The host could not take a consistent copy of the database | A host-side problem, not a GitHub one. Report it |
+| `PLAN_NOT_FOUND` / `PLAN_EXPIRED` | The `planId` was already used, is over 10 minutes old, or a server restart dropped it | Plan again |
+| `PLAN_STALE` | A file on the site changed after the plan | Plan again, and show the new plan |
+| `DIVERGED_BRANCH` | Someone pushed to the branch after the plan. Nothing was written | Plan again, and show the new plan |
+| `PROVIDER_ERROR` | GitHub rejected a request | The message names what went wrong. Pass it on |
+| `NETWORK_UNREACHABLE` | GitHub could not be reached, even after retries | Says nothing about the credential. Try again later, from a fresh plan |
+| `UNAVAILABLE` | This runtime has no site folder on disk | A backup cannot be made from here |
+| `SITE_BACKUP_FORBIDDEN` | The person lacks the backup or credential-write permission | An admin grants it. Nothing was touched |
+| `SITE_BACKUP_INVALID_INPUT` | A field was malformed | The message names the field. Fix it and plan again |
+
+---
+
+## Never force
+
+`site_backup_push` has no force option, and every write it makes is a **non-force** ref update on
+top of the exact commit the plan saw. That is why `DIVERGED_BRANCH` is a refusal, not a lost commit.
+
+So when a push is refused because the world moved (`PLAN_EXPIRED`, `PLAN_STALE`,
+`DIVERGED_BRANCH`), the answer is always **plan again** and show the human the new plan. Never force
+the branch through `custom_credential_make_request`, never delete and recreate the branch, and never
+rebuild the backup out of `custom_credential_write_files` calls. Each of these would throw away
+someone else's commit, or push content the human never reviewed.
+
+There is no restore tool unless the host guidance names one. Do not promise one.

package/github/skills/github/references/source-control.md

@@ -0,0 +1,123 @@
+# Source Control: publishing the site's export, and why it is not a file write
+
+The host has a second, narrower pair of GitHub tools. They are easy to reach for by mistake, because
+their names sound general and they are not.
+
+- `source_control_get_capabilities` — read-only. Which providers have a saved connection.
+- `source_control_execute_commit` — commits the site's **rendered static export** to a repository.
+
+Neither is a way to put a file in a repository. That is `custom_credential_write_files`.
+
+---
+
+## The distinction that actually matters
+
+**App source is not a rendered export.**
+
+| | `custom_credential_write_files` | `source_control_execute_commit` |
+|---|---|---|
+| What it commits | Exactly the files you name, verbatim | A **fresh static copy of the active theme** — generated HTML and assets — that it runs itself |
+| Where the content comes from | You | The host's exporter. You do not supply file content at all |
+| Deletes anything? | **Never.** It writes named paths and touches nothing else | **Yes.** Unchanged stale files recorded by this destination’s manifest are removed; human-edited stale files are preserved |
+| Creates a branch? | No — the branch must already exist | Yes, if the named branch does not exist |
+| Which credential | The Access Tokens page's saved custom provider (`label`) | The **Source Control** credential, falling back to a saved `github` API key only when no explicit connection exists |
+| Repository layout | Wherever you name | Repository root by default, or the optional `folder` the user named |
+
+A container build needs **app source** — the repository's real code, its Dockerfile, its lockfiles.
+A rendered export is the *output* of running that code, and a build handed one either fails or,
+worse, succeeds and ships a static site where a server was expected.
+
+So when a task says "push the app to a repo so CI can build it", that is **not**
+`source_control_execute_commit`. It is either app source the human already has in a repository, or
+specific files you write with `custom_credential_write_files`. Conflating the two wastes a whole
+build cycle before anyone notices what was actually committed.
+
+`source_control_execute_commit` is for one job: **publishing the site's rendered output** into a
+repository as a portable static copy. Hosting this layout requires configuration; use the static-publish flow for hosted deployment.
+
+---
+
+## Two credential stores, not one
+
+This surprises people and is worth stating flatly.
+
+- `custom_credential_*` reads the **Access Tokens** page's *Add custom provider* table. That is
+  where a credential labelled `github` lives.
+- `source_control_*` reads a **separate** table, connected with `credential_save {kind:"plugin-provider",target:"github-source-control"}`.
+
+An explicit Source Control connection takes priority. If none exists, `source_control_execute_commit`
+can use the saved `github` API key; capabilities identify this as `credentialSource:"saved-api-key"`.
+A connected Source Control provider does not give `custom_credential_make_request` a label to use.
+
+So: call `source_control_get_capabilities` before you promise a human anything about committing an
+export. And never ask a human to paste a token into chat to bridge the gap — open the plugin’s source-control card, which saves it encrypted through that owner.
+
+---
+
+## Using `source_control_execute_commit`
+
+```
+source_control_execute_commit({
+  provider: "github",
+  owner: "<owner>",
+  repo: "<repo>",
+  commitMessage: "<message>",
+  branch: "<branch>",   // optional — the repository's default branch when omitted
+  folder: "static_sites", // optional — empty or omitted means repository root
+  dryRun: true
+})
+```
+
+Use the folder the user named. If the destination is unclear, ask “repository root or which folder?”.
+Run a dry run first. Folder commits require `supportsFolder:true` from capabilities; an older
+provider is refused rather than allowed to ignore the destination.
+
+The package contains `Open website.html`, `README.txt`, `media/` and `sites/<theme>/`.
+The README is deterministic so unchanged re-commits can report `NO_CHANGES`. Open the launcher to
+view the copy. A theme directory needs its sibling `media/`; there is no generated root `index.html`.
+Existing GitHub Pages/root-hosting URLs can break with this layout. The host's other static
+publishing and export commands retain their current output.
+
+Ownership is recorded at `<folder>/.tovu/managed-files.json`. Changing folders creates an independent
+destination, preserving the previous root export and sibling folders. A folder commit never reads
+the root manifest as a fallback.
+
+Only `provider: "github"` is accepted. A gitlab or bitbucket credential can be **saved** and is
+reported honestly by `source_control_get_capabilities` with `commitSupported: false` — committing
+to either is not implemented. Say that plainly rather than letting a human discover it from a
+failed attempt.
+
+Like every gated write here, **one call raises the dialog and waits.** There is no second call.
+
+### Reading the result
+
+On success: `{ committed: true, folder, entryPath, branchCreated, commitSha, commitUrl, filesChanged, filesDeleted,
+divergedPaths }`.
+
+**Report the destination, `entryPath`, and `filesDeleted` to the human, always.** A nonzero value means real content was *removed*
+from their repository, not merely added. Only paths this tool itself previously wrote, whose live
+content still exactly matches what it wrote, are ever deleted — unrelated files and human-edited stale files are preserved. Current generated paths are replaced,
+including the generated README at this destination.
+
+`divergedPaths` lists paths that fell into that last case: no longer part of the export, but
+preserved because their content no longer matches this tool's own record. Tell the human those need
+their own manual review if removal is still wanted. Silence here reads as "everything is clean",
+which is the opposite of what a non-empty `divergedPaths` means.
+
+### The failure codes, and what each one is telling you
+
+| Code | What it means | The right next move |
+|---|---|---|
+| `no-credential` | No Source Control credential is connected. Returned **without raising a dialog** | Point them at the admin's Source Control page. Call `source_control_get_capabilities` first next time |
+| `REPOSITORY_NOT_FOUND` | The token cannot see that `owner/repo` | Confirm the identifiers, then the token's access. Not necessarily a bad token |
+| `NO_CHANGES` | Nothing changed since the branch's last commit | **Not a failure.** Say nothing needed to commit |
+| `DIVERGED_BRANCH` | Someone else pushed since this call started; the commit was refused rather than overwriting history | The human resolves it, exactly as with any rejected non-fast-forward push |
+| `NETWORK_UNREACHABLE` | Could not reach GitHub at all | Says **nothing** about the credential. Do not tell them to replace it. Suggest retrying |
+| `PROVIDER_ERROR` | GitHub's API rejected the request — expired token, insufficient scope, permission | The message names what went wrong. Never a raw body, never the credential |
+| `EXPORT_FAILED` | The site failed to export cleanly, before any commit was attempted | A host-side problem, not a GitHub one. Fix the export |
+
+`{ committed: false, cancelled: true }` is a human declining. Say so and stop.
+
+Wait for the result and report the true outcome. Do not tell a human a dialog is open and then
+stop, and do not call again while a call is pending — a fresh call raises a second, separate dialog
+rather than answering the first.

package/github/source-control/backup-push.mjs

@@ -0,0 +1,242 @@
+// @ts-check
+import { createHash } from "node:crypto";
+
+import { enc, encPath, extractStringField, isOk, parseJsonBody, providerErrorMessage, repoPathOf } from "./write-files.mjs";
+
+/**
+ * @file Pushes a site backup into a folder of a PRIVATE GitHub repository. Moved out of core
+ * (`apps/website/src/features/site-backup/github-push.ts`) unchanged in behavior.
+ *
+ * Three steps, the tool (`site_backup_*` in core) sequencing them: `inspectBackupRepository` checks
+ * the repository BEFORE anything is uploaded (it must exist, be private — a backup holds the whole
+ * database — be pushable and non-empty, and the folder must not be a file); `uploadBackupBlob` sends
+ * one file as a git blob; `commitBackupTree` replaces the backup folder with a tree of the uploaded
+ * blobs on top of the planned parent, with an unforced ref update (a moved branch is `diverged`).
+ * No recursive tree fetch and no deletion list are needed: the folder's tree is replaced whole.
+ *
+ * Large sites (2026-10-06, a 212 MiB backup failed live): every request gets
+ * {@link BACKUP_CLIENT_OPTIONS} — a long socket-idle budget, because GitHub stays silent while it
+ * stores a big blob, and retries with backoff for timeouts, 5xx and rate limits. Small text files ride
+ * inline in the tree requests ({@link BACKUP_INLINE_TEXT_MAX_BYTES}) instead of one blob POST each,
+ * which keeps a first backup of ~1500 files to a few hundred writes, under GitHub's content-creation
+ * limits.
+ *
+ * @typedef {import("./write-files.mjs").Target} Target
+ * @typedef {import("./write-files.mjs").GitDataClient} GitDataClient
+ * @typedef {{ path: string, blobSha: string, bytes: number, sha256: string }} UploadedBackupBlob
+ * @typedef {{ path: string, text: string, bytes: number, sha256: string }} InlineBackupText
+ */
+
+/**
+ * The backup's GitHub client. The 2-minute idle budget (the backup egress policy allows it; the
+ * custom-credential one caps every request at 10 s) is what a 42 MiB database blob needed: the 10 s
+ * cap timed out while GitHub was still answering. Waits follow GitHub's REST guidance: `retry-after`
+ * first, a minute for a secondary limit without one, never longer than 10 minutes in one wait.
+ *
+ * @type {{ timeoutMs: number, retry: import("./write-files.mjs").RetryPolicy }}
+ */
+export const BACKUP_CLIENT_OPTIONS = {
+  timeoutMs: 120_000,
+  retry: { maxAttempts: 5, baseBackoffMs: 2_000, maxBackoffMs: 30_000, rateLimitWaitMs: 60_000, maxWaitMs: 10 * 60_000 },
+};
+
+/** A UTF-8 file up to this size goes inline in a tree request instead of as its own blob. */
+export const BACKUP_INLINE_TEXT_MAX_BYTES = 512 * 1024;
+
+const PROVIDER_ERROR = "provider-error";
+
+/** One tree request's share of the folder: GitHub abandons a request it cannot finish in 10 s, so a
+ *  large folder is built over several chained `base_tree` requests rather than one. */
+const TREE_CHUNK_MAX_ENTRIES = 300;
+const TREE_CHUNK_MAX_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Splits the folder's entries into tree requests, by entry count and inline-text bytes.
+ *
+ * @param {readonly (UploadedBackupBlob | InlineBackupText)[]} entries
+ * @complexity O(n).
+ */
+function chunkTreeEntries(entries) {
+  /** @type {(UploadedBackupBlob | InlineBackupText)[][]} */
+  const chunks = [[]];
+  let bytes = 0;
+  for (const entry of entries) {
+    const size = entry.path.length + ("text" in entry ? entry.bytes : 64);
+    const current = chunks[chunks.length - 1];
+    if (current.length > 0 && (current.length >= TREE_CHUNK_MAX_ENTRIES || bytes + size > TREE_CHUNK_MAX_BYTES)) {
+      chunks.push([entry]);
+      bytes = size;
+    } else {
+      current.push(entry);
+      bytes += size;
+    }
+  }
+  return chunks;
+}
+
+/** @param {UploadedBackupBlob | InlineBackupText} entry */
+function treeEntry(entry) {
+  return "text" in entry ? { path: entry.path, mode: "100644", type: "blob", content: entry.text } : { path: entry.path, mode: "100644", type: "blob", sha: entry.blobSha };
+}
+
+/** @param {GitDataClient} git */
+export function createBackupPusher(git) {
+  /** @param {{ json: any, name: string }} required */
+  function checkBackupPrivacy({ json, name }, _options = {}) {
+    const fallbackVisibility = json.private === true ? "private" : "public";
+    const visibility = typeof json.visibility === "string" ? json.visibility : fallbackVisibility;
+    if (json.private !== true || visibility !== "private") {
+      return {
+        ok: false,
+        code: "repo-not-private",
+        message:
+          `repository ${name} is ${visibility}. A site backup contains the whole database — members, form submissions, admin accounts — ` +
+          "which would be exposed to everyone who can read that repository. Back up only to a private repository.",
+      };
+    }
+    return undefined;
+  }
+
+  /** @param {Target} target */
+  async function checkRepository(target) {
+    const name = `${target.owner}/${target.repo}`;
+    const repoJson = await git.getJson(target, repoPathOf(target), "GitHub repository lookup failed");
+    if (!repoJson.ok) return repoJson;
+    if (!repoJson.found) {
+      return { ok: false, code: "repo-not-found", message: `repository ${name} was not found, or this credential cannot see it` };
+    }
+    const json = repoJson.json;
+    const privacy = checkBackupPrivacy({ json, name });
+    if (privacy) return privacy;
+    const permissions = json.permissions;
+    if (typeof permissions === "object" && permissions !== null && permissions.push === false) {
+      return { ok: false, code: "no-push-permission", message: `this credential can read ${name} but cannot push to it` };
+    }
+    const defaultBranch = extractStringField(json, "default_branch");
+    const htmlUrl = extractStringField(json, "html_url");
+    if (!defaultBranch || !htmlUrl) return { ok: false, code: PROVIDER_ERROR, message: "GitHub repository lookup response did not include a default branch or URL" };
+    return { ok: true, defaultBranch, htmlUrl };
+  }
+
+  /** GitHub answers 409 for the ref of an EMPTY repository. @param {Target} target @param {string} branch */
+  async function readBranchTip(target, branch) {
+    const name = `${target.owner}/${target.repo}`;
+    const refResult = await git.send(target, { method: "GET", url: `${repoPathOf(target)}/git/ref/heads/${encPath(branch)}` });
+    if (refResult.kind !== "response") return git.nonResponseFailure(refResult);
+    const refResponse = refResult.response;
+    if (refResponse.status === 409) {
+      return { ok: false, code: "repo-empty", message: `repository ${name} is empty. Add a first commit (for example a README) on GitHub, then back up again.` };
+    }
+    if (refResponse.status === 404) return { ok: false, code: "branch-not-found", message: `branch '${branch}' does not exist in ${name}` };
+    if (!isOk(refResponse)) return { ok: false, code: PROVIDER_ERROR, message: providerErrorMessage(refResponse, "GitHub branch lookup failed") };
+    const refBody = parseJsonBody(refResponse);
+    const parentCommitSha = refBody.ok ? extractStringField(refBody.json?.object, "sha") : "";
+    if (!parentCommitSha) return { ok: false, code: PROVIDER_ERROR, message: "GitHub branch lookup response did not include a sha" };
+
+    return readBackupParentTree({ target, parentCommitSha });
+  }
+
+  /** @param {{ target: Target, parentCommitSha: string }} required */
+  async function readBackupParentTree({ target, parentCommitSha }, _options = {}) {
+    const commitJson = await git.getJson(target, `${repoPathOf(target)}/git/commits/${enc(parentCommitSha)}`, "GitHub parent-commit lookup failed");
+    if (!commitJson.ok) return commitJson;
+    const baseTreeSha = commitJson.found ? extractStringField(commitJson.json.tree, "sha") : "";
+    if (!baseTreeSha) return { ok: false, code: PROVIDER_ERROR, message: "GitHub parent-commit lookup did not return a tree sha" };
+    return { ok: true, parentCommitSha, baseTreeSha };
+  }
+
+  /** @param {Target & { branch?: string, folder: string }} input */
+  async function inspectBackupRepository(input) {
+    const repo = await checkRepository(input);
+    if (!repo.ok) return repo;
+    const branch = input.branch ?? repo.defaultBranch;
+
+    const tip = await readBranchTip(input, branch);
+    if (!tip.ok) return tip;
+
+    const folderJson = await git.getJson(input, `${repoPathOf(input)}/contents/${encPath(input.folder)}?ref=${enc(branch)}`, "GitHub folder lookup failed");
+    if (!folderJson.ok) return folderJson;
+    if (folderJson.found && !Array.isArray(folderJson.json)) {
+      return { ok: false, code: "folder-is-file", message: `'${input.folder}' exists on branch '${branch}' but is not a folder — refusing to replace it` };
+    }
+    return { ok: true, state: { branch, parentCommitSha: tip.parentCommitSha, baseTreeSha: tip.baseTreeSha, htmlUrl: repo.htmlUrl, folderExists: folderJson.found } };
+  }
+
+  /** @param {Target} target @param {{ path: string, content: Uint8Array }} file */
+  async function uploadBackupBlob(target, file) {
+    const result = await git.createBlob(target, file.content);
+    if (!result.ok) return result;
+    const sha256 = createHash("sha256").update(file.content).digest("hex");
+    return { ok: true, blob: { path: file.path, blobSha: result.sha, bytes: file.content.byteLength, sha256 } };
+  }
+
+  /**
+   * The backup folder's tree, built over chained requests: each one adds a chunk of entries on top of
+   * the previous one's tree (`base_tree`), the first starting empty, so the folder still REPLACES
+   * whatever was there.
+   *
+   * @param {Target} input @param {string} repoPath @param {readonly (UploadedBackupBlob | InlineBackupText)[]} entries
+   * @complexity O(n) entries over ceil(n / chunk) requests.
+   */
+  async function createFolderTree(input, repoPath, entries) {
+    /** @type {string | undefined} */
+    let folderTreeSha;
+    for (const chunk of chunkTreeEntries(entries)) {
+      const folderTree = await git.postJson(
+        input,
+        `${repoPath}/git/trees`,
+        { ...(folderTreeSha !== undefined ? { base_tree: folderTreeSha } : {}), tree: chunk.map(treeEntry) },
+        "GitHub folder tree creation failed"
+      );
+      if (!folderTree.ok) return folderTree;
+      folderTreeSha = extractStringField(folderTree.json, "sha");
+      if (!folderTreeSha) return { ok: false, code: PROVIDER_ERROR, message: "GitHub folder tree creation response did not include a sha" };
+    }
+    return { ok: true, sha: /** @type {string} */ (folderTreeSha) };
+  }
+
+  /**
+   * @param {Target & { branch: string, folder: string, commitMessage: string, parentCommitSha: string,
+   *   baseTreeSha: string, htmlUrl: string, entries: readonly (UploadedBackupBlob | InlineBackupText)[] }} input
+   */
+  async function commitBackupTree(input) {
+    const repoPath = repoPathOf(input);
+
+    const folderTree = await createFolderTree(input, repoPath, input.entries);
+    if (!folderTree.ok) return folderTree;
+    const folderTreeSha = folderTree.sha;
+
+    const rootTree = await git.postJson(
+      input,
+      `${repoPath}/git/trees`,
+      { base_tree: input.baseTreeSha, tree: [{ path: input.folder, mode: "040000", type: "tree", sha: folderTreeSha }] },
+      "GitHub tree creation failed"
+    );
+    if (!rootTree.ok) return rootTree;
+    const rootTreeSha = extractStringField(rootTree.json, "sha");
+    if (!rootTreeSha) return { ok: false, code: PROVIDER_ERROR, message: "GitHub tree creation response did not include a sha" };
+
+    const commit = await git.postJson(
+      input,
+      `${repoPath}/git/commits`,
+      { message: input.commitMessage, tree: rootTreeSha, parents: [input.parentCommitSha] },
+      "GitHub commit creation failed"
+    );
+    if (!commit.ok) return commit;
+    const commitSha = extractStringField(commit.json, "sha");
+    if (!commitSha) return { ok: false, code: PROVIDER_ERROR, message: "GitHub commit creation response did not include a sha" };
+
+    const ref = await git.updateRef(input, input.branch, commitSha);
+    if (!ref.ok) {
+      if (ref.code !== "diverged") return ref;
+      return {
+        ok: false,
+        code: "diverged",
+        message: `branch '${input.branch}' moved since the backup was planned (someone pushed to it). Nothing was overwritten. Call site_backup_plan again.`,
+      };
+    }
+    return { ok: true, commitSha, commitUrl: `${input.htmlUrl}/commit/${commitSha}` };
+  }
+
+  return { inspectBackupRepository, uploadBackupBlob, commitBackupTree };
+}