feat(document-api): support deleting entire block nodes not only text (#2181)

* feat(document-api): node deletion

* fix(document-api): include blocks.delete INVALID_INPUT in contract and CLI mapping

* test(doc-api-stories): add block deletion test

* fix(document-api): validate nodeId in blocks.delete and add blocks to CLI help

* fix(document-api): remove image from deletable block types

* chore: fix tests in ci

Author: harbournick

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

@@ -58,6 +58,7 @@ const INTENT_NAMES = {
   'doc.insert': 'insert_content',
   'doc.replace': 'replace_content',
   'doc.delete': 'delete_content',
+  'doc.blocks.delete': 'delete_block',
   'doc.format.apply': 'format_apply',
   'doc.format.fontSize': 'format_font_size',
   'doc.format.fontFamily': 'format_font_family',

apps/cli/src/__tests__/conformance/scenarios.ts

@@ -291,6 +291,23 @@ export const SUCCESS_SCENARIOS = {
       ],
     };
   },
+  'doc.blocks.delete': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-blocks-delete-success');
+    const docPath = await harness.copyFixtureDoc('doc-blocks-delete');
+    const block = await harness.firstBlockMatch(docPath, stateDir);
+    return {
+      stateDir,
+      args: [
+        'blocks',
+        'delete',
+        docPath,
+        '--target-json',
+        JSON.stringify({ kind: 'block', nodeType: block.nodeType, nodeId: block.nodeId }),
+        '--out',
+        harness.createOutputPath('doc-blocks-delete-output'),
+      ],
+    };
+  },
   'doc.lists.list': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
     const stateDir = await harness.createStateDir('doc-lists-list-success');
     const docPath = await harness.copyListFixtureDoc('doc-lists-list');

apps/cli/src/__tests__/help-regression.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from 'bun:test';
+import { CLI_COMMAND_SPECS, CLI_HELP } from '../cli/commands';
+
+describe('CLI help regression coverage', () => {
+  test('includes blocks.delete in help output', () => {
+    const blocksDeleteCommand = CLI_COMMAND_SPECS.find(
+      (spec) => !spec.alias && spec.operationId === 'doc.blocks.delete',
+    );
+
+    expect(blocksDeleteCommand).toBeDefined();
+    expect(CLI_HELP).toContain('blocks:');
+    expect(CLI_HELP).toContain(blocksDeleteCommand!.key);
+  });
+});

apps/cli/src/__tests__/lib/error-mapping.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from 'bun:test';
+import { mapInvokeError } from '../../lib/error-mapping';
+
+describe('mapInvokeError', () => {
+  test('maps blocks.delete INVALID_INPUT errors to INVALID_ARGUMENT', () => {
+    const error = Object.assign(new Error('blocks.delete requires a target.'), {
+      code: 'INVALID_INPUT',
+      details: { field: 'target' },
+    });
+
+    const mapped = mapInvokeError('blocks.delete', error);
+    expect(mapped.code).toBe('INVALID_ARGUMENT');
+    expect(mapped.message).toBe('blocks.delete requires a target.');
+    expect(mapped.details).toEqual({ operationId: 'blocks.delete', details: { field: 'target' } });
+  });
+});

apps/cli/src/cli/commands.ts

@@ -162,6 +162,7 @@ function buildHelpText(): string {
     'mutation',
     'format',
     'create',
+    'blocks',
     'lists',
     'comments',
     'trackChanges',

apps/cli/src/cli/operation-hints.ts

@@ -35,6 +35,7 @@ export const SUCCESS_VERB: Record<CliExposedOperationId, string> = {
   insert: 'inserted text',
   replace: 'replaced text',
   delete: 'deleted text',
+  'blocks.delete': 'deleted block',
   'format.apply': 'applied style',
   'format.fontSize': 'set font size',
   'format.fontFamily': 'set font family',
@@ -96,6 +97,7 @@ export const OUTPUT_FORMAT: Record<CliExposedOperationId, OutputFormat> = {
   insert: 'mutationReceipt',
   replace: 'mutationReceipt',
   delete: 'mutationReceipt',
+  'blocks.delete': 'plain',
   'format.apply': 'mutationReceipt',
   'format.fontSize': 'mutationReceipt',
   'format.fontFamily': 'mutationReceipt',
@@ -145,6 +147,7 @@ export const RESPONSE_ENVELOPE_KEY: Record<CliExposedOperationId, string | null>
   insert: null,
   replace: null,
   delete: null,
+  'blocks.delete': 'result',
   'format.apply': null,
   'format.fontSize': null,
   'format.fontFamily': null,
@@ -204,7 +207,15 @@ export const RESPONSE_VALIDATION_KEY: Partial<Record<CliExposedOperationId, stri
  * Operation family — determines which error-mapping rules apply.
  * Explicit Record for compile-time completeness (no string-prefix heuristics).
  */
-export type OperationFamily = 'trackChanges' | 'comments' | 'lists' | 'textMutation' | 'create' | 'query' | 'general';
+export type OperationFamily =
+  | 'trackChanges'
+  | 'comments'
+  | 'lists'
+  | 'textMutation'
+  | 'create'
+  | 'blocks'
+  | 'query'
+  | 'general';
 
 export const OPERATION_FAMILY: Record<CliExposedOperationId, OperationFamily> = {
   find: 'query',
@@ -215,6 +226,7 @@ export const OPERATION_FAMILY: Record<CliExposedOperationId, OperationFamily> =
   insert: 'textMutation',
   replace: 'textMutation',
   delete: 'textMutation',
+  'blocks.delete': 'blocks',
   'format.apply': 'textMutation',
   'format.fontSize': 'textMutation',
   'format.fontFamily': 'textMutation',

apps/cli/src/cli/operation-params.ts

@@ -375,6 +375,10 @@ const EXTRA_CLI_PARAMS: Partial<Record<string, CliOperationParamSpec[]>> = {
     ...LIST_TARGET_FLAT_PARAMS,
   ],
   'doc.lists.exit': [{ name: 'input', kind: 'jsonFlag', flag: 'input-json', type: 'json' }, ...LIST_TARGET_FLAT_PARAMS],
+  'doc.blocks.delete': [
+    { name: 'nodeType', kind: 'flag', flag: 'node-type', type: 'string' },
+    { name: 'nodeId', kind: 'flag', flag: 'node-id', type: 'string' },
+  ],
   'doc.create.paragraph': [{ name: 'input', kind: 'jsonFlag', flag: 'input-json', type: 'json' }],
   'doc.create.heading': [{ name: 'input', kind: 'jsonFlag', flag: 'input-json', type: 'json' }],
 };

apps/cli/src/cli/types.ts

@@ -119,6 +119,7 @@ export type CliCategory =
   | 'mutation'
   | 'format'
   | 'create'
+  | 'blocks'
   | 'lists'
   | 'comments'
   | 'trackChanges'

apps/cli/src/lib/error-mapping.ts

@@ -133,10 +133,46 @@ function mapCreateError(operationId: CliExposedOperationId, error: unknown, code
     return new CliError('INVALID_ARGUMENT', message, { operationId, details });
   }
 
-  if (code === 'TRACK_CHANGE_COMMAND_UNAVAILABLE' || code === 'CAPABILITY_UNAVAILABLE') {
+  if (code === 'TRACK_CHANGE_COMMAND_UNAVAILABLE') {
     return new CliError('TRACK_CHANGE_COMMAND_UNAVAILABLE', message, { operationId, details });
   }
 
+  if (code === 'CAPABILITY_UNAVAILABLE') {
+    const reason = (details as { reason?: string } | undefined)?.reason;
+    if (reason === 'tracked_mode_unsupported') {
+      return new CliError('TRACK_CHANGE_COMMAND_UNAVAILABLE', message, { operationId, details });
+    }
+    return new CliError('COMMAND_FAILED', message, { operationId, details });
+  }
+
+  if (code === 'COMMAND_UNAVAILABLE') {
+    return new CliError('COMMAND_FAILED', message, { operationId, details });
+  }
+
+  if (error instanceof CliError) return error;
+  return new CliError('COMMAND_FAILED', message, { operationId, details });
+}
+
+function mapBlocksError(operationId: CliExposedOperationId, error: unknown, code: string | undefined): CliError {
+  const message = extractErrorMessage(error);
+  const details = extractErrorDetails(error);
+
+  if (code === 'TARGET_NOT_FOUND') {
+    return new CliError('TARGET_NOT_FOUND', message, { operationId, details });
+  }
+
+  if (code === 'AMBIGUOUS_TARGET' || code === 'INVALID_TARGET' || code === 'INVALID_INPUT') {
+    return new CliError('INVALID_ARGUMENT', message, { operationId, details });
+  }
+
+  if (code === 'CAPABILITY_UNAVAILABLE') {
+    const reason = (details as { reason?: string } | undefined)?.reason;
+    if (reason === 'tracked_mode_unsupported') {
+      return new CliError('TRACK_CHANGE_COMMAND_UNAVAILABLE', message, { operationId, details });
+    }
+    return new CliError('COMMAND_FAILED', message, { operationId, details });
+  }
+
   if (code === 'COMMAND_UNAVAILABLE') {
     return new CliError('COMMAND_FAILED', message, { operationId, details });
   }
@@ -170,6 +206,7 @@ const FAMILY_MAPPERS: Record<
   lists: mapListsError,
   textMutation: mapTextMutationError,
   create: mapCreateError,
+  blocks: mapBlocksError,
   query: mapQueryError,
   general: (operationId, error) => {
     if (error instanceof CliError) return error;
@@ -272,6 +309,14 @@ export function mapFailedReceipt(operationId: CliExposedOperationId, result: unk
     return new CliError('COMMAND_FAILED', failureMessage, { operationId, failure });
   }
 
+  // Blocks family
+  if (family === 'blocks') {
+    if (failureCode === 'INVALID_TARGET') {
+      return new CliError('INVALID_ARGUMENT', failureMessage, { operationId, failure });
+    }
+    return new CliError('COMMAND_FAILED', failureMessage, { operationId, failure });
+  }
+
   // Create family
   if (family === 'create') {
     if (failureCode === 'TRACK_CHANGE_COMMAND_UNAVAILABLE') {

apps/cli/src/lib/invoke-input.ts

@@ -147,6 +147,20 @@ function normalizeFlatTargetFlags(operationId: CliExposedOperationId, apiInput:
     return apiInput;
   }
 
+  // --- Block delete (nodeType + nodeId → block target) ---
+  if (operationId === 'blocks.delete') {
+    const nodeType = apiInput.nodeType;
+    const nodeId = apiInput.nodeId;
+    if (typeof nodeType === 'string' && typeof nodeId === 'string') {
+      const { nodeType: _, nodeId: _n, ...rest } = apiInput;
+      return {
+        ...rest,
+        target: { kind: 'block', nodeType, nodeId },
+      };
+    }
+    return apiInput;
+  }
+
   // --- List operations (nodeId → listItem block target) ---
   if (LIST_TARGET_OPERATIONS.has(operationId)) {
     const nodeId = apiInput.nodeId;