@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/dist/modules/kb-fs/repo-path.js

@@ -6,9 +6,17 @@ import { WorkflowValidationError } from '../../shared/domain-errors.js';
  * A workspace directory holds the git clone as `<kbDirName>/` (plus transient
  * scratch such as `tmp/`). The agent filesystem, the lock keys and the human
  * editor all speak WORKSPACE-relative paths, so a path reaches git only when
- * it starts with that folder. `KnowledgeBase/Foo.md` on its own is not a
- * shorthand for `knowledge-base/KnowledgeBase/Foo.md`: it is a different
- * location, beside the clone, that nothing commits and nothing pushes.
+ * it starts with that folder — and `KnowledgeBase/Foo.md` on its own names a
+ * location BESIDE the clone, that nothing commits and nothing pushes.
+ *
+ * Which is why nothing on this platform resolves a workspace path for itself.
+ * Every accepted path goes through {@link normalizeWorkspacePath} first, which
+ * places it inside the clone; {@link assertInsideRepo} is then the check that
+ * what came out really is in there. A route or a tool that resolved a path of
+ * its own would be the drift this file exists to prevent — a `KnowledgeBase/`
+ * folder, a `Plugins/` folder and eight uploaded documents sitting beside a
+ * staging checkout is what it looked like the last time two spellings of this
+ * rule were allowed to exist.
  */
 /**
  * True when `wsPath` is the repository folder or lies under it.
@@ -36,6 +44,10 @@ export function isInsideRepo(wsPath, kbDirName) {
  * switch on it, plus the same corrected path on its own, for a consumer
  * that cannot rely on the message surviving intact (the pending-commits
  * worker stores a sanitized, truncated copy).
+ *
+ * This is the check AFTER {@link normalizeWorkspacePath}, not instead of it:
+ * the normaliser has already placed an unprefixed path inside the repository,
+ * so what reaches here and still fails is a path no spelling can rescue.
  */
 export function assertInsideRepo(wsPath, kbDirName) {
     if (isInsideRepo(wsPath, kbDirName))
@@ -51,4 +63,184 @@ export function assertInsideRepo(wsPath, kbDirName) {
     throw new WorkflowValidationError(`"${wsPath}" is outside the knowledge base repository: paths are workspace-relative, must start with "${kbDirName}/" and may not contain "." or ".." segments or backslashes. ` +
         `Use "${corrected}" instead. A file written without that prefix lands beside the repository, where it is never committed or pushed.`, { kind: 'path-outside-repo', path: wsPath, kbDirName, corrected });
 }
+/**
+ * THE normaliser: any accepted workspace path as a REPOSITORY path.
+ *
+ * Three cases, and only three:
+ *  - Already under `<kbDirName>/` (the root-anchored `/<kbDirName>/…` form the
+ *    app's Copy path gives included, because that is the form a Markdown link
+ *    resolves from and people paste the same text into an agent): returned as
+ *    it is.
+ *  - Anything else: placed under `<kbDirName>/`. `KnowledgeBase/Report.md` is
+ *    not a location beside the clone any more — it is the page of that name
+ *    inside it, which is what every caller that ever sent it meant.
+ *  - `.` or `..` segments, a backslash, or an absolute path: refused, with
+ *    {@link assertInsideRepo}'s message. Those are not spellings of a
+ *    repository path, they are attempts to leave one, and a normaliser that
+ *    "fixed" them would launder a traversal into a write.
+ *
+ * A leading `./` and repeated slashes are stripped rather than refused — they
+ * are spellings of one path, which is what `canonicalRelativePath` has always
+ * said, and ONE identity per file is what the write turns and the lock rows
+ * coordinate on. Every other `.` segment is a refusal.
+ */
+export function normalizeWorkspacePath(wsPath, kbDirName) {
+    /** The refusal, with {@link assertInsideRepo}'s message and corrected path. */
+    const refuse = () => {
+        assertInsideRepo(wsPath, kbDirName);
+        // Unreachable: everything that gets here fails `isInsideRepo` by
+        // construction. Spelled out rather than trusted, so a future edit that
+        // breaks the correspondence fails loudly instead of returning a bad path.
+        throw new Error(`unreachable: "${wsPath}" was refused but is inside the repository`);
+    };
+    // A non-string arrives from JSON, not from TypeScript: refuse it as the path
+    // it is not, rather than crash on `.startsWith`.
+    if (typeof wsPath !== 'string')
+        refuse();
+    // `\` separates segments on Windows, so `foo\..\..` is a climb this cannot
+    // read. Refused before anything is collapsed, never rewritten to `/`.
+    if (wsPath.includes('\\'))
+        refuse();
+    // The root-anchored form, and ONLY for the repository folder: `/<kbDirName>/…`
+    // is what the app's Copy path gives (it is the form a Markdown link resolves
+    // from) and names the same workspace path. `/tmp/x` and `//x` are not that
+    // form; they stay absolute, which is a refusal — `path.resolve` lets an
+    // absolute path win over the workspace dir, so laundering one would be the
+    // whole bug.
+    const rooted = wsPath === `/${kbDirName}` || wsPath.startsWith(`/${kbDirName}/`) ? wsPath.slice(1) : wsPath;
+    // `C:/Windows/System32` and the drive-relative `C:x` are absolute too, and
+    // carry neither a leading slash nor a backslash — so they are named here
+    // rather than left to the two checks above. On Windows `path.resolve` reads
+    // the drive and the workspace dir loses; refused, like every other absolute.
+    if (rooted.startsWith('/') || /^[A-Za-z]:/.test(rooted))
+        refuse();
+    // A leading `./` and repeated slashes are SPELLINGS, not paths: `x/a.md`,
+    // `./x/a.md` and `x//a.md` are one file, which is what `canonicalRelativePath`
+    // has always said and what the write turns and the lock rows coordinate on.
+    // Collapsed here so one identity comes out whichever way it went in.
+    const segments = rooted.replace(/^\.\//, '').split('/').filter((segment) => segment !== '');
+    // `.` deeper in, and `..` anywhere, are not spellings of the same path —
+    // `knowledge-base/Public/../Locked/x.md` is judged under one folder and
+    // written in another — so they are refused rather than resolved.
+    if (segments.length === 0 || segments.some((segment) => segment === '.' || segment === '..'))
+        refuse();
+    // A directory path may carry a single trailing slash; keep the caller's.
+    const canonical = segments.join('/') + (rooted.endsWith('/') ? '/' : '');
+    return segments[0] === kbDirName ? canonical : `${kbDirName}/${canonical}`;
+}
+/**
+ * Refuse a repository-root folder named exactly `<kbDirName>`.
+ *
+ * Consequence of normalising rather than refusing: `knowledge-base/x` has to
+ * mean ONE thing, and it means the repository's own `x`. A repository folder
+ * called `knowledge-base` would therefore be ambiguous — `knowledge-base/x`
+ * is read as the checkout's `x`, and the folder is reachable only by spelling
+ * the prefix twice — so the name is reserved at the root rather than left
+ * ambiguous. An existing one is left alone: nothing here deletes it, and a
+ * delete or a move OUT of it stays possible so an operator can clean it up.
+ *
+ * Case-INSENSITIVELY, whatever this host's filesystem does. On macOS or
+ * Windows `Knowledge-Base/` and `knowledge-base/` are one folder, so a
+ * case variant would create exactly the unreachable folder this refuses; on
+ * Linux they are two, and refusing the variant costs a name nobody should
+ * want at the root of a repository that is cloned onto all three.
+ */
+export function assertRepoRootNameFree(wsPath, kbDirName) {
+    const segments = String(wsPath).replace(/\/+$/, '').split('/');
+    const reserved = kbDirName.toLowerCase();
+    if (segments[0] !== kbDirName || segments[1]?.toLowerCase() !== reserved)
+        return;
+    throw new WorkflowValidationError(`"${segments[1]}" is reserved: it is the checkout folder's name. A folder of that name at the repository root ` +
+        `could never be reached — every workspace path starting with "${kbDirName}/" names the checkout itself — so it cannot be created, moved to or renamed to.` +
+        // Said only when the caller spelled it differently, so the ordinary
+        // refusal stays one sentence about one name.
+        (segments[1] === kbDirName ? '' : ` A different case is the same folder wherever the repository is cloned onto a case-insensitive filesystem, so "${kbDirName}" is refused in every spelling.`), { kind: 'reserved-root-name', path: wsPath, kbDirName });
+}
+/**
+ * {@link assertRepoRootNameFree} over the arguments of a tool call that CREATES
+ * something — `keys` names the inputs that are destinations (`path` of a
+ * write or a mkdir, `dest` of a copy or a move, `destination` of an unzip, and
+ * `files` for each `files[].path` of a batch write). Never a source: a move or
+ * a delete OUT of an existing reserved folder is how it gets cleaned up.
+ *
+ * The routes enforce the reservation inside `WorkspaceService`; the MCP tools
+ * write through the locking filesystem, which never enters that service, so
+ * this is where the same rule meets them — after {@link normalizePathArgs},
+ * on the normalised path.
+ */
+export function assertRepoRootNameFreeArgs(args, kbDirName, keys) {
+    for (const key of keys) {
+        if (key === 'files') {
+            if (!Array.isArray(args.files))
+                continue;
+            for (const f of args.files) {
+                const p = f && typeof f === 'object' ? f.path : undefined;
+                if (typeof p === 'string')
+                    assertRepoRootNameFree(p, kbDirName);
+            }
+            continue;
+        }
+        const value = args[key];
+        if (typeof value === 'string' && value.length > 0)
+            assertRepoRootNameFree(value, kbDirName);
+    }
+}
+/**
+ * Refuse a checkout folder name that is also one of the repository's own root
+ * names (the knowledge, skills or plugins root, or the agent guide's file).
+ *
+ * The normaliser reads a path whose first segment is `<kbDirName>` as already
+ * inside the checkout. Were the checkout folder called `KnowledgeBase` — the
+ * default name of the knowledge root — `KnowledgeBase/Report.md` would mean
+ * the checkout's OWN `Report.md`, never the page under the knowledge root, and
+ * {@link assertRepoRootNameFree} would refuse the knowledge root itself as a
+ * reserved name. Both settings are the operator's to choose, so the collision
+ * is refused at boot, by name, rather than discovered one misplaced write at a
+ * time. Case-insensitive, for the same reason the reservation is.
+ */
+export function assertKbDirNameFree(kbDirName, layout) {
+    const taken = kbDirName.toLowerCase();
+    const collision = [
+        ['knowledgeBaseDir', layout.knowledgeBaseDir],
+        ['skillsDir', layout.skillsDir],
+        ['pluginsDir', layout.pluginsDir],
+        ['agentsFile', layout.agentsFile],
+    ].find(([, name]) => name.toLowerCase() === taken);
+    if (!collision)
+        return;
+    throw new Error(`The checkout folder name (kbDirName / KB_DIR_NAME) is "${kbDirName}", which is also the repository's ` +
+        `${collision[0]} ("${collision[1]}"). Every workspace path starting with that name is read as the checkout itself, ` +
+        `so the repository's own "${collision[1]}" could never be named. Give the checkout folder a name none of the ` +
+        `repository's root folders or files use.`);
+}
+/** The tool inputs that carry a workspace path. */
+const PATH_ARG_KEYS = ['path', 'src', 'dest', 'destination'];
+/**
+ * {@link normalizeWorkspacePath} over a tool call's arguments: every
+ * path-shaped input, including each `files[].path` of a batch write. Returns a
+ * copy. This is where the MCP surface meets the normaliser — one call, before
+ * any handler runs, so no tool keeps a resolver of its own.
+ *
+ * `skip` is for the one input that is not a workspace path at all: `read_file`
+ * also takes a `__tool_chain_spill__/…` ref, which belongs to no workspace and
+ * must reach the handler as written. An absent or non-string value is left
+ * alone too — the handler's own required-argument message is better than a
+ * path refusal about `undefined`.
+ */
+export function normalizePathArgs(args, kbDirName, skip) {
+    const one = (value) => typeof value !== 'string' || value.length === 0 || skip?.(value)
+        ? value
+        : normalizeWorkspacePath(value, kbDirName);
+    const out = { ...args };
+    for (const key of PATH_ARG_KEYS) {
+        if (key in out)
+            out[key] = one(out[key]);
+    }
+    if (Array.isArray(out.files)) {
+        out.files = out.files.map((f) => f && typeof f === 'object' && 'path' in f
+            ? { ...f, path: one(f.path) }
+            : f);
+    }
+    return out;
+}
 //# sourceMappingURL=repo-path.js.map

package/dist/modules/kb-fs/repo-path.js.map

@@ -1 +1 @@
-{"version":3,"file":"repo-path.js","sourceRoot":"","sources":["../../../src/modules/kb-fs/repo-path.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAExE;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,SAAiB;IAC5D,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACtE,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC;AAC5F,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,SAAiB;IAChE,IAAI,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC;QAAE,OAAO;IAC5C,0EAA0E;IAC1E,4EAA4E;IAC5E,yEAAyE;IACzE,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK;SAC1B,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;SACxE,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;SAC7B,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvB,MAAM,SAAS,GAAG,YAAY,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,UAAU,EAAE,CAAC;IAClG,MAAM,IAAI,uBAAuB,CAC/B,IAAI,MAAM,8FAA8F,SAAS,8DAA8D;QAC7K,QAAQ,SAAS,mHAAmH,EACtI,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,CAClE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"repo-path.js","sourceRoot":"","sources":["../../../src/modules/kb-fs/repo-path.ts"],"names":[],"mappings":"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"}

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;AAI9B,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,137 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+const log = logger('sync');
+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(' ');
+            log.info(`by ${who} via ${selection.source} for ${asked}: ${result.status} ${summary}`);
+            res.status(httpStatusFor(result)).json(result);
+        }
+        catch (err) {
+            log.error('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":"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"}

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":"AAKA,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"}