@bevel-software/platform-core-backend 0.13.6 → 0.15.1

package/dist/modules/kb-fs/mutex.d.ts

@@ -7,5 +7,42 @@
 export declare class WorkspaceMutex {
     private readonly tails;
     run<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Reserve SEVERAL keys for one operation, atomically.
+     *
+     * Nesting `run(a, () => run(b, fn))` does NOT do this: between taking `a`
+     * and taking `b` there is a gap in which another operation can take `b`,
+     * finish, and release it — so an operation holding both keys can still be
+     * interleaved with one holding just the second. For branch lifecycle that
+     * gap is the whole bug: a change request being opened `Y -> X` would hold
+     * one branch's key while the other was deleted out from under it.
+     *
+     * This reserves the set in ONE synchronous step. The tails are read and
+     * rewritten without an await between, so no other call can observe a
+     * half-taken set: a concurrent `run` on any of these keys either already
+     * sits in `prev` (it goes first) or chains onto `next` (it goes after).
+     * Within one call nothing is ever held while waiting for something else,
+     * so callers that do not nest need no ordering discipline and cannot
+     * deadlock.
+     *
+     * NESTING is the one way to reintroduce hold-and-wait, so never nest
+     * `run`/`runAll` calls on the same instance. An inner call chains behind
+     * everything already queued on its keys, which can include a `runAll` that
+     * is itself waiting for the outer call to finish: `run(b, () => run(a, …))`
+     * was harmless when every operation took a single key, but against a
+     * concurrent `runAll([a, b])` it deadlocks — outer waits inner, inner
+     * waits the pair, the pair waits outer. No caller nests today; keep it
+     * that way, or hand the full key set to one `runAll` at the top.
+     *
+     * Duplicate keys collapse; the operation waits on each distinct key once.
+     *
+     * Each predecessor is caught INDIVIDUALLY, before the `Promise.all`. A bare
+     * `Promise.all` settles on the first rejection rather than waiting for the
+     * rest, so one key's task failing early would start this one while another
+     * key was still held — a failure on any key would punch a hole in the
+     * mutual exclusion of every key beside it. Catching first makes the
+     * combined promise wait for all of them to settle, however each ends.
+     */
+    runAll<T>(keys: string[], fn: () => Promise<T>): Promise<T>;
 }
 //# sourceMappingURL=mutex.d.ts.map

package/dist/modules/kb-fs/mutex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mutex.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-fs/mutex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAEvD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAY5D"}
+{"version":3,"file":"mutex.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-fs/mutex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAEvD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAI3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAiBlE"}

package/dist/modules/kb-fs/mutex.js

@@ -7,15 +7,58 @@
 export class WorkspaceMutex {
     tails = new Map();
     async run(key, fn) {
-        const prev = this.tails.get(key) ?? Promise.resolve();
-        const next = prev.catch(() => undefined).then(fn);
-        this.tails.set(key, next);
+        return this.runAll([key], fn);
+    }
+    /**
+     * Reserve SEVERAL keys for one operation, atomically.
+     *
+     * Nesting `run(a, () => run(b, fn))` does NOT do this: between taking `a`
+     * and taking `b` there is a gap in which another operation can take `b`,
+     * finish, and release it — so an operation holding both keys can still be
+     * interleaved with one holding just the second. For branch lifecycle that
+     * gap is the whole bug: a change request being opened `Y -> X` would hold
+     * one branch's key while the other was deleted out from under it.
+     *
+     * This reserves the set in ONE synchronous step. The tails are read and
+     * rewritten without an await between, so no other call can observe a
+     * half-taken set: a concurrent `run` on any of these keys either already
+     * sits in `prev` (it goes first) or chains onto `next` (it goes after).
+     * Within one call nothing is ever held while waiting for something else,
+     * so callers that do not nest need no ordering discipline and cannot
+     * deadlock.
+     *
+     * NESTING is the one way to reintroduce hold-and-wait, so never nest
+     * `run`/`runAll` calls on the same instance. An inner call chains behind
+     * everything already queued on its keys, which can include a `runAll` that
+     * is itself waiting for the outer call to finish: `run(b, () => run(a, …))`
+     * was harmless when every operation took a single key, but against a
+     * concurrent `runAll([a, b])` it deadlocks — outer waits inner, inner
+     * waits the pair, the pair waits outer. No caller nests today; keep it
+     * that way, or hand the full key set to one `runAll` at the top.
+     *
+     * Duplicate keys collapse; the operation waits on each distinct key once.
+     *
+     * Each predecessor is caught INDIVIDUALLY, before the `Promise.all`. A bare
+     * `Promise.all` settles on the first rejection rather than waiting for the
+     * rest, so one key's task failing early would start this one while another
+     * key was still held — a failure on any key would punch a hole in the
+     * mutual exclusion of every key beside it. Catching first makes the
+     * combined promise wait for all of them to settle, however each ends.
+     */
+    async runAll(keys, fn) {
+        const distinct = [...new Set(keys)];
+        const prev = Promise.all(distinct.map((k) => (this.tails.get(k) ?? Promise.resolve()).catch(() => undefined)));
+        const next = prev.then(fn);
+        for (const k of distinct)
+            this.tails.set(k, next);
         try {
             return await next;
         }
         finally {
-            if (this.tails.get(key) === next) {
-                this.tails.delete(key);
+            for (const k of distinct) {
+                if (this.tails.get(k) === next) {
+                    this.tails.delete(k);
+                }
             }
         }
     }

package/dist/modules/kb-fs/mutex.js.map

@@ -1 +1 @@
-{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../../src/modules/kb-fs/mutex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IACR,KAAK,GAAG,IAAI,GAAG,EAA4B,CAAC;IAE7D,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,EAAoB;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACtD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;gBACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../../src/modules/kb-fs/mutex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IACR,KAAK,GAAG,IAAI,GAAG,EAA4B,CAAC;IAE7D,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,EAAoB;QAC5C,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,KAAK,CAAC,MAAM,CAAI,IAAc,EAAE,EAAoB;QAClD,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACpC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CACtB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CACrF,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3B,KAAK,MAAM,CAAC,IAAI,QAAQ;YAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;gBACzB,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;oBAC/B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBACvB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/modules/kb-sync/index.d.ts

@@ -0,0 +1,6 @@
+export type { IKbSyncService, LastSync, SyncRequest, SyncResult, SyncWorkflowPort, SyncWorkspacePort, } from './kb-sync.interface.js';
+export { KbSyncService } from './kb-sync.service.js';
+export { createKbSyncRoutes, httpStatusFor, isSyncRawBodyPath, SYNC_RESPONSE_HEADER, SYNC_RESPONSE_MARKER, type KbSyncRouteDeps, } from './kb-sync.routes.js';
+export { parseSyncPayload, type ParsedSyncPayload, type SyncPayloadSource } from './sync-payload.js';
+export { verifySyncCredential, type SyncAuthInput, type SyncAuthResult, type SyncCredential } from './sync-auth.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/kb-sync/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-sync/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,cAAc,EACd,QAAQ,EACR,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrG,OAAO,EAAE,oBAAoB,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/modules/kb-sync/index.js

@@ -0,0 +1,5 @@
+export { KbSyncService } from './kb-sync.service.js';
+export { createKbSyncRoutes, httpStatusFor, isSyncRawBodyPath, SYNC_RESPONSE_HEADER, SYNC_RESPONSE_MARKER, } from './kb-sync.routes.js';
+export { parseSyncPayload } from './sync-payload.js';
+export { verifySyncCredential } from './sync-auth.js';
+//# sourceMappingURL=index.js.map

package/dist/modules/kb-sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/kb-sync/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,GAErB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAkD,MAAM,mBAAmB,CAAC;AACrG,OAAO,EAAE,oBAAoB,EAAgE,MAAM,gBAAgB,CAAC"}

package/dist/modules/kb-sync/kb-sync.interface.d.ts

@@ -0,0 +1,77 @@
+import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
+/**
+ * Remote sync: a git host (Azure DevOps, GitHub, GitLab, a pipeline) tells
+ * Hexis "the repository changed" and Hexis brings the clones it holds up to
+ * date. The module owns the HTTP surface, the credential check, the payload
+ * parsing and the coalescing; every git operation happens behind the
+ * workflow port below, never here.
+ */
+/** Which branches a caller asked to sync. `'all'` = every clone Hexis holds. */
+export interface SyncRequest {
+    branches: string[] | 'all';
+    /** Who asked — a credential kind or an admin's email — for the last-sync record. */
+    by?: string;
+}
+/**
+ * What the most recent sync did, for the admin's Deployment page. Kept in
+ * memory only: it answers "is the hook wired up and working?", and a restart
+ * resetting it to "none yet" is the honest answer for a fresh process.
+ */
+export interface LastSync {
+    /** Epoch ms when the sync finished. */
+    at: number;
+    by: string;
+    status: SyncResult['status'];
+    /** One entry per branch, as the response carried them. */
+    results: BranchSyncOutcome[];
+}
+export interface SyncResult {
+    /** `synced` when no branch needs a person or a retry; `partial` otherwise. */
+    status: 'synced' | 'partial';
+    results: BranchSyncOutcome[];
+    changeRequests: {
+        /** Open change requests closed because one of their branches is gone from the host. */
+        closedDeletedBranch: number;
+    };
+}
+export interface IKbSyncService {
+    /**
+     * Sync the requested branches. One sync runs at a time; a request arriving
+     * mid-run is folded into a single queued follow-up (the union of every
+     * request that arrived meanwhile) and resolves with that follow-up's result.
+     * Never rejects for a per-branch failure — those are outcomes.
+     */
+    sync(request: SyncRequest): Promise<SyncResult>;
+    /** The most recent completed sync in this process, or null before the first. */
+    lastSync(): LastSync | null;
+}
+/** The slice of the workflow module a sync drives. */
+export interface SyncWorkflowPort {
+    syncWorkspaceFromRemote(workspaceId: string): Promise<BranchSyncOutcome>;
+    /**
+     * Retire the clone of a branch the host deleted, under the branch-lifecycle
+     * lock and only if origin still lacks it. Returns whether it was removed.
+     */
+    retireRemoteGoneClone(workspaceId: string): Promise<boolean>;
+    /** The existing sweep; returns how many requests it closed. */
+    closeChangeRequestsWithDeletedBranches(): Promise<number>;
+}
+/**
+ * The slice of the workspace module a sync reads: which clones exist ON
+ * DISK. Not the in-memory "seen this process" cache — clones survive a
+ * restart and a hook that fires before anyone has opened a branch must still
+ * find them.
+ */
+export interface SyncWorkspacePort {
+    /**
+     * `unreadable` names a clone the listing could see but not probe (an ACL,
+     * a half-deleted directory); the sync reports it as that branch's error
+     * rather than letting one bad directory fail every other branch.
+     */
+    listClonedWorkspaces(): Promise<Array<{
+        id: string;
+        branch: string;
+        unreadable?: string;
+    }>>;
+}
+//# sourceMappingURL=kb-sync.interface.d.ts.map

package/dist/modules/kb-sync/kb-sync.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-sync.interface.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-sync/kb-sync.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAEzE;;;;;;GAMG;AAEH,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAC3B,oFAAoF;IACpF,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7B,0DAA0D;IAC1D,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,cAAc,EAAE;QACd,uFAAuF;QACvF,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAChD,gFAAgF;IAChF,QAAQ,IAAI,QAAQ,GAAG,IAAI,CAAC;CAC7B;AAED,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACzE;;;OAGG;IACH,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,+DAA+D;IAC/D,sCAAsC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3D;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,oBAAoB,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CAC7F"}

package/dist/modules/kb-sync/kb-sync.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=kb-sync.interface.js.map

package/dist/modules/kb-sync/kb-sync.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-sync.interface.js","sourceRoot":"","sources":["../../../src/modules/kb-sync/kb-sync.interface.ts"],"names":[],"mappings":""}

package/dist/modules/kb-sync/kb-sync.routes.d.ts

@@ -0,0 +1,70 @@
+import express from 'express';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { IKbSyncService, SyncResult } from './kb-sync.interface.js';
+/**
+ * Remote sync — a git host or a pipeline tells Hexis the repository changed.
+ *
+ *   POST /api/sync/<branch>   sync that one branch — the branch whose change
+ *                             made the call. What a GitHub Action or a
+ *                             pipeline step uses: the branch name goes in the
+ *                             URL, the body is ignored for branch selection.
+ *   POST /api/sync            the branches named by the body — an Azure
+ *                             DevOps service hook or a GitHub/GitLab webhook
+ *                             payload (they cannot template the URL), an
+ *                             explicit `{ "branches": [...] }`, or nothing,
+ *                             which syncs every clone Hexis holds.
+ *
+ * Mounted BEFORE every JWT-protected `/api` mount: the caller is a machine
+ * holding the deployment's sync secret, not a browser session, and Express 5
+ * would otherwise 401 it in the first protected mount. The route parses its
+ * own body as raw bytes (the global JSON parser skips this path) because the
+ * GitHub-style credential is an HMAC over exactly the bytes that arrived.
+ *
+ * Status codes are chosen for the two kinds of caller. A pipeline's
+ * `curl --fail` must fail exactly when Hexis is not in sync; a webhook host
+ * retries 5xx and gives up on 4xx:
+ *
+ *   200  every branch updated, already current, or not cloned here
+ *   409  a branch has a CONFLICT: Hexis-side commits clash with the host.
+ *        Automatic recovery is queued, but the branch is not in sync at the
+ *        time of the answer; the body's `error` names the files. A retry
+ *        answers 200 once recovery (or a person) has cleared it.
+ *   503  a branch could not be pulled (origin unreachable, credential
+ *        refused) — retriable. Also: no sync secret configured.
+ *   401  missing or wrong credential
+ *   400  a branch name git would refuse, or a body that is not JSON
+ */
+export interface KbSyncRouteDeps {
+    kbSync: IKbSyncService;
+    /** The configured secret, read per request so a setup-screen save applies at once. */
+    syncSecret: () => string;
+    authService: {
+        verifyToken(token: string): {
+            userId: string;
+            email: string;
+        };
+    };
+    adminAccess: IAdminAccessService;
+}
+/**
+ * Stamped on EVERY response this router writes. The endpoint answers 503 for
+ * an ordinary result (a branch could not be pulled), and a reverse proxy
+ * answers 503 when the backend is down; by status alone the browser cannot
+ * tell them apart, and it must — one is a line on the page, the other the
+ * maintenance overlay. A proxy standing in for a dead upstream never sets
+ * this header. Exposed to cross-origin callers in `create-core-server.ts`.
+ */
+export declare const SYNC_RESPONSE_HEADER = "X-Hexis-Sync";
+export declare const SYNC_RESPONSE_MARKER = "result";
+/**
+ * Whether a request path belongs to this router and must reach it with its
+ * body UNPARSED. The server's global JSON parser consults this: once that
+ * parser has read the stream, `express.raw` below sees nothing and the
+ * signature credential has no bytes to verify. Both routes share the check,
+ * so the branch form (`/api/sync/<branch>`) is covered as well as the bare
+ * one — an exact-path exemption used to protect only the latter.
+ */
+export declare function isSyncRawBodyPath(path: string): boolean;
+export declare function httpStatusFor(result: SyncResult): 200 | 409 | 503;
+export declare function createKbSyncRoutes(deps: KbSyncRouteDeps): express.Router;
+//# sourceMappingURL=kb-sync.routes.d.ts.map

package/dist/modules/kb-sync/kb-sync.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-sync.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-sync/kb-sync.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,cAAc,CAAC;IACvB,sFAAsF;IACtF,UAAU,EAAE,MAAM,MAAM,CAAC;IACzB,WAAW,EAAE;QAAE,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAC/E,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAKD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,iBAAiB,CAAC;AACnD,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CASvD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAIjE;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAsGxE"}

package/dist/modules/kb-sync/kb-sync.routes.js

@@ -0,0 +1,135 @@
+import express from 'express';
+import { assertValidBranchName } from '../kb-fs/branch-name.js';
+import { parseSyncPayload } from './sync-payload.js';
+import { verifySyncCredential } from './sync-auth.js';
+/** Cap on a webhook body. ADO's PR payloads run to a few hundred KB. */
+const BODY_LIMIT = '2mb';
+/**
+ * Stamped on EVERY response this router writes. The endpoint answers 503 for
+ * an ordinary result (a branch could not be pulled), and a reverse proxy
+ * answers 503 when the backend is down; by status alone the browser cannot
+ * tell them apart, and it must — one is a line on the page, the other the
+ * maintenance overlay. A proxy standing in for a dead upstream never sets
+ * this header. Exposed to cross-origin callers in `create-core-server.ts`.
+ */
+export const SYNC_RESPONSE_HEADER = 'X-Hexis-Sync';
+export const SYNC_RESPONSE_MARKER = 'result';
+/**
+ * Whether a request path belongs to this router and must reach it with its
+ * body UNPARSED. The server's global JSON parser consults this: once that
+ * parser has read the stream, `express.raw` below sees nothing and the
+ * signature credential has no bytes to verify. Both routes share the check,
+ * so the branch form (`/api/sync/<branch>`) is covered as well as the bare
+ * one — an exact-path exemption used to protect only the latter.
+ */
+export function isSyncRawBodyPath(path) {
+    // Case-insensitive, because Express routing is: `/api/Sync` reaches this
+    // router, and if this check said no the global parser would eat the body
+    // first. On either form a signed call would then 401 (no bytes to verify).
+    // On the bare form a bearer call would silently sync every clone, since a
+    // body that is no longer a Buffer parses as "no body"; the branch form is
+    // unaffected there, its branch comes from the URL.
+    const lower = path.toLowerCase();
+    return lower === '/api/sync' || lower.startsWith('/api/sync/');
+}
+export function httpStatusFor(result) {
+    if (result.results.some((r) => r.outcome === 'conflict'))
+        return 409;
+    if (result.results.some((r) => r.outcome === 'error'))
+        return 503;
+    return 200;
+}
+export function createKbSyncRoutes(deps) {
+    const router = express.Router();
+    const rawBody = express.raw({ type: () => true, limit: BODY_LIMIT });
+    /**
+     * Everything both routes share: the credential check, then the sync and
+     * its answer. `select` turns the request into the branches to sync, or
+     * sends its own 400 and returns null.
+     */
+    async function handle(req, res, select) {
+        res.setHeader(SYNC_RESPONSE_HEADER, SYNC_RESPONSE_MARKER);
+        const raw = Buffer.isBuffer(req.body) ? req.body : undefined;
+        const auth = await verifySyncCredential({
+            secret: deps.syncSecret(),
+            authorization: header(req, 'authorization'),
+            gitlabToken: header(req, 'x-gitlab-token'),
+            hubSignature: header(req, 'x-hub-signature-256'),
+            rawBody: raw,
+        }, {
+            verifyJwt: (token) => {
+                try {
+                    return { email: deps.authService.verifyToken(token).email };
+                }
+                catch {
+                    return null;
+                }
+            },
+            isAdmin: (email) => deps.adminAccess.isAdmin(email),
+        });
+        if (!auth.ok) {
+            if (auth.status === 401)
+                res.setHeader('WWW-Authenticate', 'Bearer realm="hexis-sync"');
+            res.status(auth.status).json({ error: auth.message });
+            return;
+        }
+        const selection = select();
+        if (!selection)
+            return;
+        const who = auth.credential.kind === 'admin-session' ? auth.credential.email : auth.credential.kind;
+        const asked = selection.branches === 'all' ? 'all cloned branches' : selection.branches.join(', ') || '(none)';
+        try {
+            const result = await deps.kbSync.sync({ branches: selection.branches, by: who });
+            const summary = result.results.map((r) => `${r.branch}=${r.outcome}`).join(' ');
+            console.log(`[sync] by ${who} via ${selection.source} for ${asked}: ${result.status} ${summary}`);
+            res.status(httpStatusFor(result)).json(result);
+        }
+        catch (err) {
+            console.error('[sync] unhandled error:', err);
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    }
+    // The branch in the URL. A wildcard rather than `:branch` so a branch with
+    // slashes (`ali/new-skill`) works spelled either way — as segments or
+    // percent-encoded as one.
+    router.post('/sync/*branch', rawBody, (req, res) => handle(req, res, () => {
+        const param = req.params.branch;
+        const branch = (Array.isArray(param) ? param.join('/') : String(param ?? '')).trim();
+        try {
+            assertValidBranchName(branch);
+        }
+        catch {
+            res.status(400).json({ error: `Not a valid branch name: ${branch}` });
+            return null;
+        }
+        return { source: 'path', branches: [branch] };
+    }));
+    router.post('/sync', rawBody, (req, res) => handle(req, res, () => {
+        const raw = Buffer.isBuffer(req.body) ? req.body : undefined;
+        let body = undefined;
+        if (raw && raw.length > 0) {
+            try {
+                body = JSON.parse(raw.toString('utf8'));
+            }
+            catch {
+                res.status(400).json({ error: 'The request body is not valid JSON.' });
+                return null;
+            }
+        }
+        const parsed = parseSyncPayload(body);
+        if (parsed.invalid.length > 0) {
+            res.status(400).json({
+                error: `Not a valid branch name: ${parsed.invalid.join(', ')}`,
+                invalid: parsed.invalid,
+            });
+            return null;
+        }
+        return { source: parsed.source, branches: parsed.branches };
+    }));
+    return router;
+}
+function header(req, name) {
+    const v = req.headers[name];
+    return typeof v === 'string' ? v : undefined;
+}
+//# sourceMappingURL=kb-sync.routes.js.map

package/dist/modules/kb-sync/kb-sync.routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-sync.routes.js","sourceRoot":"","sources":["../../../src/modules/kb-sync/kb-sync.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,EAAE,gBAAgB,EAA0B,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AA2CtD,wEAAwE;AACxE,MAAM,UAAU,GAAG,KAAK,CAAC;AAEzB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,cAAc,CAAC;AACnD,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,yEAAyE;IACzE,yEAAyE;IACzE,2EAA2E;IAC3E,0EAA0E;IAC1E,0EAA0E;IAC1E,mDAAmD;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,OAAO,KAAK,KAAK,WAAW,IAAI,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAkB;IAC9C,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC;QAAE,OAAO,GAAG,CAAC;IACrE,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC;QAAE,OAAO,GAAG,CAAC;IAClE,OAAO,GAAG,CAAC;AACb,CAAC;AAID,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAEhC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IAErE;;;;OAIG;IACH,KAAK,UAAU,MAAM,CACnB,GAAoB,EACpB,GAAqB,EACrB,MAA8B;QAE9B,GAAG,CAAC,SAAS,CAAC,oBAAoB,EAAE,oBAAoB,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAuB,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAEjF,MAAM,IAAI,GAAG,MAAM,oBAAoB,CACrC;YACE,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE;YACzB,aAAa,EAAE,MAAM,CAAC,GAAG,EAAE,eAAe,CAAC;YAC3C,WAAW,EAAE,MAAM,CAAC,GAAG,EAAE,gBAAgB,CAAC;YAC1C,YAAY,EAAE,MAAM,CAAC,GAAG,EAAE,qBAAqB,CAAC;YAChD,OAAO,EAAE,GAAG;SACb,EACD;YACE,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE;gBACnB,IAAI,CAAC;oBACH,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC;gBAC9D,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;YACD,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC;SACpD,CACF,CAAC;QACF,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG;gBAAE,GAAG,CAAC,SAAS,CAAC,kBAAkB,EAAE,2BAA2B,CAAC,CAAC;YACxF,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;YACtD,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,SAAS;YAAE,OAAO;QAEvB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QACpG,MAAM,KAAK,GACT,SAAS,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC;QACnG,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YACjF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAChF,OAAO,CAAC,GAAG,CAAC,aAAa,GAAG,QAAQ,SAAS,CAAC,MAAM,QAAQ,KAAK,KAAK,MAAM,CAAC,MAAM,IAAI,OAAO,EAAE,CAAC,CAAC;YAClG,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,GAAG,CAAC,CAAC;YAC9C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,sEAAsE;IACtE,0BAA0B;IAC1B,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CACjD,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;QACpB,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,MAAiB,CAAC;QAC3C,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACrF,IAAI,CAAC;YACH,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,4BAA4B,MAAM,EAAE,EAAE,CAAC,CAAC;YACtE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;IAChD,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CACzC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;QACpB,MAAM,GAAG,GAAuB,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QACjF,IAAI,IAAI,GAAY,SAAS,CAAC;QAC9B,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YAC1C,CAAC;YAAC,MAAM,CAAC;gBACP,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,qCAAqC,EAAE,CAAC,CAAC;gBACvE,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACnB,KAAK,EAAE,4BAA4B,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBAC9D,OAAO,EAAE,MAAM,CAAC,OAAO;aACxB,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC9D,CAAC,CAAC,CACH,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,MAAM,CAAC,GAAoB,EAAE,IAAY;IAChD,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC"}

package/dist/modules/kb-sync/kb-sync.service.d.ts

@@ -0,0 +1,45 @@
+import type { IKbSyncService, LastSync, SyncRequest, SyncResult, SyncWorkflowPort, SyncWorkspacePort } from './kb-sync.interface.js';
+/**
+ * Runs remote syncs one at a time and folds everything that arrives
+ * mid-run into ONE follow-up.
+ *
+ * Why coalesce: a git host fires several hooks for one event — Azure DevOps
+ * sends a push, a PR-updated and a PR-merged within a second of each other —
+ * and each would otherwise queue behind the workspace mutex to pull the same
+ * tree again. The follow-up pulls the union of every request that arrived
+ * during the run (an "all" absorbs the rest).
+ *
+ * But each caller is answered for the branches IT asked about. The endpoint
+ * promises to fail exactly when the caller's branch is not in sync; a hook
+ * for branch A answered with branch B's conflict would fail the wrong
+ * subscription — and a host that disables subscriptions after repeated
+ * failures would disable the wrong one.
+ *
+ * Branches are pulled sequentially. N is small (only cloned branches count),
+ * the per-clone mutex serialises them anyway, and one slow origin round-trip
+ * at a time keeps the process calm during a burst.
+ */
+export declare class KbSyncService implements IKbSyncService {
+    private readonly workflow;
+    private readonly workspaces;
+    private readonly now;
+    private inFlight;
+    /** Everyone who arrived mid-run, each with what they asked for. */
+    private waiters;
+    private last;
+    constructor(workflow: SyncWorkflowPort, workspaces: SyncWorkspacePort, now?: () => number);
+    lastSync(): LastSync | null;
+    sync(request: SyncRequest): Promise<SyncResult>;
+    private start;
+    /**
+     * Run ONE follow-up for everyone who arrived during the last run: the union
+     * of their branches, then each waiter answered from its own share of the
+     * result — never from another caller's branches.
+     */
+    private drain;
+    /** The part of a union run that answers one caller: its branches, and its status over them. */
+    private static subsetFor;
+    private static statusOf;
+    private run;
+}
+//# sourceMappingURL=kb-sync.service.d.ts.map

package/dist/modules/kb-sync/kb-sync.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-sync.service.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-sync/kb-sync.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,QAAQ,EACR,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAc,YAAW,cAAc;IAYhD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAbtB,OAAO,CAAC,QAAQ,CAAiC;IACjD,mEAAmE;IACnE,OAAO,CAAC,OAAO,CAKP;IACR,OAAO,CAAC,IAAI,CAAyB;gBAGlB,QAAQ,EAAE,gBAAgB,EAC1B,UAAU,EAAE,iBAAiB,EAC7B,GAAG,GAAE,MAAM,MAAyB;IAGvD,QAAQ,IAAI,QAAQ,GAAG,IAAI;IAI3B,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAW/C,OAAO,CAAC,KAAK;IASb;;;;OAIG;IACH,OAAO,CAAC,KAAK;IA2Bb,+FAA+F;IAC/F,OAAO,CAAC,MAAM,CAAC,SAAS;IAWxB,OAAO,CAAC,MAAM,CAAC,QAAQ;YAWT,GAAG;CAyElB"}