@bevel-software/platform-shared 0.1.0

package/src/workflow/events.ts

@@ -0,0 +1,271 @@
+/**
+ * Workflow event bus types — what the backend pushes over SSE to keep the
+ * frontend in sync with state changes, including those triggered by other
+ * users on the same branch or by the agent acting server-side.
+ *
+ * **Scope model** — events have one of three scopes, set by the variant:
+ *
+ *   - **Workspace-scoped** (`workspaceId` field). Pushed to every connected
+ *     session whose current focus is `workspaceId`. Examples: a file changed
+ *     on this branch, someone took the lock on a file. Anyone editing this
+ *     branch cares.
+ *
+ *   - **User-scoped** (`forUserId` field, no `workspaceId`). Pushed only to
+ *     sessions opened by `forUserId`, regardless of their current focus.
+ *     Examples: an agent turn called a tool on your behalf, your view should
+ *     navigate to a different branch. Other users on the same branch don't
+ *     care.
+ *
+ *   - **Global** (no `workspaceId`, no `forUserId`). Pushed to every
+ *     authenticated session. Examples: change requests opening / merging /
+ *     being rejected — any user with access to the repo might care.
+ *
+ * **Identity + replay** — every event carries an `id` (monotonic int) and an
+ * ISO `ts`. Clients reconnecting with `Last-Event-ID: <id>` get the buffered
+ * tail replayed (server's ring buffer is finite — see `WorkflowEventBus`).
+ * If `id` is older than what the buffer still has, the server sends a
+ * `{ kind: 'resync' }` instead so the client refetches the world cleanly.
+ *
+ * **Idempotency over exactly-once** — clients tolerate duplicates and
+ * out-of-order delivery: every payload carries enough state for the UI to
+ * reach the right end state regardless of how many times it sees the event
+ * (e.g. `file-changed` includes the new SHA — UI only refreshes if the open
+ * tab's SHA differs).
+ */
+
+export interface WorkflowEventEnvelope {
+  /** Monotonic, process-local. Used for `Last-Event-ID` replay. */
+  id: number;
+  /** ISO timestamp the event was emitted on the backend. */
+  ts: string;
+}
+
+// ── Workspace-scoped ─────────────────────────────────────────────────────────
+
+/**
+ * A file's content changed on disk — fires for ANY write that lands bytes
+ * for `(workspaceId, branch, path)`, whether or not a commit followed.
+ *
+ *   - **`newSha` set** → a commit landed. The disk write came through the
+ *     full lock-release pipeline (acquire → write → commitFile → push).
+ *     History views should refetch.
+ *
+ *   - **`newSha === null`** → disk bytes changed but no commit yet, i.e.
+ *     the writer is mid-edit (lock still held — e.g. the editor's Ctrl+S
+ *     autosave-to-disk before the final Save click). Watchers should
+ *     refetch content but NOT history (nothing new in git log).
+ *
+ * Emitted from both the human PUT/PATCH/DELETE routes and the agent's
+ * LockingFilesystem so anyone tailing the file sees changes immediately.
+ */
+export interface FileChangedEvent {
+  kind: 'file-changed';
+  workspaceId: string;
+  branch: string;
+  path: string;
+  /** Commit sha if a commit landed; null if this was a disk-only write. */
+  newSha: string | null;
+  /** The user whose write caused the change. */
+  byUserId: string;
+  byUserName: string;
+}
+
+/** Someone (`holderUserId`) just acquired the lock on `(branch, path)`. */
+export interface LockAcquiredEvent {
+  kind: 'lock-acquired';
+  workspaceId: string;
+  branch: string;
+  path: string;
+  holderUserId: string;
+  holderName: string;
+}
+
+/** The lock on `(branch, path)` was released — file is free for the next caller. */
+export interface LockReleasedEvent {
+  kind: 'lock-released';
+  workspaceId: string;
+  branch: string;
+  path: string;
+}
+
+/**
+ * The file tree for `(workspaceId, branch)` changed in a way that's not
+ * captured by a single `file-changed` event — typically a recursive delete,
+ * a move, or an unzip extracting many files. Emitted alongside per-file
+ * `file-changed` events, but lets the file explorer refresh once instead of
+ * N times.
+ */
+export interface FsTreeChangedEvent {
+  kind: 'fs-tree-changed';
+  workspaceId: string;
+  branch: string;
+}
+
+// ── User-scoped ──────────────────────────────────────────────────────────────
+
+/**
+ * Agent called `switch_branch` mid-turn and the target validated +
+ * pre-warmed successfully. Tells the frontend to navigate to the new draft
+ * once the in-flight chat turn completes — navigation mid-stream would tear
+ * down the chat connection. The chat hook stashes the latest pending
+ * destination and consumes it in `onFinish`. The native chat path stamps the
+ * `threadId`; the registry `switch_branch` tool (called over the internal
+ * loopback, which carries no threadId) omits it, so the frontend keys the
+ * pending destination on `forUserId` — a user has one active chat stream.
+ *
+ * User-scoped (no `workspaceId`) — only the user whose agent ran the tool
+ * should follow; other users on the same branch don't care.
+ */
+export interface BranchSwitchedEvent {
+  kind: 'branch-switched';
+  forUserId: string;
+  threadId?: string;
+  branch: string;
+  workspaceId: string;
+}
+
+/**
+ * Agent (running on `forUserId`'s behalf) is about to call a tool — used by
+ * the file explorer to highlight files the agent is touching and by the
+ * chat sidebar to show a live activity feed without parsing the chat
+ * stream's data parts.
+ *
+ * Fired BEFORE the tool runs; the resulting `file-changed` /
+ * `change-request-opened` / etc. events arrive after.
+ */
+export interface AgentToolCallEvent {
+  kind: 'agent-tool-call';
+  forUserId: string;
+  threadId: string;
+  tool: string;
+  /**
+   * Free-form summary of what the tool is about to do (e.g. `"writing
+   * Knowledge/Foo.md"`, `"opening change request Foo → target-company-state"`).
+   * Optional — purely informational, never load-bearing.
+   */
+  summary?: string;
+}
+
+// ── Global ───────────────────────────────────────────────────────────────────
+
+export interface ChangeRequestOpenedEvent {
+  kind: 'change-request-opened';
+  number: number;
+  source: string;
+  target: string;
+  /** Hash of the author's email (matches the marker in the CR body); null when unattributable. */
+  authorIdHash: string | null;
+  title: string;
+}
+
+export interface ChangeRequestMergedEvent {
+  kind: 'change-request-merged';
+  number: number;
+}
+
+export interface ChangeRequestRejectedEvent {
+  kind: 'change-request-rejected';
+  number: number;
+}
+
+/**
+ * A merge the caller triggered did NOT land — either the gate refused it, the
+ * branch needs conflict resolution, or `gh pr merge` failed. The merge route
+ * is async (returns 202 immediately so a large PR's merge can't outlive the
+ * gateway timeout), so this is how the failure reaches the UI that kicked it
+ * off. Success travels on `change-request-merged` instead.
+ *
+ * User-scoped (`forUserId`, no `workspaceId`) — a failed merge changes no
+ * shared state; only the user who clicked needs the reason, so we don't
+ * broadcast the error string to every session.
+ */
+export interface ChangeRequestMergeFailedEvent {
+  kind: 'change-request-merge-failed';
+  forUserId: string;
+  number: number;
+  /** Human-readable reason for the error banner (tokens already redacted). */
+  reason: string;
+  /**
+   * True when the merge failed because the branch needs conflict resolution.
+   * The UI routes to the agent resolution flow instead of showing an error.
+   */
+  conflicts: boolean;
+}
+
+/**
+ * Per-file approval on a change request was added or removed (e.g. via the
+ * Approve / Withdraw confirmation buttons, or auto-invalidated by a new
+ * commit). The UI re-fetches the CR detail to get the updated approval set.
+ */
+export interface ApprovalChangedEvent {
+  kind: 'approval-changed';
+  number: number;
+  path: string;
+  approverUserId: string;
+  change: 'added' | 'removed';
+}
+
+// ── Control ──────────────────────────────────────────────────────────────────
+
+/**
+ * Sent every ~25 s on the SSE stream to keep proxies / load balancers from
+ * killing idle connections. Carries no payload state — the client ignores it
+ * apart from the keepalive effect.
+ */
+export interface HeartbeatEvent {
+  kind: 'heartbeat';
+}
+
+/**
+ * Server told the client to discard its cached state and refetch from
+ * scratch — sent when a reconnecting client's `Last-Event-ID` is older than
+ * the server's ring buffer still has, so we can't trust an event replay to
+ * catch them up.
+ */
+export interface ResyncEvent {
+  kind: 'resync';
+  /** Human-readable reason for logs / debugging. */
+  reason: string;
+}
+
+// ── Union + helpers ──────────────────────────────────────────────────────────
+
+export type WorkflowEventPayload =
+  | FileChangedEvent
+  | LockAcquiredEvent
+  | LockReleasedEvent
+  | FsTreeChangedEvent
+  | BranchSwitchedEvent
+  | AgentToolCallEvent
+  | ChangeRequestOpenedEvent
+  | ChangeRequestMergedEvent
+  | ChangeRequestRejectedEvent
+  | ChangeRequestMergeFailedEvent
+  | ApprovalChangedEvent
+  | HeartbeatEvent
+  | ResyncEvent;
+
+export type WorkflowEvent = WorkflowEventEnvelope & WorkflowEventPayload;
+
+/** True for events scoped to a workspace — the focus filter applies. */
+export function isWorkspaceScoped(
+  e: WorkflowEventPayload,
+): e is WorkflowEventPayload & { workspaceId: string } {
+  return (
+    e.kind === 'file-changed' ||
+    e.kind === 'lock-acquired' ||
+    e.kind === 'lock-released' ||
+    e.kind === 'fs-tree-changed'
+  );
+}
+
+/** True for events scoped to a specific user — the user filter applies. */
+export function isUserScoped(
+  e: WorkflowEventPayload,
+): e is WorkflowEventPayload & { forUserId: string } {
+  return (
+    e.kind === 'agent-tool-call' ||
+    e.kind === 'branch-switched' ||
+    e.kind === 'change-request-merge-failed'
+  );
+}

package/src/workflow/interface.ts

@@ -0,0 +1,357 @@
+/**
+ * `IWorkflowService` — the abstraction the rest of the app talks to instead
+ * of raw git/gh. See `bevel-platform/PLAN.md` for the motivation and the spec the
+ * methods here encode (protected branches, atomic per-file changes, file
+ * locks, change requests as branch-pair reconciliations).
+ *
+ * Naming convention: methods speak workflow vocabulary (`commitChange`,
+ * `openChangeRequest`, `acquireLock`), never git vocabulary (`commit`,
+ * `createPr`, no analogue for locks). Implementations may delegate to the
+ * existing git/PR/review-workflow services until those are folded into
+ * `modules/workflow`; callers should not depend on that fact.
+ *
+ * Some methods on this interface have no backing service yet — file locks,
+ * `openChangeRequest`, `updateFromTarget`. The facade implementation throws
+ * `NotImplementedWorkflowError` from those until the underlying support
+ * lands. The interface defines them up-front so consumers can plan against
+ * the final surface area.
+ */
+
+import type { AuthUser } from '../auth/types.js';
+import type {
+  AcquireLockResult,
+  Branch,
+  BranchWorkspaceStatus,
+  CancelChangeRequestResult,
+  Change,
+  ChangeInput,
+  ChangeRequest,
+  ChangeRequestComment,
+  ChangeRequestDetail,
+  ChangeRequestState,
+  ChangedFile,
+  FileApproval,
+  FileLock,
+  MergeChangeRequestOutcome,
+  OpenChangeRequestInput,
+  PostChangeRequestCommentInput,
+} from './types.js';
+
+export interface IWorkflowService {
+  // ── Branches ──────────────────────────────────────────────────────────────
+
+  listBranches(workspaceId: string, opts?: { freshFetch?: boolean }): Promise<Branch[]>;
+  /**
+   * Create a new unprotected branch. Protected branches cannot be created
+   * via the workflow — the protected set is bootstrapped from the KB repo's
+   * initial state and never grown at runtime.
+   */
+  createBranch(workspaceId: string, name: string, fromBase?: string): Promise<Branch>;
+  /**
+   * Delete a branch. Removes both local and origin refs in one call. The
+   * branch's author (per `<email-localpart>/...` naming) OR an admin (per the
+   * workspace's `roles.yaml`) can delete it. Admins can additionally remove
+   * unprefixed CLI-created branches that have no recognisable author.
+   *
+   * `onlyIfNoRemote: true` is the legacy orphan-cleanup path: bypasses the
+   * author/admin check (callers prune any orphan they encounter) and refuses
+   * if origin still has the ref. Protected and current branches always reject.
+   */
+  deleteBranch(
+    workspaceId: string,
+    name: string,
+    user: AuthUser,
+    opts?: { onlyIfNoRemote?: boolean },
+  ): Promise<void>;
+  // `switchBranch` removed: under the per-branch workspace model the active
+  // branch is the workspace's identity. Switching branches is a workspace
+  // selection (`WorkspaceService.getOrCreateForBranch`), not an operation
+  // on an existing workspace's clone.
+  // `forkCurrentToDraft` removed: under the per-branch workspace model each
+  // branch is its own workspace; nothing carries uncommitted edits across.
+  // `createBranch` + URL navigation covers the "start a new draft" intent.
+  /** Current branch's workspace status — currently just the branch name + upstream sync state. */
+  branchStatus(workspaceId: string): Promise<BranchWorkspaceStatus>;
+  // `discardWorkingChanges` removed: under save=share the working tree is
+  // never dirty, so there is nothing for "undo my unsaved edits" to undo.
+  /**
+   * Push the current branch upstream so other users (and change requests)
+   * can see the commits on it. Workflow term: "share current branch". The
+   * underlying implementation is `git push -u origin <branch>`.
+   */
+  shareCurrentBranch(workspaceId: string, user: AuthUser): Promise<void>;
+  /**
+   * Number of commits on `branch` that aren't on `baseBranch` — exactly
+   * what a CR from `branch` to `baseBranch` would propose for review.
+   * Implemented as `git rev-list --count <baseBranch>..<branch>` against
+   * the workspace's clone; returns 0 when the branch has no unmerged
+   * commits (a fresh fork that nobody wrote to) and when either ref
+   * cannot be resolved. Background runs use this to decide whether a
+   * routine branch deserves a change request — without it, a run where
+   * the agent commits files but forgets to call `open_change_request`
+   * would silently lose its work to the no-changes cleanup path.
+   */
+  countCommitsAhead(workspaceId: string, branch: string, baseBranch: string): Promise<number>;
+  /** Fetch remote refs without modifying the working tree. */
+  refreshRemotes(workspaceId: string): Promise<void>;
+  /** Pull the latest remote state into the current branch (rebase strategy). */
+  updateFromRemote(workspaceId: string): Promise<void>;
+  /**
+   * Hard-reset the workspace's checked-out branch to `origin/<branch>` (fetch
+   * first), discarding any local divergence. Break-glass primitive for
+   * roles.yaml recovery so the restoring commit can fast-forward on push.
+   */
+  resetToRemote(workspaceId: string, branch: string): Promise<void>;
+  /**
+   * Best-fit protected branch that `branch` was forked from — picks the
+   * protected branch on origin yielding the smallest "ahead" count.
+   * Returns null if no protected branch can be reached.
+   */
+  resolveForkBase(workspaceId: string, branch: string): Promise<string | null>;
+  /**
+   * Paths that the next `commitChange` would include — what `git add -A`
+   * would stage: modified + deleted + renamed + untracked (honouring
+   * `.gitignore`). Returns only paths.
+   */
+  listPendingChangePaths(workspaceId: string): Promise<string[]>;
+  // `listWorkingChanges` + `diffFileInWorking` removed: under save=share the
+  // working tree is never dirty, so both report the empty state by
+  // definition. Cross-branch / per-commit diff cases are covered by
+  // `compareFile` + `showFileAtChange` below.
+
+  // ── Changes ───────────────────────────────────────────────────────────────
+
+  /**
+   * Commit one atomic change. The current backing implementation packs every
+   * dirty path in the working tree into the commit; the workflow spec
+   * eventually constrains this to one file per change, enforced at the
+   * commit boundary. Until that lands, callers should already commit
+   * one-file-at-a-time by convention.
+   */
+  commitChange(workspaceId: string, user: AuthUser, input: ChangeInput): Promise<Change>;
+  /**
+   * Commit whatever the caller has already written to the working tree as ONE
+   * atomic change, then push. Unlike `commitChange` (one file at a time, guarded
+   * at the commit boundary) this commits the whole dirty set together — for the
+   * rare case where a group of files must land together or not at all (e.g. a
+   * role rename rewriting `roles.yaml` + every reference). Does NOT write
+   * content: the caller writes the files first (e.g. via the lock-aware
+   * filesystem) and is responsible for any validation. Returns null on a no-op
+   * (clean tree).
+   */
+  commitChanges(
+    workspaceId: string,
+    user: AuthUser,
+    summary: string,
+  ): Promise<Change | null>;
+  /** Per-file history. Newest first; clamps to ≤ 100 entries. */
+  listChangesForFile(workspaceId: string, path: string, limit?: number): Promise<Change[]>;
+  /**
+   * Revert a single change by creating a new change that undoes it.
+   * Refused on protected branches; refused without write permission on the
+   * touched paths.
+   */
+  revertChange(workspaceId: string, user: AuthUser, sha: string): Promise<Change>;
+  /**
+   * Diff of one file between two branches. Both names must resolve to a
+   * known branch on this workspace (local head or remote-tracking). Returns
+   * the raw unified diff body — empty when identical, includes the
+   * "new file" / "deleted file" headers when the file only exists on one
+   * side.
+   */
+  compareFile(
+    workspaceId: string,
+    path: string,
+    fromBranch: string,
+    toBranch: string,
+  ): Promise<string>;
+  /**
+   * Diff of one file at a specific change (sha) — i.e. `git show <sha> -- <path>`.
+   * Used by the File viewer's History tab.
+   */
+  showFileAtChange(workspaceId: string, path: string, sha: string): Promise<string>;
+
+  // ── File locks (new — currently NotImplementedWorkflowError) ──────────────
+
+  /**
+   * Try to acquire an edit lock on `(branch, path)` for the caller. Returns
+   * `{ acquired: true, lock }` on success; `{ acquired: false, lock }` if
+   * someone else already holds it (the existing lock is included so the UI
+   * can render "Locked by X" without a follow-up call).
+   *
+   * Pessimistic per the spec. Auto-released when the lock expires past TTL
+   * without a heartbeat — stale locks must not block forever.
+   */
+  acquireLock(
+    workspaceId: string,
+    branch: string,
+    path: string,
+    user: AuthUser,
+  ): Promise<AcquireLockResult>;
+  /** Heartbeat to keep an acquired lock alive past its current TTL. */
+  heartbeatLock(workspaceId: string, branch: string, path: string, user: AuthUser): Promise<FileLock>;
+  /**
+   * Commit the lock-held file's accumulated edits as a change *without*
+   * releasing the lock. Used by the client-side autosave checkpoint timer
+   * so the lock stays exclusively the caller's across many interim
+   * commits — releasing + reacquiring around every checkpoint would let
+   * another user grab the lock in the gap. Returns `null` when the file
+   * has no pending edits (idempotent). Refused when the lock isn't held
+   * by `user`.
+   */
+  commitFileWhileLocked(
+    workspaceId: string,
+    branch: string,
+    path: string,
+    user: AuthUser,
+    summary?: string,
+  ): Promise<Change | null>;
+
+  /**
+   * Release a held lock. The "I'm done editing this file" terminal signal.
+   *
+   * **Does not commit or push synchronously.** This method enqueues a row in
+   * `pending_commits` and drops the lock, then returns `void`. The background
+   * `PendingCommitsWorker` claims the row, synthesises the commit subject
+   * (callers do *not* supply one — the worker derives a default from the path
+   * and any worker-side metadata), runs `commitFile` against whatever bytes
+   * are on disk, and pushes the result. Decoupling the user-visible lock
+   * release from git means a transient push failure no longer wedges the
+   * editor, and a process crash mid-commit becomes resumable instead of
+   * leaving an orphan on disk. See `lock-decoupling-plan.md` for the full
+   * design.
+   *
+   * The autosave-checkpoint timer and explicit `commitChange` calls land
+   * commits directly (no queue); `releaseLock` is queue-only.
+   */
+  releaseLock(
+    workspaceId: string,
+    branch: string,
+    path: string,
+    user: AuthUser,
+  ): Promise<void>;
+  /**
+   * Drop the lock **without committing**. Used on the failure path of a
+   * lock-aware write — when the underlying op threw, we don't want the
+   * normal `releaseLock` to commit + push whatever partial state happens
+   * to be on disk. The lock row goes away (so the next caller can edit
+   * the file); the working tree is left as-is. Idempotent like
+   * `releaseLock`: a no-op when the caller doesn't hold the lock.
+   */
+  releaseLockNoCommit(
+    workspaceId: string,
+    branch: string,
+    path: string,
+    user: AuthUser,
+  ): Promise<void>;
+  /** Current lock holder for `(branch, path)`, or null when nobody holds it. */
+  getLock(workspaceId: string, branch: string, path: string): Promise<FileLock | null>;
+
+  // ── Change Requests ───────────────────────────────────────────────────────
+
+  listChangeRequests(opts?: { fresh?: boolean }): Promise<ChangeRequest[]>;
+  /** Change requests authored by the caller (hash-matched against the body marker). */
+  listChangeRequestsAuthoredBy(emailOrLogin: string): Promise<ChangeRequest[]>;
+  /** Change requests touching files the user has write permission on. */
+  listChangeRequestsForUser(
+    workspaceId: string,
+    email: string,
+    opts?: { fresh?: boolean },
+  ): Promise<ChangeRequest[]>;
+  getChangeRequest(number: number): Promise<ChangeRequest | null>;
+  getChangeRequestDetail(
+    number: number,
+    opts?: { fresh?: boolean; workspaceId?: string; viewerEmail?: string },
+  ): Promise<ChangeRequestDetail | null>;
+
+  /**
+   * Open a new change request. Per spec, auto-merges `targetBranch` into
+   * `sourceBranch` and surfaces the resulting diff as the changes to review.
+   * Throws `NotImplementedWorkflowError` until the backing create-PR path
+   * lands in the workflow module (today the agent shells `gh pr create`
+   * directly).
+   */
+  openChangeRequest(
+    workspaceId: string,
+    user: AuthUser,
+    input: OpenChangeRequestInput,
+  ): Promise<ChangeRequestDetail>;
+
+  /**
+   * Re-run `targetBranch → sourceBranch` merge on an existing change request.
+   * Used when the target has advanced since the change request was opened.
+   * Throws `NotImplementedWorkflowError` until the backing merge path lands.
+   */
+  updateFromTarget(workspaceId: string, user: AuthUser, number: number): Promise<ChangeRequestDetail>;
+
+  // Comments
+  listComments(number: number): Promise<ChangeRequestComment[]>;
+  postComment(
+    number: number,
+    user: AuthUser,
+    input: PostChangeRequestCommentInput,
+    headSha: string,
+  ): Promise<ChangeRequestComment>;
+  editComment(commentId: string, number: number, user: AuthUser, body: string): Promise<ChangeRequestComment>;
+  deleteComment(commentId: string, number: number, user: AuthUser): Promise<void>;
+
+  // Approvals — per-file, tied to the file's current change. New changes
+  // invalidate approvals on the affected file.
+  approveFile(
+    number: number,
+    path: string,
+    user: AuthUser,
+    files: ChangedFile[],
+    headSha: string,
+    baseBranch: string,
+    authorIdHash: string | null,
+    workspaceId: string,
+  ): Promise<FileApproval[]>;
+  unapproveFile(
+    number: number,
+    path: string,
+    user: AuthUser,
+    files: ChangedFile[],
+    headSha: string,
+    baseBranch: string,
+    authorIdHash: string | null,
+    workspaceId: string,
+  ): Promise<FileApproval[]>;
+
+  /**
+   * Reject a change request without merging. Authorized for the author or
+   * for users with write permission to every changed file on the target
+   * branch.
+   */
+  rejectChangeRequest(
+    number: number,
+    user: AuthUser,
+    state: ChangeRequestState,
+    authorIdHash: string | null,
+    baseBranch: string,
+    workspaceId: string,
+  ): Promise<CancelChangeRequestResult>;
+
+  /**
+   * Merge a change request. The workflow tries a direct merge first; on
+   * conflicts it returns a `conflicts-need-resolution` outcome and the
+   * caller (typically the agent) is responsible for resolving them as new
+   * changes on the source branch. Once the source contains target cleanly,
+   * a subsequent `mergeChangeRequest` call lands the merge.
+   *
+   * The hard merge invariant — only this method may invoke `gh pr merge` —
+   * is preserved through the facade by delegating to
+   * `IReviewWorkflowService.mergePr`.
+   */
+  mergeChangeRequest(
+    number: number,
+    user: AuthUser,
+    headSha: string,
+    approvals: FileApproval[],
+    state: ChangeRequestState,
+    title: string,
+    baseBranch: string,
+    workspaceId: string,
+    opts?: { bypass?: boolean },
+  ): Promise<MergeChangeRequestOutcome>;
+}