Sync Upstream

Sync Upstream

Synchronize the Switchboard app with a newer version of the official LibreChat server.

You are the coordinator. You run the lightweight deterministic work yourself with Bash (prereqs, target/mode resolution, final consistency asserts) and own the three human decision points. All heavy parallel work is delegated to two dynamic workflows — you never read or write app code yourself.

[you]  0. Prereqs + resolve target + detect mode          (Bash — fail loud on ambiguity)
  │
[WF1]  1. sync-upstream-discovery   — parallel multi-angle sweep → converged findings
  │
[you]  2. HITL INTERVIEW            — the one real gate: target + scope + direction   (AskUserQuestion)
  │
[WF2]  3. sync-upstream-implement   — implement → build+consistency gates → ≥2 independent review passes
  │
[you]  4. TEST + PUSH TAIL          — present test plan, facilitate device testing, hold the push gate

Two workflows do the work; you hold the seams. A workflow cannot pause to ask the user — that is exactly why the target choice, the proposal approval, and the no-push/device-test boundary live in your main loop between invocations, never inside a script.

Two modes

Resolve these before anything else (Phase 0), because they change the whole run:

Audit's default range is the last synced delta (previous pin → current pin), recovered from UPSTREAM_VERSION's own git history. --full widens it to full-pin reconciliation.

Target Modes (sync)

Shared invariants: the diff base is always commit= from UPSTREAM_VERSION (never tag=); BackendVersion.parse() handles all three forms; a later sync from a partial baseline is normal.

Phase 0 — Prereqs, target & mode (you, with Bash)

Working directory is already the mobile repo root — do not cd elsewhere; rely on relative paths. Fail LOUD on any ambiguity below — never guess a baseline or target for the user.

1. Submodule. git submodule status. If upstream/ missing: git submodule add https://github.com/LibreChat-AI/LibreChat.git upstream && git submodule update --init.
2. Version file. cat UPSTREAM_VERSION. If missing, create from version.properties backendTargetVersion + submodule HEAD (tag=v<version>, commit=<HEAD>, date=$(date +%Y-%m-%d)).
3. Clean tree. git status --porcelain. If dirty → ask the user to commit/stash; wait.
4. Baseline consistency (compute, then apply — a partial/rc baseline is NOT an inconsistency):
   • X.Y.Z+dev.<sha8> → <sha8> must be a prefix of commit=; verify the sha, not tag equality.
   • X.Y.Z-rcN / plain X.Y.Z → must equal tag= without v.
   • Always: submodule HEAD must equal commit=.
   • On failure → ask the user which state is the true baseline; wait. Never auto-pick.
5. Fetch + resolve target. cd upstream && git fetch origin --tags && git fetch origin dev main. Resolve $ARGUMENTS (see Target Modes) to a full {target_commit}:
   • none → newest stable tag (exclude -rc/-beta/-alpha), but still enumerate newer rc tags and how far dev/main are ahead (git rev-list --count {base_commit}..origin/dev) for the interview.
   • tag (stable or rc) → that tag; never silently drop an rc the user named.
   • branch/SHA → partial; {base_version} from git show {sha}:package.json, {anchor_tag} = git describe --tags --abbrev=0 --match "v[0-9]*" {sha} (--match is required — upstream also tags Helm charts like chart-2.0.7).
6. Detect mode. If {target_commit} == commit= (submodule HEAD) or $ARGUMENTS contains audit → audit mode; the audit base is the previous commit= from git log -p --format=%H -- UPSTREAM_VERSION (or full-pin if --full). Else sync mode. If sync mode and no newer tags AND branch heads == base → tell the user "already up to date" and offer an audit instead of stopping.
7. Artifacts dir. mkdir -p .claude/sync-upstream/artifacts.
8. Mirrored constants. scripts/check-mirrors.py --from {base_commit} --to {target_commit} --diff Some upstream values are never served over the API, so the client hardcodes a copy — which providers take documents natively, which MIME types the parser extracts, which feedback reasons the write route accepts. These drift silently: nothing fails to decode, nothing errors, the app just makes worse decisions as it ages, so the ordinary diff sweep reads them as inert constant edits and defers them. Exit 1 means at least one moved; the output names the Kotlin file to reconcile. Exit 2 is not drift — it is a fatal (empty submodule, unresolvable revision, bad registry); fix the setup and re-run rather than reporting it as a finding. Carry every DRIFT and ?? row into the Phase 2 interview as its own item — a ?? means upstream renamed or deleted the symbol, so the registry entry is wrong either way. Registry: scripts/mirrors.json. Adding a mirror to the codebase means adding an entry there in the same PR.

If a prior run's artifacts exist (ls .claude/sync-upstream/artifacts/), offer to resume from them.

Phase 1 — Discovery (WF1)

Invoke the discovery workflow. It runs the parallel multi-angle sweep, converges + cross-references the mobile codebase, and runs a completeness critic. Watch its phase tree live via /workflows.

Workflow({ name: "sync-upstream-discovery", args: {
  mode, baseCommit, targetCommit, targetMode, baseVersion, anchorTag,
  skillDir: "<abs path to .claude/skills/sync-upstream>",
  artifactsDir: "<abs path to .claude/sync-upstream/artifacts>",
} })

It returns { mode, range, findings[], counts, criticComplete, reportPath } and writes artifacts/discovery-report.md. Each finding is machine-complete: category, severity, mobile-gap status, iosMain coverage, landing commit + UTC landedDate, first-target-line, gate form. Do not paraphrase-and-lose those — thread the structured objects straight into WF2.