@tdxvolt/volt-drive-mcp 0.0.0-stage → 0.1.1

package/src/drive-index.js

@@ -0,0 +1,370 @@
+/**
+ * Pure helpers for working with a drive's index.
+ *
+ * A drive stores its structure in two synced Yjs documents:
+ *
+ * - `__meta`: `idx` is a map of `documentId -> Y.Map` holding, per file,
+ *   `json` ({ name: "<path>", s: <size> }), `__hash`, `__schema` and
+ *   `__timestamp`. It is owned by the server; clients never write it directly.
+ * - `folders`: `folders` is a map of explicit folder path -> true.
+ *
+ * Nothing in this module talks to the network, which keeps it unit-testable.
+ */
+
+import {
+  basename,
+  compareDrivePaths,
+  globToRegExp,
+  isWithin,
+  parentOf
+} from "./paths.js";
+
+/** Id of the synapse document that holds the folder list. */
+export const FOLDERS_DOCUMENT_ID = "folders";
+/** Name of the map inside the folders document. */
+export const FOLDERS_BRANCH = "folders";
+/** Name of the bookkeeping map inside the folders document. */
+export const FOLDERS_STATE_BRANCH = "state";
+/** Name of the index map inside the `__meta` document. */
+export const IDX_BRANCH = "idx";
+/** Id of the document holding the index. */
+export const META_DOCUMENT_ID = "__meta";
+
+/** `__schema` types. */
+export const SCHEMA_BLOB = "blob";
+export const SCHEMA_ARRAY = "array";
+
+function asYMap(value) {
+  if (value && typeof value.get === "function" && typeof value.keys === "function") {
+    return value;
+  }
+  return null;
+}
+
+function readJson(docMap) {
+  if (!docMap) {
+    return null;
+  }
+  const json = docMap.get("json");
+  if (!json || typeof json !== "object" || !json.name) {
+    return null;
+  }
+  return { name: String(json.name), s: Number(json.s ?? 0) || 0 };
+}
+
+function readSchema(docMap) {
+  const schema = docMap.get("__schema");
+  return Array.isArray(schema)
+    ? schema.filter((item) => item && typeof item === "object")
+    : [];
+}
+
+function readSchemaType(schema) {
+  if (schema.length !== 1) {
+    return "text";
+  }
+  const type = schema[0]?.type;
+  if (type === SCHEMA_BLOB) {
+    return SCHEMA_BLOB;
+  }
+  if (type === SCHEMA_ARRAY) {
+    return SCHEMA_ARRAY;
+  }
+  return "text";
+}
+
+/**
+ * Derive the flat list of files from the `idx` map.
+ *
+ * @param {import("yjs").Map<unknown>} idxMap
+ * @returns {DriveEntry[]}
+ */
+export function readDriveEntries(idxMap) {
+  const entries = [];
+  for (const documentId of idxMap.keys()) {
+    if (documentId === FOLDERS_DOCUMENT_ID) {
+      continue;
+    }
+    const docMap = asYMap(idxMap.get(documentId));
+    const json = readJson(docMap);
+    if (!json) {
+      continue;
+    }
+    const hash = docMap.get("__hash");
+    const timestamp = Number(docMap.get("__timestamp"));
+    const schema = readSchema(docMap);
+    const schemaType = readSchemaType(schema);
+    entries.push({
+      documentId,
+      path: json.name,
+      size: json.s,
+      // Both blob documents and the legacy byte-array encoding are binary.
+      binary: schemaType === SCHEMA_BLOB || schemaType === SCHEMA_ARRAY,
+      schemaType,
+      schema,
+      contentHash: typeof hash === "string" ? hash : "",
+      modified: Number.isFinite(timestamp) && timestamp > 0 ? timestamp : null
+    });
+  }
+  entries.sort((a, b) => compareDrivePaths(a.path, b.path));
+  return entries;
+}
+
+/**
+ * Explicit folder paths from the `folders` map.
+ * @param {import("yjs").Map<unknown>} foldersMap
+ * @returns {string[]}
+ */
+export function readDriveFolders(foldersMap) {
+  const folders = [...foldersMap.keys()].filter(Boolean);
+  folders.sort(compareDrivePaths);
+  return folders;
+}
+
+/**
+ * The `metadata` of a `SetSynapseDocumentMetadata` request that leaves an
+ * existing file's schema as it is.
+ *
+ * The Volt rewrites a document's schema on every metadata call and rejects a
+ * request with none, so even a rename must restate it.
+ */
+export function schemaToMetadata(entry) {
+  const schema = entry.schema?.length
+    ? entry.schema
+    : [{ name: "content", type: "text" }];
+  return schema.map((item) => {
+    const jsonSchema = item.jsonSchema;
+    const hasJsonSchema =
+      jsonSchema && typeof jsonSchema === "object" && Object.keys(jsonSchema).length > 0;
+    return {
+      name: String(item.name ?? "content"),
+      type: String(item.type ?? "text"),
+      ...(hasJsonSchema ? { json_schema: JSON.stringify(jsonSchema) } : {})
+    };
+  });
+}
+
+/** Find the file entry at exactly `path`. */
+export function findEntry(entries, path) {
+  return entries.find((entry) => entry.path === path) ?? null;
+}
+
+/** True when anything (a file or a folder) lies underneath `folder`. */
+export function hasChildren(entries, folders, folder) {
+  const prefix = `${folder}/`;
+  return (
+    entries.some((entry) => entry.path.startsWith(prefix)) ||
+    folders.some((path) => path.startsWith(prefix))
+  );
+}
+
+/**
+ * What lives at `path`: "directory" (the root, an explicit folder, or an
+ * implied folder that contains files), "file", or null when nothing does.
+ */
+export function pathKind(entries, folders, path) {
+  if (!path) {
+    return "directory";
+  }
+  if (findEntry(entries, path)) {
+    return "file";
+  }
+  if (folders.includes(path) || hasChildren(entries, folders, path)) {
+    return "directory";
+  }
+  return null;
+}
+
+/**
+ * The first ancestor of `path` that is a file, or null. Used to refuse
+ * creating `a/b/c` when `a/b` is already a file.
+ */
+export function findFileAncestor(entries, path) {
+  let slash = path.indexOf("/");
+  while (slash > 0) {
+    const ancestor = path.slice(0, slash);
+    if (findEntry(entries, ancestor)) {
+      return ancestor;
+    }
+    slash = path.indexOf("/", slash + 1);
+  }
+  return null;
+}
+
+/**
+ * List the immediate children of `folder` (or every descendant when
+ * `recursive`), folders first.
+ *
+ * @returns {ListedItem[]}
+ */
+export function listDirectory(entries, folders, folder, { recursive = false } = {}) {
+  const items = new Map();
+
+  const addFolder = (path) => {
+    if (!items.has(path)) {
+      items.set(path, {
+        type: "directory",
+        name: basename(path),
+        path,
+        size: null,
+        modified: null
+      });
+    }
+    return items.get(path);
+  };
+
+  const touchFolderModified = (path, modified) => {
+    if (modified === null) {
+      return;
+    }
+    const item = items.get(path);
+    if (item && (item.modified === null || modified > item.modified)) {
+      item.modified = modified;
+    }
+  };
+
+  const prefix = folder ? `${folder}/` : "";
+
+  for (const entry of entries) {
+    if (folder && !entry.path.startsWith(prefix)) {
+      continue;
+    }
+    const rest = entry.path.slice(prefix.length);
+    const slash = rest.indexOf("/");
+
+    if (recursive) {
+      // Materialise every folder on the way down to this file.
+      let walked = folder;
+      const parts = rest.split("/");
+      for (let i = 0; i < parts.length - 1; i++) {
+        walked = walked ? `${walked}/${parts[i]}` : parts[i];
+        addFolder(walked);
+        touchFolderModified(walked, entry.modified);
+      }
+      items.set(entry.path, fileItem(entry));
+    } else if (slash < 0) {
+      items.set(entry.path, fileItem(entry));
+    } else {
+      const childFolder = prefix + rest.slice(0, slash);
+      addFolder(childFolder);
+      touchFolderModified(childFolder, entry.modified);
+    }
+  }
+
+  for (const path of folders) {
+    if (folder && !path.startsWith(prefix)) {
+      continue;
+    }
+    if (path === folder) {
+      continue;
+    }
+    const rest = path.slice(prefix.length);
+    if (recursive) {
+      let walked = folder;
+      for (const part of rest.split("/")) {
+        walked = walked ? `${walked}/${part}` : part;
+        addFolder(walked);
+      }
+    } else {
+      const slash = rest.indexOf("/");
+      addFolder(prefix + (slash < 0 ? rest : rest.slice(0, slash)));
+    }
+  }
+
+  return [...items.values()].sort((a, b) => {
+    if (a.type !== b.type) {
+      return a.type === "directory" ? -1 : 1;
+    }
+    return compareDrivePaths(a.path, b.path);
+  });
+}
+
+function fileItem(entry) {
+  return {
+    type: "file",
+    name: basename(entry.path),
+    path: entry.path,
+    size: entry.size,
+    modified: entry.modified,
+    ...(entry.binary ? { binary: true } : {})
+  };
+}
+
+/**
+ * Match paths by name. A query containing `*` or `?` is a glob matched against
+ * the whole path (or just the file name when it has no `/`); otherwise it is a
+ * case-insensitive substring of the path.
+ *
+ * @returns {DriveEntry[]} matching file entries under `folder`.
+ */
+export function searchEntriesByPath(entries, query, folder = "") {
+  const candidates = entries.filter((entry) => isWithin(entry.path, folder));
+  if (!query) {
+    return candidates;
+  }
+
+  if (/[*?]/.test(query)) {
+    const regex = globToRegExp(query);
+    const nameOnly = !query.includes("/");
+    return candidates.filter((entry) =>
+      regex.test(nameOnly ? basename(entry.path) : entry.path)
+    );
+  }
+
+  const needle = query.toLowerCase();
+  return candidates.filter((entry) => entry.path.toLowerCase().includes(needle));
+}
+
+/**
+ * Plan the document metadata rewrites needed to move `source` to `target`.
+ * Works for a single file and for a whole folder (every file beneath it).
+ *
+ * @returns {{ rewrites: {entry: DriveEntry, newPath: string}[], folderRenames: {from: string, to: string}[] }}
+ */
+export function planMove(entries, folders, source, target) {
+  const rewrites = [];
+  const file = findEntry(entries, source);
+  if (file) {
+    rewrites.push({ entry: file, newPath: target });
+    return { rewrites, folderRenames: [] };
+  }
+
+  for (const entry of entries) {
+    if (isWithin(entry.path, source)) {
+      const suffix = entry.path.slice(source.length);
+      rewrites.push({ entry, newPath: `${target}${suffix}` });
+    }
+  }
+
+  const folderRenames = [];
+  for (const path of folders) {
+    if (isWithin(path, source)) {
+      folderRenames.push({ from: path, to: `${target}${path.slice(source.length)}` });
+    }
+  }
+  return { rewrites, folderRenames };
+}
+
+/** Parent folder of `path`, exported for callers working with entries. */
+export { parentOf };
+
+/**
+ * @typedef {object} DriveEntry
+ * @property {string} documentId
+ * @property {string} path
+ * @property {number} size
+ * @property {boolean} binary
+ * @property {"text"|"blob"|"array"} schemaType
+ * @property {string} contentHash
+ * @property {number|null} modified - epoch milliseconds.
+ */
+
+/**
+ * @typedef {object} ListedItem
+ * @property {"file"|"directory"} type
+ * @property {string} name
+ * @property {string} path
+ * @property {number|null} size
+ * @property {number|null} modified
+ * @property {boolean} [binary]
+ */