diff --git a/src/hooks/useGitHubSync.ts b/src/hooks/useGitHubSync.ts
index 6a1fd90..68851e8 100644
--- a/src/hooks/useGitHubSync.ts
+++ b/src/hooks/useGitHubSync.ts
@@ -11,6 +11,7 @@ import { isChunkLoadError, showChunkReloadToast, CHUNK_RELOAD_MESSAGE } from '@/
// prefetch). pullFromZipball still lives in githubSync.ts for callers/tests.
import { syncToGitHub, pullFromGitHub } from '@/utils/githubSync'
import type { PullClassification, SyncResult, GitPathUpdate } from '@/utils/githubSync'
+import { makeGitHostProvider } from '@/utils/gitHost'
import { getValidGitHubToken, withTokenRefresh, ReconnectRequiredError } from '@/utils/tokenRefresh'
import { applyNonConflicts, applyAttachmentClassifications } from '@/utils/syncApply'
import { fillShellsInBackground } from '@/utils/backgroundFill'
@@ -186,8 +187,9 @@ async function runPull(
// clone runs on the user's own authenticated GitHub API quota instead of
// Noteser's Vercel bandwidth. pullFromZipball + fetchZipball + the
// /api/github/zipball route are kept in the tree but no longer on this path.
+ const { host, baseUrl } = useGitHubStore.getState()
const { classifications, latestCommitSha } = await pullFromGitHub({
- token, repo,
+ provider: makeGitHostProvider({ host, token, baseUrl }), repo,
notes: localNotes, folders: localFolders,
excludedFolderPaths,
vaultSettingsPath,
@@ -242,8 +244,9 @@ async function runPush(
}
}
+ const { host, baseUrl } = useGitHubStore.getState()
const outcome = await syncToGitHub({
- token, repo, notes, folders, commitMessage,
+ provider: makeGitHostProvider({ host, token, baseUrl }), repo, notes, folders, commitMessage,
vaultSettings: vaultSettingsInput,
// gi9n: thread the editor's draft through. Null = no pending edit;
// syncToGitHub will leave the remote `.gitignore` alone.
diff --git a/src/middleware.ts b/src/middleware.ts
index f9f74b4..02c4280 100644
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -1,6 +1,6 @@
import { NextResponse, type NextRequest } from 'next/server'
-import { buildCsp, deriveCollabWsOrigin } from '@/utils/csp'
+import { buildCsp, deriveCollabWsOrigin, deriveGitHostOrigin } from '@/utils/csp'
/**
* Per-request nonce-based CSP (Finding 6 of the 2026-05-21 security audit).
@@ -22,6 +22,7 @@ export function middleware(request: NextRequest) {
const csp = buildCsp(nonce, {
isDev: process.env.NODE_ENV !== 'production',
wsOrigin: deriveCollabWsOrigin(process.env.NEXT_PUBLIC_YJS_WS_URL),
+ gitHostOrigin: deriveGitHostOrigin(process.env.NEXT_PUBLIC_FORGEJO_BASE_URL),
// /share renders arbitrary shared content to arbitrary visitors — no
// remote-image tracking pixels there. See BuildCspOptions.restrictImages.
restrictImages: request.nextUrl.pathname.startsWith('/share'),
diff --git a/src/stores/githubStore.ts b/src/stores/githubStore.ts
index e5afe6f..d5e7466 100644
--- a/src/stores/githubStore.ts
+++ b/src/stores/githubStore.ts
@@ -1,6 +1,7 @@
import { create } from 'zustand'
import { persist } from 'zustand/middleware'
import type { GitHubUser, SyncRepo } from '@/types'
+import type { HostKind } from '@/utils/gitHost/types'
import { STORAGE_KEYS } from '@/utils/storageKeys'
import { localStorageJSON } from '@/utils/persistStorage'
import { trackEventOncePerSession } from '@/utils/analytics'
@@ -46,6 +47,13 @@ interface GitHubState {
token: string | null
user: GitHubUser | null
connectedAt: number | null
+ // Which git host this connection targets. `'github'` is the default for
+ // every existing user (a persisted blob with no `host` key merges over this
+ // initial value). The sync pipeline selects the provider from it.
+ host: HostKind
+ // Base URL for the active host. Null means "use the provider's own default"
+ // (GitHub ignores it entirely; Forgejo falls back to codeberg.org).
+ baseUrl: string | null
syncRepo: SyncRepo | null
lastSyncedAt: number | null
lastCommitSha: string | null
@@ -83,6 +91,7 @@ interface GitHubState {
// the refresh token on every use, so the new one is persisted here too.
applyRefreshedTokens: (tokens: GitHubTokenSet) => void
setTokenScopes: (scopes: string[] | null) => void
+ setHost: (host: HostKind, baseUrl: string | null) => void
setSyncRepo: (repo: SyncRepo | null) => void
recordSync: (commitSha: string) => void
setIsSyncing: (value: boolean) => void
@@ -100,6 +109,8 @@ export const useGitHubStore = create
()(
token: null,
user: null,
connectedAt: null,
+ host: 'github',
+ baseUrl: null,
syncRepo: null,
lastSyncedAt: null,
lastCommitSha: null,
@@ -129,6 +140,7 @@ export const useGitHubStore = create()(
refreshTokenExpiresAt: tokens.refreshTokenExpiresAt,
}),
setTokenScopes: (scopes) => set({ tokenScopes: scopes }),
+ setHost: (host, baseUrl) => set({ host, baseUrl }),
setIsSyncing: (value) => set({ isSyncing: value }),
setSyncRepo: (repo) => set(state => {
const currentKey = repoKey(state.syncRepo)
@@ -162,6 +174,7 @@ export const useGitHubStore = create()(
}),
disconnect: () => set({
token: null, user: null, connectedAt: null,
+ host: 'github', baseUrl: null,
syncRepo: null, lastSyncedAt: null, lastCommitSha: null,
repoSyncStates: {}, tokenScopes: null,
accessTokenExpiresAt: null, refreshToken: null, refreshTokenExpiresAt: null,
@@ -177,6 +190,8 @@ export const useGitHubStore = create()(
token: state.token,
user: state.user,
connectedAt: state.connectedAt,
+ host: state.host,
+ baseUrl: state.baseUrl,
syncRepo: state.syncRepo,
lastSyncedAt: state.lastSyncedAt,
lastCommitSha: state.lastCommitSha,
diff --git a/src/utils/csp.ts b/src/utils/csp.ts
index 35815ef..3807834 100644
--- a/src/utils/csp.ts
+++ b/src/utils/csp.ts
@@ -41,11 +41,33 @@ export function deriveCollabWsOrigin(raw: string | undefined): string | null {
}
}
+/**
+ * Derive a single http(s) origin from a raw NEXT_PUBLIC_FORGEJO_BASE_URL
+ * value so the CSP only allows the self-hosted Forgejo/Gitea instance the
+ * operator opted into at deploy time. Same posture as deriveCollabWsOrigin:
+ * an allow-listed origin, never a scheme wildcard — a runtime-controllable
+ * connect-src would let an XSS payload exfiltrate localStorage (which holds
+ * the git token) to an arbitrary host. Codeberg itself is a static entry in
+ * connect-src and needs no env var.
+ */
+export function deriveGitHostOrigin(raw: string | undefined): string | null {
+ if (!raw) return null
+ try {
+ const url = new URL(raw)
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') return null
+ return `${url.protocol}//${url.host}`
+ } catch {
+ return null
+ }
+}
+
export interface BuildCspOptions {
/** Non-production (dev / test): adds 'unsafe-eval' to script-src. */
isDev: boolean
/** Already-derived ws(s):// origin to add to connect-src, or null. */
wsOrigin: string | null
+ /** Already-derived self-hosted Forgejo origin for connect-src, or null. */
+ gitHostOrigin?: string | null
/**
* Drop the `https:` wildcard from img-src. The editor's own notes
* legitimately embed arbitrary HTTPS images (`![]()`), but the public
@@ -63,7 +85,7 @@ export interface BuildCspOptions {
* @param nonce base64 per-request nonce (already generated by middleware).
*/
export function buildCsp(nonce: string, options: BuildCspOptions): string {
- const { isDev, wsOrigin, restrictImages = false } = options
+ const { isDev, wsOrigin, gitHostOrigin = null, restrictImages = false } = options
const scriptSrc = [
"'self'",
@@ -76,9 +98,15 @@ export function buildCsp(nonce: string, options: BuildCspOptions): string {
"'self'",
'https://api.github.com',
'https://github.com',
+ // Codeberg is the built-in Forgejo host preset in the vault connect flow;
+ // its Gitea API is called browser-direct just like api.github.com.
+ 'https://codeberg.org',
'https://api.anthropic.com',
'https://api.openai.com',
...(wsOrigin ? [wsOrigin] : []),
+ // Self-hosted Forgejo/Gitea: only the single origin the operator
+ // allow-listed via NEXT_PUBLIC_FORGEJO_BASE_URL (see deriveGitHostOrigin).
+ ...(gitHostOrigin ? [gitHostOrigin] : []),
].join(' ')
return [
diff --git a/src/utils/gitHost/forgejoProvider.ts b/src/utils/gitHost/forgejoProvider.ts
new file mode 100644
index 0000000..d5d1e1f
--- /dev/null
+++ b/src/utils/gitHost/forgejoProvider.ts
@@ -0,0 +1,322 @@
+// ForgejoProvider: the Forgejo/Gitea implementation of the GitHostProvider
+// seam. Codeberg is just a base-URL preset (https://codeberg.org); any
+// self-hosted Forgejo/Gitea instance works via a configurable baseUrl.
+//
+// Unlike GitHubProvider (a thin wrap of github.ts), this provider talks to
+// the Gitea API directly at `{baseUrl}/api/v1`. The big divergence from
+// GitHub is the write path: Forgejo's git-data endpoints are read-only, so
+// commitChanges goes through `POST /repos/{owner}/{repo}/contents` (the
+// ChangeFiles batch API) — one request writes N files as a single commit.
+// See docs/multi-host-sync-plan.md.
+
+import type { SyncRepo } from '@/types'
+import { base64ToBytes } from '../github'
+import type {
+ GitHostProvider,
+ HostKind,
+ HostRepo,
+ HostUser,
+ CommitRequest,
+ CommitResult
+} from './types'
+
+const CODEBERG_BASE = 'https://codeberg.org'
+
+// Gitea caps repo listings; 50 keeps each page small enough to stay snappy.
+const REPOS_PER_PAGE = 50
+
+// Typed error thrown at the network boundary for any non-ok Gitea response.
+// Carries the HTTP status and the API's error message (when the body parses
+// as JSON) so the UI can show a precise message instead of a bare code.
+export class ForgejoAPIError extends Error {
+ constructor(
+ public readonly status: number,
+ public readonly operation: string,
+ public readonly serverMessage: string | null
+ ) {
+ const tail = serverMessage ? ` — ${serverMessage}` : ''
+ super(`${operation} failed (${status})${tail}`)
+ this.name = 'ForgejoAPIError'
+ }
+
+ static async fromResponse(
+ res: Response,
+ operation: string
+ ): Promise {
+ let serverMessage: string | null = null
+ try {
+ const body = (await res.clone().json()) as { message?: string }
+ if (typeof body.message === 'string') serverMessage = body.message
+ } catch {
+ // Body wasn't JSON, leave message null.
+ }
+ return new ForgejoAPIError(res.status, operation, serverMessage)
+ }
+}
+
+// Base64-encode a UTF-8 string for the ChangeFiles `content` field. TextEncoder
+// + btoa (btoa alone only handles Latin-1).
+function utf8ToBase64(content: string): string {
+ const bytes = new TextEncoder().encode(content)
+ let bin = ''
+ for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i])
+ return btoa(bin)
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+ let bin = ''
+ for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i])
+ return btoa(bin)
+}
+
+interface GiteaRepo {
+ name: string
+ owner: { login: string }
+ default_branch: string
+ private: boolean
+}
+
+function toHostRepo(repo: GiteaRepo): HostRepo {
+ return {
+ owner: repo.owner.login,
+ name: repo.name,
+ defaultBranch: repo.default_branch,
+ isPrivate: repo.private
+ }
+}
+
+export class ForgejoProvider implements GitHostProvider {
+ readonly kind: HostKind = 'forgejo'
+ readonly baseUrl: string
+
+ constructor(
+ private readonly token: string,
+ baseUrl: string = CODEBERG_BASE
+ ) {
+ this.baseUrl = baseUrl.replace(/\/+$/, '')
+ }
+
+ private get apiBase(): string {
+ return `${this.baseUrl}/api/v1`
+ }
+
+ private headers(extra: Record = {}): Record {
+ return {
+ Authorization: `token ${this.token}`,
+ Accept: 'application/json',
+ ...extra
+ }
+ }
+
+ private async get(path: string, operation: string): Promise {
+ const res = await fetch(`${this.apiBase}${path}`, {
+ headers: this.headers()
+ })
+ if (!res.ok) throw await ForgejoAPIError.fromResponse(res, operation)
+ return res.json()
+ }
+
+ // --- repo ops ---
+ async listRepos(): Promise {
+ const out: HostRepo[] = []
+ for (let page = 1; ; page++) {
+ const batch = (await this.get(
+ `/user/repos?limit=${REPOS_PER_PAGE}&page=${page}`,
+ 'List repos'
+ )) as GiteaRepo[]
+ out.push(...batch.map(toHostRepo))
+ if (batch.length < REPOS_PER_PAGE) break
+ }
+ return out
+ }
+
+ async getRepo(owner: string, name: string): Promise {
+ const repo = (await this.get(
+ `/repos/${owner}/${name}`,
+ 'Fetch repo'
+ )) as GiteaRepo
+ return toHostRepo(repo)
+ }
+
+ async listBranches(owner: string, name: string): Promise {
+ const branches = (await this.get(
+ `/repos/${owner}/${name}/branches`,
+ 'List branches'
+ )) as { name: string }[]
+ return branches.map(b => b.name)
+ }
+
+ async createRepo(name: string, isPrivate: boolean): Promise {
+ const res = await fetch(`${this.apiBase}/user/repos`, {
+ method: 'POST',
+ headers: this.headers({ 'Content-Type': 'application/json' }),
+ body: JSON.stringify({ name, private: isPrivate, auto_init: true })
+ })
+ if (!res.ok) throw await ForgejoAPIError.fromResponse(res, 'Create repo')
+ return toHostRepo((await res.json()) as GiteaRepo)
+ }
+
+ async getAuthenticatedUser(): Promise {
+ const data = (await this.get('/user', 'Read user')) as {
+ id: number
+ login: string
+ full_name?: string
+ avatar_url?: string
+ }
+ return {
+ id: data.id,
+ login: data.login,
+ name: data.full_name ? data.full_name : null,
+ avatarUrl: data.avatar_url
+ }
+ }
+
+ // --- git-data READ ---
+ async getBranchHeadSha(repo: SyncRepo): Promise {
+ // The refs endpoint returns an array when the path is a prefix match for
+ // multiple refs, or a single object for an exact match.
+ const data = (await this.get(
+ `/repos/${repo.owner}/${repo.name}/git/refs/heads/${repo.branch}`,
+ 'Read ref'
+ )) as { object: { sha: string } } | { object: { sha: string } }[]
+ return Array.isArray(data) ? data[0].object.sha : data.object.sha
+ }
+
+ async getCommitTreeSha(repo: SyncRepo, commitSha: string): Promise {
+ // Forgejo nests the tree sha under `.commit.tree.sha` (GitHub puts it at
+ // the top-level `.tree.sha`).
+ const data = (await this.get(
+ `/repos/${repo.owner}/${repo.name}/git/commits/${commitSha}`,
+ 'Read commit'
+ )) as { commit: { tree: { sha: string } } }
+ return data.commit.tree.sha
+ }
+
+ async getTreeMap(
+ repo: SyncRepo,
+ treeSha: string
+ ): Promise> {
+ // Forgejo paginates large recursive trees via ?page=; follow `truncated`
+ // until the whole tree is read.
+ const out = new Map()
+ for (let page = 1; ; page++) {
+ const data = (await this.get(
+ `/repos/${repo.owner}/${repo.name}/git/trees/${treeSha}?recursive=true&page=${page}`,
+ 'Read tree'
+ )) as {
+ tree: Array<{ path: string; type: string; sha: string }>
+ truncated?: boolean
+ }
+ for (const entry of data.tree) {
+ if (entry.type === 'blob') out.set(entry.path, entry.sha)
+ }
+ if (!data.truncated) break
+ }
+ return out
+ }
+
+ async getBlobContent(repo: SyncRepo, sha: string): Promise {
+ const data = (await this.get(
+ `/repos/${repo.owner}/${repo.name}/git/blobs/${sha}`,
+ `Read blob ${sha}`
+ )) as { content: string; encoding: string }
+ return new TextDecoder('utf-8').decode(base64ToBytes(data.content))
+ }
+
+ // Forgejo/Gitea has no ETag-conditional read layer here, so the cached
+ // variants are plain reads — same result, no caching. (The seam's PULL path
+ // calls these; PUSH uses getTreeMap/getBlobContent.)
+ getTreeMapCached(
+ repo: SyncRepo,
+ treeSha: string
+ ): Promise> {
+ return this.getTreeMap(repo, treeSha)
+ }
+
+ getBlobContentCached(repo: SyncRepo, sha: string): Promise {
+ return this.getBlobContent(repo, sha)
+ }
+
+ async getBlobBytes(repo: SyncRepo, sha: string): Promise {
+ const data = (await this.get(
+ `/repos/${repo.owner}/${repo.name}/git/blobs/${sha}`,
+ `Read binary blob ${sha}`
+ )) as { content: string; encoding: string }
+ return base64ToBytes(data.content)
+ }
+
+ // --- bulk archive (first-clone fast path) ---
+ async fetchArchive(repo: SyncRepo, ref: string): Promise {
+ const res = await fetch(
+ `${this.apiBase}/repos/${repo.owner}/${repo.name}/archive/${ref}.zip`,
+ { headers: this.headers() }
+ )
+ if (!res.ok)
+ throw await ForgejoAPIError.fromResponse(res, 'Download archive')
+ return res.arrayBuffer()
+ }
+
+ // --- git-data WRITE ---
+ // One `POST /contents` with a ChangeFiles batch: every create/update/delete
+ // is a single ChangeFileOperation and the server builds the blobs, tree, and
+ // commit and advances the branch in one shot. Create/update carry base64
+ // content; update/delete carry the current blob sha. An empty change set is
+ // a no-op (syncPush already filters unchanged files), so it makes no network
+ // call and reports committed:false — preserving the no-churn invariant.
+ async commitChanges(
+ repo: SyncRepo,
+ req: CommitRequest
+ ): Promise {
+ if (req.changes.length === 0) {
+ return {
+ commitSha: req.parentSha,
+ commitUrl: null,
+ committed: false,
+ uploadedPaths: []
+ }
+ }
+
+ const files = req.changes.map(change => {
+ if (change.op === 'delete') {
+ return { operation: 'delete', path: change.path, sha: change.sha }
+ }
+ const content = change.contentBytes
+ ? bytesToBase64(change.contentBytes)
+ : utf8ToBase64(change.content ?? '')
+ return change.op === 'update'
+ ? { operation: 'update', path: change.path, content, sha: change.sha }
+ : { operation: 'create', path: change.path, content }
+ })
+
+ const uploadedPaths = req.changes
+ .filter(c => c.op !== 'delete')
+ .map(c => c.path)
+
+ // Forgejo writes are a single request — no per-blob progress.
+ req.onProgress?.({ phase: 'committing' })
+
+ const res = await fetch(
+ `${this.apiBase}/repos/${repo.owner}/${repo.name}/contents`,
+ {
+ method: 'POST',
+ headers: this.headers({ 'Content-Type': 'application/json' }),
+ body: JSON.stringify({
+ branch: req.branch,
+ message: req.message,
+ files
+ })
+ }
+ )
+ if (!res.ok) throw await ForgejoAPIError.fromResponse(res, 'Commit changes')
+ const data = (await res.json()) as {
+ commit: { sha: string; html_url?: string }
+ }
+
+ return {
+ commitSha: data.commit.sha,
+ commitUrl: data.commit.html_url ?? null,
+ committed: true,
+ uploadedPaths
+ }
+ }
+}
diff --git a/src/utils/gitHost/githubProvider.ts b/src/utils/gitHost/githubProvider.ts
new file mode 100644
index 0000000..a591751
--- /dev/null
+++ b/src/utils/gitHost/githubProvider.ts
@@ -0,0 +1,305 @@
+// GitHubProvider: the GitHub implementation of the GitHostProvider seam.
+//
+// This is a mechanical WRAP of the existing functions in `../github.ts` —
+// it delegates every call rather than reimplementing any HTTP. The repo
+// read/write functions in github.ts take `(token, owner, repo, ...)`; this
+// class binds the token at construction and maps a `SyncRepo {owner,name,
+// branch}` onto those positional args.
+//
+// Tree/blob reads delegate to the ETag-conditional wrappers in
+// `../githubETagCache` (which themselves fall back to the bare github.ts
+// helpers on a cold cache), so GitHub's #69 conditional-request caching is
+// encapsulated here and available to any caller of the provider — the pull
+// pipeline never has to know about it. `getBlobBytes` has no conditional
+// variant and stays on the bare helper.
+//
+// `commitChanges` reproduces the existing push flow that `githubSync/
+// syncPush.ts` used to perform inline (createBlob → createTree →
+// createCommit → updateBranchRef), mirroring its semantics: deletes are
+// `sha:null` tree entries, the base tree is resolved from the parent commit,
+// and the branch ref is fast-forwarded. It also keeps the GitHub-specific
+// blob upload-cache and the no-op-tree skip that used to live in syncPush —
+// both are pure GitHub-blob optimizations (Forgejo's ChangeFiles batch sends
+// content directly, so they have no meaning there). See
+// docs/multi-host-sync-plan.md.
+
+import type { SyncRepo, GitHubRepo } from '@/types'
+import {
+ getBranchRefSha,
+ getCommitTreeSha,
+ getTreeMap,
+ getBlobContent,
+ getBlobBytes,
+ fetchZipball,
+ fetchGitHubUser,
+ listUserRepos,
+ listRepoBranches,
+ getRepo as githubGetRepo,
+ createRepo as githubCreateRepo,
+ createBlob,
+ createBlobBinary,
+ createTree,
+ createCommit,
+ updateBranchRef,
+ gitBlobSha,
+ gitBlobShaBytes,
+ type GitTreeEntry
+} from '../github'
+// The plain `getTreeMap`/`getBlobContent` above are the canonical reads used
+// by the PUSH path — byte-identical to pre-seam behavior, no caching layer in
+// the way (a stale tree during a push would risk a non-fast-forward commit).
+// The `*Cached` methods below add the #69 ETag-conditional caching and are
+// used only by the PULL path, where a re-sync of an unchanged repo should come
+// back as cheap 304s. Forgejo has no ETag variant, so its provider aliases the
+// cached methods to the plain reads. getBlobBytes has no conditional variant.
+import {
+ getBlobContentConditional,
+ getTreeMapConditional
+} from '../githubETagCache'
+import type {
+ GitHostProvider,
+ HostKind,
+ HostRepo,
+ HostUser,
+ CommitRequest,
+ CommitResult
+} from './types'
+
+const GITHUB_API_BASE = 'https://api.github.com'
+
+// In-memory cache of blob SHAs we've already uploaded to GitHub in this tab
+// session. Git blob SHAs are content-addressable, so a hit here means GitHub
+// already has that content — skip the redundant network round-trip. Survives
+// across commitChanges calls within the tab (so a token-refresh retry skips
+// blobs the first attempt already uploaded) but is cleared on a reload and
+// after each successful commit. Indexed per-repo so two vaults don't share
+// state. Lives at module scope (not on the instance) so a fresh provider
+// built for a retry still sees the prior attempt's uploads.
+const uploadedBlobShaCache = new Map>()
+
+function repoCacheKey(repo: SyncRepo): string {
+ return `${repo.owner}/${repo.name}#${repo.branch}`
+}
+
+function getUploadedShas(repo: SyncRepo): Set {
+ const key = repoCacheKey(repo)
+ let set = uploadedBlobShaCache.get(key)
+ if (!set) {
+ set = new Set()
+ uploadedBlobShaCache.set(key, set)
+ }
+ return set
+}
+
+/** Test hook. Drops the in-memory upload cache. */
+export function _resetUploadedShaCache(): void {
+ uploadedBlobShaCache.clear()
+}
+
+function toHostRepo(repo: GitHubRepo): HostRepo {
+ return {
+ owner: repo.owner.login,
+ name: repo.name,
+ defaultBranch: repo.default_branch,
+ isPrivate: repo.private
+ }
+}
+
+export class GitHubProvider implements GitHostProvider {
+ readonly kind: HostKind = 'github'
+ readonly baseUrl: string
+
+ constructor(
+ private readonly token: string,
+ baseUrl: string = GITHUB_API_BASE
+ ) {
+ this.baseUrl = baseUrl
+ }
+
+ // --- repo ops ---
+ async listRepos(): Promise {
+ const repos = await listUserRepos(this.token)
+ return repos.map(toHostRepo)
+ }
+
+ async getRepo(owner: string, name: string): Promise {
+ const repo = await githubGetRepo(this.token, owner, name)
+ return toHostRepo(repo)
+ }
+
+ async listBranches(owner: string, name: string): Promise {
+ const branches = await listRepoBranches(this.token, owner, name)
+ return branches.map(b => b.name)
+ }
+
+ async createRepo(name: string, isPrivate: boolean): Promise {
+ const repo = await githubCreateRepo(this.token, name, isPrivate)
+ return toHostRepo(repo)
+ }
+
+ async getAuthenticatedUser(): Promise {
+ const u = await fetchGitHubUser(this.token)
+ return { id: u.id, login: u.login, name: u.name, avatarUrl: u.avatar_url }
+ }
+
+ // --- git-data READ ---
+ getBranchHeadSha(repo: SyncRepo): Promise {
+ return getBranchRefSha(this.token, repo.owner, repo.name, repo.branch)
+ }
+
+ getCommitTreeSha(repo: SyncRepo, commitSha: string): Promise {
+ return getCommitTreeSha(this.token, repo.owner, repo.name, commitSha)
+ }
+
+ getTreeMap(repo: SyncRepo, treeSha: string): Promise> {
+ return getTreeMap(this.token, repo.owner, repo.name, treeSha)
+ }
+
+ getBlobContent(repo: SyncRepo, sha: string): Promise {
+ return getBlobContent(this.token, repo.owner, repo.name, sha)
+ }
+
+ getTreeMapCached(
+ repo: SyncRepo,
+ treeSha: string
+ ): Promise> {
+ return getTreeMapConditional(this.token, repo, treeSha)
+ }
+
+ getBlobContentCached(repo: SyncRepo, sha: string): Promise {
+ return getBlobContentConditional(this.token, repo, sha)
+ }
+
+ getBlobBytes(repo: SyncRepo, sha: string): Promise {
+ return getBlobBytes(this.token, repo.owner, repo.name, sha)
+ }
+
+ // --- bulk archive (first-clone fast path) ---
+ fetchArchive(repo: SyncRepo, ref: string): Promise {
+ return fetchZipball(this.token, repo.owner, repo.name, ref)
+ }
+
+ // --- git-data WRITE ---
+ // Reproduces the existing GitHub push: build a blob per create/update file
+ // (binary via createBlobBinary when contentBytes is set), add a sha:null
+ // tree entry per delete, then createTree(baseTree) → createCommit(parent) →
+ // updateBranchRef. The base tree is the parent commit's tree.
+ //
+ // Two GitHub-blob optimizations carried over from the old inline syncPush
+ // write block:
+ // 1. Upload cache — a create/update whose content blob SHA is already in
+ // the per-repo cache (uploaded earlier this tab session, e.g. before a
+ // token-refresh retry) skips the blob POST and reuses the SHA as its
+ // tree entry. Reported as `skipped` in the progress stream.
+ // 2. No-op-tree skip — if the assembled tree is byte-identical to the
+ // parent's tree (a freshly-cloned note that round-trips to the same
+ // bytes), creating a commit would produce an empty "No files changed"
+ // commit. We skip commit+ref and return `committed:false`.
+ async commitChanges(
+ repo: SyncRepo,
+ req: CommitRequest
+ ): Promise {
+ const { owner, name } = repo
+ const { onProgress } = req
+ const uploadedShas = getUploadedShas(repo)
+ const baseTreeSha = await this.getCommitTreeSha(repo, req.parentSha)
+
+ // Pre-pass: split create/update changes into "cached" (blob already on the
+ // host, no POST) vs "to upload", so we can emit a stable `total`. Deletes
+ // carry no blob. Content blob SHAs are computed locally and are identical
+ // to what GitHub assigns (git content-addressing).
+ interface BlobPlan {
+ change: (typeof req.changes)[number]
+ localSha: string
+ cached: boolean
+ }
+ const blobPlans: BlobPlan[] = []
+ for (const change of req.changes) {
+ if (change.op === 'delete') continue
+ const localSha = change.contentBytes
+ ? await gitBlobShaBytes(change.contentBytes)
+ : await gitBlobSha(change.content ?? '')
+ blobPlans.push({ change, localSha, cached: uploadedShas.has(localSha) })
+ }
+
+ const total = blobPlans.filter(p => !p.cached).length
+ const skipped = blobPlans.filter(p => p.cached).length
+ let uploaded = 0
+ const emit = () =>
+ onProgress?.({ phase: 'uploading-blobs', uploaded, total, skipped })
+ if (total > 0 || skipped > 0) emit()
+
+ // Map every change to a tree entry, uploading blobs that aren't cached.
+ const blobShaByChange = new Map<(typeof req.changes)[number], string>()
+ const uploadedPaths: string[] = []
+ for (const plan of blobPlans) {
+ if (plan.cached) {
+ blobShaByChange.set(plan.change, plan.localSha)
+ continue
+ }
+ const blobSha = plan.change.contentBytes
+ ? await createBlobBinary(
+ this.token,
+ owner,
+ name,
+ new Blob([plan.change.contentBytes.slice()])
+ )
+ : await createBlob(this.token, owner, name, plan.change.content ?? '')
+ uploadedShas.add(plan.localSha)
+ blobShaByChange.set(plan.change, blobSha)
+ uploadedPaths.push(plan.change.path)
+ uploaded++
+ emit()
+ }
+
+ const entries: GitTreeEntry[] = req.changes.map(change =>
+ change.op === 'delete'
+ ? { path: change.path, mode: '100644', type: 'blob', sha: null }
+ : {
+ path: change.path,
+ mode: '100644',
+ type: 'blob',
+ sha: blobShaByChange.get(change)!
+ }
+ )
+
+ onProgress?.({ phase: 'building-tree' })
+ const newTreeSha = await createTree(
+ this.token,
+ owner,
+ name,
+ baseTreeSha,
+ entries
+ )
+
+ // No-op-tree skip: the changes resolved to the parent's exact tree, so a
+ // commit would be empty. Leave the branch untouched and report no commit.
+ if (newTreeSha === baseTreeSha) {
+ uploadedShas.clear()
+ return {
+ commitSha: req.parentSha,
+ commitUrl: null,
+ committed: false,
+ uploadedPaths
+ }
+ }
+
+ onProgress?.({ phase: 'committing' })
+ const { sha: commitSha, html_url } = await createCommit(
+ this.token,
+ owner,
+ name,
+ req.message,
+ newTreeSha,
+ req.parentSha
+ )
+ onProgress?.({ phase: 'updating-ref' })
+ await updateBranchRef(this.token, owner, name, req.branch, commitSha)
+
+ // Push succeeded — start the next push from a clean cache (the remote tree
+ // is consulted again then).
+ uploadedShas.clear()
+
+ return { commitSha, commitUrl: html_url, committed: true, uploadedPaths }
+ }
+}
diff --git a/src/utils/gitHost/index.ts b/src/utils/gitHost/index.ts
new file mode 100644
index 0000000..14760b4
--- /dev/null
+++ b/src/utils/gitHost/index.ts
@@ -0,0 +1,28 @@
+// Public entry point for the git-host abstraction. Re-exports the seam types
+// and both provider implementations, plus the factory that picks a provider
+// from a connection's host kind. The sync pipeline imports `makeGitHostProvider`
+// here rather than constructing a concrete provider, so the active host is a
+// piece of connection state — not a hardcoded `new GitHubProvider`. See
+// docs/multi-host-sync-plan.md → "Data model changes".
+
+import type { GitHostProvider, HostKind } from './types'
+import { GitHubProvider } from './githubProvider'
+import { ForgejoProvider } from './forgejoProvider'
+
+export * from './types'
+export { GitHubProvider } from './githubProvider'
+export { ForgejoProvider } from './forgejoProvider'
+
+/** Build the provider for a connection. GitHub is the default — `baseUrl` is
+ * ignored there. For Forgejo a null/undefined baseUrl falls back to the
+ * provider's own default (codeberg.org). */
+export function makeGitHostProvider(opts: {
+ host: HostKind
+ token: string
+ baseUrl?: string | null
+}): GitHostProvider {
+ if (opts.host === 'forgejo') {
+ return new ForgejoProvider(opts.token, opts.baseUrl ?? undefined)
+ }
+ return new GitHubProvider(opts.token)
+}
diff --git a/src/utils/gitHost/types.ts b/src/utils/gitHost/types.ts
new file mode 100644
index 0000000..389f797
--- /dev/null
+++ b/src/utils/gitHost/types.ts
@@ -0,0 +1,138 @@
+// The host-abstraction seam for vault sync. See
+// docs/multi-host-sync-plan.md → "The seam: GitHostProvider".
+//
+// The whole point: the GitHub push flow (createBlob → createTree →
+// createCommit → updateBranchRef) cannot be ported to Forgejo/Gitea because
+// those create endpoints don't exist there. So the seam does NOT expose
+// git-data write primitives — it exposes a higher-level "commit a batch of
+// file changes" operation each host implements its own way.
+
+import type { SyncRepo, GitHubUser } from '@/types'
+
+export type HostKind = 'github' | 'forgejo'
+
+export interface HostUser {
+ id: string | number
+ login: string
+ name: string | null
+ avatarUrl?: string
+}
+
+export interface HostRepo {
+ owner: string
+ name: string
+ defaultBranch: string
+ isPrivate: boolean
+}
+
+/** One file change in a commit. content is the raw UTF-8 string (provider
+ * handles base64). For deletes, content is omitted. sha is the *current*
+ * blob sha of the file being replaced/deleted (Forgejo requires it;
+ * GitHub ignores it). */
+export interface FileChange {
+ op: 'create' | 'update' | 'delete'
+ path: string
+ content?: string
+ contentBytes?: Uint8Array // for binary attachments
+ sha?: string
+}
+
+// Host-agnostic progress for a single commitChanges call. A multi-request
+// host (GitHub: N blobs + tree + commit + ref) reports each phase; a
+// single-request host (Forgejo ChangeFiles) may only report `committing`.
+// `uploading-blobs` carries running counts so the caller can render
+// "uploaded 47 / 200 (3 skipped)". The caller translates these back into
+// whatever external progress shape it exposes.
+export type CommitProgress =
+ | {
+ phase: 'uploading-blobs'
+ uploaded: number
+ total: number
+ skipped: number
+ }
+ | { phase: 'building-tree' }
+ | { phase: 'committing' }
+ | { phase: 'updating-ref' }
+
+export interface CommitRequest {
+ branch: string
+ parentSha: string // expected current head (optimistic FF)
+ message: string
+ changes: FileChange[]
+ // Optional host-agnostic progress hook. Hosts emit the phases they
+ // actually perform; absent phases simply aren't reported.
+ onProgress?: (event: CommitProgress) => void
+}
+
+export interface CommitResult {
+ commitSha: string
+ commitUrl: string | null
+ // False when the host determined the change set was a no-op (e.g. the
+ // built tree was byte-identical to the parent's tree, so no commit was
+ // created and the branch was left untouched). commitSha then equals the
+ // parent sha. True when a real commit advanced the branch.
+ committed: boolean
+ // Paths whose create/update content was actually transmitted to the host
+ // (as opposed to satisfied from a same-session content cache). On GitHub a
+ // path is absent here when its blob was already uploaded earlier this tab
+ // session (a token-refresh retry) and reused. Hosts with no content cache
+ // list every create/update path. The caller uses this to mirror the prior
+ // syncPush behavior of only recording a path-metadata update for paths it
+ // genuinely pushed in this attempt.
+ uploadedPaths: string[]
+}
+
+export interface GitHostProvider {
+ readonly kind: HostKind
+ readonly baseUrl: string // e.g. https://api.github.com | https://codeberg.org
+
+ // --- repo ops ---
+ listRepos(): Promise
+ getRepo(owner: string, name: string): Promise
+ listBranches(owner: string, name: string): Promise
+ createRepo(name: string, isPrivate: boolean): Promise
+
+ // --- git-data READ (near-identical across hosts) ---
+ getBranchHeadSha(repo: SyncRepo): Promise
+ getCommitTreeSha(repo: SyncRepo, commitSha: string): Promise
+ getTreeMap(repo: SyncRepo, treeSha: string): Promise> // path -> blobSha
+ getBlobContent(repo: SyncRepo, sha: string): Promise
+ getBlobBytes(repo: SyncRepo, sha: string): Promise
+
+ // Cached read variants for the PULL path: same result as getTreeMap /
+ // getBlobContent, but a host may layer caching on top (GitHub uses #69
+ // ETag-conditional requests). The PUSH path must use the plain reads above
+ // — a stale tree would risk a non-fast-forward commit — so only pull uses
+ // these. Hosts without a caching layer (Forgejo) alias them to plain reads.
+ getTreeMapCached(
+ repo: SyncRepo,
+ treeSha: string
+ ): Promise>
+ getBlobContentCached(repo: SyncRepo, sha: string): Promise
+
+ // --- bulk archive (first-clone fast path) ---
+ // Optional whole-repo archive download for the first-clone fast path
+ // (GitHub: zipball; Forgejo: GET /archive/{ref}.zip, or omit). Returns the
+ // raw archive bytes; the caller unzips. Hosts without an archive endpoint
+ // leave this undefined and the caller falls back to the per-blob pull.
+ fetchArchive?(repo: SyncRepo, ref: string): Promise
+
+ // The authenticated user behind the token. Used by the connect flow to
+ // populate the session identity host-agnostically.
+ getAuthenticatedUser(): Promise
+
+ // --- git-data WRITE (the one real divergence) ---
+ commitChanges(repo: SyncRepo, req: CommitRequest): Promise
+}
+
+// Bridge the host-agnostic HostUser onto the store's existing GitHubUser shape
+// (avatarUrl -> avatar_url, id coerced to number). Lets the store keep its
+// current type while the connect flow stays host-agnostic.
+export function hostUserToGitHubUser(u: HostUser): GitHubUser {
+ return {
+ id: typeof u.id === 'number' ? u.id : Number(u.id) || 0,
+ login: u.login,
+ name: u.name,
+ avatar_url: u.avatarUrl ?? ''
+ }
+}
diff --git a/src/utils/githubSync/syncPull.ts b/src/utils/githubSync/syncPull.ts
index 3831211..d94e1f5 100644
--- a/src/utils/githubSync/syncPull.ts
+++ b/src/utils/githubSync/syncPull.ts
@@ -11,20 +11,10 @@
import type JSZip from 'jszip'
import type { Note, SyncRepo } from '@/types'
import {
- getBranchRefSha,
- getCommitTreeSha,
gitBlobSha,
gitBlobShaBytes,
- fetchZipball,
} from '../github'
-// #69: pull-side blob/tree reads go through the ETag-conditional wrappers
-// so a re-sync of an unchanged repo comes back as 304s and doesn't burn
-// quota. Push-side reads in `syncPush.ts` still call the bare helpers from
-// `../github` — the cache is read-side only.
-import {
- getBlobContentConditional,
- getTreeMapConditional,
-} from '../githubETagCache'
+import type { GitHostProvider } from '../gitHost/types'
import { threeWayMerge } from '../lineDiff'
import {
isAttachmentPath,
@@ -54,7 +44,12 @@ function sameTagSet(a: string[], b: string[]): boolean {
}
export async function pullFromGitHub(input: {
- token: string
+ // Host abstraction for every remote read. The pull pipeline calls
+ // provider.* and never branches on host kind; the GitHubProvider
+ // encapsulates GitHub's ETag-conditional caching (#69) behind
+ // getTreeMapCached / getBlobContentCached so re-syncs of an unchanged
+ // repo still come back as 304s.
+ provider: GitHostProvider
repo: SyncRepo
notes: Note[]
folders: import('@/types').Folder[]
@@ -83,15 +78,14 @@ export async function pullFromGitHub(input: {
// own progress via the onPhase callback wired in useGitHubSync.
onBlobProgress?: (loaded: number, total: number) => void
}): Promise {
- const { token, repo, notes } = input
+ const { provider, repo, notes } = input
const excluded = input.excludedFolderPaths ?? []
const vaultSettingsPath = input.vaultSettingsPath ?? null
const vaultSettingsLocalUpdatedAt = input.vaultSettingsLocalUpdatedAt ?? 0
const isFirstClone = input.isFirstClone ?? false
- const { owner, name, branch } = repo
- const headSha = await getBranchRefSha(token, owner, name, branch)
- const treeSha = await getCommitTreeSha(token, owner, name, headSha)
- const remoteTree = await getTreeMapConditional(token, repo, treeSha)
+ const headSha = await provider.getBranchHeadSha(repo)
+ const treeSha = await provider.getCommitTreeSha(repo, headSha)
+ const remoteTree = await provider.getTreeMapCached(repo, treeSha)
// Build the gitignore matcher BEFORE walking the tree so step 1's
// .md loop can short-circuit on ignored paths. The matcher is also
@@ -111,7 +105,7 @@ export async function pullFromGitHub(input: {
let remoteRaw = ''
if (gitignoreSha) {
try {
- remoteRaw = await getBlobContentConditional(token, repo, gitignoreSha)
+ remoteRaw = await provider.getBlobContentCached(repo, gitignoreSha)
} catch {
remoteRaw = ''
}
@@ -219,7 +213,7 @@ export async function pullFromGitHub(input: {
// didn't cover). The conditional read may itself be served from the
// ETag cache and short-circuit before hitting the network. decrypt
// runs here either way.
- const raw = prefetchedBlobs.get(remoteSha) ?? await getBlobContentConditional(token, repo, remoteSha)
+ const raw = prefetchedBlobs.get(remoteSha) ?? await provider.getBlobContentCached(repo, remoteSha)
remoteContent = await maybeDecryptFromPull(raw)
}
return remoteContent
@@ -398,14 +392,14 @@ export async function pullFromGitHub(input: {
// and remote edits don't overlap line-wise we can auto-merge and the
// user never sees the conflict tab. The common ancestor is the REMOTE
// blob we last synced against (`gitRemoteBaseSha`, fetchable via
- // getBlobContentConditional) — NOT gitLastPushedSha, which is the SHA of
+ // provider.getBlobContentCached) — NOT gitLastPushedSha, which is the SHA of
// the transformed local bytes and may not exist as a remote blob at all.
// Anything that goes wrong (no ancestor sha, blob GC'd, network hiccup,
// overlapping edits) falls back to the existing manual conflict flow.
let autoMerged: string | null = null
if (remoteBase) {
try {
- const ancestorRaw = await getBlobContentConditional(token, repo, remoteBase)
+ const ancestorRaw = await provider.getBlobContentCached(repo, remoteBase)
const ancestor = await maybeDecryptFromPull(ancestorRaw)
const merged = threeWayMerge(ancestor, localContent, content)
if (merged.ok) autoMerged = merged.merged
@@ -508,7 +502,7 @@ export async function pullFromGitHub(input: {
const remoteSettingsSha = remoteTree.get(vaultSettingsPath)
if (remoteSettingsSha) {
try {
- const raw = await getBlobContentConditional(token, repo, remoteSettingsSha)
+ const raw = await provider.getBlobContentCached(repo, remoteSettingsSha)
const { parseVaultSettings, vaultSettingsHash, pickVaultSlice, serializeVaultSettings } = await import('../vaultSettings')
const parsed = parseVaultSettings(raw)
if (parsed && parsed.updatedAt > vaultSettingsLocalUpdatedAt) {
@@ -689,19 +683,29 @@ export async function pullFromGitHub(input: {
// same SHA-1 of `blob \0`), so a separate tree fetch isn't
// necessary.
export async function pullFromZipball(input: {
- token: string
+ // Host abstraction. The archive download goes through provider.fetchArchive
+ // (GitHub: zipball). A provider without an archive endpoint can't take this
+ // fast path — callers gate on `provider.fetchArchive` before choosing it.
+ provider: GitHostProvider
repo: SyncRepo
// Phase hint so the caller can surface "Downloading vault (retrying)…" when
// a corrupted/truncated archive triggers a re-download. Optional — the retry
// loop works regardless.
onPhase?: (msg: string) => void
}): Promise {
- const { token, repo, onPhase } = input
- const { owner, name, branch } = repo
+ const { provider, repo, onPhase } = input
+ const { branch } = repo
+
+ // This fast path only exists for hosts with a whole-repo archive endpoint.
+ // Callers gate on provider.fetchArchive; guard here at the boundary so a
+ // mis-wired caller fails loudly rather than throwing an opaque TypeError.
+ if (!provider.fetchArchive) {
+ throw new Error(`pullFromZipball: provider "${provider.kind}" has no archive endpoint`)
+ }
// The ref is cheap and we need it for `latestCommitSha` regardless — fetch
// it once up front, independent of the archive retry loop below.
- const headSha = await getBranchRefSha(token, owner, name, branch)
+ const headSha = await provider.getBranchHeadSha(repo)
// Lazy-load jszip — only callers of pullFromZipball pay the
// ~140kB cost. The rest of the sync flow (push, regular pull via
@@ -723,7 +727,7 @@ export async function pullFromZipball(input: {
let attempt = 0
for (;;) {
try {
- const zipBuffer = await fetchZipball(token, owner, name, branch)
+ const zipBuffer = await provider.fetchArchive(repo, branch)
zip = await JSZip.loadAsync(zipBuffer)
break
} catch (err) {
diff --git a/src/utils/githubSync/syncPush.ts b/src/utils/githubSync/syncPush.ts
index c3a3d3e..7cef902 100644
--- a/src/utils/githubSync/syncPush.ts
+++ b/src/utils/githubSync/syncPush.ts
@@ -8,19 +8,9 @@
// from `@/utils/githubSync`.
import type { Note, SyncRepo } from '@/types'
-import {
- getBranchRefSha,
- getCommitTreeSha,
- getTreeMap,
- createBlob,
- createBlobBinary,
- createTree,
- createCommit,
- updateBranchRef,
- getBlobContent,
- gitBlobSha,
- type GitTreeEntry,
-} from '../github'
+import { gitBlobSha } from '../github'
+import type { GitHostProvider, FileChange, CommitProgress } from '../gitHost/types'
+import { _resetUploadedShaCache } from '../gitHost/githubProvider'
import {
listAttachmentPathsTracked,
getAttachmentBlob,
@@ -49,7 +39,10 @@ export type PushProgress =
| { phase: 'done' }
export interface SyncInput {
- token: string
+ // Host abstraction for the final write. syncToGitHub builds a host-neutral
+ // FileChange[] and hands it to provider.commitChanges; the provider turns it
+ // into commits its host's way (GitHub: blob/tree/commit/ref).
+ provider: GitHostProvider
repo: SyncRepo
notes: Note[]
folders: import('@/types').Folder[]
@@ -79,32 +72,10 @@ export interface SyncInput {
onProgress?: (event: PushProgress) => void
}
-// In-memory cache of blob SHAs we've already uploaded to GitHub in this
-// tab session. Git blob SHAs are content-addressable, so a hit here
-// means GitHub already has that content — skip the redundant network
-// round-trip. Survives across syncToGitHub calls within the tab but is
-// cleared when the user reloads. Indexed per-repo so two different
-// vaults don't share state.
-const uploadedBlobShaCache = new Map>()
-
-function repoCacheKey(repo: SyncRepo): string {
- return `${repo.owner}/${repo.name}#${repo.branch}`
-}
-
-function getUploadedShas(repo: SyncRepo): Set {
- const key = repoCacheKey(repo)
- let set = uploadedBlobShaCache.get(key)
- if (!set) {
- set = new Set()
- uploadedBlobShaCache.set(key, set)
- }
- return set
-}
-
-/** Test hook. Drops the in-memory upload cache. */
-export function _resetUploadedShaCache(): void {
- uploadedBlobShaCache.clear()
-}
+// The blob upload-cache now lives in GitHubProvider (it is a GitHub-blob
+// optimization). Re-exported here so the public test hook keeps its import
+// path (`@/utils/githubSync`).
+export { _resetUploadedShaCache }
export type GitPathUpdate = {
noteId: string
@@ -137,9 +108,8 @@ export interface SyncOutcome {
}
export async function syncToGitHub(input: SyncInput): Promise {
- const { token, repo, notes, folders, commitMessage, vaultSettings, vaultGitignoreDraft, onProgress } = input
- const { owner, name, branch } = repo
- const uploadedShas = getUploadedShas(repo)
+ const { provider, repo, notes, folders, commitMessage, vaultSettings, vaultGitignoreDraft, onProgress } = input
+ const { branch } = repo
onProgress?.({ phase: 'computing' })
// 1. Compute desired files for every active note.
@@ -184,10 +154,12 @@ export async function syncToGitHub(input: SyncInput): Promise {
desired.set(path, { content, note })
}
- // 2. Fetch the current branch state.
- const parentCommitSha = await getBranchRefSha(token, owner, name, branch)
- const baseTreeSha = await getCommitTreeSha(token, owner, name, parentCommitSha)
- const remoteTree = await getTreeMap(token, owner, name, baseTreeSha)
+ // 2. Fetch the current branch state. PLAIN reads (not the pull path's
+ // ETag-conditional variants) — a stale tree here risks a non-fast-forward
+ // commit, so push always talks to the live remote state.
+ const parentCommitSha = await provider.getBranchHeadSha(repo)
+ const baseTreeSha = await provider.getCommitTreeSha(repo, parentCommitSha)
+ const remoteTree = await provider.getTreeMap(repo, baseTreeSha)
// Layered gitignore matcher for push (gi9n): defaults + remote +
// local overlay. Same composition as the pull side so push and pull
@@ -198,7 +170,7 @@ export async function syncToGitHub(input: SyncInput): Promise {
let pushRemoteRaw = ''
if (remoteGitignoreSha) {
try {
- pushRemoteRaw = await getBlobContent(token, owner, name, remoteGitignoreSha)
+ pushRemoteRaw = await provider.getBlobContent(repo, remoteGitignoreSha)
} catch {
pushRemoteRaw = ''
}
@@ -216,23 +188,34 @@ export async function syncToGitHub(input: SyncInput): Promise {
// Defaults already applied above.
}
- // 3. Build tree entries for changes only.
- const entries: GitTreeEntry[] = []
+ // 3. Build the host-neutral change set for CHANGED files only. Unchanged
+ // files are NOT listed — the host carries them forward from the parent
+ // tree, so a no-churn sync produces an empty `changes` and never touches
+ // the host (see the early return below).
+ const changes: FileChange[] = []
const pathUpdates: GitPathUpdate[] = []
let created = 0
let updated = 0
let deleted = 0
+ // Path-metadata updates for genuinely-changed notes are recorded as
+ // candidates here and committed AFTER the push, gated on whether the host
+ // actually transmitted that path's content this attempt (CommitResult
+ // .uploadedPaths). This mirrors the old behavior where a note whose blob
+ // was served from the same-session upload cache got a tree entry but NO
+ // pathUpdate.
+ const uploadedNotePathUpdate = new Map()
+
// We snapshot per-note pushed content so the editor's gutter diff
// (109) can compare against it. The IDB write is fire-and-forget
// outside the loop — collect first, write after the loop ends to
// avoid serial awaits per note.
const lastPushedToSnapshot: Array<{ noteId: string; content: string }> = []
- // Pre-pass: classify every desired path into "skip" (remote already
- // has this SHA, or our in-tab cache says we uploaded it) vs "needs
- // upload". Keeping the pre-pass separate lets us emit a stable
- // `total` to the progress callback.
+ // Pre-pass: classify every desired path into "skip" (remote already has
+ // this SHA, or the note wasn't genuinely edited) vs "push". Keeping this
+ // separate from the host write lets the genuine-edit / normalization-churn
+ // logic stay here while the provider owns the actual blob upload + dedupe.
//
// push-only-real-edits: the upload decision must reflect a GENUINE local
// edit, not just a wire-form mismatch against the remote blob. The remote
@@ -248,8 +231,8 @@ export async function syncToGitHub(input: SyncInput): Promise {
// canonical SHA as of the last sync). When they match the body is byte-equal
// to what we last synced → NO genuine edit. A null baseline means a
// new/never-synced note → MUST push. We use `plainSha` (NOT the wire/encrypted
- // sha) ONLY for this change decision; `localSha` (wire) is still what we
- // hash, upload and dedupe against `uploadedShas`/`remoteSha`.
+ // sha) ONLY for this change decision; `localSha` (wire) is the git content sha
+ // we compare against `remoteSha` to decide whether the file actually changed.
interface NoteBlobPlan { path: string; content: string; note: Note; localSha: string; remoteSha: string | undefined; locallyChanged: boolean }
const noteBlobPlan: NoteBlobPlan[] = []
for (const [path, { content, note }] of desired) {
@@ -287,7 +270,7 @@ export async function syncToGitHub(input: SyncInput): Promise {
if (locallyChanged && baseline !== null && remoteSha !== undefined && baseline === remoteSha) {
try {
const remoteRawBody = await maybeDecryptFromPull(
- await getBlobContent(token, owner, name, remoteSha),
+ await provider.getBlobContent(repo, remoteSha),
)
if (isUnchangedModuloNormalization(content, remoteRawBody)) {
locallyChanged = false
@@ -300,47 +283,53 @@ export async function syncToGitHub(input: SyncInput): Promise {
noteBlobPlan.push({ path, content: wireContent, note, localSha, remoteSha, locallyChanged })
}
- // push-only-real-edits: SUPPRESS the upload for a note that is NOT locally
- // changed AND already has a remote blob at this path. We emit NO tree entry
- // for it, so the base tree's existing (user's original, possibly
- // non-canonical) blob is preserved untouched — zero rewrite. We STILL push
- // when the note is locally changed (a real edit) OR has no remote blob yet
- // (`remoteSha === undefined`: a brand-new note, or a note moved to a new path
- // — the move's old-path deletion is handled by the deletion loop in step 4).
+ // push-only-real-edits: SUPPRESS the push for a note that is NOT locally
+ // changed AND already has a remote blob at this path. We emit NO change for
+ // it, so the base tree's existing (user's original, possibly non-canonical)
+ // blob is preserved untouched — zero rewrite. We STILL push when the note is
+ // locally changed (a real edit) OR has no remote blob yet (`remoteSha ===
+ // undefined`: a brand-new note, or a note moved to a new path — the move's
+ // old-path deletion is handled by the deletion loop in step 4).
const noteBlobsSuppressed = noteBlobPlan.filter(p => !p.locallyChanged && p.remoteSha !== undefined && p.remoteSha !== p.localSha)
const suppressedNoteIds = new Set(noteBlobsSuppressed.map(p => p.note.id))
- const noteBlobsToUpload = noteBlobPlan.filter(p => !suppressedNoteIds.has(p.note.id) && p.remoteSha !== p.localSha && !uploadedShas.has(p.localSha))
- const noteBlobsCached = noteBlobPlan.filter(p => !suppressedNoteIds.has(p.note.id) && p.remoteSha !== p.localSha && uploadedShas.has(p.localSha))
- let blobsUploaded = 0
- let blobsSkipped = noteBlobsCached.length
- // Use a single running `total` that we refine after the attachment
- // pre-pass below. For now: just notes.
- let blobsTotal = noteBlobsToUpload.length
-
- const emitBlobProgress = () => {
- onProgress?.({ phase: 'uploading-blobs', uploaded: blobsUploaded, total: blobsTotal, skipped: blobsSkipped })
- }
-
- // Apply the cached-skip entries first — no network, just emit tree entries
- // and bookkeeping.
- for (const plan of noteBlobsCached) {
- entries.push({ path: plan.path, mode: '100644', type: 'blob', sha: plan.localSha })
+ // Genuinely-changed notes (remoteSha differs from what we'd push, and not
+ // suppressed) become create/update FileChanges. The provider owns the blob
+ // upload + same-session content cache; here we just describe WHAT changed.
+ for (const plan of noteBlobPlan) {
+ if (suppressedNoteIds.has(plan.note.id)) continue
+ if (plan.remoteSha === plan.localSha) continue
+ changes.push({
+ op: plan.remoteSha ? 'update' : 'create',
+ path: plan.path,
+ content: plan.content,
+ // Forgejo's ChangeFiles requires the current blob sha when updating an
+ // existing file; GitHub ignores it. Undefined for a create (no remote
+ // file yet), matching the delete path which also carries remoteSha.
+ sha: plan.remoteSha,
+ })
if (plan.remoteSha) updated++; else created++
+ // Candidate pathUpdate — committed after the push only if the provider
+ // actually transmitted this path's content this attempt (uploadedPaths).
+ // After a push the pushed blob IS the remote file, so the local baseline
+ // and the remote merge base coincide — set both to localSha (== the git
+ // content sha the host stores).
+ if (plan.note.gitPath !== plan.path || plan.note.gitLastPushedSha !== plan.localSha || plan.note.gitRemoteBaseSha !== plan.localSha) {
+ uploadedNotePathUpdate.set(plan.path, { noteId: plan.note.id, gitPath: plan.path, gitLastPushedSha: plan.localSha, gitRemoteBaseSha: plan.localSha })
+ }
}
- // Pure-skip entries (remote has this SHA): no entry, no upload, but the
- // note's path metadata may still need an update. The lastPushedSnapshot
- // gets the PLAINTEXT body (gutter compares against unencrypted text).
+ // Pure-skip notes (remote already has this SHA): no change, but the note's
+ // path metadata may still need an update. The lastPushedSnapshot gets the
+ // PLAINTEXT body (gutter compares against unencrypted text).
//
// push-only-real-edits: a SUPPRESSED note (unchanged but its canonical wire
// SHA differs from the non-canonical remote blob) is left ENTIRELY untouched:
- // no tree entry (handled by the filters above) AND no pathUpdate. Emitting a
- // pathUpdate here would rewrite gitLastPushedSha to `finalSha` (the wire SHA),
- // overwriting the canonical baseline syncApply pinned — which would make the
- // NEXT pull misclassify the note (localChanged would flip on every sync). The
- // note did not change, so we leave gitPath / gitLastPushedSha / gitRemoteBaseSha
- // exactly as they are. We still take a gutter snapshot (body is unchanged, so
- // the plaintext is correct).
+ // no change AND no pathUpdate. Emitting a pathUpdate here would rewrite
+ // gitLastPushedSha to the wire SHA, overwriting the canonical baseline
+ // syncApply pinned — which would make the NEXT pull misclassify the note
+ // (localChanged would flip on every sync). The note did not change, so we
+ // leave gitPath / gitLastPushedSha / gitRemoteBaseSha exactly as they are. We
+ // still take a gutter snapshot (body is unchanged, so the plaintext is correct).
for (const plan of noteBlobPlan) {
const suppressed = suppressedNoteIds.has(plan.note.id)
const skipped = plan.remoteSha === plan.localSha
@@ -360,25 +349,6 @@ export async function syncToGitHub(input: SyncInput): Promise {
}
}
- // Upload the genuinely-changed blobs.
- if (blobsTotal > 0) emitBlobProgress()
- for (const plan of noteBlobsToUpload) {
- const finalSha = await createBlob(token, owner, name, plan.content)
- // Cache by LOCAL SHA — that's what the next iteration computes from
- // the same content. (In production localSha === serverSha because
- // both follow git's content-addressing, but the local key is what
- // gates the next cache lookup.)
- uploadedShas.add(plan.localSha)
- entries.push({ path: plan.path, mode: '100644', type: 'blob', sha: finalSha })
- if (plan.remoteSha) updated++; else created++
- if (plan.note.gitPath !== plan.path || plan.note.gitLastPushedSha !== finalSha || plan.note.gitRemoteBaseSha !== finalSha) {
- // Pushed blob == remote file → both SHAs coincide.
- pathUpdates.push({ noteId: plan.note.id, gitPath: plan.path, gitLastPushedSha: finalSha, gitRemoteBaseSha: finalSha })
- }
- blobsUploaded++
- emitBlobProgress()
- }
-
// Fire-and-forget the per-note snapshot writes. The gutter will pick
// them up on the next render — we don't await because a slow IDB
// flush shouldn't block the push completing.
@@ -389,10 +359,10 @@ export async function syncToGitHub(input: SyncInput): Promise {
}
})()
- // 3b. Local attachments → binary blob entries. Push uploads any local
- // attachment whose SHA differs from the remote. Files only present
- // locally get created remotely; files present in both get updated when
- // their content drifts. Same upload-cache + progress treatment as notes.
+ // 3b. Local attachments → binary FileChanges. Push uploads any local
+ // attachment whose SHA differs from the remote. Files only present locally
+ // get created remotely; files present in both get updated when their content
+ // drifts. The provider handles the binary blob upload + content cache.
//
// attachment-timeout-retry: a stalled IDB read (mobile Safari) must not
// silently look like "zero local attachments" — that would push a commit
@@ -400,10 +370,10 @@ export async function syncToGitHub(input: SyncInput): Promise {
// nothing would ever retry it (the attachment was already durably saved
// locally, just never uploaded). So the *Tracked reads report `timedOut`
// and, the moment any one of them fires, we abort the ENTIRE attachment
- // section for this cycle: no partial plan, no tree entries, no
- // `uploadedShas` writes. Because nothing gets marked as pushed, the next
- // sync's 3b runs exactly as if this one never attempted it — that's what
- // makes the retry automatic without a dedicated retry-queue.
+ // section for this cycle: no partial plan, no FileChanges, no bookkeeping.
+ // Because nothing gets marked as pushed, the next sync's 3b runs exactly as
+ // if this one never attempted it — that's what makes the retry automatic
+ // without a dedicated retry-queue.
let attachmentSyncSkipped = false
const { value: localAttachmentPaths, timedOut: listTimedOut } = await listAttachmentPathsTracked()
if (listTimedOut) attachmentSyncSkipped = true
@@ -427,30 +397,16 @@ export async function syncToGitHub(input: SyncInput): Promise {
attachmentPlan.push({ path, localSha, remoteSha })
}
const effectiveAttachmentPlan = attachmentSyncSkipped ? [] : attachmentPlan
- const attachmentsToUpload = effectiveAttachmentPlan.filter(p => p.remoteSha !== p.localSha && !uploadedShas.has(p.localSha))
- const attachmentsCached = effectiveAttachmentPlan.filter(p => p.remoteSha !== p.localSha && uploadedShas.has(p.localSha))
- blobsTotal += attachmentsToUpload.length
- blobsSkipped += attachmentsCached.length
- if (blobsTotal > 0 || blobsSkipped > 0) emitBlobProgress()
if (attachmentSyncSkipped) {
console.warn('[syncPush] attachment sync skipped this cycle (IndexedDB stalled) — will retry next sync.')
}
-
- for (const plan of attachmentsCached) {
- entries.push({ path: plan.path, mode: '100644', type: 'blob', sha: plan.localSha })
- if (plan.remoteSha) updated++; else created++
- }
- for (const plan of attachmentsToUpload) {
+ for (const plan of effectiveAttachmentPlan) {
+ if (plan.remoteSha === plan.localSha) continue
const blob = await getAttachmentBlob(plan.path)
if (!blob) continue
- const uploadedSha = await createBlobBinary(token, owner, name, blob)
- // See the note loop above: cache the LOCAL sha for the next-pass
- // lookup, which uses local-side hashing.
- uploadedShas.add(plan.localSha)
- entries.push({ path: plan.path, mode: '100644', type: 'blob', sha: uploadedSha })
+ const contentBytes = new Uint8Array(await blob.arrayBuffer())
+ changes.push({ op: plan.remoteSha ? 'update' : 'create', path: plan.path, contentBytes, sha: plan.remoteSha })
if (plan.remoteSha) updated++; else created++
- blobsUploaded++
- emitBlobProgress()
}
// 3c. Apply attachment tombstones — paths the user explicitly deleted
@@ -466,8 +422,9 @@ export async function syncToGitHub(input: SyncInput): Promise {
const tombstones = attachmentSyncSkipped ? [] : await getAttachmentTombstones()
const consumedTombstones: string[] = []
for (const path of tombstones) {
- if (remoteTree.has(path)) {
- entries.push({ path, mode: '100644', type: 'blob', sha: null })
+ const remoteSha = remoteTree.get(path)
+ if (remoteSha !== undefined) {
+ changes.push({ op: 'delete', path, sha: remoteSha })
deleted++
}
consumedTombstones.push(path)
@@ -479,8 +436,7 @@ export async function syncToGitHub(input: SyncInput): Promise {
// the no-change case keeps idle syncs commit-free.
let vaultGitignorePushed = false
if (vaultGitignoreDraft != null && vaultGitignoreDraft !== pushRemoteRaw) {
- const blobSha = await createBlob(token, owner, name, vaultGitignoreDraft)
- entries.push({ path: GITIGNORE_PATH, mode: '100644', type: 'blob', sha: blobSha })
+ changes.push({ op: remoteGitignoreSha ? 'update' : 'create', path: GITIGNORE_PATH, content: vaultGitignoreDraft, sha: remoteGitignoreSha })
if (remoteGitignoreSha) updated++; else created++
vaultGitignorePushed = true
}
@@ -496,8 +452,7 @@ export async function syncToGitHub(input: SyncInput): Promise {
const remoteHasFile = remoteTree.has(path)
const localChanged = contentHash !== lastPushedHash
if (localChanged || !remoteHasFile) {
- const blobSha = await createBlob(token, owner, name, content)
- entries.push({ path, mode: '100644', type: 'blob', sha: blobSha })
+ changes.push({ op: remoteHasFile ? 'update' : 'create', path, content, sha: remoteTree.get(path) })
if (remoteHasFile) updated++; else created++
vaultSettingsHashPushed = contentHash
} else {
@@ -513,10 +468,10 @@ export async function syncToGitHub(input: SyncInput): Promise {
const seenGitPaths = new Set()
// rename-not-delete HARD PUSH-SIDE SAFETY NET (the critical data-loss
- // preventer). Before we emit ANY `sha:null` delete, build the set of remote
- // paths that a LIVE (non-deleted) note still represents. A remote file at
- // such a path MUST NOT be deleted, even if some upstream classification was
- // wrong (e.g. a rename misread as a delete that soft-deleted the note).
+ // preventer). Before we emit ANY delete, build the set of remote paths
+ // that a LIVE (non-deleted) note still represents. A remote file at such a
+ // path MUST NOT be deleted, even if some upstream classification was wrong
+ // (e.g. a rename misread as a delete that soft-deleted the note).
//
// A path is protected when EITHER:
// (a) it is in `desired` — an active note's CURRENT computed path maps to
@@ -567,7 +522,7 @@ export async function syncToGitHub(input: SyncInput): Promise {
// Safety net: never delete a path a live note still represents (by
// content), even though this note's CURRENT path moved away from it.
if (protectedRemotePaths.has(note.gitPath)) continue
- entries.push({ path: note.gitPath, mode: '100644', type: 'blob', sha: null })
+ changes.push({ op: 'delete', path: note.gitPath, sha: remoteTree.get(note.gitPath) })
deleted++
}
}
@@ -578,7 +533,7 @@ export async function syncToGitHub(input: SyncInput): Promise {
if (note.kind === 'foreign') continue
// do-not-sync (#179): a flagged note never touches the remote, deletes
// included. Soft-deleting the seeded tour note locally must not emit a
- // sha:null for a legacy user's remote copy — remote cleanup is manual.
+ // delete for a legacy user's remote copy — remote cleanup is manual.
// Skipping also leaves its git fields intact in case it is restored.
if (note.doNotSync) continue
if (note.isDeleted && note.gitPath && remoteTree.has(note.gitPath)) {
@@ -592,15 +547,17 @@ export async function syncToGitHub(input: SyncInput): Promise {
!seenGitPaths.has(note.gitPath) &&
!protectedRemotePaths.has(note.gitPath)
) {
- entries.push({ path: note.gitPath, mode: '100644', type: 'blob', sha: null })
+ changes.push({ op: 'delete', path: note.gitPath, sha: remoteTree.get(note.gitPath) })
deleted++
}
pathUpdates.push({ noteId: note.id, gitPath: null, gitLastPushedSha: null, gitRemoteBaseSha: null })
}
}
- if (entries.length === 0) {
- // Even with no tree changes, clear stale tombstones (files already gone
+ if (changes.length === 0) {
+ // No changed files → nothing to commit. The host carries the whole tree
+ // forward unchanged, so we never touch it (the no-churn invariant: 0
+ // network calls). Even so, clear stale tombstones (files already gone
// remotely) so they don't re-attempt every sync.
if (consumedTombstones.length > 0) await clearAttachmentTombstones(consumedTombstones)
return {
@@ -611,46 +568,67 @@ export async function syncToGitHub(input: SyncInput): Promise {
}
}
- // 5. Create new tree → commit → fast-forward branch. Each step gets
- // its own progress event so the UI (and any error) can pinpoint where
- // a failure happened.
- onProgress?.({ phase: 'creating-tree' })
- const newTreeSha = await createTree(token, owner, name, baseTreeSha, entries)
- // Some "changed" entries can resolve to a blob byte-identical to what the
- // base tree already holds (e.g. a freshly-cloned note that round-trips to
- // the same bytes on the first sync). GitHub then returns a tree equal to the
- // base, so committing it would create an EMPTY "Sync from Noteser (1 change)"
- // commit — "No files changed" — cluttering the history on every initial sync
- // (and, with discard-on-switch re-cloning, on every repo switch). Skip the
- // commit entirely when the tree did not actually change.
- if (newTreeSha === baseTreeSha) {
- if (consumedTombstones.length > 0) await clearAttachmentTombstones(consumedTombstones)
- uploadedShas.clear()
- onProgress?.({ phase: 'done' })
+ // 5. Hand the change set to the host. provider.commitChanges turns it into
+ // a commit its host's way (GitHub: blob/tree/commit/ref). We translate its
+ // host-agnostic progress back into the external PushProgress stream so the
+ // UI sequence is unchanged.
+ const total = created + updated + deleted
+ const autoMessage = `Sync from Noteser (${total} change${total === 1 ? '' : 's'})`
+ const message = commitMessage && commitMessage.length > 0 ? commitMessage : autoMessage
+
+ const translateCommitProgress = (e: CommitProgress) => {
+ switch (e.phase) {
+ case 'uploading-blobs':
+ onProgress?.({ phase: 'uploading-blobs', uploaded: e.uploaded, total: e.total, skipped: e.skipped })
+ break
+ case 'building-tree':
+ onProgress?.({ phase: 'creating-tree' })
+ break
+ case 'committing':
+ onProgress?.({ phase: 'creating-commit' })
+ break
+ case 'updating-ref':
+ onProgress?.({ phase: 'updating-ref' })
+ break
+ }
+ }
+
+ const commit = await provider.commitChanges(repo, {
+ branch,
+ parentSha: parentCommitSha,
+ message,
+ changes,
+ onProgress: translateCommitProgress,
+ })
+
+ // Record path-metadata updates only for note paths the host actually
+ // transmitted this attempt (see uploadedNotePathUpdate's note). A path
+ // served from the host's same-session content cache keeps its prior
+ // metadata, matching the old cached-blob behavior.
+ for (const path of commit.uploadedPaths) {
+ const upd = uploadedNotePathUpdate.get(path)
+ if (upd) pathUpdates.push(upd)
+ }
+
+ // Push reached the host (whether or not it produced a commit) — drop
+ // tombstones whose deletes are now applied so they don't re-attempt.
+ if (consumedTombstones.length > 0) await clearAttachmentTombstones(consumedTombstones)
+ onProgress?.({ phase: 'done' })
+
+ // committed:false means the host found the change set was a no-op (e.g. the
+ // built tree was byte-identical to the parent's). Report it as unchanged,
+ // exactly like the old empty-tree skip did.
+ if (!commit.committed) {
return {
- result: { unchanged: true, created: 0, updated: 0, deleted: 0, commitSha: parentCommitSha, commitUrl: null, attachmentSyncSkipped },
+ result: { unchanged: true, created: 0, updated: 0, deleted: 0, commitSha: commit.commitSha, commitUrl: commit.commitUrl, attachmentSyncSkipped },
pathUpdates,
vaultSettingsHashPushed,
vaultGitignorePushed,
}
}
- const total = created + updated + deleted
- const autoMessage = `Sync from Noteser (${total} change${total === 1 ? '' : 's'})`
- const message = commitMessage && commitMessage.length > 0 ? commitMessage : autoMessage
- onProgress?.({ phase: 'creating-commit' })
- const { sha: commitSha, html_url } = await createCommit(token, owner, name, message, newTreeSha, parentCommitSha)
- onProgress?.({ phase: 'updating-ref' })
- await updateBranchRef(token, owner, name, branch, commitSha)
-
- // Push succeeded — drop tombstones whose deletes are now in the commit
- // AND clear the upload cache for this repo. The next push will start
- // from scratch (which is fine — remote tree will be consulted again).
- if (consumedTombstones.length > 0) await clearAttachmentTombstones(consumedTombstones)
- uploadedShas.clear()
- onProgress?.({ phase: 'done' })
return {
- result: { unchanged: false, created, updated, deleted, commitSha, commitUrl: html_url, attachmentSyncSkipped },
+ result: { unchanged: false, created, updated, deleted, commitSha: commit.commitSha, commitUrl: commit.commitUrl, attachmentSyncSkipped },
pathUpdates,
vaultSettingsHashPushed,
vaultGitignorePushed,