@bevel-software/platform-core-backend 0.1.0

package/src/modules/workflow/__tests__/workflow.service.releaseLock.test.ts

@@ -0,0 +1,340 @@
+import { describe, it, expect, vi, beforeEach, type MockInstance } from 'vitest';
+import type { AuthUser, Change } from '@bevel-software/platform-shared';
+import type { GitService } from '../git/git.service.js';
+import type { PullRequestService } from '../git/pull-request.service.js';
+import type { IReviewWorkflowService } from '../review-workflow/review-workflow.interface.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import { FileLockService } from '../file-lock.service.js';
+import { PendingCommitsService } from '../pending-commits.service.js';
+import { WorkflowEventBus } from '../event-bus.js';
+import { WorkflowService } from '../workflow.service.js';
+import type { Database } from '../../database/connection.js';
+import {
+  PushNeedsAgentResolutionError,
+  WorkflowValidationError,
+} from '../workflow.errors.js';
+
+/**
+ * Two surfaces under test:
+ *
+ *   1. `WorkflowService.releaseLock` — new shape (enqueue + drop lock,
+ *      no synchronous commit).
+ *   2. `WorkflowService.runPendingCommit` — what the background worker
+ *      calls per claimed row. This is where the old releaseLock's
+ *      commit + cooperative-push + recovery body now lives, so the
+ *      non-FF + auth-failure + double-push-fail scenarios moved here.
+ *
+ * The non-fast-forward push recovery path has burned us in production
+ * before; every scenario asserts both the git calls AND the SSE
+ * events: a successful commit MUST emit `file-changed`; a failed
+ * commit MUST NOT (other clients would otherwise refetch a sha they
+ * can't reach on origin yet).
+ */
+
+const USER: AuthUser = {
+  id: 'user-1',
+  email: 'alice@example.com',
+  name: 'Alice',
+};
+
+const CHANGE: Change = {
+  sha: 'abc1234',
+  authorName: 'Alice',
+  authorEmail: 'alice@example.com',
+  subject: 'edit foo.md',
+  committedAt: '2026-04-20T00:00:00.000Z',
+};
+
+function makeFileLocks(holderUserId: string): FileLockService {
+  return {
+    acquire: vi.fn(),
+    heartbeat: vi.fn(),
+    release: vi.fn().mockResolvedValue(undefined),
+    get: vi.fn().mockResolvedValue({
+      branch: 'feat/x',
+      path: 'foo.md',
+      holderUserId,
+      holderName: 'Alice',
+      acquiredAt: '',
+      lastHeartbeatAt: '',
+      expiresAt: '',
+    }),
+  } as unknown as FileLockService;
+}
+
+function makePending(): PendingCommitsService {
+  return {
+    enqueue: vi.fn().mockResolvedValue(undefined),
+    claimNext: vi.fn().mockResolvedValue(null),
+    markSucceeded: vi.fn().mockResolvedValue(undefined),
+    markTransientFailure: vi.fn().mockResolvedValue(undefined),
+    markRecoveryStarted: vi.fn().mockResolvedValue(undefined),
+    markNeedsAttention: vi.fn().mockResolvedValue(undefined),
+    listNeedsAttention: vi.fn().mockResolvedValue([]),
+    countPending: vi.fn().mockResolvedValue(0),
+    startupReconcile: vi.fn().mockResolvedValue(undefined),
+  } as unknown as PendingCommitsService;
+}
+
+function makeGit(overrides: Partial<{
+  commitFile: Change | null;
+  pushBehavior: 'ok' | 'nff' | 'auth-fail';
+  pullBehavior: 'ok' | 'fail';
+  pushAfterPullBehavior: 'ok' | 'fail';
+}> = {}): GitService {
+  const commitFileResult = overrides.commitFile === undefined ? CHANGE : overrides.commitFile;
+  const pushBehavior = overrides.pushBehavior ?? 'ok';
+  const pullBehavior = overrides.pullBehavior ?? 'ok';
+  const pushAfterPullBehavior = overrides.pushAfterPullBehavior ?? 'ok';
+  let pushCalls = 0;
+  return {
+    commitFile: vi.fn().mockResolvedValue(commitFileResult),
+    push: vi.fn().mockImplementation(async () => {
+      pushCalls++;
+      const phase = pushCalls === 1 ? pushBehavior : pushAfterPullBehavior;
+      if (phase === 'nff') {
+        throw new Error(
+          'git push failed: Command failed: git push -u origin feat/x\n' +
+            ' ! [rejected]        feat/x -> feat/x (non-fast-forward)\n' +
+            'error: failed to push some refs to https://example.com/repo.git\n' +
+            'hint: Updates were rejected because the tip of your current branch is behind\n',
+        );
+      }
+      if (phase === 'auth-fail') {
+        throw new Error('git push failed: Command failed: ... fatal: Authentication failed');
+      }
+      if (phase === 'fail') {
+        throw new Error('git push failed (post-pull retry)');
+      }
+    }),
+    pull: vi.fn().mockImplementation(async () => {
+      if (pullBehavior === 'fail') throw new Error('git pull failed: merge conflict');
+    }),
+  } as unknown as GitService;
+}
+
+function makeFacade(
+  git: GitService,
+  locks: FileLockService,
+  pending: PendingCommitsService,
+  events: WorkflowEventBus,
+): WorkflowService {
+  return new WorkflowService(
+    {} as unknown as Database,
+    git,
+    {} as PullRequestService,
+    {} as IReviewWorkflowService,
+    {} as WorkspaceService,
+    {} as IAccessControl,
+    locks,
+    pending,
+    'knowledge-base',
+    events,
+  );
+}
+
+describe('WorkflowService.releaseLock — new (enqueue, no synchronous commit)', () => {
+  let events: WorkflowEventBus;
+  let emitSpy: MockInstance;
+
+  beforeEach(() => {
+    events = new WorkflowEventBus();
+    emitSpy = vi.spyOn(events, 'emit');
+  });
+
+  it('enqueues a pending-commit row, drops the lock, emits lock-released (NO commit, NO push)', async () => {
+    const git = makeGit();
+    const locks = makeFileLocks(USER.id);
+    const pending = makePending();
+    const svc = makeFacade(git, locks, pending, events);
+
+    await expect(svc.releaseLock('ws-1', 'feat/x', 'foo.md', USER)).resolves.toBeUndefined();
+
+    expect(pending.enqueue).toHaveBeenCalledWith({
+      workspaceId: 'ws-1',
+      branch: 'feat/x',
+      path: 'foo.md',
+      authorEmail: USER.email,
+      authorName: USER.name,
+    });
+    expect(locks.release).toHaveBeenCalledTimes(1);
+    // Critical: the new shape doesn't touch git on the user-visible
+    // path. Commit + push happen later in the worker via runPendingCommit.
+    expect(git.commitFile).not.toHaveBeenCalled();
+    expect(git.push).not.toHaveBeenCalled();
+    // Only lock-released fires synchronously now; file-changed lands when
+    // the worker's commit succeeds (covered in the runPendingCommit suite).
+    expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual(['lock-released']);
+  });
+
+  it('throws lock-not-held when the caller does not hold the lock', async () => {
+    const git = makeGit();
+    const locks = makeFileLocks('someone-else');
+    const pending = makePending();
+    const svc = makeFacade(git, locks, pending, events);
+
+    await expect(svc.releaseLock('ws-1', 'feat/x', 'foo.md', USER)).rejects.toBeInstanceOf(
+      WorkflowValidationError,
+    );
+    // Ownership guard MUST run before we enqueue — otherwise a non-holder
+    // could schedule a commit attributed to themselves on any file.
+    expect(pending.enqueue).not.toHaveBeenCalled();
+    expect(locks.release).not.toHaveBeenCalled();
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+
+  it('throws lock-not-held when the lock row is missing entirely (TTL expired + GC)', async () => {
+    const git = makeGit();
+    const locks = {
+      ...makeFileLocks(USER.id),
+      get: vi.fn().mockResolvedValue(null),
+    } as unknown as FileLockService;
+    const pending = makePending();
+    const svc = makeFacade(git, locks, pending, events);
+
+    await expect(svc.releaseLock('ws-1', 'feat/x', 'foo.md', USER)).rejects.toBeInstanceOf(
+      WorkflowValidationError,
+    );
+    expect(pending.enqueue).not.toHaveBeenCalled();
+  });
+
+  it('surfaces lock-release failure without rolling back the enqueue', async () => {
+    // Documents the deliberate ordering at workflow.service.ts:
+    // enqueue first, drop second. If `locks.release` throws after a
+    // successful `pending.enqueue`, we let the error propagate — the
+    // queued row stays so the worker eventually commits the file, and
+    // the held lock will be reaped by its TTL. "Brief over-lock" is the
+    // documented trade-off; the alternative (drop-then-enqueue) would
+    // re-introduce the orphan-files bug the queue exists to prevent.
+    const git = makeGit();
+    const locks = {
+      ...makeFileLocks(USER.id),
+      release: vi.fn().mockRejectedValue(new Error('db connection lost')),
+    } as unknown as FileLockService;
+    const pending = makePending();
+    const svc = makeFacade(git, locks, pending, events);
+
+    await expect(svc.releaseLock('ws-1', 'feat/x', 'foo.md', USER)).rejects.toThrow(
+      /db connection lost/,
+    );
+
+    // Enqueue happened first and was NOT compensated/rolled back.
+    expect(pending.enqueue).toHaveBeenCalledTimes(1);
+    expect(pending.enqueue).toHaveBeenCalledWith({
+      workspaceId: 'ws-1',
+      branch: 'feat/x',
+      path: 'foo.md',
+      authorEmail: USER.email,
+      authorName: USER.name,
+    });
+    // Release was attempted (and threw).
+    expect(locks.release).toHaveBeenCalledTimes(1);
+    // No git side effects on the user path — the worker handles those.
+    expect(git.commitFile).not.toHaveBeenCalled();
+    expect(git.push).not.toHaveBeenCalled();
+    // No `lock-released` event when the release itself failed; the lock
+    // is still held, and we'd lie to any SSE subscriber by emitting.
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe('WorkflowService.runPendingCommit — worker entry point', () => {
+  let events: WorkflowEventBus;
+  let emitSpy: MockInstance;
+
+  beforeEach(() => {
+    events = new WorkflowEventBus();
+    emitSpy = vi.spyOn(events, 'emit');
+  });
+
+  it('happy path: commits + pushes, emits file-changed with the new sha', async () => {
+    const git = makeGit();
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER);
+
+    expect(git.commitFile).toHaveBeenCalledTimes(1);
+    expect(git.push).toHaveBeenCalledTimes(1);
+    expect(git.pull).not.toHaveBeenCalled();
+    expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual(['file-changed']);
+    expect(emitSpy.mock.calls[0][0]).toMatchObject({
+      kind: 'file-changed',
+      newSha: CHANGE.sha,
+      byUserId: USER.id,
+    });
+  });
+
+  it('skips push + file-changed when commitFile reports nothing dirty (double-enqueue, identical bytes)', async () => {
+    // The worker treats a no-op commit as success and drops the row.
+    // No push, no SSE event — there's no new sha for clients to see.
+    const git = makeGit({ commitFile: null });
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER);
+
+    expect(git.commitFile).toHaveBeenCalledTimes(1);
+    expect(git.push).not.toHaveBeenCalled();
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+
+  it('recovers from non-fast-forward push via pull --rebase + retry, emits file-changed exactly once', async () => {
+    // Teammate pushed to the same branch between our commit and our
+    // push. The cooperative path pulls + retries — this is the case
+    // the worker handles without escalating to the recovery agent.
+    const git = makeGit({ pushBehavior: 'nff' });
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER);
+
+    expect(git.pull).toHaveBeenCalledTimes(1);
+    expect(git.push).toHaveBeenCalledTimes(2);
+    expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual(['file-changed']);
+  });
+
+  it('throws PushNeedsAgentResolutionError on auth failure so the worker can escalate', async () => {
+    // Auth failures aren't divergences pull-rebase can resolve. The
+    // worker's catch arm decides what to do (transient retry → recovery
+    // agent → needs_attention) based on its own budgets.
+    const git = makeGit({ pushBehavior: 'auth-fail' });
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    await expect(svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER)).rejects.toBeInstanceOf(
+      PushNeedsAgentResolutionError,
+    );
+    expect(git.pull).not.toHaveBeenCalled();
+    expect(git.push).toHaveBeenCalledTimes(1);
+    // The commit landed locally but we do NOT emit file-changed — other
+    // clients would refetch a SHA that's not yet on origin. Recovery
+    // (or the next worker pass) emits it when the push actually lands.
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+
+  it('throws PushNeedsAgentResolutionError when pull --rebase itself fails (textbook conflict case)', async () => {
+    const git = makeGit({ pushBehavior: 'nff', pullBehavior: 'fail' });
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    const err = await svc
+      .runPendingCommit('ws-1', 'feat/x', 'foo.md', USER)
+      .then(() => null)
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(PushNeedsAgentResolutionError);
+    expect((err as PushNeedsAgentResolutionError).branch).toBe('feat/x');
+    expect((err as PushNeedsAgentResolutionError).path).toBe('foo.md');
+    expect(git.pull).toHaveBeenCalledTimes(1);
+    expect(git.push).toHaveBeenCalledTimes(1);
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+
+  it('throws PushNeedsAgentResolutionError when post-pull retry also fails (origin moved twice)', async () => {
+    const git = makeGit({ pushBehavior: 'nff', pushAfterPullBehavior: 'fail' });
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    await expect(svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER)).rejects.toBeInstanceOf(
+      PushNeedsAgentResolutionError,
+    );
+    expect(git.pull).toHaveBeenCalledTimes(1);
+    expect(git.push).toHaveBeenCalledTimes(2);
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+});

package/src/modules/workflow/agent-tools/__tests__/workflow.tools.test.ts

@@ -0,0 +1,192 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../../../tool-registry/tool-registry.js';
+import { InternalTokenService } from '../../../tool-auth/internal-token.service.js';
+import { createToolAuthMiddleware } from '../../../tool-auth/tool-auth.middleware.js';
+import { createToolContextResolver } from '../../../tool-helpers/tool-context.js';
+import { createToolHandlerFactory } from '../../../tool-helpers/tool-handler.js';
+import { createManualRoutes } from '../../../tool-registry/manual.routes.js';
+import { registerWorkflowTools } from '../workflow.tools.js';
+
+const WS = 'target-company-state';
+
+let calls: unknown[][] = [];
+const externalApiKeyService = {
+  looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
+  verifyAndLoadToken: async (t: string) =>
+    t === 'bevel_key' ? { user: { id: 'user-A', email: 'e@x', name: 'N' }, tokenId: 'tok' } : null,
+} as never;
+const authService = { getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }) } as never;
+const workspaceService = {
+  getOrCreateForUser: async () => ({ id: WS }),
+  getWorkspacePath: async () => '/tmp/ws',
+  getOrCreateForBranch: async (b: string) => ({ id: b }),
+  // Repo-global tools resolve any existing clone instead of cloning a named branch.
+  findAnyWorkspaceId: async () => 'existing-ws',
+} as never;
+const workflowService = {
+  listBranches: async (ws: string) => {
+    calls.push(['listBranches', ws]);
+    return [{ name: 'main', isProtected: true }];
+  },
+  commitChange: async (ws: string, user: { id: string }, body: unknown) => {
+    calls.push(['commitChange', ws, user.id, body]);
+    return { id: 'change-1', ...(body as object) };
+  },
+  openChangeRequest: async (ws: string, user: { id: string }, body: unknown) => {
+    calls.push(['openChangeRequest', ws, user.id, body]);
+    return { number: 7, url: 'http://cr/7' };
+  },
+  createBranch: async (ws: string, name: string) => {
+    calls.push(['createBranch', ws, name]);
+    return { name, isProtected: false, ahead: 0, behind: 0, hasRemote: true };
+  },
+} as never;
+const events = {
+  emit: (p: unknown) => {
+    calls.push(['emit', p]);
+    return {};
+  },
+} as never;
+
+const internalToken = new InternalTokenService({ secret: 's' });
+let httpServer: HttpServer | undefined;
+
+async function start(): Promise<string> {
+  const registry = new ToolRegistry();
+  const toolAuth = createToolAuthMiddleware(externalApiKeyService, internalToken);
+  const resolve = createToolContextResolver({ authService, workspaceService, workflowService, events, kbDirName: 'knowledge-base', creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} } });
+  const toolHandler = createToolHandlerFactory(resolve);
+
+  const router = express.Router();
+  registerWorkflowTools(registry, router, toolAuth, toolHandler);
+  router.use(createManualRoutes(registry, toolAuth));
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', router);
+  httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+}
+
+const post = (url: string, bearer: string, body: unknown = {}) =>
+  fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${bearer}` }, body: JSON.stringify(body) });
+
+beforeEach(() => {
+  calls = [];
+});
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+});
+
+const writeTok = () => internalToken.mint({ userId: 'user-A' });
+
+describe('registerWorkflowTools', () => {
+  it('commit_change commits as the context user + workspace', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/commit_change`, writeTok(), { summary: 'fix typo', branch: WS });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ change: { id: 'change-1', summary: 'fix typo' } });
+    expect(calls).toContainEqual(['commitChange', WS, 'user-A', { summary: 'fix typo', description: undefined }]);
+  });
+
+  it('list_branches takes no branch and lists from any existing clone (repo-global)', async () => {
+    const base = await start();
+    // No `branch` in the body — the tool is repo-global. It must NOT try to
+    // resolve/clone a model-named branch (the `-b <branch>` clone-failure bug).
+    const res = await post(`${base}/api/agent/tools/list_branches`, writeTok(), {});
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ branches: [{ name: 'main' }] });
+    expect(calls).toContainEqual(['listBranches', 'existing-ws']);
+  });
+
+  it('open_change_request returns the CR detail', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/open_change_request`, writeTok(), {
+      sourceBranch: 'me/draft',
+      targetBranch: 'target-company-state',
+      title: 'My change',
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ changeRequest: { number: 7 } });
+    // The workspace must be derived from the SOURCE branch (not a separate
+    // `branch` arg) — encodeURIComponent('me/draft'). Regression guard for the
+    // `-b undefined` clone bug when the model omitted `branch`.
+    expect(calls).toContainEqual([
+      'openChangeRequest',
+      'me%2Fdraft',
+      'user-A',
+      { sourceBranch: 'me/draft', targetBranch: 'target-company-state', title: 'My change', description: undefined },
+    ]);
+  });
+
+  it('create_branch forks in the BASE branch\'s workspace, never the new draft\'s', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/create_branch`, writeTok(), {
+      name: 'me/new-draft',
+      branch: WS,
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ branch: { name: 'me/new-draft' } });
+    // Workspace derived from the existing base `branch`, not the
+    // not-yet-existing `name` — resolving `name`'s workspace lazily clones it
+    // and 500s with "Remote branch not found in upstream origin". No fromBase:
+    // the base is the workspace's own checked-out branch (HEAD).
+    expect(calls).toContainEqual(['createBranch', WS, 'me/new-draft']);
+  });
+
+  it('create_branch rejects `branch` naming the draft being created with a 400, not a clone 500', async () => {
+    const base = await start();
+    // The exact reported failure: the caller filled `branch` with the draft
+    // being created instead of the base to fork from.
+    const res = await post(`${base}/api/agent/tools/create_branch`, writeTok(), {
+      name: 'me/new-draft',
+      branch: 'me/new-draft',
+    });
+    expect(res.status).toBe(400);
+    expect(calls.filter((c) => c[0] === 'createBranch')).toHaveLength(0);
+  });
+
+  it('works under a connection key too (both surface)', async () => {
+    const base = await start();
+    expect((await post(`${base}/api/agent/tools/commit_change`, 'bevel_key', { summary: 's' })).status).toBe(200);
+  });
+
+  it('switch_branch validates + pre-warms + emits a user-scoped event (internal-only)', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/switch_branch`, writeTok(), { branch: 'main' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ switched: true, branch: 'main' });
+    expect(calls).toContainEqual([
+      'emit',
+      expect.objectContaining({ kind: 'branch-switched', forUserId: 'user-A', branch: 'main' }),
+    ]);
+    // unknown draft → 404
+    expect((await post(`${base}/api/agent/tools/switch_branch`, writeTok(), { branch: 'nope' })).status).toBe(404);
+  });
+
+  it('refuses switch_branch to an external connection key — internal-only is enforced at the route, not just hidden', async () => {
+    const base = await start();
+    // `bevel_key` authenticates as an external caller; the internal-only route
+    // must reject it (403) even though it knows the tool name.
+    expect((await post(`${base}/api/agent/tools/switch_branch`, 'bevel_key', { branch: 'main' })).status).toBe(403);
+  });
+
+  it('registers workflow tools into the right catalogs (switch_branch internal-only)', async () => {
+    const base = await start();
+    const fetchManual = async (which: 'utcp' | 'internal/utcp') =>
+      ((await (await fetch(`${base}/api/agent/${which}`, { headers: { authorization: `Bearer ${writeTok()}` } })).json()) as { tools: { name: string }[] }).tools
+        .map((t) => t.name)
+        .sort();
+    const internal = await fetchManual('internal/utcp');
+    const external = await fetchManual('utcp');
+    expect(internal).toContain('switch_branch');
+    expect(internal).toContain('commit_change');
+    expect(external).toContain('commit_change');
+    expect(external).not.toContain('switch_branch'); // internal-only
+  });
+});