@bevel-software/platform-core-backend 0.1.0

package/src/modules/workflow/git/__tests__/git.service.pull.test.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { GitService } from '../git.service.js';
+import { runGit, gitOut, stubWorkflowHooks, stubWorkspaceService } from './git-test-helpers.js';
+
+/** See git.service.createBranch.test.ts — same prod-mirroring layout. */
+async function seedWorkspace(root: string, workspaceId: string): Promise<{
+  upstream: string;
+  repo: string;
+}> {
+  const upstream = path.join(root, 'upstream.git');
+  await runGit(root, ['init', '--bare', '-b', 'target-company-state', upstream]);
+
+  const seed = path.join(root, '.seed');
+  await fs.mkdir(seed);
+  await runGit(seed, ['init', '-b', 'target-company-state']);
+  await runGit(seed, ['remote', 'add', 'origin', upstream]);
+  await runGit(seed, ['commit', '--allow-empty', '-m', 'init']);
+  await runGit(seed, ['push', 'origin', 'target-company-state']);
+  await runGit(upstream, ['symbolic-ref', 'HEAD', 'refs/heads/target-company-state']);
+
+  const workspaceDir = path.join(root, workspaceId);
+  const repo = path.join(workspaceDir, 'knowledge-base');
+  await fs.mkdir(workspaceDir, { recursive: true });
+  await runGit(root, ['clone', upstream, repo]);
+  // Give the clone a repo-local committer identity. Production workspaces
+  // always have one (every commitFile commit relies on it), but the bare CI
+  // runner has no global git identity — without this, a `pull --rebase` that
+  // has to *replay* a local commit (the autostash regression below) dies with
+  // "empty ident name". `GitService.git` runs git with the ambient env, so the
+  // identity must live in the repo, not just in this test's runGit env.
+  await runGit(repo, ['config', 'user.email', 'workspace@bevel.test']);
+  await runGit(repo, ['config', 'user.name', 'bevel Workspace']);
+  return { upstream, repo };
+}
+
+/** Advance origin by one commit so a pull actually has something to fast-forward. */
+async function advanceOrigin(root: string, upstream: string): Promise<void> {
+  const pusher = path.join(root, '.pusher');
+  await runGit(root, ['clone', upstream, pusher]);
+  await fs.writeFile(path.join(pusher, 'remote-change.txt'), 'from origin\n');
+  await runGit(pusher, ['add', '.']);
+  await runGit(pusher, ['commit', '-m', 'remote change']);
+  await runGit(pusher, ['push', 'origin', 'target-company-state']);
+}
+
+describe('GitService.pull', () => {
+  let root: string;
+  const workspaceId = 'target-company-state';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-pull-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  // Regression: a hand edit to the tracked branch can append a second
+  // `branch.<name>.merge` line, after which a bare `pull --rebase` dies with
+  // "Cannot rebase onto multiple branches". The explicit `pull origin <branch>`
+  // plus upstream self-heal must recover and actually pull origin's commit.
+  it('recovers from a multi-valued branch.<name>.merge config', async () => {
+    const { upstream, repo } = await seedWorkspace(root, workspaceId);
+    await advanceOrigin(root, upstream);
+
+    // Corrupt the upstream exactly as an out-of-band re-point would: a second
+    // merge ref bolted onto the existing one.
+    await runGit(repo, [
+      'config', '--add', 'branch.target-company-state.merge', 'refs/heads/some-other-branch',
+    ]);
+    const mergeRefsBefore = (await gitOut(repo, [
+      'config', '--get-all', 'branch.target-company-state.merge',
+    ])).split('\n').filter(Boolean);
+    expect(mergeRefsBefore.length).toBe(2);
+
+    const svc = new GitService(
+      stubWorkspaceService({ [workspaceId]: path.join(root, workspaceId) }),
+      stubWorkflowHooks(),
+      'knowledge-base',
+    );
+
+    await expect(svc.pull(workspaceId)).resolves.toBeUndefined();
+
+    // The pull landed origin's commit...
+    const head = await gitOut(repo, ['log', '-1', '--pretty=%s']);
+    expect(head).toBe('remote change');
+    const pulled = await fs.readFile(path.join(repo, 'remote-change.txt'), 'utf8');
+    expect(pulled.trim()).toBe('from origin');
+
+    // ...and the config self-healed back to a single merge ref.
+    const mergeRefsAfter = (await gitOut(repo, [
+      'config', '--get-all', 'branch.target-company-state.merge',
+    ])).split('\n').filter(Boolean);
+    expect(mergeRefsAfter).toEqual(['refs/heads/target-company-state']);
+  });
+
+  // Regression: the same clone can also accumulate a SECOND
+  // `remote.origin.fetch` refspec — a re-run `git remote add`, a
+  // `git remote set-branches --add`, a hand-edited `.git/config` — after which
+  // one fetch maps the branch in twice and the refresh dies with "Cannot
+  // rebase onto multiple branches". The pull must land origin's commit anyway
+  // and collapse the refspec list back to the single canonical one.
+  it('recovers from duplicated remote.origin.fetch refspecs', async () => {
+    const { upstream, repo } = await seedWorkspace(root, workspaceId);
+    await advanceOrigin(root, upstream);
+
+    await runGit(repo, [
+      'config', '--add', 'remote.origin.fetch', '+refs/heads/*:refs/remotes/origin/*',
+    ]);
+    await runGit(repo, [
+      'config', '--add', 'remote.origin.fetch',
+      '+refs/heads/target-company-state:refs/remotes/origin/target-company-state',
+    ]);
+    const refspecsBefore = (await gitOut(repo, [
+      'config', '--get-all', 'remote.origin.fetch',
+    ])).split('\n').filter(Boolean);
+    expect(refspecsBefore.length).toBe(3);
+
+    const svc = new GitService(
+      stubWorkspaceService({ [workspaceId]: path.join(root, workspaceId) }),
+      stubWorkflowHooks(),
+      'knowledge-base',
+    );
+
+    await expect(svc.pull(workspaceId)).resolves.toBeUndefined();
+
+    // Origin's commit landed...
+    expect(await gitOut(repo, ['log', '-1', '--pretty=%s'])).toBe('remote change');
+    // ...and the clone fetches through exactly one refspec again.
+    const refspecsAfter = (await gitOut(repo, [
+      'config', '--get-all', 'remote.origin.fetch',
+    ])).split('\n').filter(Boolean);
+    expect(refspecsAfter).toEqual(['+refs/heads/*:refs/remotes/origin/*']);
+  });
+
+  // The invariant behind the reported failure: `.git/FETCH_HEAD` is a single
+  // mutable file shared by every git process in the clone, and this app runs
+  // fetches on the same clone from paths that don't share the workspace mutex.
+  // A refresh that reads it can be steered by any of them; one that writes it
+  // can steer them. So the refresh must do neither.
+  it('neither reads nor writes the shared FETCH_HEAD', async () => {
+    const { upstream, repo } = await seedWorkspace(root, workspaceId);
+    await advanceOrigin(root, upstream);
+
+    // A hostile FETCH_HEAD: two for-merge entries, the first pointing at an
+    // unrelated commit. This is what a concurrent bare `git fetch origin`
+    // leaves on a clone whose `branch.<name>.merge` has drifted to two values
+    // — and what made `git pull --rebase` die with "Cannot rebase onto
+    // multiple branches".
+    // The stray entry must name a commit the refresh can never legitimately
+    // land on — this clone hasn't fetched yet, so plain `HEAD` still equals
+    // `origin/target-company-state` and the assertion below would pass even if
+    // FETCH_HEAD had been honoured. Park an unrelated commit in the object
+    // store instead, then step off it.
+    await runGit(repo, ['commit', '--allow-empty', '-m', 'stray']);
+    const strayCommit = await gitOut(repo, ['rev-parse', 'HEAD']);
+    await runGit(repo, ['reset', '--hard', 'HEAD~1']);
+    const originTip = await gitOut(repo, ['rev-parse', 'origin/target-company-state']);
+    const hostile =
+      `${strayCommit}\t\tbranch 'some-other-branch' of ${upstream}\n` +
+      `${originTip}\t\tbranch 'target-company-state' of ${upstream}\n`;
+    const fetchHeadPath = path.join(repo, '.git', 'FETCH_HEAD');
+    await fs.writeFile(fetchHeadPath, hostile);
+
+    const svc = new GitService(
+      stubWorkspaceService({ [workspaceId]: path.join(root, workspaceId) }),
+      stubWorkflowHooks(),
+      'knowledge-base',
+    );
+
+    await expect(svc.pull(workspaceId)).resolves.toBeUndefined();
+
+    // Landed origin's commit — not the stray head the hostile file names.
+    expect(await gitOut(repo, ['log', '-1', '--pretty=%s'])).toBe('remote change');
+    // ...and left the shared file exactly as it found it.
+    expect(await fs.readFile(fetchHeadPath, 'utf8')).toBe(hostile);
+  });
+
+  // Regression (BEVA-114): the cooperative push recovery pulls --rebase to
+  // integrate a diverged origin before retrying the push. A bare
+  // `pull --rebase` aborts outright when the working tree carries a modified
+  // tracked file ("cannot pull with rebase: You have unstaged changes") —
+  // exactly the state the validator's dashboard regeneration leaves behind —
+  // which strands the branch in an unrecoverable non-fast-forward loop.
+  // `--autostash` must stash the dirty edit, rebase the local commit onto
+  // origin, and reapply the edit so the retry push can fast-forward.
+  it('rebases past a dirty tracked file via autostash', async () => {
+    const { upstream, repo } = await seedWorkspace(root, workspaceId);
+
+    // A tracked, generated-style artifact shared by both sides as the base.
+    await fs.writeFile(path.join(repo, 'dash.html'), 'v0\n');
+    await runGit(repo, ['add', '.']);
+    await runGit(repo, ['commit', '-m', 'add dashboard']);
+    await runGit(repo, ['push', 'origin', 'target-company-state']);
+
+    // Origin advances independently...
+    await advanceOrigin(root, upstream);
+
+    // ...and so does the local branch → the two have diverged and a real
+    // rebase (not a fast-forward) is required to reconcile them.
+    await fs.writeFile(path.join(repo, 'local-change.txt'), 'local\n');
+    await runGit(repo, ['add', '.']);
+    await runGit(repo, ['commit', '-m', 'local change']);
+
+    // The validator-style regeneration leaves a modified tracked file dirty in
+    // the working tree — the exact condition that makes a bare `pull --rebase`
+    // abort with "you have unstaged changes".
+    await fs.writeFile(path.join(repo, 'dash.html'), 'v1\n');
+
+    const svc = new GitService(
+      stubWorkspaceService({ [workspaceId]: path.join(root, workspaceId) }),
+      stubWorkflowHooks(),
+      'knowledge-base',
+    );
+
+    await expect(svc.pull(workspaceId)).resolves.toBeUndefined();
+
+    // Both commits are present — the local commit was rebased onto origin's.
+    const log = await gitOut(repo, ['log', '--pretty=%s']);
+    expect(log).toContain('remote change');
+    expect(log).toContain('local change');
+    const remote = await fs.readFile(path.join(repo, 'remote-change.txt'), 'utf8');
+    expect(remote.trim()).toBe('from origin');
+
+    // The dirty tracked edit survived — autostash reapplied it after the rebase.
+    const dash = await fs.readFile(path.join(repo, 'dash.html'), 'utf8');
+    expect(dash).toBe('v1\n');
+  });
+});

package/src/modules/workflow/git/__tests__/git.service.readFileAtRef.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import { WorkflowHooks } from '../../workflow-hooks.js';
+import { GitService } from '../git.service.js';
+
+const execFileAsync = promisify(execFile);
+const PROCESS_MAP_DIR = 'knowledge-base';
+
+async function runGit(cwd: string, args: string[]): Promise<void> {
+  await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test',
+      GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test',
+      GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+}
+
+async function seedWorkspace(root: string, workspaceId: string) {
+  const workspaceDir = path.join(root, workspaceId);
+  const repo = path.join(workspaceDir, PROCESS_MAP_DIR);
+  await fs.mkdir(repo, { recursive: true });
+  await runGit(repo, ['init', '-b', 'current-company-state']);
+  await runGit(repo, ['config', 'user.email', 't@x.com']);
+  await runGit(repo, ['config', 'user.name', 'Test']);
+  return { workspaceDir, repo };
+}
+
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+  } as unknown as WorkspaceService;
+}
+
+describe('GitService.readFileAtRef', () => {
+  let root: string;
+  const workspaceId = 'ws-read-at-ref-1';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-read-at-ref-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  function makeSvc(workspaceDir: string) {
+    return new GitService(
+      stubWorkspaceService(workspaceId, workspaceDir),
+      new WorkflowHooks(),
+      PROCESS_MAP_DIR,
+    );
+  }
+
+  it('returns the file content at a ref without touching the working tree', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const svc = makeSvc(workspaceDir);
+    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles:\n  Admin:\n    - a@x.com\n');
+    await runGit(repo, ['add', 'roles.yaml']);
+    await runGit(repo, ['commit', '-m', 'add roles']);
+
+    const out = await svc.readFileAtRef(workspaceId, 'HEAD', 'roles.yaml');
+    expect(out).toBe('roles:\n  Admin:\n    - a@x.com\n');
+  });
+
+  it('returns null when the path is absent at the ref (true absence)', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const svc = makeSvc(workspaceDir);
+    await fs.writeFile(path.join(repo, 'other.md'), 'x\n');
+    await runGit(repo, ['add', 'other.md']);
+    await runGit(repo, ['commit', '-m', 'add other']);
+
+    const out = await svc.readFileAtRef(workspaceId, 'HEAD', 'roles.yaml');
+    expect(out).toBeNull();
+  });
+
+  it('THROWS (fail-closed) on a non-absence git error such as an unresolvable ref', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const svc = makeSvc(workspaceDir);
+    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles: {}\n');
+    await runGit(repo, ['add', 'roles.yaml']);
+    await runGit(repo, ['commit', '-m', 'add roles']);
+
+    // An unresolvable ref is NOT "the path is absent" — it must propagate so a
+    // caller comparing base-vs-head can't misread the failure as "no roles.yaml".
+    await expect(
+      svc.readFileAtRef(workspaceId, 'origin/does-not-exist', 'roles.yaml'),
+    ).rejects.toThrow();
+  });
+});

package/src/modules/workflow/git/__tests__/git.service.status.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import { WorkflowHooks } from '../../workflow-hooks.js';
+import { GitService } from '../git.service.js';
+
+const execFileAsync = promisify(execFile);
+const PROCESS_MAP_DIR = 'knowledge-base';
+
+async function mkTmpRoot(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-status-'));
+}
+
+async function runGit(cwd: string, args: string[]): Promise<void> {
+  await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test',
+      GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test',
+      GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+}
+
+/**
+ * Seeds an upstream + per-user clone exactly like the list-branches harness,
+ * so a `git push -u` actually has somewhere to land. The clone starts on
+ * `current-company-state` with its upstream set; new local branches the test
+ * creates have no upstream until explicitly pushed.
+ */
+async function seedWorkspace(
+  root: string,
+  workspaceId: string,
+): Promise<{ workspaceDir: string; repo: string }> {
+  const upstream = path.join(root, 'upstream.git');
+  await runGit(root, ['init', '--bare', '-b', 'current-company-state', upstream]);
+
+  const seed = path.join(root, '.seed');
+  await fs.mkdir(seed);
+  await runGit(seed, ['init', '-b', 'current-company-state']);
+  await runGit(seed, ['remote', 'add', 'origin', upstream]);
+  await runGit(seed, ['commit', '--allow-empty', '-m', 'init']);
+  await runGit(seed, ['push', 'origin', 'current-company-state']);
+  await runGit(upstream, ['symbolic-ref', 'HEAD', 'refs/heads/current-company-state']);
+
+  const workspaceDir = path.join(root, workspaceId);
+  const repo = path.join(workspaceDir, PROCESS_MAP_DIR);
+  await fs.mkdir(workspaceDir, { recursive: true });
+  await runGit(root, ['clone', upstream, repo]);
+  return { workspaceDir, repo };
+}
+
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+  } as unknown as WorkspaceService;
+}
+
+describe('GitService.status — hasUpstream', () => {
+  let root: string;
+  const workspaceId = 'ws-status-1';
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  it('reports hasUpstream=true on a tracked branch (cloned from origin)', async () => {
+    const { workspaceDir } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), 'knowledge-base');
+
+    const status = await svc.status(workspaceId);
+    expect(status.branch).toBe('current-company-state');
+    expect(status.hasUpstream).toBe(true);
+    expect(status.unmergedFromUpstream).toBe(false);
+  });
+
+  it('reports hasUpstream=false on a freshly-created local branch that has never been pushed', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    // Branch off the protected base into a draft. No `--track` and no push,
+    // so it has no upstream — exactly the "unpublished draft" case the
+    // ShareChangesButton must offer to publish.
+    await runGit(repo, ['checkout', '-b', 'alice/unpublished-draft']);
+    await runGit(repo, ['commit', '--allow-empty', '-m', 'local-only edit']);
+
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), 'knowledge-base');
+    const status = await svc.status(workspaceId);
+
+    expect(status.branch).toBe('alice/unpublished-draft');
+    expect(status.hasUpstream).toBe(false);
+    // No upstream means there's nothing to diff against — the previous
+    // "always 0" behaviour is preserved, but the UI now learns the truth
+    // via `hasUpstream` instead of conflating it with "0 ahead".
+    expect(status.unmergedFromUpstream).toBe(false);
+  });
+
+  it('flips hasUpstream to true after the branch is pushed with -u', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    await runGit(repo, ['checkout', '-b', 'alice/published-draft']);
+    await runGit(repo, ['commit', '--allow-empty', '-m', 'one']);
+    await runGit(repo, ['commit', '--allow-empty', '-m', 'two']);
+    await runGit(repo, ['push', '-u', 'origin', 'alice/published-draft']);
+
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), 'knowledge-base');
+    const status = await svc.status(workspaceId);
+
+    expect(status.branch).toBe('alice/published-draft');
+    expect(status.hasUpstream).toBe(true);
+    // `unpushedCommits` removed from WorkingTreeStatus under save=share —
+    // every commit auto-pushes on lock release, so "ahead" is always 0 by
+    // construction. The remaining upstream-sync signal is
+    // `unmergedFromUpstream` (origin ahead of us, driven by teammates).
+  });
+});

package/src/modules/workflow/git/__tests__/mutex.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { WorkspaceMutex } from '../mutex.js';
+
+function deferred<T = void>() {
+  let resolve!: (v: T) => void;
+  const promise = new Promise<T>((r) => { resolve = r; });
+  return { promise, resolve };
+}
+
+describe('WorkspaceMutex', () => {
+  it('serializes tasks for the same key in submission order', async () => {
+    const mtx = new WorkspaceMutex();
+    const order: string[] = [];
+    const d1 = deferred();
+    const d2 = deferred();
+
+    const p1 = mtx.run('ws-1', async () => {
+      order.push('start-1');
+      await d1.promise;
+      order.push('end-1');
+    });
+    const p2 = mtx.run('ws-1', async () => {
+      order.push('start-2');
+      await d2.promise;
+      order.push('end-2');
+    });
+
+    // Yield so the first task actually starts before we release it.
+    await new Promise((r) => setImmediate(r));
+    expect(order).toEqual(['start-1']);
+    d1.resolve();
+    await p1;
+    // After 1 finishes, 2 should start.
+    await new Promise((r) => setImmediate(r));
+    expect(order).toEqual(['start-1', 'end-1', 'start-2']);
+    d2.resolve();
+    await p2;
+    expect(order).toEqual(['start-1', 'end-1', 'start-2', 'end-2']);
+  });
+
+  it('runs tasks for different keys concurrently', async () => {
+    const mtx = new WorkspaceMutex();
+    const order: string[] = [];
+    const dA = deferred();
+    const dB = deferred();
+
+    const pA = mtx.run('ws-a', async () => {
+      order.push('start-A');
+      await dA.promise;
+      order.push('end-A');
+    });
+    const pB = mtx.run('ws-b', async () => {
+      order.push('start-B');
+      await dB.promise;
+      order.push('end-B');
+    });
+
+    await new Promise((r) => setImmediate(r));
+    expect(order.sort()).toEqual(['start-A', 'start-B']);
+    // Finish B first despite starting A first — possible only because they ran in parallel.
+    dB.resolve();
+    await pB;
+    dA.resolve();
+    await pA;
+    expect(order).toEqual(['start-A', 'start-B', 'end-B', 'end-A']);
+  });
+
+  it('continues serving the queue after a task throws', async () => {
+    const mtx = new WorkspaceMutex();
+    const failing = mtx.run('ws-1', async () => {
+      throw new Error('boom');
+    });
+    await expect(failing).rejects.toThrow('boom');
+
+    const ok = await mtx.run('ws-1', async () => 42);
+    expect(ok).toBe(42);
+  });
+});