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

package/dist/shared/fs-walk.js

@@ -1,34 +1,42 @@
-import path from 'node:path';
-import fs from 'node:fs/promises';
+import { walkKb, isSkippedEntry } from './kb-walk.js';
+export { isSkippedEntry };
 /**
- * The ONE recursive file walk for catalog scanners: relative (`/`-separated,
- * sorted) paths of files under `root` whose basename matches. A missing root
- * yields `[]`; dot-entries (incl. `.git`) are skipped. Scanners with different
- * semantics (the skills scanner's stop-at-skill-folder walk, the access
- * resolver's dir chains) deliberately keep their own walks.
+ * The file listing catalog scanners want, on top of {@link walkKb}: relative
+ * (`/`-separated, sorted) paths of files under `root` whose basename matches.
+ * A missing root yields `[]`; skipped entries are never entered.
+ *
+ * A directory that cannot be listed is SKIPPED by default — right for a
+ * catalog, which shows what it can. A caller that must see EVERYTHING or
+ * nothing passes `strict`, and the listing throws a {@link WalkError} naming
+ * the directory instead: a list with a hole in it is not a list of every
+ * file, and the caller can say WHICH hole rather than pass a raw errno up.
  */
-export async function walkFiles(root, match) {
+export async function walkFiles(root, match, opts = {}) {
     const out = [];
-    const walk = async (dir, rel) => {
-        let entries;
-        try {
-            entries = await fs.readdir(dir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            if (entry.name.startsWith('.'))
-                continue;
-            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
-            if (entry.isDirectory())
-                await walk(path.join(dir, entry.name), childRel);
-            else if (entry.isFile() && match(entry.name))
-                out.push(childRel);
-        }
-    };
-    await walk(root, '');
+    await walkKb(root, [
+        {
+            onFile(dir, name) {
+                if (match(name))
+                    out.push(dir ? `${dir}/${name}` : name);
+            },
+            onHole(rel, err) {
+                if (opts.strict)
+                    throw new WalkError(rel, err);
+            },
+        },
+    ]);
     out.sort();
     return out;
 }
+/** A strict listing's refusal: the directory (relative to the root, `''` for the root itself) it could not list. */
+export class WalkError extends Error {
+    relDir;
+    cause;
+    constructor(relDir, cause) {
+        super(`${relDir || '.'} could not be listed — ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.relDir = relDir;
+        this.cause = cause;
+        this.name = 'WalkError';
+    }
+}
 //# sourceMappingURL=fs-walk.js.map

package/dist/shared/fs-walk.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs-walk.js","sourceRoot":"","sources":["../../src/shared/fs-walk.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAElC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY,EAAE,KAAoC;IAChF,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,KAAK,EAAE,GAAW,EAAE,GAAW,EAAiB,EAAE;QAC7D,IAAI,OAAmC,CAAC;QACxC,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS;YACzC,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;YAC3D,IAAI,KAAK,CAAC,WAAW,EAAE;gBAAE,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;iBACrE,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnE,CAAC;IACH,CAAC,CAAC;IACF,MAAM,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACrB,GAAG,CAAC,IAAI,EAAE,CAAC;IACX,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"fs-walk.js","sourceRoot":"","sources":["../../src/shared/fs-walk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAY,EACZ,KAAoC,EACpC,OAA6B,EAAE;IAE/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,MAAM,CAAC,IAAI,EAAE;QACjB;YACE,MAAM,CAAC,GAAG,EAAE,IAAI;gBACd,IAAI,KAAK,CAAC,IAAI,CAAC;oBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC3D,CAAC;YACD,MAAM,CAAC,GAAG,EAAE,GAAG;gBACb,IAAI,IAAI,CAAC,MAAM;oBAAE,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACjD,CAAC;SACF;KACF,CAAC,CAAC;IACH,GAAG,CAAC,IAAI,EAAE,CAAC;IACX,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oHAAoH;AACpH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEvB;IACA;IAFX,YACW,MAAc,EACd,KAAc;QAEvB,KAAK,CAAC,GAAG,MAAM,IAAI,GAAG,0BAA0B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAHjG,WAAM,GAAN,MAAM,CAAQ;QACd,UAAK,GAAL,KAAK,CAAS;QAGvB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/shared/kb-walk.d.ts

@@ -0,0 +1,52 @@
+/**
+ * THE walk of a knowledge-base checkout.
+ *
+ * Every reader of the tree — the access resolver looking for rules, plugin
+ * discovery looking for manifests, a rename looking for grants, the catalog
+ * scanners — used to carry a recursive `readdir` loop of its own, each with
+ * its own skip list, its own idea of what an unreadable folder means and its
+ * own visiting order. Two loops that disagree on one of those are two
+ * answers to "what is in the tree", and every such disagreement was a bug.
+ *
+ * So there is one loop, and it decides three things once:
+ *
+ *   - WHAT IS SKIPPED: {@link isSkippedEntry} — dot-entries (`.git`, a parked
+ *     delete) and vendored dependencies. Nothing else is pruned; a listener
+ *     that stops at a leaf of its own (a skill folder, a plugin folder)
+ *     simply ignores what lies beneath it.
+ *   - IN WHAT ORDER: each folder's entries in {@link comparePathComponents}
+ *     order, so "first by path" means the same thing to every listener.
+ *   - WHAT A HOLE IS: a folder that exists but could not be listed is
+ *     reported as an event and in the result — never thrown, never silently
+ *     skipped — so a reader can show what it saw and a writer can refuse.
+ *     A folder that vanished between listing and visiting is not a hole.
+ *
+ * Listeners see the same events in the same order; what each makes of them
+ * is its own business (`.bevelignore` included — the explorer honours it,
+ * the resolver must not, so it is a listener's decision, not the walk's).
+ */
+export declare function isSkippedEntry(name: string): boolean;
+/** A directory entry as the walk presents it: a name and what it is. */
+export interface WalkedEntry {
+    name: string;
+    isDirectory(): boolean;
+    isFile(): boolean;
+}
+export interface KbWalkListener {
+    /** A folder was listed. `rel` is repo-relative (`''` for the root); `entries` are its children, skipped ones removed, in walk order. */
+    onDir?(rel: string, entries: readonly WalkedEntry[]): void | Promise<void>;
+    /** A file was seen. `dir` is its folder (`''` for the root), `name` its basename. */
+    onFile?(dir: string, name: string): void | Promise<void>;
+    /** A folder that exists but could not be listed. */
+    onHole?(rel: string, err: unknown): void | Promise<void>;
+}
+export interface KbWalkResult {
+    /** Every folder that could not be listed, repo-relative (`''` for the root). */
+    holes: string[];
+}
+/**
+ * Walk the checkout at `root`, driving every listener from one traversal.
+ * A missing root is an empty tree. Listener errors propagate untouched.
+ */
+export declare function walkKb(root: string, listeners: readonly KbWalkListener[]): Promise<KbWalkResult>;
+//# sourceMappingURL=kb-walk.d.ts.map

package/dist/shared/kb-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-walk.d.ts","sourceRoot":"","sources":["../../src/shared/kb-walk.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,IAAI,OAAO,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,wIAAwI;IACxI,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,qFAAqF;IACrF,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,oDAAoD;IACpD,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,cAAc,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAiCtG"}

package/dist/shared/kb-walk.js

@@ -0,0 +1,76 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { isAbsence } from './fs-errors.js';
+import { comparePathComponents } from './path-order.js';
+/**
+ * THE walk of a knowledge-base checkout.
+ *
+ * Every reader of the tree — the access resolver looking for rules, plugin
+ * discovery looking for manifests, a rename looking for grants, the catalog
+ * scanners — used to carry a recursive `readdir` loop of its own, each with
+ * its own skip list, its own idea of what an unreadable folder means and its
+ * own visiting order. Two loops that disagree on one of those are two
+ * answers to "what is in the tree", and every such disagreement was a bug.
+ *
+ * So there is one loop, and it decides three things once:
+ *
+ *   - WHAT IS SKIPPED: {@link isSkippedEntry} — dot-entries (`.git`, a parked
+ *     delete) and vendored dependencies. Nothing else is pruned; a listener
+ *     that stops at a leaf of its own (a skill folder, a plugin folder)
+ *     simply ignores what lies beneath it.
+ *   - IN WHAT ORDER: each folder's entries in {@link comparePathComponents}
+ *     order, so "first by path" means the same thing to every listener.
+ *   - WHAT A HOLE IS: a folder that exists but could not be listed is
+ *     reported as an event and in the result — never thrown, never silently
+ *     skipped — so a reader can show what it saw and a writer can refuse.
+ *     A folder that vanished between listing and visiting is not a hole.
+ *
+ * Listeners see the same events in the same order; what each makes of them
+ * is its own business (`.bevelignore` included — the explorer honours it,
+ * the resolver must not, so it is a listener's decision, not the walk's).
+ */
+export function isSkippedEntry(name) {
+    return name.startsWith('.') || name === 'node_modules';
+}
+/**
+ * Walk the checkout at `root`, driving every listener from one traversal.
+ * A missing root is an empty tree. Listener errors propagate untouched.
+ */
+export async function walkKb(root, listeners) {
+    const holes = [];
+    const visit = async (abs, rel) => {
+        let listed;
+        try {
+            listed = await fs.readdir(abs, { withFileTypes: true });
+        }
+        catch (err) {
+            if (isAbsence(err)) {
+                // The root: a checkout without this tree, an empty walk. Deeper: a
+                // folder that vanished between listing and visiting — not a hole.
+                return;
+            }
+            holes.push(rel);
+            for (const l of listeners)
+                await l.onHole?.(rel, err);
+            return;
+        }
+        const entries = listed
+            .filter((e) => !isSkippedEntry(e.name) && (e.isDirectory() || e.isFile()))
+            .sort((a, b) => comparePathComponents(a.name, b.name));
+        for (const l of listeners)
+            await l.onDir?.(rel, entries);
+        for (const entry of entries) {
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await visit(path.join(abs, entry.name), childRel);
+            }
+            else {
+                for (const l of listeners)
+                    await l.onFile?.(rel, entry.name);
+            }
+        }
+    };
+    await visit(root, '');
+    return { holes };
+}
+//# sourceMappingURL=kb-walk.js.map

package/dist/shared/kb-walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-walk.js","sourceRoot":"","sources":["../../src/shared/kb-walk.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,cAAc,CAAC;AACzD,CAAC;AAuBD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAY,EAAE,SAAoC;IAC7E,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,MAAM,KAAK,GAAG,KAAK,EAAE,GAAW,EAAE,GAAW,EAAiB,EAAE;QAC9D,IAAI,MAAkC,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnB,mEAAmE;gBACnE,kEAAkE;gBAClE,OAAO;YACT,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAChB,KAAK,MAAM,CAAC,IAAI,SAAS;gBAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACtD,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAkB,MAAM;aAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;aACzE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,KAAK,MAAM,CAAC,IAAI,SAAS;YAAE,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACzD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;YAC3D,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;YACpD,CAAC;iBAAM,CAAC;gBACN,KAAK,MAAM,CAAC,IAAI,SAAS;oBAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACtB,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/shared/path-order.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The ONE ordering of repository paths: component by component, each
+ * component by `localeCompare`, a shorter path before its extensions. It is
+ * exactly the order a directory walk that sorts each level's entries visits
+ * them in — so a consumer that must agree with the walk on "first by path"
+ * (plugin discovery keeps the first of two folders sharing a slug; principal
+ * synthesis must pick the same one) sorts with this and nothing else. A
+ * whole-string `localeCompare` does not agree: it weighs the separator
+ * against the next character (`a-b/x` before `a/b/x`), the walk never does.
+ *
+ * TOTAL over distinct paths: two components the collation cannot tell apart
+ * (a precomposed `é` and its decomposed spelling) fall through to code-unit
+ * order, so no pair of distinct paths ever compares equal — an equal pair
+ * would leave "first" to whichever enumeration happened to run, and the two
+ * consumers could then pick different folders for one slug.
+ */
+export declare function comparePathComponents(a: string, b: string): number;
+//# sourceMappingURL=path-order.d.ts.map

package/dist/shared/path-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-order.d.ts","sourceRoot":"","sources":["../../src/shared/path-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CASlE"}

package/dist/shared/path-order.js

@@ -0,0 +1,35 @@
+/**
+ * The ONE ordering of repository paths: component by component, each
+ * component by `localeCompare`, a shorter path before its extensions. It is
+ * exactly the order a directory walk that sorts each level's entries visits
+ * them in — so a consumer that must agree with the walk on "first by path"
+ * (plugin discovery keeps the first of two folders sharing a slug; principal
+ * synthesis must pick the same one) sorts with this and nothing else. A
+ * whole-string `localeCompare` does not agree: it weighs the separator
+ * against the next character (`a-b/x` before `a/b/x`), the walk never does.
+ *
+ * TOTAL over distinct paths: two components the collation cannot tell apart
+ * (a precomposed `é` and its decomposed spelling) fall through to code-unit
+ * order, so no pair of distinct paths ever compares equal — an equal pair
+ * would leave "first" to whichever enumeration happened to run, and the two
+ * consumers could then pick different folders for one slug.
+ */
+export function comparePathComponents(a, b) {
+    const as = a.split('/');
+    const bs = b.split('/');
+    const n = Math.min(as.length, bs.length);
+    for (let i = 0; i < n; i++) {
+        const order = compareComponent(as[i], bs[i]);
+        if (order !== 0)
+            return order;
+    }
+    return as.length - bs.length;
+}
+/** One component against another: collation first, code units to break a tie. */
+function compareComponent(a, b) {
+    const order = a.localeCompare(b);
+    if (order !== 0)
+        return order;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+//# sourceMappingURL=path-order.js.map

package/dist/shared/path-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-order.js","sourceRoot":"","sources":["../../src/shared/path-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAS,EAAE,CAAS;IACxD,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,CAAC,CAAE,CAAC,CAAC;QAC/C,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;IAChC,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;AAC/B,CAAC;AAED,iFAAiF;AACjF,SAAS,gBAAgB,CAAC,CAAS,EAAE,CAAS;IAC5C,MAAM,KAAK,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/dist/shared/token-crypto.d.ts

@@ -8,9 +8,24 @@
  */
 export declare class TokenCrypto {
     private readonly key;
-    /** @param rawKey 32-byte key as hex (64 chars) or base64. */
-    constructor(rawKey: string);
+    /**
+     * @param rawKey 32-byte key as hex (64 chars) or base64.
+     * @param envVarName the environment variable the caller read `rawKey` from,
+     *   so a bad key is reported against the variable the operator actually has
+     *   to fix. Defaults to core's own `SECRETS_ENC_KEY` — every core consumer
+     *   reads that; an overlay bringing its own key (the SharePoint token
+     *   cache, connector configs) passes its own name.
+     */
+    constructor(rawKey: string, envVarName?: string);
     encrypt(plaintext: string): string;
     decrypt(blob: string): string;
 }
+/**
+ * Decode a key and refuse anything that is not exactly 32 bytes, blaming
+ * `envVarName`. Exported so boot-time config can validate the key THE MOMENT
+ * it knows which environment variable supplied it (`SECRETS_ENC_KEY` or a
+ * legacy fallback) — every later `new TokenCrypto(key)` with the default name
+ * is then safe, because a bad key never gets that far.
+ */
+export declare function assertKeyDecodesTo32Bytes(rawKey: string, envVarName: string): Buffer;
 //# sourceMappingURL=token-crypto.d.ts.map

package/dist/shared/token-crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-crypto.d.ts","sourceRoot":"","sources":["../../src/shared/token-crypto.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,6DAA6D;gBACjD,MAAM,EAAE,MAAM;IAW1B,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAQlC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAa9B"}
+{"version":3,"file":"token-crypto.d.ts","sourceRoot":"","sources":["../../src/shared/token-crypto.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B;;;;;;;OAOG;gBACS,MAAM,EAAE,MAAM,EAAE,UAAU,SAAoB;IAI1D,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAQlC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAa9B;AASD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CASpF"}

package/dist/shared/token-crypto.js

@@ -9,14 +9,16 @@ import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
  */
 export class TokenCrypto {
     key;
-    /** @param rawKey 32-byte key as hex (64 chars) or base64. */
-    constructor(rawKey) {
-        const key = decodeKey(rawKey);
-        if (key.length !== 32) {
-            throw new Error(`SHAREPOINT_TOKEN_ENC_KEY must decode to 32 bytes (got ${key.length}). ` +
-                'Generate one with: `node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'base64\'))"`.');
-        }
-        this.key = key;
+    /**
+     * @param rawKey 32-byte key as hex (64 chars) or base64.
+     * @param envVarName the environment variable the caller read `rawKey` from,
+     *   so a bad key is reported against the variable the operator actually has
+     *   to fix. Defaults to core's own `SECRETS_ENC_KEY` — every core consumer
+     *   reads that; an overlay bringing its own key (the SharePoint token
+     *   cache, connector configs) passes its own name.
+     */
+    constructor(rawKey, envVarName = 'SECRETS_ENC_KEY') {
+        this.key = assertKeyDecodesTo32Bytes(rawKey, envVarName);
     }
     encrypt(plaintext) {
         const iv = randomBytes(12);
@@ -46,4 +48,19 @@ function decodeKey(raw) {
         return Buffer.from(raw, 'hex');
     return Buffer.from(raw, 'base64');
 }
+/**
+ * Decode a key and refuse anything that is not exactly 32 bytes, blaming
+ * `envVarName`. Exported so boot-time config can validate the key THE MOMENT
+ * it knows which environment variable supplied it (`SECRETS_ENC_KEY` or a
+ * legacy fallback) — every later `new TokenCrypto(key)` with the default name
+ * is then safe, because a bad key never gets that far.
+ */
+export function assertKeyDecodesTo32Bytes(rawKey, envVarName) {
+    const key = decodeKey(rawKey);
+    if (key.length !== 32) {
+        throw new Error(`${envVarName} must decode to 32 bytes (got ${key.length}). ` +
+            'Generate one with: `node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'base64\'))"`.');
+    }
+    return key;
+}
 //# sourceMappingURL=token-crypto.js.map

package/dist/shared/token-crypto.js.map

@@ -1 +1 @@
-{"version":3,"file":"token-crypto.js","sourceRoot":"","sources":["../../src/shared/token-crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE5E;;;;;;;GAOG;AACH,MAAM,OAAO,WAAW;IACL,GAAG,CAAS;IAE7B,6DAA6D;IAC7D,YAAY,MAAc;QACxB,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;QAC9B,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,yDAAyD,GAAG,CAAC,MAAM,KAAK;gBACtE,uGAAuG,CAC1G,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,OAAO,CAAC,SAAiB;QACvB,MAAM,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,MAAM,GAAG,cAAc,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC3D,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC7E,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QAChC,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;IACvF,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACzF,CAAC;QACD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;QACrC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QACzF,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;QACnD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3G,CAAC;CACF;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,8EAA8E;IAC9E,sCAAsC;IACtC,IAAI,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAClE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AACpC,CAAC"}
+{"version":3,"file":"token-crypto.js","sourceRoot":"","sources":["../../src/shared/token-crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE5E;;;;;;;GAOG;AACH,MAAM,OAAO,WAAW;IACL,GAAG,CAAS;IAE7B;;;;;;;OAOG;IACH,YAAY,MAAc,EAAE,UAAU,GAAG,iBAAiB;QACxD,IAAI,CAAC,GAAG,GAAG,yBAAyB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,CAAC,SAAiB;QACvB,MAAM,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,MAAM,GAAG,cAAc,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC3D,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC7E,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QAChC,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;IACvF,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACzF,CAAC;QACD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;QACrC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QACzF,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;QACnD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3G,CAAC;CACF;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,8EAA8E;IAC9E,sCAAsC;IACtC,IAAI,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAClE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAc,EAAE,UAAkB;IAC1E,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,iCAAiC,GAAG,CAAC,MAAM,KAAK;YAC3D,uGAAuG,CAC1G,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/shared/ttl-cache.d.ts

@@ -8,9 +8,36 @@ export declare class TtlCache<T> {
     private readonly ttlMs;
     private readonly now;
     private entry;
+    /**
+     * Bumped by every `invalidate()`. A fetch carries the value this had when it
+     * started, and `set` refuses a value whose fetch straddled a drop — see there.
+     */
+    private generation;
     constructor(ttlMs: number, now?: () => number);
     get(): T | null;
-    set(value: T): void;
+    /**
+     * Take a token BEFORE starting the fetch whose result you will `set`.
+     *
+     * Every caller of this cache reads the disk across an `await`, and the whole
+     * point of `invalidate()` is that it fires during exactly that window: the
+     * merge pulls the new tree in while a catalog read that started on the old
+     * one is still in flight. Without a token that late `set` wins, and the cache
+     * holds the PRE-invalidation scan for a fresh full TTL — the drop silently
+     * undone, and the staleness it existed to prevent restored.
+     */
+    begin(): number;
+    /**
+     * Store a value fetched under `token`. Required, not optional: a caller that
+     * could forget it is a caller that reintroduces the race above, and there are
+     * few enough call sites to make the token cheap.
+     *
+     * A stale token means an `invalidate()` landed mid-fetch, so this value
+     * describes a tree that is already gone: it is DISCARDED rather than stored.
+     * The fetcher still returns it to its own caller — that read is merely as old
+     * as the moment it started, which is true of any read — but the next caller
+     * re-scans instead of inheriting it.
+     */
+    set(value: T, token: number): void;
     invalidate(): void;
 }
 //# sourceMappingURL=ttl-cache.d.ts.map

package/dist/shared/ttl-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ttl-cache.d.ts","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,CAAC;IAInB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJtB,OAAO,CAAC,KAAK,CAAyC;gBAGnC,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,MAAiB;IAG/C,GAAG,IAAI,CAAC,GAAG,IAAI;IAKf,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAInB,UAAU,IAAI,IAAI;CAGnB"}
+{"version":3,"file":"ttl-cache.d.ts","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,CAAC;IASnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IATtB,OAAO,CAAC,KAAK,CAAyC;IACtD;;;OAGG;IACH,OAAO,CAAC,UAAU,CAAK;gBAGJ,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,MAAiB;IAG/C,GAAG,IAAI,CAAC,GAAG,IAAI;IAKf;;;;;;;;;OASG;IACH,KAAK,IAAI,MAAM;IAIf;;;;;;;;;;OAUG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKlC,UAAU,IAAI,IAAI;CAInB"}

package/dist/shared/ttl-cache.js

@@ -8,6 +8,11 @@ export class TtlCache {
     ttlMs;
     now;
     entry = null;
+    /**
+     * Bumped by every `invalidate()`. A fetch carries the value this had when it
+     * started, and `set` refuses a value whose fetch straddled a drop — see there.
+     */
+    generation = 0;
     constructor(ttlMs, now = Date.now) {
         this.ttlMs = ttlMs;
         this.now = now;
@@ -17,11 +22,38 @@ export class TtlCache {
             return this.entry.value;
         return null;
     }
-    set(value) {
+    /**
+     * Take a token BEFORE starting the fetch whose result you will `set`.
+     *
+     * Every caller of this cache reads the disk across an `await`, and the whole
+     * point of `invalidate()` is that it fires during exactly that window: the
+     * merge pulls the new tree in while a catalog read that started on the old
+     * one is still in flight. Without a token that late `set` wins, and the cache
+     * holds the PRE-invalidation scan for a fresh full TTL — the drop silently
+     * undone, and the staleness it existed to prevent restored.
+     */
+    begin() {
+        return this.generation;
+    }
+    /**
+     * Store a value fetched under `token`. Required, not optional: a caller that
+     * could forget it is a caller that reintroduces the race above, and there are
+     * few enough call sites to make the token cheap.
+     *
+     * A stale token means an `invalidate()` landed mid-fetch, so this value
+     * describes a tree that is already gone: it is DISCARDED rather than stored.
+     * The fetcher still returns it to its own caller — that read is merely as old
+     * as the moment it started, which is true of any read — but the next caller
+     * re-scans instead of inheriting it.
+     */
+    set(value, token) {
+        if (token !== this.generation)
+            return;
         this.entry = { at: this.now(), value };
     }
     invalidate() {
         this.entry = null;
+        this.generation++;
     }
 }
 //# sourceMappingURL=ttl-cache.js.map

package/dist/shared/ttl-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"ttl-cache.js","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IAIA;IACA;IAJX,KAAK,GAAoC,IAAI,CAAC;IAEtD,YACmB,KAAa,EACb,MAAoB,IAAI,CAAC,GAAG;QAD5B,UAAK,GAAL,KAAK,CAAQ;QACb,QAAG,GAAH,GAAG,CAAyB;IAC5C,CAAC;IAEJ,GAAG;QACD,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QACnF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,KAAQ;QACV,IAAI,CAAC,KAAK,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC;IACzC,CAAC;IAED,UAAU;QACR,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;CACF"}
+{"version":3,"file":"ttl-cache.js","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IASA;IACA;IATX,KAAK,GAAoC,IAAI,CAAC;IACtD;;;OAGG;IACK,UAAU,GAAG,CAAC,CAAC;IAEvB,YACmB,KAAa,EACb,MAAoB,IAAI,CAAC,GAAG;QAD5B,UAAK,GAAL,KAAK,CAAQ;QACb,QAAG,GAAH,GAAG,CAAyB;IAC5C,CAAC;IAEJ,GAAG;QACD,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QACnF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;;;;;;;;;OAUG;IACH,GAAG,CAAC,KAAQ,EAAE,KAAa;QACzB,IAAI,KAAK,KAAK,IAAI,CAAC,UAAU;YAAE,OAAO;QACtC,IAAI,CAAC,KAAK,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC;IACzC,CAAC;IAED,UAAU;QACR,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,UAAU,EAAE,CAAC;IACpB,CAAC;CACF"}

package/kb-template/.bevelignore

@@ -22,4 +22,4 @@ CLAUDE.md
 **/access.md
 roles.yaml
 
-Plugins/
+{{pluginsDir}}/