@bevel-software/platform-core-backend 0.35.0 → 0.37.0

package/src/modules/{workflow/workflow.routes.ts → version-control/version-control.routes.ts}

@@ -6,13 +6,14 @@
  * URL layout:
  *   /workspace/:id/workflow/...     — workspace-scoped ops (branches, changes, locks, compare)
  *   /workflow/change-requests/...   — change-request ops (list/detail/edit/approvals/merge/reject)
+ * The `/workflow/` prefix is kept for API compatibility until a core major.
  *
  * Workspace ids are `encodeURIComponent(branch)` (PLAN §3) — branches are
  * shared by every user editing them, so route handlers gate on
  * authentication only. Coordination of concurrent edits happens via the
  * file-lock service, not via per-user clones.
  *
- * Error mapping: every workflow error class extends `WorkflowDomainError`
+ * Error mapping: every version-control error class extends `VersionControlDomainError`
  * which exposes `.status` + optional `.payload`, so a single `toHttpError`
  * covers all branches/changes/CR errors uniformly.
  */
@@ -27,7 +28,7 @@ import type {
   ChangeInput,
   ChangeRequest,
   ChangeRequestApplyFailureKind,
-  IWorkflowService,
+  IVersionControlService,
   OpenChangeRequestInput,
 } from '@bevel-software/platform-shared';
 import type { AuthService } from '../auth/index.js';
@@ -35,8 +36,8 @@ import type { IAccessControl } from '../access/index.js';
 import { canReadWorkspacePath, toKbRelative } from '../access-model/index.js';
 import type { WorkspaceService } from '../workspace/index.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
-import type { WorkflowEventBus } from './event-bus.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { VersionControlEventBus } from './event-bus.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { assertReadableAtCommits } from './read-on-branch.js';
 import { assertValidRelativePath } from '../kb-fs/index.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
@@ -46,7 +47,7 @@ import '../auth/index.js'; // Express Request augmentation
 function toHttpError(
   err: unknown,
 ): { status: number; body: Record<string, unknown> } {
-  if (err instanceof WorkflowDomainError) {
+  if (err instanceof VersionControlDomainError) {
     return { status: err.status, body: domainErrorBody(err) };
   }
   log.error('unhandled error:', { err });
@@ -71,11 +72,11 @@ function isTruthyQuery(v: unknown): boolean {
   return v === '1' || v === 'true';
 }
 
-export function createWorkflowRoutes(
-  workflow: IWorkflowService,
+export function createVersionControlRoutes(
+  versionControl: IVersionControlService,
   workspaceService: WorkspaceService,
   authService: AuthService,
-  events: WorkflowEventBus,
+  events: VersionControlEventBus,
   accessControl: IAccessControl,
   kbDirName: string,
 ): express.Router {
@@ -84,9 +85,9 @@ export function createWorkflowRoutes(
   /**
    * Authentication gate. Per PLAN §3, branches are shared workspaces —
    * any authenticated user can access any branch. Authorization for
-   * mutations happens at the workflow / git layer (access tree, file
+   * mutations happens at the version-control / git layer (access tree, file
    * locks, change-request approval gate). This helper just resolves the
-   * caller's `AuthUser` record; route bodies pass it to workflow methods
+   * caller's `AuthUser` record; route bodies pass it to version-control methods
    * for per-operation auth.
    */
   async function requireUser(
@@ -237,7 +238,7 @@ export function createWorkflowRoutes(
       // TTL) so a user-initiated refresh — e.g. opening the branch selector —
       // immediately reflects branches another workspace just created/deleted.
       const freshFetch = isTruthyQuery(req.query.fresh);
-      res.json(await workflow.listBranches(req.params.id, { freshFetch }));
+      res.json(await versionControl.listBranches(req.params.id, { freshFetch }));
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -252,7 +253,7 @@ export function createWorkflowRoutes(
       return;
     }
     try {
-      res.json(await workflow.createBranch(req.params.id, name, fromBase));
+      res.json(await versionControl.createBranch(req.params.id, name, fromBase));
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -264,7 +265,7 @@ export function createWorkflowRoutes(
     if (!user) return;
     const onlyIfNoRemote = isTruthyQuery(req.query.onlyIfNoRemote);
     try {
-      await workflow.deleteBranch(req.params.id, req.params.name, user, { onlyIfNoRemote });
+      await versionControl.deleteBranch(req.params.id, req.params.name, user, { onlyIfNoRemote });
       res.json({ status: 'deleted' });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -293,7 +294,7 @@ export function createWorkflowRoutes(
       // The call is idempotent and ~free in the warm case (Map lookup), so it
       // costs nothing once the workspace is already on disk.
       await workspaceService.getOrCreateForBranch(branchForWorkspaceId(req.params.id));
-      res.json(await workflow.branchStatus(req.params.id));
+      res.json(await versionControl.branchStatus(req.params.id));
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -307,7 +308,7 @@ export function createWorkflowRoutes(
     const user = await requireUser(req, res);
     if (!user) return;
     try {
-      await workflow.shareCurrentBranch(req.params.id, user);
+      await versionControl.shareCurrentBranch(req.params.id, user);
       res.json({ status: 'shared' });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -318,7 +319,7 @@ export function createWorkflowRoutes(
   router.post('/workspace/:id/workflow/refresh-remotes', async (req, res) => {
     if (!(await requireUser(req, res))) return;
     try {
-      await workflow.refreshRemotes(req.params.id);
+      await versionControl.refreshRemotes(req.params.id);
       res.json({ status: 'refreshed' });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -332,7 +333,7 @@ export function createWorkflowRoutes(
     const user = await requireUser(req, res);
     if (!user) return;
     try {
-      await workflow.updateFromRemote(req.params.id, user);
+      await versionControl.updateFromRemote(req.params.id, user);
       res.json({ status: 'updated' });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -348,7 +349,7 @@ export function createWorkflowRoutes(
       return;
     }
     try {
-      const base = await workflow.resolveForkBase(req.params.id, branch);
+      const base = await versionControl.resolveForkBase(req.params.id, branch);
       res.json({ base });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -359,7 +360,7 @@ export function createWorkflowRoutes(
   router.get('/workspace/:id/workflow/pending-changes', async (req, res) => {
     if (!(await requireUser(req, res))) return;
     try {
-      const paths = await workflow.listPendingChangePaths(req.params.id);
+      const paths = await versionControl.listPendingChangePaths(req.params.id);
       res.json({ paths });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -377,7 +378,7 @@ export function createWorkflowRoutes(
     if (!user) return;
     const input = req.body as ChangeInput;
     try {
-      res.json(await workflow.commitChange(req.params.id, user, input));
+      res.json(await versionControl.commitChange(req.params.id, user, input));
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -394,7 +395,7 @@ export function createWorkflowRoutes(
     const rawLimit = Number.parseInt(String(req.query.limit ?? '20'), 10);
     const limit = Number.isFinite(rawLimit) ? Math.max(1, Math.min(rawLimit, 100)) : 20;
     try {
-      res.json({ changes: await workflow.listChangesForFile(req.params.id, pathParam, limit) });
+      res.json({ changes: await versionControl.listChangesForFile(req.params.id, pathParam, limit) });
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -429,7 +430,7 @@ export function createWorkflowRoutes(
     if (!user) return;
     const repoRelative = toKbRelative(pathParam, kbDirName)!;
     try {
-      const compared = await workflow.compareFile(req.params.id, pathParam, fromBranch, toBranch, async (sides) => {
+      const compared = await versionControl.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);
       });
@@ -449,7 +450,7 @@ export function createWorkflowRoutes(
     }
     if (!(await requireReadPermission(req, res, req.params.id, pathParam))) return;
     try {
-      const diff = await workflow.showFileAtChange(req.params.id, pathParam, sha);
+      const diff = await versionControl.showFileAtChange(req.params.id, pathParam, sha);
       res.json({ diff });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -466,7 +467,7 @@ export function createWorkflowRoutes(
     }
     if (!(await requireReadPermission(req, res, req.params.id, pathParam))) return;
     try {
-      const { baseline, current } = await workflow.fileAtChange(req.params.id, pathParam, sha);
+      const { baseline, current } = await versionControl.fileAtChange(req.params.id, pathParam, sha);
       res.json({ baseline, current });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -476,10 +477,10 @@ export function createWorkflowRoutes(
 
   // ── File locks ────────────────────────────────────────────────────────────
 
-  // These routes hand the caller's spelling straight to the workflow service,
+  // These routes hand the caller's spelling straight to the version-control service,
   // which is where ONE file identity is decided (`canonicalFileIdentity`), so
   // `./x//a.md` and `x/a.md` are the same lock on every verb below. Refusals
-  // arrive here as `WorkflowDomainError`s carrying the status the file verbs
+  // arrive here as `VersionControlDomainError`s carrying the status the file verbs
   // answer for that same input, and `toHttpError` passes it through unchanged.
   // Nothing is canonicalised at this layer on purpose: a route-level fix would
   // leave any other caller of the service coordinating on its own identity.
@@ -495,7 +496,7 @@ export function createWorkflowRoutes(
       return;
     }
     try {
-      res.json(await workflow.acquireLock(req.params.id, branch, targetPath, user));
+      res.json(await versionControl.acquireLock(req.params.id, branch, targetPath, user));
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -519,7 +520,7 @@ export function createWorkflowRoutes(
       return;
     }
     try {
-      await workflow.releaseLock(req.params.id, branch, targetPath, user);
+      await versionControl.releaseLock(req.params.id, branch, targetPath, user);
       res.json({ queued: true });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -542,7 +543,7 @@ export function createWorkflowRoutes(
       return;
     }
     try {
-      const change = await workflow.commitFileWhileLocked(
+      const change = await versionControl.commitFileWhileLocked(
         req.params.id,
         branch,
         targetPath,
@@ -565,7 +566,7 @@ export function createWorkflowRoutes(
       return;
     }
     try {
-      res.json(await workflow.heartbeatLock(req.params.id, branch, targetPath, user));
+      res.json(await versionControl.heartbeatLock(req.params.id, branch, targetPath, user));
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -601,7 +602,7 @@ export function createWorkflowRoutes(
         res.status(403).json({ error: `You don't have permission to read "${targetPath}".` });
         return;
       }
-      res.json({ lock: await workflow.getLock(req.params.id, branch, targetPath) });
+      res.json({ lock: await versionControl.getLock(req.params.id, branch, targetPath) });
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -613,7 +614,7 @@ export function createWorkflowRoutes(
   router.get('/workflow/change-requests', async (req, res) => {
     const fresh = isTruthyQuery(req.query.fresh);
     try {
-      res.json(await scopeApplyFailures(req, await workflow.listChangeRequests({ fresh })));
+      res.json(await scopeApplyFailures(req, await versionControl.listChangeRequests({ fresh })));
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -628,7 +629,7 @@ export function createWorkflowRoutes(
     // the list changed, and a cached answer would hide their own change.
     const fresh = isTruthyQuery(req.query.fresh);
     try {
-      res.json(await scopeApplyFailures(req, await workflow.listChangeRequestsAuthoredBy(user.email, { fresh }), user));
+      res.json(await scopeApplyFailures(req, await versionControl.listChangeRequestsAuthoredBy(user.email, { fresh }), user));
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -642,7 +643,7 @@ export function createWorkflowRoutes(
     try {
       const workspace = await workspaceService.getOrCreateForUser(user);
       res.json(
-        await scopeApplyFailures(req, await workflow.listChangeRequestsForUser(workspace.id, user.email, { fresh }), user),
+        await scopeApplyFailures(req, await versionControl.listChangeRequestsForUser(workspace.id, user.email, { fresh }), user),
       );
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -689,7 +690,7 @@ export function createWorkflowRoutes(
     const user = await requireUser(req, res);
     if (!user) return;
     try {
-      res.json({ requests: await workflow.changeRequestsUnderFolder(folder, user) });
+      res.json({ requests: await versionControl.changeRequestsUnderFolder(folder, user) });
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -707,7 +708,7 @@ export function createWorkflowRoutes(
     const user = await requireUser(req, res);
     if (!user) return;
     try {
-      res.json({ results: await workflow.removeFolderFromChangeRequests(folder, user) });
+      res.json({ results: await versionControl.removeFolderFromChangeRequests(folder, user) });
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -721,7 +722,7 @@ export function createWorkflowRoutes(
       return;
     }
     try {
-      const cr = await workflow.getChangeRequest(num);
+      const cr = await versionControl.getChangeRequest(num);
       if (!cr) {
         res.status(404).json({ error: 'change request not found' });
         return;
@@ -760,7 +761,7 @@ export function createWorkflowRoutes(
           // blip when the caller's workspace isn't yet provisioned.
         }
       }
-      let detail = await workflow.getChangeRequestDetail(num, {
+      let detail = await versionControl.getChangeRequestDetail(num, {
         fresh,
         workspaceId,
         viewerEmail,
@@ -777,9 +778,9 @@ export function createWorkflowRoutes(
       if (detail.state === 'open' && detail.files.length === 0 && req.userId) {
         try {
           const user = await authService.getUserById(req.userId);
-          if (user && (await workflow.closeEmptyChangeRequest(num, user))) {
+          if (user && (await versionControl.closeEmptyChangeRequest(num, user))) {
             detail =
-              (await workflow.getChangeRequestDetail(num, {
+              (await versionControl.getChangeRequestDetail(num, {
                 fresh: true,
                 workspaceId,
                 viewerEmail,
@@ -812,7 +813,7 @@ export function createWorkflowRoutes(
     const user = await requireUser(req, res);
     if (!user) return;
     try {
-      await workflow.deleteChangeRequest(num, user);
+      await versionControl.deleteChangeRequest(num, user);
       res.json({ deleted: true });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -824,7 +825,7 @@ export function createWorkflowRoutes(
    * Change an open request's title and/or description. Its author, or anyone
    * who may merge it (an admin, or the holder of write on every changed file);
    * anyone else gets a worded 403, and a merged or closed request a worded
-   * 409 — `WorkflowService.updateChangeRequest` decides both. Answers the
+   * 409 — `VersionControlService.updateChangeRequest` decides both. Answers the
    * updated request. `appendDescription` (the app's own later-round note) adds
    * a paragraph to the description as stored, instead of replacing it.
    */
@@ -846,7 +847,7 @@ export function createWorkflowRoutes(
     const user = await requireUser(req, res);
     if (!user) return;
     try {
-      const updated = await workflow.updateChangeRequest(num, user, {
+      const updated = await versionControl.updateChangeRequest(num, user, {
         title: body.title as string | undefined,
         description: body.description as string | undefined,
         appendDescription: body.appendDescription as string | undefined,
@@ -879,7 +880,7 @@ export function createWorkflowRoutes(
       return;
     }
     try {
-      res.json(await workflow.revertChangeRequestFile(num, user, body.path));
+      res.json(await versionControl.revertChangeRequestFile(num, user, body.path));
     } catch (err) {
       const { status, body: errBody } = toHttpError(err);
       res.status(status).json(errBody);
@@ -904,7 +905,7 @@ export function createWorkflowRoutes(
       // bootstraps the clone if this is the first request for it.
       const workspace = await workspaceService.getOrCreateForBranch(body.sourceBranch);
       res.json(
-        await workflow.openChangeRequest(workspace.id, user, {
+        await versionControl.openChangeRequest(workspace.id, user, {
           sourceBranch: body.sourceBranch,
           targetBranch: body.targetBranch,
           title: body.title,
@@ -932,13 +933,13 @@ export function createWorkflowRoutes(
       // first, then resolve the matching workspace — same reasoning as
       // `openChangeRequest` above. `getOrCreateForBranch` lazily clones
       // if the source branch hasn't been touched on this replica yet.
-      const cr = await workflow.getChangeRequest(num);
+      const cr = await versionControl.getChangeRequest(num);
       if (!cr) {
         res.status(404).json({ error: 'change request not found' });
         return;
       }
       const workspace = await workspaceService.getOrCreateForBranch(cr.branch);
-      res.json(await workflow.updateFromTarget(workspace.id, user, num));
+      res.json(await versionControl.updateFromTarget(workspace.id, user, num));
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -979,7 +980,7 @@ export function createWorkflowRoutes(
     const user = await requireUser(req, res);
     if (!user) return;
     try {
-      const cr = await workflow.getChangeRequest(num);
+      const cr = await versionControl.getChangeRequest(num);
       if (!cr) {
         res.status(404).json({ error: 'change request not found' });
         return;
@@ -996,12 +997,12 @@ export function createWorkflowRoutes(
         return;
       }
       const forkSha =
-        sha || (await workflow.changeRequestForkPoint(workspace.id, cr.base, cr.branch));
+        sha || (await versionControl.changeRequestForkPoint(workspace.id, cr.base, cr.branch));
       if (!forkSha) {
         res.json({ content: null, forkSha: null });
         return;
       }
-      const content = await workflow.fileAtForkPoint(workspace.id, cr.base, forkSha, repoPath);
+      const content = await versionControl.fileAtForkPoint(workspace.id, cr.base, forkSha, repoPath);
       res.json({ content, forkSha });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -1027,7 +1028,7 @@ export function createWorkflowRoutes(
     }
     try {
       const workspace = await workspaceService.getOrCreateForUser(user);
-      const detail = await workflow.getChangeRequestDetail(num, {
+      const detail = await versionControl.getChangeRequestDetail(num, {
         fresh: true,
         workspaceId: workspace.id,
         viewerEmail: user.email,
@@ -1040,7 +1041,7 @@ export function createWorkflowRoutes(
         res.status(404).json({ error: 'change request not found' });
         return;
       }
-      const approvals = await workflow.approveFile(
+      const approvals = await versionControl.approveFile(
         num,
         body.path,
         user,
@@ -1072,7 +1073,7 @@ export function createWorkflowRoutes(
     }
     try {
       const workspace = await workspaceService.getOrCreateForUser(user);
-      const detail = await workflow.getChangeRequestDetail(num, {
+      const detail = await versionControl.getChangeRequestDetail(num, {
         fresh: true,
         workspaceId: workspace.id,
         viewerEmail: user.email,
@@ -1085,7 +1086,7 @@ export function createWorkflowRoutes(
         res.status(404).json({ error: 'change request not found' });
         return;
       }
-      const approvals = await workflow.unapproveFile(
+      const approvals = await versionControl.unapproveFile(
         num,
         targetPath,
         user,
@@ -1112,7 +1113,7 @@ export function createWorkflowRoutes(
     if (!user) return;
     try {
       const workspace = await workspaceService.getOrCreateForUser(user);
-      const detail = await workflow.getChangeRequestDetail(num, {
+      const detail = await versionControl.getChangeRequestDetail(num, {
         fresh: true,
         workspaceId: workspace.id,
         viewerEmail: user.email,
@@ -1125,7 +1126,7 @@ export function createWorkflowRoutes(
         res.status(404).json({ error: 'change request not found' });
         return;
       }
-      const result = await workflow.rejectChangeRequest(
+      const result = await versionControl.rejectChangeRequest(
         num,
         user,
         detail.state,
@@ -1157,7 +1158,7 @@ export function createWorkflowRoutes(
     // timeout — surfacing to the user as a 502 even while the merge is still
     // running. So we ack with 202 and run the merge in the background, reporting
     // the result over the event bus: `change-request-merged` on success (emitted
-    // by the workflow service; the PR viewer refreshes off it), and a
+    // by the version-control service; the PR viewer refreshes off it), and a
     // user-scoped `change-request-merge-failed` on a gate block / conflict /
     // merge error so the UI that kicked it off can react. A failure on a
     // request that exists is ALSO persisted and broadcast (`recordApplyFailure`)
@@ -1167,7 +1168,7 @@ export function createWorkflowRoutes(
     // needs no clearing (only an open request reports a refusal), and a newer
     // refusal simply overwrites the old one.
     res.status(202).json({ status: 'merging', number: num });
-    const attempt = workflow.beginApplyAttempt(num);
+    const attempt = versionControl.beginApplyAttempt(num);
     // What the clicker's reason is scoped against, once the request is loaded.
     // Unset (a failure before that) means read access is unproven: withheld.
     let readScope: { workspaceId: string; paths: string[] } | null = null;
@@ -1188,7 +1189,7 @@ export function createWorkflowRoutes(
       });
       if (!persist) return;
       try {
-        await workflow.recordApplyFailure(num, { reason, kind, at }, user, attempt);
+        await versionControl.recordApplyFailure(num, { reason, kind, at }, user, attempt);
       } catch (err) {
         // The clicker already has the reason; only the other viewers lose it.
         log.warn(`could not record the failed apply of change request #${num}:`, { err });
@@ -1197,7 +1198,7 @@ export function createWorkflowRoutes(
     void (async () => {
       try {
         const workspace = await workspaceService.getOrCreateForUser(user);
-        const detail = await workflow.getChangeRequestDetail(num, {
+        const detail = await versionControl.getChangeRequestDetail(num, {
           fresh: true,
           workspaceId: workspace.id,
           viewerEmail: user.email,
@@ -1213,7 +1214,7 @@ export function createWorkflowRoutes(
           return;
         }
         readScope = { workspaceId: workspace.id, paths: detail.touchedNodePaths };
-        const outcome = await workflow.mergeChangeRequest(
+        const outcome = await versionControl.mergeChangeRequest(
           num,
           user,
           detail.headSha,
@@ -1227,7 +1228,7 @@ export function createWorkflowRoutes(
         if (outcome.kind === 'conflicts-need-resolution') {
           await reportFailure('This draft conflicts with the target and needs resolving first.', 'conflicts');
         }
-        // Success path: `workflow.mergeChangeRequest` emits `change-request-merged`.
+        // Success path: `versionControl.mergeChangeRequest` emits `change-request-merged`.
       } catch (err) {
         const { status, body: errBody } = toHttpError(err);
         log.error(`async merge of change request #${num} failed:`, { err });
@@ -1244,7 +1245,7 @@ export function createWorkflowRoutes(
           !aboutTheCaller,
         );
       } finally {
-        workflow.endApplyAttempt(num, attempt);
+        versionControl.endApplyAttempt(num, attempt);
       }
     })();
   });