@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/fs/git-merge-conflict.test.ts

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A merge, rebase, cherry-pick or stash pop that STOPS ON A CONFLICT is a
+ * RESULT, not a failure.
+ *
+ * This is the bug the e2e layer could not see and a unit test can: `git merge`
+ * exits 1 when it leaves conflicts, and the route treated any non-zero exit as
+ * an error, so it answered 400 while `MERGE_HEAD` was live on disk. The panel
+ * then showed a failed request beside the conflict it had just created — and
+ * because the spec helper ignored the response, the e2e run read as a flaky
+ * panel rather than a rejected command (measured: 5 of 10 git-panel specs
+ * failed in CI on every run, all green locally only because a local git
+ * identity let the merge commit cleanly).
+ *
+ * The proof that a stop is genuine is the OPERATION the command left behind:
+ * a real failure (a bad ref, a dirty tree) leaves none.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { mergeBranch, rebaseOnto } from '@/server/lib/fs/git-merge';
+import { applyStash, pushStash } from '@/server/lib/fs/git-stash';
+import { readGitState } from '@/server/lib/fs/git-state';
+
+const repos: string[] = [];
+
+afterEach(() => {
+  while (repos.length > 0) fs.rmSync(repos.pop() as string, { recursive: true, force: true });
+});
+
+/** A scratch repo with an identity that cannot leak into the developer's config. */
+function makeRepo(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-merge-'));
+  repos.push(dir);
+  git(dir, 'init', '-q', '-b', 'main');
+  // The identity goes into the REPO's own config, not the spawn env: the code
+  // under test runs `git` through `runGit`, a SEPARATE process that inherits
+  // only `Bun.env` — an identity passed to this fixture's `spawnSync` would not
+  // reach it, and `git merge` needs one even to write the conflict state.
+  git(dir, 'config', 'user.email', 'e2e@example.invalid');
+  git(dir, 'config', 'user.name', 'E2E');
+  return dir;
+}
+
+function git(cwd: string, ...args: string[]): string {
+  const result = Bun.spawnSync({
+    cmd: ['git', ...args],
+    cwd,
+    // Identity lives in the repo's config (see `makeRepo`); only the editor is
+    // forced here, so a command that would open one cannot block the run.
+    env: { ...Bun.env, GIT_EDITOR: 'true' },
+  });
+  if (result.exitCode !== 0) throw new Error(`git ${args.join(' ')} failed: ${result.stderr.toString()}`);
+  return result.stdout.toString();
+}
+
+/** Two branches editing the same line, so a merge stops on a conflict. */
+function seedConflict(cwd: string, file = 'shared.txt'): void {
+  fs.writeFileSync(path.join(cwd, file), 'one\ntwo\nthree\n');
+  git(cwd, 'add', '-A');
+  git(cwd, 'commit', '-q', '-m', 'base');
+  git(cwd, 'checkout', '-q', '-b', 'feature');
+  fs.writeFileSync(path.join(cwd, file), 'one\nFEATURE\nthree\n');
+  git(cwd, 'commit', '-q', '-am', 'feature');
+  git(cwd, 'checkout', '-q', 'main');
+  fs.writeFileSync(path.join(cwd, file), 'one\nMAIN\nthree\n');
+  git(cwd, 'commit', '-q', '-am', 'main');
+}
+
+describe('a conflicting merge is accepted, not reported as a failure', () => {
+  test('mergeBranch resolves with MERGE_HEAD in place', async () => {
+    const repo = makeRepo();
+    seedConflict(repo);
+    // Would throw before the fix: git exits 1 on a conflict.
+    await mergeBranch(repo, 'feature');
+    expect((await readGitState(repo)).operation).toBe('merge');
+    expect(fs.existsSync(path.join(repo, '.git', 'MERGE_HEAD'))).toBe(true);
+  });
+
+  test('a merge that genuinely fails still throws', async () => {
+    const repo = makeRepo();
+    fs.writeFileSync(path.join(repo, 'a.txt'), 'x\n');
+    git(repo, 'add', '-A');
+    git(repo, 'commit', '-q', '-m', 'only commit');
+    // No such branch, and no operation is left behind — the error stands.
+    await expect(mergeBranch(repo, 'does-not-exist')).rejects.toThrow();
+    expect((await readGitState(repo)).operation).toBeNull();
+  });
+});
+
+describe('a conflicting rebase is accepted', () => {
+  test('rebaseOnto resolves with a rebase in progress', async () => {
+    const repo = makeRepo();
+    seedConflict(repo);
+    // `rebaseOnto` takes a HASH (the panel's own caller sends one), so resolve
+    // the feature tip first. main and feature both touched the same line.
+    const featureTip = git(repo, 'rev-parse', 'feature').trim();
+    await rebaseOnto(repo, featureTip);
+    expect((await readGitState(repo)).operation).toBe('rebase');
+  });
+});
+
+describe('a conflicting stash pop is accepted', () => {
+  test('applyStash resolves with the stash-pop state', async () => {
+    const repo = makeRepo();
+    fs.writeFileSync(path.join(repo, 's.txt'), 'one\ntwo\n');
+    git(repo, 'add', '-A');
+    git(repo, 'commit', '-q', '-m', 'base');
+    fs.writeFileSync(path.join(repo, 's.txt'), 'one\nSTASHED\n');
+    await pushStash({ targetDir: repo, message: 'wip' });
+    // A different change to the same line, committed, so the pop conflicts.
+    fs.writeFileSync(path.join(repo, 's.txt'), 'one\nCOMMITTED\n');
+    git(repo, 'commit', '-q', '-am', 'move on');
+    await applyStash({ targetDir: repo, ref: 'stash@{0}', pop: true });
+    expect((await readGitState(repo)).operation).toBe('stash-pop');
+  });
+});

package/src/server/lib/fs/git-merge.ts

@@ -0,0 +1,210 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Merge, and the three actions that exist only while an operation is stopped on
+ * a conflict: abort, continue, and resolving one path.
+ *
+ * **A merge is merged BY NAME, not by SHA.** `git merge <sha>` writes
+ * `Merge commit '<sha>'`; `git merge <branch>` writes `Merge branch '<name>'`.
+ * The panel's only merge today goes through the commit modal and sends a full
+ * hash, so every merge it ever made produced the worse message — measured on a
+ * scratch repo, both forms.
+ *
+ * **Continue is `git commit --no-edit`, not `git merge --continue`.** Both
+ * conclude a resolved merge (verified: `MERGE_HEAD` is gone after either), but
+ * `--continue` needs an editor for the message git prepared and there is no
+ * terminal to draw one in. Two failure modes were reproduced: with `GIT_EDITOR`
+ * unset it exits with `error: Terminal is dumb, but EDITOR unset`; with a real
+ * `GIT_EDITOR=vim` inherited it BLOCKS on vim until the timeout kills it.
+ * `git commit --no-edit` needs no editor at all, which is why it is the verb —
+ * `runGit` sets `GIT_EDITOR=true` as the belt to this braces.
+ *
+ * **`--ours`/`--theirs` are INVERTED during a rebase.** Measured on the same
+ * two commits: in a merge conflict `--ours` yields the branch you are on and
+ * `--theirs` the branch merged in; in a rebase conflict `--ours` yields the
+ * branch being rebased ONTO and `--theirs` your own commit. The caller must
+ * label the buttons from the conflict markers (`parseConflictMarkers`), not
+ * from the words ours/theirs — a button that says "ours" and silently takes the
+ * other side in half the states is worse than no button.
+ */
+
+import { runGit } from '@/server/lib/fs/git-run';
+import { readGitState } from '@/server/lib/fs/git-state';
+import type { GitOperation } from '@/shared/types';
+
+/** Runs a git command and throws with its stderr when it exits non-zero. */
+async function expectOk(args: string[], cwd: string, timeout?: number): Promise<string> {
+  const result = await runGit(args, { cwd, timeout, maxBuffer: 1024 * 1024 });
+  if (result.error) throw result.error;
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || result.stdout.trim() || `git exited with code ${result.exitCode}`);
+  }
+  return result.stdout;
+}
+
+/**
+ * Run a command that STARTS an operation, and accept a conflict stop as success.
+ *
+ * `git merge`, `rebase`, `cherry-pick` and `revert` exit **1** when they stop on
+ * a conflict — that is the state the panel exists to show, not a failure. The
+ * bare `expectOk` reported it as an error, so the route answered 400 while the
+ * operation was in fact live on disk: the panel's own request said "failed"
+ * beside a conflict it had just created. Verified against a real conflicting
+ * merge: `git merge --no-edit -- feature` exits 1, `MERGE_HEAD` exists, and the
+ * old path surfaced `Auto-merging shared.txt / CONFLICT (content) …` as the
+ * error message.
+ *
+ * A non-zero exit is therefore only an error when NO operation was left behind
+ * (a bad branch name, a dirty tree, a missing ref). The operation name is passed
+ * in because the caller knows which one it started.
+ */
+async function expectStarted(args: string[], cwd: string, operation: GitOperation, timeout: number): Promise<string> {
+  const result = await runGit(args, { cwd, timeout, maxBuffer: 1024 * 1024 });
+  if (result.error) throw result.error;
+  if (result.exitCode === 0) return result.stdout;
+  const state = await readGitState(cwd);
+  if (state.operation === operation) return result.stdout;
+  throw new Error(result.stderr.trim() || result.stdout.trim() || `git exited with code ${result.exitCode}`);
+}
+
+/**
+ * Merge a branch into the current one.
+ *
+ * `--no-edit` accepts git's own merge message, which is the one the user would
+ * have kept: a plain `git merge` in this environment has no editor to open, and
+ * the merge message is not something the panel collects. No `--no-ff` — a
+ * fast-forward is what the user asked for by merging a branch that is ahead.
+ *
+ * The name is validated first, so a string that is not a branch cannot reach
+ * git as an option (`git merge --abort` would run happily on a bare `merge`).
+ */
+export async function mergeBranch(targetDir: string, branch: string): Promise<string> {
+  const name = branch.trim();
+  if (!name) throw new Error('A branch name is required.');
+  const check = await runGit(['check-ref-format', '--branch', name], { cwd: targetDir, timeout: 5_000 });
+  if (check.exitCode !== 0) {
+    throw new Error(check.stderr.trim() || `'${name}' is not a valid branch name`);
+  }
+  await expectStarted(['merge', '--no-edit', '--', name], targetDir, 'merge', 120_000);
+  return `git merge ${name}`;
+}
+
+/** True when a ref resolves — used to refuse a merge of something that is not one. */
+export async function refResolves(targetDir: string, ref: string): Promise<boolean> {
+  const result = await runGit(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { cwd: targetDir, timeout: 5_000 });
+  return result.exitCode === 0;
+}
+
+/**
+ * Merge one commit by hash — the commit modal's action.
+ *
+ * Kept separate from `mergeBranch` because the two produce different history
+ * (a hash cannot name a branch in the merge message) and because the hash path
+ * is reached from a commit row where there is no branch name to send. The
+ * `--` separator and the hash-shape guard close the argv hole the previous
+ * `['merge', hash]` had: measured, `git merge --abort` ran when the "hash" was
+ * `--abort`.
+ */
+export async function mergeCommit(targetDir: string, hash: string): Promise<void> {
+  const sha = hash.trim();
+  if (!/^[0-9a-f]{7,40}$/i.test(sha)) throw new Error(`'${sha}' is not a commit hash.`);
+  await expectStarted(['merge', '--no-edit', '--', sha], targetDir, 'merge', 120_000);
+}
+
+/** Cherry-pick one commit, with the same guard. */
+export async function cherryPick(targetDir: string, hash: string): Promise<void> {
+  const sha = hash.trim();
+  if (!/^[0-9a-f]{7,40}$/i.test(sha)) throw new Error(`'${sha}' is not a commit hash.`);
+  await expectStarted(['cherry-pick', '--', sha], targetDir, 'cherry-pick', 120_000);
+}
+
+/** Revert one commit without opening an editor for the message. */
+export async function revertCommit(targetDir: string, hash: string): Promise<void> {
+  const sha = hash.trim();
+  if (!/^[0-9a-f]{7,40}$/i.test(sha)) throw new Error(`'${sha}' is not a commit hash.`);
+  await expectStarted(['revert', '--no-edit', '--', sha], targetDir, 'revert', 120_000);
+}
+
+/** Rebase onto a commit, with the same guard. */
+export async function rebaseOnto(targetDir: string, hash: string): Promise<void> {
+  const sha = hash.trim();
+  if (!/^[0-9a-f]{7,40}$/i.test(sha)) throw new Error(`'${sha}' is not a commit hash.`);
+  await expectStarted(['rebase', '--', sha], targetDir, 'rebase', 120_000);
+}
+
+/** Reset the current branch, with the mode and the hash both guarded. */
+export async function resetTo(targetDir: string, hash: string, mode: string): Promise<void> {
+  const sha = hash.trim();
+  if (!/^[0-9a-f]{7,40}$/i.test(sha)) throw new Error(`'${sha}' is not a commit hash.`);
+  if (!['soft', 'mixed', 'hard'].includes(mode)) throw new Error(`Unknown reset mode: ${mode}`);
+  await expectOk(['reset', `--${mode}`, '--', sha], targetDir, 30_000);
+}
+
+/**
+ * Conclude an operation whose conflicts are all resolved.
+ *
+ * **The verb is PER OPERATION, and `git commit --no-edit` is only right for a
+ * merge.** Measured on a real rebase conflict: resolving the file and running
+ * `git commit --no-edit` makes the commit but leaves the rebase RUNNING —
+ * `rebase-merge` is still there, `git status` reads "interactive rebase in
+ * progress … use `git rebase --continue`", and the operation bar would never
+ * clear. The same applies to cherry-pick and revert, each of which has its own
+ * `--continue` that finishes the sequencer.
+ *
+ * `stash-pop` is deliberately absent: a conflicting stash pop leaves the
+ * resolved changes in the WORKING TREE with no operation to conclude — there is
+ * nothing to continue, and the stash entry survives so it can be dropped
+ * separately. `continueArgsFor` returns `null` for it, and the bar hides the
+ * button rather than offering a verb that would do the wrong thing.
+ *
+ * `GIT_EDITOR=true` (set by `runGit`) is what makes the `--continue` forms
+ * usable here: without it `rebase --continue` fails with "Terminal is dumb, but
+ * EDITOR unset", and with a real editor inherited it blocks until the timeout.
+ */
+export function continueArgsFor(operation: GitOperation): string[] | null {
+  switch (operation) {
+    case 'merge':
+      return ['commit', '--no-edit'];
+    case 'rebase':
+    case 'rebase-apply':
+      return ['rebase', '--continue'];
+    case 'cherry-pick':
+      return ['cherry-pick', '--continue'];
+    case 'revert':
+      return ['revert', '--continue'];
+    case 'stash-pop':
+      // No operation to conclude: the applied changes are in the working tree.
+      return null;
+  }
+}
+
+/** Which side of a conflict to keep. */
+export type ConflictSide = 'ours' | 'theirs';
+
+export interface ResolveConflictOptions {
+  targetDir: string;
+  file: string;
+  /** Omit for "mark resolved" — the file was edited by hand. */
+  side?: ConflictSide;
+}
+
+/**
+ * Resolve one conflicted path.
+ *
+ * `side` runs `git checkout --ours|--theirs -- <path>` (both verified: they
+ * write the chosen stage into the working tree) and then `git add`, which is
+ * what moves `ls-files -u` toward empty. No `side` is "mark resolved": the file
+ * was resolved in the editor and only the `git add` is missing — exactly what
+ * git's own hint tells the user to run.
+ *
+ * `--` separates the path in both commands: a repo-relative path is
+ * repository-controlled data, and the same rule `revertPath` follows applies.
+ */
+export async function resolveConflict({ targetDir, file, side }: ResolveConflictOptions): Promise<void> {
+  if (!file.trim()) throw new Error('A file path is required.');
+  if (side) await expectOk(['checkout', `--${side}`, '--', file], targetDir, 30_000);
+  await expectOk(['add', '--', file], targetDir, 30_000);
+}

package/src/server/lib/fs/git-porcelain-v2.ts

@@ -0,0 +1,140 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `git status --porcelain=v2 --branch -z` — the ONE spawn that answers every
+ * fact a repository row shows: the branch, whether HEAD is detached, the
+ * upstream and its ahead/behind track, and the counts of changed, untracked and
+ * conflicted paths.
+ *
+ * **v2, not the v1 the panel's own read uses, because v1 has no structured
+ * header.** v1 prints `## main...origin/main [ahead 1, behind 2]` and everything
+ * about the upstream has to be re-derived from that prose — including its two
+ * degenerate spellings, `## No commits yet on main` and `## HEAD (no branch)`.
+ * v2 states each fact on its own `#` line, and `--branch` is what adds them.
+ *
+ * The forms were measured against real repositories:
+ *
+ * ```
+ * # branch.oid f709e10eb56661c42bcc0b2871221817bb733862   (initial) when unborn
+ * # branch.head main                                      (detached) when detached
+ * # branch.upstream origin/main                            absent with no upstream
+ * # branch.ab +0 -0                                       absent when the upstream is GONE
+ * ```
+ *
+ * `branch.ab` absent with `branch.upstream` PRESENT is the `[gone]` case — the
+ * remote ref was deleted, which is what a remote rename without `--prune`
+ * leaves behind. It is not "in sync", and the row must not say it is.
+ *
+ * `-z` for the same reason `parsePorcelainZ` uses it: the non-`-z` form quotes
+ * any path holding a space or a non-ASCII byte and octal-escapes the latter, and
+ * no decode reverses that.
+ */
+
+/** One repository's status, as a `--porcelain=v2 --branch` read reports it. */
+export interface PorcelainV2Summary {
+  /** The checked-out branch, or the short sha when HEAD is detached. */
+  branch: string;
+  detached: boolean;
+  /** False on a branch with no commits yet — the log read is skipped then. */
+  hasCommits: boolean;
+  /** The upstream's short name (`origin/main`), or `''`. */
+  upstream: string;
+  /** Commits ahead of the upstream; 0 when there is no track to read. */
+  ahead: number;
+  /** Commits behind the upstream; 0 when there is no track to read. */
+  behind: number;
+  /** The upstream ref no longer exists on the remote. */
+  gone: boolean;
+  /** Modified / staged / renamed / unmerged paths. */
+  changed: number;
+  /** Paths git has never seen. */
+  untracked: number;
+  /** Unmerged index entries — a conflict waiting for a resolve. */
+  conflicts: number;
+}
+
+/**
+ * Parse the `-z` form.
+ *
+ * Records are NUL-terminated and a rename or copy spends TWO of them — the new
+ * path, then the original — so the second is consumed rather than read as a
+ * record of its own (the same unwrapping `parsePorcelainZ` performs).
+ *
+ * A record's fixed fields are space-separated and the path is whatever follows
+ * them, so each type's path is the remaining tokens rejoined with a single
+ * space: splitting and rejoining a verbatim path is lossless, and it keeps this
+ * parser from depending on a field count git is free to extend.
+ */
+export function parsePorcelainV2(out: string): PorcelainV2Summary {
+  const summary: PorcelainV2Summary = {
+    branch: '',
+    detached: false,
+    hasCommits: true,
+    upstream: '',
+    ahead: 0,
+    behind: 0,
+    gone: false,
+    changed: 0,
+    untracked: 0,
+    conflicts: 0,
+  };
+  let oid = '';
+  let sawAb = false;
+
+  const records = out.split('\0');
+  for (let i = 0; i < records.length; i += 1) {
+    const record = records[i];
+    if (!record) continue;
+
+    if (record.startsWith('# ')) {
+      const [key, ...rest] = record.slice(2).split(' ');
+      const value = rest.join(' ');
+      if (key === 'branch.oid') oid = value;
+      else if (key === 'branch.head') {
+        if (value === '(detached)') summary.detached = true;
+        else summary.branch = value;
+      } else if (key === 'branch.upstream') summary.upstream = value;
+      else if (key === 'branch.ab') {
+        sawAb = true;
+        const ahead = /\+(\d+)/.exec(value);
+        const behind = /-(\d+)/.exec(value);
+        summary.ahead = ahead ? Number(ahead[1]) : 0;
+        summary.behind = behind ? Number(behind[1]) : 0;
+      }
+      continue;
+    }
+
+    const kind = record[0];
+    if (kind === '1') {
+      summary.changed += 1;
+      continue;
+    }
+    if (kind === '2') {
+      summary.changed += 1;
+      // The original path is its own record; it names nothing the tree has.
+      i += 1;
+      continue;
+    }
+    if (kind === 'u') {
+      // An unmerged entry is a CONFLICT, not a change: its two letters are the
+      // two SIDES of the conflict, and counting it as an ordinary change is what
+      // made the panel report every conflicted file as staged.
+      summary.conflicts += 1;
+      continue;
+    }
+    if (kind === '?') {
+      summary.untracked += 1;
+      continue;
+    }
+    // `!` (ignored) is never requested, and anything else is a shape this
+    // version of git does not emit — counted nowhere rather than guessed at.
+  }
+
+  if (summary.detached) summary.branch = oid.slice(0, 7);
+  summary.hasCommits = oid !== '' && oid !== '(initial)';
+  summary.gone = summary.upstream !== '' && !sawAb;
+  return summary;
+}

package/src/server/lib/fs/git-publish.test.ts

@@ -0,0 +1,147 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Publishing one branch, on the branch a user is most likely to be on: one just
+ * created locally.
+ *
+ * Both naive commands fail there, and both failures were real. `git push` exits
+ * 128 ("has no upstream branch"), so Sync could not send the commits the badge
+ * was counting. `git pull --ff-only` exits 1 ("no tracking information") — a
+ * refusal, not a failure — and treating it as an error aborted Sync before it
+ * ever reached the push. Driven against real repositories, because the exit
+ * codes and the `-u` upstream write are what the module exists for.
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pullBranch, pushBranch } from '@/server/lib/fs/git-publish';
+import { removeDir } from '@/test-support/remove-dir';
+
+const tempDirs: string[] = [];
+
+function tempDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-gitpub-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function git(cwd: string, ...args: string[]): string {
+  const result = Bun.spawnSync({ cmd: ['git', ...args], cwd });
+  if (result.exitCode !== 0) {
+    throw new Error(`git ${args.join(' ')} failed: ${result.stderr.toString()}`);
+  }
+  return result.stdout.toString();
+}
+
+function initRepo(cwd: string): void {
+  git(cwd, 'init', '-q', '-b', 'main');
+  git(cwd, 'config', 'user.email', 'test@example.invalid');
+  git(cwd, 'config', 'user.name', 'Test');
+}
+
+function commitFile(cwd: string, name: string, message: string): void {
+  fs.writeFileSync(path.join(cwd, name), `${name}\n`);
+  git(cwd, 'add', '-A');
+  git(cwd, 'commit', '-q', '-m', message);
+}
+
+/** A bare origin plus a clone tracking it, each on its own temp path. */
+function makeClone(): { origin: string; clone: string } {
+  const origin = tempDir();
+  git(origin, 'init', '-q', '--bare', '-b', 'main');
+  const clone = tempDir();
+  git(tempDir(), 'clone', '-q', origin, clone);
+  initRepo(clone);
+  commitFile(clone, 'seed.txt', 'seed');
+  git(clone, 'push', '-q', '-u', 'origin', 'main');
+  return { origin, clone };
+}
+
+function upstreamOf(cwd: string): string {
+  return git(cwd, 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}').trim();
+}
+
+afterAll(() => {
+  for (const dir of tempDirs) removeDir(dir);
+});
+
+describe('pushBranch', () => {
+  test('publishes a fresh local branch and sets its upstream', async () => {
+    const { origin, clone } = makeClone();
+    git(clone, 'checkout', '-q', '-b', 'feat/x');
+    commitFile(clone, 'one.txt', 'one');
+
+    await pushBranch(clone);
+
+    expect(upstreamOf(clone)).toBe('origin/feat/x');
+    // The remote really holds it — an upstream set without a push would be a
+    // local-only ref and the next count would still read as unpushed.
+    expect(git(clone, 'ls-remote', '--heads', origin, 'feat/x')).toContain('feat/x');
+  });
+
+  test('pushes a branch that already tracks, without re-pointing it', async () => {
+    const { clone } = makeClone();
+    commitFile(clone, 'more.txt', 'more');
+
+    await pushBranch(clone);
+
+    expect(upstreamOf(clone)).toBe('origin/main');
+  });
+
+  test('names the missing remote instead of pushing nowhere', async () => {
+    const repo = tempDir();
+    initRepo(repo);
+    commitFile(repo, 'a.txt', 'a');
+
+    await expect(pushBranch(repo)).rejects.toThrow(/no remote/i);
+  });
+
+  test('uses the repository\'s own remote, not a hardcoded origin', async () => {
+    const { origin, clone } = makeClone();
+    git(clone, 'remote', 'rename', 'origin', 'upstream');
+    git(clone, 'checkout', '-q', '-b', 'feat/z');
+    commitFile(clone, 'z.txt', 'z');
+
+    await pushBranch(clone);
+
+    expect(upstreamOf(clone)).toBe('upstream/feat/z');
+    expect(git(clone, 'ls-remote', '--heads', origin, 'feat/z')).toContain('feat/z');
+  });
+});
+
+describe('pullBranch', () => {
+  test('stands down on a branch with no upstream instead of failing', async () => {
+    const { clone } = makeClone();
+    git(clone, 'checkout', '-q', '-b', 'feat/new');
+    commitFile(clone, 'n.txt', 'n');
+
+    // The command this replaces exited 1 here, which aborted Sync before push.
+    // Reaching the next line at all is the assertion; the rev-parse below is
+    // read through the raw runner because it is EXPECTED to exit non-zero.
+    await pullBranch(clone);
+
+    const upstream = Bun.spawnSync({
+      cmd: ['git', 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'],
+      cwd: clone,
+    });
+    expect(upstream.exitCode).not.toBe(0);
+  });
+
+  test('fast-forwards a tracking branch', async () => {
+    const { origin, clone } = makeClone();
+    const work = tempDir();
+    git(tempDir(), 'clone', '-q', origin, work);
+    initRepo(work);
+    commitFile(work, 'remote.txt', 'remote');
+    git(work, 'push', '-q');
+
+    await pullBranch(clone);
+
+    expect(fs.existsSync(path.join(clone, 'remote.txt'))).toBe(true);
+  });
+});