mikser-io-git 2.1.0

package/lib/config.js

@@ -0,0 +1,82 @@
+// Resolve the factory's raw options into the fully-derived config the
+// rest of the plugin uses. Pure — no filesystem, no network — so the
+// validation and owner/repo/apiBase derivation are directly testable
+// without instantiating the lifecycle plugin.
+
+import { parseDuration } from './duration.js'
+import { parseRepoUrl } from './repo-url.js'
+
+const VALID_FORGES = ['github', 'gitea', 'none']
+
+const DEFAULT_MESSAGE = ({ fileCount }) => `content: ${fileCount} file(s) via mikser`
+
+// Accept a single path string or an array; resolve to either a
+// non-empty array of strings, or `null` meaning "no scope — the
+// working folder itself, whatever git sees, subject to .gitignore."
+// `paths`, when given, are pathspecs RELATIVE to the working folder
+// (the repo root — see index.js) naming the specific collection
+// folders (documents, layouts, files, ...) this plugin is allowed to
+// touch: every git operation is scoped to exactly those pathspecs, so
+// mikser.config.js/node_modules/runtime/out/.env are never staged or
+// committed regardless of what's dirty there — a hard scope, not a
+// convenience.
+//
+// Omitting `paths` entirely is a DIFFERENT, weaker guarantee: with no
+// pathspec at all, git operates on the whole working folder, and
+// `.gitignore` is the only thing keeping node_modules/.env/etc out of
+// the commit — this plugin provides no scoping of its own in that
+// case. The zero-config default is "the working folder is the
+// checkout, commit whatever's in it" (matching the model's own
+// framing), not "commit just documents/" — narrower defaults are an
+// explicit `paths` away, not the unconfigured behavior.
+//
+// An explicitly-passed EMPTY array is treated as a mistake (throws),
+// not as an alias for "no scope" — a bare `paths: []` reads as an
+// oversight, not an intentional "commit everything" request, and
+// silently reinterpreting it that way would hide the typo.
+function normalizePaths(value) {
+    if (value == null) return null
+    const arr = Array.isArray(value) ? value : [value]
+    const cleaned = arr.map(p => String(p).trim()).filter(Boolean)
+    if (cleaned.length === 0) {
+        throw new Error('git: `paths` must be a non-empty string or array of strings (omit `paths` entirely to commit the whole working folder)')
+    }
+    return cleaned
+}
+
+export function resolveConfig(options = {}) {
+    if (!options.url) {
+        throw new Error('git: `url` is required — the repo the working folder syncs with')
+    }
+    const forge = options.forge ?? 'none'
+    if (!VALID_FORGES.includes(forge)) {
+        throw new Error(`git: \`forge\` must be "github", "gitea", or "none"; got ${JSON.stringify(forge)}`)
+    }
+
+    let owner = options.owner
+    let repo = options.repo
+    let apiBase = options.apiBase
+    if (forge !== 'none' && (!owner || !repo || !apiBase)) {
+        const parsed = parseRepoUrl(options.url)
+        owner   = owner   ?? parsed.owner
+        repo    = repo    ?? parsed.repo
+        apiBase = apiBase ?? parsed.apiOrigin
+    }
+
+    return {
+        url: options.url,
+        paths: normalizePaths(options.paths),
+        forge,
+        targetBranch: options.branch ?? 'main',
+        writeBranch: options.writeBranch ?? 'mikser',
+        token: options.token,
+        message: options.message ?? DEFAULT_MESSAGE,
+        author: options.author,
+        afterMs: parseDuration(options.after, 60_000),
+        maxWaitMs: parseDuration(options.maxWait, 600_000),
+        pollIntervalMs: parseDuration(options.pollInterval, 300_000),
+        owner,
+        repo,
+        apiBase,
+    }
+}

package/lib/debounce.js

@@ -0,0 +1,26 @@
+// Pure debounce-with-ceiling reducer for the green-gated sync timer.
+//
+// A green cycle should (re)start a short debounce (`after`) so a burst
+// of quick edits collapses into one sync pass rather than one per
+// cycle. But a pure trailing debounce never fires if green cycles keep
+// arriving faster than `after` — so `maxWait` bounds how long a change
+// can wait from the moment it FIRST became eligible, regardless of how
+// many more green cycles follow.
+//
+// A red cycle clears the window outright: don't commit a state that's
+// currently broken. When cycles turn green again later, that starts a
+// fresh window — there's no reason to preserve how long a change was
+// waiting before an interruption once the interruption has cleared.
+//
+// state shape: { pendingSince: number|null, fireAt: number|null }
+// (both null means idle — nothing queued, no timer needed)
+export function reduceDebounce(state, event, { afterMs, maxWaitMs }) {
+    if (event.type === 'red') {
+        return { pendingSince: null, fireAt: null }
+    }
+    const pendingSince = state.pendingSince ?? event.now
+    const fireAt = Math.min(event.now + afterMs, pendingSince + maxWaitMs)
+    return { pendingSince, fireAt }
+}
+
+export const IDLE_DEBOUNCE_STATE = { pendingSince: null, fireAt: null }

package/lib/duration.js

@@ -0,0 +1,14 @@
+// Parse a duration config value: a plain number of ms, or a string
+// like '1m', '30s', '10m', '1h'. Same shape as other mikser-io sibling
+// plugins' duration configs (e.g. mikser-io-post-email's maxDelay) —
+// not shared via import (no cross-plugin imports), just a consistent
+// small convention repeated where it's needed.
+export function parseDuration(value, fallback) {
+    if (value == null) return fallback
+    if (typeof value === 'number') return value
+    const m = /^\s*(\d+)\s*(ms|s|m|h|d)\s*$/i.exec(String(value))
+    if (!m) throw new Error(`git: invalid duration "${value}" (expected e.g. "1m", "30s", "10m", "1h")`)
+    const n = Number(m[1])
+    const u = m[2].toLowerCase()
+    return n * ({ ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[u])
+}

package/lib/forge/gitea.js

@@ -0,0 +1,71 @@
+// Gitea forge adapter. Gitea's API is deliberately modeled on GitHub's
+// for pull requests, but with real differences confirmed against
+// Gitea's own route definitions (routers/api/v1/api.go):
+//   - base path is <instance-url>/api/v1, not a fixed host
+//   - auth header is `Authorization: token <token>` (Gitea's documented
+//     scheme), not `Bearer`
+//   - merge is POST .../pulls/{index}/merge with body `{ Do: 'merge' }`
+//     (GitHub: PUT .../merge with `{ merge_method }`) — there is NO
+//     bare "merge branch A into B" endpoint; merge-upstream exists but
+//     is a different feature (syncing a fork from its upstream), so
+//     the pull-request path is the only portable one.
+// The head/base ref field names on a listed PR (`head.ref` / `base.ref`)
+// are assumed to mirror GitHub's shape (Gitea's PullRequest struct is
+// modeled the same way) but are NOT independently verified here — if
+// they don't match, ensurePR's existing-PR lookup simply finds nothing
+// and creates a new PR. Worst case is a duplicate open PR, never lost
+// content, so this is a safe direction to be wrong in.
+//
+// Same contract as lib/forge/github.js:
+//   ensurePR({...}) -> { number, url }
+//   mergePR({...})  -> { merged: true } | { merged: false, reason }
+
+function headers(token) {
+    return {
+        'Authorization': `token ${token}`,
+        'Accept': 'application/json',
+        'Content-Type': 'application/json',
+    }
+}
+
+async function bestEffortMessage(res) {
+    try {
+        const body = await res.json()
+        return body?.message ?? res.statusText
+    } catch {
+        return res.statusText
+    }
+}
+
+export async function ensurePR({ apiBase, owner, repo, head, base, title, token, fetchImpl = fetch }) {
+    const listRes = await fetchImpl(
+        `${apiBase}/api/v1/repos/${owner}/${repo}/pulls?state=open`,
+        { headers: headers(token) },
+    )
+    if (listRes.ok) {
+        const list = await listRes.json()
+        const match = Array.isArray(list)
+            ? list.find(pr => pr.head?.ref === head && pr.base?.ref === base)
+            : null
+        if (match) return { number: match.number, url: match.html_url ?? match.url }
+    }
+
+    const created = await fetchImpl(
+        `${apiBase}/api/v1/repos/${owner}/${repo}/pulls`,
+        { method: 'POST', headers: headers(token), body: JSON.stringify({ title, head, base }) },
+    )
+    if (!created.ok) {
+        throw new Error(`Gitea: failed to create PR ${head} → ${base}: ${await bestEffortMessage(created)}`)
+    }
+    const pr = await created.json()
+    return { number: pr.number, url: pr.html_url ?? pr.url }
+}
+
+export async function mergePR({ apiBase, owner, repo, number, token, fetchImpl = fetch }) {
+    const res = await fetchImpl(
+        `${apiBase}/api/v1/repos/${owner}/${repo}/pulls/${number}/merge`,
+        { method: 'POST', headers: headers(token), body: JSON.stringify({ Do: 'merge' }) },
+    )
+    if (res.ok) return { merged: true }
+    return { merged: false, reason: await bestEffortMessage(res) }
+}

package/lib/forge/github.js

@@ -0,0 +1,64 @@
+// GitHub forge adapter — create-or-reuse a PR from the write branch
+// onto the target branch, and attempt to merge it.
+//
+// `fetchImpl` is injectable (defaults to the global fetch) purely so
+// tests can supply a mock without a network or a real token.
+//
+// Contract shared with lib/forge/gitea.js:
+//   ensurePR({...}) -> { number, url }
+//   mergePR({...})  -> { merged: true } | { merged: false, reason }
+// Any non-2xx response is treated as "not merged" with a best-effort
+// reason string — this plugin never needs to distinguish a real merge
+// conflict from a permissions error or a moved base branch; either way
+// the PR stays open and a human looks at it.
+
+function headers(token) {
+    return {
+        'Authorization': `Bearer ${token}`,
+        'Accept': 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        'Content-Type': 'application/json',
+        // GitHub requires a User-Agent on API requests; any non-empty
+        // value satisfies it.
+        'User-Agent': 'mikser-io-git',
+    }
+}
+
+async function bestEffortMessage(res) {
+    try {
+        const body = await res.json()
+        return body?.message ?? res.statusText
+    } catch {
+        return res.statusText
+    }
+}
+
+export async function ensurePR({ apiBase = 'https://api.github.com', owner, repo, head, base, title, token, fetchImpl = fetch }) {
+    const existing = await fetchImpl(
+        `${apiBase}/repos/${owner}/${repo}/pulls?head=${owner}:${head}&base=${base}&state=open`,
+        { headers: headers(token) },
+    )
+    if (existing.ok) {
+        const list = await existing.json()
+        if (list.length > 0) return { number: list[0].number, url: list[0].html_url }
+    }
+
+    const created = await fetchImpl(
+        `${apiBase}/repos/${owner}/${repo}/pulls`,
+        { method: 'POST', headers: headers(token), body: JSON.stringify({ title, head, base }) },
+    )
+    if (!created.ok) {
+        throw new Error(`GitHub: failed to create PR ${head} → ${base}: ${await bestEffortMessage(created)}`)
+    }
+    const pr = await created.json()
+    return { number: pr.number, url: pr.html_url }
+}
+
+export async function mergePR({ apiBase = 'https://api.github.com', owner, repo, number, token, fetchImpl = fetch }) {
+    const res = await fetchImpl(
+        `${apiBase}/repos/${owner}/${repo}/pulls/${number}/merge`,
+        { method: 'PUT', headers: headers(token), body: JSON.stringify({ merge_method: 'merge' }) },
+    )
+    if (res.ok) return { merged: true }
+    return { merged: false, reason: await bestEffortMessage(res) }
+}

package/lib/git.js

@@ -0,0 +1,191 @@
+// Thin wrapper over the `git` binary. Every call goes through execFile
+// with argv arrays — never a shell string — so a commit message or
+// branch name built from entity ids (arbitrary content from documents)
+// can never be interpreted as a shell command.
+//
+// `run` is the one low-level primitive; everything else composes it.
+// Kept thin and exported individually so tests can stub `run` and
+// exercise the higher-level functions' argv-building and result
+// parsing without a real git binary or network.
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+// Run a git subcommand in `cwd`. Returns trimmed stdout on success;
+// throws with `.stderr` and `.code` attached on failure (execFile's
+// own shape) so callers can branch on specific failures (e.g. a
+// non-fast-forward push) without string-matching stdout.
+export async function run(cwd, args, opts = {}) {
+    try {
+        const { stdout } = await execFileAsync('git', args, { cwd, ...opts })
+        return stdout.trim()
+    } catch (err) {
+        // execFile already attaches .code / .stderr / .stdout to the
+        // error; re-throw as-is so callers can inspect them.
+        throw err
+    }
+}
+
+export async function isInsideWorkTree(folder) {
+    try {
+        const out = await run(folder, ['rev-parse', '--is-inside-work-tree'])
+        return out === 'true'
+    } catch {
+        return false
+    }
+}
+
+export async function currentBranch(folder) {
+    return run(folder, ['rev-parse', '--abbrev-ref', 'HEAD'])
+}
+
+export async function remoteUrl(folder, remote = 'origin') {
+    try {
+        return await run(folder, ['remote', 'get-url', remote])
+    } catch {
+        return null
+    }
+}
+
+// Auth via a short-lived per-request header, never embedded in the
+// remote URL or written to .git/config — an embedded
+// `https://token@host/...` remote leaks the token into `git remote -v`
+// output and any log/error that echoes the URL. `http.extraheader` is
+// passed as a one-off `-c` flag on the specific command that needs it
+// (fetch/pull/push/clone), so it never persists to disk.
+function authArgs(token) {
+    if (!token) return []
+    const b64 = Buffer.from(`x-access-token:${token}`).toString('base64')
+    return ['-c', `http.extraheader=AUTHORIZATION: basic ${b64}`]
+}
+
+export async function clone(url, folder, { branch, token } = {}) {
+    const args = [...authArgs(token), 'clone', ...(branch ? ['--branch', branch] : []), url, folder]
+    // clone's cwd doesn't matter (destination is a full path); run from
+    // the parent so a not-yet-existing `folder` isn't required as cwd.
+    await run('.', args)
+}
+
+export async function fetch(folder, { remote = 'origin', token } = {}) {
+    await run(folder, [...authArgs(token), 'fetch', remote])
+}
+
+export async function push(folder, refspec, { remote = 'origin', token, force = false } = {}) {
+    const args = [...authArgs(token), 'push', ...(force ? ['--force-with-lease'] : []), remote, refspec]
+    await run(folder, args)
+}
+
+// Non-fast-forward pushes throw with stderr containing "non-fast-forward"
+// or "fetch first" (exact wording varies by git version/remote); callers
+// that need to distinguish "rejected, needs integration" from other
+// failures should check this rather than assuming any push() throw
+// means the same thing.
+export function isNonFastForwardError(err) {
+    const msg = `${err?.stderr ?? ''} ${err?.message ?? ''}`
+    return /non-fast-forward|fetch first|rejected/i.test(msg)
+}
+
+// `paths`, when given, scopes the command to those pathspecs via git's
+// `--` separator — e.g. `['documents', 'layouts']`. This is the actual
+// enforcement mechanism behind "this plugin only touches the folders
+// you configured": mikser.config.js, node_modules/, runtime/, out/,
+// .env can all sit in the SAME checkout (the working folder IS the
+// checkout — see index.js) without ever being staged, added, or
+// committed, because they're simply not in the pathspec. Omit `paths`
+// for the rare whole-repo case (nothing in this plugin currently needs
+// that, but the functions stay generally usable).
+function pathspecArgs(paths) {
+    return paths?.length ? ['--', ...paths] : []
+}
+
+export async function statusPorcelain(folder, paths) {
+    // --untracked-files=all: without it, git collapses an entire new
+    // untracked directory into ONE porcelain line ("?? newdir/") rather
+    // than one line per file inside it. Harmless for hasChanges() (any
+    // non-empty output still means "changed"), but sync.js derives its
+    // commit message's file count from this output's line count — with
+    // the default, a brand-new author's folder or category directory
+    // would silently undercount (confirmed against a real git repo: a
+    // 3-file new directory reported as a single line). `git add`
+    // itself was never affected by this — it always stages everything
+    // in its scope regardless of how status reports it — this only
+    // fixes what the commit message claims happened.
+    return run(folder, ['status', '--porcelain', '--untracked-files=all', ...pathspecArgs(paths)])
+}
+
+export async function hasChanges(folder, paths) {
+    return (await statusPorcelain(folder, paths)).length > 0
+}
+
+export async function addAll(folder, paths) {
+    // `-A` with a pathspec stages new/modified/deleted files WITHIN
+    // that pathspec only — it does not fall back to staging the whole
+    // repo. Verified directly (see test/git.test.js) before relying on
+    // it as the scope boundary.
+    await run(folder, ['add', '-A', ...pathspecArgs(paths)])
+}
+
+export async function commit(folder, message, { author } = {}) {
+    const args = ['commit', '-m', message]
+    if (author?.name)  args.push('--author', `${author.name} <${author.email ?? ''}>`)
+    await run(folder, args)
+}
+
+// True when there's nothing staged to commit — the caller's signal to
+// skip commit() entirely rather than treat "nothing to commit" as an
+// error. Cheaper than parsing commit()'s own failure for this one case.
+export async function hasStagedChanges(folder, paths) {
+    try {
+        // --quiet + --exit-code: exits 1 if there ARE differences
+        // (i.e. something staged), 0 if the index matches HEAD.
+        await run(folder, ['diff', '--cached', '--quiet', ...pathspecArgs(paths)])
+        return false
+    } catch {
+        return true
+    }
+}
+
+export async function checkoutBranch(folder, branch, { create = false, startPoint } = {}) {
+    const args = ['checkout', ...(create ? ['-b'] : []), branch, ...(startPoint ? [startPoint] : [])]
+    await run(folder, args)
+}
+
+export async function branchExistsLocal(folder, branch) {
+    try {
+        await run(folder, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`])
+        return true
+    } catch {
+        return false
+    }
+}
+
+export async function branchExistsRemote(folder, branch, { remote = 'origin', token } = {}) {
+    // ls-remote hits the network but needs no local ref state — safe
+    // to call before any fetch has happened.
+    const out = await run(folder, [...authArgs(token), 'ls-remote', '--heads', remote, branch])
+    return out.length > 0
+}
+
+// Reset the current branch (HARD — working tree included) to match
+// `ref` exactly. Used only to converge the local `mikser` branch onto
+// origin/<target> after a successful PR merge, or to recover from a
+// rejected push by re-basing onto the fetched remote. Never used to
+// discard a user's uncommitted work — every call site commits first.
+export async function resetHard(folder, ref) {
+    await run(folder, ['reset', '--hard', ref])
+}
+
+export async function mergeBranch(folder, ref, { message } = {}) {
+    const args = ['merge', '--no-edit', ...(message ? ['-m', message] : []), ref]
+    await run(folder, args)
+}
+
+export async function abortMerge(folder) {
+    try { await run(folder, ['merge', '--abort']) } catch { /* nothing to abort */ }
+}
+
+export async function revParse(folder, ref) {
+    return run(folder, ['rev-parse', ref])
+}

package/lib/inbound.js

@@ -0,0 +1,43 @@
+// Pull remote changes into the working folder. Two things can have
+// moved on the remote since our last fetch:
+//   - the write branch itself (a human pushed directly to it instead
+//     of going through the CMS — discouraged but not prevented)
+//   - the target branch (a promotion merged, or a human pushed/merged
+//     directly to it)
+// Both are merged in sequentially (not as one octopus merge) so a
+// conflict is attributable to a specific branch and doesn't abort a
+// merge that would otherwise have succeeded.
+//
+// On ANY conflict, the merge is aborted immediately — never left
+// half-applied. This folder is mikser's live working copy; leaving
+// conflict markers in a file would mean the render pipeline reads
+// "<<<<<<< HEAD" as page content on the next cycle. Abort-and-log is
+// the only acceptable outcome here.
+//
+// Note: this module ONLY performs the merge. It doesn't need to wake
+// mikser's watch loop itself — `git merge` writes real files via
+// normal filesystem writes, which the file source's own chokidar
+// watcher already sees as ordinary 'change' events (same as a human
+// editing a file), and manager.js's watch() wakes the process loop
+// from that automatically.
+
+import * as git from './git.js'
+
+export async function pullInbound(folder, { writeBranch, targetBranch, token, logger }) {
+    await git.fetch(folder, { token })
+
+    for (const ref of [writeBranch, targetBranch]) {
+        try {
+            await git.mergeBranch(folder, `origin/${ref}`)
+        } catch (err) {
+            await git.abortMerge(folder)
+            logger?.error(
+                'git: inbound merge of origin/%s conflicted — aborted, working folder left untouched. ' +
+                'Resolve manually: cd <folder> && git merge origin/%s (or origin/%s) and fix the conflicts. %s',
+                ref, writeBranch, targetBranch, err.stderr || err.message,
+            )
+            return { merged: false, conflictedRef: ref, reason: err.stderr || err.message }
+        }
+    }
+    return { merged: true }
+}

package/lib/repo-url.js

@@ -0,0 +1,28 @@
+// Derive { owner, repo, apiOrigin } from a plain repo URL, so config
+// only needs `url` + `forge` — not four separately-specified fields
+// that would drift from the clone URL if ever changed independently.
+//
+// apiOrigin is the scheme+host the forge adapter's API lives at. For
+// github.com this is NOT the repo's own host — GitHub's API is on
+// api.github.com, a different subdomain — so github.com URLs get that
+// origin by default. Self-hosted GitHub Enterprise Server serves its
+// API at <host>/api/v3 instead; that's a real case this doesn't derive
+// automatically — pass `apiBase` explicitly for GHES. Gitea (and any
+// other self-hosted forge) serves its API at the SAME host the repo
+// lives on, just under /api/v1 (which the gitea adapter appends
+// itself) — so the repo's own origin is the correct default there.
+export function parseRepoUrl(url) {
+    let u
+    try {
+        u = new URL(url)
+    } catch {
+        throw new Error(`git: "${url}" is not a valid URL`)
+    }
+    const parts = u.pathname.replace(/^\/+/, '').replace(/\.git$/, '').replace(/\/+$/, '').split('/')
+    if (parts.length < 2 || !parts[0] || !parts[1]) {
+        throw new Error(`git: cannot derive owner/repo from url "${url}" — expected .../owner/repo(.git)`)
+    }
+    const [owner, repo] = parts
+    const apiOrigin = u.host === 'github.com' ? 'https://api.github.com' : u.origin
+    return { owner, repo, apiOrigin }
+}

package/lib/sync.js

@@ -0,0 +1,123 @@
+// Orchestrates one sync pass: commit whatever's on disk to the write
+// branch (always — this is the durable log, it must never block),
+// then try to promote the write branch into the target branch (only
+// when the caller has already determined the last cycle was green).
+//
+// Two promotion mechanisms:
+//   - forge 'github' | 'gitea': open (or reuse) a PR write→target and
+//     attempt to merge it. Conflict or any other failure just leaves
+//     the PR open — never a crash, never data loss, always visible.
+//   - forge 'none': a direct fast-forward push write:target. Works
+//     against any bare remote with no API at all. If target has
+//     diverged, the push is rejected (also not a crash) and everything
+//     stays queued on the write branch until a human intervenes.
+
+import * as git from './git.js'
+import * as github from './forge/github.js'
+import * as gitea from './forge/gitea.js'
+
+const ADAPTERS = { github, gitea }
+
+// Commit whatever's currently on disk and push it to the write branch.
+// Returns { committed: boolean, pushed: boolean }. Never throws for
+// "nothing to commit" — that's the common, expected case on a quiet
+// cycle. Retries the push once after a pull --rebase-equivalent
+// (fetch + reset onto the remote tip, since this branch is bot-owned
+// and a local commit on top of a stale base is fine to replay) if the
+// initial push is rejected as non-fast-forward — covers the case
+// where an inbound pull (lib/inbound.js) advanced origin/<writeBranch>
+// between this cycle's fetch and its push.
+// `paths` scopes every git operation here to those pathspecs (relative
+// to `folder`, the working folder / repo root) — see git.js's
+// pathspecArgs. This is the hard boundary that lets mikser.config.js,
+// node_modules/, runtime/, out/, and .env live in the SAME checkout
+// this plugin manages without ever being staged or committed by it.
+//
+// `message` is a string or a function receiving { fileCount } (from
+// `git status --porcelain`'s line count, computed before staging) and
+// returning a string — a count rather than a file list, since a full
+// list of paths in a commit message gets unwieldy past a handful of
+// files and git status is cheap to re-derive if anyone needs detail.
+export async function commitAndPushWriteBranch(folder, { paths, writeBranch, message, author, token }) {
+    const porcelain = await git.statusPorcelain(folder, paths)
+    if (!porcelain) return { committed: false, pushed: false }
+    const fileCount = porcelain.split('\n').filter(Boolean).length
+
+    await git.addAll(folder, paths)
+    if (!(await git.hasStagedChanges(folder, paths))) {
+        // hasChanges() can be true from untracked files git add didn't
+        // end up staging as a diff from HEAD in edge cases (e.g. a
+        // file that matches .gitignore was force-added) — defensive,
+        // should not normally happen.
+        return { committed: false, pushed: false }
+    }
+    const resolvedMessage = typeof message === 'function' ? message({ fileCount }) : message
+    await git.commit(folder, resolvedMessage, { author })
+
+    try {
+        await git.push(folder, writeBranch, { token })
+        return { committed: true, pushed: true }
+    } catch (err) {
+        if (!git.isNonFastForwardError(err)) throw err
+        // The remote write branch moved (an inbound pull landed
+        // between our last fetch and now). Rebase our new commit onto
+        // the fresh remote tip and retry once. This branch is
+        // exclusively bot-written, so replaying our commit on top of
+        // the latest remote state is always safe — there's no other
+        // writer's history to preserve alongside it beyond what
+        // inbound sync already merged in.
+        await git.fetch(folder, { token })
+        await git.run(folder, ['rebase', `origin/${writeBranch}`])
+        await git.push(folder, writeBranch, { token })
+        return { committed: true, pushed: true }
+    }
+}
+
+// Attempt to promote the write branch into the target branch. Called
+// only when the caller has confirmed the cycle is green — this
+// function does not itself check for render/postprocess failures.
+//
+// Returns { promoted: boolean, reason?, prUrl? }.
+export async function promote(folder, {
+    forge, targetBranch, writeBranch, token,
+    owner, repo, apiBase, prTitle, fetchImpl,
+}) {
+    if (forge === 'none') {
+        try {
+            await git.push(folder, `${writeBranch}:${targetBranch}`, { token })
+            return { promoted: true }
+        } catch (err) {
+            if (!git.isNonFastForwardError(err)) throw err
+            return {
+                promoted: false,
+                reason: `${targetBranch} has diverged from ${writeBranch}; fast-forward push rejected. ` +
+                    `Configure a forge adapter (github/gitea) to get a pull request here instead of a ` +
+                    `manual merge, or merge ${writeBranch} into ${targetBranch} by hand.`,
+            }
+        }
+    }
+
+    const adapter = ADAPTERS[forge]
+    if (!adapter) throw new Error(`git: unknown forge "${forge}" (expected github, gitea, or none)`)
+
+    const pr = await adapter.ensurePR({
+        apiBase, owner, repo, head: writeBranch, base: targetBranch, title: prTitle, token, fetchImpl,
+    })
+    const result = await adapter.mergePR({ apiBase, owner, repo, number: pr.number, token, fetchImpl })
+
+    if (!result.merged) {
+        return { promoted: false, reason: result.reason, prUrl: pr.url }
+    }
+
+    // Converge: the target branch just advanced past the write
+    // branch's old tip (via a merge commit or squash). Pull the write
+    // branch up to match so next cycle's commit doesn't keep re-diffing
+    // against an increasingly stale base. force-with-lease is safe here
+    // — this branch is exclusively bot-written, nothing else's history
+    // is at risk, and --force-with-lease still refuses if the remote
+    // moved unexpectedly since our last fetch.
+    await git.fetch(folder, { token })
+    await git.resetHard(folder, `origin/${targetBranch}`)
+    await git.push(folder, writeBranch, { token, force: true })
+    return { promoted: true, prUrl: pr.url }
+}