feat(document-api): insert/replace structural content (#2305)

* feat(document-api): insert/replace structural content cutover with legacy input support

* fix(document-api): avoid empty node IDs in markdownToFragment structural fragments

* fix(document-api): preserve markdown table style metadata in structural writes

* chore: fix doc-api-stories tests

* chore: update docs

Author: harbournick

apps/cli/scripts/export-sdk-contract.ts

@@ -49,6 +49,8 @@ const CLI_PKG_PATH = resolve(CLI_DIR, 'package.json');
 // ---------------------------------------------------------------------------
 
 const INTENT_NAMES = {
+  'doc.get': 'get_document',
+  'doc.markdownToFragment': 'markdown_to_fragment',
   'doc.find': 'find_content',
   'doc.getNode': 'get_node',
   'doc.getNodeById': 'get_node_by_id',

apps/cli/src/__tests__/cli.test.ts

@@ -93,23 +93,54 @@ function hasPrettyProperties(node: unknown): boolean {
 }
 
 async function firstTextRange(args: string[]): Promise<TextRange> {
+  // SDM/1: find returns SDNodeResult with SDAddress. For text searches,
+  // the address is content-level (the containing block). We extract the
+  // blockId and find the pattern position within the node's text content.
   const result = await runCli(args);
   expect(result.code).toBe(0);
 
   const envelope = parseJsonOutput<
     SuccessEnvelope<{
       result: {
-        items?: Array<{ context?: { textRanges?: TextRange[] } }>;
+        items?: Array<{
+          node?: { kind?: string; [key: string]: unknown };
+          address?: { kind?: string; nodeId?: string };
+        }>;
       };
     }>
   >(result);
 
-  const range = envelope.data.result.items?.[0]?.context?.textRanges?.[0];
-  if (!range) {
-    throw new Error('Expected at least one text range from find result.');
+  const item = envelope.data.result.items?.[0];
+  const address = item?.address;
+  if (!address?.nodeId) {
+    throw new Error('Expected at least one match from find result.');
   }
 
-  return range;
+  // Extract concatenated text from the SDM/1 node's inline content
+  const node = item?.node as Record<string, unknown> | undefined;
+  const nodeKind = node?.kind as string | undefined;
+  const kindData = nodeKind ? (node?.[nodeKind] as Record<string, unknown> | undefined) : undefined;
+  const inlines = Array.isArray(kindData?.inlines) ? kindData!.inlines : [];
+  let fullText = '';
+  for (const inline of inlines) {
+    if (typeof inline === 'object' && inline != null && (inline as Record<string, unknown>).kind === 'run') {
+      const runData = (inline as Record<string, unknown>).run as Record<string, unknown> | undefined;
+      if (typeof runData?.text === 'string') fullText += runData.text as string;
+    }
+  }
+
+  // Extract the search pattern from args to find its position within the text
+  const patternIdx = args.indexOf('--pattern');
+  const pattern = patternIdx >= 0 ? args[patternIdx + 1] : undefined;
+  const matchIndex = pattern ? fullText.indexOf(pattern) : -1;
+  const start = matchIndex >= 0 ? matchIndex : 0;
+  const end = matchIndex >= 0 ? matchIndex + pattern!.length : Math.max(fullText.length, 1);
+
+  return {
+    kind: 'text',
+    blockId: address.nodeId,
+    range: { start, end },
+  };
 }
 
 function firstInsertedEntityId(result: RunResult): string {
@@ -263,7 +294,7 @@ describe('superdoc CLI', () => {
     expect(result.code).toBe(0);
     expect(result.stdout).toContain('Parameters:');
     expect(result.stdout).toContain('--session');
-    expect(result.stdout).toContain('--include-nodes');
+    expect(result.stdout).toContain('--limit');
     expect(result.stdout).toContain('Constraints:');
   });
 
@@ -514,13 +545,13 @@ describe('superdoc CLI', () => {
         operationId: string;
         result: {
           document: { source: string };
-          target: TextRange;
+          receipt: { success: boolean };
         };
       }>
     >(callResult);
     expect(envelope.data.operationId).toBe('doc.insert');
     expect(envelope.data.result.document.source).toBe('path');
-    expect(envelope.data.result.target.range.start).toBe(0);
+    expect(envelope.data.result.receipt.success).toBe(true);
 
     const verifyResult = await runCli(['find', out, '--type', 'text', '--pattern', 'CALL_INSERT_TOKEN_1597']);
     expect(verifyResult.code).toBe(0);
@@ -574,8 +605,7 @@ describe('superdoc CLI', () => {
     expect(envelope.ok).toBe(true);
     expect(envelope.command).toBe('find');
     expect(envelope.data.result.total).toBeGreaterThan(0);
-    expect(envelope.data.result.items[0].address.kind).toBe('inline');
-    expect(envelope.data.result.items[0].address.nodeType).toBe('run');
+    expect(envelope.data.result.items[0].node.kind).toBe('run');
   });
 
   test('find rejects legacy query.include payloads', async () => {
@@ -595,7 +625,7 @@ describe('superdoc CLI', () => {
     expect(envelope.error.message).toContain('query.include');
   });
 
-  test('find text queries return context and textRanges without includeNodes', async () => {
+  test('find text queries return content addresses with node projections', async () => {
     const result = await runCli([
       'find',
       SAMPLE_DOC,
@@ -611,21 +641,22 @@ describe('superdoc CLI', () => {
       SuccessEnvelope<{
         result: {
           items?: Array<{
-            context?: {
-              textRanges?: Array<{ kind: 'text'; blockId: string; range: { start: number; end: number } }>;
-            };
+            node?: { kind?: string };
+            address?: { kind?: string; nodeId?: string };
           }>;
         };
       }>
     >(result);
 
-    const firstContext = envelope.data.result.items?.[0]?.context;
-    expect(firstContext).toBeDefined();
-    expect(firstContext?.textRanges?.length).toBeGreaterThan(0);
+    const firstItem = envelope.data.result.items?.[0];
+    expect(firstItem).toBeDefined();
+    expect(firstItem?.address?.kind).toBe('content');
+    expect(firstItem?.address?.nodeId).toBeDefined();
+    expect(firstItem?.node?.kind).toBeDefined();
   });
 
   test('get-node resolves address returned by find', async () => {
-    const findResult = await runCli(['find', SAMPLE_DOC, '--type', 'text', '--pattern', 'Wilde', '--limit', '1']);
+    const findResult = await runCli(['find', SAMPLE_DOC, '--type', 'node', '--node-type', 'paragraph', '--limit', '1']);
     expect(findResult.code).toBe(0);
 
     const findEnvelope = parseJsonOutput<
@@ -639,7 +670,17 @@ describe('superdoc CLI', () => {
     const address = findEnvelope.data.result.items[0]?.address;
     expect(address).toBeDefined();
 
-    const getNodeResult = await runCli(['get-node', SAMPLE_DOC, '--address-json', JSON.stringify(address)]);
+    // SDM/1 addresses use kind: 'content' for block-level nodes
+    // getNode still accepts the old NodeAddress format, so we construct one
+    const nodeId = address?.nodeId as string;
+    expect(nodeId).toBeDefined();
+
+    const getNodeResult = await runCli([
+      'get-node',
+      SAMPLE_DOC,
+      '--address-json',
+      JSON.stringify({ kind: 'block', nodeType: 'paragraph', nodeId }),
+    ]);
     expect(getNodeResult.code).toBe(0);
 
     const nodeEnvelope = parseJsonOutput<SuccessEnvelope<{ node: unknown }>>(getNodeResult);
@@ -649,7 +690,7 @@ describe('superdoc CLI', () => {
   });
 
   test('get-node pretty includes resolved identity and optional node details', async () => {
-    const findResult = await runCli(['find', SAMPLE_DOC, '--type', 'text', '--pattern', 'Wilde', '--limit', '1']);
+    const findResult = await runCli(['find', SAMPLE_DOC, '--type', 'node', '--node-type', 'paragraph', '--limit', '1']);
     expect(findResult.code).toBe(0);
 
     const findEnvelope = parseJsonOutput<
@@ -663,51 +704,53 @@ describe('superdoc CLI', () => {
     expect(address).toBeDefined();
     if (!address) return;
 
+    const nodeId = address.nodeId as string;
+    const blockAddress = { kind: 'block', nodeType: 'paragraph', nodeId };
+
     const prettyResult = await runCli([
       'get-node',
       SAMPLE_DOC,
       '--address-json',
-      JSON.stringify(address),
+      JSON.stringify(blockAddress),
       '--output',
       'pretty',
     ]);
     expect(prettyResult.code).toBe(0);
     expect(prettyResult.stdout).toContain('Revision 0:');
 
-    const jsonResult = await runCli(['get-node', SAMPLE_DOC, '--address-json', JSON.stringify(address)]);
+    const jsonResult = await runCli(['get-node', SAMPLE_DOC, '--address-json', JSON.stringify(blockAddress)]);
     expect(jsonResult.code).toBe(0);
     const jsonEnvelope = parseJsonOutput<SuccessEnvelope<{ node: unknown }>>(jsonResult);
     const node = asRecord(jsonEnvelope.data.node);
-    if (typeof node?.text === 'string' && node.text.length > 0) {
-      expect(prettyResult.stdout).toContain('Text:');
-    }
-    if (hasPrettyProperties(jsonEnvelope.data.node)) {
-      expect(prettyResult.stdout).toContain('Properties:');
+    // SDNodeResult: node is under result.node (which contains { kind, ... })
+    const sdNode = asRecord(node?.node) ?? node;
+    if (sdNode && typeof sdNode.kind === 'string') {
+      expect(prettyResult.stdout).toContain('Revision 0:');
     }
   });
 
   test('get-node-by-id resolves block ID returned by find', async () => {
-    const findResult = await runCli(['find', SAMPLE_DOC, '--type', 'text', '--pattern', 'Wilde', '--limit', '1']);
+    const findResult = await runCli(['find', SAMPLE_DOC, '--type', 'node', '--node-type', 'paragraph', '--limit', '1']);
     expect(findResult.code).toBe(0);
 
     const findEnvelope = parseJsonOutput<
       SuccessEnvelope<{
         result: {
-          items: Array<{ address: { kind: string; nodeType: string; nodeId: string } }>;
+          items: Array<{ node: { kind: string }; address: { kind: string; nodeId: string } }>;
         };
       }>
     >(findResult);
 
-    const firstMatch = findEnvelope.data.result.items[0].address;
-    expect(firstMatch.kind).toBe('block');
+    const firstItem = findEnvelope.data.result.items[0];
+    expect(firstItem.address.kind).toBe('content');
 
     const getByIdResult = await runCli([
       'get-node-by-id',
       SAMPLE_DOC,
       '--id',
-      firstMatch.nodeId,
+      firstItem.address.nodeId,
       '--node-type',
-      firstMatch.nodeType,
+      firstItem.node.kind,
     ]);
     expect(getByIdResult.code).toBe(0);
 
@@ -717,51 +760,44 @@ describe('superdoc CLI', () => {
   });
 
   test('get-node-by-id pretty includes resolved identity and optional node details', async () => {
-    const findResult = await runCli(['find', SAMPLE_DOC, '--type', 'text', '--pattern', 'Wilde', '--limit', '1']);
+    const findResult = await runCli(['find', SAMPLE_DOC, '--type', 'node', '--node-type', 'paragraph', '--limit', '1']);
     expect(findResult.code).toBe(0);
 
     const findEnvelope = parseJsonOutput<
       SuccessEnvelope<{
         result: {
-          items: Array<{ address: { kind: string; nodeType: string; nodeId: string } }>;
+          items: Array<{ node: { kind: string }; address: { kind: string; nodeId: string } }>;
         };
       }>
     >(findResult);
 
-    const firstMatch = findEnvelope.data.result.items[0].address;
-    expect(firstMatch.kind).toBe('block');
+    const firstItem = findEnvelope.data.result.items[0];
+    expect(firstItem.address.kind).toBe('content');
 
     const prettyResult = await runCli([
       'get-node-by-id',
       SAMPLE_DOC,
       '--id',
-      firstMatch.nodeId,
+      firstItem.address.nodeId,
       '--node-type',
-      firstMatch.nodeType,
+      firstItem.node.kind,
       '--output',
       'pretty',
     ]);
     expect(prettyResult.code).toBe(0);
     expect(prettyResult.stdout).toContain('Revision 0:');
-    expect(prettyResult.stdout).toContain(firstMatch.nodeId);
 
     const jsonResult = await runCli([
       'get-node-by-id',
       SAMPLE_DOC,
       '--id',
-      firstMatch.nodeId,
+      firstItem.address.nodeId,
       '--node-type',
-      firstMatch.nodeType,
+      firstItem.node.kind,
     ]);
     expect(jsonResult.code).toBe(0);
     const jsonEnvelope = parseJsonOutput<SuccessEnvelope<{ node: unknown }>>(jsonResult);
-    const node = asRecord(jsonEnvelope.data.node);
-    if (typeof node?.text === 'string' && node.text.length > 0) {
-      expect(prettyResult.stdout).toContain('Text:');
-    }
-    if (hasPrettyProperties(jsonEnvelope.data.node)) {
-      expect(prettyResult.stdout).toContain('Properties:');
-    }
+    expect(jsonEnvelope.data.node).toBeDefined();
   });
 
   test('replace dry-run does not write output file', async () => {
@@ -873,11 +909,17 @@ describe('superdoc CLI', () => {
 
     const insertEnvelope = parseJsonOutput<
       SuccessEnvelope<{
-        target: TextRange;
+        receipt: {
+          success: boolean;
+          resolution?: {
+            target: { anchor?: { start: { offset: number }; end: { offset: number } } };
+          };
+        };
       }>
     >(insertResult);
-    expect(insertEnvelope.data.target.range.start).toBe(0);
-    expect(insertEnvelope.data.target.range.end).toBe(0);
+    expect(insertEnvelope.data.receipt.success).toBe(true);
+    expect(insertEnvelope.data.receipt.resolution?.target.anchor?.start.offset).toBe(0);
+    expect(insertEnvelope.data.receipt.resolution?.target.anchor?.end.offset).toBe(0);
 
     const verifyResult = await runCli([
       'find',
@@ -922,13 +964,19 @@ describe('superdoc CLI', () => {
 
     const insertEnvelope = parseJsonOutput<
       SuccessEnvelope<{
-        target: TextRange;
-        resolvedRange: { from: number; to: number };
+        receipt: {
+          success: boolean;
+          resolution?: {
+            target: { anchor?: { start: { offset: number }; end: { offset: number } } };
+          };
+        };
       }>
     >(insertResult);
 
-    expect(insertEnvelope.data.target.range).toEqual({ start: 0, end: 0 });
-    expect(insertEnvelope.data.resolvedRange.from).toBe(insertEnvelope.data.resolvedRange.to);
+    expect(insertEnvelope.data.receipt.success).toBe(true);
+    const anchor = insertEnvelope.data.receipt.resolution?.target.anchor;
+    expect(anchor?.start.offset).toBe(0);
+    expect(anchor?.end.offset).toBe(0);
 
     const verifyResult = await runCli([
       'find',
@@ -1001,12 +1049,18 @@ describe('superdoc CLI', () => {
 
     const insertEnvelope = parseJsonOutput<
       SuccessEnvelope<{
-        target: TextRange;
+        receipt: {
+          success: boolean;
+          resolution?: {
+            target: { anchor?: { start: { offset: number }; end: { offset: number } } };
+          };
+        };
       }>
     >(insertResult);
     // blockId alone → offset defaults to 0 → collapsed range at start
-    expect(insertEnvelope.data.target.range.start).toBe(0);
-    expect(insertEnvelope.data.target.range.end).toBe(0);
+    expect(insertEnvelope.data.receipt.success).toBe(true);
+    expect(insertEnvelope.data.receipt.resolution?.target.anchor?.start.offset).toBe(0);
+    expect(insertEnvelope.data.receipt.resolution?.target.anchor?.end.offset).toBe(0);
   });
 
   test('insert with --offset but no --block-id returns INVALID_ARGUMENT', async () => {
@@ -1701,11 +1755,17 @@ describe('superdoc CLI', () => {
 
     const insertEnvelope = parseJsonOutput<
       SuccessEnvelope<{
-        target: TextRange;
+        receipt: {
+          success: boolean;
+          resolution?: {
+            target: { anchor?: { start: { offset: number }; end: { offset: number } } };
+          };
+        };
       }>
     >(insertResult);
-    expect(insertEnvelope.data.target.range.start).toBe(0);
-    expect(insertEnvelope.data.target.range.end).toBe(0);
+    expect(insertEnvelope.data.receipt.success).toBe(true);
+    expect(insertEnvelope.data.receipt.resolution?.target.anchor?.start.offset).toBe(0);
+    expect(insertEnvelope.data.receipt.resolution?.target.anchor?.end.offset).toBe(0);
 
     const verifyResult = await runCli(['find', '--type', 'text', '--pattern', 'STATEFUL_DEFAULT_INSERT_1597']);
     expect(verifyResult.code).toBe(0);