@bevel-software/platform-core-backend 0.13.6 → 0.15.1

package/src/modules/kb-sync/__tests__/kb-sync.service.test.ts

@@ -0,0 +1,295 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
+import { KbSyncService } from '../kb-sync.service.js';
+import type { SyncWorkflowPort, SyncWorkspacePort } from '../kb-sync.interface.js';
+
+function deferred<T>() {
+  let resolve!: (v: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+function workspaces(branches: string[]): SyncWorkspacePort {
+  return {
+    listClonedWorkspaces: async () => branches.map((branch) => ({ id: encodeURIComponent(branch), branch })),
+  };
+}
+
+function updated(branch: string): BranchSyncOutcome {
+  return { branch, outcome: 'updated', from: 'aaa', to: 'bbb' };
+}
+
+describe('KbSyncService', () => {
+  it('syncs every known clone for an "all" request and reports unknown branches as not cloned', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 1),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+
+    const all = await svc.sync({ branches: 'all' });
+    expect(all.status).toBe('synced');
+    expect(all.results.map((r) => r.branch)).toEqual(['main', 'ali/x']);
+    expect(all.changeRequests.closedDeletedBranch).toBe(1);
+    expect(workflow.syncWorkspaceFromRemote).toHaveBeenCalledWith('ali%2Fx');
+
+    const some = await svc.sync({ branches: ['ali/x', 'juan/other'] });
+    expect(some.results).toEqual([updated('ali/x'), { branch: 'juan/other', outcome: 'not-cloned' }]);
+  });
+
+  it('a conflict or an error makes the result partial; the other branches still sync', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> =>
+        id === 'main'
+          ? { branch: 'main', outcome: 'conflict', conflictedPaths: ['a.md'], error: 'msg' }
+          : updated(decodeURIComponent(id)),
+      ),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const r = await svc.sync({ branches: 'all' });
+    expect(r.status).toBe('partial');
+    expect(r.results[1]).toEqual(updated('ali/x'));
+  });
+
+  it('a failing sweep does not fail the sync', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async () => updated('main')),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => {
+        throw new Error('origin down');
+      }),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main']));
+    const r = await svc.sync({ branches: 'all' });
+    expect(r.status).toBe('synced');
+    expect(r.changeRequests.closedDeletedBranch).toBe(0);
+  });
+
+  it('coalesces everything that arrives mid-run into ONE follow-up carrying the union', async () => {
+    const gate = deferred<void>();
+    // Each run's branches, in order. The first run parks on `gate` so the
+    // others arrive mid-run; a new run is recognised by its first branch
+    // landing after the gate opened.
+    const calls: string[][] = [['']];
+    let gateOpened = false;
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => {
+        const branch = decodeURIComponent(id);
+        if (!gateOpened && branch === 'main') {
+          await gate.promise;
+          gateOpened = true;
+          calls[0] = [];
+        } else if (gateOpened && calls.length === 1) {
+          calls.push([]);
+        }
+        calls[calls.length - 1].push(branch);
+        return updated(branch);
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+
+    const first = svc.sync({ branches: ['main'] });
+    // Three requests land while the first is parked on `gate`.
+    const second = svc.sync({ branches: ['ali/x'] });
+    const third = svc.sync({ branches: ['juan/y'] });
+    const fourth = svc.sync({ branches: ['ali/x'] });
+    gate.resolve();
+
+    const [r1, r2, r3, r4] = await Promise.all([first, second, third, fourth]);
+    expect(r1.results.map((r) => r.branch)).toEqual(['main']);
+    // One follow-up, the union, in arrival order — and every mid-run caller
+    // answered for the branches IT asked about, never for the others'.
+    expect(calls).toEqual([['main'], ['ali/x', 'juan/y']]);
+    expect(r2.results.map((r) => r.branch)).toEqual(['ali/x']);
+    expect(r3.results.map((r) => r.branch)).toEqual(['juan/y']);
+    expect(r4.results.map((r) => r.branch)).toEqual(['ali/x']);
+    expect(workflow.closeChangeRequestsWithDeletedBranches).toHaveBeenCalledTimes(2);
+  });
+
+  it('an "all" arriving mid-run absorbs the queued branches', async () => {
+    const gate = deferred<void>();
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => {
+        if (id === 'main') await gate.promise;
+        return updated(decodeURIComponent(id));
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const first = svc.sync({ branches: ['main'] });
+    const second = svc.sync({ branches: ['ali/x'] });
+    const third = svc.sync({ branches: 'all' });
+    gate.resolve();
+    await first;
+    // The follow-up pulled everything; the "all" caller hears all of it, the
+    // one-branch caller only its branch.
+    expect((await third).results.map((x) => x.branch)).toEqual(['main', 'ali/x', 'juan/y']);
+    expect((await second).results.map((x) => x.branch)).toEqual(['ali/x']);
+  });
+});
+
+describe('KbSyncService.lastSync', () => {
+  it('is null before the first sync, then records when, who and what', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    let clock = 1_000;
+    const svc = new KbSyncService(workflow, workspaces(['main']), () => clock);
+    expect(svc.lastSync()).toBeNull();
+
+    await svc.sync({ branches: 'all', by: 'bearer' });
+    expect(svc.lastSync()).toEqual({
+      at: 1_000,
+      by: 'bearer',
+      status: 'synced',
+      results: [updated('main')],
+    });
+
+    clock = 2_000;
+    await svc.sync({ branches: ['main'], by: 'admin@example.com' });
+    expect(svc.lastSync()).toMatchObject({ at: 2_000, by: 'admin@example.com' });
+  });
+
+  it('a coalesced follow-up names everyone who asked for it', async () => {
+    const gate = deferred<void>();
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => {
+        if (id === 'main') await gate.promise;
+        return updated(decodeURIComponent(id));
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const first = svc.sync({ branches: ['main'], by: 'bearer' });
+    const second = svc.sync({ branches: ['ali/x'], by: 'github-signature' });
+    const third = svc.sync({ branches: ['ali/x'], by: 'admin@example.com' });
+    gate.resolve();
+    await Promise.all([first, second, third]);
+    expect(svc.lastSync()?.by).toBe('github-signature, admin@example.com');
+  });
+});
+
+describe('KbSyncService — a throwing branch step', () => {
+  it('becomes an error outcome; the other branches, the sweep and the record all still happen', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => {
+        if (id === 'main') throw new Error('fatal: unable to access https://x:ghp_secret@host/r');
+        return updated(decodeURIComponent(id));
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 1),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const r = await svc.sync({ branches: 'all', by: 'bearer' });
+    expect(r.status).toBe('partial');
+    expect(r.results[0]).toMatchObject({ branch: 'main', outcome: 'error' });
+    expect((r.results[0] as { error: string }).error).not.toContain('ghp_secret');
+    expect(r.results[1]).toEqual(updated('ali/x'));
+    expect(r.changeRequests.closedDeletedBranch).toBe(1);
+    expect(svc.lastSync()?.status).toBe('partial');
+  });
+});
+
+describe('KbSyncService — clones the host no longer has, and clones that cannot be read', () => {
+  it('a remote-gone branch is retired through the workflow, counts as clean, and does not stop the others', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> =>
+        id === 'ali%2Fx' ? { branch: 'ali/x', outcome: 'remote-gone' } : updated(decodeURIComponent(id)),
+      ),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 1),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['ali/x', 'main']));
+    const r = await svc.sync({ branches: 'all' });
+    expect(r.status).toBe('synced');
+    expect(r.results).toEqual([{ branch: 'ali/x', outcome: 'remote-gone' }, updated('main')]);
+    expect(workflow.retireRemoteGoneClone).toHaveBeenCalledTimes(1);
+    expect(workflow.retireRemoteGoneClone).toHaveBeenCalledWith('ali%2Fx');
+  });
+
+  it('a clone that could not be read is that branch’s error, not everyone’s', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const port: SyncWorkspacePort = {
+      listClonedWorkspaces: async () => [
+        { id: 'main', branch: 'main' },
+        { id: 'juan%2Fy', branch: 'juan/y', unreadable: "Could not read this branch's clone: EPERM" },
+      ],
+    };
+    const svc = new KbSyncService(workflow, port);
+    const r = await svc.sync({ branches: 'all' });
+    expect(r.status).toBe('partial');
+    expect(r.results).toEqual([
+      updated('main'),
+      { branch: 'juan/y', outcome: 'error', error: "Could not read this branch's clone: EPERM" },
+    ]);
+    expect(workflow.syncWorkspaceFromRemote).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('KbSyncService — a coalesced caller is judged by its own branches', () => {
+  it("branch A's hook is not failed by branch B's conflict in the same follow-up", async () => {
+    const gate = deferred<void>();
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> => {
+        if (id === 'main') await gate.promise;
+        if (id === 'juan%2Fy') return { branch: 'juan/y', outcome: 'conflict', conflictedPaths: ['a.md'], error: 'msg' };
+        return updated(decodeURIComponent(id));
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const first = svc.sync({ branches: ['main'] });
+    const hookA = svc.sync({ branches: ['ali/x'] });
+    const hookB = svc.sync({ branches: ['juan/y'] });
+    gate.resolve();
+    await first;
+    const a = await hookA;
+    const b = await hookB;
+    expect(a).toMatchObject({ status: 'synced', results: [updated('ali/x')] });
+    expect(b.status).toBe('partial');
+    expect(b.results.map((r) => r.outcome)).toEqual(['conflict']);
+    // The record keeps the whole follow-up.
+    expect(svc.lastSync()?.results.map((r) => r.branch)).toEqual(['ali/x', 'juan/y']);
+  });
+});
+
+describe('KbSyncService — a waiter keeps the branches it asked for', () => {
+  it('a caller that edits its array after queueing changes nothing about its sync or its answer', async () => {
+    const gate = deferred<void>();
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => {
+        if (id === 'main') await gate.promise;
+        return updated(decodeURIComponent(id));
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const first = svc.sync({ branches: ['main'] });
+    const asked = ['ali/x'];
+    const waiting = svc.sync({ branches: asked });
+    asked.push('juan/y');
+    asked[0] = 'main';
+    gate.resolve();
+    await first;
+    const r = await waiting;
+    expect(r.results.map((x) => x.branch)).toEqual(['ali/x']);
+    expect(workflow.syncWorkspaceFromRemote).not.toHaveBeenCalledWith('juan%2Fy');
+  });
+});

package/src/modules/kb-sync/__tests__/sync-auth.test.ts

@@ -0,0 +1,118 @@
+import { createHmac } from 'node:crypto';
+import { describe, expect, it, vi } from 'vitest';
+import { verifySyncCredential, type SyncSessionVerifier } from '../sync-auth.js';
+
+const SECRET = 'a-very-long-and-random-sync-secret';
+
+function session(opts: { email?: string; admin?: boolean } = {}): SyncSessionVerifier {
+  return {
+    verifyJwt: vi.fn((token: string) =>
+      token === 'jwt-ok' && opts.email ? { email: opts.email } : null,
+    ),
+    isAdmin: vi.fn(async () => opts.admin === true),
+  };
+}
+
+describe('verifySyncCredential', () => {
+  it('accepts the secret as a bearer', async () => {
+    const r = await verifySyncCredential(
+      { secret: SECRET, authorization: `Bearer ${SECRET}` },
+      session(),
+    );
+    expect(r).toEqual({ ok: true, credential: { kind: 'bearer' } });
+  });
+
+  it('refuses a wrong bearer with 401', async () => {
+    const r = await verifySyncCredential(
+      { secret: SECRET, authorization: 'Bearer nope' },
+      session(),
+    );
+    expect(r).toMatchObject({ ok: false, status: 401 });
+  });
+
+  it('refuses a missing credential with 401', async () => {
+    const r = await verifySyncCredential({ secret: SECRET }, session());
+    expect(r).toMatchObject({ ok: false, status: 401 });
+  });
+
+  it('accepts the GitLab token header', async () => {
+    const r = await verifySyncCredential({ secret: SECRET, gitlabToken: SECRET }, session());
+    expect(r).toEqual({ ok: true, credential: { kind: 'gitlab-token' } });
+  });
+
+  it('accepts a GitHub signature over the raw body, and only over those bytes', async () => {
+    const body = Buffer.from('{"ref":"refs/heads/main"}');
+    const sig = 'sha256=' + createHmac('sha256', SECRET).update(body).digest('hex');
+    expect(
+      await verifySyncCredential({ secret: SECRET, hubSignature: sig, rawBody: body }, session()),
+    ).toEqual({ ok: true, credential: { kind: 'github-signature' } });
+    expect(
+      await verifySyncCredential(
+        { secret: SECRET, hubSignature: sig, rawBody: Buffer.from('{"ref":"refs/heads/other"}') },
+        session(),
+      ),
+    ).toMatchObject({ ok: false, status: 401 });
+    expect(
+      await verifySyncCredential(
+        { secret: SECRET, hubSignature: 'sha1=abc', rawBody: body },
+        session(),
+      ),
+    ).toMatchObject({ ok: false, status: 401 });
+  });
+
+  it("accepts an admin's own session as the bearer", async () => {
+    const r = await verifySyncCredential(
+      { secret: SECRET, authorization: 'Bearer jwt-ok' },
+      session({ email: 'admin@example.com', admin: true }),
+    );
+    expect(r).toEqual({
+      ok: true,
+      credential: { kind: 'admin-session', email: 'admin@example.com' },
+    });
+  });
+
+  it("refuses a non-admin's session", async () => {
+    const r = await verifySyncCredential(
+      { secret: SECRET, authorization: 'Bearer jwt-ok' },
+      session({ email: 'someone@example.com', admin: false }),
+    );
+    expect(r).toMatchObject({ ok: false, status: 401 });
+  });
+
+  it('with no secret configured, a header credential gets 503 that says so', async () => {
+    const r = await verifySyncCredential({ secret: '', authorization: 'Bearer anything' }, session());
+    expect(r).toMatchObject({ ok: false, status: 503 });
+    expect((r as { message: string }).message).toContain('KB_SYNC_SECRET');
+  });
+
+  it('with no secret configured, an admin session still works', async () => {
+    const r = await verifySyncCredential(
+      { secret: '', authorization: 'Bearer jwt-ok' },
+      session({ email: 'admin@example.com', admin: true }),
+    );
+    expect(r).toMatchObject({ ok: true });
+  });
+
+  it('with no secret configured and no credential, 401 not 503', async () => {
+    expect(await verifySyncCredential({ secret: '' }, session())).toMatchObject({
+      ok: false,
+      status: 401,
+    });
+  });
+});
+
+describe('verifySyncCredential — a secret set too short', () => {
+  it('is refused with 503 that says so, even when the caller presents it exactly', async () => {
+    const r = await verifySyncCredential({ secret: 'short', authorization: 'Bearer short' }, session());
+    expect(r).toMatchObject({ ok: false, status: 503 });
+    expect((r as { message: string }).message).toContain('shorter than 16');
+  });
+
+  it('an admin session still works past a too-short secret', async () => {
+    const r = await verifySyncCredential(
+      { secret: 'short', authorization: 'Bearer jwt-ok' },
+      session({ email: 'admin@example.com', admin: true }),
+    );
+    expect(r).toMatchObject({ ok: true });
+  });
+});

package/src/modules/kb-sync/__tests__/sync-payload.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+import { parseSyncPayload } from '../sync-payload.js';
+
+describe('parseSyncPayload', () => {
+  it('an empty or foreign body syncs everything', () => {
+    expect(parseSyncPayload(undefined)).toEqual({ source: 'none', branches: 'all', invalid: [] });
+    expect(parseSyncPayload({ hello: 'world' })).toEqual({ source: 'none', branches: 'all', invalid: [] });
+    expect(parseSyncPayload('text')).toEqual({ source: 'none', branches: 'all', invalid: [] });
+  });
+
+  it('explicit branches are kept in order, trimmed and de-duplicated', () => {
+    expect(parseSyncPayload({ branches: [' main ', 'ali/x', 'main'] })).toEqual({
+      source: 'explicit',
+      branches: ['main', 'ali/x'],
+      invalid: [],
+    });
+  });
+
+  it('an explicit name git would refuse is reported, not silently dropped', () => {
+    const parsed = parseSyncPayload({ branches: ['main', '--upload-pack=x', 'a..b', 7] });
+    expect(parsed.branches).toEqual(['main']);
+    expect(parsed.invalid).toEqual(['--upload-pack=x', 'a..b', '7']);
+  });
+
+  it('an explicit `branches` that is not a list means everything', () => {
+    expect(parseSyncPayload({ branches: 'main' }).branches).toBe('all');
+  });
+
+  it('Azure DevOps push: every updated head ref, tags ignored', () => {
+    const parsed = parseSyncPayload({
+      eventType: 'git.push',
+      resource: {
+        refUpdates: [
+          { name: 'refs/heads/main', oldObjectId: 'a', newObjectId: 'b' },
+          { name: 'refs/tags/v1', oldObjectId: '0', newObjectId: 'c' },
+          { name: 'refs/heads/ali/new-skill' },
+        ],
+      },
+    });
+    expect(parsed).toEqual({
+      source: 'azure-devops',
+      branches: ['main', 'ali/new-skill'],
+      invalid: [],
+    });
+  });
+
+  it('Azure DevOps pull request: target then source', () => {
+    for (const eventType of ['git.pullrequest.created', 'git.pullrequest.updated', 'git.pullrequest.merged']) {
+      const parsed = parseSyncPayload({
+        eventType,
+        resource: {
+          sourceRefName: 'refs/heads/ali/new-skill',
+          targetRefName: 'refs/heads/main',
+          status: 'completed',
+        },
+      });
+      expect(parsed).toEqual({
+        source: 'azure-devops',
+        branches: ['main', 'ali/new-skill'],
+        invalid: [],
+      });
+    }
+  });
+
+  it('an Azure DevOps event we do not know syncs everything', () => {
+    expect(parseSyncPayload({ eventType: 'build.complete', resource: {} }).branches).toBe('all');
+  });
+
+  it('GitHub push: the pushed branch', () => {
+    expect(parseSyncPayload({ ref: 'refs/heads/main', before: 'a', after: 'b' })).toEqual({
+      source: 'github',
+      branches: ['main'],
+      invalid: [],
+    });
+  });
+
+  it('GitHub tag push names nothing to sync', () => {
+    expect(parseSyncPayload({ ref: 'refs/tags/v1' })).toEqual({
+      source: 'github',
+      branches: [],
+      invalid: [],
+    });
+  });
+
+  it('GitLab push: the pushed branch', () => {
+    expect(parseSyncPayload({ object_kind: 'push', ref: 'refs/heads/main' })).toEqual({
+      source: 'gitlab',
+      branches: ['main'],
+      invalid: [],
+    });
+  });
+});
+
+describe('parseSyncPayload — hostile shapes', () => {
+  it('an explicit entry that cannot be stringified is reported, not thrown', () => {
+    const parsed = parseSyncPayload({ branches: ['main', { toString: 1 }, [1], null] });
+    expect(parsed.branches).toEqual(['main']);
+    expect(parsed.invalid).toEqual(['(object)', '(array)', 'null']);
+  });
+
+  it('a GitLab event that is not a push falls back to everything, even with a stray ref', () => {
+    expect(parseSyncPayload({ object_kind: 'merge_request', ref: 'refs/heads/main' })).toEqual({
+      source: 'none',
+      branches: 'all',
+      invalid: [],
+    });
+  });
+
+  it('a GitLab tag push names nothing to sync', () => {
+    expect(parseSyncPayload({ object_kind: 'tag_push', ref: 'refs/tags/v1' })).toEqual({
+      source: 'gitlab',
+      branches: [],
+      invalid: [],
+    });
+  });
+});
+
+describe('parseSyncPayload — deletions', () => {
+  it('a GitHub branch deletion names its branch, so the sync finds it gone and retires the clone', () => {
+    expect(parseSyncPayload({ ref: 'refs/heads/ali/x', deleted: true, after: '0'.repeat(40) })).toEqual({
+      source: 'github',
+      branches: ['ali/x'],
+      invalid: [],
+    });
+  });
+
+  it('an Azure DevOps deletion (new object id all zeros) names its branch beside the real update', () => {
+    expect(
+      parseSyncPayload({
+        eventType: 'git.push',
+        resource: {
+          refUpdates: [
+            { name: 'refs/heads/ali/x', oldObjectId: 'a'.repeat(40), newObjectId: '0'.repeat(40) },
+            { name: 'refs/heads/main', oldObjectId: 'b'.repeat(40), newObjectId: 'c'.repeat(40) },
+          ],
+        },
+      }),
+    ).toEqual({ source: 'azure-devops', branches: ['ali/x', 'main'], invalid: [] });
+  });
+
+  it('a GitLab branch deletion (after all zeros) names its branch', () => {
+    expect(parseSyncPayload({ object_kind: 'push', ref: 'refs/heads/ali/x', after: '0'.repeat(40) })).toEqual({
+      source: 'gitlab',
+      branches: ['ali/x'],
+      invalid: [],
+    });
+  });
+});

package/src/modules/kb-sync/index.ts

@@ -0,0 +1,19 @@
+export type {
+  IKbSyncService,
+  LastSync,
+  SyncRequest,
+  SyncResult,
+  SyncWorkflowPort,
+  SyncWorkspacePort,
+} from './kb-sync.interface.js';
+export { KbSyncService } from './kb-sync.service.js';
+export {
+  createKbSyncRoutes,
+  httpStatusFor,
+  isSyncRawBodyPath,
+  SYNC_RESPONSE_HEADER,
+  SYNC_RESPONSE_MARKER,
+  type KbSyncRouteDeps,
+} from './kb-sync.routes.js';
+export { parseSyncPayload, type ParsedSyncPayload, type SyncPayloadSource } from './sync-payload.js';
+export { verifySyncCredential, type SyncAuthInput, type SyncAuthResult, type SyncCredential } from './sync-auth.js';

package/src/modules/kb-sync/kb-sync.interface.ts

@@ -0,0 +1,79 @@
+import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
+
+/**
+ * Remote sync: a git host (Azure DevOps, GitHub, GitLab, a pipeline) tells
+ * Hexis "the repository changed" and Hexis brings the clones it holds up to
+ * date. The module owns the HTTP surface, the credential check, the payload
+ * parsing and the coalescing; every git operation happens behind the
+ * workflow port below, never here.
+ */
+
+/** Which branches a caller asked to sync. `'all'` = every clone Hexis holds. */
+export interface SyncRequest {
+  branches: string[] | 'all';
+  /** Who asked — a credential kind or an admin's email — for the last-sync record. */
+  by?: string;
+}
+
+/**
+ * What the most recent sync did, for the admin's Deployment page. Kept in
+ * memory only: it answers "is the hook wired up and working?", and a restart
+ * resetting it to "none yet" is the honest answer for a fresh process.
+ */
+export interface LastSync {
+  /** Epoch ms when the sync finished. */
+  at: number;
+  by: string;
+  status: SyncResult['status'];
+  /** One entry per branch, as the response carried them. */
+  results: BranchSyncOutcome[];
+}
+
+export interface SyncResult {
+  /** `synced` when no branch needs a person or a retry; `partial` otherwise. */
+  status: 'synced' | 'partial';
+  results: BranchSyncOutcome[];
+  changeRequests: {
+    /** Open change requests closed because one of their branches is gone from the host. */
+    closedDeletedBranch: number;
+  };
+}
+
+export interface IKbSyncService {
+  /**
+   * Sync the requested branches. One sync runs at a time; a request arriving
+   * mid-run is folded into a single queued follow-up (the union of every
+   * request that arrived meanwhile) and resolves with that follow-up's result.
+   * Never rejects for a per-branch failure — those are outcomes.
+   */
+  sync(request: SyncRequest): Promise<SyncResult>;
+  /** The most recent completed sync in this process, or null before the first. */
+  lastSync(): LastSync | null;
+}
+
+/** The slice of the workflow module a sync drives. */
+export interface SyncWorkflowPort {
+  syncWorkspaceFromRemote(workspaceId: string): Promise<BranchSyncOutcome>;
+  /**
+   * Retire the clone of a branch the host deleted, under the branch-lifecycle
+   * lock and only if origin still lacks it. Returns whether it was removed.
+   */
+  retireRemoteGoneClone(workspaceId: string): Promise<boolean>;
+  /** The existing sweep; returns how many requests it closed. */
+  closeChangeRequestsWithDeletedBranches(): Promise<number>;
+}
+
+/**
+ * The slice of the workspace module a sync reads: which clones exist ON
+ * DISK. Not the in-memory "seen this process" cache — clones survive a
+ * restart and a hook that fires before anyone has opened a branch must still
+ * find them.
+ */
+export interface SyncWorkspacePort {
+  /**
+   * `unreadable` names a clone the listing could see but not probe (an ACL,
+   * a half-deleted directory); the sync reports it as that branch's error
+   * rather than letting one bad directory fail every other branch.
+   */
+  listClonedWorkspaces(): Promise<Array<{ id: string; branch: string; unreadable?: string }>>;
+}