@sfrangulov/shared-memory-mcp 1.0.0

package/lib/atomic-commit.js

@@ -0,0 +1,126 @@
+/**
+ * Atomic commit via Git Trees API with SHA conflict retry.
+ *
+ * @module atomic-commit
+ */
+
+/**
+ * Error thrown when a ref update fails due to a SHA conflict (HTTP 422).
+ */
+export class ConflictError extends Error {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(message);
+    this.name = "ConflictError";
+  }
+}
+
+/** @param {number} ms */
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Performs a single atomic commit using the Git Trees API.
+ *
+ * Workflow:
+ * 1. Get HEAD SHA (or use provided parentSHA)
+ * 2. Get tree SHA of parent commit
+ * 3. Create blobs for each file
+ * 4. Create new tree with base_tree (preserves existing files)
+ * 5. Create commit pointing to new tree
+ * 6. Update ref to new commit (throws ConflictError on 422)
+ *
+ * @param {object} client - GitHub client (from createGitHubClient)
+ * @param {object} params
+ * @param {Array<{path: string, content: string}>} params.files - files to commit
+ * @param {string} params.message - commit message
+ * @param {string} [params.parentSHA] - optional parent commit SHA (fetches HEAD if omitted)
+ * @returns {Promise<{commitSHA: string, success: true}>}
+ * @throws {ConflictError} when ref update fails with 422
+ */
+export async function atomicCommit(client, { files, message, parentSHA }) {
+  // Step 1: Get parent SHA
+  const resolvedParentSHA = parentSHA ?? (await client.getHeadSHA());
+
+  // Step 2: Get tree SHA of parent commit
+  const treeSHA = await client.getTreeSHA(resolvedParentSHA);
+
+  // Step 3: Create blobs for each file
+  const filesWithBlobs = await Promise.all(
+    files.map(async (file) => {
+      const blobSHA = await client.createBlob(file.content);
+      return { path: file.path, blobSHA };
+    })
+  );
+
+  // Step 4: Create new tree with base_tree
+  const newTreeSHA = await client.createTree(treeSHA, filesWithBlobs);
+
+  // Step 5: Create commit
+  const commitSHA = await client.createCommit(
+    newTreeSHA,
+    resolvedParentSHA,
+    message
+  );
+
+  // Step 6: Update ref — throw ConflictError on 422
+  try {
+    await client.updateRef(commitSHA);
+  } catch (err) {
+    if (err.status === 422) {
+      throw new ConflictError(
+        `Ref update conflict: ${err.message || "SHA mismatch"}`
+      );
+    }
+    throw err;
+  }
+
+  return { commitSHA, success: true };
+}
+
+/**
+ * Performs an atomic commit with automatic retry on SHA conflicts.
+ *
+ * On ConflictError: retries with fresh HEAD SHA.
+ * Backoff: 1s, 3s, 9s (exponential * 3).
+ * After all retries exhausted: returns { success: false, error: 'conflict' }.
+ * On non-ConflictError: rethrows immediately.
+ *
+ * @param {object} client - GitHub client (from createGitHubClient)
+ * @param {object} params
+ * @param {Array<{path: string, content: string}>} params.files - files to commit
+ * @param {string} params.message - commit message
+ * @param {number} [params.maxRetries=3] - maximum number of retries
+ * @returns {Promise<{commitSHA: string, success: true} | {success: false, error: 'conflict'}>}
+ */
+export async function atomicCommitWithRetry(
+  client,
+  { files, message, maxRetries = 3 }
+) {
+  const backoffs = [1000, 3000, 9000];
+
+  // First attempt
+  try {
+    return await atomicCommit(client, { files, message });
+  } catch (err) {
+    if (!(err instanceof ConflictError)) throw err;
+    // Fall through to retry loop
+  }
+
+  // Retry loop
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    const delay = backoffs[attempt] ?? backoffs[backoffs.length - 1];
+    await sleep(delay);
+
+    try {
+      // No parentSHA — atomicCommit will fetch fresh HEAD
+      return await atomicCommit(client, { files, message });
+    } catch (err) {
+      if (!(err instanceof ConflictError)) throw err;
+      // Continue to next retry
+    }
+  }
+
+  return { success: false, error: "conflict" };
+}

package/lib/github-client.js

@@ -0,0 +1,220 @@
+import { Octokit } from "@octokit/rest";
+import { retry } from "@octokit/plugin-retry";
+import { throttling } from "@octokit/plugin-throttling";
+import pLimit from "p-limit";
+
+const limit = pLimit(5);
+
+/**
+ * Creates an Octokit instance with retry and throttling plugins.
+ * @param {string} token - GitHub personal access token
+ * @returns {Octokit} configured Octokit instance
+ */
+export function createOctokit(token) {
+  const MyOctokit = Octokit.plugin(retry, throttling);
+
+  return new MyOctokit({
+    auth: token,
+    throttle: {
+      onRateLimit: (retryAfter, options, octokit, retryCount) => {
+        octokit.log.warn(
+          `Rate limit hit for ${options.method} ${options.url}`
+        );
+        if (retryCount < 1) return true;
+      },
+      onSecondaryRateLimit: (retryAfter, options, octokit) => {
+        octokit.log.warn(
+          `Secondary rate limit for ${options.method} ${options.url}`
+        );
+      },
+    },
+    retry: { doNotRetry: ["429"] },
+    request: { timeout: 10000 },
+  });
+}
+
+/**
+ * Creates a GitHub client object with convenience methods.
+ * @param {object} params
+ * @param {Octokit} params.octokit - Octokit instance (or mock)
+ * @param {string} params.repo - "owner/repo" string
+ * @returns {object} client with owner, repo, and API methods
+ */
+export function createGitHubClient({ octokit, repo }) {
+  const parts = repo.split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(
+      `Invalid repo format: "${repo}". Expected "owner/repo".`
+    );
+  }
+  const [owner, repoName] = parts;
+
+  return {
+    owner,
+    repo: repoName,
+
+    async getUserInfo() {
+      return limit(async () => {
+        const { data } = await octokit.rest.users.getAuthenticated();
+        return {
+          name: data.name ?? data.login,
+          login: data.login,
+        };
+      });
+    },
+
+    async getFileContent(path) {
+      return limit(async () => {
+        try {
+          const { data } = await octokit.rest.repos.getContent({
+            owner,
+            repo: repoName,
+            path,
+          });
+          const content = Buffer.from(data.content, "base64").toString("utf-8");
+          return { content, sha: data.sha };
+        } catch (err) {
+          if (err.status === 404) return null;
+          throw err;
+        }
+      });
+    },
+
+    async getDirectoryListing(path) {
+      return limit(async () => {
+        try {
+          const { data } = await octokit.rest.repos.getContent({
+            owner,
+            repo: repoName,
+            path,
+          });
+          return Array.isArray(data)
+            ? data.filter((item) => item.type === "file").map((item) => item.name)
+            : [];
+        } catch (err) {
+          if (err.status === 404) return [];
+          throw err;
+        }
+      });
+    },
+
+    async searchCode(query) {
+      return limit(async () => {
+        const { data } = await octokit.rest.search.code({
+          q: `${query} repo:${owner}/${repoName} extension:md`,
+        });
+        return data.items;
+      });
+    },
+
+    async getHeadSHA() {
+      return limit(async () => {
+        const { data } = await octokit.rest.git.getRef({
+          owner,
+          repo: repoName,
+          ref: "heads/main",
+        });
+        return data.object.sha;
+      });
+    },
+
+    async getTreeSHA(commitSHA) {
+      return limit(async () => {
+        const { data } = await octokit.rest.git.getCommit({
+          owner,
+          repo: repoName,
+          commit_sha: commitSHA,
+        });
+        return data.tree.sha;
+      });
+    },
+
+    async createBlob(content) {
+      return limit(async () => {
+        const { data } = await octokit.rest.git.createBlob({
+          owner,
+          repo: repoName,
+          content,
+          encoding: "utf-8",
+        });
+        return data.sha;
+      });
+    },
+
+    async createTree(baseTreeSHA, files) {
+      return limit(async () => {
+        const tree = files.map(({ path, blobSHA }) => ({
+          path,
+          mode: "100644",
+          type: "blob",
+          sha: blobSHA,
+        }));
+        const { data } = await octokit.rest.git.createTree({
+          owner,
+          repo: repoName,
+          base_tree: baseTreeSHA,
+          tree,
+        });
+        return data.sha;
+      });
+    },
+
+    async createCommit(treeSHA, parentSHA, message) {
+      return limit(async () => {
+        const { data } = await octokit.rest.git.createCommit({
+          owner,
+          repo: repoName,
+          message,
+          tree: treeSHA,
+          parents: [parentSHA],
+        });
+        return data.sha;
+      });
+    },
+
+    async updateRef(commitSHA) {
+      return limit(async () => {
+        await octokit.rest.git.updateRef({
+          owner,
+          repo: repoName,
+          ref: "heads/main",
+          sha: commitSHA,
+          force: false,
+        });
+      });
+    },
+
+    async getLastCommitForFile(path) {
+      return limit(async () => {
+        try {
+          const { data } = await octokit.rest.repos.listCommits({
+            owner,
+            repo: repoName,
+            path,
+            per_page: 1,
+          });
+          if (data.length === 0) return null;
+          const commit = data[0].commit;
+          return {
+            author: commit.author.name,
+            date: commit.author.date,
+          };
+        } catch (err) {
+          if (err.status === 404) return null;
+          throw err;
+        }
+      });
+    },
+
+    async getRootDirectoryListing() {
+      return limit(async () => {
+        const { data } = await octokit.rest.repos.getContent({
+          owner,
+          repo: repoName,
+          path: "",
+        });
+        return Array.isArray(data) ? data : [data];
+      });
+    },
+  };
+}

package/lib/root-parser.js

@@ -0,0 +1,323 @@
+/**
+ * Markdown table parser for root.md files.
+ *
+ * Handles parsing, adding, and updating entries in the table of contents
+ * that lives inside each project's root.md file.
+ *
+ * @module root-parser
+ */
+
+/** Regex that matches a separator line like |---|---|---| */
+const SEPARATOR_RE = /^\|?\s*[-:]+\s*(\|\s*[-:]+\s*)+\|?\s*$/;
+
+/** Regex that matches a markdown link [name](file.md) */
+const LINK_RE = /^\[([^\]]+)\]\(([^)]+)\)$/;
+
+/**
+ * Splits a markdown table row into cell values, respecting escaped `\|`.
+ *
+ * Algorithm (from spec):
+ * 1. Remove leading/trailing `|` from the line
+ * 2. Walk character by character:
+ *    - If char is `\` and next char is `|` -> append `|` to current cell, skip next
+ *    - If char is `|` -> push current cell (trimmed) to result, start new cell
+ *    - Otherwise -> append char to current cell
+ * 3. Push final cell (trimmed) to result
+ *
+ * @param {string} line - a single markdown table row
+ * @returns {string[]} array of cell values (trimmed, unescaped)
+ */
+export function splitTableRow(line) {
+  let s = line;
+
+  // Remove leading pipe (with optional whitespace)
+  if (s.startsWith("|")) {
+    s = s.slice(1);
+  }
+  // Remove trailing pipe (with optional whitespace)
+  const trimmedEnd = s.trimEnd();
+  if (trimmedEnd.endsWith("|")) {
+    // Make sure it's not an escaped pipe
+    if (!trimmedEnd.endsWith("\\|")) {
+      s = trimmedEnd.slice(0, -1);
+    }
+  }
+
+  const cells = [];
+  let current = "";
+
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === "\\" && i + 1 < s.length && s[i + 1] === "|") {
+      current += "|";
+      i++; // skip next char
+    } else if (ch === "|") {
+      cells.push(current.trim());
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+
+  // Push the final cell
+  cells.push(current.trim());
+
+  return cells;
+}
+
+/**
+ * Escapes pipe characters in text for safe inclusion in a markdown table cell.
+ * Replaces `|` with `\|`.
+ *
+ * @param {string} text - raw text
+ * @returns {string} escaped text
+ */
+export function escapeTableCell(text) {
+  return text.replace(/\|/g, "\\|");
+}
+
+/**
+ * Reverses pipe escaping. Replaces `\|` with `|`.
+ *
+ * @param {string} text - escaped text
+ * @returns {string} unescaped text
+ */
+export function unescapeTableCell(text) {
+  return text.replace(/\\\|/g, "|");
+}
+
+/**
+ * Finds the table header row in an array of lines and returns the column
+ * index mapping. The header columns can appear in any order.
+ *
+ * @param {string[]} lines - all lines of the markdown document
+ * @returns {{ headerIndex: number, columnMap: Record<string, number> } | null}
+ */
+function findTableHeader(lines) {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    // A header row must contain at least a pipe and the word "Entry"
+    if (!line.includes("|")) continue;
+
+    const cells = splitTableRow(line);
+    const lower = cells.map((c) => c.toLowerCase().trim());
+
+    const entryIdx = lower.indexOf("entry");
+    if (entryIdx === -1) continue;
+
+    // Check that a separator line follows
+    if (i + 1 < lines.length && SEPARATOR_RE.test(lines[i + 1].trim())) {
+      const columnMap = {};
+      for (let j = 0; j < lower.length; j++) {
+        if (lower[j] === "entry") columnMap.entry = j;
+        else if (lower[j] === "description") columnMap.description = j;
+        else if (lower[j] === "tags") columnMap.tags = j;
+      }
+      return { headerIndex: i, columnMap };
+    }
+  }
+  return null;
+}
+
+/**
+ * Parses a root.md markdown string into a structured object.
+ *
+ * @param {string} markdown - full content of root.md
+ * @returns {{ description: string, entries: Array<{ name: string, file: string, description: string, tags: string[] }>, corrupted?: boolean }}
+ */
+export function parseRootMd(markdown) {
+  const lines = markdown.split("\n");
+  const header = findTableHeader(lines);
+
+  if (!header) {
+    return { description: "", entries: [], corrupted: true };
+  }
+
+  const { headerIndex, columnMap } = header;
+
+  // Description = everything before the table header line
+  const descriptionLines = lines.slice(0, headerIndex);
+  // Trim trailing empty lines from description
+  while (
+    descriptionLines.length > 0 &&
+    descriptionLines[descriptionLines.length - 1].trim() === ""
+  ) {
+    descriptionLines.pop();
+  }
+  const description = descriptionLines.join("\n");
+
+  const entries = [];
+
+  // Start parsing from headerIndex + 2 (skip header and separator)
+  for (let i = headerIndex + 2; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line || !line.includes("|")) continue;
+    if (SEPARATOR_RE.test(line)) continue;
+
+    const cells = splitTableRow(lines[i]);
+
+    const entryCell =
+      columnMap.entry !== undefined ? cells[columnMap.entry] ?? "" : "";
+    const descCell =
+      columnMap.description !== undefined
+        ? cells[columnMap.description] ?? ""
+        : "";
+    const tagsCell =
+      columnMap.tags !== undefined ? cells[columnMap.tags] ?? "" : "";
+
+    // Parse entry cell: could be [name](file.md) or plain text
+    const linkMatch = entryCell.match(LINK_RE);
+    let name = "";
+    let file = "";
+    if (linkMatch) {
+      name = linkMatch[1];
+      file = linkMatch[2];
+    } else {
+      name = entryCell;
+      file = "";
+    }
+
+    // Parse tags: split by comma, trim, filter empty
+    const tags = tagsCell
+      .split(",")
+      .map((t) => t.trim())
+      .filter((t) => t.length > 0);
+
+    entries.push({ name, file, description: descCell, tags });
+  }
+
+  return { description, entries };
+}
+
+/**
+ * Adds an entry row to a root.md markdown table. Idempotent: if a row with
+ * the same filename already exists, the markdown is returned unchanged.
+ *
+ * @param {string} markdown - full content of root.md
+ * @param {{ file: string, name: string, description: string, tags: string[] }} entry
+ * @returns {{ updated_markdown: string, was_added: boolean }}
+ */
+export function addEntryToRoot(markdown, entry) {
+  const lines = markdown.split("\n");
+  const header = findTableHeader(lines);
+
+  if (!header) {
+    // If there's no table, we can't add to it
+    return { updated_markdown: markdown, was_added: false };
+  }
+
+  const { headerIndex, columnMap } = header;
+
+  // Check idempotency: does a row with this filename already exist?
+  for (let i = headerIndex + 2; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line || !line.includes("|")) continue;
+    if (SEPARATOR_RE.test(line)) continue;
+
+    const cells = splitTableRow(lines[i]);
+    const entryCell =
+      columnMap.entry !== undefined ? cells[columnMap.entry] ?? "" : "";
+
+    // Check if filename matches (parse link or compare plain text)
+    const linkMatch = entryCell.match(LINK_RE);
+    const existingFile = linkMatch ? linkMatch[2] : "";
+
+    if (existingFile === entry.file) {
+      return { updated_markdown: markdown, was_added: false };
+    }
+  }
+
+  // Build the new row in the correct column order
+  const entryValue = `[${escapeTableCell(entry.name)}](${entry.file})`;
+  const descValue = escapeTableCell(entry.description);
+  const tagsValue = escapeTableCell(entry.tags.join(", "));
+
+  // Determine the number of columns from the header
+  const headerCells = splitTableRow(lines[headerIndex]);
+  const newRowCells = new Array(headerCells.length).fill("");
+
+  if (columnMap.entry !== undefined) newRowCells[columnMap.entry] = entryValue;
+  if (columnMap.description !== undefined)
+    newRowCells[columnMap.description] = descValue;
+  if (columnMap.tags !== undefined) newRowCells[columnMap.tags] = tagsValue;
+
+  const newRow = "| " + newRowCells.join(" | ") + " |";
+
+  // Find the last table row to append after it
+  let lastTableRowIndex = headerIndex + 1; // separator line
+  for (let i = headerIndex + 2; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line.includes("|")) break;
+    lastTableRowIndex = i;
+  }
+
+  // Insert the new row after the last table row
+  const updatedLines = [
+    ...lines.slice(0, lastTableRowIndex + 1),
+    newRow,
+    ...lines.slice(lastTableRowIndex + 1),
+  ];
+
+  return { updated_markdown: updatedLines.join("\n"), was_added: true };
+}
+
+/**
+ * Updates an existing entry row in a root.md markdown table.
+ * Only updates the fields provided in `changes`. Returns the original
+ * markdown if the filename is not found.
+ *
+ * @param {string} markdown - full content of root.md
+ * @param {string} filename - the filename to match (e.g. "overview.md")
+ * @param {{ description?: string, tags?: string[] }} changes
+ * @returns {string} updated markdown
+ */
+export function updateEntryInRoot(markdown, filename, changes) {
+  const lines = markdown.split("\n");
+  const header = findTableHeader(lines);
+
+  if (!header) {
+    return markdown;
+  }
+
+  const { headerIndex, columnMap } = header;
+
+  for (let i = headerIndex + 2; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line || !line.includes("|")) continue;
+    if (SEPARATOR_RE.test(line)) continue;
+
+    const cells = splitTableRow(lines[i]);
+    const entryCell =
+      columnMap.entry !== undefined ? cells[columnMap.entry] ?? "" : "";
+
+    const linkMatch = entryCell.match(LINK_RE);
+    const existingFile = linkMatch ? linkMatch[2] : "";
+
+    if (existingFile !== filename) continue;
+
+    // Found the row — rebuild it with changes applied
+    const headerCells = splitTableRow(lines[headerIndex]);
+    const newCells = new Array(headerCells.length).fill("");
+
+    // Populate all cells from the current row, re-escaping preserved values
+    for (let j = 0; j < headerCells.length; j++) {
+      newCells[j] = escapeTableCell(cells[j] ?? "");
+    }
+
+    // Apply changes (these get escaped as well)
+    if (changes.description !== undefined && columnMap.description !== undefined) {
+      newCells[columnMap.description] = escapeTableCell(changes.description);
+    }
+    if (changes.tags !== undefined && columnMap.tags !== undefined) {
+      newCells[columnMap.tags] = escapeTableCell(changes.tags.join(", "));
+    }
+
+    const updatedRow = "| " + newCells.join(" | ") + " |";
+    lines[i] = updatedRow;
+
+    return lines.join("\n");
+  }
+
+  // Filename not found — return original
+  return markdown;
+}