@bevel-software/platform-core-backend 0.1.0

package/dist/modules/workflow/workflow-hooks.js

@@ -0,0 +1,35 @@
+/**
+ * The registry instance. ONE per composition (created in
+ * `createCoreServices`, shared by `GitService` and exposed as
+ * `WorkflowService.hooks` for the composition root to register against).
+ */
+export class WorkflowHooks {
+    commitValidation = [];
+    preWrite = [];
+    /** Register an advisory commit-time validation hook. */
+    onCommitValidation(hook) {
+        this.commitValidation.push(hook);
+    }
+    /** Register a blocking pre-write hook. */
+    onPreWrite(hook) {
+        this.preWrite.push(hook);
+    }
+    /**
+     * The registered commit-validation hooks, for the caller (`GitService`) to
+     * iterate with its own advisory catch-and-log semantics.
+     */
+    commitValidationHooks() {
+        return this.commitValidation;
+    }
+    /**
+     * Run every blocking pre-write hook in registration order. The first throw
+     * propagates and rejects the write; with no hooks registered (core-only)
+     * this resolves immediately.
+     */
+    async runPreWrite(ctx) {
+        for (const hook of this.preWrite) {
+            await hook(ctx);
+        }
+    }
+}
+//# sourceMappingURL=workflow-hooks.js.map

package/dist/modules/workflow/workflow-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-hooks.js","sourceRoot":"","sources":["../../../src/modules/workflow/workflow-hooks.ts"],"names":[],"mappings":"AA+DA;;;;GAIG;AACH,MAAM,OAAO,aAAa;IACP,gBAAgB,GAA2B,EAAE,CAAC;IAC9C,QAAQ,GAAmB,EAAE,CAAC;IAE/C,wDAAwD;IACxD,kBAAkB,CAAC,IAA0B;QAC3C,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,0CAA0C;IAC1C,UAAU,CAAC,IAAkB;QAC3B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,qBAAqB;QACnB,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,GAAoB;QACpC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF"}

package/dist/modules/workflow/workflow.errors.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Workflow domain errors. This is the single source of truth — every error
+ * raised by the workflow module (branches, changes, change requests, access
+ * control, locks) lives here. Route handlers shape responses via the
+ * `.status` + `.payload` contract on the base class.
+ *
+ * Naming: classes use workflow vocabulary. `WorkflowDomainError` is the
+ * abstract base; specific subclasses describe the workflow concept that
+ * went wrong (`BranchNameError`, `ProtectedBranchError`, etc.). Where a
+ * concept is purely git mechanics with no workflow analogue
+ * (`NoSharedHistoryError`), the name keeps its git flavour because
+ * consumers actually need to discriminate on it.
+ */
+import type { ValidationReport } from '@bevel-software/platform-shared';
+export declare class WorkflowDomainError extends Error {
+    readonly status: number;
+    readonly payload?: Record<string, unknown>;
+    constructor(message: string, status: number, payload?: Record<string, unknown>);
+}
+export declare class BranchNameError extends WorkflowDomainError {
+    readonly branchName: string;
+    constructor(reason: string, branchName: string);
+}
+export declare class ProtectedBranchError extends WorkflowDomainError {
+    readonly branchName: string;
+    readonly action: string;
+    constructor(branchName: string, action: string);
+}
+/**
+ * The caller tried to delete a branch they don't own. Authorship is inferred
+ * from the `<email-localpart>/<slug>` naming convention used by
+ * `slugifyDraftName` — see `isBranchAuthoredBy` in `@bevel-software/platform-shared`.
+ *
+ * Distinct from `AccessDeniedError` because that error is path-based
+ * (file-level write permission via `roles.yaml`/`access.md`). Branch
+ * authorship is identity-based and has no eligible-roles list to surface —
+ * the only way for someone else to delete a non-author's branch is to push
+ * the delete via git CLI directly.
+ */
+export declare class BranchAuthorshipError extends WorkflowDomainError {
+    readonly branchName: string;
+    readonly kind: "branch-authorship";
+    constructor(branchName: string);
+}
+/**
+ * The local commit landed but pushing it to origin failed because the
+ * remote diverged (a teammate or the agent landed competing commits while
+ * the lock was held). The cooperative recovery — `pull --rebase` + retry
+ * push — also failed, because the divergence touches the same file and the
+ * 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
+ * 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,
+ * semantically merge, and save the resolved file through the normal
+ * save=share pipeline. The user sees only a loading indicator; the agent
+ * does the reconciliation.
+ *
+ * State at the moment this fires:
+ *   - The local branch has the user's just-committed change as its HEAD.
+ *   - The lock has already been released (lock release runs BEFORE the
+ *     push attempt). The agent can acquire its own lock.
+ *   - `origin/<branch>` has commits the local clone doesn't reach.
+ *   - The working tree is clean (the commit landed).
+ *
+ * The payload carries enough context that the prompt builder can phrase
+ * the resolution request to the agent without further server round-trips.
+ */
+export declare class PushNeedsAgentResolutionError extends WorkflowDomainError {
+    readonly branch: string;
+    readonly path: string;
+    readonly originalDetail: string;
+    readonly recoveryDetail: string;
+    readonly kind: "push-needs-resolution";
+    constructor(branch: string, path: string, originalDetail: string, recoveryDetail: string);
+}
+/**
+ * Generic 400 for workflow-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 declare class WorkflowValidationError extends WorkflowDomainError {
+    constructor(message: string, payload?: Record<string, unknown>);
+}
+/**
+ * The draft branch doesn't share history with the target branch, so GitHub
+ * would reject the change request with `no history in common`. Surfaced as
+ * a structured payload so the frontend's typed-error parser can route into
+ * the agent recovery flow.
+ */
+export declare class NoSharedHistoryError extends WorkflowDomainError {
+    readonly head: string;
+    readonly base: string;
+    readonly kind: "no-shared-history";
+    constructor(head: string, base: string);
+}
+/**
+ * The KB validator reported `mustFix` issues (DANGLING LINK / ASYMMETRY /
+ * ERROR) — the change cannot land until they're resolved. The payload
+ * carries the structured report so the UI / agent can render the items
+ * the user must fix without re-running the validator.
+ */
+export declare class ValidationFailedError extends WorkflowDomainError {
+    readonly validation: ValidationReport;
+    constructor(report: ValidationReport);
+}
+/**
+ * Method exists on the workflow 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
+ * name; clients switch on it to render targeted copy.
+ */
+export declare class NotImplementedWorkflowError extends WorkflowDomainError {
+    readonly feature: string;
+    readonly kind: "not-implemented";
+    constructor(feature: string);
+}
+/**
+ * Attempting to reconcile two branches (opening a change request, refreshing
+ * one from target, or executing a merge) hit conflicts that the workflow
+ * 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.
+ *
+ * 409 because the conflict is a precondition the caller has to clear (by
+ * resolving + committing on the source branch) before the operation can
+ * succeed — same semantics git itself uses for merge conflicts.
+ */
+export declare class ChangeRequestConflictsError extends WorkflowDomainError {
+    readonly sourceBranch: string;
+    readonly targetBranch: string;
+    readonly conflictedPaths: string[];
+    readonly kind: "change-request-conflicts";
+    constructor(sourceBranch: string, targetBranch: string, conflictedPaths: string[]);
+}
+/**
+ * Caller tried to open a change request for a `(source, target)` pair that
+ * already has one open. Spec rule: A→B blocks A→B (B→A is allowed). Carries
+ * the existing CR number so the UI / agent can deep-link to it instead of
+ * trying to recover.
+ */
+export declare class DuplicateChangeRequestError extends WorkflowDomainError {
+    readonly sourceBranch: string;
+    readonly targetBranch: string;
+    readonly existingNumber: number;
+    readonly kind: "duplicate-change-request";
+    constructor(sourceBranch: string, targetBranch: string, existingNumber: number);
+}
+/**
+ * Raised when a merge must neutralise a CR's `roles.yaml` change (restore the
+ * base branch's version on the source branch) but that preservation write fails.
+ * `roles.yaml` decides admin membership and is mutable ONLY via the admin Roles
+ * & Members surface — a CR must never carry a roles.yaml change across a merge,
+ * so if we cannot guarantee the base version is preserved we abort the merge
+ * 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 declare class RolesYamlPreservationError extends WorkflowDomainError {
+    readonly kind: "roles-yaml-preservation-failed";
+    /**
+     * The underlying git/push failure. Kept OFF the client-facing message (which
+     * stays generic for the 502) so raw git internals / paths don't leak to the
+     * caller — log this server-side for diagnostics instead.
+     */
+    readonly detail: string;
+    constructor(reason: string);
+}
+//# sourceMappingURL=workflow.errors.d.ts.map

package/dist/modules/workflow/workflow.errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.errors.d.ts","sourceRoot":"","sources":["../../../src/modules/workflow/workflow.errors.ts"],"names":[],"mappings":"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"}

package/dist/modules/workflow/workflow.errors.js

@@ -0,0 +1,260 @@
+/**
+ * Workflow domain errors. This is the single source of truth — every error
+ * raised by the workflow module (branches, changes, change requests, access
+ * control, locks) lives here. Route handlers shape responses via the
+ * `.status` + `.payload` contract on the base class.
+ *
+ * Naming: classes use workflow vocabulary. `WorkflowDomainError` is the
+ * abstract base; specific subclasses describe the workflow concept that
+ * went wrong (`BranchNameError`, `ProtectedBranchError`, etc.). Where a
+ * concept is purely git mechanics with no workflow analogue
+ * (`NoSharedHistoryError`), the name keeps its git flavour because
+ * consumers actually need to discriminate on it.
+ */
+export class WorkflowDomainError extends Error {
+    status;
+    payload;
+    constructor(message, status, payload) {
+        super(message);
+        this.name = 'WorkflowDomainError';
+        this.status = status;
+        this.payload = payload;
+    }
+}
+export class BranchNameError extends WorkflowDomainError {
+    branchName;
+    constructor(reason, branchName) {
+        super(`Invalid branch name "${branchName}": ${reason}`, 400);
+        this.branchName = branchName;
+        this.name = 'BranchNameError';
+    }
+}
+export class ProtectedBranchError extends WorkflowDomainError {
+    branchName;
+    action;
+    constructor(branchName, action) {
+        super(`Branch "${branchName}" is protected — ${action} is not allowed.`, 403);
+        this.branchName = branchName;
+        this.action = action;
+        this.name = 'ProtectedBranchError';
+    }
+}
+/**
+ * The caller tried to delete a branch they don't own. Authorship is inferred
+ * from the `<email-localpart>/<slug>` naming convention used by
+ * `slugifyDraftName` — see `isBranchAuthoredBy` in `@bevel-software/platform-shared`.
+ *
+ * Distinct from `AccessDeniedError` because that error is path-based
+ * (file-level write permission via `roles.yaml`/`access.md`). Branch
+ * authorship is identity-based and has no eligible-roles list to surface —
+ * 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 {
+    branchName;
+    kind = 'branch-authorship';
+    constructor(branchName) {
+        super(`Only the author of "${branchName}" can delete it.`, 403, { kind: 'branch-authorship', branchName });
+        this.branchName = branchName;
+        this.name = 'BranchAuthorshipError';
+    }
+}
+// `DirtyWorkingTreeError` removed: under save=share + per-branch workspaces
+// no operation in the workflow 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
+// surfaced as a user-facing 409.
+/**
+ * The local commit landed but pushing it to origin failed because the
+ * remote diverged (a teammate or the agent landed competing commits while
+ * the lock was held). The cooperative recovery — `pull --rebase` + retry
+ * push — also failed, because the divergence touches the same file and the
+ * 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
+ * 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,
+ * semantically merge, and save the resolved file through the normal
+ * save=share pipeline. The user sees only a loading indicator; the agent
+ * does the reconciliation.
+ *
+ * State at the moment this fires:
+ *   - The local branch has the user's just-committed change as its HEAD.
+ *   - The lock has already been released (lock release runs BEFORE the
+ *     push attempt). The agent can acquire its own lock.
+ *   - `origin/<branch>` has commits the local clone doesn't reach.
+ *   - The working tree is clean (the commit landed).
+ *
+ * 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 {
+    branch;
+    path;
+    originalDetail;
+    recoveryDetail;
+    kind = 'push-needs-resolution';
+    constructor(branch, path, originalDetail, recoveryDetail) {
+        super(`Saved locally on "${branch}" but couldn't share with the team automatically — ` +
+            `the remote diverged on "${path}" and the cooperative rebase couldn't reconcile. ` +
+            `The agent will resolve this.`, 409, {
+            kind: 'push-needs-resolution',
+            branch,
+            path,
+            originalDetail,
+            recoveryDetail,
+        });
+        this.branch = branch;
+        this.path = path;
+        this.originalDetail = originalDetail;
+        this.recoveryDetail = recoveryDetail;
+        this.name = 'PushNeedsAgentResolutionError';
+    }
+}
+/**
+ * Generic 400 for workflow-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 {
+    constructor(message, payload) {
+        super(message, 400, payload);
+        this.name = 'WorkflowValidationError';
+    }
+}
+/**
+ * The draft branch doesn't share history with the target branch, so GitHub
+ * would reject the change request with `no history in common`. Surfaced as
+ * a structured payload so the frontend's typed-error parser can route into
+ * the agent recovery flow.
+ */
+export class NoSharedHistoryError extends WorkflowDomainError {
+    head;
+    base;
+    kind = 'no-shared-history';
+    constructor(head, base) {
+        super(`The draft "${head}" doesn't share history with "${base}". ` +
+            `It was likely started outside the app or from an unrelated point.`, 400, { kind: 'no-shared-history', head, base });
+        this.head = head;
+        this.base = base;
+        this.name = 'NoSharedHistoryError';
+    }
+}
+/**
+ * The KB validator reported `mustFix` issues (DANGLING LINK / ASYMMETRY /
+ * ERROR) — the change cannot land until they're resolved. The payload
+ * 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 {
+    validation;
+    constructor(report) {
+        super(`Cannot commit — knowledge graph has ${report.mustFix.length} unresolved issue(s).`, 422, {
+            validation: {
+                ok: report.ok,
+                mustFix: report.mustFix,
+                warnings: report.warnings,
+            },
+        });
+        this.name = 'ValidationFailedError';
+        this.validation = report;
+    }
+}
+/**
+ * Method exists on the workflow 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
+ * name; clients switch on it to render targeted copy.
+ */
+export class NotImplementedWorkflowError extends WorkflowDomainError {
+    feature;
+    kind = 'not-implemented';
+    constructor(feature) {
+        super(`Workflow feature "${feature}" is not yet implemented in this build.`, 501, { kind: 'not-implemented', feature });
+        this.feature = feature;
+        this.name = 'NotImplementedWorkflowError';
+    }
+}
+/**
+ * Attempting to reconcile two branches (opening a change request, refreshing
+ * one from target, or executing a merge) hit conflicts that the workflow
+ * 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.
+ *
+ * 409 because the conflict is a precondition the caller has to clear (by
+ * resolving + committing on the source branch) before the operation can
+ * succeed — same semantics git itself uses for merge conflicts.
+ */
+export class ChangeRequestConflictsError extends WorkflowDomainError {
+    sourceBranch;
+    targetBranch;
+    conflictedPaths;
+    kind = 'change-request-conflicts';
+    constructor(sourceBranch, targetBranch, conflictedPaths) {
+        const list = conflictedPaths.join(', ');
+        super(`Conflicts merging "${targetBranch}" into "${sourceBranch}". ` +
+            `${conflictedPaths.length} file(s): ${list}. Resolve on "${sourceBranch}" and try again.`, 409, {
+            kind: 'change-request-conflicts',
+            sourceBranch,
+            targetBranch,
+            conflictedPaths,
+        });
+        this.sourceBranch = sourceBranch;
+        this.targetBranch = targetBranch;
+        this.conflictedPaths = conflictedPaths;
+        this.name = 'ChangeRequestConflictsError';
+    }
+}
+/**
+ * Caller tried to open a change request for a `(source, target)` pair that
+ * already has one open. Spec rule: A→B blocks A→B (B→A is allowed). Carries
+ * the existing CR number so the UI / agent can deep-link to it instead of
+ * trying to recover.
+ */
+export class DuplicateChangeRequestError extends WorkflowDomainError {
+    sourceBranch;
+    targetBranch;
+    existingNumber;
+    kind = 'duplicate-change-request';
+    constructor(sourceBranch, targetBranch, existingNumber) {
+        super(`An open change request already exists from "${sourceBranch}" to "${targetBranch}" (#${existingNumber}).`, 409, {
+            kind: 'duplicate-change-request',
+            sourceBranch,
+            targetBranch,
+            existingNumber,
+        });
+        this.sourceBranch = sourceBranch;
+        this.targetBranch = targetBranch;
+        this.existingNumber = existingNumber;
+        this.name = 'DuplicateChangeRequestError';
+    }
+}
+/**
+ * Raised when a merge must neutralise a CR's `roles.yaml` change (restore the
+ * base branch's version on the source branch) but that preservation write fails.
+ * `roles.yaml` decides admin membership and is mutable ONLY via the admin Roles
+ * & Members surface — a CR must never carry a roles.yaml change across a merge,
+ * so if we cannot guarantee the base version is preserved we abort the merge
+ * 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 {
+    kind = 'roles-yaml-preservation-failed';
+    /**
+     * The underlying git/push failure. Kept OFF the client-facing message (which
+     * stays generic for the 502) so raw git internals / paths don't leak to the
+     * caller — log this server-side for diagnostics instead.
+     */
+    detail;
+    constructor(reason) {
+        super('Could not preserve the official roles.yaml while merging — merge aborted so no roles.yaml change can ride in.', 502, { kind: 'roles-yaml-preservation-failed' });
+        this.name = 'RolesYamlPreservationError';
+        this.detail = reason;
+    }
+}
+//# sourceMappingURL=workflow.errors.js.map

package/dist/modules/workflow/workflow.errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.errors.js","sourceRoot":"","sources":["../../../src/modules/workflow/workflow.errors.ts"],"names":[],"mappings":"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"}

package/dist/modules/workflow/workflow.routes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `/workflow/*` HTTP surface — the route family the frontend and agent
+ * should reach for instead of `/git/*` and `/pr/*`. Today these are additive
+ * (the old families keep working); migration plan in `bevel-platform/PLAN.md`.
+ *
+ * URL layout:
+ *   /workspace/:id/workflow/...     — workspace-scoped ops (branches, changes, locks, compare)
+ *   /workflow/change-requests/...   — change-request ops (list/detail/comments/approvals/merge/reject)
+ *
+ * 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`
+ * which exposes `.status` + optional `.payload`, so a single `toHttpError`
+ * covers all branches/changes/CR errors uniformly.
+ */
+import express from 'express';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthService } from '../auth/auth.service.js';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkflowEventBus } from './event-bus.js';
+import '../auth/auth.middleware.js';
+export declare function createWorkflowRoutes(workflow: IWorkflowService, workspaceService: WorkspaceService, authService: AuthService, events: WorkflowEventBus): express.Router;
+//# sourceMappingURL=workflow.routes.d.ts.map

package/dist/modules/workflow/workflow.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/workflow/workflow.routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAGV,gBAAgB,EAGjB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,4BAA4B,CAAC;AAyBpC,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,gBAAgB,EAAE,gBAAgB,EAClC,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,MAAM,CA2xBhB"}