@bevel-software/platform-core-backend 0.12.1 → 0.13.1

package/src/modules/workflow/review-workflow/__tests__/approval-states.test.ts

@@ -13,6 +13,7 @@ import type { WorkspaceService } from '../../../workspace/workspace.service.js';
 import type { GitService } from '../../git/git.service.js';
 import type { IAccessControl } from '../../../access/access-control.interface.js';
 import { hashEmail as hash } from '../../../../shared/hash-email.js';
+import { AccessUnreadableError } from '../../../access-model/access-errors.js';
 
 function file(overrides: Partial<PullRequestFile>): PullRequestFile {
   return {
@@ -557,3 +558,62 @@ describe('mergePr — roles.yaml privilege-escalation guard', () => {
     expect(mergeChangeRequestMock).toHaveBeenCalledTimes(1);
   });
 });
+
+/**
+ * An access tree that could not be READ is not the same as "no eligible
+ * writers": the latter drops a file out of the merge gate, so answering it for
+ * a lost git read would let a change merge past a deny nobody managed to
+ * load. The unreadable case propagates (the caller fails closed, 503); any
+ * other lookup failure still degrades to empty eligibility as documented.
+ */
+describe('ReviewWorkflowService.getApprovalStates — unreadable access tree', () => {
+  const FILES = [file({ path: 'Knowledge/Foo.md' })];
+  function serviceWith(overrides: Partial<IAccessControl>) {
+    const workspace = {
+      ensureRemotesFetched: vi.fn(async () => undefined),
+      getOrCreateForBranch: vi.fn(async () => ({ id: 'ws-base' })),
+    } as unknown as WorkspaceService;
+    const git = { mergeChangeRequest: mergeChangeRequestMock } as unknown as GitService;
+    return new ReviewWorkflowService(makeDb([]), { ...makeAccessControl({}), ...overrides }, workspace, git);
+  }
+
+  it('propagates AccessUnreadableError from the eligibility lookup', async () => {
+    const svc = serviceWith({
+      eligibleWritersForPathsAtRef: async () => {
+        throw new AccessUnreadableError('origin/current-company-state', 'Knowledge/access.md');
+      },
+    });
+    await expect(
+      svc.getApprovalStates(1, FILES, 'head-sha-1', 'current-company-state', null, 'ws-base', 'alice@bevel.software'),
+    ).rejects.toBeInstanceOf(AccessUnreadableError);
+  });
+
+  it('propagates AccessUnreadableError from the viewer batch too', async () => {
+    const svc = serviceWith({
+      canWriteBatchAtRef: async () => {
+        throw new AccessUnreadableError('origin/current-company-state', 'Knowledge/access.md');
+      },
+    });
+    await expect(
+      svc.getApprovalStates(1, FILES, 'head-sha-1', 'current-company-state', null, 'ws-base', 'alice@bevel.software'),
+    ).rejects.toBeInstanceOf(AccessUnreadableError);
+  });
+
+  it('still degrades any other lookup failure to empty eligibility', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    try {
+      const svc = serviceWith({
+        eligibleWritersForPathsAtRef: async () => {
+          throw new Error('origin not fetched yet');
+        },
+      });
+      const states = await svc.getApprovalStates(1, FILES, 'head-sha-1', 'current-company-state', null, 'ws-base');
+      expect(states).toHaveLength(1);
+      expect(states[0].eligibleApprovers).toEqual({ roles: [], users: [] });
+      expect(states[0].isApproved).toBe(false);
+      expect(warn).toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});

package/src/modules/workflow/review-workflow/review-workflow.service.ts

@@ -12,6 +12,7 @@ import type {
 } from '@bevel-software/platform-shared';
 import type { Database } from '../../database/connection.js';
 import { changeRequests, prComments, prFileApprovals, prMergeLog } from '../../database/schema.js';
+import { AccessUnreadableError } from '../../access-model/access-errors.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import { isAccessMdPath } from '../../access-model/access-grammar.js';
 import type { GitService } from '../git/git.service.js';
@@ -374,6 +375,9 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
         );
         if (resolved) eligibilityByPath = resolved;
       } catch (err) {
+        // An unreadable tree is not "no eligible writers": that answer would
+        // drop every file out of the merge gate. Fail closed instead.
+        if (err instanceof AccessUnreadableError) throw err;
         console.warn(
           `[review-workflow] eligibleWritersForPathsAtRef failed for PR #${prNumber} (base=${baseBranch}):`,
           err,
@@ -390,6 +394,7 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
           );
           if (batch) viewerCanApproveByPath = batch;
         } catch (err) {
+          if (err instanceof AccessUnreadableError) throw err;
           console.warn(
             `[review-workflow] canWriteBatchAtRef failed for PR #${prNumber} viewer=${viewerEmail}:`,
             err,

package/src/modules/workflow/workflow.routes.ts

@@ -764,6 +764,10 @@ export function createWorkflowRoutes(
         fresh: true,
         workspaceId: workspace.id,
         viewerEmail: user.email,
+        // Internal read: this route pins its work on the detail and never
+        // reads a patch; skipping them is one git subprocess per file saved
+        // on every click, and the result stays out of the client cache.
+        patches: false,
       });
       if (!detail) {
         res.status(404).json({ error: 'change request not found' });
@@ -805,6 +809,10 @@ export function createWorkflowRoutes(
         fresh: true,
         workspaceId: workspace.id,
         viewerEmail: user.email,
+        // Internal read: this route pins its work on the detail and never
+        // reads a patch; skipping them is one git subprocess per file saved
+        // on every click, and the result stays out of the client cache.
+        patches: false,
       });
       if (!detail) {
         res.status(404).json({ error: 'change request not found' });
@@ -841,6 +849,10 @@ export function createWorkflowRoutes(
         fresh: true,
         workspaceId: workspace.id,
         viewerEmail: user.email,
+        // Internal read: this route pins its work on the detail and never
+        // reads a patch; skipping them is one git subprocess per file saved
+        // on every click, and the result stays out of the client cache.
+        patches: false,
       });
       if (!detail) {
         res.status(404).json({ error: 'change request not found' });

package/src/modules/workflow/workflow.service.ts

@@ -1241,7 +1241,7 @@ export class WorkflowService implements IWorkflowService {
 
   getChangeRequestDetail(
     number: number,
-    opts?: { fresh?: boolean; workspaceId?: string; viewerEmail?: string },
+    opts?: { fresh?: boolean; workspaceId?: string; viewerEmail?: string; patches?: boolean },
   ): Promise<ChangeRequestDetail | null> {
     return this.prs.getPrDetail(number, opts);
   }
@@ -1896,6 +1896,10 @@ export class WorkflowService implements IWorkflowService {
         fresh: true,
         workspaceId,
         viewerEmail: user.email,
+        // Only `files[].path` is read below; a patch per file would be one
+        // git subprocess each, generated for nothing, on every reject by a
+        // non-author.
+        patches: false,
       });
       const paths = detail?.files.map((f) => f.path) ?? [];
       if (paths.length > 0) {

package/src/modules/workspace/__tests__/workspace.tools.test.ts

@@ -1065,3 +1065,48 @@ describe('branch is a required parameter in the tool contract', () => {
     }
   });
 });
+
+/**
+ * The tools are rooted at the WORKSPACE dir, one level above the git clone, so
+ * a path has to start with the clone folder to reach git at all. Every place an
+ * agent reads before choosing a path says so, in the `path` input itself rather
+ * than only in prose it may not read: the root listing (where the folder is
+ * discoverable) and each content-writing tool.
+ */
+describe('path inputs tell the agent about the repository folder', () => {
+  // `toolDef` wraps a tool's inputs under a single `body` property.
+  const inputDescription = (def: { inputs?: unknown } | undefined, ...keys: string[]): string => {
+    let node = (def?.inputs ?? {}) as Record<string, unknown>;
+    for (const key of ['body', ...keys]) {
+      node = ((node.properties as Record<string, unknown> | undefined)?.[key] ?? {}) as Record<string, unknown>;
+      if (key === 'files') node = (node.items ?? {}) as Record<string, unknown>;
+    }
+    return typeof node.description === 'string' ? node.description : '';
+  };
+
+  it('every content-writing tool says paths start with `knowledge-base/`, so a repo-relative path is never guessed', async () => {
+    await start();
+    const tools = await toolRegistry.listInternal();
+    const byName = (name: string) => {
+      const def = tools.find((t) => t.name === name);
+      expect(def, name).toBeDefined();
+      return def;
+    };
+    for (const name of ['write_file', 'edit_file', 'mkdir', 'delete_file', 'unzip']) {
+      expect(inputDescription(byName(name), 'path'), name).toContain(`\`${KB_DIR}/\``);
+    }
+    expect(inputDescription(byName('write_files'), 'files', 'path'), 'write_files').toContain(`\`${KB_DIR}/\``);
+    for (const name of ['move_file', 'copy_file']) {
+      expect(inputDescription(byName(name), 'dest'), name).toContain(`\`${KB_DIR}/\``);
+    }
+  });
+
+  it('the root listing names the clone folder, so an agent that lists first learns the prefix', async () => {
+    await start();
+    const tools = await toolRegistry.listInternal();
+    const list = tools.find((t) => t.name === 'list_files');
+    expect(list).toBeDefined();
+    expect(list!.description).toContain(`\`${KB_DIR}/\``);
+    expect(inputDescription(list, 'path')).toContain(`\`${KB_DIR}/\``);
+  });
+});

package/src/modules/workspace/workspace.tools.ts

@@ -20,6 +20,7 @@ import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 // Leaf-level shared primitive (same exception `workspace.service.ts` already
 // relies on) — not a workflow service, so this stays inside the module boundary.
 import { assertValidBranchName } from '../kb-fs/branch-name.js';
+import { assertInsideRepo } from '../kb-fs/repo-path.js';
 import type { ISessionSink } from './session-sink.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { toKbRelative, resolveReadableMap } from '../access-model/kb-read-filter.js';
@@ -111,6 +112,22 @@ const int = (description: string): JsonSchema => ({ type: 'integer', description
 
 const str = (description: string): JsonSchema => ({ type: 'string', description });
 
+/**
+ * A path input that names the clone folder. The tools are rooted at the
+ * WORKSPACE dir, one level above the git clone, so a path only reaches git
+ * when it starts with that folder; an agent that reads `KnowledgeBase/Foo.md`
+ * in a URL or a doc and passes it verbatim would otherwise write beside the
+ * repository. Saying so in the input itself, not only in prose, is what the
+ * agent actually sees when it fills the argument. `refused` is false for the
+ * inputs that may legitimately name a stray (a source to rescue, a file to
+ * remove).
+ */
+const wsPath = (kbDirName: string, what: string, refused = true): JsonSchema =>
+  str(
+    `${what}: starts with \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`).` +
+      (refused ? ' A path without that prefix is outside the repository and is refused.' : ''),
+  );
+
 function asText(content: string | Buffer): string {
   return typeof content === 'string' ? content : content.toString('utf8');
 }
@@ -394,7 +411,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative path, or a `__tool_chain_spill__/…` ref from a truncated `call_tool_chain`.'),
+        path: str(`Path to read, starting with \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`), or a \`__tool_chain_spill__/…\` ref from a truncated \`call_tool_chain\`.`),
         offset: int('Start character index (default 0).'),
         limit: int('Max characters to return from `offset`.'),
         sessionId: SESSION_ID_INPUT,
@@ -453,13 +470,13 @@ export function registerWorkspaceTools(
   mount({
     name: 'list_files',
     description:
-      'List a directory. Returns `{ path, entries: [{ name, type, size? }] }`. Omit `path` for the workspace root.' +
+      `List a directory. Returns \`{ path, entries: [{ name, type, size? }] }\`. Omit \`path\` for the workspace root, which holds the repository as the \`${kbDirName}/\` folder: every content path starts with it (e.g. \`${kbDirName}/KnowledgeBase\`).` +
       ONTOLOGY_BOUNDARY_NOTE,
     inputs: {
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative directory (default: root).'),
+        path: str(`Directory to list, starting with \`${kbDirName}/\` (default: the workspace root, where the repository is the \`${kbDirName}/\` folder).`),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch'],
@@ -501,7 +518,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative path.'),
+        path: wsPath(kbDirName, 'Path'),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'path'],
@@ -610,7 +627,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative path.'),
+        path: wsPath(kbDirName, 'Path'),
         content: str('Full file content.'),
         sessionId: SESSION_ID_INPUT,
       },
@@ -657,7 +674,7 @@ export function registerWorkspaceTools(
           description: 'Files to write; each created or overwritten.',
           items: {
             type: 'object',
-            properties: { path: str('Workspace-relative path.'), content: str('Full file content.') },
+            properties: { path: wsPath(kbDirName, 'Path'), content: str('Full file content.') },
             required: ['path', 'content'],
             additionalProperties: false,
           },
@@ -705,7 +722,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative path.'),
+        path: wsPath(kbDirName, 'Path'),
         old_string: str('Exact text to replace (include enough context to be unique).'),
         new_string: str('Replacement text.'),
         replace_all: { type: 'boolean', description: 'Replace every occurrence instead of requiring a unique match.' },
@@ -750,7 +767,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative path.'),
+        path: wsPath(kbDirName, 'Path to the file', false),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'path'],
@@ -781,7 +798,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative directory.'),
+        path: wsPath(kbDirName, 'Directory to create'),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'path'],
@@ -808,8 +825,8 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        src: str('Source path.'),
-        dest: str('Destination path.'),
+        src: wsPath(kbDirName, 'Source path', false),
+        dest: wsPath(kbDirName, 'Destination path'),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'src', 'dest'],
@@ -842,8 +859,8 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        src: str('Source path.'),
-        dest: str('Destination path.'),
+        src: wsPath(kbDirName, 'Source path', false),
+        dest: wsPath(kbDirName, 'Destination path'),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'src', 'dest'],
@@ -877,8 +894,8 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative .zip path.'),
-        destination: str("Directory to extract into (default: the zip's parent)."),
+        path: wsPath(kbDirName, 'Path to the .zip archive', false),
+        destination: wsPath(kbDirName, "Directory to extract into (default: the zip's parent)"),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'path'],
@@ -916,6 +933,9 @@ export function registerWorkspaceTools(
         // extension policy applies per entry too, so a restricted run can't unzip a
         // `.md` into the graph.
         (wsRelPath) => {
+          // An entry that would land beside the repository is skipped with the
+          // corrected-path reason, like any other refused entry.
+          assertInsideRepo(wsRelPath, kbDirName);
           writePolicy.assertPathWritable(ctx.sessionId, wsRelPath);
           return assertOntologyWriteAllowed(sessionOntologyGate, ctx, wsRelPath);
         },