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

package/src/modules/kb-fs/node-fs.ts

@@ -0,0 +1,165 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import {
+  WalkError,
+  isAbsence,
+  isSkippedEntry,
+  type EntryStat,
+  type IFsProbe,
+  type IgnoreRules,
+  type ITreeWalker,
+  type TreeWalkOptions,
+  type WalkListener,
+  type WalkResult,
+  type WalkedDir,
+  type WalkedEntry,
+} from '../../shared/fs.contract.js';
+import { comparePathComponents } from '../../shared/path-order.js';
+import { BevelIgnoreStack } from './bevel-ignore.js';
+
+/**
+ * The one implementation of {@link ITreeWalker} and {@link IFsProbe}, over
+ * node's filesystem. Stateless: the composition root makes one and hands it
+ * to every module that reads the disk. See `shared/fs.contract.ts` for what
+ * the walk promises; this file only keeps those promises.
+ */
+export class NodeFs implements ITreeWalker, IFsProbe {
+  // ── ITreeWalker ───────────────────────────────────────────────────────────
+
+  async walk(root: string, options: TreeWalkOptions, listeners: readonly WalkListener[]): Promise<WalkResult> {
+    const { skip, ignore = false, leaf, until, unreadable = 'hole' } = options;
+    const holes: string[] = [];
+
+    const visit = async (abs: string, rel: string, inherited: IgnoreRules): Promise<void> => {
+      if (until?.()) return;
+      let raw: WalkedEntry[];
+      let rules: IgnoreRules;
+      // Only the DISK's failures are holes: the listing and the folder's own
+      // rules. A reader's callback that throws is the reader's error, and
+      // propagates untouched like every other listener error.
+      try {
+        const listed = await this.listDir(abs);
+        // The root: a checkout without this tree, an empty walk. Deeper: a
+        // folder that vanished between listing and visiting — not a hole.
+        if (listed === null) return;
+        raw = listed;
+        // A folder whose own `.bevelignore` is there but cannot be read is as
+        // much a hole as one that cannot be listed: its rules are unknown, so
+        // nothing in it can be judged. (No file is no rules, never an error.)
+        rules = ignore ? await inherited.extendedWith(abs) : inherited;
+      } catch (err) {
+        if (unreadable === 'throw') throw err;
+        holes.push(rel);
+        for (const l of listeners) await l.onHole?.(rel, err);
+        return;
+      }
+      const seen = raw.filter((e) => !skip?.(e));
+      const isEntry = (e: WalkedEntry) => e.isDirectory() || e.isFile();
+      const listed = seen.filter(isEntry);
+      // The rules apply to everything that is there — a link a rule names is as hidden as a file.
+      const visible = ignore ? seen.filter((e) => !rules.isIgnored(path.join(abs, e.name), e.isDirectory())) : seen;
+      const entries = visible.filter(isEntry);
+      const dir: WalkedDir = { rel, abs, listed, ignore: rules };
+      for (const l of listeners) await l.onDir?.(rel, entries, dir);
+      if (leaf?.(dir, entries)) return;
+      for (const entry of visible) {
+        if (until?.()) return;
+        if (!isEntry(entry)) {
+          for (const l of listeners) await l.onOther?.(rel, entry);
+        } else if (entry.isDirectory()) {
+          await visit(path.join(abs, entry.name), rel ? `${rel}/${entry.name}` : entry.name, rules);
+        } else {
+          for (const l of listeners) await l.onFile?.(rel, entry.name);
+        }
+      }
+    };
+
+    await visit(root, '', typeof ignore === 'object' ? ignore : BevelIgnoreStack.empty());
+    return { holes };
+  }
+
+  walkKb(root: string, listeners: readonly WalkListener[], options: Omit<TreeWalkOptions, 'skip'> = {}): Promise<WalkResult> {
+    return this.walk(root, { ...options, skip: (e) => isSkippedEntry(e.name) }, listeners);
+  }
+
+  async walkFiles(root: string, match: (basename: string) => boolean, opts: { strict?: boolean } = {}): Promise<string[]> {
+    // Walk order IS component order over the paths: a folder's entries come
+    // sorted, and a folder's files are visited before its sibling's.
+    const out: string[] = [];
+    await this.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);
+        },
+      },
+    ]);
+    return out;
+  }
+
+  // ── IFsProbe ──────────────────────────────────────────────────────────────
+
+  async exists(p: string): Promise<boolean> {
+    return (await this.lstatOrNull(p)) !== null;
+  }
+
+  statOrNull(p: string): Promise<EntryStat | null> {
+    return fs.stat(p).catch((err: unknown) => (isAbsence(err) ? null : Promise.reject(err)));
+  }
+
+  lstatOrNull(p: string): Promise<EntryStat | null> {
+    return fs.lstat(p).catch((err: unknown) => (isAbsence(err) ? null : Promise.reject(err)));
+  }
+
+  async isDirectory(p: string): Promise<boolean> {
+    return (await this.lstatOrNull(p))?.isDirectory() ?? false;
+  }
+
+  async listDir(p: string): Promise<WalkedEntry[] | null> {
+    let raw: import('node:fs').Dirent[];
+    try {
+      raw = await fs.readdir(p, { withFileTypes: true });
+    } catch (err) {
+      if (isAbsence(err)) return null;
+      throw err;
+    }
+    return raw.sort((a, b) => comparePathComponents(a.name, b.name));
+  }
+
+  async readTextFile(p: string): Promise<string> {
+    return fs.readFile(p, 'utf-8');
+  }
+
+  async readJsonObject(p: string): Promise<Record<string, unknown> | null> {
+    let text: string;
+    try {
+      text = await this.readTextFile(p);
+    } catch (err) {
+      if (isAbsence(err)) return null;
+      throw err;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return null;
+    }
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  }
+
+  async freeBytes(p: string): Promise<number | null> {
+    try {
+      // `bavail`, not `bfree`: the blocks an unprivileged process may still
+      // write, which is what a git run as this process will actually get.
+      const stats = await fs.statfs(p);
+      return Number(stats.bavail) * Number(stats.bsize);
+    } catch {
+      // A path that is not there, or a filesystem that cannot answer — the
+      // contract's null: "cannot say", which the reader treats as not known
+      // to be full rather than as full.
+      return null;
+    }
+  }
+}

package/src/modules/kb-fs/read-only-filesystem.ts

@@ -1,10 +1,10 @@
 import {
-  LocalFilesystem,
   type CopyOptions,
   type FileContent,
   type RemoveOptions,
   type WriteOptions,
 } from '@mastra/core/workspace';
+import { GitGuardedFilesystem } from './git-guarded-filesystem.js';
 
 /**
  * A `LocalFilesystem` that permits reads but refuses every mutating operation.
@@ -16,7 +16,7 @@ import {
  * The architect agent keeps the lock-aware `LockingFilesystem` (which commits +
  * pushes); consumer agents get no write path at all.
  */
-export class ReadOnlyFilesystem extends LocalFilesystem {
+export class ReadOnlyFilesystem extends GitGuardedFilesystem {
   private static deny(op: string): never {
     throw new Error(
       `This assistant is read-only — "${op}" is not allowed. ` +
@@ -24,31 +24,40 @@ export class ReadOnlyFilesystem extends LocalFilesystem {
     );
   }
 
-  override async writeFile(_path: string, _content: FileContent, _options?: WriteOptions): Promise<void> {
+  override async writeFile(path: string, _content: FileContent, _options?: WriteOptions): Promise<void> {
+    await this.assertNotGitInternals(path);
     ReadOnlyFilesystem.deny('write_file');
   }
 
-  override async appendFile(_path: string, _content: FileContent): Promise<void> {
+  override async appendFile(path: string, _content: FileContent): Promise<void> {
+    await this.assertNotGitInternals(path);
     ReadOnlyFilesystem.deny('append_file');
   }
 
-  override async deleteFile(_path: string, _options?: RemoveOptions): Promise<void> {
+  override async deleteFile(path: string, _options?: RemoveOptions): Promise<void> {
+    await this.assertNotGitInternals(path);
     ReadOnlyFilesystem.deny('delete_file');
   }
 
-  override async copyFile(_src: string, _dest: string, _options?: CopyOptions): Promise<void> {
+  override async copyFile(src: string, dest: string, _options?: CopyOptions): Promise<void> {
+    await this.assertNotGitInternals(src);
+    await this.assertNotGitInternals(dest);
     ReadOnlyFilesystem.deny('copy_file');
   }
 
-  override async moveFile(_src: string, _dest: string, _options?: CopyOptions): Promise<void> {
+  override async moveFile(src: string, dest: string, _options?: CopyOptions): Promise<void> {
+    await this.assertNotGitInternals(src);
+    await this.assertNotGitInternals(dest);
     ReadOnlyFilesystem.deny('move_file');
   }
 
-  override async mkdir(_path: string, _options?: { recursive?: boolean }): Promise<void> {
+  override async mkdir(path: string, _options?: { recursive?: boolean }): Promise<void> {
+    await this.assertNotGitInternals(path);
     ReadOnlyFilesystem.deny('mkdir');
   }
 
-  override async rmdir(_path: string, _options?: RemoveOptions): Promise<void> {
+  override async rmdir(path: string, _options?: RemoveOptions): Promise<void> {
+    await this.assertNotGitInternals(path);
     ReadOnlyFilesystem.deny('rmdir');
   }
 }

package/src/modules/kb-fs/repo-path.ts

@@ -7,9 +7,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.
  */
 
 /**
@@ -37,6 +45,10 @@ export function isInsideRepo(wsPath: string, kbDirName: string): boolean {
  * 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: string, kbDirName: string): void {
   if (isInsideRepo(wsPath, kbDirName)) return;
@@ -54,3 +66,201 @@ export function assertInsideRepo(wsPath: string, kbDirName: string): void {
     { 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: string, kbDirName: string): string {
+  /** The refusal, with {@link assertInsideRepo}'s message and corrected path. */
+  const refuse = (): never => {
+    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: string, kbDirName: string): void {
+  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: Record<string, unknown>,
+  kbDirName: string,
+  keys: readonly string[],
+): void {
+  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 as Record<string, unknown>).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: string,
+  layout: { knowledgeBaseDir: string; skillsDir: string; pluginsDir: string; agentsFile: string },
+): void {
+  const taken = kbDirName.toLowerCase();
+  const collision = (
+    [
+      ['knowledgeBaseDir', layout.knowledgeBaseDir],
+      ['skillsDir', layout.skillsDir],
+      ['pluginsDir', layout.pluginsDir],
+      ['agentsFile', layout.agentsFile],
+    ] as const
+  ).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'] as const;
+
+/**
+ * {@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: Record<string, unknown>,
+  kbDirName: string,
+  skip?: (value: string) => boolean,
+): Record<string, unknown> {
+  const one = (value: unknown): unknown =>
+    typeof value !== 'string' || value.length === 0 || skip?.(value)
+      ? value
+      : normalizeWorkspacePath(value, kbDirName);
+  const out: Record<string, unknown> = { ...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: unknown) =>
+      f && typeof f === 'object' && 'path' in f
+        ? { ...(f as Record<string, unknown>), path: one((f as Record<string, unknown>).path) }
+        : f,
+    );
+  }
+  return out;
+}