@bevel-software/platform-shared 0.14.0 → 0.19.0

package/src/workspace/agent-preamble.ts

@@ -0,0 +1,47 @@
+/**
+ * The rules about the deployment preamble's TEXT that both sides need to
+ * agree on: the file it lives in, the caps it is cut at, and what counts as a
+ * private comment inside it.
+ *
+ * These lived in the backend composer and were mirrored by hand in the
+ * frontend editor, whose own comment said so. The two are not free to differ:
+ * the editor decides what an admin is shown and what it writes back, the
+ * composer decides what agents receive, and a drift between them shows the
+ * admin one description while agents get another.
+ *
+ * Pure: no IO, no clock, no platform assumptions.
+ */
+
+/** The repository-root file an admin edits. */
+export const PREAMBLE_FILE = 'mcp-description.md';
+
+/** UTF-16 units of preamble sent on the handshake before the marker replaces the rest. */
+export const PREAMBLE_CAP = 6_000;
+
+/** UTF-16 units of the whole tool prefix (fixed line included). */
+export const TOOL_PREFIX_CAP = 300;
+
+/**
+ * Remove every `<!-- … -->` block.
+ *
+ * A `<!--` that is never closed takes the rest of the text with it and is
+ * reported, so a caller can warn: that is the fail-closed half of the rule,
+ * and it is why an admin's private note cannot leak through the likeliest
+ * editing slip. The editor strips the same blocks to decide what to show, and
+ * closes an unterminated one when it writes back.
+ */
+export function stripHtmlComments(text: string): { text: string; unterminated: boolean } {
+  let out = '';
+  let from = 0;
+  for (;;) {
+    const open = text.indexOf('<!--', from);
+    if (open === -1) {
+      out += text.slice(from);
+      return { text: out, unterminated: false };
+    }
+    out += text.slice(from, open);
+    const close = text.indexOf('-->', open + 4);
+    if (close === -1) return { text: out, unterminated: true };
+    from = close + 3;
+  }
+}

package/src/workspace/entry-exists.ts

@@ -0,0 +1,36 @@
+/**
+ * THE sentence a rename, a move or a copy answers with when something is
+ * already at the destination.
+ *
+ * A rename is not a way to replace content: renaming a `.docx` onto an
+ * existing `.md` used to hand the markdown file the Word bytes and break the
+ * page. Every surface — the sidebar rename box, a drag onto a folder, the
+ * agent's `move_file` and `copy_file` — refuses with this one sentence, so a
+ * user who meets it in the sidebar and an agent that meets it in a tool
+ * result are told the same thing.
+ *
+ * Kept here, beside `filename.ts`, for the same reason that file is: the
+ * backend throws it and the frontend renders it, and neither should spell it
+ * its own way.
+ */
+
+/** What is already sitting at the destination. */
+export type ExistingEntryKind = 'file' | 'folder';
+
+/**
+ * `A file named <name> already exists in <folder>.` — `name` and `folder` are
+ * read off `destinationPath`, which may be workspace-relative or
+ * repo-relative; only its last two segments are used, so the reader sees the
+ * name they typed and the folder they were aiming at rather than a full path.
+ * A destination directly at the top of the tree has no folder segment to
+ * name, and says `the top level` instead.
+ */
+export function entryExistsMessage(kind: ExistingEntryKind, destinationPath: string): string {
+  const segments = destinationPath
+    .replace(/\\/g, '/')
+    .split('/')
+    .filter((segment) => segment.length > 0 && segment !== '.');
+  const name = segments[segments.length - 1] ?? destinationPath;
+  const folder = segments.length > 1 ? segments[segments.length - 2] : 'the top level';
+  return `A ${kind} named ${name} already exists in ${folder}.`;
+}

package/src/workspace/filename.ts

@@ -23,9 +23,13 @@ const WINDOWS_RESERVED_NAMES = new Set([
 
 /** Characters Windows forbids in any filename component. `/` is the path
  *  separator on Unix, included for the same reason. `\` is also a path
- *  separator on Windows. Control chars (0x00–0x1F) are rejected separately. */
+ *  separator on Windows. Control characters are rejected with them: NUL and
+ *  0x01–0x1F because Windows refuses them, and DEL (0x7F) — which every
+ *  filesystem would write — as a matter of hygiene: a name carrying a
+ *  character nobody can see or type is not a name people can share, and the
+ *  knowledge-base root names are validated by this same rule. */
 // eslint-disable-next-line no-control-regex
-const FORBIDDEN_CHARS = /[<>:"/\\|?*\x00-\x1F]/;
+const FORBIDDEN_CHARS = /[<>:"/\\|?*\x00-\x1F\x7F]/;
 
 /** Per-component byte limit: NTFS = 255 UTF-16 units, ext4 = 255 bytes,
  *  APFS = 255 UTF-8 bytes. Use UTF-8 bytes — the strictest of the three. */
@@ -45,7 +49,7 @@ export function validateFilename(name: string): string | null {
   if (name === '.' || name === '..') return 'Name cannot be "." or ".."';
 
   if (FORBIDDEN_CHARS.test(name)) {
-    return 'Name cannot contain any of these characters: < > : " / \\ | ? *';
+    return 'Name cannot contain control characters or any of: < > : " / \\ | ? *';
   }
 
   // Windows trims trailing dots and spaces silently — a name ending in either
@@ -92,6 +96,37 @@ export function validateRelativePath(relativePath: string): string | null {
   return null;
 }
 
+/**
+ * ONE identity per file, so everything that coordinates on a path agrees about
+ * what it is coordinating on: an in-process queue, a database lock row, and
+ * the bytes on disk. {@link validateRelativePath} accepts a leading `./` and
+ * repeated slashes as spellings of the same path, and two callers spelling one
+ * file differently would otherwise take two different locks and write over
+ * each other. `.` and `..` segments are refused outright by the validator, so
+ * there is nothing to resolve here beyond the separators.
+ *
+ * Case is deliberately left alone. The deployment target is Linux, where
+ * `Foo.md` and `foo.md` are two different files; folding case to suit a
+ * case-insensitive development machine would merge two real files in
+ * production, which is a worse failure than the race it would close.
+ */
+export function canonicalRelativePath(relativePath: string): string {
+  // Never LAUNDER a path. Dropping empty segments would turn the absolute
+  // `/etc/passwd` into the perfectly ordinary `etc/passwd`, and an absolute
+  // path is exactly what `path.resolve` lets win over the workspace directory
+  // — which is why the workspace-boundary check refuses it today. A path this
+  // cannot canonicalise is returned UNCHANGED, so every gate downstream sees
+  // what the caller actually sent and goes on refusing it.
+  if (relativePath.startsWith('/') || validateRelativePath(relativePath) !== null) {
+    return relativePath;
+  }
+  return relativePath
+    .replace(/^\.\//, '')
+    .split('/')
+    .filter((segment) => segment.length > 0)
+    .join('/');
+}
+
 /**
  * Throwing wrapper for the backend service layer — keeps call sites a single
  * line and produces a clear `Error` the route handler can surface as a 400.

package/src/workspace/frontmatter-carriers.ts

@@ -0,0 +1,57 @@
+/**
+ * Which files can carry their OWN frontmatter — and therefore their own
+ * per-file access rules.
+ *
+ * A file-level grant, revoke or restriction splices a `---` YAML block into
+ * the file itself. That is right for a Markdown note and destructive for
+ * anything else: spliced into a PDF, a presentation or an image it corrupts
+ * the bytes (the preview goes blank), and the grant never even resolves.
+ * Such a file takes its folder's rules instead.
+ *
+ * THE ONE predicate for that question: the access routes refuse a file-level
+ * mutation on a file it rejects, and the Manage access dialog shows the folder
+ * pointer for the same files.
+ *
+ * The carriers are exactly the files the access resolver reads its own
+ * frontmatter from — the backend's core access-frontmatter extension set:
+ * Markdown notes (`.md`) and `.tool` definitions (whole-document YAML whose
+ * access verbs sit beside the definition). Both are served by the file-reader
+ * registry's text-editable text reader. The registry test pins both facts, so
+ * this list cannot drift from the resolver or the registry silently. (Neither
+ * can live here: the registry's document readers carry backend-only extraction
+ * dependencies, and overlays register further extensions at boot — the backend
+ * passes its full registered set as `extensions`.)
+ *
+ * Matching is case-SENSITIVE, as the resolver's is: `Note.MD` carries no
+ * enforced rule, so a grant written there would never resolve. An extensionless
+ * file is NOT a carrier either: its content may be anything, and a path alone
+ * cannot tell a note from a binary.
+ */
+export const FRONTMATTER_CARRIER_EXTENSIONS: readonly string[] = ['.md', '.tool'];
+
+/**
+ * True when the file at `path` can carry its own frontmatter (and so its own
+ * access rules). `extensions` defaults to the core set; the backend passes the
+ * resolver's registered set so an overlay's kinds count too.
+ */
+export function canCarryFrontmatter(
+  path: string,
+  extensions: readonly string[] = FRONTMATTER_CARRIER_EXTENSIONS,
+): boolean {
+  const name = path.slice(path.lastIndexOf('/') + 1);
+  // The resolver's own rule is a plain suffix match, so a file named exactly
+  // `.md` is read for its frontmatter there — and must be a carrier here too,
+  // or a rule the resolver honours could not be managed.
+  return extensions.some((ext) => name.endsWith(ext));
+}
+
+/** The `kind` a refused file-level access mutation answers with. */
+export const FOLDER_GOVERNS_ACCESS_KIND = 'folder-governs-access';
+
+/**
+ * The one sentence both the 422 and the dialog say, naming the folder whose
+ * rules govern the file.
+ */
+export function folderGovernsAccessMessage(folder: string): string {
+  return `This file's access comes from its folder. Manage access on ${folder} instead.`;
+}

package/src/workspace/frontmatter.ts

@@ -1,14 +1,60 @@
+/**
+ * THE fence rule: a line is a frontmatter fence when, whitespace aside, it is
+ * exactly `---`. Forgiving on purpose — an opening fence with a trailing space
+ * or an indented fence is still a fence.
+ *
+ * Every reader in the platform asks this one function. The access model's
+ * line scan always judged fences this way while the splitter below demanded
+ * `---` at column 0, so a file written with a near-miss fence had access
+ * rules that applied while the catalog, the tool manuals and the frontmatter
+ * panel saw no frontmatter at all. One rule, asked everywhere, is what keeps
+ * a file from meaning two things.
+ */
+export function isFrontmatterFence(line: string | undefined): boolean {
+  return line?.trim() === '---';
+}
+
 /**
  * The ONE `---` frontmatter splitter, shared by backend and frontend so no file
- * type grows its own regex. Splits a leading `---`-fenced YAML block from the
- * body; null when the text doesn't open with a fence. Parsing the YAML inside is
- * the caller's concern (the access-control resolver deliberately keeps its own
- * hardened line-based reader — see `modules/access/access-splice.ts`).
+ * type grows its own reader. Splits a leading fenced YAML block from the body;
+ * null when the first line is not a fence or no later line closes it. Fences
+ * are judged by {@link isFrontmatterFence}. Parsing the YAML inside is the
+ * caller's concern (the access model keeps its own line scan, on the same
+ * fence rule, because a splice must put bytes back exactly as it found them).
+ *
+ * `frontmatter` is the raw text between the fence lines and `body` the raw
+ * text after the closing fence's line break, both byte for byte — line
+ * endings included — so a caller that rebuilds the file changes nothing it
+ * did not mean to.
  */
 export function extractFrontmatter(text: string): { frontmatter: string; body: string } | null {
-  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-  if (!m) return null;
-  return { frontmatter: m[1], body: m[2] };
+  // Walk the lines by offset rather than splitting, so both halves can be
+  // sliced out of the original text with their own line endings intact.
+  let start = 0;
+  let lineIndex = 0;
+  let openEnd = -1; // offset just past the opening fence's line break
+  while (start <= text.length) {
+    const nl = text.indexOf('\n', start);
+    const end = nl === -1 ? text.length : nl;
+    const line = text.slice(start, end).replace(/\r$/, '');
+    const next = nl === -1 ? text.length + 1 : nl + 1;
+    if (lineIndex === 0) {
+      // A lone `---` with nothing after it opens nothing.
+      if (!isFrontmatterFence(line) || nl === -1) return null;
+      openEnd = next;
+    } else if (isFrontmatterFence(line)) {
+      // The frontmatter ends before the line break that precedes this fence.
+      const fmEnd = start - (start >= 2 && text[start - 2] === '\r' ? 2 : 1);
+      return {
+        frontmatter: fmEnd > openEnd ? text.slice(openEnd, fmEnd) : '',
+        body: next > text.length ? '' : text.slice(next),
+      };
+    }
+    if (nl === -1) return null; // never closed
+    start = next;
+    lineIndex += 1;
+  }
+  return null;
 }
 
 /**
@@ -37,7 +83,10 @@ export function setFrontmatterField(text: string, key: string, value: string): s
     // No frontmatter — prepend a fresh block, keeping the original body intact.
     return `---${eol}${line}${eol}---${eol}${text}`;
   }
-  const fmLines = fm.frontmatter.split(/\r?\n/);
+  // An empty block has no lines, not one empty line: splitting '' would give
+  // [''], and the inserted key would be followed by a blank line before the
+  // closing fence.
+  const fmLines = fm.frontmatter === '' ? [] : fm.frontmatter.split(/\r?\n/);
   const idx = fmLines.findIndex((l) => keyRe.test(l));
   if (idx >= 0) fmLines[idx] = line;
   else fmLines.unshift(line);