feat(ci): add bit ci sync — bi-directional sync between Bit lanes and git branches/PRs

[luvkapur]

What this PR adds

This PR adds one command: bit ci sync. The command keeps Bit lanes and git branches equal. It works in both directions. A lane on bit.cloud becomes a branch and a pull request on the git host. A commit on that branch becomes a snap on the lane.

The command completes the bit ci set. bit ci pr and bit ci merge move changes from git to Bit. bit ci sync also moves changes from Bit to git.

Why teams need this

Use case 1: git is the source of truth. Some organizations must review every change in a pull request. Their policy blocks lane merges on bit.cloud. With this command, a lane export creates a pull request. The team reviews the pull request in GitHub. When the pull request merges, bit ci merge releases the components. The audit trail stays in git.

Use case 2: git is a compliance mirror. Some teams merge lanes on bit.cloud. They also keep a git repository for audit. When the scope moves ahead of the repository, the command opens a sync pull request. A reviewer approves it. The repository then shows the true state of the scope.

How to use it

bit ci sync [lane]        # reconcile one lane; accepts <scope>/<name>
bit ci sync --branch <b>  # resolve the lane from a branch name
bit ci sync --all         # reconcile every mapped lane, then the main scope
bit ci sync --main        # reconcile only the main scope
bit ci sync --dry-run     # show the plan; write nothing
bit ci sync --init        # write the GitHub workflow files and the config block

Triggers decide when the command runs. They never decide what it does. A webhook, a push, a cron job, or a person can start it. The result is the same. A converged pair is a no-op. For a fully working GitHub setup, --init writes two workflow files and prints a checklist.

How a sync works

The command reads three facts for each lane and branch pair:

1. The lane head on bit.cloud.
2. The branch tip on the git remote.
3. The branch state: the .bitmap file at the branch tip. Bit writes this file. It records the lane pointer and each component version. No extra state store exists.

A pure planner compares these facts and picks one action: import the lane onto the branch, export the branch commits to the lane, merge a diverged pair, close a retired pair, skip, or halt. The executor performs the action with Bit APIs and plain git pushes. The command never force-pushes.

Safety rules

• A conflict never breaks a branch. The command stops, labels the pull request bit-sync-conflict, and writes the recovery steps as a comment. Remove the label to resume.
• Branch deletion needs strong proof. The branch tip must be a sync commit that the reconciler wrote. The .bitmap at the tip must name the same lane. The commits must be safe to delete. A developer branch never qualifies.
• A cross-scope lane creates no branch. A lane can hold components from many scopes. One repository maps to one scope. Enumerated runs skip such a lane and stay green. A direct request for it gets a clear refusal.
• Cold environments are first class. A fresh CI runner has no local Bit objects. The command reads state from the branch files, not from local caches. It imports what it needs.

Other changes in this PR

• scopes/git/ci/git.ts no longer runs git clean -f when the module loads. This side effect ran on every bit invocation and could delete untracked files.
• bit ci merge and the sync paths now stage files with an exclusion list. They can no longer commit the local scope directory (.bit/) in a workspace without a .gitignore.
• The CLI reference files are regenerated and now include ci sync.

Tests

• 131 unit tests cover the planner table, the state readers, the ownership rules, and the GitHub client.
• 134 end-to-end assertions run the full cycle against a local scope and a bare git remote. They include cold-runner scenarios, conflict halts, branch retirement, and cross-scope refusals.
• A live sandbox validated the flow on real GitHub runners with a real bit.cloud org: lane export to pull request, dev commit to lane, merge to release, and orphan branch retirement.

Known follow-ups

• bit ci pr has one cold-runner gap at its lane-switch probe. The sync paths are fixed. The shared path needs its own change.
• Cross-scope lanes: scope-sliced mirroring and a coordinated multi-repository release are designed but not built.
• BitMap would benefit from a parse(content, { defaultScope }) API. The current no-filesystem entry point needs two placeholder arguments.

[qodo-free-for-open-source-projects]

Code review by qodo was updated up to the latest commit 3d1b72c

[qodo-free-for-open-source-projects]

Code review by qodo was updated up to the latest commit 1dbeefa

[davidfirst]

This line is running also for dry-run? (also the next line). if so, a user might loose local (uncommitted) changes unexpectedly

[luvkapur]

Good catch — you're right, and thank you. Fixed in 221cf6c.

I audited every write reachable under dryRun: true:

• Main-scope path — the offending one. syncMain runs checkoutPristine (checkout -f -B + scoped clean), then catchUpWithDefaultBranch (a local merge commit), then bit checkout head, all before its dry-run return — because main drift is computed as a diff, so the tree has to be written to learn the answer. restoreWorkspace rewinds to HEAD, so anything uncommitted was already gone.
• Lane path — clean. The dry-run early return precedes every tree move (checkoutPristine/materializeLane are only reachable from the three action executors behind the switch). Everything before it is reads plus lane-object imports into .bit.
• Orchestrator — reads only; --init is already refused together with --dry-run.

Fix: a dry run now refuses when the working tree has uncommitted changes (tracked modifications or untracked non-.bit/node_modules files), naming up to 10 offending paths and telling the user to commit or stash — instead of discarding them. With a clean tree the write-then-restore loses nothing, and that reasoning is recorded at the site. The guard sits in the orchestrator's existing status block, so it fires for every target shape (uniformly, including lane-only dry runs that provably write nothing — the promise 'a dry run never discards' then holds without the user having to know which shape writes).

Covered by unit rows plus an e2e cell asserting --main --dry-run over an uncommitted modification exits non-zero and leaves the modification intact.

[davidfirst]

This command deletes the branch without checking if it was progressed in the remote. Can be risky because every input to the deletion decision (tip-is-sync-commit, no-dev-commits, ownership) is computed from origin/* refs fetched once per run (fetchOnce, :1097).
In case like --all it can take some time until completing one lane and moving to the other, which, in the meanwhile, things can change.
Better to refetch at this point. or use a flag that "--force-with-lease=:"

[luvkapur]

Right on both counts — fixed in f3cb357 with both belts you suggested.

1. Re-verify. readBranchSyncState now also returns the tipSha it read every ownership input from. Before anything (including the PR close), executeClosePr re-fetches just that branch (git fetch origin +refs/heads/<b>:refs/remotes/origin/<b>) and compares. If the tip moved — or cannot be re-read — the outcome downgrades to {deleteBranch:false; keepReason:'tip-advanced-during-run'}, so the PR comment and the run summary both say the branch was kept because it advanced.
2. Lease. The delete itself is now git push origin --force-with-lease=refs/heads/<b>:<sha> :refs/heads/<b> — the server refuses a racing update rather than losing it. Argv order verified against a real bare repo (git 2.39.5); the full :refs/heads/<b> refspec is kept so the branch name can never be read as an option. A lease rejection is classified and reported as the same 'kept' outcome, never a crash.

One thing the e2e taught us: the server-side refusal wording differs from git's client-side stale info (cannot lock ref … is at X but expected Y / [remote rejected]), so the predicate matches both — a stale info-only match would have fallen through as 'left in place' instead of 'kept'.

Coverage: an e2e cell races the window directly (a pre-push hook advances the branch in the bare repo while the delete is in flight) and asserts the branch survives with the racing tip and the summary explains why, plus unit rows for the argv, the moved/unreadable tip paths, and both refusal wordings.

[qodo-free-for-open-source-projects]

Code Review by Qodo

New Review Started

This review has been superseded by a new analysis

[qodo-free-for-open-source-projects]

Code review by qodo was updated up to the latest commit a69cf60

[qodo-free-for-open-source-projects]

Code review by qodo was updated up to the latest commit 60aff5b

[qodo-free-for-open-source-projects]

Code review by qodo was updated up to the latest commit 997bbbd

[qodo-free-for-open-source-projects]

1. Wrong .bitmap ref path 🐞 Bug ≡ Correctness

readBranchSyncState() reads the committed .bitmap via git show origin/<branch>:./.bitmap, but
it never prefixes the workspace’s repo-relative subdirectory. In repositories where the Bit
workspace is not at the repo root (explicitly supported by --init and orchestrator comments), this
can make .bitmap look “missing”, which then makes the lane planner treat the branch as having no
state and may incorrectly choose import-lane for an existing mirrored branch.

Agent Prompt

### Issue description
`sync-state.readFileAtRef()` uses `git show ${revision}:./${filePath}` while callers pass `filePath` as `BIT_MAP` (`.bitmap`). This does not incorporate the Bit workspace’s repo-relative directory, so in non-root workspaces the `.bitmap` at the branch tip may be read from the wrong location (or not found), causing `branchState.bitmap` to be `undefined` and the planner to select actions as if the branch has no sync state.

### Issue Context
This PR explicitly supports workspaces that are subdirectories (init scaffold `ws-dir`, orchestrator mentions workspace may be subdirectory). The sync logic must read the `.bitmap` that is committed **at the workspace path**, not necessarily at repository root.

### Fix Focus Areas
- scopes/git/ci/sync/sync-state.ts[155-166]
- scopes/git/ci/sync/sync-orchestrator.ts[223-226]

### What to change
1. Compute the workspace’s repo-relative prefix once (e.g. via `git rev-parse --show-prefix` or by combining `gitRepoRoot()` with `workspace.path` to derive a repo-relative path).
2. Pass that prefix into `readBranchSyncState()` / `readFileAtRef()` and use it when building the `rev:path` argument, e.g. `${revision}:${prefix}${filePath}` where `prefix` is `''` at repo root or like `packages/my-workspace/`.
3. Add/adjust unit tests in `sync-state.spec.ts` to cover both root and subdirectory workspace cases (ensure `git show` arguments include the prefix).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-free-for-open-source-projects]

2. Ambiguous host provider pick 🐞 Bug ☼ Reliability

selectGitHostProvider() returns the first configured provider among those that matchesRemote(),
even if multiple configured providers claim the same remote. This makes selection order-dependent
and can route PR operations through the wrong provider, despite the function’s documented assumption
that claims are exclusive.

Agent Prompt

### Issue description
When multiple providers claim the same `remoteUrl` and more than one is configured, `selectGitHostProvider()` picks the first configured claimant via `.find(...)`. This is order-dependent and conflicts with the documented “claim is exclusive” routing rule.

### Issue Context
Providers are registered via a public slot (`ci.registerGitHostProvider(...)`). In real deployments, it’s plausible to have overlapping `matchesRemote()` implementations (e.g., a generic GitHub provider plus an org-specific wrapper) or accidental double-registration.

### Fix Focus Areas
- scopes/git/ci/sync/git-host-provider.ts[46-85]

### What to change
1. When `claimants.length > 0`, compute `configuredClaimants = claimants.filter(p => p.isConfigured(remoteUrl))`.
2. If `configuredClaimants.length === 1`, return it.
3. If `configuredClaimants.length > 1`, return `{ reason: "...too ambiguous..." }` (or throw a `BitError` that instructs users to remove/disable one provider).
4. Add a unit test in `git-host-provider.spec.ts` covering: two claimants, both configured => ambiguity (no provider selected).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-free-for-open-source-projects]

Code review by qodo was updated up to the latest commit d38e892