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

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

@@ -1,5 +1,5 @@
 /**
- * What the workflow module offers the other modules: the addresses of its
+ * What the version-control 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;
  * and the live-event surface — the bus, the events route, and the delivery
@@ -7,14 +7,15 @@
  * the composition root.
  */
 export { CHANGE_REQUEST_URL_NOTE, changeRequestLink, changeRequestLinkBase } from './git/change-request-link.js';
-export { WorkflowEventBus } from './event-bus.js';
+export { VersionControlEventBus } from './event-bus.js';
 export { createEventsRoutes } from './events.routes.js';
+export { createVersionControlRoutes } from './version-control.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 type { IChangeRequestReviewService } from './change-request-review/change-request-review.interface.js';
 export { sanitizeError } from './sanitize-error.js';
-export type { WorkflowHooks } from './workflow-hooks.js';
-export type { WorkflowService } from './workflow.service.js';
+export type { VersionControlHooks } from './version-control-hooks.js';
+export type { VersionControlService } from './version-control.service.js';

package/src/modules/{workflow → version-control}/pending-commits.service.ts

@@ -1,7 +1,7 @@
 /**
  * Persistent queue of "files written to disk but not yet committed to git."
  *
- * Decouples the lock-release path from git work: `WorkflowService.releaseLock`
+ * Decouples the lock-release path from git work: `VersionControlService.releaseLock`
  * enqueues a row and returns immediately; the background `PendingCommitsWorker`
  * drains rows by running `commitFile + push`. Persistence is the point — a
  * process crash mid-commit (the bug class that stranded the `GTM/Uploads/*.docx`
@@ -510,7 +510,7 @@ export class PendingCommitsService {
    * `needs_attention` row deliberately does NOT count: its ladder has
    * escalated to a human and nothing will retry it, so a caller asking
    * "is my landed-but-unpushed commit going to be published?" must hear no.
-   * Backs `IWorkflowService.hasQueuedCommit` (the synced-groups committer's
+   * Backs `IVersionControlService.hasQueuedCommit` (the synced-groups committer's
    * armed-retry proof) and the coordination-release discard guard.
    */
   async hasLiveRowFor(rawWorkspaceId: string, branch: string, path: string): Promise<boolean> {

package/src/modules/{workflow → version-control}/pending-commits.worker.ts

@@ -49,10 +49,10 @@ import {
   canonicalWorkspaceId,
 } from './pending-commits.service.js';
 import { sanitizeError } from './sanitize-error.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 
 /**
- * Where the worker escalates terminal failures — the narrow, workflow-owned
+ * Where the worker escalates terminal failures — the narrow, version-control-owned
  * slice of whatever notice sink the app provides. The enterprise app passes
  * its feedback service (structurally compatible: its `send` accepts a wider
  * source union); a core-only deployment can pass
@@ -134,11 +134,11 @@ export interface RecoveryAgentRunner {
 }
 
 /**
- * Workflow surface the worker depends on. A subset of the real
- * `WorkflowService` — pulled behind an interface so tests can stub the
+ * Version-control surface the worker depends on. A subset of the real
+ * `VersionControlService` — pulled behind an interface so tests can stub the
  * commit/push pipeline without spinning up a real git workspace.
  */
-export interface WorkflowCommitDriver {
+export interface VersionControlCommitDriver {
   /**
    * Commit whatever's currently on disk for `path`, then push the branch.
    * Uses `pushWithRecovery` semantics internally (cooperative pull-rebase
@@ -167,7 +167,7 @@ export interface WorkspaceProvider {
 
 export interface PendingCommitsWorkerDeps {
   service: PendingCommitsService;
-  workflow: WorkflowCommitDriver;
+  versionControl: VersionControlCommitDriver;
   recoveryAgent: RecoveryAgentRunner;
   feedback: ISystemNoticeSink;
   workspaces: WorkspaceProvider;
@@ -361,7 +361,7 @@ export class PendingCommitsWorker {
       name: row.authorName,
     };
     try {
-      await this.deps.workflow.runPendingCommit(row.workspaceId, row.branch, row.path, user, {
+      await this.deps.versionControl.runPendingCommit(row.workspaceId, row.branch, row.path, user, {
         skipValidation: opts?.skipValidation,
       });
       await this.deps.service.markSucceeded(row.id);
@@ -467,7 +467,7 @@ export class PendingCommitsWorker {
  * it on every attempt.
  */
 function pathOutsideRepoCorrection(err: unknown): string | null {
-  if (!(err instanceof WorkflowDomainError) || err.payload?.kind !== 'path-outside-repo') return null;
+  if (!(err instanceof VersionControlDomainError) || err.payload?.kind !== 'path-outside-repo') return null;
   const corrected = err.payload.corrected;
   return typeof corrected === 'string' && corrected.length > 0 ? corrected : '(see error)';
 }

package/src/modules/{workflow → version-control}/read-on-branch.ts

@@ -1,5 +1,5 @@
 import type { IAccessControl } from '../access/index.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 
 /**
  * Which of `paths` `userEmail` may read at `origin/<base>`, as a membership
@@ -48,7 +48,7 @@ export async function readableAtCommits(
 }
 
 /** The refusal `readableAtCommits` answers false with, as every caller words it: the branch named, never the commit. */
-export class ReadOnBranchDeniedError extends WorkflowDomainError {
+export class ReadOnBranchDeniedError extends VersionControlDomainError {
   constructor(displayPath: string, branch: string) {
     super(`You don't have permission to read "${displayPath}" on "${branch}".`, 403, {
       kind: 'read-denied',

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

@@ -1,13 +1,27 @@
-import type { AuthUser, ValidationReport } from '@bevel-software/platform-shared';
+import type { AuthUser, FilesChange, ValidationReport } from '@bevel-software/platform-shared';
+import { callFireAndForget, type FireAndForgetListener } from '../../shared/fire-and-forget.js';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('version-control');
 
 /**
- * Workflow lifecycle hooks — the generic seam that replaced the
+ * Version-control lifecycle hooks — the generic seam that replaced the
  * constructor-injected KB validator. Core code invokes the hooks at fixed
  * lifecycle points; the modules that OWN the behavior register handlers in the
  * composition root, right after `createCoreServices` returns. Core registers
  * none, so a core-only deployment runs every hook point as a no-op.
  *
- * Three hook kinds, with deliberately different failure semantics:
+ * Four hook kinds, with deliberately different failure semantics:
+ *
+ *   - `commitLanded` — INFORMATIONAL. Runs in `GitService` when a commit it
+ *     made is final: right after `git commit` for a save, an autosave
+ *     checkpoint, a batch, a branch merge and a `commit_change`; after the
+ *     push lands for a change-request merge, whose commit is redone on the new
+ *     tip if the push is rejected because the target advanced (any other
+ *     refusal throws, and nothing is reported). Carries the commit's
+ *     workspace-relative paths and the person. The one place a commit is reported from; the composition root
+ *     hands it to the file-change notifier. A hook that throws, or whose
+ *     promise rejects, is logged and can neither fail nor unwind the commit.
  *
  *   - `commitValidation` — ADVISORY. Runs at commit time in `GitService`
  *     (`commit` / `commitFile`), exactly where the injected `IKbValidator`
@@ -82,15 +96,25 @@ export type AgentReadHook = (ctx: AgentOperationContext) => Promise<void>;
 /** Blocking pre-write hook: throw to refuse the write; return to allow. */
 export type PreWriteHook = (ctx: AgentOperationContext) => Promise<void>;
 
+/**
+ * Told of every commit the git service lands — a single-file save, an autosave
+ * checkpoint, a batch, a merge, a `commit_change` — when it lands: pushed, or
+ * awaiting its push. The one place a commit is reported from, so no committer
+ * can be forgotten; the composition root hands it to the file-change notifier.
+ * Fire-and-forget: a hook may answer a promise, which nobody awaits.
+ */
+export type CommitLandedHook = FireAndForgetListener<FilesChange>;
+
 /**
  * The registry instance. ONE per composition (created in
  * `createCoreServices`, shared by `GitService` and exposed as
- * `WorkflowService.hooks` for the composition root to register against).
+ * `VersionControlService.hooks` for the composition root to register against).
  */
-export class WorkflowHooks {
+export class VersionControlHooks {
   private readonly commitValidation: CommitValidationHook[] = [];
   private readonly agentRead: AgentReadHook[] = [];
   private readonly preWrite: PreWriteHook[] = [];
+  private readonly commitLandedHooks: CommitLandedHook[] = [];
 
   /** Register an advisory commit-time validation hook. */
   onCommitValidation(hook: CommitValidationHook): void {
@@ -107,6 +131,21 @@ export class WorkflowHooks {
     this.preWrite.push(hook);
   }
 
+  onCommitLanded(hook: CommitLandedHook): void {
+    this.commitLandedHooks.push(hook);
+  }
+
+  /**
+   * Report a landed commit to every hook, each isolated: a reactor that throws,
+   * or whose promise rejects, is logged and cannot fail — or unwind — the
+   * commit it was told of.
+   */
+  commitLanded(change: FilesChange): void {
+    for (const hook of this.commitLandedHooks) {
+      callFireAndForget(hook, change, log, 'a commit-landed hook failed:');
+    }
+  }
+
   /**
    * The registered commit-validation hooks, for the caller (`GitService`) to
    * iterate with its own advisory catch-and-log semantics.