@bevel-software/platform-core-backend 0.29.0 → 0.31.0

package/src/modules/workflow/read-on-branch.ts

@@ -0,0 +1,79 @@
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+
+/**
+ * Which of `paths` `userEmail` may read at `origin/<base>`, as a membership
+ * set — ONE rule for the change-request reads (their file lists, judged at
+ * the request's base) and for `branch_status` (the paths a request would
+ * carry). A null answer (the ref, or its `roles.yaml`, does not resolve)
+ * withholds everything, which is the same reading the app's fork-point
+ * route gives it.
+ */
+export async function readablePathsAt(
+  accessControl: Pick<IAccessControl, 'canReadBatchAtRef'>,
+  workspaceId: string,
+  userEmail: string,
+  base: string,
+  paths: string[],
+): Promise<Set<string>> {
+  if (paths.length === 0) return new Set();
+  const verdicts = await accessControl.canReadBatchAtRef(workspaceId, `origin/${base}`, userEmail, [...new Set(paths)]);
+  if (!verdicts) return new Set();
+  return new Set([...verdicts].filter(([, allowed]) => allowed).map(([p]) => p));
+}
+
+/**
+ * Whether `userEmail` may read `repoRelativePath` at EVERY one of `commits`
+ * — ONE rule for content served from another branch, for the app's compare
+ * route and the agent's history tools alike: the commits the service read
+ * the content at, pinned by the service inside its reservation (a diff's two
+ * sides, a file at a branch's published tip, the two commits a merge is of),
+ * so the verdict is about the bytes actually served, never about a branch
+ * ref a fetch may have moved between the verdict and the read. A commit
+ * whose rules cannot be read (null) grants nothing. An access-model FAILURE
+ * is not a null: it propagates with its own status (an unreadable access
+ * tree is the documented 503 a client retries).
+ */
+export async function readableAtCommits(
+  accessControl: Pick<IAccessControl, 'canReadAtRef'>,
+  workspaceId: string,
+  userEmail: string,
+  repoRelativePath: string,
+  commits: readonly string[],
+): Promise<boolean> {
+  for (const sha of commits) {
+    if ((await accessControl.canReadAtRef(workspaceId, sha, userEmail, repoRelativePath)) !== true) return false;
+  }
+  return true;
+}
+
+/** The refusal `readableAtCommits` answers false with, as every caller words it: the branch named, never the commit. */
+export class ReadOnBranchDeniedError extends WorkflowDomainError {
+  constructor(displayPath: string, branch: string) {
+    super(`You don't have permission to read "${displayPath}" on "${branch}".`, 403, {
+      kind: 'read-denied',
+      path: displayPath,
+      branch,
+    });
+    this.name = 'ReadOnBranchDeniedError';
+  }
+}
+
+/**
+ * `readableAtCommits` at every commit `branch` resolves to (the one its
+ * content was served from, and any other its local head or published tip
+ * names), thrown when it answers false.
+ */
+export async function assertReadableAtCommits(
+  accessControl: Pick<IAccessControl, 'canReadAtRef'>,
+  workspaceId: string,
+  userEmail: string,
+  repoRelativePath: string,
+  commits: readonly string[],
+  branch: string,
+  displayPath: string = repoRelativePath,
+): Promise<void> {
+  if (!(await readableAtCommits(accessControl, workspaceId, userEmail, repoRelativePath, commits))) {
+    throw new ReadOnBranchDeniedError(displayPath, branch);
+  }
+}

package/src/modules/workflow/workflow-hooks.ts

@@ -65,7 +65,7 @@ export interface AgentOperationContext {
   sessionId?: string;
   /**
    * The workspace-relative path the operation targets. Absent for a
-   * write-capable operation with no resolvable target (`execute_command`).
+   * write-capable operation with no resolvable target.
    */
   wsPath?: string;
   /** The branch (draft) whose workspace the operation acts on. */

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

@@ -38,6 +38,7 @@ import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { WorkflowEventBus } from './event-bus.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { assertReadableAtCommits } from './read-on-branch.js';
 import { assertValidRelativePath } from '../kb-fs/branch-name.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
@@ -413,46 +414,27 @@ export function createWorkflowRoutes(
     // The other history endpoints serve commits of the URL workspace's own
     // branch, so its working-tree verdict covers what they return. This one
     // serves content of TWO caller-named branches — the verdict must come
-    // from the refs actually being served, or a caller could pick a
-    // workspace whose tree grants what the compared branches' trees deny.
-    //
-    // The comparison prefers a LOCAL ref (and the working tree for the
-    // checked-out branch) over `origin/<branch>`, so both candidate refs are
-    // authorized: every ref that RESOLVES must grant the read, and a branch
-    // none of whose refs resolve is denied — never serve a ref that cannot
-    // be authorized. (The working-tree side is additionally covered by the
-    // workspace `canRead` above.)
-    {
-      const user = await requireUser(req, res);
-      if (!user) return;
-      const repoRelative = toKbRelative(pathParam, kbDirName)!;
-      for (const branch of [fromBranch, toBranch]) {
-        const verdicts: (boolean | null)[] = [];
-        for (const ref of [`origin/${branch}`, branch]) {
-          try {
-            verdicts.push(await accessControl.canReadAtRef(req.params.id, ref, user.email, repoRelative));
-          } catch (err) {
-            // An access-model FAILURE is not an unresolvable ref: mapped to
-            // null it would let the other candidate's grant serve a ref
-            // whose authorization errored. Fail closed — but keep the
-            // error's own status: an unreadable access tree is the
-            // documented 503 a client retries, not a permanent 403 denial.
-            const { status, body } = toHttpError(err);
-            res.status(status).json(body);
-            return;
-          }
-        }
-        const denied = verdicts.some((v) => v === false);
-        const unresolvable = verdicts.every((v) => v === null);
-        if (denied || unresolvable) {
-          res.status(403).json({ error: `You don't have permission to read "${pathParam}" on "${branch}".` });
-          return;
-        }
-      }
-    }
+    // from the commits actually served (`readableAtCommits`, the one rule
+    // this route and the agent's history tools share): the service pins the
+    // commit each side is read at and asks this verdict inside its
+    // reservation, before anything is said about the path at either, with
+    // every commit the branch resolves to — its local head and its published
+    // tip, all of which must grant, as this route has always required of
+    // both refs — never at a branch ref a fetch may move between a verdict
+    // and a read. (The
+    // working-tree side is additionally covered by the workspace `canRead`
+    // above.) An access-model failure keeps its own status: an unreadable
+    // access tree is the documented 503 a client retries, not a permanent
+    // 403 denial.
+    const user = await requireUser(req, res);
+    if (!user) return;
+    const repoRelative = toKbRelative(pathParam, kbDirName)!;
     try {
-      const diff = await workflow.compareFile(req.params.id, pathParam, fromBranch, toBranch);
-      res.json({ diff });
+      const compared = await workflow.compareFile(req.params.id, pathParam, fromBranch, toBranch, async (sides) => {
+        await assertReadableAtCommits(accessControl, req.params.id, user.email, repoRelative, sides.from, fromBranch, pathParam);
+        await assertReadableAtCommits(accessControl, req.params.id, user.email, repoRelative, sides.to, toBranch, pathParam);
+      });
+      res.json({ diff: compared.diff });
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);

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

@@ -58,9 +58,11 @@ import type {
   IWorkflowService,
   MergeBranchOutcome,
   MergeChangeRequestOutcome,
+  MergeResolution,
   OpenChangeRequestInput,
   PostChangeRequestCommentInput,
   RemoteSyncPullResult,
+  UpdateBranchOutcome,
 } from '@bevel-software/platform-shared';
 import {
   isFolderPlaceholder,
@@ -68,6 +70,7 @@ import {
   isPlatformRestoreShape,
 } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
+import { readableAtCommits, ReadOnBranchDeniedError } from './read-on-branch.js';
 import { and, desc, eq, inArray, isNotNull, isNull, lt, ne, or, sql } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { changeRequests } from '../database/schema.js';
@@ -421,22 +424,29 @@ export class WorkflowService implements IWorkflowService {
    * opposite directions (`A -> B` and `B -> A`), and nothing is ever held
    * while waiting for the other key.
    *
-   * A PROTECTED target's key is NOT reserved. No path in the system can
-   * delete a protected branch (`git.deleteBranch` throws
+   * A PROTECTED branch's key is NOT reserved, at either end. No path in the
+   * system can delete a protected branch (`git.deleteBranch` throws
    * `ProtectedBranchError` before any lock, `retireMergedSourceBranch`
    * returns early on one), so the key would exclude nothing. It would only
-   * cost: nearly every request targets the protected default branch, so one
-   * shared key there would serialize every open on the hottest path for the
-   * duration of a fetch + merge + push + diff. The source needs no such
-   * carve-out; `openChangeRequest` refuses protected sources before locking.
+   * cost: nearly every request targets the protected default branch, and
+   * every draft refreshes FROM it (`updateBranch`, the merge tool's sync),
+   * so one shared key there would serialize every open on the hottest path for the
+   * duration of a fetch + merge + push + diff. A protected SOURCE takes no
+   * key for the same reason: `openChangeRequest` refuses protected sources
+   * before locking, and a draft refreshing from the default branch is
+   * exactly a protected source.
    */
   private runOnBranchPair<T>(
     source: string,
     target: string,
     fn: () => Promise<T>,
   ): Promise<T> {
-    const keys = [`branch:${source}`];
-    if (!this.kb.isProtectedBranch(target)) keys.push(`branch:${target}`);
+    // A PROTECTED branch's key is not reserved at EITHER end (see above):
+    // nothing can delete one, so the key would exclude nothing and only
+    // serialize every draft that refreshes from the default branch behind
+    // every other. The same branch at both ends (a draft syncing its own
+    // shared state) takes its one key.
+    const keys = [...new Set([source, target].filter((b) => !this.kb.isProtectedBranch(b)).map((b) => `branch:${b}`))];
     return this.branchLifecycle.runAll(keys, fn);
   }
 
@@ -968,7 +978,17 @@ export class WorkflowService implements IWorkflowService {
     workspaceId: string,
     opts: { preserveMerges?: boolean } = {},
   ): Promise<boolean> {
-    const { treeChanged } = await this.git.pull(workspaceId, opts);
+    return this.pullWorkspaceVia(() => this.git.pull(workspaceId, opts), workspaceId);
+  }
+
+  /**
+   * `pullWorkspace` over the pull it is given: the workspace's own
+   * (`git.pull`, which takes the workspace's reservation) or one a caller
+   * already holding that reservation hands in (a merge's publish). The
+   * announcement is the same either way.
+   */
+  private async pullWorkspaceVia(pull: () => Promise<{ treeChanged: boolean }>, workspaceId: string): Promise<boolean> {
+    const { treeChanged } = await pull();
     const defaultBranch = this.kb.defaultBranch;
     if (treeChanged && branchForWorkspaceId(workspaceId) === defaultBranch) {
       this.events?.emit({ kind: 'fs-tree-changed', workspaceId, branch: defaultBranch });
@@ -1259,8 +1279,9 @@ export class WorkflowService implements IWorkflowService {
     path: string,
     fromBranch: string,
     toBranch: string,
-  ): Promise<string> {
-    return this.git.diffFileBetweenBranches(workspaceId, path, fromBranch, toBranch);
+    authorize: (sides: { from: string[]; to: string[] }) => Promise<void>,
+  ): Promise<{ diff: string; from: string; to: string }> {
+    return this.git.diffFileBetweenBranches(workspaceId, path, fromBranch, toBranch, authorize);
   }
 
   fileAtForkPoint(
@@ -1893,8 +1914,33 @@ export class WorkflowService implements IWorkflowService {
   ): Promise<void> {
     // No explicit `undefined` third argument when there are no options: the
     // call shape stays the bare `push(workspaceId, user)` every caller made.
-    const push = () =>
-      opts ? this.git.push(workspaceId, user, opts) : this.git.push(workspaceId, user);
+    return this.pushWithRecoveryVia(
+      {
+        push: () => (opts ? this.git.push(workspaceId, user, opts) : this.git.push(workspaceId, user)),
+        pull: () => this.pullWorkspace(workspaceId, { preserveMerges: true }),
+      },
+      workspaceId,
+      branch,
+      targetPath,
+      user,
+    );
+  }
+
+  /**
+   * `pushWithRecovery`'s policy over the two moves it is made of — the push,
+   * and the pull-rebase that keeps a stranded merge a merge — so that a
+   * caller already holding the workspace's reservation (a merge publishing
+   * itself, `updateBranch`) runs the SAME policy over its own unlocked moves,
+   * and a push the host refuses answers one way there too.
+   */
+  private async pushWithRecoveryVia(
+    ops: { push: () => Promise<void>; pull: () => Promise<unknown> },
+    workspaceId: string,
+    branch: string,
+    targetPath: string,
+    user: AuthUser,
+  ): Promise<void> {
+    const push = ops.push;
     try {
       await push();
       this.noteGitSyncOk(workspaceId, branch);
@@ -1915,7 +1961,7 @@ export class WorkflowService implements IWorkflowService {
           // with whatever push of the branch comes next — a save, a share —
           // and a plain rebase would flatten it into cherry-picks. With no
           // merge among the local commits the two spellings replay the same.
-          await this.pullWorkspace(workspaceId, { preserveMerges: true });
+          await ops.pull();
           try {
             await push();
           } catch (retryErr) {
@@ -4182,8 +4228,8 @@ export class WorkflowService implements IWorkflowService {
     // while they are held: a bare read would let a person open the request
     // mid-merge and the agent would land its content anyway, which is the one
     // thing this tool exists to prevent. `runOnBranchPair` drops a protected
-    // target's key; the source key is held either way, and every competing
-    // request from this source takes it too.
+    // branch's key at either end; a draft source's key is held, and every
+    // competing request from this source takes it too.
     return this.runOnBranchPair(sourceBranch, targetBranch, async () => {
       // A person merges a change request. Only the request's OWN direction is
       // blocked: the target merged into the source is how a draft under review
@@ -4681,4 +4727,145 @@ export class WorkflowService implements IWorkflowService {
     return formatAffectedOwnersBlock(paths, resolved);
   }
 
+  async updateBranch(
+    workspaceId: string,
+    user: AuthUser,
+    opts: { from?: string } & (
+      | { resolutions?: undefined; validateWrite?: undefined }
+      | { resolutions: MergeResolution[]; validateWrite: (wsPath: string, content: string) => void | Promise<void> }
+    ) = {},
+  ): Promise<UpdateBranchOutcome> {
+    const branch = branchForWorkspaceId(workspaceId);
+    const from = opts.from ?? branch;
+    // A resolution writes on the draft: it is somebody's to gate, and a
+    // caller that brings none gates nothing (closed) — the type says so for
+    // a compiled caller, this for any other.
+    if ((opts.resolutions?.length ?? 0) > 0 && typeof opts.validateWrite !== 'function') {
+      throw new Error('updateBranch: resolutions need a `validateWrite` to be asked before the merge');
+    }
+    if (this.kb.isProtectedBranch(branch)) {
+      throw new WorkflowDomainError(
+        `"${branch}" is protected: it is changed through change requests, never merged into directly.`,
+        403,
+        { kind: 'protected-update-target', branch },
+      );
+    }
+    // The one merge a person makes: a change request's. An update that would
+    // land an OPEN request from `from` into this draft is that merge by
+    // another name, and `mergeBranch`'s gate refuses it here too — asked once
+    // before waiting, and again under the locks below, where the answer
+    // counts. (The other direction, the request's target into its source, is
+    // how a draft under review stays current, and is never blocked.)
+    if (from !== branch) {
+      const openBefore = await this.openRequestBlockingMerge(from, branch);
+      if (openBefore !== null) throw new OpenChangeRequestBlocksMergeError(from, branch, openBefore);
+    }
+    // The merge takes what the REMOTE holds of `from`, and the push publishes
+    // the branch: writes still being committed on either would be missed by
+    // the first or swept up by the second. Waited for, as `mergeBranch` waits
+    // — outside the lifecycle locks, which must not be held for seconds of
+    // waiting on a queue.
+    for (const b of from === branch ? [branch] : [from, branch]) {
+      const settled = await this.awaitPendingCommits(b);
+      if (!settled.ok) {
+        const message = settled.needsAttention
+          ? `A commit queued on "${b}" failed and needs a person: ${settled.needsAttention} ` +
+            'Nothing was merged. Tell the user; update again once it has been resolved.'
+          : `${settled.pending} write(s) on "${b}" are still being committed. Nothing was merged. Retry shortly.`;
+        return {
+          kind: 'pending-commits',
+          branch: b,
+          pending: settled.pending,
+          ...(settled.needsAttention ? { needsAttention: settled.needsAttention } : {}),
+          message,
+        };
+      }
+    }
+    // Under the lifecycle lock of both branches, as `mergeBranch` and
+    // `openChangeRequest` run: the "no open request" answer is only sound
+    // while nobody can open one mid-merge, and a branch being merged into is
+    // not one to delete or recreate meanwhile. A protected `from` takes no
+    // key, and the branch's own shared state (from = branch) takes the one.
+    return this.runOnBranchPair(from, branch, async () => {
+      if (from !== branch) {
+        const open = await this.openRequestBlockingMerge(from, branch);
+        if (open !== null) throw new OpenChangeRequestBlocksMergeError(from, branch, open);
+      }
+      if (!(await this.git.remoteBranchExists(workspaceId, from))) {
+        throw new WorkflowValidationError(`No branch named "${from}" on the shared repository.`);
+      }
+      const resolutions = opts.resolutions ?? [];
+      const subject = from === branch ? `Merge the shared ${branch} into the local one` : `Merge ${from} into ${branch}`;
+      const body =
+        (from === branch
+          ? `The branch had moved on the shared repository while this workspace held commits of its own; both are kept.`
+          : `Brings the latest ${from} into ${branch}.`) +
+        (resolutions.length > 0
+          ? ` Conflicts resolved by ${user.name} <${user.email}> in: ${resolutions.map((r) => r.path).join(', ')}.`
+          : '');
+      // Published inside the merge's own reservation: nothing lands between
+      // the merge commit and its push, and the push is EVERY workflow push's
+      // `pushWithRecovery`, run over the merge's own unlocked moves — a
+      // rejection replays the merge (kept as a merge) onto the moved branch
+      // and pushes again; a replay that conflicts or a host that refuses
+      // answers as every refused share answers, the banner noted and the
+      // typed hand-off thrown, naming the branch (no single file is at issue)
+      // and never a conflicted path. The merge commit stays local for the
+      // next push of the branch to carry.
+      return this.git.mergeIntoBranch(workspaceId, branch, from, user, {
+        subject,
+        body,
+        resolutions,
+        publish: (ops) =>
+          this.pushWithRecoveryVia(
+            { push: ops.push, pull: () => this.pullWorkspaceVia(ops.pullRebase, workspaceId) },
+            workspaceId,
+            branch,
+            branch,
+            user,
+          ),
+        // A resolution writes a file on the draft from what both branches
+        // hold of it. It is authorized inside the merge's reservation, after
+        // the fetch and before the merge touches the checkout — the draft's
+        // tree clean at its own commit, so the rules read from it are the
+        // draft's, never a rule file mid-merge: the caller must read the
+        // file at the draft's commit and at the source commit the merge is
+        // of, and may change it on the draft by the one rule every draft
+        // write takes — the change gate `acquireLock` asks, not a write
+        // permission a draft never requires.
+        authorizeResolutions: async ({ ours, theirs }) => {
+          for (const r of resolutions) {
+            const rel = r.path.startsWith(`${this.kbDirName}/`) ? r.path.slice(this.kbDirName.length + 1) : r.path;
+            // At the two COMMITS the merge is of — pinned by the merge itself,
+            // never at a ref a concurrent fetch can move between this verdict
+            // and the merge — by the one rule the tool shows a conflict by.
+            if (!(await readableAtCommits(this.accessControl, workspaceId, user.email, rel, [ours, theirs]))) {
+              throw new ReadOnBranchDeniedError(rel, from);
+            }
+            // The gate takes the WORKSPACE path, as `acquireLock` hands it
+            // one: a repository-relative path reads as outside the knowledge
+            // base there, which the gate waves through.
+            await this.changeGate.assertMayChange(workspaceId, user.email, `${this.kbDirName}/${rel}`, 'file');
+            // Content the resolution brings takes the caller's pre-disk write
+            // gate, as its file writes do before a byte lands; a side kept
+            // whole is a commit's own bytes and brings none.
+            if (r.content !== undefined && opts.validateWrite) await opts.validateWrite(`${this.kbDirName}/${rel}`, r.content);
+          }
+        },
+      });
+    });
+  }
+
+  fileAtBranch(
+    workspaceId: string,
+    path: string,
+    branch: string,
+    authorize: (commits: string[]) => Promise<void>,
+  ): Promise<{ sha: string; ref: string; content: string | null }> {
+    return this.git.readFileAtBranch(workspaceId, path, branch, authorize);
+  }
+
+  changedPathsBetweenBranches(workspaceId: string, base: string, branch: string): Promise<string[]> {
+    return this.git.changedPathsForPr(workspaceId, base, branch);
+  }
 }

package/src/modules/workspace/__tests__/agent-downloads.test.ts

@@ -22,7 +22,6 @@ import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../agent-access.gate.js';
 import { SpillStore } from '../spill-store.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
-import { WorkspaceService } from '../workspace.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { AgentDownloadStore, DOWNLOAD_TOKEN_REFUSAL } from '../agent-download.store.js';
 import { attachmentDisposition, createAgentDownloadRoutes, createDownloadFetcherIdentifier } from '../agent-download.routes.js';
@@ -31,6 +30,7 @@ import jwt from 'jsonwebtoken';
 import { buildDownload, DOWNLOAD_PERMISSION_REQUIRED, NOT_FOUND } from '../agent-download.builder.js';
 import { READ_ONLY_CODE, type IWriteAccess } from '../../write-access/write-access.js';
 import { sharedFileRules } from '../../agent-instructions/shared-file-rules.js';
+import { newWorkspaceService } from '../../../__tests__/workspace-service.js';
 
 /**
  * `request_file_download` end to end, over the REAL access resolver on a
@@ -136,7 +136,7 @@ async function start(options: StartOptions = {}): Promise<Started> {
     await mkdir(dirname(abs), { recursive: true });
     await writeFile(abs, contents);
   }
-  const workspaceService = new WorkspaceService(
+  const workspaceService = newWorkspaceService(
     root,
     'https://example.invalid/kb.git',
     testKbContext({ kbDirName: KB }),