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

package/src/modules/workflow/index.ts

@@ -1,7 +1,20 @@
 /**
  * What the workflow module offers the other modules: the addresses of its
  * change requests, so a module that lands a proposal can hand back a link
- * built by the one rule — rather than each spelling the route for itself.
- * The services are wired by the composition root.
+ * built by the one rule — rather than each spelling the route for itself;
+ * and the live-event surface — the bus, the events route, and the delivery
+ * rule every event passes on its way to a session. The services are wired by
+ * the composition root.
  */
 export { CHANGE_REQUEST_URL_NOTE, changeRequestLink, changeRequestLinkBase } from './git/change-request-link.js';
+export { WorkflowEventBus } from './event-bus.js';
+export { createEventsRoutes } from './events.routes.js';
+export { EventDelivery, createEventAccess } from './events-delivery.js';
+export type { ChangeRequestFacts, EventAccess, EventViewer, IEventDelivery } from './events-delivery.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { NodeGitRunner } from './git/node-git-runner.js';
+export { RECOVERY_BOT_EMAIL } from './recovery-bot.js';
+export type { IReviewWorkflowService } from './review-workflow/review-workflow.interface.js';
+export { sanitizeError } from './sanitize-error.js';
+export type { WorkflowHooks } from './workflow-hooks.js';
+export type { WorkflowService } from './workflow.service.js';

package/src/modules/workflow/pending-commits.service.ts

@@ -38,9 +38,9 @@ import { and, asc, eq, inArray, isNull, min, or, sql, type SQL } from 'drizzle-o
 import { logger } from '../../shared/logging.js';
 
 const log = logger('pending-commits');
-import type { Database } from '../database/connection.js';
+import type { Database } from '../database/index.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
-import { pendingCommits } from '../database/schema.js';
+import { pendingCommits } from '../database/index.js';
 import { canonicalWorkspaceId } from '../../shared/workspace-id.js';
 
 /**

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

@@ -1,4 +1,4 @@
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 
 /**

package/src/modules/workflow/recovery-bot.ts

@@ -21,8 +21,8 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('pending-commits');
 import type { AuthUser } from '@bevel-software/platform-shared';
-import type { Database } from '../database/connection.js';
-import { users } from '../database/schema.js';
+import type { Database } from '../database/index.js';
+import { users } from '../database/index.js';
 
 export const RECOVERY_BOT_EMAIL = (
   process.env.RECOVERY_BOT_EMAIL ?? 'recovery-bot@bevel.local'

package/src/modules/workflow/review-workflow/approval-lock.ts

@@ -1,5 +1,5 @@
 import { sql } from 'drizzle-orm';
-import type { Database } from '../../database/connection.js';
+import type { Database } from '../../database/index.js';
 
 /**
  * The lock every writer of `pr_file_approvals` takes, and the one thing that

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

@@ -3,8 +3,6 @@ import type {
   CancelPrResult,
   FileApprovalState,
   MergePrResult,
-  PostPrCommentInput,
-  PrReviewComment,
   PullRequestFile,
   PullRequestState,
 } from '@bevel-software/platform-shared';
@@ -42,42 +40,12 @@ export interface MergeGateResult {
 }
 
 /**
- * Owns the Bevel-side review state for a PR: comments (phase 2), per-file
- * approvals (phase 3), and the merge gate (phase 4). GitHub stays authoritative
- * for the diff + eventual merge; everything in this interface is in-app state
+ * Owns the Bevel-side review state for a PR: per-file approvals (phase 3) and
+ * the merge gate (phase 4). GitHub stays authoritative for the diff + eventual
+ * merge; everything in this interface is in-app state
  * the team uses to decide whether the merge should fire.
  */
 export interface IReviewWorkflowService {
-  /** List all comments for a PR, oldest first. */
-  listComments(prNumber: number): Promise<PrReviewComment[]>;
-
-  /** Post a new comment. Shape of `input` decides whether it's general, file-level, or inline. */
-  postComment(
-    prNumber: number,
-    user: AuthUser,
-    input: PostPrCommentInput,
-    headSha: string,
-  ): Promise<PrReviewComment>;
-
-  /**
-   * Edit an existing comment. Only the original author may edit — 403 otherwise.
-   * `prNumber` scopes the lookup so a caller can't touch a comment from a
-   * different PR via a guessed id; the comment must belong to this PR.
-   */
-  editComment(
-    commentId: string,
-    prNumber: number,
-    user: AuthUser,
-    body: string,
-  ): Promise<PrReviewComment>;
-
-  /**
-   * Delete a comment. Only the original author may delete — 403 otherwise.
-   * Replies are preserved (orphaned to the thread root). `prNumber` scopes the
-   * lookup so a caller can't cross PRs via a guessed id.
-   */
-  deleteComment(commentId: string, prNumber: number, user: AuthUser): Promise<void>;
-
   /**
    * Compose the per-file approval state for a PR detail response. Resolves
    * the eligible approver set against **the PR's base branch on origin**

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

@@ -1,4 +1,4 @@
-import { and, asc, eq, isNull } from 'drizzle-orm';
+import { and, eq, isNull } from 'drizzle-orm';
 import { logger } from '../../../shared/logging.js';
 
 const log = logger('review-workflow');
@@ -8,15 +8,13 @@ import type {
   FileApprovalEntry,
   FileApprovalState,
   MergePrResult,
-  PostPrCommentInput,
-  PrReviewComment,
   PullRequestFile,
   PullRequestState,
 } from '@bevel-software/platform-shared';
-import type { Database } from '../../database/connection.js';
-import { changeRequests, prComments, prFileApprovals, prMergeLog, users } from '../../database/schema.js';
-import { AccessUnreadableError } from '../../access-model/access-errors.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { Database } from '../../database/index.js';
+import { changeRequests, prFileApprovals, prMergeLog, users } from '../../database/index.js';
+import { AccessUnreadableError } from '../../access-model/index.js';
+import type { IAccessControl } from '../../access/index.js';
 import type { GitService } from '../git/git.service.js';
 import { mergeCommitSubject } from '../git/merge-commit.js';
 import { redactSecret } from '../../../shared/redact-secret.js';
@@ -25,7 +23,7 @@ import {
   WorkflowDomainError,
   WorkflowValidationError,
 } from '../../../shared/domain-errors.js';
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { WorkspaceService } from '../../workspace/index.js';
 import { canonicalEmail, hashEmail } from '../../../shared/email-identity.js';
 import type {
   IReviewWorkflowService,
@@ -64,16 +62,6 @@ function redactTokens(msg: string, token: string | null | undefined): string {
   return redactSecret(msg, [token]);
 }
 
-class CommentAuthError extends WorkflowDomainError {
-  constructor(reason: 'not-found' | 'forbidden') {
-    super(
-      reason === 'not-found' ? 'Comment not found' : 'You can only edit your own comments',
-      reason === 'not-found' ? 404 : 403,
-    );
-    this.name = 'CommentAuthError';
-  }
-}
-
 /**
  * Another approval write on this same request is holding the lock and did not
  * let go. Retryable BY THE CALLER, and said in words a business user can act
@@ -174,31 +162,6 @@ function assertValidPrNumber(n: number): void {
   }
 }
 
-function assertValidBody(body: string): void {
-  const trimmed = body.trim();
-  if (!trimmed) throw new WorkflowValidationError('comment body is required');
-  if (trimmed.length > 64_000) {
-    throw new WorkflowValidationError('comment body exceeds 64k character limit');
-  }
-}
-
-function assertValidLine(line: number | undefined): void {
-  if (line === undefined) return;
-  if (!Number.isInteger(line) || line < 1 || line > 1_000_000) {
-    throw new WorkflowValidationError('line must be a positive integer');
-  }
-}
-
-// RFC 4122 — accepts any variant/version so legacy v1 ids still pass. Stricter
-// than "any 32 hex" because Drizzle/PG reject mis-shaped strings with a 500,
-// and we want a 4xx on malformed input from URL params / body fields.
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-function assertValidUuid(value: unknown, fieldName: string): asserts value is string {
-  if (typeof value !== 'string' || !UUID_RE.test(value)) {
-    throw new WorkflowValidationError(`${fieldName} must be a valid UUID`);
-  }
-}
-
 /**
  * Approval enforcement binds every touched file that has someone eligible to
  * approve it per the access tree — Markdown notes, the access-config files
@@ -279,20 +242,6 @@ function assertValidPath(p: unknown): asserts p is string | undefined {
   if (p.includes('\0')) throw new WorkflowValidationError('path contains NUL');
 }
 
-function toDTO(row: typeof prComments.$inferSelect): PrReviewComment {
-  return {
-    id: row.id,
-    author: { email: row.authorEmail, name: row.authorName },
-    body: row.body,
-    path: row.path ?? undefined,
-    line: row.line ?? undefined,
-    headSha: row.headSha,
-    parentId: row.parentId ?? undefined,
-    createdAt: row.createdAt.toISOString(),
-    updatedAt: row.updatedAt ? row.updatedAt.toISOString() : undefined,
-  };
-}
-
 export class ReviewWorkflowService implements IReviewWorkflowService {
   constructor(
     private readonly db: Database,
@@ -301,114 +250,6 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
     private readonly git: GitService,
   ) {}
 
-  async listComments(prNumber: number): Promise<PrReviewComment[]> {
-    assertValidPrNumber(prNumber);
-    const rows = await this.db
-      .select()
-      .from(prComments)
-      .where(eq(prComments.prNumber, prNumber))
-      .orderBy(asc(prComments.createdAt));
-    return rows.map(toDTO);
-  }
-
-  async postComment(
-    prNumber: number,
-    user: AuthUser,
-    input: PostPrCommentInput,
-    headSha: string,
-  ): Promise<PrReviewComment> {
-    assertValidPrNumber(prNumber);
-    assertValidBody(input.body);
-    assertValidPath(input.path);
-    assertValidLine(input.line);
-    if (!headSha) throw new WorkflowValidationError('head sha is required');
-
-    // Inline (line-level) comments must have a path; general comments may have neither.
-    if (input.line !== undefined && !input.path) {
-      throw new WorkflowValidationError('line comments require a file path');
-    }
-
-    // Validate parentId references a real comment on the same PR. UUID format
-    // check first — PG rejects mis-shaped ids with a 500 from its uuid type,
-    // so we convert that to a structured 4xx before hitting the DB. We skip a
-    // depth check — trees deeper than two levels are rare and the UI flattens
-    // them into a single reply chain for display.
-    if (input.parentId !== undefined && input.parentId !== null) {
-      assertValidUuid(input.parentId, 'parentId');
-      const parent = await this.db
-        .select()
-        .from(prComments)
-        .where(
-          and(eq(prComments.id, input.parentId), eq(prComments.prNumber, prNumber)),
-        )
-        .limit(1);
-      if (parent.length === 0) {
-        throw new WorkflowValidationError('parent comment not found on this PR');
-      }
-    }
-
-    const [row] = await this.db
-      .insert(prComments)
-      .values({
-        prNumber,
-        authorEmail: canonicalEmail(user.email),
-        authorEmailBidx: user.email,
-        authorName: user.name,
-        path: input.path ?? null,
-        line: input.line ?? null,
-        headSha,
-        body: input.body.trim(),
-        parentId: input.parentId ?? null,
-      })
-      .returning();
-    return toDTO(row);
-  }
-
-  async editComment(
-    commentId: string,
-    prNumber: number,
-    user: AuthUser,
-    body: string,
-  ): Promise<PrReviewComment> {
-    assertValidPrNumber(prNumber);
-    assertValidUuid(commentId, 'comment id');
-    assertValidBody(body);
-    // Scope lookup to (id, prNumber) so a guessed id from another PR 404s
-    // rather than leaking existence / touching a foreign comment.
-    const existing = await this.db
-      .select()
-      .from(prComments)
-      .where(and(eq(prComments.id, commentId), eq(prComments.prNumber, prNumber)))
-      .limit(1);
-    if (existing.length === 0) throw new CommentAuthError('not-found');
-    if (existing[0].authorEmail !== canonicalEmail(user.email)) {
-      throw new CommentAuthError('forbidden');
-    }
-    const [row] = await this.db
-      .update(prComments)
-      .set({ body: body.trim(), updatedAt: new Date() })
-      .where(and(eq(prComments.id, commentId), eq(prComments.prNumber, prNumber)))
-      .returning();
-    return toDTO(row);
-  }
-
-  async deleteComment(commentId: string, prNumber: number, user: AuthUser): Promise<void> {
-    assertValidPrNumber(prNumber);
-    assertValidUuid(commentId, 'comment id');
-    const existing = await this.db
-      .select()
-      .from(prComments)
-      .where(and(eq(prComments.id, commentId), eq(prComments.prNumber, prNumber)))
-      .limit(1);
-    if (existing.length === 0) throw new CommentAuthError('not-found');
-    if (existing[0].authorEmail !== canonicalEmail(user.email)) {
-      throw new CommentAuthError('forbidden');
-    }
-    await this.db
-      .delete(prComments)
-      .where(and(eq(prComments.id, commentId), eq(prComments.prNumber, prNumber)));
-  }
-
   async getApprovalStates(
     prNumber: number,
     files: PullRequestFile[],

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

@@ -5,7 +5,7 @@
  *
  * URL layout:
  *   /workspace/:id/workflow/...     — workspace-scoped ops (branches, changes, locks, compare)
- *   /workflow/change-requests/...   — change-request ops (list/detail/comments/approvals/merge/reject)
+ *   /workflow/change-requests/...   — change-request ops (list/detail/edit/approvals/merge/reject)
  *
  * Workspace ids are `encodeURIComponent(branch)` (PLAN §3) — branches are
  * shared by every user editing them, so route handlers gate on
@@ -29,20 +29,19 @@ import type {
   ChangeRequestApplyFailureKind,
   IWorkflowService,
   OpenChangeRequestInput,
-  PostChangeRequestCommentInput,
 } from '@bevel-software/platform-shared';
-import type { AuthService } from '../auth/auth.service.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import { canReadWorkspacePath, toKbRelative } from '../access-model/kb-read-filter.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { AuthService } from '../auth/index.js';
+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 { assertReadableAtCommits } from './read-on-branch.js';
-import { assertValidRelativePath } from '../kb-fs/branch-name.js';
+import { assertValidRelativePath } from '../kb-fs/index.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import '../auth/index.js'; // Express Request augmentation
 
 function toHttpError(
   err: unknown,
@@ -821,6 +820,45 @@ 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
+   * updated request. `appendDescription` (the app's own later-round note) adds
+   * a paragraph to the description as stored, instead of replacing it.
+   */
+  router.patch('/workflow/change-requests/:number', async (req, res) => {
+    const num = parsePrNumber(req.params.number);
+    if (num === null) {
+      res.status(400).json({ error: 'invalid change request number' });
+      return;
+    }
+    const body = (req.body ?? {}) as { title?: unknown; description?: unknown; appendDescription?: unknown };
+    if (
+      (body.title !== undefined && typeof body.title !== 'string') ||
+      (body.description !== undefined && typeof body.description !== 'string') ||
+      (body.appendDescription !== undefined && typeof body.appendDescription !== 'string')
+    ) {
+      res.status(400).json({ error: 'title, description and appendDescription must be strings' });
+      return;
+    }
+    const user = await requireUser(req, res);
+    if (!user) return;
+    try {
+      const updated = await workflow.updateChangeRequest(num, user, {
+        title: body.title as string | undefined,
+        description: body.description as string | undefined,
+        appendDescription: body.appendDescription as string | undefined,
+      });
+      const [scoped] = await scopeApplyFailures(req, [updated], user);
+      res.json(scoped);
+    } catch (err) {
+      const { status, body } = toHttpError(err);
+      res.status(status).json(body);
+    }
+  });
+
   /**
    * Decline ONE file of a change request: restore its merge-base version on
    * the source branch, dropping it from the request's diff. Takes the same
@@ -971,98 +1009,6 @@ export function createWorkflowRoutes(
     }
   });
 
-  router.get('/workflow/change-requests/:number/comments', async (req, res) => {
-    const num = parsePrNumber(req.params.number);
-    if (num === null) {
-      res.status(400).json({ error: 'invalid change request number' });
-      return;
-    }
-    try {
-      res.json(await workflow.listComments(num));
-    } catch (err) {
-      const { status, body } = toHttpError(err);
-      res.status(status).json(body);
-    }
-  });
-
-  router.post('/workflow/change-requests/:number/comments', async (req, res) => {
-    const num = parsePrNumber(req.params.number);
-    if (num === null) {
-      res.status(400).json({ error: 'invalid change request number' });
-      return;
-    }
-    const user = await requireUser(req, res);
-    if (!user) return;
-    const body = (req.body ?? {}) as Partial<PostChangeRequestCommentInput>;
-    if (typeof body.body !== 'string') {
-      res.status(400).json({ error: 'body is required' });
-      return;
-    }
-    try {
-      // Resolve the current head from the detail endpoint so the comment
-      // anchors against what the user is actually viewing. Mirrors the
-      // legacy /pr/:n/comments handler.
-      const detail = await workflow.getChangeRequestDetail(num, { fresh: true });
-      if (!detail) {
-        res.status(404).json({ error: 'change request not found' });
-        return;
-      }
-      const comment = await workflow.postComment(
-        num,
-        user,
-        {
-          body: body.body,
-          path: body.path,
-          line: body.line,
-          parentId: body.parentId,
-        },
-        detail.headSha,
-      );
-      res.json(comment);
-    } catch (err) {
-      const { status, body } = toHttpError(err);
-      res.status(status).json(body);
-    }
-  });
-
-  router.patch('/workflow/change-requests/:number/comments/:id', async (req, res) => {
-    const num = parsePrNumber(req.params.number);
-    if (num === null) {
-      res.status(400).json({ error: 'invalid change request number' });
-      return;
-    }
-    const user = await requireUser(req, res);
-    if (!user) return;
-    const body = (req.body ?? {}) as { body?: unknown };
-    if (typeof body.body !== 'string') {
-      res.status(400).json({ error: 'body is required' });
-      return;
-    }
-    try {
-      res.json(await workflow.editComment(req.params.id, num, user, body.body));
-    } catch (err) {
-      const { status, body } = toHttpError(err);
-      res.status(status).json(body);
-    }
-  });
-
-  router.delete('/workflow/change-requests/:number/comments/:id', async (req, res) => {
-    const num = parsePrNumber(req.params.number);
-    if (num === null) {
-      res.status(400).json({ error: 'invalid change request number' });
-      return;
-    }
-    const user = await requireUser(req, res);
-    if (!user) return;
-    try {
-      await workflow.deleteComment(req.params.id, num, user);
-      res.json({ status: 'deleted' });
-    } catch (err) {
-      const { status, body } = toHttpError(err);
-      res.status(status).json(body);
-    }
-  });
-
   // Approve / unapprove. Both fetch fresh detail so the approval pins to the
   // current head — a stale cached head could let the gate accept an approval
   // the user never actually saw.