@bevel-software/platform-core-backend 0.1.0

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

@@ -0,0 +1,389 @@
+import { describe, it, expect, beforeEach, afterEach, vi } 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 type { IAccessControl } from '../../../access/access-control.interface.js';
+import { GitService } from '../git.service.js';
+import { AccessDeniedError } from '../../../access/access-errors.js';
+
+const execFileAsync = promisify(execFile);
+const PROCESS_MAP_DIR = 'knowledge-base';
+
+async function mkTmpRoot(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), 'bevel-access-gate-'));
+}
+
+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,
+): Promise<{ workspaceDir: string; repo: 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']);
+  // CI runners (and fresh dev machines) don't have a global git identity.
+  // `GitService.commit` uses `--author="..."` for the author but git still
+  // needs a committer identity — falling back to env vars / config. Setting
+  // local repo config keeps test runs reproducible without depending on the
+  // ambient env on the host.
+  await runGit(repo, ['config', 'user.email', 'test@bevel.local']);
+  await runGit(repo, ['config', 'user.name', 'Test Runner']);
+  return { workspaceDir, repo };
+}
+
+async function writeFile(repo: string, rel: string, contents: string): Promise<void> {
+  const abs = path.join(repo, rel);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, contents);
+}
+
+async function commitFile(
+  repo: string,
+  rel: string,
+  contents: string,
+  subject: string,
+): Promise<void> {
+  await writeFile(repo, rel, contents);
+  await runGit(repo, ['add', rel]);
+  await runGit(repo, ['commit', '-m', subject]);
+}
+
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+    ensureRemotesFetched: async () => undefined,
+  } as unknown as WorkspaceService;
+}
+
+/**
+ * Records every call into the access service and lets each test choose what
+ * the gate-relevant methods return. The unit under test is GitService's
+ * decision about WHICH ref to pass — the access service itself is exercised
+ * by its own test file.
+ */
+interface AccessRecord {
+  method: string;
+  ref: string;
+  userEmail: string;
+  paths: string[];
+}
+
+function recordingAccessControl(opts: {
+  canWriteAtRef?: (ref: string, email: string, path: string) => boolean | null;
+  canWriteBatchAtRef?: (ref: string, email: string, paths: string[]) => Map<string, boolean> | null;
+  eligible?: () => { roles: string[]; users: { name: string; email: string }[] };
+} = {}): { ac: IAccessControl; calls: AccessRecord[] } {
+  const calls: AccessRecord[] = [];
+  const ac: IAccessControl = {
+    canWrite: async () => true,
+    canWriteBatch: async (_w, _u, paths) => new Map(paths.map((p) => [p, true])),
+    canRead: async () => true,
+    canReadBatch: async (_w, _u, paths) => new Map(paths.map((p) => [p, true])),
+    eligibleReaders: async () => ({ restricted: false, roles: [], users: [] }),
+    canReadAtRef: async () => true,
+    canDownload: async () => false,
+    canOwner: async () => false,
+    eligibleOwners: async () => ({ roles: [], users: [] }),
+    eligibleDownloaders: async () => ({ roles: [], users: [] }),
+    eligibleWriters: async () => opts.eligible?.() ?? { roles: ['Admin'], users: [] },
+    eligibleWriterEmails: async () => new Map(),
+    eligibleOwnerEmails: async () => new Map(),
+    grantSources: async () => ({}),
+    invalidate: () => {},
+    canWriteAtRef: async (_w, ref, userEmail, p) => {
+      calls.push({ method: 'canWriteAtRef', ref, userEmail, paths: [p] });
+      return opts.canWriteAtRef?.(ref, userEmail, p) ?? true;
+    },
+    canWriteBatchAtRef: async (_w, ref, userEmail, paths) => {
+      calls.push({ method: 'canWriteBatchAtRef', ref, userEmail, paths });
+      return opts.canWriteBatchAtRef?.(ref, userEmail, paths) ?? new Map(paths.map((p) => [p, true]));
+    },
+    eligibleWritersAtRef: async () => opts.eligible?.() ?? { roles: ['Admin'], users: [] },
+    eligibleWritersForPathsAtRef: async (_w, _ref, paths) =>
+      new Map(paths.map((p) => [p, { roles: [], users: [], emails: new Set<string>() }])),
+    findEmailByHash: async () => null,
+    kbPrincipals: async () => ({ groups: [], people: [] }),
+    validateRolesYaml: () => ({ ok: true }),
+    referencesToRole: async () => [],
+  };
+  return { ac, calls };
+}
+
+async function makeSvc(
+  root: string,
+  workspaceId: string,
+  ac?: IAccessControl,
+): Promise<{ svc: GitService; repo: string; workspaceDir: string }> {
+  const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+  const svc = new GitService(
+    stubWorkspaceService(workspaceId, workspaceDir),
+    new WorkflowHooks(),
+    'knowledge-base',
+    undefined,
+    ac ?? null,
+  );
+  return { svc, repo, workspaceDir };
+}
+
+const USER = { id: 'user-alice', name: 'Alice', email: 'alice@bevel.software' };
+const SHARE_REQ = { summary: 'edit foo' };
+
+describe('GitService — commit gate uses HEAD (not working tree)', () => {
+  let root: string;
+  const workspaceId = 'ws-commit-gate';
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  it('passes ref=HEAD when checking the touched paths', async () => {
+    const { ac, calls } = recordingAccessControl();
+    const { svc, repo } = await makeSvc(root, workspaceId, ac);
+    await commitFile(repo, 'Knowledge/Foo.md', 'seed\n', 'seed');
+    await writeFile(repo, 'Knowledge/Foo.md', 'modified\n');
+
+    await svc.commit(workspaceId, USER, SHARE_REQ);
+
+    const gateCalls = calls.filter((c) => c.method === 'canWriteBatchAtRef');
+    expect(gateCalls).toHaveLength(1);
+    expect(gateCalls[0].ref).toBe('HEAD');
+    expect(gateCalls[0].userEmail).toBe(USER.email);
+    expect(gateCalls[0].paths).toContain('Knowledge/Foo.md');
+  });
+
+  it('refuses the commit with AccessDeniedError when the gate says no', async () => {
+    const { ac } = recordingAccessControl({
+      canWriteBatchAtRef: (_ref, _email, paths) => new Map(paths.map((p) => [p, false])),
+      eligible: () => ({ roles: ['Admin'], users: [] }),
+    });
+    const { svc, repo } = await makeSvc(root, workspaceId, ac);
+    await commitFile(repo, 'Knowledge/Foo.md', 'seed\n', 'seed');
+    await writeFile(repo, 'Knowledge/Foo.md', 'modified\n');
+
+    await expect(svc.commit(workspaceId, USER, SHARE_REQ)).rejects.toBeInstanceOf(AccessDeniedError);
+  });
+
+  it('allows the commit (bootstrap) when canWriteBatchAtRef returns null', async () => {
+    // null = HEAD has no usable access config (typically the very first
+    // commit creating roles.yaml). Without this, every initial commit would
+    // deadlock — you can't create the config because you don't have access,
+    // and you don't have access because there's no config.
+    const { ac, calls } = recordingAccessControl({
+      canWriteBatchAtRef: () => null,
+    });
+    const { svc, repo } = await makeSvc(root, workspaceId, ac);
+    await commitFile(repo, 'README.md', 'first\n', 'seed');
+    await writeFile(repo, 'roles.yaml', 'roles:\n  Admin:\n    - alice@bevel.software\n');
+
+    await expect(svc.commit(workspaceId, USER, SHARE_REQ)).resolves.toBeDefined();
+    const gateCalls = calls.filter((c) => c.method === 'canWriteBatchAtRef');
+    expect(gateCalls).toHaveLength(1);
+    expect(gateCalls[0].ref).toBe('HEAD');
+  });
+
+  it('skips the gate entirely when accessControl is null (legacy wiring)', async () => {
+    const { svc, repo } = await makeSvc(root, workspaceId); // no access service
+    await commitFile(repo, 'Knowledge/Foo.md', 'seed\n', 'seed');
+    await writeFile(repo, 'Knowledge/Foo.md', 'modified\n');
+    await expect(svc.commit(workspaceId, USER, SHARE_REQ)).resolves.toBeDefined();
+  });
+
+  it('skips the gate on non-protected (feature/draft) branches', async () => {
+    // After fork-to-draft the user is on a feature branch whose HEAD content
+    // is identical to the protected branch they forked from — so HEAD's
+    // access tree still says "Admin only". Without skipping the gate here,
+    // a non-admin's commit on their own draft would 403, breaking the
+    // entire propose-via-PR workflow.
+    const { ac, calls } = recordingAccessControl({
+      canWriteBatchAtRef: (_ref, _email, paths) => new Map(paths.map((p) => [p, false])),
+    });
+    const { svc, repo } = await makeSvc(root, workspaceId, ac);
+    await commitFile(repo, 'Knowledge/Foo.md', 'seed\n', 'seed');
+    await runGit(repo, ['checkout', '-b', 'alice/draft']);
+    await writeFile(repo, 'Knowledge/Foo.md', 'modified\n');
+
+    await expect(svc.commit(workspaceId, USER, SHARE_REQ)).resolves.toBeDefined();
+    expect(calls.filter((c) => c.method === 'canWriteBatchAtRef')).toHaveLength(0);
+  });
+});
+
+describe('GitService — revert gate uses HEAD', () => {
+  let root: string;
+  const workspaceId = 'ws-revert-gate';
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  it('passes ref=HEAD when gating a revert', async () => {
+    const { ac, calls } = recordingAccessControl();
+    const { svc, repo } = await makeSvc(root, workspaceId, ac);
+    await commitFile(repo, 'Knowledge/Foo.md', 'a\n', 'seed');
+    await commitFile(repo, 'Knowledge/Foo.md', 'b\n', 'second');
+    const { stdout: sha } = await execFileAsync('git', ['-C', repo, 'rev-parse', 'HEAD'], {
+      encoding: 'utf-8',
+    });
+
+    // We only care that the gate is invoked with `HEAD`; downstream
+    // behaviour of `git revert` (which may or may not succeed for unrelated
+    // environmental reasons — author parsing, signing config, etc.) is out
+    // of scope for this test.
+    await svc.revertCommit(workspaceId, USER, sha.trim()).catch(() => undefined);
+
+    const gateCalls = calls.filter((c) => c.method === 'canWriteBatchAtRef');
+    expect(gateCalls).toHaveLength(1);
+    expect(gateCalls[0].ref).toBe('HEAD');
+    expect(gateCalls[0].paths).toContain('Knowledge/Foo.md');
+  });
+
+  it('refuses with AccessDeniedError when the gate denies', async () => {
+    const { ac } = recordingAccessControl({
+      canWriteBatchAtRef: (_ref, _email, paths) => new Map(paths.map((p) => [p, false])),
+    });
+    const { svc, repo } = await makeSvc(root, workspaceId, ac);
+    await commitFile(repo, 'Knowledge/Foo.md', 'a\n', 'seed');
+    await commitFile(repo, 'Knowledge/Foo.md', 'b\n', 'second');
+    const { stdout: sha } = await execFileAsync('git', ['-C', repo, 'rev-parse', 'HEAD'], {
+      encoding: 'utf-8',
+    });
+
+    await expect(svc.revertCommit(workspaceId, USER, sha.trim())).rejects.toBeInstanceOf(
+      AccessDeniedError,
+    );
+  });
+});
+
+describe('GitService — push gate uses origin/<branch> (not HEAD or working tree)', () => {
+  let root: string;
+  const workspaceId = 'ws-push-gate';
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  async function setupWithOrigin(): Promise<{ svc: GitService; repo: string; calls: AccessRecord[] }> {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    // Stand up a bare repo as origin so push has something to talk to.
+    const originDir = path.join(root, 'origin.git');
+    await fs.mkdir(originDir);
+    await runGit(originDir, ['init', '--bare', '-b', 'current-company-state']);
+    await runGit(repo, ['remote', 'add', 'origin', originDir]);
+
+    // Seed origin with a baseline commit so `origin/<branch>` exists.
+    await commitFile(repo, 'Knowledge/Foo.md', 'seed\n', 'seed');
+    await runGit(repo, ['push', '-u', 'origin', 'current-company-state']);
+
+    // Make a local commit that hasn't been pushed yet.
+    await commitFile(repo, 'Knowledge/Foo.md', 'modified\n', 'edit');
+
+    const { ac, calls } = recordingAccessControl();
+    const svc = new GitService(
+      stubWorkspaceService(workspaceId, workspaceDir),
+      new WorkflowHooks(),
+      'knowledge-base',
+      undefined,
+      ac,
+    );
+    return { svc, repo, calls };
+  }
+
+  it('passes ref=origin/<branch> when gating the push', async () => {
+    const { svc, calls } = await setupWithOrigin();
+    await svc.push(workspaceId, USER);
+    const gateCalls = calls.filter((c) => c.method === 'canWriteBatchAtRef');
+    expect(gateCalls).toHaveLength(1);
+    expect(gateCalls[0].ref).toBe('origin/current-company-state');
+    expect(gateCalls[0].paths).toContain('Knowledge/Foo.md');
+  });
+
+  it('refuses the push when origin/<branch> rules deny the caller', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const originDir = path.join(root, 'origin.git');
+    await fs.mkdir(originDir);
+    await runGit(originDir, ['init', '--bare', '-b', 'current-company-state']);
+    await runGit(repo, ['remote', 'add', 'origin', originDir]);
+    await commitFile(repo, 'Knowledge/Foo.md', 'seed\n', 'seed');
+    await runGit(repo, ['push', '-u', 'origin', 'current-company-state']);
+    await commitFile(repo, 'Knowledge/Foo.md', 'modified\n', 'edit');
+
+    const { ac } = recordingAccessControl({
+      canWriteBatchAtRef: (ref, _email, paths) =>
+        ref === 'origin/current-company-state'
+          ? new Map(paths.map((p) => [p, false]))
+          : new Map(paths.map((p) => [p, true])),
+    });
+    const svc = new GitService(
+      stubWorkspaceService(workspaceId, workspaceDir),
+      new WorkflowHooks(),
+      'knowledge-base',
+      undefined,
+      ac,
+    );
+
+    await expect(svc.push(workspaceId, USER)).rejects.toBeInstanceOf(AccessDeniedError);
+  });
+
+  it('skips the gate entirely on non-protected (feature/draft) branches', async () => {
+    // The whole point of the draft-then-PR workflow is that non-admins can
+    // commit + push their own branches freely. Gating pushes on feature
+    // branches would 403 the share-changes flow for anyone without write
+    // access. Canonical state is only changed via PR merge, which has its
+    // own approval gate (`origin/<base>` access tree).
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const originDir = path.join(root, 'origin.git');
+    await fs.mkdir(originDir);
+    await runGit(originDir, ['init', '--bare', '-b', 'current-company-state']);
+    await runGit(repo, ['remote', 'add', 'origin', originDir]);
+    await commitFile(repo, 'Knowledge/Foo.md', 'seed\n', 'seed');
+    await runGit(repo, ['checkout', '-b', 'alice/fresh-draft']);
+    await commitFile(repo, 'Knowledge/Foo.md', 'on draft\n', 'edit on draft');
+
+    // Even an access service that would deny everything should be
+    // bypassed on a non-protected branch.
+    const { ac, calls } = recordingAccessControl({
+      canWriteBatchAtRef: (_ref, _email, paths) => new Map(paths.map((p) => [p, false])),
+    });
+    const svc = new GitService(
+      stubWorkspaceService(workspaceId, workspaceDir),
+      new WorkflowHooks(),
+      'knowledge-base',
+      undefined,
+      ac,
+    );
+
+    await expect(svc.push(workspaceId, USER)).resolves.toBeUndefined();
+    expect(calls.filter((c) => c.method === 'canWriteBatchAtRef')).toHaveLength(0);
+  });
+
+});

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

@@ -0,0 +1,124 @@
+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, parseNameStatusZ, parseNumstatZ } from '../git.service.js';
+
+const execFileAsync = promisify(execFile);
+
+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',
+    },
+  });
+}
+
+
+/** Bare upstream + one clone on `current-company-state`, mirroring prod layout. */
+async function seedWorkspace(root: string, workspaceId: 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 fs.writeFile(path.join(seed, 'base.md'), 'base\n');
+  await runGit(seed, ['add', '-A']);
+  await runGit(seed, ['commit', '-m', 'init']);
+  await runGit(seed, ['push', 'origin', 'current-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]);
+  return { upstream, repo };
+}
+
+function stubWorkspaceService(workspaceId: string, repo: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return path.dirname(repo);
+    },
+  } as unknown as WorkspaceService;
+}
+
+describe('parseNameStatusZ', () => {
+  it('parses adds/mods/deletes and rename pairs', () => {
+    const out = ['A', 'a.md', 'M', 'b.md', 'D', 'c.md', 'R100', 'old.md', 'new.md', ''].join('\0');
+    expect(parseNameStatusZ(out)).toEqual([
+      { status: 'added', path: 'a.md' },
+      { status: 'modified', path: 'b.md' },
+      { status: 'removed', path: 'c.md' },
+      { status: 'renamed', path: 'new.md', previousPath: 'old.md' },
+    ]);
+  });
+});
+
+describe('parseNumstatZ', () => {
+  it('parses counts, binary markers, and rename entries in order', () => {
+    // normal, binary, rename (empty path segment then two names)
+    const out = ['3\t1\ta.md', '-\t-\tlogo.png', '5\t2\t', 'old.md', 'new.md', ''].join('\0');
+    expect(parseNumstatZ(out)).toEqual([
+      { additions: 3, deletions: 1, isBinary: false },
+      { additions: 0, deletions: 0, isBinary: true },
+      { additions: 5, deletions: 2, isBinary: false },
+    ]);
+  });
+});
+
+describe('GitService.changedFilesForPr / resolvePrShas', () => {
+  let root: string;
+  const workspaceId = 'current-company-state';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-pr-files-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('computes the changed-file list + patches for a feature branch vs base', async () => {
+    const { repo } = await seedWorkspace(root, workspaceId);
+    // Build a feature branch with an add, a modify, and a delete.
+    await runGit(repo, ['checkout', '-b', 'alice/feature']);
+    await fs.writeFile(path.join(repo, 'added.md'), 'hello\nworld\n');
+    await fs.writeFile(path.join(repo, 'base.md'), 'base changed\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'feature work']);
+    await runGit(repo, ['push', '-u', 'origin', 'alice/feature']);
+
+    const git = new GitService(
+      stubWorkspaceService(workspaceId, repo),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+
+    const files = await git.changedFilesForPr(
+      workspaceId,
+      'current-company-state',
+      'alice/feature',
+    );
+    const byPath = Object.fromEntries(files.map((f) => [f.path, f]));
+    expect(byPath['added.md'].status).toBe('added');
+    expect(byPath['added.md'].additions).toBe(2);
+    expect(byPath['added.md'].patch).toContain('+hello');
+    expect(byPath['base.md'].status).toBe('modified');
+
+    const { baseSha, headSha } = await git.resolvePrShas(
+      workspaceId,
+      'current-company-state',
+      'alice/feature',
+    );
+    expect(baseSha).toMatch(/^[0-9a-f]{40}$/);
+    expect(headSha).toMatch(/^[0-9a-f]{40}$/);
+    expect(baseSha).not.toBe(headSha);
+  });
+});

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

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach, afterEach, vi } 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';
+
+/**
+ * `GitService.commitChanges` — the atomic multi-file batch primitive behind bulk
+ * node upload + the role-rename rewrite. It commits whatever is already dirty in
+ * the working tree as ONE commit attributed to the user (it does NOT write
+ * content — the caller writes the files first), idempotent on a clean tree.
+ */
+
+const execFileAsync = promisify(execFile);
+const PROCESS_MAP_DIR = 'knowledge-base';
+const USER = { id: 'u-alice', name: 'Alice', email: 'alice@bevel.software' };
+
+async function runGit(cwd: string, args: string[]): Promise<void> {
+  await execFileAsync('git', args, {
+    cwd,
+    env: { ...process.env, GIT_AUTHOR_NAME: 'T', GIT_AUTHOR_EMAIL: 't@x.com', GIT_COMMITTER_NAME: 'T', GIT_COMMITTER_EMAIL: 't@x.com' },
+  });
+}
+
+async function seedWorkspace(root: string, workspaceId: string): Promise<{ workspaceDir: string; repo: 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', 'feature-test']);
+  await runGit(repo, ['config', 'user.email', 'test@bevel.local']);
+  await runGit(repo, ['config', 'user.name', 'Test Runner']);
+  await fs.writeFile(path.join(repo, 'Old.md'), 'old\n');
+  await runGit(repo, ['add', 'Old.md']);
+  await runGit(repo, ['commit', '-m', 'seed']);
+  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;
+}
+
+function makeValidator(): WorkflowHooks {
+  const report = { ok: true, mustFix: [], warnings: [], rawOutput: '' };
+  // A clean-report commit-validation hook — the seam GitService consults
+  // where it used to call the injected validator.
+  const hooks = new WorkflowHooks();
+  hooks.onCommitValidation(vi.fn(async () => report));
+  return hooks;
+}
+
+describe('GitService.commitChanges', () => {
+  let root: string;
+  const workspaceId = 'ws-commitchanges-1';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-commitchanges-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  it('commits many dirty files + a delete as ONE commit attributed to the user', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), makeValidator(), PROCESS_MAP_DIR);
+
+    // The caller writes the batch to disk first (the git layer never writes content).
+    await fs.mkdir(path.join(repo, 'Product/Knowledge'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'Product/Knowledge/A.md'), 'a\n');
+    await fs.writeFile(path.join(repo, 'Product/Knowledge/B.md'), 'b\n');
+    await fs.rm(path.join(repo, 'Old.md'));
+
+    const change = await svc.commitChanges(workspaceId, USER, 'Bulk node upload (2 created, 1 moved)');
+
+    expect(change?.sha).toBeTruthy();
+    expect(change?.authorEmail).toBe('alice@bevel.software');
+    expect(change?.subject).toBe('Bulk node upload (2 created, 1 moved)');
+
+    // All three changes ride ONE commit.
+    const { stdout: nameStatus } = await execFileAsync('git', ['-C', repo, 'show', '--name-status', '--pretty=format:', 'HEAD']);
+    expect(nameStatus).toMatch(/A\s+Product\/Knowledge\/A\.md/);
+    expect(nameStatus).toMatch(/A\s+Product\/Knowledge\/B\.md/);
+    expect(nameStatus).toMatch(/D\s+Old\.md/);
+
+    // Working tree clean — everything was committed.
+    const { stdout: status } = await execFileAsync('git', ['-C', repo, 'status', '--porcelain']);
+    expect(status.trim()).toBe('');
+  });
+
+  it('returns null on a clean tree (nothing to commit)', async () => {
+    const { workspaceDir } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), makeValidator(), PROCESS_MAP_DIR);
+
+    const change = await svc.commitChanges(workspaceId, USER, 'no-op');
+    expect(change).toBeNull();
+  });
+});