@bevel-software/platform-core-backend 0.30.0 → 0.32.0

package/src/modules/tool-helpers/tool-context.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { LocalFilesystem } from '@mastra/core/workspace';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
 import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
+import type { WriteValidator } from '../kb-fs/index.js';
 import { ReadOnlyFilesystem } from '../kb-fs/read-only-filesystem.js';
 import {
   makeAgentRolesYamlWriteValidator,
@@ -76,6 +77,36 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
     if (!user) throw new ToolError('Your account is no longer available.', 401);
 
     const { loadActiveGroups } = deps;
+    const validatorCache = new Map<string, WriteValidator>();
+    /**
+     * The agent's pre-disk `roles.yaml` gate for `branch`'s workspace
+     * (cached): refuses a write that would leave the file unparseable (an
+     * app-wide admin lockout), that creates a role, or that adds a
+     * `- group:` entry naming no group — agents manage membership; roles are
+     * pre-set. ONE gate for every agent write to the workspace: the file
+     * tools take it before a byte lands, and `update_branch` takes it for a
+     * resolution's content before the merge.
+     */
+    const getWriteValidator = async (branch: string): Promise<WriteValidator> => {
+      assertBranchProvided(branch);
+      const cached = validatorCache.get(branch);
+      if (cached) return cached;
+      const ws = await deps.workspaceService.getOrCreateForUser(user, branch);
+      const basePath = await deps.workspaceService.getWorkspacePath(ws.id);
+      const validator = makeAgentRolesYamlWriteValidator(
+        deps.kbDirName,
+        () => readTextIfExists(path.join(basePath, deps.kbDirName, ROLES_YAML_BASENAME)),
+        loadActiveGroups &&
+          (async () => {
+            // A source that exists but cannot be read leaves group entries
+            // unchecked rather than refusing every one.
+            const active = await loadActiveGroups((file) => readTextIfExists(path.join(basePath, deps.kbDirName, file)));
+            return active.health.ok ? active : null;
+          }),
+      );
+      validatorCache.set(branch, validator);
+      return validator;
+    };
     const fsCache = new Map<string, LocalFilesystem>();
     const getFilesystem = async (branch: string): Promise<LocalFilesystem> => {
       // THE choke point: every knowledge-base tool resolves its workspace
@@ -94,6 +125,7 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
       assertBranchProvided(branch);
       const cached = fsCache.get(branch);
       if (cached) return cached;
+      // (The write validator below is built through `getWriteValidator`.)
       const ws = await deps.workspaceService.getOrCreateForUser(user, branch);
       const workspaceId = ws.id;
       const basePath = await deps.workspaceService.getWorkspacePath(workspaceId);
@@ -107,24 +139,10 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
                 branch: branchForWorkspaceId(workspaceId),
                 user,
                 kbDirName: deps.kbDirName,
-                // Reject an agent write that would leave roles.yaml unparseable
-                // (app-wide admin lockout) or that creates a role before it
-                // reaches disk, or that adds a `- group:` entry naming no group
-                // — the agent gets a tool error and the file is untouched.
-                // Agents manage membership; roles are pre-set.
-                validateWrite: makeAgentRolesYamlWriteValidator(
-                  deps.kbDirName,
-                  () => readTextIfExists(path.join(basePath, deps.kbDirName, ROLES_YAML_BASENAME)),
-                  loadActiveGroups &&
-                    (async () => {
-                      // A source that exists but cannot be read leaves group
-                      // entries unchecked rather than refusing every one.
-                      const active = await loadActiveGroups((file) =>
-                        readTextIfExists(path.join(basePath, deps.kbDirName, file)),
-                      );
-                      return active.health.ok ? active : null;
-                    }),
-                ),
+                // The agent's pre-disk roles.yaml gate (`getWriteValidator`):
+                // the file tools and `update_branch`'s resolutions take the
+                // same one.
+                validateWrite: await getWriteValidator(branch),
                 creatorAccess: deps.creatorAccess,
               },
             )
@@ -155,6 +173,7 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
       workflowService: deps.workflowService,
       events: deps.events,
       getFilesystem,
+      getWriteValidator,
     };
   };
 }

package/src/modules/tool-helpers/tool.contract.ts

@@ -2,6 +2,7 @@ import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared
 import type { LocalFilesystem } from '@mastra/core/workspace';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { WriteValidator } from '../kb-fs/index.js';
 
 /**
  * The hosting/execution contract a module works against when it lets `toolHelpers`
@@ -63,6 +64,13 @@ export interface ToolContext {
   events: WorkflowEventBus;
   /** Build the lock-aware filesystem for `branch`'s workspace (cached). The tool supplies `branch` from its own input. */
   getFilesystem(branch: string): Promise<LocalFilesystem>;
+  /**
+   * The agent's pre-disk write gate for `branch`'s workspace (cached) — the
+   * one the filesystem above runs before a byte lands (`roles.yaml`: must
+   * parse, no new role, no unknown group). A tool that writes content by
+   * another road than that filesystem (a merge resolution) takes it too.
+   */
+  getWriteValidator(branch: string): Promise<WriteValidator>;
 }
 
 /**

package/src/modules/tool-registry/__tests__/own-tool-schemas.test.ts

@@ -59,7 +59,7 @@ const CORE_SERVER_SOURCE = new URL('../../../core/create-core-server.ts', import
 const MODULES: ReadonlyArray<{ name: string; register: (registry: ToolRegistry) => void }> = [
   {
     name: 'registerWorkflowTools',
-    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext(), async () => true),
+    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext(), async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never),
   },
   {
     name: 'registerChangeRequestReadTools',

package/src/modules/tool-registry/__tests__/tool-description-length.test.ts

@@ -117,7 +117,7 @@ async function hexisTools(skills: Parameters<typeof registerSkillsTools>[4] = em
     undefined,
     new WorkerPatternMatcher(),
   );
-  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true);
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never);
   registerPluginsTools(registry, kb);
   registerSkillsTools(registry, router, toolAuth, toolHandler, skills);
   registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {

package/src/modules/workflow/__tests__/change-request-hooks.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ChangeRequestHooks, type ChangeRequestOpenedEvent } from '../change-request-hooks.js';
+
+const EVENT: ChangeRequestOpenedEvent = {
+  number: 12,
+  title: 'Tidy the glossary',
+  sourceBranch: 'ali/x',
+  targetBranch: 'main',
+  openedBy: { id: 'u-ali', email: 'ali@acme.test', name: 'Ali' },
+  approvers: [{ id: 'u-dana', email: 'dana@acme.test', name: 'Dana' }],
+  unresolvedApprovers: 0,
+  pushPending: false,
+};
+
+describe('ChangeRequestHooks: a change request was opened', () => {
+  it('notifies nobody when nothing is registered, and says so', async () => {
+    expect(await new ChangeRequestHooks().runChangeRequestOpened(EVENT)).toEqual([]);
+  });
+
+  it('runs every listener in registration order, with the event, and collects the channels that reached the approvers', async () => {
+    const hooks = new ChangeRequestHooks();
+    const seen: string[] = [];
+    hooks.onChangeRequestOpened(async (event) => {
+      seen.push(`mail:#${event.number}:${event.approvers.map((a) => a.email).join(',')}`);
+      return 'email';
+    });
+    hooks.onChangeRequestOpened(async () => {
+      seen.push('chat');
+      return null;
+    });
+    hooks.onChangeRequestOpened(async () => {
+      seen.push('sms');
+      return 'sms';
+    });
+    expect(await hooks.runChangeRequestOpened(EVENT)).toEqual(['email', 'sms']);
+    expect(seen).toEqual(['mail:#12:dana@acme.test', 'chat', 'sms']);
+  });
+
+  it('a listener that throws counts as not having notified, and stops nothing', async () => {
+    const hooks = new ChangeRequestHooks();
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      hooks.onChangeRequestOpened(async () => {
+        throw new Error('smtp down');
+      });
+      hooks.onChangeRequestOpened(async () => 'email');
+      expect(await hooks.runChangeRequestOpened(EVENT)).toEqual(['email']);
+      // Logged, so a failing mailer is diagnosable from the server's log.
+      expect(error).toHaveBeenCalledTimes(1);
+      expect(String(error.mock.calls[0]![0])).toContain('a change-request-opened listener failed');
+    } finally {
+      error.mockRestore();
+    }
+  });
+
+  it('an empty channel name is no channel: it counts as not having notified', async () => {
+    const hooks = new ChangeRequestHooks();
+    hooks.onChangeRequestOpened(async () => '');
+    hooks.onChangeRequestOpened(async () => 'email');
+    expect(await hooks.runChangeRequestOpened(EVENT)).toEqual(['email']);
+  });
+});

package/src/modules/workflow/__tests__/workflow.routes.history-read-gate.test.ts

@@ -41,7 +41,12 @@ async function makeHarness(): Promise<Harness> {
   const accessControl = { canRead, canReadAtRef } as unknown as IAccessControl;
   const workflow = {
     listChangesForFile: vi.fn(async () => []),
-    compareFile: vi.fn(async () => ''),
+    compareFile: vi.fn(async (_w: string, _p: string, from: string, to: string, authorize?: (s: { from: string[]; to: string[] }) => Promise<void>) => {
+      // Each branch resolves to its served commit and, for `b`, a second one (a
+      // local head past the published tip): the verdict is asked at both.
+      await authorize?.({ from: [`sha-of-${from}`], to: [`sha-of-${to}`, `other-sha-of-${to}`] });
+      return { diff: '', from: `sha-of-${from}`, to: `sha-of-${to}` };
+    }),
     showFileAtChange: vi.fn(async () => ''),
     fileAtChange: vi.fn(async () => ({ baseline: null, current: 'x' })),
   };
@@ -113,23 +118,29 @@ describe('history routes enforce the read model', () => {
     expect(h.workflow.listChangesForFile).not.toHaveBeenCalled();
   });
 
-  it('compare-file authorizes at every ref the comparison could serve', async () => {
-    // The comparison prefers a local ref (and the working tree) over
-    // `origin/<branch>`, so BOTH candidates are authorized per branch.
+  it('compare-file authorizes at the two commits the diff was served from, never at a ref', async () => {
+    // The diff is made first, pinned to the commit each side was read at,
+    // and authorized at those before any of it is answered: a branch ref a
+    // fetch moves meanwhile cannot have swapped in content the verdict never
+    // saw.
     h = await makeHarness();
     const res = await get(`/compare-file?from=a&to=b&path=${OPEN}`);
     expect(res.status).toBe(200);
     const refs = h.canReadAtRef.mock.calls.map((c) => c[1]).sort();
-    expect(refs).toEqual(['a', 'b', 'origin/a', 'origin/b']);
+    expect(refs).toEqual(['other-sha-of-b', 'sha-of-a', 'sha-of-b']);
 
-    // Any RESOLVABLE ref denying the read refuses the diff.
-    h.canReadAtRef.mockImplementation(async (_w: string, ref: string) => (ref === 'b' ? false : true));
-    expect((await get(`/compare-file?from=a&to=b&path=${OPEN}`)).status).toBe(403);
+    // Any commit a side resolves to denying the read refuses the diff — the
+    // served one or the other (a grant at the served commit never outruns a
+    // denial at the branch's other tip) — disclosing none of it.
+    for (const denying of ['sha-of-a', 'sha-of-b', 'other-sha-of-b']) {
+      h.canReadAtRef.mockImplementation(async (_w: string, ref: string) => (ref === denying ? false : true));
+      const denied = await get(`/compare-file?from=a&to=b&path=${OPEN}`);
+      expect(denied.status, denying).toBe(403);
+      expect(await denied.json()).not.toHaveProperty('diff');
+    }
 
-    // A branch none of whose refs resolve cannot be authorized: refused.
-    h.canReadAtRef.mockImplementation(async (_w: string, ref: string) =>
-      ref.endsWith('b') ? null : true,
-    );
+    // A commit whose rules cannot be read grants nothing: refused.
+    h.canReadAtRef.mockImplementation(async (_w: string, ref: string) => (ref === 'sha-of-b' ? null : true));
     expect((await get(`/compare-file?from=a&to=b&path=${OPEN}`)).status).toBe(403);
   });
 

package/src/modules/workflow/__tests__/workflow.routes.open-change-request.test.ts

@@ -0,0 +1,79 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { WorkflowEventBus } from '../event-bus.js';
+import { createWorkflowRoutes } from '../workflow.routes.js';
+
+/**
+ * `POST /api/workflow/change-requests` answers the opened request as the
+ * service hands it over, `notified` included: the channels the deployment's
+ * change-request listeners said reached the approvers, so the dialog can say
+ * "the reviewers were emailed" — or hand over the link when nobody was.
+ */
+
+const ALICE: AuthUser = { id: '11111111-1111-4111-8111-111111111111', email: 'alice@example.com', name: 'Alice' };
+
+async function serve(workflow: Partial<IWorkflowService>): Promise<{ server: Server; baseUrl: string }> {
+  const authService = { getUserById: vi.fn(async () => ALICE) } as unknown as AuthService;
+  const workspaceService = {
+    getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: encodeURIComponent(branch) })),
+  } as unknown as WorkspaceService;
+  const app = express();
+  app.use(express.json());
+  app.use('/api', (req, _res, next) => {
+    (req as unknown as { userId: string }).userId = ALICE.id;
+    next();
+  });
+  app.use(
+    '/api',
+    createWorkflowRoutes(
+      workflow as IWorkflowService,
+      workspaceService,
+      authService,
+      new WorkflowEventBus(),
+      {} as unknown as IAccessControl,
+      'knowledge-base',
+    ),
+  );
+  const server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  return { server, baseUrl: `http://127.0.0.1:${(server.address() as AddressInfo).port}` };
+}
+
+describe('POST /workflow/change-requests answers who was notified', () => {
+  let server: Server | undefined;
+  afterEach(async () => {
+    if (server) await new Promise<void>((resolve, reject) => server!.close((e) => (e ? reject(e) : resolve())));
+    server = undefined;
+  });
+
+  it.each([
+    ['the channels that reached the approvers', ['email']],
+    ['nobody, truthfully', []],
+  ])('carries `notified`: %s', async (_what, notified) => {
+    const openChangeRequest = vi.fn(async () => ({ number: 12, branch: 'alice/deal', base: 'main', notified }) as never);
+    let baseUrl: string;
+    ({ server, baseUrl } = await serve({ openChangeRequest }));
+
+    const res = await fetch(`${baseUrl}/api/workflow/change-requests`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ sourceBranch: 'alice/deal', targetBranch: 'main', title: 'Deal' }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ number: 12, branch: 'alice/deal', base: 'main', notified });
+    // The open runs in the SOURCE branch's workspace, by the caller.
+    expect(openChangeRequest).toHaveBeenCalledTimes(1);
+    expect(openChangeRequest).toHaveBeenCalledWith(
+      encodeURIComponent('alice/deal'),
+      ALICE,
+      { sourceBranch: 'alice/deal', targetBranch: 'main', title: 'Deal', description: undefined },
+    );
+  });
+});

package/src/modules/workflow/__tests__/workflow.service.delete-branch.test.ts

@@ -115,6 +115,7 @@ interface Harness {
   deleted: string[];
   /** What the service announced to connected tabs. */
   emitted: { kind: string; number?: number }[];
+  changeRequestHooks: { onChangeRequestOpened: ReturnType<typeof vi.fn>; runChangeRequestOpened: ReturnType<typeof vi.fn> };
   hasAnyActive: MockInstance<FileLockService['hasAnyActive']>;
 }
 
@@ -142,6 +143,7 @@ function harness(opts: {
 }): Harness {
   const deleted: string[] = [];
   const emitted: { kind: string; number?: number }[] = [];
+  const changeRequestHooks = { onChangeRequestOpened: vi.fn(), runChangeRequestOpened: vi.fn(async () => []) };
   const rows = opts.rows ?? [];
   const branches = { ...(opts.branches ?? {}) };
   const git = {
@@ -212,8 +214,11 @@ function harness(opts: {
     testKbContext(),
     openChangeGate(),
     { emit: (e: { kind: string; number?: number }) => void emitted.push(e) } as unknown as WorkflowEventBus,
+    undefined,
+    undefined,
+    changeRequestHooks,
   );
-  return { svc, git, fetch, deleted, emitted, hasAnyActive };
+  return { svc, git, fetch, deleted, emitted, hasAnyActive, changeRequestHooks };
 }
 
 const merged = (number: number, source: string, sha: string | null): CrRow => ({
@@ -557,6 +562,9 @@ describe('a change request that proposes nothing never blocks a deletion', () =>
       expect.objectContaining({ number: 21, source: 'ali/sync', target: DEFAULT }),
       expect.objectContaining({ number: 22, source: 'ali/feature', target: 'ali/sync' }),
     ]);
+    // A reopened request was opened once already: the deployment's
+    // change-request-opened listeners are not told again.
+    expect(h.changeRequestHooks.runChangeRequestOpened).not.toHaveBeenCalled();
     // The app's path, the same.
     reopens.length = 0;
     await expect(h.svc.deleteBranch(workspaceIdForBranch(DEFAULT), 'ali/sync', ADMIN)).rejects.toThrow(/stale info/);