Merge pull request '#114 refactor(ai-chat): shared parseNodeArg helper; keep duplication backlog doc' (#114) from refactor/ai-chat-tool-spec-registry into develop

# Conflicts:
#	apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts

apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts

@@ -13,6 +13,7 @@ import {
   type DocmostClientLike,
 } from './docmost-client.loader';
 import { resolveCurrentPageResult } from './current-page.util';
+import { parseNodeArg } from './parse-node-arg';
 
 /**
  * Per-user, per-request adapter that exposes Docmost READ operations to the
@@ -705,14 +706,7 @@ export class AiChatToolsService {
           // Parity with the standalone MCP server (index.ts patch_node): the
           // model sometimes serializes the node as a JSON string. Parse it
           // before the client's typeof-object guard rejects it.
-          let parsedNode = node;
-          if (typeof node === 'string') {
-            try {
-              parsedNode = JSON.parse(node);
-            } catch {
-              throw new Error('node was a string but not valid JSON');
-            }
-          }
+          const parsedNode = parseNodeArg(node);
           return await client.patchNode(pageId, nodeId, parsedNode);
         },
       }),
@@ -764,14 +758,7 @@ export class AiChatToolsService {
           // Parity with the standalone MCP server (index.ts insert_node): the
           // model sometimes serializes the node as a JSON string. Parse it
           // before the client's typeof-object guard rejects it.
-          let parsedNode = node;
-          if (typeof node === 'string') {
-            try {
-              parsedNode = JSON.parse(node);
-            } catch {
-              throw new Error('node was a string but not valid JSON');
-            }
-          }
+          const parsedNode = parseNodeArg(node);
           return await client.insertNode(pageId, parsedNode, {
             position,
             anchorNodeId,
@@ -820,14 +807,9 @@ export class AiChatToolsService {
           let doc;
           if (content === undefined || content === null) {
             doc = undefined;
-          } else if (typeof content === 'string') {
-            try {
-              doc = JSON.parse(content);
-            } catch {
-              throw new Error('content was a string but not valid JSON');
-            }
           } else {
-            doc = content;
+            // String -> JSON.parse (throwing on invalid); object passes through.
+            doc = parseNodeArg(content, 'content was a string but not valid JSON');
           }
           return await client.updatePageJson(pageId, doc, title);
         },

apps/server/src/core/ai-chat/tools/parse-node-arg.spec.ts

@@ -0,0 +1,37 @@
+import { parseNodeArg } from './parse-node-arg';
+
+/**
+ * Unit tests for the in-app `parseNodeArg` helper. It mirrors the standalone
+ * MCP helper (packages/mcp/src/lib/parse-node-arg.ts) and is used by the
+ * patchNode / insertNode / updatePageJson tool adapters. Behavior must be
+ * byte-identical: object passthrough, valid-string parse, invalid-string throw.
+ */
+describe('parseNodeArg', () => {
+  it('passes an object through unchanged', () => {
+    const obj = { type: 'paragraph', content: [] };
+    expect(parseNodeArg(obj)).toBe(obj);
+  });
+
+  it('passes undefined/null through unchanged', () => {
+    expect(parseNodeArg(undefined)).toBeUndefined();
+    expect(parseNodeArg(null)).toBeNull();
+  });
+
+  it('parses a valid JSON string into an object', () => {
+    expect(parseNodeArg('{"type":"paragraph"}')).toEqual({
+      type: 'paragraph',
+    });
+  });
+
+  it('throws the default message on an invalid JSON string', () => {
+    expect(() => parseNodeArg('{not json')).toThrow(
+      'node was a string but not valid JSON',
+    );
+  });
+
+  it('throws a custom message on an invalid JSON string', () => {
+    expect(() =>
+      parseNodeArg('{not json', 'content was a string but not valid JSON'),
+    ).toThrow('content was a string but not valid JSON');
+  });
+});

apps/server/src/core/ai-chat/tools/parse-node-arg.ts

@@ -0,0 +1,26 @@
+// The model sometimes serializes a ProseMirror node arg as a JSON string
+// instead of an object. Normalize: parse a string to an object (throwing on
+// invalid JSON), pass an object through unchanged. Shared by patchNode /
+// insertNode (and the analogous updatePageJson content parsing).
+//
+// This is behaviorally identical to `packages/mcp/src/lib/parse-node-arg.ts`
+// (the function logic, default/explicit throw messages and branch order match;
+// only comments and quote style differ). We cannot import that helper here:
+// `@docmost/mcp` is ESM-only and this server
+// compiles with module:commonjs, so it is loaded at runtime via the
+// `new Function('import()')` trick (see docmost-client.loader.ts). Sharing
+// runtime code across that ESM/CJS boundary by a normal import is impossible,
+// hence the mirrored copy.
+export function parseNodeArg(
+  node: unknown,
+  errMsg = 'node was a string but not valid JSON',
+): unknown {
+  if (typeof node === 'string') {
+    try {
+      return JSON.parse(node);
+    } catch {
+      throw new Error(errMsg);
+    }
+  }
+  return node;
+}