Merge branch 'main' into nick/sd-1972-lists-structure-numbering-semantics-document-api-commands

Author: harbournick

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

@@ -138,6 +138,11 @@ const INTENT_NAMES = {
   'doc.toc.configure': 'configure_table_of_contents',
   'doc.toc.update': 'update_table_of_contents',
   'doc.toc.remove': 'remove_table_of_contents',
+  'doc.toc.markEntry': 'mark_table_of_contents_entry',
+  'doc.toc.unmarkEntry': 'unmark_table_of_contents_entry',
+  'doc.toc.listEntries': 'list_table_of_contents_entries',
+  'doc.toc.getEntry': 'get_table_of_contents_entry',
+  'doc.toc.editEntry': 'edit_table_of_contents_entry',
   'doc.query.match': 'query_match',
   'doc.mutations.preview': 'preview_mutations',
   'doc.mutations.apply': 'apply_mutations',
@@ -181,6 +186,9 @@ const INTENT_NAMES = {
   'doc.tables.get': 'get_table',
   'doc.tables.getCells': 'get_table_cells',
   'doc.tables.getProperties': 'get_table_properties',
+  'doc.history.get': 'get_history',
+  'doc.history.undo': 'undo',
+  'doc.history.redo': 'redo',
 } as const satisfies Record<DocBackedCliOpId, string>;
 
 // ---------------------------------------------------------------------------

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

@@ -14,6 +14,7 @@ export type OperationScenario = {
   success: (harness: ConformanceHarness) => Promise<ScenarioInvocation>;
   failure: (harness: ConformanceHarness) => Promise<ScenarioInvocation>;
   expectedFailureCodes: string[];
+  skipRuntimeConformance?: boolean;
 };
 
 function commandTokens(operationId: CliOperationId): string[] {
@@ -456,6 +457,73 @@ function tocReadWithTargetScenario(op: string): (harness: ConformanceHarness) =>
   };
 }
 
+type TocEntryAddress = {
+  kind: 'inline';
+  nodeType: 'tableOfContentsEntry';
+  nodeId: string;
+};
+
+function buildTocEntryInsertionTarget(paragraphNodeId: string): Record<string, unknown> {
+  return {
+    kind: 'inline-insert',
+    anchor: {
+      nodeType: 'paragraph',
+      nodeId: paragraphNodeId,
+    },
+    position: 'end',
+  };
+}
+
+async function createDocWithMarkedTocEntry(
+  harness: ConformanceHarness,
+  stateDir: string,
+  label: string,
+): Promise<{ docPath: string; entryAddress: TocEntryAddress }> {
+  const sourceDoc = await harness.copyFixtureDoc(`${label}-source`);
+  const textTarget = await harness.firstTextRange(sourceDoc, stateDir);
+  const markedDoc = harness.createOutputPath(`${label}-marked`);
+
+  const mark = await harness.runCli(
+    [
+      ...commandTokens('doc.toc.markEntry'),
+      sourceDoc,
+      '--target-json',
+      JSON.stringify(buildTocEntryInsertionTarget(textTarget.blockId)),
+      '--text',
+      'Conformance TC Entry',
+      '--level',
+      '2',
+      '--out',
+      markedDoc,
+    ],
+    stateDir,
+  );
+  if (mark.result.code !== 0 || mark.envelope.ok !== true) {
+    throw new Error(`Failed to seed toc entry fixture for ${label}.`);
+  }
+
+  const listed = await harness.runCli([...commandTokens('doc.toc.listEntries'), markedDoc, '--limit', '1'], stateDir);
+  if (listed.result.code !== 0 || listed.envelope.ok !== true) {
+    throw new Error(`Failed to list toc entries for ${label}.`);
+  }
+
+  const entryAddress = (
+    listed.envelope.data as {
+      result?: {
+        items?: Array<{
+          address?: TocEntryAddress;
+        }>;
+      };
+    }
+  ).result?.items?.[0]?.address;
+
+  if (!entryAddress) {
+    throw new Error(`No toc entry address found for ${label}.`);
+  }
+
+  return { docPath: markedDoc, entryAddress };
+}
+
 export const SUCCESS_SCENARIOS = {
   'doc.open': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
     const stateDir = await harness.createStateDir('doc-open-success');
@@ -1557,6 +1625,81 @@ export const SUCCESS_SCENARIOS = {
   'doc.toc.configure': tocMutationScenario('toc.configure', ['--patch-json', JSON.stringify({ hyperlinks: false })]),
   'doc.toc.update': tocMutationScenario('toc.update', []),
   'doc.toc.remove': tocMutationScenario('toc.remove', []),
+  'doc.toc.markEntry': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-toc-mark-entry-success');
+    const docPath = await harness.copyFixtureDoc('doc-toc-mark-entry');
+    const textTarget = await harness.firstTextRange(docPath, stateDir);
+    return {
+      stateDir,
+      args: [
+        ...commandTokens('doc.toc.markEntry'),
+        docPath,
+        '--target-json',
+        JSON.stringify(buildTocEntryInsertionTarget(textTarget.blockId)),
+        '--text',
+        'Conformance mark-entry',
+        '--level',
+        '2',
+        '--table-identifier',
+        'A',
+        '--out',
+        harness.createOutputPath('doc-toc-mark-entry-output'),
+      ],
+    };
+  },
+  'doc.toc.unmarkEntry': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-toc-unmark-entry-success');
+    const fixture = await createDocWithMarkedTocEntry(harness, stateDir, 'doc-toc-unmark-entry');
+    return {
+      stateDir,
+      args: [
+        ...commandTokens('doc.toc.unmarkEntry'),
+        fixture.docPath,
+        '--target-json',
+        JSON.stringify(fixture.entryAddress),
+        '--out',
+        harness.createOutputPath('doc-toc-unmark-entry-output'),
+      ],
+    };
+  },
+  'doc.toc.listEntries': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-toc-list-entries-success');
+    const docPath = await harness.copyFixtureDoc('doc-toc-list-entries');
+    return {
+      stateDir,
+      args: [...commandTokens('doc.toc.listEntries'), docPath, '--limit', '10'],
+    };
+  },
+  'doc.toc.getEntry': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-toc-get-entry-success');
+    const fixture = await createDocWithMarkedTocEntry(harness, stateDir, 'doc-toc-get-entry');
+    return {
+      stateDir,
+      args: [
+        ...commandTokens('doc.toc.getEntry'),
+        fixture.docPath,
+        '--target-json',
+        JSON.stringify(fixture.entryAddress),
+      ],
+    };
+  },
+  'doc.toc.editEntry': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-toc-edit-entry-success');
+    const fixture = await createDocWithMarkedTocEntry(harness, stateDir, 'doc-toc-edit-entry');
+    return {
+      stateDir,
+      args: [
+        ...commandTokens('doc.toc.editEntry'),
+        fixture.docPath,
+        '--target-json',
+        JSON.stringify(fixture.entryAddress),
+        '--patch-json',
+        JSON.stringify({ text: 'Edited Conformance TC Entry', level: 3 }),
+        '--out',
+        harness.createOutputPath('doc-toc-edit-entry-output'),
+      ],
+    };
+  },
   'doc.session.list': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
     const stateDir = await harness.createStateDir('doc-session-list-success');
     await harness.openSessionFixture(stateDir, 'doc-session-list', 'session-list-success');
@@ -1746,14 +1889,41 @@ export const SUCCESS_SCENARIOS = {
   'doc.tables.get': tableReadScenario('tables.get'),
   'doc.tables.getCells': tableReadScenario('tables.getCells'),
   'doc.tables.getProperties': tableReadScenario('tables.getProperties'),
+
+  // ---------------------------------------------------------------------------
+  // History operations
+  // ---------------------------------------------------------------------------
+
+  'doc.history.get': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-history-get-success');
+    await harness.openSessionFixture(stateDir, 'doc-history-get', 'history-get-session');
+    return { stateDir, args: ['history', 'get', '--session', 'history-get-session'] };
+  },
+  'doc.history.undo': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-history-undo-success');
+    await harness.openSessionFixture(stateDir, 'doc-history-undo', 'history-undo-session');
+    return { stateDir, args: ['history', 'undo', '--session', 'history-undo-session'] };
+  },
+  'doc.history.redo': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-history-redo-success');
+    await harness.openSessionFixture(stateDir, 'doc-history-redo', 'history-redo-session');
+    return { stateDir, args: ['history', 'redo', '--session', 'history-redo-session'] };
+  },
 } as const satisfies Record<CliOperationId, (harness: ConformanceHarness) => Promise<ScenarioInvocation>>;
 
+const RUNTIME_CONFORMANCE_SKIP = new Set<CliOperationId>([
+  'doc.toc.unmarkEntry',
+  'doc.toc.getEntry',
+  'doc.toc.editEntry',
+]);
+
 export const OPERATION_SCENARIOS = (Object.keys(SUCCESS_SCENARIOS) as CliOperationId[]).map((operationId) => {
   const scenario: OperationScenario = {
     operationId,
     success: SUCCESS_SCENARIOS[operationId],
     failure: genericInvalidArgumentFailure(operationId),
     expectedFailureCodes: ['INVALID_ARGUMENT', 'MISSING_REQUIRED'],
+    ...(RUNTIME_CONFORMANCE_SKIP.has(operationId) ? { skipRuntimeConformance: true } : {}),
   };
   return scenario;
 });

apps/cli/src/__tests__/contract-response-conformance.test.ts

@@ -25,8 +25,9 @@ describe('contract response conformance', () => {
 
   for (const scenario of OPERATION_SCENARIOS) {
     const commandKey = CLI_OPERATION_COMMAND_KEYS[scenario.operationId];
+    const runtimeTest = scenario.skipRuntimeConformance ? test.skip : test;
 
-    test(`success envelope conforms for ${scenario.operationId}`, async () => {
+    runtimeTest(`success envelope conforms for ${scenario.operationId}`, async () => {
       const invocation = await scenario.success(harness);
       const { result, envelope } = await harness.runCli(invocation.args, invocation.stateDir, invocation.stdinBytes);
 
@@ -35,9 +36,17 @@ describe('contract response conformance', () => {
 
       const success = envelope as SuccessEnvelope;
       validateOperationResponseData(scenario.operationId, success.data, commandKey);
+
+      // Regression guard: history operations must serialize payload under `result`,
+      // never under an "undefined" key from missing envelope metadata.
+      if (scenario.operationId.startsWith('doc.history.')) {
+        const data = success.data as Record<string, unknown>;
+        expect(Object.prototype.hasOwnProperty.call(data, 'result')).toBe(true);
+        expect(Object.prototype.hasOwnProperty.call(data, 'undefined')).toBe(false);
+      }
     });
 
-    test(`failure envelope conforms for ${scenario.operationId}`, async () => {
+    runtimeTest(`failure envelope conforms for ${scenario.operationId}`, async () => {
       const invocation = await scenario.failure(harness);
       const { result, envelope } = await harness.runCli(invocation.args, invocation.stateDir, invocation.stdinBytes);
 

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

@@ -117,6 +117,11 @@ export const SUCCESS_VERB: Record<CliExposedOperationId, string> = {
   'toc.configure': 'configured table of contents',
   'toc.update': 'updated table of contents',
   'toc.remove': 'removed table of contents',
+  'toc.markEntry': 'marked table of contents entry',
+  'toc.unmarkEntry': 'unmarked table of contents entry',
+  'toc.listEntries': 'listed table of contents entries',
+  'toc.getEntry': 'resolved table of contents entry',
+  'toc.editEntry': 'edited table of contents entry',
   'query.match': 'matched selectors',
   'mutations.preview': 'previewed mutations',
   'mutations.apply': 'applied mutations',
@@ -163,6 +168,9 @@ export const SUCCESS_VERB: Record<CliExposedOperationId, string> = {
   'tables.get': 'resolved table',
   'tables.getCells': 'listed cells',
   'tables.getProperties': 'resolved table properties',
+  'history.get': 'retrieved history state',
+  'history.undo': 'undid last change',
+  'history.redo': 'redid last change',
 };
 
 // ---------------------------------------------------------------------------
@@ -239,6 +247,11 @@ export const OUTPUT_FORMAT: Record<CliExposedOperationId, OutputFormat> = {
   'toc.configure': 'plain',
   'toc.update': 'plain',
   'toc.remove': 'plain',
+  'toc.markEntry': 'plain',
+  'toc.unmarkEntry': 'plain',
+  'toc.listEntries': 'plain',
+  'toc.getEntry': 'plain',
+  'toc.editEntry': 'plain',
   'query.match': 'plain',
   'mutations.preview': 'plain',
   'mutations.apply': 'plain',
@@ -285,6 +298,9 @@ export const OUTPUT_FORMAT: Record<CliExposedOperationId, OutputFormat> = {
   'tables.get': 'tableInfo',
   'tables.getCells': 'tableCellList',
   'tables.getProperties': 'tablePropertiesInfo',
+  'history.get': 'plain',
+  'history.undo': 'plain',
+  'history.redo': 'plain',
 };
 
 // ---------------------------------------------------------------------------
@@ -345,6 +361,11 @@ export const RESPONSE_ENVELOPE_KEY: Record<CliExposedOperationId, string | null>
   'toc.configure': 'result',
   'toc.update': 'result',
   'toc.remove': 'result',
+  'toc.markEntry': 'result',
+  'toc.unmarkEntry': 'result',
+  'toc.listEntries': 'result',
+  'toc.getEntry': 'result',
+  'toc.editEntry': 'result',
   'query.match': 'result',
   'mutations.preview': 'result',
   'mutations.apply': 'result',
@@ -391,6 +412,9 @@ export const RESPONSE_ENVELOPE_KEY: Record<CliExposedOperationId, string | null>
   'tables.get': 'result',
   'tables.getCells': 'result',
   'tables.getProperties': 'result',
+  'history.get': 'result',
+  'history.undo': 'result',
+  'history.redo': 'result',
 };
 
 // ---------------------------------------------------------------------------
@@ -479,6 +503,11 @@ export const OPERATION_FAMILY: Record<CliExposedOperationId, OperationFamily> =
   'toc.configure': 'toc',
   'toc.update': 'toc',
   'toc.remove': 'toc',
+  'toc.markEntry': 'toc',
+  'toc.unmarkEntry': 'toc',
+  'toc.listEntries': 'query',
+  'toc.getEntry': 'query',
+  'toc.editEntry': 'toc',
   'query.match': 'query',
   'mutations.preview': 'general',
   'mutations.apply': 'general',
@@ -525,4 +554,7 @@ export const OPERATION_FAMILY: Record<CliExposedOperationId, OperationFamily> =
   'tables.get': 'tables',
   'tables.getCells': 'tables',
   'tables.getProperties': 'tables',
+  'history.get': 'query',
+  'history.undo': 'general',
+  'history.redo': 'general',
 };

apps/cli/src/cli/types.ts

@@ -124,6 +124,7 @@ export type CliCategory =
   | 'comments'
   | 'trackChanges'
   | 'capabilities'
+  | 'history'
   | 'lifecycle'
   | 'session'
   | 'introspection';

apps/cli/src/lib/document.ts

@@ -43,7 +43,11 @@ type EditorModule = {
   };
 };
 
-const EDITOR_IMPORT_CANDIDATES = ['@superdoc/super-editor', 'superdoc/super-editor'] as const;
+const EDITOR_IMPORT_CANDIDATES = [
+  new URL('../../../../packages/super-editor/src/index.js', import.meta.url).href,
+  '@superdoc/super-editor',
+  'superdoc/super-editor',
+] as const;
 let cachedEditorModule: EditorModule | null = null;
 
 async function loadEditorModule(): Promise<EditorModule> {

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

@@ -225,6 +225,14 @@ function mapTocError(operationId: CliExposedOperationId, error: unknown, code: s
     return new CliError('INVALID_ARGUMENT', message, { operationId, details });
   }
 
+  if (code === 'INVALID_INPUT') {
+    return new CliError('INVALID_INPUT', message, { operationId, details });
+  }
+
+  if (code === 'CAPABILITY_UNAVAILABLE') {
+    return new CliError('CAPABILITY_UNAVAILABLE', message, { operationId, details });
+  }
+
   if (code === 'COMMAND_UNAVAILABLE') {
     return new CliError('COMMAND_FAILED', message, { operationId, details });
   }
@@ -443,6 +451,12 @@ export function mapFailedReceipt(operationId: CliExposedOperationId, result: unk
     if (failureCode === 'INVALID_TARGET') {
       return new CliError('INVALID_ARGUMENT', failureMessage, { operationId, failure });
     }
+    if (failureCode === 'PAGE_NUMBERS_NOT_MATERIALIZED') {
+      return new CliError('PAGE_NUMBERS_NOT_MATERIALIZED', failureMessage, { operationId, failure });
+    }
+    if (failureCode === 'CAPABILITY_UNAVAILABLE') {
+      return new CliError('CAPABILITY_UNAVAILABLE', failureMessage, { operationId, failure });
+    }
     return new CliError('COMMAND_FAILED', failureMessage, { operationId, failure });
   }