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

package/src/shared/__tests__/http-errors.test.ts

@@ -3,8 +3,8 @@ import { domainErrorBody } from '../http-errors.js';
 import {
   PathTraversalError,
   UnreadableArchiveError,
-  WorkflowDomainError,
-  WorkflowValidationError,
+  VersionControlDomainError,
+  VersionControlValidationError,
 } from '../domain-errors.js';
 
 /**
@@ -24,7 +24,7 @@ describe('domainErrorBody', () => {
   });
 
   it('is just the message when the error carries no payload', () => {
-    expect(domainErrorBody(new WorkflowValidationError('Only .zip files can be extracted'))).toEqual({
+    expect(domainErrorBody(new VersionControlValidationError('Only .zip files can be extracted'))).toEqual({
       error: 'Only .zip files can be extracted',
     });
   });
@@ -33,7 +33,7 @@ describe('domainErrorBody', () => {
     // Spread payload-last and the client renders "something else entirely"
     // instead of the refusal. `payload` is a Record<string, unknown>, so this
     // key is expressible and nothing but ordering prevents it.
-    const err = new WorkflowDomainError('The real refusal.', 409, {
+    const err = new VersionControlDomainError('The real refusal.', 409, {
       error: 'something else entirely',
       kind: 'contended',
     });

package/src/shared/canonical-file-identity.ts

@@ -23,7 +23,7 @@
  *      the time the validator runs. `WorkspaceService.withPathTurn` runs the
  *      same check first (via the shared `assertValidRelativePath`) and its
  *      `Invalid path: ...` message is what `workspace.routes.sendError` turns
- *      into a 400. Same message here, raised as a 400 `WorkflowValidationError`.
+ *      into a 400. Same message here, raised as a 400 `VersionControlValidationError`.
  *   2. Containment. `withPathTurn` then resolves the path against the
  *      workspace directory and refuses anything landing outside it, which
  *      `sendError` turns into a 403. Step 1 has already rejected every `..`,
@@ -52,13 +52,13 @@
  */
 
 import { canonicalRelativePath, validateRelativePath } from '@bevel-software/platform-shared';
-import { PathTraversalError, WorkflowValidationError } from './domain-errors.js';
+import { PathTraversalError, VersionControlValidationError } from './domain-errors.js';
 
 /**
  * The canonical spelling of `targetPath`, or a throw carrying the status the
  * file verbs answer with for that same input.
  *
- * @throws {WorkflowValidationError} 400, when the path is not a usable
+ * @throws {VersionControlValidationError} 400, when the path is not a usable
  *   workspace-relative path (not a string at all, a `.` or `..` segment, a
  *   backslash, empty).
  * @throws {PathTraversalError} 403, when the path resolves outside the
@@ -74,11 +74,11 @@ export function canonicalFileIdentity(targetPath: string): string {
   // answers. The message is the validator's own for a non-string, so the two
   // 400s read identically as well.
   if (typeof targetPath !== 'string') {
-    throw new WorkflowValidationError('Invalid path: Path is required');
+    throw new VersionControlValidationError('Invalid path: Path is required');
   }
   const canonical = canonicalRelativePath(targetPath);
   const reason = validateRelativePath(canonical);
-  if (reason) throw new WorkflowValidationError(`Invalid path: ${reason}`);
+  if (reason) throw new VersionControlValidationError(`Invalid path: ${reason}`);
   // `validateRelativePath` ACCEPTS `/workspace/a.md` (its leading empty
   // segment is filtered out, leaving two ordinary segments), so absolute is
   // refused here, on its own terms: a workspace-relative path is never

package/src/shared/domain-errors.ts

@@ -1,18 +1,18 @@
 /**
- * Workflow domain errors. This is the single source of truth — every error
- * raised by the workflow domain (branches, changes, change requests, access
+ * Version-control domain errors. This is the single source of truth — every error
+ * raised by the version-control domain (branches, changes, change requests, access
  * control, locks) lives here. Route handlers shape responses via the
  * `.status` + `.payload` contract on the base class.
  *
- * Lives in `src/shared` (not `modules/workflow`) because the classes are
+ * Lives in `src/shared` (not `modules/version-control`) because the classes are
  * consumed across module boundaries — access, diff, plugins and workspace all
  * catch or raise them — and `src/shared` is the layer with no module imports.
  * Only a type from `@bevel-software/platform-shared` comes in; nothing else.
  *
- * Naming: classes use workflow vocabulary. `WorkflowDomainError` is the
- * abstract base; specific subclasses describe the workflow concept that
+ * Naming: classes use version-control vocabulary. `VersionControlDomainError` is the
+ * abstract base; specific subclasses describe the version-control concept that
  * went wrong (`BranchNameError`, `ProtectedBranchError`, etc.). Where a
- * concept is purely git mechanics with no workflow analogue
+ * concept is purely git mechanics with no version-control analogue
  * (`NoSharedHistoryError`), the name keeps its git flavour because
  * consumers actually need to discriminate on it.
  */
@@ -20,25 +20,25 @@
 import type { ValidationReport } from '@bevel-software/platform-shared';
 import { sanitizedPath } from './printable.js';
 
-export class WorkflowDomainError extends Error {
+export class VersionControlDomainError extends Error {
   readonly status: number;
   readonly payload?: Record<string, unknown>;
   constructor(message: string, status: number, payload?: Record<string, unknown>) {
     super(message);
-    this.name = 'WorkflowDomainError';
+    this.name = 'VersionControlDomainError';
     this.status = status;
     this.payload = payload;
   }
 }
 
-export class BranchNameError extends WorkflowDomainError {
+export class BranchNameError extends VersionControlDomainError {
   constructor(reason: string, readonly branchName: string) {
     super(`Invalid branch name "${branchName}": ${reason}`, 400);
     this.name = 'BranchNameError';
   }
 }
 
-export class ProtectedBranchError extends WorkflowDomainError {
+export class ProtectedBranchError extends VersionControlDomainError {
   constructor(readonly branchName: string, readonly action: string) {
     super(`Branch "${branchName}" is protected — ${action} is not allowed.`, 403);
     this.name = 'ProtectedBranchError';
@@ -56,7 +56,7 @@ export class ProtectedBranchError extends WorkflowDomainError {
  * the only way for someone else to delete a non-author's branch is to push
  * the delete via git CLI directly.
  */
-export class BranchAuthorshipError extends WorkflowDomainError {
+export class BranchAuthorshipError extends VersionControlDomainError {
   readonly kind = 'branch-authorship' as const;
   constructor(readonly branchName: string) {
     super(
@@ -69,7 +69,7 @@ export class BranchAuthorshipError extends WorkflowDomainError {
 }
 
 // `DirtyWorkingTreeError` removed: under save=share + per-branch workspaces
-// no operation in the workflow can legitimately encounter a dirty working
+// no operation in the version-control can legitimately encounter a dirty working
 // tree. The two former callers (`switchBranch` and `mergeFromOrigin`'s
 // pre-flight) are gone / relaxed; if a dirty tree ever shows up it's an
 // internal bug that gets server-side-logged in `statusInternal`, never
@@ -83,7 +83,7 @@ export class BranchAuthorshipError extends WorkflowDomainError {
  * rebase conflicts.
  *
  * Per the "disk is the source of truth" rule we do NOT auto-force-push
- * from the workflow layer (that's a destructive history rewrite that can
+ * from the version-control layer (that's a destructive history rewrite that can
  * lose teammate work irrecoverably). Instead we surface this structured
  * error so the frontend can seed an agent prompt — the agent has git + gh
  * CLI access plus the lock-aware write tool, so it can read both sides,
@@ -101,7 +101,7 @@ export class BranchAuthorshipError extends WorkflowDomainError {
  * The payload carries enough context that the prompt builder can phrase
  * the resolution request to the agent without further server round-trips.
  */
-export class PushNeedsAgentResolutionError extends WorkflowDomainError {
+export class PushNeedsAgentResolutionError extends VersionControlDomainError {
   readonly kind = 'push-needs-resolution' as const;
   constructor(
     readonly branch: string,
@@ -143,7 +143,7 @@ export class PushNeedsAgentResolutionError extends WorkflowDomainError {
  * `detail` is the raw git failure, for the server log only; it never enters
  * the message or the payload.
  */
-export class BranchDeleteRefusedError extends WorkflowDomainError {
+export class BranchDeleteRefusedError extends VersionControlDomainError {
   readonly kind = 'branch-delete-refused' as const;
   constructor(readonly branchName: string, readonly detail: string) {
     super(
@@ -166,7 +166,7 @@ export class BranchDeleteRefusedError extends WorkflowDomainError {
  * conflict, and the local commits (someone's saved content, under
  * save=share) stay unshared until the divergence is reconciled. The service
  * layer therefore reacts by queueing a background recovery run (see
- * `WorkflowService.updateFromRemote`); this error tells the caller what
+ * `VersionControlService.updateFromRemote`); this error tells the caller what
  * happened and which paths are contested.
  *
  * 409 like the other conflict errors — the operation needs the divergence
@@ -174,7 +174,7 @@ export class BranchDeleteRefusedError extends WorkflowDomainError {
  * credential-redacted by `GitService.git`) is kept OFF the payload; it's for
  * server logs and the recovery pipeline, not the client.
  */
-export class PullRebaseConflictError extends WorkflowDomainError {
+export class PullRebaseConflictError extends VersionControlDomainError {
   readonly kind = 'pull-rebase-conflict' as const;
   constructor(
     readonly branch: string,
@@ -223,7 +223,7 @@ export const BRANCH_REQUIRED_MESSAGE =
  * 400 with kind `branch-required`, so a client tells it apart from the 404
  * (no such branch) and the 410 (the branch was deleted) without reading prose.
  */
-export class BranchRequiredError extends WorkflowDomainError {
+export class BranchRequiredError extends VersionControlDomainError {
   readonly kind = 'branch-required' as const;
   constructor() {
     super(BRANCH_REQUIRED_MESSAGE, 400, { kind: 'branch-required' });
@@ -273,7 +273,7 @@ export function branchProvided(branch: unknown): branch is string {
  * once did. 404, and the message names the branch and nothing else: no git
  * output, no remote URL.
  */
-export class BranchNotFoundError extends WorkflowDomainError {
+export class BranchNotFoundError extends VersionControlDomainError {
   readonly kind = 'branch-not-found' as const;
   constructor(readonly branch: string) {
     super(`There is no branch named ${branch}.`, 404, {
@@ -291,7 +291,7 @@ export class BranchNotFoundError extends WorkflowDomainError {
  * misdescribe the call — the caller did nothing wrong, the deployment is not
  * set up. 503 with kind `default-branch-unset`; passing a branch works.
  */
-export class DefaultBranchUnsetError extends WorkflowDomainError {
+export class DefaultBranchUnsetError extends VersionControlDomainError {
   readonly kind = 'default-branch-unset' as const;
   constructor() {
     super('This deployment has no default branch configured: pass `branch` to name the one to use.', 503, {
@@ -312,7 +312,7 @@ export class DefaultBranchUnsetError extends WorkflowDomainError {
  * `BranchNotFoundError` — see `WorkspaceService.hasHeardOfBranch`. A sync
  * always has the clone in hand, so it is always this one.
  */
-export class RemoteBranchGoneError extends WorkflowDomainError {
+export class RemoteBranchGoneError extends VersionControlDomainError {
   readonly kind = 'remote-branch-gone' as const;
   constructor(readonly branch: string) {
     super(`Branch "${branch}" no longer exists on the remote.`, 410, {
@@ -345,11 +345,11 @@ export function isMissingRemoteBranchFailure(message: string): boolean {
  * `WorkspaceService.assertWithinWorkspace` throws a bare `Error` with this
  * text and `workspace.routes.sendError` maps that text to 403. The lock
  * service raises this instead of a bare `Error`, because `toHttpError` on the
- * workflow routes reads the status off the class and would otherwise call it
+ * version-control routes reads the status off the class and would otherwise call it
  * a 500. Both surfaces then answer identically for the same input. See
  * `canonicalFileIdentity`.
  */
-export class PathTraversalError extends WorkflowDomainError {
+export class PathTraversalError extends VersionControlDomainError {
   readonly kind = 'path-traversal' as const;
   constructor() {
     super('Path traversal detected', 403, { kind: 'path-traversal' });
@@ -365,7 +365,7 @@ export class PathTraversalError extends WorkflowDomainError {
  */
 export const GIT_INTERNALS_MESSAGE = "That path is inside the repository's internal git data and is not available.";
 
-export class GitInternalsError extends WorkflowDomainError {
+export class GitInternalsError extends VersionControlDomainError {
   readonly kind = 'git-internals' as const;
   constructor() {
     super(GIT_INTERNALS_MESSAGE, 403, { kind: 'git-internals' });
@@ -374,15 +374,15 @@ export class GitInternalsError extends WorkflowDomainError {
 }
 
 /**
- * Generic 400 for workflow-input validation (malformed branch names, missing
+ * Generic 400 for version-control-input validation (malformed branch names, missing
  * fields, etc.). Carries an optional payload so callers can attach typed
  * discriminators (`kind: '...'`) when the frontend needs to switch on the
  * specific failure mode.
  */
-export class WorkflowValidationError extends WorkflowDomainError {
+export class VersionControlValidationError extends VersionControlDomainError {
   constructor(message: string, payload?: Record<string, unknown>) {
     super(message, 400, payload);
-    this.name = 'WorkflowValidationError';
+    this.name = 'VersionControlValidationError';
   }
 }
 
@@ -407,7 +407,7 @@ export type BranchDeleteBlockedReason =
   | 'saves-landing'
   | 'state-unconfirmed';
 
-export class BranchDeleteBlockedError extends WorkflowDomainError {
+export class BranchDeleteBlockedError extends VersionControlDomainError {
   readonly kind = 'branch-delete-blocked' as const;
   constructor(
     readonly reason: BranchDeleteBlockedReason,
@@ -435,7 +435,7 @@ export class BranchDeleteBlockedError extends WorkflowDomainError {
  * because it never mends: a reader may remember it, where a commit the clone
  * merely does not hold yet must be asked for again after the next fetch.
  */
-export class AppliedChangeMismatchError extends WorkflowValidationError {
+export class AppliedChangeMismatchError extends VersionControlValidationError {
   constructor(message: string, payload?: Record<string, unknown>) {
     super(message, payload);
     this.name = 'AppliedChangeMismatchError';
@@ -473,7 +473,7 @@ export const NOT_FOUND_NEXT_STEP = 'Check the path with list_files.';
  * Sanitizing the path and appending the next step in the constructor is what
  * makes those two answers the same answer.
  */
-export class PathNotFoundError extends WorkflowDomainError {
+export class PathNotFoundError extends VersionControlDomainError {
   readonly kind = 'not_found' as const;
   /** The requested path, sanitized — never the path on disk. */
   readonly path: string;
@@ -512,7 +512,7 @@ export const VERSION_NOT_ON_BRANCH_MESSAGE =
  * into an oracle for "does this commit exist in the repository", which is
  * exactly the reading a branch-scoped rule exists to prevent.
  */
-export class VersionNotOnBranchError extends WorkflowDomainError {
+export class VersionNotOnBranchError extends VersionControlDomainError {
   readonly kind = 'version-not-on-branch' as const;
   constructor() {
     super(VERSION_NOT_ON_BRANCH_MESSAGE, 404, { kind: 'version-not-on-branch' });
@@ -529,7 +529,7 @@ export class VersionNotOnBranchError extends WorkflowDomainError {
  * file` prefix its message happens to start with, and a reworded message
  * would silently have turned it into a 500.
  */
-export class UnreadableArchiveError extends WorkflowDomainError {
+export class UnreadableArchiveError extends VersionControlDomainError {
   constructor(reason: string) {
     super(`Could not read zip file: ${reason}`, 422, { kind: 'unreadable-archive' });
     this.name = 'UnreadableArchiveError';
@@ -542,7 +542,7 @@ export class UnreadableArchiveError extends WorkflowDomainError {
  * a structured payload so the frontend's typed-error parser can route into
  * the agent recovery flow.
  */
-export class NoSharedHistoryError extends WorkflowDomainError {
+export class NoSharedHistoryError extends VersionControlDomainError {
   readonly kind = 'no-shared-history' as const;
   constructor(readonly head: string, readonly base: string) {
     super(
@@ -561,7 +561,7 @@ export class NoSharedHistoryError extends WorkflowDomainError {
  * carries the structured report so the UI / agent can render the items
  * the user must fix without re-running the validator.
  */
-export class ValidationFailedError extends WorkflowDomainError {
+export class ValidationFailedError extends VersionControlDomainError {
   readonly validation: ValidationReport;
   constructor(report: ValidationReport) {
     super(
@@ -581,26 +581,26 @@ export class ValidationFailedError extends WorkflowDomainError {
 }
 
 /**
- * Method exists on the workflow interface but has no backing implementation
+ * Method exists on the version-control interface but has no backing implementation
  * yet. 501 so the frontend can light up "coming soon" affordances without
- * confusing them with 5xx infra failures. `feature` is the workflow method
+ * confusing them with 5xx infra failures. `feature` is the version-control method
  * name; clients switch on it to render targeted copy.
  */
-export class NotImplementedWorkflowError extends WorkflowDomainError {
+export class NotImplementedVersionControlError extends VersionControlDomainError {
   readonly kind = 'not-implemented' as const;
   constructor(readonly feature: string) {
     super(
-      `Workflow feature "${feature}" is not yet implemented in this build.`,
+      `Version-control feature "${feature}" is not yet implemented in this build.`,
       501,
       { kind: 'not-implemented', feature },
     );
-    this.name = 'NotImplementedWorkflowError';
+    this.name = 'NotImplementedVersionControlError';
   }
 }
 
 /**
  * Attempting to reconcile two branches (opening a change request, refreshing
- * one from target, or executing a merge) hit conflicts that the workflow
+ * one from target, or executing a merge) hit conflicts that the version-control service
  * cannot auto-resolve. The structured payload carries the list of
  * conflicting paths so the frontend / agent can route into the resolution
  * flow without a second round-trip.
@@ -609,7 +609,7 @@ export class NotImplementedWorkflowError extends WorkflowDomainError {
  * resolving + committing on the source branch) before the operation can
  * succeed — same semantics git itself uses for merge conflicts.
  */
-export class ChangeRequestConflictsError extends WorkflowDomainError {
+export class ChangeRequestConflictsError extends VersionControlDomainError {
   readonly kind = 'change-request-conflicts' as const;
   constructor(
     readonly sourceBranch: string,
@@ -637,7 +637,7 @@ export class ChangeRequestConflictsError extends WorkflowDomainError {
  * waiting for a person to do: merge `sourceBranch` into `targetBranch`.
  * Carries the request's number so the caller can point the person at it.
  */
-export class OpenChangeRequestBlocksMergeError extends WorkflowDomainError {
+export class OpenChangeRequestBlocksMergeError extends VersionControlDomainError {
   readonly kind = 'open-change-request-blocks-merge' as const;
   constructor(
     readonly sourceBranch: string,
@@ -660,7 +660,7 @@ export class OpenChangeRequestBlocksMergeError extends WorkflowDomainError {
  * the existing CR number so the UI / agent can deep-link to it instead of
  * trying to recover.
  */
-export class DuplicateChangeRequestError extends WorkflowDomainError {
+export class DuplicateChangeRequestError extends VersionControlDomainError {
   readonly kind = 'duplicate-change-request' as const;
   constructor(
     readonly sourceBranch: string,
@@ -690,7 +690,7 @@ export class DuplicateChangeRequestError extends WorkflowDomainError {
  * rather than risk landing the CR's version on a protected branch. 502: the
  * failure is an internal git/push hiccup, not the caller's fault.
  */
-export class RolesYamlPreservationError extends WorkflowDomainError {
+export class RolesYamlPreservationError extends VersionControlDomainError {
   readonly kind = 'roles-yaml-preservation-failed' as const;
   /**
    * The underlying git/push failure. Kept OFF the client-facing message (which

package/src/shared/fire-and-forget.ts

@@ -0,0 +1,26 @@
+import type { ILogger } from './logger.contract.js';
+
+/** A listener told of something after the fact: it may answer a promise, which nobody awaits. */
+export type FireAndForgetListener<E> = (event: E) => void | Promise<void>;
+
+/**
+ * Call a fire-and-forget listener so that nothing it does reaches the caller:
+ * a throw is caught, a returned promise's rejection is caught, and either is
+ * logged as `failed`. The caller's own effect — the commit that landed, the
+ * change that was announced — stands whatever the listener does. The one way
+ * core dispatches such listeners (the commit-landed hooks, the file-change
+ * notifier), so the rule is written once; the awaited, channel-answering kind
+ * is `ListenerSeam`.
+ */
+export function callFireAndForget<E>(listener: FireAndForgetListener<E>, event: E, log: ILogger, failed: string): void {
+  try {
+    const answer: unknown = listener(event);
+    if (isPromiseLike(answer)) answer.then(undefined, (err: unknown) => log.error(failed, { err }));
+  } catch (err) {
+    log.error(failed, { err });
+  }
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return typeof value === 'object' && value !== null && typeof (value as PromiseLike<unknown>).then === 'function';
+}

package/src/shared/git.contract.ts

@@ -1,6 +1,6 @@
 /**
  * The contract for RUNNING git. Nothing here spawns anything — the one
- * implementation is `NodeGitRunner` in `modules/workflow/git`, wired once by
+ * implementation is `NodeGitRunner` in `modules/version-control/git`, wired once by
  * the composition root and injected into every module that shells out to git,
  * so no module carries an `execFile('git', …)` of its own.
  *

package/src/shared/http-errors.ts

@@ -1,4 +1,4 @@
-import type { WorkflowDomainError } from './domain-errors.js';
+import type { VersionControlDomainError } from './domain-errors.js';
 
 /**
  * THE response body for a domain refusal: the error's own message, plus
@@ -6,7 +6,7 @@ import type { WorkflowDomainError } from './domain-errors.js';
  * rather than on the prose.
  *
  * The payload is an open `Record<string, unknown>` and deliberately stays
- * that way — `WorkflowValidationError` takes one from its caller — so this
+ * that way — `VersionControlValidationError` takes one from its caller — so this
  * lists no closed set. The discriminator to reach for is `kind`
  * (`path-traversal`, `unreadable-archive`, `no-shared-history`, …), which
  * most refusals carry; beside it they add whatever context that kind needs
@@ -30,7 +30,7 @@ import type { WorkflowDomainError } from './domain-errors.js';
  * workspace routes surface `AccessConfigError`'s message because an admin
  * has to read it — and those differ on purpose, not by drift.
  */
-export function domainErrorBody(err: WorkflowDomainError): Record<string, unknown> {
+export function domainErrorBody(err: VersionControlDomainError): Record<string, unknown> {
   // Payload FIRST, `error` LAST: the message always wins.
   return { ...(err.payload ?? {}), error: err.message };
 }