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

package/src/shared/__tests__/ttl-cache.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { TtlCache } from '../ttl-cache.js';
+
+describe('TtlCache', () => {
+  it('serves a value until the TTL runs out, then stops', () => {
+    let now = 0;
+    const cache = new TtlCache<string>(1000, () => now);
+    cache.set('v', cache.begin());
+    expect(cache.get()).toBe('v');
+    now = 999;
+    expect(cache.get()).toBe('v');
+    now = 1000;
+    expect(cache.get()).toBeNull();
+  });
+
+  it('invalidate() drops the value immediately', () => {
+    const cache = new TtlCache<string>(1000, () => 0);
+    cache.set('v', cache.begin());
+    cache.invalidate();
+    expect(cache.get()).toBeNull();
+  });
+
+  /**
+   * The race the token exists for, and the one that made the merge fix a
+   * no-op in exactly the case it targeted: a catalog read starts on the
+   * pre-merge tree, the merge's pull lands and drops the cache, and the
+   * in-flight read then writes its stale list back with a fresh full TTL —
+   * silently undoing the drop.
+   */
+  it('discards a value whose fetch straddled an invalidate()', () => {
+    const cache = new TtlCache<string>(1000, () => 0);
+    const token = cache.begin(); // read starts on the old tree
+    cache.invalidate(); //           the pull lands mid-read
+    cache.set('stale', token); //    the read comes back and tries to store
+    expect(cache.get()).toBeNull();
+  });
+
+  it('stores a value whose fetch did not straddle an invalidate()', () => {
+    const cache = new TtlCache<string>(1000, () => 0);
+    cache.invalidate();
+    const token = cache.begin();
+    cache.set('fresh', token);
+    expect(cache.get()).toBe('fresh');
+  });
+
+  it('keeps refusing a token from before the drop, not just the first time', () => {
+    const cache = new TtlCache<string>(1000, () => 0);
+    const stale = cache.begin();
+    cache.invalidate();
+    const fresh = cache.begin();
+    cache.set('fresh', fresh);
+    cache.set('stale', stale);
+    expect(cache.get()).toBe('fresh');
+  });
+});

package/src/shared/domain-errors.ts

@@ -166,6 +166,35 @@ export class PullRebaseConflictError extends WorkflowDomainError {
   }
 }
 
+/**
+ * The clone's branch no longer exists on origin: the fetch that refreshes
+ * `refs/remotes/origin/<branch>` found no such ref. Distinct from an
+ * unreachable remote — the host answered, and the answer was "gone" — so a
+ * caller can treat the clone as stale rather than the sync as failed. 410.
+ */
+export class RemoteBranchGoneError extends WorkflowDomainError {
+  readonly kind = 'remote-branch-gone' as const;
+  constructor(readonly branch: string) {
+    super(`Branch "${branch}" no longer exists on the remote.`, 410, {
+      kind: 'remote-branch-gone',
+      branch,
+    });
+    this.name = 'RemoteBranchGoneError';
+  }
+}
+
+/**
+ * Whether a failed clone or fetch failed because origin has no such branch, as
+ * opposed to being unreachable or refusing the credential. Git's wording for
+ * the two shapes: `Remote branch <x> not found in upstream origin` (clone) and
+ * `couldn't find remote ref refs/heads/<x>` (fetch). The ONE classifier for
+ * this fact — the workspace bootstrap and the git layer both consult it, so
+ * a wording learned by one is learned by both.
+ */
+export function isMissingRemoteBranchFailure(message: string): boolean {
+  return /Remote branch .* not found in upstream|couldn't find remote ref/i.test(message);
+}
+
 /**
  * Generic 400 for workflow-input validation (malformed branch names, missing
  * fields, etc.). Carries an optional payload so callers can attach typed

package/src/shared/fs-errors.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a filesystem error means "there is no such path" — the one failure
+ * a reader may treat as an ordinary answer. Everything else (permissions,
+ * I/O, a loop) is a failure to READ what is there, and a caller that folds
+ * it into absence turns an outage into a wrong answer.
+ */
+export function isAbsence(err: unknown): boolean {
+  const code = (err as { code?: unknown } | null)?.code;
+  return code === 'ENOENT' || code === 'ENOTDIR';
+}

package/src/shared/fs-walk.ts

@@ -1,30 +1,45 @@
-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: string, match: (basename: string) => boolean): Promise<string[]> {
+export async function walkFiles(
+  root: string,
+  match: (basename: string) => boolean,
+  opts: { strict?: boolean } = {},
+): Promise<string[]> {
   const out: string[] = [];
-  const walk = async (dir: string, rel: string): Promise<void> => {
-    let entries: import('node:fs').Dirent[];
-    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 {
+  constructor(
+    readonly relDir: string,
+    readonly cause: unknown,
+  ) {
+    super(`${relDir || '.'} could not be listed — ${cause instanceof Error ? cause.message : String(cause)}`);
+    this.name = 'WalkError';
+  }
+}

package/src/shared/kb-walk.ts

@@ -0,0 +1,95 @@
+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: string): boolean {
+  return name.startsWith('.') || name === 'node_modules';
+}
+
+/** 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 async function walkKb(root: string, listeners: readonly KbWalkListener[]): Promise<KbWalkResult> {
+  const holes: string[] = [];
+
+  const visit = async (abs: string, rel: string): Promise<void> => {
+    let listed: import('node:fs').Dirent[];
+    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: WalkedEntry[] = 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 };
+}

package/src/shared/path-order.ts

@@ -0,0 +1,33 @@
+/**
+ * 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: string, b: string): number {
+  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: string, b: string): number {
+  const order = a.localeCompare(b);
+  if (order !== 0) return order;
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/shared/ttl-cache.ts

@@ -6,6 +6,11 @@
  */
 export class TtlCache<T> {
   private entry: { at: number; value: T } | null = 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.
+   */
+  private generation = 0;
 
   constructor(
     private readonly ttlMs: number,
@@ -17,11 +22,38 @@ export class TtlCache<T> {
     return 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 {
+    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: T, token: number): void {
+    if (token !== this.generation) return;
     this.entry = { at: this.now(), value };
   }
 
   invalidate(): void {
     this.entry = null;
+    this.generation++;
   }
 }