cli.test.ts

import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import { execFile } from 'node:child_process';
import { access, copyFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import { promisify } from 'node:util';
import { run } from '../index';
import { resolveListDocFixture, resolveSourceDocFixture } from './fixtures';
import { writeListDocWithoutParaIds, writeTableOnlyDocFixture } from './unstable-list-fixture';

type RunResult = {
  code: number;
  stdout: string;
  stderr: string;
};

type TextRange = {
  kind: 'text';
  blockId: string;
  range: {
    start: number;
    end: number;
  };
};

type ListItemAddress = {
  kind: 'block';
  nodeType: 'listItem';
  nodeId: string;
};

type SuccessEnvelope<TData> = {
  ok: true;
  command: string;
  data: TData;
  meta: {
    elapsedMs: number;
  };
};

type ErrorEnvelope = {
  ok: false;
  error: {
    code: string;
    message: string;
  };
};

type MutationReceiptEnvelope = SuccessEnvelope<{
  receipt: {
    success: boolean;
    resolution?: {
      target: TextRange;
    };
  };
}>;

const TEST_DIR = join(import.meta.dir, 'fixtures-cli');
const STATE_DIR = join(TEST_DIR, 'state');
const SAMPLE_DOC = join(TEST_DIR, 'sample.docx');
const LIST_SAMPLE_DOC = join(TEST_DIR, 'lists-sample.docx');
const ENCRYPTED_DOC = join(TEST_DIR, 'encrypted.docx');
const CLI_PACKAGE_JSON_PATH = join(import.meta.dir, '../../package.json');
const REPO_ROOT = join(import.meta.dir, '../../../..');
const ENCRYPTED_FIXTURE_SOURCE = join(
  REPO_ROOT,
  'packages/super-editor/src/editors/v1/core/ooxml-encryption/fixtures/encrypted-advanced-text.docx',
);
const TRACKED_CHANGE_FIXTURE_SOURCE = join(
  REPO_ROOT,
  'packages/super-editor/src/editors/v1/tests/data/basic-tracked-change.docx',
);
const execFileAsync = promisify(execFile);
const ZIP_MAX_BUFFER_BYTES = 10 * 1024 * 1024;

async function readCliPackageVersion(): Promise<string> {
  const raw = await readFile(CLI_PACKAGE_JSON_PATH, 'utf8');
  const parsed = JSON.parse(raw) as { version?: unknown };
  if (typeof parsed.version !== 'string' || parsed.version.length === 0) {
    throw new Error('Expected apps/cli/package.json to contain a non-empty version string.');
  }
  return parsed.version;
}

async function readDocxPart(docPath: string, partPath: string): Promise<string> {
  const { stdout } = await execFileAsync('unzip', ['-p', docPath, partPath], {
    maxBuffer: ZIP_MAX_BUFFER_BYTES,
  });
  return stdout;
}

async function runCli(args: string[], stdinBytes?: Uint8Array): Promise<RunResult> {
  let stdout = '';
  let stderr = '';

  const code = await run(
    args,
    {
      stdout(message: string) {
        stdout += message;
      },
      stderr(message: string) {
        stderr += message;
      },
      async readStdinBytes() {
        return stdinBytes ?? new Uint8Array();
      },
    },
    { stateDir: STATE_DIR },
  );

  return { code, stdout, stderr };
}

function parseJsonOutput<T>(result: RunResult): T {
  const source = result.stdout.trim() || result.stderr.trim();
  if (!source) {
    throw new Error('No JSON output found.');
  }

  return JSON.parse(source) as T;
}

function asRecord(value: unknown): Record<string, unknown> | null {
  if (typeof value !== 'object' || value == null || Array.isArray(value)) return null;
  return value as Record<string, unknown>;
}

function hasPrettyProperties(node: unknown): boolean {
  const record = asRecord(node);
  if (!record) return false;
  const properties = asRecord(record.properties);
  if (!properties) return false;
  return Object.values(properties).some((value) => value != null && value !== '' && value !== false);
}

async function firstTextRange(args: string[]): Promise<TextRange> {
  // SDM/1: find returns SDNodeResult with NodeAddress. For text searches,
  // the address is block-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<{
          node?: { kind?: string; [key: string]: unknown };
          address?: { kind?: string; nodeId?: string };
        }>;
      };
    }>
  >(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.');
  }

  // 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 {
  const envelope = parseJsonOutput<
    SuccessEnvelope<{
      receipt?: {
        inserted?: Array<{ entityId?: string }>;
      };
    }>
  >(result);
  const entityId = envelope.data.receipt?.inserted?.[0]?.entityId;
  if (!entityId) {
    throw new Error('Expected inserted entity id in receipt.');
  }
  return entityId;
}

async function firstListItemAddress(args: string[]): Promise<ListItemAddress> {
  const result = await runCli(args);
  expect(result.code).toBe(0);

  const envelope = parseJsonOutput<
    SuccessEnvelope<{
      result: {
        items: Array<{ address: ListItemAddress }>;
      };
    }>
  >(result);

  const address = envelope.data.result.items[0]?.address;
  if (!address) {
    throw new Error('Expected at least one list item address from lists.list result.');
  }

  return address;
}

describe('superdoc CLI', () => {
  let cliPackageVersion = '';

  beforeAll(async () => {
    await mkdir(TEST_DIR, { recursive: true });
    await copyFile(await resolveSourceDocFixture(), SAMPLE_DOC);
    await copyFile(await resolveListDocFixture(), LIST_SAMPLE_DOC);
    await copyFile(ENCRYPTED_FIXTURE_SOURCE, ENCRYPTED_DOC);
    cliPackageVersion = await readCliPackageVersion();
  });

  beforeEach(async () => {
    await rm(STATE_DIR, { recursive: true, force: true });
  });

  afterAll(async () => {
    await rm(TEST_DIR, { recursive: true, force: true });
  });

  test('status returns inactive when no document is open', async () => {
    const result = await runCli(['status']);
    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<SuccessEnvelope<{ active: boolean }>>(result);
    expect(envelope.command).toBe('status');
    expect(envelope.data.active).toBe(false);
  });

  test('global --version prints installed CLI package version', async () => {
    const result = await runCli(['--version']);
    expect(result.code).toBe(0);
    expect(result.stderr).toBe('');
    expect(result.stdout.trim()).toBe(cliPackageVersion);
  });

  test('global -v prints installed CLI package version', async () => {
    const result = await runCli(['-v']);
    expect(result.code).toBe(0);
    expect(result.stderr).toBe('');
    expect(result.stdout.trim()).toBe(cliPackageVersion);
  });

  test('global --version takes precedence over command execution', async () => {
    const result = await runCli(['status', '--version']);
    expect(result.code).toBe(0);
    expect(result.stderr).toBe('');
    expect(result.stdout.trim()).toBe(cliPackageVersion);
  });

  test('global --help takes precedence over --version', async () => {
    const result = await runCli(['--help', '--version']);
    expect(result.code).toBe(0);
    expect(result.stdout).toContain('Usage: superdoc <command> [options]');
  });

  test('commands without <doc> require an active context', async () => {
    const result = await runCli(['find', '--type', 'text', '--pattern', 'Wilde']);
    expect(result.code).toBe(1);

    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('NO_ACTIVE_DOCUMENT');
  });

  test('info returns required contract fields', async () => {
    const result = await runCli(['info', SAMPLE_DOC]);
    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<
      SuccessEnvelope<{
        document: { source: string; revision: number };
        counts: { words: number; paragraphs: number };
        capabilities: { canFind: boolean };
      }>
    >(result);

    expect(envelope.ok).toBe(true);
    expect(envelope.command).toBe('info');
    expect(envelope.data.document.source).toBe('path');
    expect(envelope.data.document.revision).toBe(0);
    expect(envelope.data.counts.words).toBeGreaterThan(0);
    expect(envelope.data.counts.paragraphs).toBeGreaterThan(0);
    expect(envelope.data.capabilities.canFind).toBe(true);
    expect(envelope.meta.elapsedMs).toBeGreaterThanOrEqual(0);
  });

  test('info pretty includes revision summary and outline section when available', async () => {
    const jsonResult = await runCli(['info', SAMPLE_DOC]);
    expect(jsonResult.code).toBe(0);

    const jsonEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        outline: Array<{ level: number; text: string; nodeId: string }>;
      }>
    >(jsonResult);

    const prettyResult = await runCli(['info', SAMPLE_DOC, '--output', 'pretty']);
    expect(prettyResult.code).toBe(0);
    expect(prettyResult.stdout).toContain('Revision 0:');
    expect(prettyResult.stdout).toContain('words');
    if (jsonEnvelope.data.outline.length > 0) {
      expect(prettyResult.stdout).toContain('Outline:');
    }
  });

  test('describe returns contract overview', async () => {
    const result = await runCli(['describe']);
    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<
      SuccessEnvelope<{
        contractVersion: string;
        operationCount: number;
        operations: Array<{ id: string; command: string[] }>;
      }>
    >(result);

    expect(envelope.command).toBe('describe');
    expect(envelope.data.contractVersion.length).toBeGreaterThan(0);
    expect(envelope.data.operationCount).toBeGreaterThan(0);
    expect(envelope.data.operations.some((operation) => operation.id === 'doc.find')).toBe(true);
  });

  test('describe command returns one operation by id', async () => {
    const result = await runCli(['describe', 'command', 'doc.find']);
    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<
      SuccessEnvelope<{
        contractVersion: string;
        operation: {
          id: string;
          command: string[];
        };
      }>
    >(result);

    expect(envelope.command).toBe('describe command');
    expect(envelope.data.contractVersion.length).toBeGreaterThan(0);
    expect(envelope.data.operation.id).toBe('doc.find');
    expect(envelope.data.operation.command).toEqual(['find']);
  });

  test('describe command pretty prints parameters and constraints', async () => {
    const result = await runCli(['describe', 'command', 'doc.find', '--output', 'pretty']);
    expect(result.code).toBe(0);
    expect(result.stdout).toContain('Parameters:');
    expect(result.stdout).toContain('--session');
    expect(result.stdout).toContain('--limit');
    expect(result.stdout).toContain('Constraints:');
  });

  test('describe command pretty labels operation positional args by name', async () => {
    const result = await runCli(['describe', 'command', 'doc.describeCommand', '--output', 'pretty']);
    expect(result.code).toBe(0);
    expect(result.stdout).toContain('<operationId>');
    expect(result.stdout).not.toContain('<doc>  Document path or stdin');
  });

  test('describe command pretty labels session ids as positional ids', async () => {
    const result = await runCli(['describe', 'command', 'doc.session.save', '--output', 'pretty']);
    expect(result.code).toBe(0);
    expect(result.stdout).toContain('<sessionId>');
    expect(result.stdout).not.toContain('<doc>  Document path or stdin');
  });

  test('describe command doc.insert includes --target and --value flags', async () => {
    const result = await runCli(['describe', 'command', 'doc.insert', '--output', 'pretty']);
    expect(result.code).toBe(0);
    expect(result.stdout).toContain('--target');
    expect(result.stdout).toContain('--value');
  });

  test('call executes an operation from canonical input payload', async () => {
    const result = await runCli([
      'call',
      'doc.find',
      '--input-json',
      JSON.stringify({
        doc: SAMPLE_DOC,
        query: {
          select: {
            type: 'text',
            pattern: 'Wilde',
            mode: 'contains',
          },
          limit: 1,
        },
      }),
    ]);
    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<
      SuccessEnvelope<{
        operationId: string;
        result: {
          query: {
            select: {
              type: string;
            };
          };
          document: {
            source: string;
          };
        };
      }>
    >(result);

    expect(envelope.command).toBe('call');
    expect(envelope.data.operationId).toBe('doc.find');
    expect(envelope.data.result.query.select.type).toBe('text');
    expect(envelope.data.result.document.source).toBe('path');
  });

  test('call resolves operation ids from command-key shorthand', async () => {
    const result = await runCli([
      'call',
      'find',
      '--input-json',
      JSON.stringify({
        doc: SAMPLE_DOC,
        query: {
          select: {
            type: 'text',
            pattern: 'Wilde',
          },
        },
      }),
    ]);
    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<
      SuccessEnvelope<{
        operationId: string;
      }>
    >(result);
    expect(envelope.data.operationId).toBe('doc.find');
  });

  test('call supports operations with non-doc positional kind:"doc" params', async () => {
    const result = await runCli([
      'call',
      'doc.describeCommand',
      '--input-json',
      JSON.stringify({
        operationId: 'doc.find',
      }),
    ]);
    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<
      SuccessEnvelope<{
        operationId: string;
        result: {
          operation: {
            id: string;
          };
        };
      }>
    >(result);
    expect(envelope.data.operationId).toBe('doc.describeCommand');
    expect(envelope.data.result.operation.id).toBe('doc.find');
  });

  test('call supports alias command keys with spaces', async () => {
    const sessionId = 'call-session-use-alias';
    const openResult = await runCli(['open', SAMPLE_DOC, '--session', sessionId]);
    expect(openResult.code).toBe(0);

    const callResult = await runCli([
      'call',
      'session',
      'use',
      '--input-json',
      JSON.stringify({
        sessionId,
      }),
    ]);
    expect(callResult.code).toBe(0);

    const envelope = parseJsonOutput<
      SuccessEnvelope<{
        operationId: string;
        result: {
          activeSessionId: string;
        };
      }>
    >(callResult);
    expect(envelope.data.operationId).toBe('doc.session.setDefault');
    expect(envelope.data.result.activeSessionId).toBe(sessionId);

    const closeResult = await runCli(['close', '--session', sessionId, '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('call doc.open accepts doc + sessionId in input payload', async () => {
    const sessionId = 'call-open-with-session-id';

    const openCall = await runCli([
      'call',
      'doc.open',
      '--input-json',
      JSON.stringify({
        doc: SAMPLE_DOC,
        sessionId,
      }),
    ]);
    expect(openCall.code).toBe(0);

    const openEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        operationId: string;
        result: {
          contextId: string;
          active: boolean;
        };
      }>
    >(openCall);
    expect(openEnvelope.data.operationId).toBe('doc.open');
    expect(openEnvelope.data.result.contextId).toBe(sessionId);
    expect(openEnvelope.data.result.active).toBe(true);

    const closeResult = await runCli(['close', '--session', sessionId, '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('call doc.save and doc.close use active session when input.sessionId is omitted', async () => {
    const sessionId = 'call-save-close-active-session';
    const savedOut = join(TEST_DIR, 'call-save-close-active-session.docx');

    const openResult = await runCli(['open', SAMPLE_DOC, '--session', sessionId]);
    expect(openResult.code).toBe(0);

    const saveCall = await runCli([
      'call',
      'doc.save',
      '--input-json',
      JSON.stringify({
        out: savedOut,
        force: true,
      }),
    ]);
    expect(saveCall.code).toBe(0);

    const closeCall = await runCli([
      'call',
      'doc.close',
      '--input-json',
      JSON.stringify({
        discard: true,
      }),
    ]);
    expect(closeCall.code).toBe(0);
  });

  test('call rejects mixing stateless doc input with session targets', async () => {
    const result = await runCli([
      'call',
      'doc.find',
      '--input-json',
      JSON.stringify({
        doc: SAMPLE_DOC,
        sessionId: 'mixed-mode-session',
        query: {
          select: {
            type: 'text',
            pattern: 'Wilde',
          },
        },
      }),
    ]);
    expect(result.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('INVALID_ARGUMENT');
    expect(envelope.error.message).toContain('stateless input.doc cannot be combined');
  });

  test('call executes direct text-mutation operations without token round-trip semantics drift', async () => {
    const source = join(TEST_DIR, 'call-insert-source.docx');
    const out = join(TEST_DIR, 'call-insert-out.docx');
    await copyFile(SAMPLE_DOC, source);

    const callResult = await runCli([
      'call',
      'doc.insert',
      '--input-json',
      JSON.stringify({
        doc: source,
        value: 'CALL_INSERT_TOKEN_1597',
        out,
      }),
    ]);
    expect(callResult.code).toBe(0);

    const envelope = parseJsonOutput<
      SuccessEnvelope<{
        operationId: string;
        result: {
          document: { source: string };
          receipt: { success: boolean };
        };
      }>
    >(callResult);
    expect(envelope.data.operationId).toBe('doc.insert');
    expect(envelope.data.result.document.source).toBe('path');
    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);
    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);
  });

  test('call only supports JSON output mode', async () => {
    const result = await runCli([
      'call',
      'doc.find',
      '--input-json',
      JSON.stringify({
        doc: SAMPLE_DOC,
        query: {
          select: {
            type: 'text',
            pattern: 'Wilde',
          },
        },
      }),
      '--output',
      'pretty',
    ]);
    expect(result.code).toBe(1);
    expect(result.stderr).toContain('INVALID_ARGUMENT');
    expect(result.stderr).toContain('call: only --output json is supported.');
  });

  test('describe command returns TARGET_NOT_FOUND for unknown operation', async () => {
    const result = await runCli(['describe', 'command', 'doc.missing']);
    expect(result.code).toBe(1);

    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('TARGET_NOT_FOUND');
  });

  test('find supports run node type', async () => {
    const result = await runCli(['find', SAMPLE_DOC, '--type', 'run', '--limit', '1']);
    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<
      SuccessEnvelope<{
        result: {
          total: number;
          items: Array<{ address: { kind: string; nodeType: string } }>;
        };
      }>
    >(result);

    expect(envelope.ok).toBe(true);
    expect(envelope.command).toBe('find');
    expect(envelope.data.result.total).toBeGreaterThan(0);
    expect(envelope.data.result.items[0].node.kind).toBe('run');
  });

  test('find rejects legacy query.include payloads', async () => {
    const result = await runCli([
      'find',
      SAMPLE_DOC,
      '--query-json',
      JSON.stringify({
        select: { type: 'text', pattern: 'Wilde' },
        include: ['context'],
      }),
    ]);
    expect(result.code).toBe(1);

    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('VALIDATION_ERROR');
    expect(envelope.error.message).toContain('query.include');
  });

  test('find text queries return block addresses with node projections', async () => {
    const result = await runCli([
      'find',
      SAMPLE_DOC,
      '--query-json',
      JSON.stringify({
        select: { type: 'text', pattern: 'Wilde' },
        limit: 1,
      }),
    ]);
    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<
      SuccessEnvelope<{
        result: {
          items?: Array<{
            node?: { kind?: string };
            address?: { kind?: string; nodeType?: string; nodeId?: string };
          }>;
        };
      }>
    >(result);

    const firstItem = envelope.data.result.items?.[0];
    expect(firstItem).toBeDefined();
    expect(firstItem?.address?.kind).toBe('block');
    expect(firstItem?.address?.nodeType).toBeDefined();
    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', 'node', '--node-type', 'paragraph', '--limit', '1']);
    expect(findResult.code).toBe(0);

    const findEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        result: {
          items: Array<{ address: Record<string, unknown> }>;
        };
      }>
    >(findResult);

    const address = findEnvelope.data.result.items[0]?.address;
    expect(address).toBeDefined();

    // find returns NodeAddress with kind: 'block' for block-level nodes
    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);
    expect(nodeEnvelope.ok).toBe(true);
    expect(nodeEnvelope.command).toBe('get-node');
    expect(nodeEnvelope.data.node).toBeDefined();
  });

  test('get-node pretty includes resolved identity and optional node details', async () => {
    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: Record<string, unknown> }>;
        };
      }>
    >(findResult);
    const address = findEnvelope.data.result.items[0]?.address;
    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(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(blockAddress)]);
    expect(jsonResult.code).toBe(0);
    const jsonEnvelope = parseJsonOutput<SuccessEnvelope<{ node: unknown }>>(jsonResult);
    const node = asRecord(jsonEnvelope.data.node);
    // 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', 'node', '--node-type', 'paragraph', '--limit', '1']);
    expect(findResult.code).toBe(0);

    const findEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        result: {
          items: Array<{ node: { kind: string }; address: { kind: string; nodeType: string; nodeId: string } }>;
        };
      }>
    >(findResult);

    const firstItem = findEnvelope.data.result.items[0];
    expect(firstItem.address.kind).toBe('block');

    const getByIdResult = await runCli([
      'get-node-by-id',
      SAMPLE_DOC,
      '--id',
      firstItem.address.nodeId,
      '--node-type',
      firstItem.node.kind,
    ]);
    expect(getByIdResult.code).toBe(0);

    const envelope = parseJsonOutput<SuccessEnvelope<{ node: unknown }>>(getByIdResult);
    expect(envelope.command).toBe('get-node-by-id');
    expect(envelope.data.node).toBeDefined();
  });

  test('get-node-by-id pretty includes resolved identity and optional node details', async () => {
    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<{ node: { kind: string }; address: { kind: string; nodeType: string; nodeId: string } }>;
        };
      }>
    >(findResult);

    const firstItem = findEnvelope.data.result.items[0];
    expect(firstItem.address.kind).toBe('block');

    const prettyResult = await runCli([
      'get-node-by-id',
      SAMPLE_DOC,
      '--id',
      firstItem.address.nodeId,
      '--node-type',
      firstItem.node.kind,
      '--output',
      'pretty',
    ]);
    expect(prettyResult.code).toBe(0);
    expect(prettyResult.stdout).toContain('Revision 0:');

    const jsonResult = await runCli([
      'get-node-by-id',
      SAMPLE_DOC,
      '--id',
      firstItem.address.nodeId,
      '--node-type',
      firstItem.node.kind,
    ]);
    expect(jsonResult.code).toBe(0);
    const jsonEnvelope = parseJsonOutput<SuccessEnvelope<{ node: unknown }>>(jsonResult);
    expect(jsonEnvelope.data.node).toBeDefined();
  });

  test('replace dry-run does not write output file', async () => {
    const target = await firstTextRange(['find', SAMPLE_DOC, '--type', 'text', '--pattern', 'Wilde']);
    const dryRunOut = join(TEST_DIR, 'dry-run.docx');

    const result = await runCli([
      'replace',
      SAMPLE_DOC,
      '--target-json',
      JSON.stringify(target),
      '--text',
      'WILDE_DRY_RUN',
      '--out',
      dryRunOut,
      '--dry-run',
    ]);

    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<SuccessEnvelope<{ dryRun: boolean }>>(result);
    expect(envelope.ok).toBe(true);
    expect(envelope.data.dryRun).toBe(true);

    await expect(access(dryRunOut)).rejects.toThrow();
  });

  test('replace writes output and updates text target', async () => {
    const replaceSource = join(TEST_DIR, 'replace-source.docx');
    const replaceOut = join(TEST_DIR, 'replace-out.docx');
    await copyFile(SAMPLE_DOC, replaceSource);

    const target = await firstTextRange(['find', replaceSource, '--type', 'text', '--pattern', 'Wilde']);

    const replaceResult = await runCli([
      'replace',
      replaceSource,
      '--target-json',
      JSON.stringify(target),
      '--text',
      'WILDE_CLI',
      '--out',
      replaceOut,
    ]);

    expect(replaceResult.code).toBe(0);

    const verifyResult = await runCli(['find', replaceOut, '--type', 'text', '--pattern', 'WILDE_CLI']);
    expect(verifyResult.code).toBe(0);

    const verifyEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        result: { total: number };
      }>
    >(verifyResult);

    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);
  });

  test('insert writes output and adds text at target', async () => {
    const insertSource = join(TEST_DIR, 'insert-source.docx');
    const insertOut = join(TEST_DIR, 'insert-out.docx');
    await copyFile(SAMPLE_DOC, insertSource);

    const target = await firstTextRange(['find', insertSource, '--type', 'text', '--pattern', 'Wilde']);
    const collapsedTarget: TextRange = {
      ...target,
      range: {
        start: target.range.start,
        end: target.range.start,
      },
    };

    const insertResult = await runCli([
      'insert',
      insertSource,
      '--target-json',
      JSON.stringify(collapsedTarget),
      '--value',
      'CLI_INSERT_TOKEN_1597',
      '--out',
      insertOut,
    ]);

    expect(insertResult.code).toBe(0);

    const verifyResult = await runCli(['find', insertOut, '--type', 'text', '--pattern', 'CLI_INSERT_TOKEN_1597']);
    expect(verifyResult.code).toBe(0);

    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);
  });

  test('insert without target defaults to document-start insertion', async () => {
    const insertSource = join(TEST_DIR, 'insert-default-source.docx');
    const insertOut = join(TEST_DIR, 'insert-default-out.docx');
    await copyFile(SAMPLE_DOC, insertSource);

    const insertResult = await runCli([
      'insert',
      insertSource,
      '--value',
      'CLI_DEFAULT_INSERT_TOKEN_1597',
      '--out',
      insertOut,
    ]);

    expect(insertResult.code).toBe(0);

    const insertEnvelope = parseJsonOutput<MutationReceiptEnvelope>(insertResult);
    expect(insertEnvelope.data.receipt.success).toBe(true);
    const target = insertEnvelope.data.receipt.resolution?.target;
    expect(target?.kind).toBe('text');
    expect(target?.blockId).toBeDefined();
    expect(target?.range.start).toBe(0);
    expect(target?.range.end).toBe(0);

    const verifyResult = await runCli([
      'find',
      insertOut,
      '--type',
      'text',
      '--pattern',
      'CLI_DEFAULT_INSERT_TOKEN_1597',
    ]);
    expect(verifyResult.code).toBe(0);

    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);
  });

  test('insert without target resolves blank first paragraphs deterministically', async () => {
    const source = join(TEST_DIR, 'insert-blank-first-source.docx');
    const blankFirstOut = join(TEST_DIR, 'insert-blank-first.docx');
    const insertOut = join(TEST_DIR, 'insert-blank-first-result.docx');
    await copyFile(SAMPLE_DOC, source);

    const createResult = await runCli([
      'create',
      'paragraph',
      source,
      '--at',
      'document-start',
      '--out',
      blankFirstOut,
    ]);
    expect(createResult.code).toBe(0);

    const insertResult = await runCli([
      'insert',
      blankFirstOut,
      '--value',
      'CLI_BLANK_INSERT_TOKEN_1597',
      '--out',
      insertOut,
    ]);
    expect(insertResult.code).toBe(0);

    const insertEnvelope = parseJsonOutput<MutationReceiptEnvelope>(insertResult);

    expect(insertEnvelope.data.receipt.success).toBe(true);
    const target = insertEnvelope.data.receipt.resolution?.target;
    expect(target?.kind).toBe('text');
    expect(target?.blockId).toBeDefined();
    expect(target?.range.start).toBe(0);
    expect(target?.range.end).toBe(0);

    const verifyResult = await runCli([
      'find',
      insertOut,
      '--type',
      'text',
      '--pattern',
      'CLI_BLANK_INSERT_TOKEN_1597',
    ]);
    expect(verifyResult.code).toBe(0);
    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);
  });

  test('insert with --block-id and --offset targets a specific block position (legacy compat)', async () => {
    const insertSource = join(TEST_DIR, 'insert-blockid-legacy-offset-source.docx');
    const insertOut = join(TEST_DIR, 'insert-blockid-legacy-offset-out.docx');
    await copyFile(SAMPLE_DOC, insertSource);

    const target = await firstTextRange(['find', insertSource, '--type', 'text', '--pattern', 'Wilde']);

    const insertResult = await runCli([
      'insert',
      insertSource,
      '--block-id',
      target.blockId,
      '--offset',
      '0',
      '--value',
      'CLI_BLOCKID_LEGACY_OFFSET_INSERT',
      '--out',
      insertOut,
    ]);

    expect(insertResult.code).toBe(0);

    const verifyResult = await runCli([
      'find',
      insertOut,
      '--type',
      'text',
      '--pattern',
      'CLI_BLOCKID_LEGACY_OFFSET_INSERT',
    ]);
    expect(verifyResult.code).toBe(0);
    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);
  });

  test('insert with --block-id and --start/--end targets a specific block position', async () => {
    const insertSource = join(TEST_DIR, 'insert-blockid-offset-source.docx');
    const insertOut = join(TEST_DIR, 'insert-blockid-offset-out.docx');
    await copyFile(SAMPLE_DOC, insertSource);

    // Get a real blockId from the document
    const target = await firstTextRange(['find', insertSource, '--type', 'text', '--pattern', 'Wilde']);

    const insertResult = await runCli([
      'insert',
      insertSource,
      '--block-id',
      target.blockId,
      '--start',
      '0',
      '--end',
      '0',
      '--value',
      'CLI_BLOCKID_OFFSET_INSERT_1597',
      '--out',
      insertOut,
    ]);

    expect(insertResult.code).toBe(0);

    const verifyResult = await runCli([
      'find',
      insertOut,
      '--type',
      'text',
      '--pattern',
      'CLI_BLOCKID_OFFSET_INSERT_1597',
    ]);
    expect(verifyResult.code).toBe(0);
    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);
  });

  test('insert with --block-id alone defaults start/end to 0', async () => {
    const insertSource = join(TEST_DIR, 'insert-blockid-only-source.docx');
    const insertOut = join(TEST_DIR, 'insert-blockid-only-out.docx');
    await copyFile(SAMPLE_DOC, insertSource);

    const target = await firstTextRange(['find', insertSource, '--type', 'text', '--pattern', 'Wilde']);

    const insertResult = await runCli([
      'insert',
      insertSource,
      '--block-id',
      target.blockId,
      '--value',
      'CLI_BLOCKID_ONLY_INSERT_1597',
      '--out',
      insertOut,
    ]);

    expect(insertResult.code).toBe(0);

    const insertEnvelope = parseJsonOutput<MutationReceiptEnvelope>(insertResult);
    // blockId alone → offset defaults to 0 → collapsed range at start
    expect(insertEnvelope.data.receipt.success).toBe(true);
    const resolvedTarget = insertEnvelope.data.receipt.resolution?.target;
    expect(resolvedTarget?.kind).toBe('text');
    expect(resolvedTarget?.range.start).toBe(0);
    expect(resolvedTarget?.range.end).toBe(0);
  });

  test('insert with --start but no --block-id returns validation error', async () => {
    const insertSource = join(TEST_DIR, 'insert-offset-no-blockid-source.docx');
    const insertOut = join(TEST_DIR, 'insert-offset-no-blockid-out.docx');
    await copyFile(SAMPLE_DOC, insertSource);

    // --start/--end without --block-id are not normalized into a target.
    // They pass through as unknown fields and are rejected by validation.
    const result = await runCli([
      'insert',
      insertSource,
      '--start',
      '5',
      '--end',
      '5',
      '--value',
      'should-fail',
      '--out',
      insertOut,
    ]);

    expect(result.code).toBe(1);
  });

  test('insert with --type html inserts HTML content into the document', async () => {
    const insertSource = join(TEST_DIR, 'insert-html-source.docx');
    const insertOut = join(TEST_DIR, 'insert-html-out.docx');
    await copyFile(SAMPLE_DOC, insertSource);

    const insertResult = await runCli([
      'insert',
      insertSource,
      '--value',
      '<p>CLI_HTML_INSERT_TOKEN</p>',
      '--type',
      'html',
      '--out',
      insertOut,
    ]);

    expect(insertResult.code).toBe(0);
    const insertEnvelope = parseJsonOutput<SuccessEnvelope<{ receipt: { success: boolean } }>>(insertResult);
    expect(insertEnvelope.data.receipt.success).toBe(true);

    const verifyResult = await runCli(['find', insertOut, '--type', 'text', '--pattern', 'CLI_HTML_INSERT_TOKEN']);
    expect(verifyResult.code).toBe(0);
    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);
  });

  test('insert tab inserts a real Word tab node', async () => {
    const outputDoc = join(TEST_DIR, 'insert-tab-output.docx');
    await rm(outputDoc, { force: true });

    const openResult = await runCli(['open']);
    expect(openResult.code).toBe(0);

    const seedResult = await runCli(['insert', '--value', 'ALPHA']);
    expect(seedResult.code).toBe(0);
    const seedEnvelope = parseJsonOutput<MutationReceiptEnvelope>(seedResult);
    const blockId = seedEnvelope.data.receipt.resolution?.target.blockId;
    expect(blockId).toBeDefined();

    const tabResult = await runCli(['insert', 'tab', '--block-id', blockId!, '--offset', '5']);
    expect(tabResult.code).toBe(0);

    const saveResult = await runCli(['save', '--out', outputDoc]);
    expect(saveResult.code).toBe(0);

    const documentXml = await readDocxPart(outputDoc, 'word/document.xml');
    expect(documentXml).toContain('<w:tab');
  });

  test('insert line-break inserts a real Word line break node', async () => {
    const outputDoc = join(TEST_DIR, 'insert-line-break-output.docx');
    await rm(outputDoc, { force: true });

    const openResult = await runCli(['open']);
    expect(openResult.code).toBe(0);

    const seedResult = await runCli(['insert', '--value', 'ALPHA']);
    expect(seedResult.code).toBe(0);
    const seedEnvelope = parseJsonOutput<MutationReceiptEnvelope>(seedResult);
    const blockId = seedEnvelope.data.receipt.resolution?.target.blockId;
    expect(blockId).toBeDefined();

    const lineBreakResult = await runCli(['insert', 'line-break', '--block-id', blockId!, '--offset', '5']);
    expect(lineBreakResult.code).toBe(0);

    const saveResult = await runCli(['save', '--out', outputDoc]);
    expect(saveResult.code).toBe(0);

    const documentXml = await readDocxPart(outputDoc, 'word/document.xml');
    expect(documentXml).toContain('<w:br');
  });

  test('insert tab without a target creates a paragraph host at structural end', async () => {
    const sourceDoc = join(TEST_DIR, 'insert-tab-table-only-source.docx');
    const outputDoc = join(TEST_DIR, 'insert-tab-table-only-output.docx');
    await rm(sourceDoc, { force: true });
    await rm(outputDoc, { force: true });
    await writeTableOnlyDocFixture(sourceDoc);

    const tabResult = await runCli(['insert', 'tab', sourceDoc, '--out', outputDoc]);
    expect(tabResult.code).toBe(0);

    const documentXml = await readDocxPart(outputDoc, 'word/document.xml');
    expect(documentXml).toContain('<w:tab');
    expect(documentXml).toMatch(/<\/w:tbl><w:p[\s\S]*<w:tab/);
  });

  test('insert line-break without a target creates a paragraph host at structural end', async () => {
    const sourceDoc = join(TEST_DIR, 'insert-line-break-table-only-source.docx');
    const outputDoc = join(TEST_DIR, 'insert-line-break-table-only-output.docx');
    await rm(sourceDoc, { force: true });
    await rm(outputDoc, { force: true });
    await writeTableOnlyDocFixture(sourceDoc);

    const lineBreakResult = await runCli(['insert', 'line-break', sourceDoc, '--out', outputDoc]);
    expect(lineBreakResult.code).toBe(0);

    const documentXml = await readDocxPart(outputDoc, 'word/document.xml');
    expect(documentXml).toContain('<w:br');
    expect(documentXml).toMatch(/<\/w:tbl><w:p[\s\S]*<w:br/);
  });

  test('session-mode mutations keep JSON output machine-clean when optional export fails', async () => {
    const occupiedOut = join(TEST_DIR, 'session-warning-existing.docx');
    await writeFile(occupiedOut, 'occupied');

    const openResult = await runCli(['open']);
    expect(openResult.code).toBe(0);

    const result = await runCli(['insert', '--value', 'JSON_CONTRACT_TOKEN', '--out', occupiedOut]);
    expect(result.code).toBe(0);
    expect(result.stderr).toBe('');

    const envelope = JSON.parse(result.stdout.trim()) as SuccessEnvelope<{
      output?: {
        path?: string;
        failed?: boolean;
        error?: { code?: string; message?: string };
      };
    }>;

    expect(envelope.command).toBe('insert');
    expect(envelope.data.output).toMatchObject({
      path: occupiedOut,
      failed: true,
      error: { code: 'OUTPUT_EXISTS' },
    });
  });

  test('create paragraph writes output and adds a new paragraph with seed text', async () => {
    const createSource = join(TEST_DIR, 'create-paragraph-source.docx');
    const createOut = join(TEST_DIR, 'create-paragraph-out.docx');
    await copyFile(SAMPLE_DOC, createSource);

    const createResult = await runCli([
      'create',
      'paragraph',
      createSource,
      '--text',
      'CLI_CREATE_PARAGRAPH_TOKEN_1597',
      '--at',
      'document-end',
      '--out',
      createOut,
    ]);

    expect(createResult.code).toBe(0);

    const createEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        result: {
          success: boolean;
          paragraph: { kind: string; nodeType: string };
          insertionPoint: TextRange;
        };
      }>
    >(createResult);

    expect(createEnvelope.data.result.success).toBe(true);
    expect(createEnvelope.data.result.paragraph.kind).toBe('block');
    expect(createEnvelope.data.result.paragraph.nodeType).toBe('paragraph');
    expect(createEnvelope.data.result.insertionPoint.kind).toBe('text');

    const verifyResult = await runCli([
      'find',
      createOut,
      '--type',
      'text',
      '--pattern',
      'CLI_CREATE_PARAGRAPH_TOKEN_1597',
    ]);
    expect(verifyResult.code).toBe(0);

    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);
  });

  test('lists list/get resolve list items in stateless mode', async () => {
    const listResult = await runCli(['lists', 'list', LIST_SAMPLE_DOC, '--limit', '2']);
    expect(listResult.code).toBe(0);

    const listEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        result: {
          total: number;
          items: Array<{ address: ListItemAddress }>;
        };
      }>
    >(listResult);
    expect(listEnvelope.data.result.total).toBeGreaterThan(0);

    const address = listEnvelope.data.result.items[0]?.address;
    expect(address).toBeDefined();
    if (!address) return;

    const getResult = await runCli(['lists', 'get', LIST_SAMPLE_DOC, '--address-json', JSON.stringify(address)]);
    expect(getResult.code).toBe(0);

    const getEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        address: ListItemAddress;
        item: { address: ListItemAddress };
      }>
    >(getResult);
    expect(getEnvelope.data.item.address.nodeId).toBe(address.nodeId);
  });

  test('lists list/get keep list item addresses stable for docs without paraIds in stateless mode', async () => {
    const source = join(TEST_DIR, 'lists-no-paraids-stateless.docx');
    await writeListDocWithoutParaIds(source);

    const address = await firstListItemAddress(['lists', 'list', source, '--limit', '1']);

    const getResult = await runCli(['lists', 'get', source, '--address-json', JSON.stringify(address)]);
    expect(getResult.code).toBe(0);

    const getEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        address: ListItemAddress;
        item: { address: ListItemAddress };
      }>
    >(getResult);
    expect(getEnvelope.data.item.address.nodeId).toBe(address.nodeId);

    const secondAddress = await firstListItemAddress(['lists', 'list', source, '--limit', '1']);
    expect(secondAddress.nodeId).toBe(address.nodeId);
  });

  test('lists list/get keep list item addresses stable for docs without paraIds in stateful mode', async () => {
    const source = join(TEST_DIR, 'lists-no-paraids-stateful.docx');
    await writeListDocWithoutParaIds(source);

    try {
      const openResult = await runCli(['open', source]);
      expect(openResult.code).toBe(0);

      const address = await firstListItemAddress(['lists', 'list', '--limit', '1']);

      const getResult = await runCli(['lists', 'get', '--address-json', JSON.stringify(address)]);
      expect(getResult.code).toBe(0);

      const getEnvelope = parseJsonOutput<
        SuccessEnvelope<{
          address: ListItemAddress;
          item: { address: ListItemAddress };
        }>
      >(getResult);
      expect(getEnvelope.data.item.address.nodeId).toBe(address.nodeId);

      const secondAddress = await firstListItemAddress(['lists', 'list', '--limit', '1']);
      expect(secondAddress.nodeId).toBe(address.nodeId);
    } finally {
      await runCli(['close', '--discard']);
    }
  });

  test('lists list pretty prints list rows', async () => {
    const result = await runCli(['lists', 'list', LIST_SAMPLE_DOC, '--limit', '2', '--output', 'pretty']);
    expect(result.code).toBe(0);
    expect(result.stdout).toContain('Revision 0:');
    expect(result.stdout).toContain('list items');
    expect(result.stdout.trim().split('\n').length).toBeGreaterThan(1);
  });

  test('lists insert writes output and returns deterministic insertionPoint', async () => {
    const source = join(TEST_DIR, 'lists-insert-source.docx');
    const out = join(TEST_DIR, 'lists-insert-out.docx');
    await copyFile(LIST_SAMPLE_DOC, source);

    const target = await firstListItemAddress(['lists', 'list', source, '--limit', '1']);
    const insertResult = await runCli([
      'lists',
      'insert',
      source,
      '--target-json',
      JSON.stringify(target),
      '--position',
      'after',
      '--text',
      'CLI_LIST_INSERT_TOKEN_1597',
      '--out',
      out,
    ]);

    expect(insertResult.code).toBe(0);

    const insertEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        result: {
          success: boolean;
          item: ListItemAddress;
          insertionPoint: TextRange;
        };
      }>
    >(insertResult);
    expect(insertEnvelope.data.result.success).toBe(true);
    expect(insertEnvelope.data.result.insertionPoint.range).toEqual({ start: 0, end: 0 });

    const verifyResult = await runCli(['find', out, '--type', 'text', '--pattern', 'CLI_LIST_INSERT_TOKEN_1597']);
    expect(verifyResult.code).toBe(0);
    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);
  });

  test('lists exit updates stateful document and invalidates list-item target', async () => {
    const openResult = await runCli(['open', LIST_SAMPLE_DOC]);
    expect(openResult.code).toBe(0);

    const target = await firstListItemAddress(['lists', 'list', '--limit', '1']);
    const exitResult = await runCli(['lists', 'exit', '--target-json', JSON.stringify(target)]);
    expect(exitResult.code).toBe(0);

    const staleGet = await runCli(['lists', 'get', '--address-json', JSON.stringify(target)]);
    expect(staleGet.code).toBe(1);
    const staleEnvelope = parseJsonOutput<ErrorEnvelope>(staleGet);
    expect(staleEnvelope.error.code).toBe('TARGET_NOT_FOUND');

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('lists detach tracked mode maps to TRACK_CHANGE_COMMAND_UNAVAILABLE', async () => {
    const source = join(TEST_DIR, 'lists-detach-source.docx');
    const out = join(TEST_DIR, 'lists-detach-out.docx');
    await copyFile(LIST_SAMPLE_DOC, source);

    const target = await firstListItemAddress(['lists', 'list', source, '--limit', '1']);
    const detachResult = await runCli([
      'lists',
      'detach',
      source,
      '--target-json',
      JSON.stringify(target),
      '--change-mode',
      'tracked',
      '--out',
      out,
    ]);

    expect(detachResult.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(detachResult);
    expect(envelope.error.code).toBe('TRACK_CHANGE_COMMAND_UNAVAILABLE');
  });

  test('delete writes output and removes inserted text target', async () => {
    const deleteSource = join(TEST_DIR, 'delete-source.docx');
    const insertedOut = join(TEST_DIR, 'delete-inserted.docx');
    const deletedOut = join(TEST_DIR, 'delete-out.docx');
    await copyFile(SAMPLE_DOC, deleteSource);

    const baseTarget = await firstTextRange(['find', deleteSource, '--type', 'text', '--pattern', 'Wilde']);
    const collapsedTarget: TextRange = {
      ...baseTarget,
      range: {
        start: baseTarget.range.start,
        end: baseTarget.range.start,
      },
    };

    const insertResult = await runCli([
      'insert',
      deleteSource,
      '--target-json',
      JSON.stringify(collapsedTarget),
      '--value',
      'CLI_DELETE_TOKEN_1597',
      '--out',
      insertedOut,
    ]);
    expect(insertResult.code).toBe(0);

    const deleteTarget = await firstTextRange([
      'find',
      insertedOut,
      '--type',
      'text',
      '--pattern',
      'CLI_DELETE_TOKEN_1597',
    ]);
    const deleteResult = await runCli([
      'delete',
      insertedOut,
      '--target-json',
      JSON.stringify(deleteTarget),
      '--out',
      deletedOut,
    ]);
    expect(deleteResult.code).toBe(0);

    const verifyResult = await runCli(['find', deletedOut, '--type', 'text', '--pattern', 'CLI_DELETE_TOKEN_1597']);
    expect(verifyResult.code).toBe(0);
    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBe(0);
  });

  test('format bold writes output for a valid text target', async () => {
    const formatSource = join(TEST_DIR, 'format-source.docx');
    const formatOut = join(TEST_DIR, 'format-out.docx');
    await copyFile(SAMPLE_DOC, formatSource);

    const target = await firstTextRange(['find', formatSource, '--type', 'text', '--pattern', 'Wilde']);

    const result = await runCli([
      'format',
      'bold',
      formatSource,
      '--target-json',
      JSON.stringify(target),
      '--out',
      formatOut,
    ]);

    expect(result.code).toBe(0);
    await access(formatOut);
  });

  test('format bold rejects collapsed target ranges', async () => {
    const formatSource = join(TEST_DIR, 'format-invalid-source.docx');
    const formatOut = join(TEST_DIR, 'format-invalid-out.docx');
    await copyFile(SAMPLE_DOC, formatSource);

    const baseTarget = await firstTextRange(['find', formatSource, '--type', 'text', '--pattern', 'Wilde']);
    const collapsedTarget: TextRange = {
      ...baseTarget,
      range: {
        start: baseTarget.range.start,
        end: baseTarget.range.start,
      },
    };

    const result = await runCli([
      'format',
      'bold',
      formatSource,
      '--target-json',
      JSON.stringify(collapsedTarget),
      '--out',
      formatOut,
    ]);

    expect(result.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('INVALID_ARGUMENT');
  });

  test('track-changes list is capability-aware', async () => {
    const result = await runCli(['track-changes', 'list', SAMPLE_DOC]);
    if (result.code === 0) {
      const envelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(result);
      expect(envelope.data.result.total).toBeGreaterThanOrEqual(0);
      return;
    }

    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('TRACK_CHANGE_COMMAND_UNAVAILABLE');
  });

  test('track-changes list pretty includes an actionable id when data is available', async () => {
    const jsonResult = await runCli(['track-changes', 'list', SAMPLE_DOC]);
    if (jsonResult.code !== 0) {
      const envelope = parseJsonOutput<ErrorEnvelope>(jsonResult);
      expect(envelope.error.code).toBe('TRACK_CHANGE_COMMAND_UNAVAILABLE');
      return;
    }

    const jsonEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        result: {
          items?: Array<{ id?: string }>;
        };
      }>
    >(jsonResult);

    const prettyResult = await runCli(['track-changes', 'list', SAMPLE_DOC, '--output', 'pretty']);
    expect(prettyResult.code).toBe(0);
    expect(prettyResult.stdout).toContain('Revision 0:');
    expect(prettyResult.stdout).toContain('tracked changes');

    const firstItemId = jsonEnvelope.data.result.items?.[0]?.id;
    if (firstItemId) {
      expect(prettyResult.stdout).toContain(firstItemId);
    }
  });

  test('track-changes get maps missing ids to TRACK_CHANGE_NOT_FOUND when capability is available', async () => {
    const listResult = await runCli(['track-changes', 'list', SAMPLE_DOC]);
    if (listResult.code !== 0) {
      const envelope = parseJsonOutput<ErrorEnvelope>(listResult);
      expect(envelope.error.code).toBe('TRACK_CHANGE_COMMAND_UNAVAILABLE');
      return;
    }

    const getResult = await runCli(['track-changes', 'get', SAMPLE_DOC, '--id', 'missing-track-change-id']);
    expect(getResult.code).toBe(1);

    const envelope = parseJsonOutput<ErrorEnvelope>(getResult);
    expect(envelope.error.code).toBe('TRACK_CHANGE_NOT_FOUND');
  });

  test('track-changes accept/reject map missing ids to TRACK_CHANGE_NOT_FOUND when capability is available', async () => {
    const listResult = await runCli(['track-changes', 'list', SAMPLE_DOC]);
    if (listResult.code !== 0) {
      const envelope = parseJsonOutput<ErrorEnvelope>(listResult);
      expect(envelope.error.code).toBe('TRACK_CHANGE_COMMAND_UNAVAILABLE');
      return;
    }

    const acceptResult = await runCli([
      'track-changes',
      'accept',
      SAMPLE_DOC,
      '--id',
      'missing-track-change-id',
      '--out',
      join(TEST_DIR, 'track-changes-accept-missing-id.docx'),
    ]);
    expect(acceptResult.code).toBe(1);
    const acceptEnvelope = parseJsonOutput<ErrorEnvelope>(acceptResult);
    expect(acceptEnvelope.error.code).toBe('TRACK_CHANGE_NOT_FOUND');

    const rejectResult = await runCli([
      'track-changes',
      'reject',
      SAMPLE_DOC,
      '--id',
      'missing-track-change-id',
      '--out',
      join(TEST_DIR, 'track-changes-reject-missing-id.docx'),
    ]);
    expect(rejectResult.code).toBe(1);
    const rejectEnvelope = parseJsonOutput<ErrorEnvelope>(rejectResult);
    expect(rejectEnvelope.error.code).toBe('TRACK_CHANGE_NOT_FOUND');
  });

  test('comments add writes output file', async () => {
    const commentsSource = join(TEST_DIR, 'comments-source.docx');
    const commentsOut = join(TEST_DIR, 'comments-out.docx');
    await copyFile(SAMPLE_DOC, commentsSource);

    const target = await firstTextRange(['find', commentsSource, '--type', 'text', '--pattern', 'Wilde']);

    const result = await runCli([
      'comments',
      'add',
      commentsSource,
      '--target-json',
      JSON.stringify(target),
      '--text',
      'CLI comment',
      '--out',
      commentsOut,
    ]);

    expect(result.code).toBe(0);
    await access(commentsOut);
  });

  test('comments add returns TARGET_NOT_FOUND for missing block targets', async () => {
    const commentsSource = join(TEST_DIR, 'comments-missing-target-source.docx');
    const commentsOut = join(TEST_DIR, 'comments-missing-target-out.docx');
    await copyFile(SAMPLE_DOC, commentsSource);

    const target = await firstTextRange(['find', commentsSource, '--type', 'text', '--pattern', 'Wilde']);
    const missingTarget: TextRange = {
      ...target,
      blockId: 'missing-block-id',
    };

    const result = await runCli([
      'comments',
      'add',
      commentsSource,
      '--target-json',
      JSON.stringify(missingTarget),
      '--text',
      'CLI comment',
      '--out',
      commentsOut,
    ]);

    expect(result.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('TARGET_NOT_FOUND');
  });

  test('comments add without --out returns MISSING_REQUIRED in stateless mode', async () => {
    const commentsSource = join(TEST_DIR, 'comments-no-out-source.docx');
    await copyFile(SAMPLE_DOC, commentsSource);

    const target = await firstTextRange(['find', commentsSource, '--type', 'text', '--pattern', 'Wilde']);

    const result = await runCli([
      'comments',
      'add',
      commentsSource,
      '--target-json',
      JSON.stringify(target),
      '--text',
      'CLI comment without out',
    ]);

    expect(result.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('MISSING_REQUIRED');
  });

  test('comments set-active is not part of the canonical CLI surface', async () => {
    const setActiveResult = await runCli(['comments', 'set-active', '--clear']);
    expect(setActiveResult.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(setActiveResult);
    expect(envelope.error.code).toBe('UNKNOWN_COMMAND');
  });

  test('comments list pretty includes comment ids for actionable output', async () => {
    const openResult = await runCli(['open', SAMPLE_DOC]);
    expect(openResult.code).toBe(0);

    const target = await firstTextRange(['find', '--type', 'text', '--pattern', 'Wilde']);
    const addResult = await runCli([
      'comments',
      'add',
      '--target-json',
      JSON.stringify(target),
      '--text',
      'Pretty comments output',
    ]);
    expect(addResult.code).toBe(0);
    const commentId = firstInsertedEntityId(addResult);

    const listPrettyResult = await runCli(['comments', 'list', '--include-resolved', 'false', '--output', 'pretty']);
    expect(listPrettyResult.code).toBe(0);
    expect(listPrettyResult.stdout).toContain('Revision ');
    expect(listPrettyResult.stdout).toContain(commentId);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('comments lifecycle commands work in stateful mode', async () => {
    const openResult = await runCli(['open', SAMPLE_DOC]);
    expect(openResult.code).toBe(0);

    const initialTarget = await firstTextRange(['find', '--type', 'text', '--pattern', 'Wilde']);

    const addResult = await runCli([
      'comments',
      'add',
      '--target-json',
      JSON.stringify(initialTarget),
      '--text',
      'Lifecycle comment',
    ]);
    expect(addResult.code).toBe(0);
    const commentId = firstInsertedEntityId(addResult);

    const editResult = await runCli(['comments', 'edit', '--id', commentId, '--text', 'Lifecycle comment (edited)']);
    expect(editResult.code).toBe(0);

    const replyResult = await runCli(['comments', 'reply', '--parent-id', commentId, '--text', 'Reply from CLI test']);
    expect(replyResult.code).toBe(0);

    const moveTarget = await firstTextRange(['find', '--type', 'text', '--pattern', 'overflow']);
    const moveResult = await runCli([
      'comments',
      'move',
      '--id',
      commentId,
      '--target-json',
      JSON.stringify(moveTarget),
    ]);
    expect(moveResult.code).toBe(0);

    const getResult = await runCli(['comments', 'get', '--id', commentId]);
    expect(getResult.code).toBe(0);
    const getEnvelope = parseJsonOutput<SuccessEnvelope<{ comment: { commentId: string } }>>(getResult);
    expect(getEnvelope.data.comment.commentId).toBe(commentId);

    const listResult = await runCli(['comments', 'list', '--include-resolved', 'false']);
    expect(listResult.code).toBe(0);
    const listEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(listResult);
    expect(listEnvelope.data.result.total).toBeGreaterThanOrEqual(1);

    const resolveResult = await runCli(['comments', 'resolve', '--id', commentId]);
    expect(resolveResult.code).toBe(0);

    const secondaryTarget = initialTarget;
    const addSecondResult = await runCli([
      'comments',
      'add',
      '--target-json',
      JSON.stringify(secondaryTarget),
      '--text',
      'Comment to remove',
    ]);
    expect(addSecondResult.code).toBe(0);
    const removableCommentId = firstInsertedEntityId(addSecondResult);

    const removeResult = await runCli(['comments', 'remove', '--id', removableCommentId]);
    expect(removeResult.code).toBe(0);

    const missingGetResult = await runCli(['comments', 'get', '--id', removableCommentId]);
    expect(missingGetResult.code).toBe(1);
    const missingGetEnvelope = parseJsonOutput<ErrorEnvelope>(missingGetResult);
    expect(missingGetEnvelope.error.code).toBe('TARGET_NOT_FOUND');

    const setInternalResult = await runCli(['comments', 'set-internal', '--id', commentId, '--is-internal', 'true']);
    expect(setInternalResult.code).toBe(0);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('stdin doc source is supported', async () => {
    const bytes = new Uint8Array(await readFile(SAMPLE_DOC));

    const result = await runCli(['info', '-'], bytes);
    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<
      SuccessEnvelope<{
        document: { source: string };
      }>
    >(result);

    expect(envelope.ok).toBe(true);
    expect(envelope.data.document.source).toBe('stdin');
  });

  test('open from stdin and save to out path keeps the session active', async () => {
    const bytes = new Uint8Array(await readFile(SAMPLE_DOC));

    const openResult = await runCli(['open', '-'], bytes);
    expect(openResult.code).toBe(0);

    const outPath = join(TEST_DIR, 'stdin-open-close.docx');
    const saveResult = await runCli(['save', '--out', outPath]);
    expect(saveResult.code).toBe(0);
    await access(outPath);

    const statusResult = await runCli(['status']);
    expect(statusResult.code).toBe(0);
    const statusEnvelope = parseJsonOutput<SuccessEnvelope<{ active: boolean }>>(statusResult);
    expect(statusEnvelope.data.active).toBe(true);
  });

  test('validation errors use structured JSON error envelope', async () => {
    const result = await runCli(['find', SAMPLE_DOC, '--query-json', '{"foo":"bar"}']);
    expect(result.code).toBe(1);

    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.ok).toBe(false);
    expect(envelope.error.code).toBe('VALIDATION_ERROR');
    expect(typeof envelope.error.message).toBe('string');
  });

  test('global output flag works when passed after command args', async () => {
    const result = await runCli(['find', SAMPLE_DOC, '--type', 'text', '--pattern', 'Wilde', '--output', 'pretty']);
    expect(result.code).toBe(0);
    expect(result.stdout).toContain('Revision 0:');
    expect(result.stdout).toContain('matches');
    expect(result.stdout).toContain('[');
    expect(result.stderr).toBe('');
  });

  test('stateful open/find/replace/save/close flow works without explicit doc', async () => {
    const openResult = await runCli(['open', SAMPLE_DOC]);
    expect(openResult.code).toBe(0);

    const target = await firstTextRange(['find', '--type', 'text', '--pattern', 'Wilde']);

    const replaceResult = await runCli(['replace', '--target-json', JSON.stringify(target), '--text', 'WILDE_CONTEXT']);
    expect(replaceResult.code).toBe(0);

    const statusResult = await runCli(['status']);
    expect(statusResult.code).toBe(0);

    const statusEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        active: boolean;
        dirty: boolean;
        document: { revision: number };
      }>
    >(statusResult);

    expect(statusEnvelope.data.active).toBe(true);
    expect(statusEnvelope.data.dirty).toBe(true);
    expect(statusEnvelope.data.document.revision).toBe(1);

    const savedOut = join(TEST_DIR, 'stateful-saved.docx');
    const saveResult = await runCli(['save', '--out', savedOut]);
    expect(saveResult.code).toBe(0);

    const statusAfterSave = await runCli(['status']);
    expect(statusAfterSave.code).toBe(0);
    const statusAfterSaveEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        active: boolean;
        dirty: boolean;
      }>
    >(statusAfterSave);
    expect(statusAfterSaveEnvelope.data.active).toBe(true);
    expect(statusAfterSaveEnvelope.data.dirty).toBe(false);

    const verifyResult = await runCli(['find', savedOut, '--type', 'text', '--pattern', 'WILDE_CONTEXT']);
    expect(verifyResult.code).toBe(0);

    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);

    const closeResult = await runCli(['close']);
    expect(closeResult.code).toBe(0);
  });

  test('stateful insert without target uses document-start default', async () => {
    const openResult = await runCli(['open', SAMPLE_DOC]);
    expect(openResult.code).toBe(0);

    const insertResult = await runCli(['insert', '--value', 'STATEFUL_DEFAULT_INSERT_1597']);
    expect(insertResult.code).toBe(0);

    const insertEnvelope = parseJsonOutput<MutationReceiptEnvelope>(insertResult);
    expect(insertEnvelope.data.receipt.success).toBe(true);
    const target = insertEnvelope.data.receipt.resolution?.target;
    expect(target?.kind).toBe('text');
    expect(target?.blockId).toBeDefined();
    expect(target?.range.start).toBe(0);
    expect(target?.range.end).toBe(0);

    const verifyResult = await runCli(['find', '--type', 'text', '--pattern', 'STATEFUL_DEFAULT_INSERT_1597']);
    expect(verifyResult.code).toBe(0);
    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('stateful insert keeps success semantics when optional --out export fails', async () => {
    const openResult = await runCli(['open', SAMPLE_DOC]);
    expect(openResult.code).toBe(0);

    const blockedOutPath = join(TEST_DIR, 'stateful-insert-blocked-output.docx');
    await writeFile(blockedOutPath, 'already-exists');

    const insertResult = await runCli([
      'insert',
      '--value',
      'STATEFUL_INSERT_EXPORT_FAILURE_1597',
      '--out',
      blockedOutPath,
    ]);
    expect(insertResult.code).toBe(0);

    const insertEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        receipt: { success: boolean };
        output?: {
          path: string;
          failed?: boolean;
          error?: { code?: string; message?: string };
        };
      }>
    >(insertResult);
    expect(insertEnvelope.data.receipt.success).toBe(true);
    expect(insertEnvelope.data.output).toMatchObject({
      path: blockedOutPath,
      failed: true,
      error: { code: 'OUTPUT_EXISTS' },
    });

    const verifyResult = await runCli(['find', '--type', 'text', '--pattern', 'STATEFUL_INSERT_EXPORT_FAILURE_1597']);
    expect(verifyResult.code).toBe(0);
    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);

    const statusResult = await runCli(['status']);
    expect(statusResult.code).toBe(0);
    const statusEnvelope = parseJsonOutput<SuccessEnvelope<{ document: { revision: number } }>>(statusResult);
    expect(statusEnvelope.data.document.revision).toBe(1);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('stateful create paragraph keeps success semantics when optional --out export fails', async () => {
    const openResult = await runCli(['open', SAMPLE_DOC]);
    expect(openResult.code).toBe(0);

    const blockedOutPath = join(TEST_DIR, 'stateful-create-blocked-output.docx');
    await writeFile(blockedOutPath, 'already-exists');

    const createResult = await runCli([
      'create',
      'paragraph',
      '--input-json',
      JSON.stringify({ text: 'STATEFUL_CREATE_EXPORT_FAILURE_1597' }),
      '--out',
      blockedOutPath,
    ]);
    expect(createResult.code).toBe(0);

    const createEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        result: { success: boolean };
        output?: {
          path: string;
          failed?: boolean;
          error?: { code?: string; message?: string };
        };
      }>
    >(createResult);
    expect(createEnvelope.data.result.success).toBe(true);
    expect(createEnvelope.data.output).toMatchObject({
      path: blockedOutPath,
      failed: true,
      error: { code: 'OUTPUT_EXISTS' },
    });

    const verifyResult = await runCli(['find', '--type', 'text', '--pattern', 'STATEFUL_CREATE_EXPORT_FAILURE_1597']);
    expect(verifyResult.code).toBe(0);
    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);

    const statusResult = await runCli(['status']);
    expect(statusResult.code).toBe(0);
    const statusEnvelope = parseJsonOutput<SuccessEnvelope<{ document: { revision: number } }>>(statusResult);
    expect(statusEnvelope.data.document.revision).toBe(1);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('close requires explicit save or discard when context is dirty', async () => {
    await runCli(['open', SAMPLE_DOC]);

    const target = await firstTextRange(['find', '--type', 'text', '--pattern', 'Wilde']);
    await runCli(['replace', '--target-json', JSON.stringify(target), '--text', 'WILDE_DIRTY']);

    const closeResult = await runCli(['close']);
    expect(closeResult.code).toBe(1);

    const closeEnvelope = parseJsonOutput<ErrorEnvelope>(closeResult);
    expect(closeEnvelope.error.code).toBe('DIRTY_CLOSE_REQUIRES_DECISION');

    const discardResult = await runCli(['close', '--discard']);
    expect(discardResult.code).toBe(0);
  });

  test('open without --session creates new session ids', async () => {
    const firstOpen = await runCli(['open', SAMPLE_DOC]);
    expect(firstOpen.code).toBe(0);

    const firstEnvelope = parseJsonOutput<SuccessEnvelope<{ contextId: string }>>(firstOpen);
    const firstContextId = firstEnvelope.data.contextId;
    expect(firstContextId.length).toBeGreaterThan(0);

    const secondOpen = await runCli(['open', SAMPLE_DOC]);
    expect(secondOpen.code).toBe(0);

    const secondEnvelope = parseJsonOutput<SuccessEnvelope<{ contextId: string }>>(secondOpen);
    const secondContextId = secondEnvelope.data.contextId;
    expect(secondContextId.length).toBeGreaterThan(0);
    expect(secondContextId).not.toBe(firstContextId);

    const listResult = await runCli(['session', 'list']);
    expect(listResult.code).toBe(0);
    const listEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        sessions: Array<{ sessionId: string }>;
      }>
    >(listResult);
    expect(listEnvelope.data.sessions.map((item) => item.sessionId)).toEqual(
      expect.arrayContaining([firstContextId, secondContextId]),
    );
  });

  test('status and session list include sessionType metadata', async () => {
    const openResult = await runCli(['open', SAMPLE_DOC, '--session', 'local-a']);
    expect(openResult.code).toBe(0);

    const statusResult = await runCli(['status', '--session', 'local-a']);
    expect(statusResult.code).toBe(0);
    const statusEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        sessionType: string;
      }>
    >(statusResult);
    expect(statusEnvelope.data.sessionType).toBe('local');

    const listResult = await runCli(['session', 'list']);
    expect(listResult.code).toBe(0);
    const listEnvelope = parseJsonOutput<
      SuccessEnvelope<{
        sessions: Array<{ sessionId: string; sessionType: string }>;
      }>
    >(listResult);

    const localSession = listEnvelope.data.sessions.find((session) => session.sessionId === 'local-a');
    expect(localSession?.sessionType).toBe('local');
  });

  test('open rejects unsupported collaboration payload fields', async () => {
    const invalidProvider = await runCli([
      'open',
      SAMPLE_DOC,
      '--collaboration-json',
      JSON.stringify({ providerType: 'invalid', url: 'ws://localhost:1234' }),
    ]);
    expect(invalidProvider.code).toBe(1);
    const invalidProviderEnvelope = parseJsonOutput<ErrorEnvelope>(invalidProvider);
    expect(invalidProviderEnvelope.error.code).toBe('VALIDATION_ERROR');

    const unsupportedToken = await runCli([
      'open',
      SAMPLE_DOC,
      '--collaboration-json',
      JSON.stringify({ providerType: 'hocuspocus', url: 'ws://localhost:1234', token: 'raw-secret' }),
    ]);
    expect(unsupportedToken.code).toBe(1);
    const unsupportedTokenEnvelope = parseJsonOutput<ErrorEnvelope>(unsupportedToken);
    expect(unsupportedTokenEnvelope.error.code).toBe('VALIDATION_ERROR');
  });

  test('open rejects primitive --collaboration-json with --on-missing', async () => {
    const result = await runCli(['open', SAMPLE_DOC, '--collaboration-json', '"oops"', '--on-missing', 'blank']);
    expect(result.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('VALIDATION_ERROR');
  });

  test('open rejects array --collaboration-json', async () => {
    const result = await runCli(['open', SAMPLE_DOC, '--collaboration-json', '[1, 2]']);
    expect(result.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('VALIDATION_ERROR');
  });

  test('open with collaboration does not require a doc path', async () => {
    const result = await runCli([
      'open',
      '--collaboration-json',
      JSON.stringify({
        providerType: 'hocuspocus',
        url: 'ws://127.0.0.1:9',
        syncTimeoutMs: 1,
      }),
      '--session',
      'collab-no-doc',
    ]);

    expect(result.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    // Verify we no longer fail argument validation for a missing document path.
    expect(envelope.error.code).not.toBe('MISSING_REQUIRED');
  });

  test('open with --session is idempotent for the same session id', async () => {
    const firstOpen = await runCli(['open', SAMPLE_DOC, '--session', 'draft-a']);
    expect(firstOpen.code).toBe(0);

    const secondOpen = await runCli(['open', SAMPLE_DOC, '--session', 'draft-a']);
    expect(secondOpen.code).toBe(0);

    const closeResult = await runCli(['close', '--discard', '--session', 'draft-a']);
    expect(closeResult.code).toBe(0);
  });

  test('expected revision protects stateful mutate commands', async () => {
    await runCli(['open', SAMPLE_DOC]);

    const target = await firstTextRange(['find', '--type', 'text', '--pattern', 'Wilde']);

    const mismatch = await runCli([
      'replace',
      '--target-json',
      JSON.stringify(target),
      '--text',
      'WILDE_REV',
      '--expected-revision',
      '1',
    ]);
    expect(mismatch.code).toBe(1);

    const mismatchEnvelope = parseJsonOutput<ErrorEnvelope>(mismatch);
    expect(mismatchEnvelope.error.code).toBe('REVISION_MISMATCH');

    const success = await runCli([
      'replace',
      '--target-json',
      JSON.stringify(target),
      '--text',
      'WILDE_REV',
      '--expected-revision',
      '0',
    ]);
    expect(success.code).toBe(0);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('session use switches default session', async () => {
    const alphaOpen = await runCli(['open', SAMPLE_DOC, '--session', 'alpha']);
    expect(alphaOpen.code).toBe(0);

    const betaOpen = await runCli(['open', SAMPLE_DOC, '--session', 'beta']);
    expect(betaOpen.code).toBe(0);

    const statusBefore = await runCli(['status']);
    expect(statusBefore.code).toBe(0);
    const statusBeforeEnvelope = parseJsonOutput<SuccessEnvelope<{ contextId: string }>>(statusBefore);
    expect(statusBeforeEnvelope.data.contextId).toBe('beta');

    const useResult = await runCli(['session', 'use', 'alpha']);
    expect(useResult.code).toBe(0);

    const statusAfter = await runCli(['status']);
    expect(statusAfter.code).toBe(0);
    const statusAfterEnvelope = parseJsonOutput<SuccessEnvelope<{ contextId: string }>>(statusAfter);
    expect(statusAfterEnvelope.data.contextId).toBe('alpha');
  });

  test('session close closes a specific non-default session', async () => {
    await runCli(['open', SAMPLE_DOC, '--session', 'alpha']);
    await runCli(['open', SAMPLE_DOC, '--session', 'beta']);

    const closeAlpha = await runCli(['session', 'close', 'alpha', '--discard']);
    expect(closeAlpha.code).toBe(0);

    const statusResult = await runCli(['status']);
    expect(statusResult.code).toBe(0);
    const statusEnvelope = parseJsonOutput<SuccessEnvelope<{ contextId: string }>>(statusResult);
    expect(statusEnvelope.data.contextId).toBe('beta');

    const useAlpha = await runCli(['session', 'use', 'alpha']);
    expect(useAlpha.code).toBe(1);
    const useAlphaEnvelope = parseJsonOutput<ErrorEnvelope>(useAlpha);
    expect(useAlphaEnvelope.error.code).toBe('SESSION_NOT_FOUND');
  });

  test('session save persists a specific session and keeps it open', async () => {
    await runCli(['open', SAMPLE_DOC, '--session', 'alpha']);

    const insertResult = await runCli(['insert', '--session', 'alpha', '--value', 'SESSION_SAVE_TOKEN_1597']);
    expect(insertResult.code).toBe(0);

    const savedOut = join(TEST_DIR, 'session-save-alpha.docx');
    const sessionSaveResult = await runCli(['session', 'save', 'alpha', '--out', savedOut]);
    expect(sessionSaveResult.code).toBe(0);
    await access(savedOut);

    const statusResult = await runCli(['status', '--session', 'alpha']);
    expect(statusResult.code).toBe(0);
    const statusEnvelope = parseJsonOutput<SuccessEnvelope<{ active: boolean; dirty: boolean }>>(statusResult);
    expect(statusEnvelope.data.active).toBe(true);
    expect(statusEnvelope.data.dirty).toBe(false);

    const verifyResult = await runCli(['find', savedOut, '--type', 'text', '--pattern', 'SESSION_SAVE_TOKEN_1597']);
    expect(verifyResult.code).toBe(0);
    const verifyEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(verifyResult);
    expect(verifyEnvelope.data.result.total).toBeGreaterThan(0);
  });

  test('save --mode final exports accepted OOXML instead of copying review-preserving revisions', async () => {
    const trackedSource = join(TEST_DIR, 'save-final-source.docx');
    const savedOut = join(TEST_DIR, 'save-final-output.docx');
    await copyFile(TRACKED_CHANGE_FIXTURE_SOURCE, trackedSource);

    const openResult = await runCli(['open', trackedSource, '--session', 'final-export']);
    expect(openResult.code).toBe(0);

    const saveResult = await runCli([
      'save',
      '--session',
      'final-export',
      '--mode',
      'final',
      '--out',
      savedOut,
      '--force',
    ]);
    expect(saveResult.code).toBe(0);

    const saveEnvelope = parseJsonOutput<SuccessEnvelope<{ mode: string; output: { path: string } }>>(saveResult);
    expect(saveEnvelope.data.mode).toBe('final');
    expect(saveEnvelope.data.output.path).toBe(savedOut);

    const documentXml = await readDocxPart(savedOut, 'word/document.xml');
    expect(documentXml).not.toContain('<w:ins');
    expect(documentXml).not.toContain('<w:del');
  });

  test('save --in-place detects source drift unless forced', async () => {
    const driftSource = join(TEST_DIR, 'drift-source.docx');
    await copyFile(SAMPLE_DOC, driftSource);

    const openResult = await runCli(['open', driftSource]);
    expect(openResult.code).toBe(0);

    const sourceBytes = new Uint8Array(await readFile(driftSource));
    sourceBytes[0] = sourceBytes[0] === 0 ? 1 : 0;
    await writeFile(driftSource, sourceBytes);

    const saveResult = await runCli(['save', '--in-place']);
    expect(saveResult.code).toBe(1);

    const saveEnvelope = parseJsonOutput<ErrorEnvelope>(saveResult);
    expect(saveEnvelope.error.code).toBe('SOURCE_DRIFT_DETECTED');

    const forcedSave = await runCli(['save', '--in-place', '--force']);
    expect(forcedSave.code).toBe(0);
  });

  test('project context mismatch is enforced', async () => {
    const openResult = await runCli(['open', SAMPLE_DOC]);
    expect(openResult.code).toBe(0);

    const openEnvelope = parseJsonOutput<SuccessEnvelope<{ contextId: string }>>(openResult);
    const metadataPath = join(STATE_DIR, 'contexts', openEnvelope.data.contextId, 'metadata.json');

    const metadataRaw = await readFile(metadataPath, 'utf8');
    const metadata = JSON.parse(metadataRaw) as Record<string, unknown>;
    metadata.projectRoot = '/tmp/not-this-project';
    await writeFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');

    const findResult = await runCli(['find', '--type', 'text', '--pattern', 'Wilde']);
    expect(findResult.code).toBe(1);

    const findEnvelope = parseJsonOutput<ErrorEnvelope>(findResult);
    expect(findEnvelope.error.code).toBe('PROJECT_CONTEXT_MISMATCH');
  });

  // -- open --content-override / --override-type validation --

  test('open rejects --content-override without --override-type', async () => {
    const result = await runCli(['open', SAMPLE_DOC, '--content-override', '# Hello']);
    expect(result.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('INVALID_ARGUMENT');
    expect(envelope.error.message).toContain('--override-type');
  });

  test('open rejects --override-type without --content-override', async () => {
    const result = await runCli(['open', SAMPLE_DOC, '--override-type', 'markdown']);
    expect(result.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('INVALID_ARGUMENT');
    expect(envelope.error.message).toContain('--content-override');
  });

  test('open rejects invalid --override-type value', async () => {
    const result = await runCli(['open', SAMPLE_DOC, '--content-override', 'x', '--override-type', 'xml']);
    expect(result.code).toBe(1);
    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('INVALID_ARGUMENT');
    expect(envelope.error.message).toContain('markdown, html, text');
  });

  test('open with --override-type text applies content semantically', async () => {
    const openResult = await runCli([
      'open',
      SAMPLE_DOC,
      '--content-override',
      'Override text content',
      '--override-type',
      'text',
    ]);
    expect(openResult.code).toBe(0);

    // Verify the override text is actually present in the document
    const findResult = await runCli(['find', '--type', 'text', '--pattern', 'Override text content']);
    expect(findResult.code).toBe(0);
    const findEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(findResult);
    expect(findEnvelope.data.result.total).toBeGreaterThan(0);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('open with --override-type text preserves leading whitespace literally', async () => {
    const literalText = '    foo';

    const openResult = await runCli(['open', SAMPLE_DOC, '--content-override', literalText, '--override-type', 'text']);
    expect(openResult.code).toBe(0);

    const findResult = await runCli(['find', '--type', 'text', '--pattern', literalText]);
    expect(findResult.code).toBe(0);
    const findEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(findResult);
    expect(findEnvelope.data.result.total).toBeGreaterThan(0);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('open with --override-type markdown applies content semantically', async () => {
    const openResult = await runCli([
      'open',
      SAMPLE_DOC,
      '--content-override',
      '# Markdown Override Heading',
      '--override-type',
      'markdown',
    ]);
    expect(openResult.code).toBe(0);

    // Verify the markdown content is present in the document
    const findResult = await runCli(['find', '--type', 'text', '--pattern', 'Markdown Override Heading']);
    expect(findResult.code).toBe(0);
    const findEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(findResult);
    expect(findEnvelope.data.result.total).toBeGreaterThan(0);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('open with --override-type html succeeds (happy-dom provides DOM)', async () => {
    const openResult = await runCli([
      'open',
      SAMPLE_DOC,
      '--content-override',
      '<p>HTML Override</p>',
      '--override-type',
      'html',
    ]);
    expect(openResult.code).toBe(0);

    const textResult = await runCli(['get-text']);
    expect(textResult.code).toBe(0);
    const textEnvelope = parseJsonOutput<{ data: { text: string } }>(textResult);
    expect(textEnvelope.data.text).toContain('HTML Override');

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('open with --content-override empty string is accepted (not silently ignored)', async () => {
    const openResult = await runCli(['open', SAMPLE_DOC, '--content-override', '', '--override-type', 'text']);
    expect(openResult.code).toBe(0);

    // Verify original document content was replaced (find for known original text should fail)
    const findOriginal = await runCli(['find', '--type', 'text', '--pattern', 'Wilde']);
    expect(findOriginal.code).toBe(0);
    const findEnvelope = parseJsonOutput<SuccessEnvelope<{ result: { total: number } }>>(findOriginal);
    expect(findEnvelope.data.result.total).toBe(0);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('open with --user-name and --user-email succeeds', async () => {
    const openResult = await runCli([
      'open',
      SAMPLE_DOC,
      '--user-name',
      'Review Bot',
      '--user-email',
      'bot@example.com',
    ]);
    expect(openResult.code).toBe(0);

    const envelope = parseJsonOutput<SuccessEnvelope<{ active: boolean }>>(openResult);
    expect(envelope.data.active).toBe(true);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  test('open with --user-name only (no --user-email) succeeds', async () => {
    const openResult = await runCli(['open', SAMPLE_DOC, '--user-name', 'Bot']);
    expect(openResult.code).toBe(0);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  });

  // -- Encrypted document tests -----------------------------------------------

  // Encrypted tests use 30s timeout — decryption + open is ~4s and can exceed
  // bun's default 5s budget under full-suite load.
  test('open encrypted doc with --password succeeds end-to-end', async () => {
    const result = await runCli(['open', ENCRYPTED_DOC, '--password', 'test123']);
    expect(result.code).toBe(0);

    const envelope = parseJsonOutput<SuccessEnvelope<{ active: boolean }>>(result);
    expect(envelope.data.active).toBe(true);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  }, 30_000);

  test('open encrypted doc without password returns DOCX_PASSWORD_REQUIRED', async () => {
    const result = await runCli(['open', ENCRYPTED_DOC]);
    expect(result.code).toBe(1);

    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('DOCX_PASSWORD_REQUIRED');
  }, 30_000);

  test('open encrypted doc with wrong password returns DOCX_PASSWORD_INVALID', async () => {
    const result = await runCli(['open', ENCRYPTED_DOC, '--password', 'wrong']);
    expect(result.code).toBe(1);

    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('DOCX_PASSWORD_INVALID');
  }, 30_000);

  test('call doc.open with --input-json password succeeds end-to-end', async () => {
    const input = JSON.stringify({ doc: ENCRYPTED_DOC, password: 'test123' });
    const result = await runCli(['call', 'doc.open', '--input-json', input]);
    expect(result.code).toBe(0);

    const closeResult = await runCli(['close', '--discard']);
    expect(closeResult.code).toBe(0);
  }, 30_000);

  test('call doc.open with missing password returns DOCX_PASSWORD_REQUIRED', async () => {
    const input = JSON.stringify({ doc: ENCRYPTED_DOC });
    const result = await runCli(['call', 'doc.open', '--input-json', input]);
    expect(result.code).toBe(1);

    const envelope = parseJsonOutput<ErrorEnvelope>(result);
    expect(envelope.error.code).toBe('DOCX_PASSWORD_REQUIRED');
  }, 30_000);

  // -- Env-fallback precedence tests ------------------------------------------

  test('SUPERDOC_DOC_PASSWORD env var is used in direct CLI mode', async () => {
    const prevEnv = process.env.SUPERDOC_DOC_PASSWORD;
    try {
      process.env.SUPERDOC_DOC_PASSWORD = 'test123';
      // No --password flag — should fall back to env var in direct mode
      const result = await runCli(['open', ENCRYPTED_DOC]);
      expect(result.code).toBe(0);

      const closeResult = await runCli(['close', '--discard']);
      expect(closeResult.code).toBe(0);
    } finally {
      if (prevEnv != null) process.env.SUPERDOC_DOC_PASSWORD = prevEnv;
      else delete process.env.SUPERDOC_DOC_PASSWORD;
    }
  }, 30_000);

  test('explicit --password takes precedence over SUPERDOC_DOC_PASSWORD env var', async () => {
    const prevEnv = process.env.SUPERDOC_DOC_PASSWORD;
    try {
      process.env.SUPERDOC_DOC_PASSWORD = 'wrong-env-password';
      // Explicit password should override the (wrong) env password
      const result = await runCli(['open', ENCRYPTED_DOC, '--password', 'test123']);
      expect(result.code).toBe(0);

      const closeResult = await runCli(['close', '--discard']);
      expect(closeResult.code).toBe(0);
    } finally {
      if (prevEnv != null) process.env.SUPERDOC_DOC_PASSWORD = prevEnv;
      else delete process.env.SUPERDOC_DOC_PASSWORD;
    }
  }, 30_000);
});