feat: fixing response envelope key for SDK operations (#2542)

* feat: fixing response envelope key for SDK operations

- Added `responseEnvelopeKey` to SDK operations to specify which property to unwrap from CLI responses.
- Updated the `buildSdkContract` function to include the new key.
- Adjusted client generation for Node and Python to utilize the `responseEnvelopeKey` for unwrapping responses.
- Enhanced tests to ensure integrity of the `responseEnvelopeKey` across operations, verifying its presence and correctness.

* fix(cli): preserve doc.find selector shorthand with schema validation

Author: andrii-harbour

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

@@ -29,6 +29,7 @@ import {
 } from '../src/cli/operation-set';
 import type { CliOnlyOperation } from '../src/cli/types';
 import { CLI_ONLY_OPERATION_DEFINITIONS } from '../src/cli/cli-only-operation-definitions';
+import { RESPONSE_ENVELOPE_KEY } from '../src/cli/operation-hints';
 import { HOST_PROTOCOL_VERSION, HOST_PROTOCOL_FEATURES, HOST_PROTOCOL_NOTIFICATIONS } from '../src/host/protocol';
 
 // ---------------------------------------------------------------------------
@@ -105,6 +106,10 @@ function buildSdkContract() {
       requiresDocumentContext: cliRequiresDocumentContext(cliOpId),
       docRequirement: metadata.docRequirement,
 
+      // Response envelope key — tells SDKs which property to unwrap from the CLI response.
+      // null means result is spread across top-level keys (no unwrapping needed).
+      responseEnvelopeKey: docApiId ? (RESPONSE_ENVELOPE_KEY[docApiId] ?? null) : null,
+
       // Transport plane
       params: metadata.params.map((p) => {
         const spec: Record<string, unknown> = {

apps/cli/src/__tests__/lib/find-query.test.ts

@@ -34,4 +34,26 @@ describe('resolveFindQuery', () => {
   test('treats null --select-json as provided and validates the payload shape', async () => {
     await expect(resolveFindQuery(makeParsed({ 'select-json': 'null' }))).rejects.toThrow(CliError);
   });
+
+  test('normalizes shorthand node selector from --select-json', async () => {
+    const query = await resolveFindQuery(makeParsed({ 'select-json': JSON.stringify({ type: 'paragraph' }) }));
+    expect(query).toEqual({
+      select: { type: 'node', nodeType: 'paragraph' },
+    });
+  });
+
+  test('passes through canonical node selector from --select-json', async () => {
+    const query = await resolveFindQuery(
+      makeParsed({ 'select-json': JSON.stringify({ type: 'node', nodeType: 'heading' }) }),
+    );
+    expect(query).toEqual({
+      select: { type: 'node', nodeType: 'heading' },
+    });
+  });
+
+  test('rejects invalid shorthand node type from --select-json', async () => {
+    await expect(resolveFindQuery(makeParsed({ 'select-json': JSON.stringify({ type: 'magic' }) }))).rejects.toThrow(
+      CliError,
+    );
+  });
 });

apps/cli/src/__tests__/lib/validate-type-spec.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import { validateValueAgainstTypeSpec } from '../../lib/operation-args';
 import { CliError } from '../../lib/errors';
 import type { CliTypeSpec } from '../../cli/types';
+import { CLI_OPERATION_METADATA } from '../../cli/operation-params';
 
 describe('validateValueAgainstTypeSpec – oneOf const enumeration', () => {
   const schema: CliTypeSpec = {
@@ -91,3 +92,53 @@ describe('validateValueAgainstTypeSpec – enum branch', () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// doc.find select schema override
+// ---------------------------------------------------------------------------
+
+describe('doc.find select schema — accepts canonical and shorthand forms', () => {
+  const metadata = CLI_OPERATION_METADATA['doc.find'];
+  const selectParam = metadata.params.find((p) => p.name === 'select');
+  const schema = selectParam?.schema;
+
+  if (!schema) throw new Error('doc.find metadata missing select param with schema');
+
+  test('accepts canonical text selector', () => {
+    expect(() => validateValueAgainstTypeSpec({ type: 'text', pattern: 'hello' }, schema, 'select')).not.toThrow();
+  });
+
+  test('accepts canonical text selector with all optional fields', () => {
+    expect(() =>
+      validateValueAgainstTypeSpec(
+        { type: 'text', pattern: 'hello', mode: 'regex', caseSensitive: true },
+        schema,
+        'select',
+      ),
+    ).not.toThrow();
+  });
+
+  test('accepts canonical node selector', () => {
+    expect(() => validateValueAgainstTypeSpec({ type: 'node', nodeType: 'heading' }, schema, 'select')).not.toThrow();
+  });
+
+  test('accepts canonical node selector with kind', () => {
+    expect(() => validateValueAgainstTypeSpec({ type: 'node', kind: 'block' }, schema, 'select')).not.toThrow();
+  });
+
+  test('accepts shorthand node selector', () => {
+    expect(() => validateValueAgainstTypeSpec({ type: 'paragraph' }, schema, 'select')).not.toThrow();
+  });
+
+  test('accepts shorthand for inline node type', () => {
+    expect(() => validateValueAgainstTypeSpec({ type: 'hyperlink' }, schema, 'select')).not.toThrow();
+  });
+
+  test('rejects invalid shorthand node type', () => {
+    expect(() => validateValueAgainstTypeSpec({ type: 'magic' }, schema, 'select')).toThrow(CliError);
+  });
+
+  test('rejects text selector missing required pattern', () => {
+    expect(() => validateValueAgainstTypeSpec({ type: 'text' }, schema, 'select')).toThrow(CliError);
+  });
+});

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

@@ -12,6 +12,7 @@
 import {
   buildInternalContractSchemas,
   COMMAND_CATALOG,
+  NODE_TYPES,
   OPERATION_REQUIRES_DOCUMENT_CONTEXT_MAP,
   type OperationId,
 } from '@superdoc/document-api';
@@ -446,7 +447,47 @@ const PARAM_FLAG_OVERRIDES: Partial<Record<string, Record<string, { name?: strin
 // adjustment for CLI metadata (e.g. simplifying or enriching).
 // ---------------------------------------------------------------------------
 
-const PARAM_SCHEMA_OVERRIDES: Partial<Record<string, Record<string, CliTypeSpec>>> = {};
+// The document-api contract schema for `select` is a strict oneOf(text, node)
+// that rejects shorthand selectors like `{ type: "paragraph" }`. The CLI
+// normalizes these shorthands in resolveFindQuery() → validateQuery(), so
+// the schema-level validation must accept all three supported forms.
+const DOC_FIND_SELECT_SCHEMA: CliTypeSpec = {
+  oneOf: [
+    // { type: 'text', pattern: '...', mode?, caseSensitive? }
+    {
+      type: 'object',
+      properties: {
+        type: { const: 'text' },
+        pattern: { type: 'string' },
+        mode: { oneOf: [{ const: 'contains' }, { const: 'regex' }] },
+        caseSensitive: { type: 'boolean' },
+      },
+      required: ['type', 'pattern'],
+    },
+    // { type: 'node', nodeType?, kind? }
+    {
+      type: 'object',
+      properties: {
+        type: { const: 'node' },
+        nodeType: { type: 'string' },
+        kind: { oneOf: [{ const: 'block' }, { const: 'inline' }] },
+      },
+      required: ['type'],
+    },
+    // Shorthand: { type: '<NodeType>' } — normalized to { type: 'node', nodeType }
+    {
+      type: 'object',
+      properties: {
+        type: { oneOf: NODE_TYPES.map((t) => ({ const: t }) as CliTypeSpec) },
+      },
+      required: ['type'],
+    },
+  ],
+};
+
+const PARAM_SCHEMA_OVERRIDES: Partial<Record<string, Record<string, CliTypeSpec>>> = {
+  'doc.find': { select: DOC_FIND_SELECT_SCHEMA },
+};
 
 // ---------------------------------------------------------------------------
 // Schema-derived param exclusions
@@ -455,11 +496,7 @@ const PARAM_SCHEMA_OVERRIDES: Partial<Record<string, Record<string, CliTypeSpec>
 // exposed in CLI metadata because the CLI provides an alternative interface.
 // ---------------------------------------------------------------------------
 
-const PARAM_EXCLUSIONS: Partial<Record<string, ReadonlySet<string>>> = {
-  // CLI uses flat flags (--type, --pattern, --mode) or --query-json; `select`
-  // is an internal document-api field that the invoker builds from flat flags.
-  'doc.find': new Set(['select']),
-};
+const PARAM_EXCLUSIONS: Partial<Record<string, ReadonlySet<string>>> = {};
 
 // ---------------------------------------------------------------------------
 // Extra CLI-specific params for doc-backed operations
@@ -494,36 +531,47 @@ const FORMAT_OPERATION_IDS = CLI_DOC_OPERATIONS.filter((operationId): operationI
 );
 
 const EXTRA_CLI_PARAMS: Partial<Record<string, CliOperationParamSpec[]>> = {
+  // Flat flags are CLI convenience alternatives to --select-json. Marked
+  // agentVisible: false so that if doc.find is ever exposed as a tool
+  // (currently skipAsATool), agents see only the structured `select` param.
   'doc.find': [
     {
       name: 'type',
       kind: 'flag',
       type: 'string',
       description: "Selector type: 'text' for text search or 'node' for node type search.",
+      agentVisible: false,
     },
     {
       name: 'nodeType',
       kind: 'flag',
       flag: 'node-type',
       type: 'string',
       description: 'Node type to match (paragraph, heading, table, listItem, etc.).',
+      agentVisible: false,
+    },
+    { name: 'kind', kind: 'flag', type: 'string', description: "Filter: 'block' or 'inline'.", agentVisible: false },
+    {
+      name: 'pattern',
+      kind: 'flag',
+      type: 'string',
+      description: 'Text or regex pattern to match.',
+      agentVisible: false,
+    },
+    {
+      name: 'mode',
+      kind: 'flag',
+      type: 'string',
+      description: "Match mode: 'contains' (substring) or 'regex'.",
+      agentVisible: false,
     },
-    { name: 'kind', kind: 'flag', type: 'string', description: "Filter: 'block' or 'inline'." },
-    { name: 'pattern', kind: 'flag', type: 'string', description: 'Text or regex pattern to match.' },
-    { name: 'mode', kind: 'flag', type: 'string', description: "Match mode: 'contains' (substring) or 'regex'." },
     {
       name: 'caseSensitive',
       kind: 'flag',
       flag: 'case-sensitive',
       type: 'boolean',
       description: 'Case-sensitive matching. Default: false.',
-    },
-    {
-      name: 'select',
-      kind: 'jsonFlag',
-      flag: 'select-json',
-      type: 'json',
-      description: "Search selector as JSON: {type:'text', pattern:'...'} or {type:'node', nodeType:'...'}.",
+      agentVisible: false,
     },
     { name: 'query', kind: 'jsonFlag', flag: 'query-json', type: 'json', description: 'Query filter as JSON object.' },
   ],