document.ts

import { readFile, writeFile } from 'node:fs/promises';
import { createHash } from 'node:crypto';
import {
  Editor,
  BLANK_DOCX_BASE64,
  DocxEncryptionError,
  getDocumentApiAdapters,
  markdownToPmDoc,
  initPartsRuntime,
} from 'superdoc/super-editor';

import { createDocumentApi, type DocumentApi } from '@superdoc/document-api';
import { createCliDomEnvironment } from './dom-environment';
import type { CollaborationProfile } from './collaboration';
import { createCollaborationRuntime } from './collaboration';
import {
  DEFAULT_BOOTSTRAP_SETTLING_MS,
  waitForContentSettling,
  detectRoomState,
  resolveBootstrapDecision,
  claimBootstrap,
  clearBootstrapMarker,
  writeBootstrapMarker,
  detectBootstrapRace,
  type RoomState,
  type ObservedCompetitor,
  type RaceDetectionResult,
} from './bootstrap';
import { CliError } from './errors';
import { pathExists } from './guards';
import { buildHeadlessCommentBridge } from './headless-comment-bridge';
import type { ContextMetadata } from './context';
import type { CliIO, DocumentSourceMeta, ExecutionMode, UserIdentity } from './types';
import type { SessionPool } from '../host/session-pool';

export type EditorWithDoc = Editor & {
  doc: DocumentApi;
};

export interface OpenedDocument {
  editor: EditorWithDoc;
  meta: DocumentSourceMeta;
  dispose(): void;
}

/** Content override options extracted before calling Editor.open(). */
interface ContentOverrideOptions {
  markdown?: string;
  html?: string;
  plainText?: string;
}

type TrackChangesReplacementMode = 'paired' | 'independent';

/** Options passed through to Editor.open() alongside content overrides. */
export interface EditorPassThroughOptions {
  password?: string;
  modules?: {
    trackChanges?: {
      replacements?: TrackChangesReplacementMode;
    };
  };
}

interface OpenDocumentOptions {
  documentId?: string;
  ydoc?: unknown;
  collaborationProvider?: unknown;
  /** Options passed through to Editor.open() (e.g., markdown/html/plainText for content override). */
  editorOpenOptions?: ContentOverrideOptions & EditorPassThroughOptions;
  /** When set, overrides Editor's auto-detected isNewFile flag. */
  isNewFile?: boolean;
  /** Optional user identity for attribution (comments, tracked changes, collaboration presence). */
  user?: UserIdentity;
}

export interface FileOutputMeta {
  path: string;
  byteLength: number;
}

function bindCurrentDocumentApi(editor: Editor): EditorWithDoc {
  const editorWithDoc = editor as EditorWithDoc;

  // Shadow the lazy getter with an eagerly-created DocumentApi so the CLI and
  // story harnesses always dispatch against the same source-backed adapter graph.
  Object.defineProperty(editorWithDoc, 'doc', {
    configurable: true,
    value: createDocumentApi(getDocumentApiAdapters(editor)),
  });

  return editorWithDoc;
}

async function toUint8Array(data: unknown): Promise<Uint8Array> {
  if (data instanceof Uint8Array) return data;
  if (data instanceof ArrayBuffer) return new Uint8Array(data);
  if (ArrayBuffer.isView(data)) {
    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
  }
  if (typeof Blob !== 'undefined' && data instanceof Blob) {
    return new Uint8Array(await data.arrayBuffer());
  }
  if (typeof data === 'object' && data !== null && 'arrayBuffer' in data && typeof data.arrayBuffer === 'function') {
    const arrayBuffer = await data.arrayBuffer();
    return new Uint8Array(arrayBuffer);
  }

  const constructorName =
    typeof data === 'object' && data !== null && 'constructor' in data && typeof data.constructor === 'function'
      ? data.constructor.name
      : undefined;
  const objectKeys = typeof data === 'object' && data !== null ? Object.keys(data).slice(0, 8) : [];

  throw new CliError(
    'DOCUMENT_EXPORT_FAILED',
    `Exported document data is not binary (type=${typeof data}, constructor=${constructorName ?? 'unknown'}, keys=${objectKeys.join(',')}).`,
  );
}

async function readDocumentSource(doc: string, io: CliIO): Promise<{ bytes: Uint8Array; meta: DocumentSourceMeta }> {
  if (doc === '-') {
    const bytes = await io.readStdinBytes();
    if (bytes.byteLength === 0) {
      throw new CliError('MISSING_REQUIRED', 'No DOCX bytes were provided on stdin.');
    }

    return {
      bytes,
      meta: {
        source: 'stdin',
        byteLength: bytes.byteLength,
      },
    };
  }

  let bytes: Uint8Array;
  try {
    const raw = await readFile(doc);
    bytes = new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    throw new CliError('FILE_READ_ERROR', `Unable to read document: ${doc}`, {
      message,
    });
  }

  return {
    bytes,
    meta: {
      source: 'path',
      path: doc,
      byteLength: bytes.byteLength,
    },
  };
}

export async function openDocument(
  doc: string | undefined,
  io: CliIO,
  options: OpenDocumentOptions = {},
): Promise<OpenedDocument> {
  let source: Uint8Array;
  let meta: DocumentSourceMeta;

  if (doc != null) {
    const result = await readDocumentSource(doc, io);
    source = result.bytes;
    meta = result.meta;
  } else {
    source = Buffer.from(BLANK_DOCX_BASE64, 'base64');
    meta = { source: 'blank', byteLength: source.byteLength };
  }

  // Separate content overrides from options passed to Editor.open().
  // Markdown and plainText are applied post-init (DOM-free AST pipelines).
  // HTML passes through to Editor.open() directly — the CLI-provided happy-dom
  // document enables the Editor's built-in HTML init path.
  const {
    markdown: markdownOverride,
    html: htmlOverride,
    plainText: plainTextOverride,
    ...passThroughEditorOpts
  } = options.editorOpenOptions ?? {};

  // Create a DOM environment for headless HTML support (getHtml, insert HTML,
  // HTML content override). Always inject via options.document — never set globals.
  const domEnv = createCliDomEnvironment();

  // Wire headless comment/tracked-change bridge when collaboration is active.
  const hasCollaboration = options.ydoc != null && options.collaborationProvider != null;
  const commentBridge = hasCollaboration ? buildHeadlessCommentBridge(options.ydoc, options.user) : null;

  let editor: Editor;
  try {
    const isTest = process.env.NODE_ENV === 'test';
    editor = await Editor.open(Buffer.from(source), {
      documentId: options.documentId ?? meta.path ?? 'blank.docx',
      document: domEnv.document,
      isHeadless: true,
      user: options.user
        ? { name: options.user.name, email: options.user.email, image: null }
        : { id: 'cli', name: 'CLI' },
      ...(isTest ? { telemetry: { enabled: false } } : {}),
      ydoc: options.ydoc,
      ...(options.collaborationProvider != null ? { collaborationProvider: options.collaborationProvider } : {}),
      ...(options.isNewFile != null ? { isNewFile: options.isNewFile } : {}),
      // Pass through HTML override directly — happy-dom provides DOM support.
      ...(htmlOverride != null ? { html: htmlOverride } : {}),
      ...(commentBridge?.editorOptions ?? {}),
      ...passThroughEditorOpts,
    });
  } catch (error) {
    commentBridge?.dispose();
    domEnv.dispose();
    // Preserve DOCX encryption errors so callers get actionable codes
    // (e.g. DOCX_PASSWORD_REQUIRED) instead of generic DOCUMENT_OPEN_FAILED.
    if (error instanceof DocxEncryptionError) {
      throw new CliError(error.code, error.message, { source: meta });
    }
    const message = error instanceof Error ? error.message : String(error);
    throw new CliError('DOCUMENT_OPEN_FAILED', 'Failed to open document.', {
      message,
      source: meta,
    });
  }

  // Parts/runtime registration is idempotent. Re-run it here so adapter-side
  // afterCommit hooks are always wired, including in headless CLI sessions.
  initPartsRuntime(editor as never);

  // SD-3214: bridge observes ydoc.getArray('comments') and feeds remote
  // (browser-authored) metadata into the editor's CommentEntityStore so the
  // headless SDK can read text/creatorName/createdTime via doc.comments.list().
  commentBridge?.attachEditor(editor as never);

  // Apply content override post-init.
  //   - markdown: DOM-free AST pipeline
  //   - plainText: builds PM paragraphs directly, preserving all whitespace
  if (markdownOverride != null) {
    try {
      const { doc: newDoc } = markdownToPmDoc(markdownOverride, editor);
      const tr = editor.state.tr;
      tr.replaceWith(0, editor.state.doc.content.size, newDoc.content);
      editor.dispatch(tr);
    } catch (error) {
      editor.destroy();
      domEnv.dispose();
      const message = error instanceof Error ? error.message : String(error);
      throw new CliError('DOCUMENT_OPEN_FAILED', 'Failed to apply content override.', {
        message,
        source: meta,
      });
    }
  } else if (plainTextOverride != null) {
    try {
      const schema = editor.state.schema;
      const lines = plainTextOverride.split('\n');
      const paragraphs = lines.map((line) => {
        const content = line.length > 0 ? [schema.text(line)] : undefined;
        return schema.nodes.paragraph.create(null, content);
      });
      const tr = editor.state.tr;
      tr.replaceWith(0, editor.state.doc.content.size, paragraphs);
      editor.dispatch(tr);
    } catch (error) {
      editor.destroy();
      domEnv.dispose();
      const message = error instanceof Error ? error.message : String(error);
      throw new CliError('DOCUMENT_OPEN_FAILED', 'Failed to apply text content override.', {
        message,
        source: meta,
      });
    }
  }

  const editorWithDoc = bindCurrentDocumentApi(editor);

  return {
    editor: editorWithDoc,
    meta,
    dispose() {
      commentBridge?.dispose();
      editor.destroy();
      domEnv.dispose();
    },
  };
}

/**
 * Describes the outcome of the bootstrap flow for a collaborative document.
 *
 * `raceSuspected` is a best-effort signal — when true, a competing finalized
 * marker was observed shortly after seeding, strongly suggesting (but not
 * proving) that two clients both seeded. `false` does not guarantee
 * exactly-once seeding.
 */
export type BootstrapResult = {
  roomState: RoomState;
  bootstrapApplied: boolean;
  bootstrapSource?: 'doc' | 'blank';
  raceSuspected?: boolean;
  raceCompetitor?: ObservedCompetitor;
};

export async function openCollaborativeDocument(
  doc: string | undefined,
  io: CliIO,
  profile: CollaborationProfile,
  options: { editorOpenOptions?: EditorPassThroughOptions; user?: UserIdentity } = {},
): Promise<OpenedDocument & { bootstrap?: BootstrapResult }> {
  const runtime = createCollaborationRuntime(profile);

  try {
    await runtime.waitForSync();

    // SD-2138: Some providers fire "synced" before Yjs updates are fully
    // applied to local shared types. Give a brief window for the XmlFragment
    // to be populated from incoming server state before checking room state.
    await waitForContentSettling(runtime.ydoc);

    const onMissing = profile.onMissing ?? 'seedFromDoc';
    let finalRoomState = detectRoomState(runtime.ydoc);
    let decision = resolveBootstrapDecision(finalRoomState, onMissing, doc != null);

    if (decision.action === 'seed') {
      const claim = await claimBootstrap(runtime.ydoc, profile.bootstrapSettlingMs ?? DEFAULT_BOOTSTRAP_SETTLING_MS);
      if (!claim.granted) {
        // Another client won the claim race — unconditionally yield.
        // Even if the winner's marker is still pending (detectRoomState
        // returns 'empty'), the winner will finalize shortly.  Re-seeding
        // here would produce a dual-seed race.
        finalRoomState = detectRoomState(runtime.ydoc);
        decision = { action: 'join' };
      } else {
        // SD-2138: Re-check room state after the claim settling period.
        // Some providers fire "synced" before Yjs updates are fully applied,
        // so content from the server may have arrived during the settling
        // wait.  If the room is now populated, join instead of seeding —
        // seeding here would destructively overwrite existing content.
        const postClaimState = detectRoomState(runtime.ydoc);
        if (postClaimState === 'populated') {
          clearBootstrapMarker(runtime.ydoc);
          finalRoomState = postClaimState;
          decision = { action: 'join' };
        }
      }
    }

    if (decision.action === 'error') {
      throw new CliError('COLLABORATION_ROOM_EMPTY', decision.reason);
    }

    const shouldSeed = decision.action === 'seed';
    // When joining an existing room, skip local doc reading — content
    // comes from the Yjs document, not from the local file path.
    const docForEditor = shouldSeed ? doc : undefined;
    const opened = await openDocument(docForEditor, io, {
      documentId: profile.documentId,
      ydoc: runtime.ydoc,
      collaborationProvider: runtime.provider,
      // When seeding from a document, we need isNewFile: false so that
      // #initComments() runs and emits commentsLoaded, pushing comments to Y.Array.
      isNewFile: shouldSeed && !docForEditor,
      editorOpenOptions: options.editorOpenOptions,
      user: options.user,
    });

    let raceDetection: RaceDetectionResult | undefined;
    if (shouldSeed) {
      writeBootstrapMarker(runtime.ydoc, decision.source);
      raceDetection = await detectBootstrapRace(runtime.ydoc);
    }

    const bootstrap: BootstrapResult = {
      roomState: finalRoomState,
      bootstrapApplied: shouldSeed,
      bootstrapSource: shouldSeed ? decision.source : undefined,
      raceSuspected: raceDetection?.raceSuspected,
      raceCompetitor: raceDetection?.raceSuspected ? raceDetection.competitor : undefined,
    };
    return {
      editor: opened.editor,
      meta: opened.meta,
      bootstrap,
      dispose() {
        try {
          opened.dispose();
        } finally {
          runtime.dispose();
        }
      },
    };
  } catch (error) {
    runtime.dispose();
    throw error;
  }
}

export async function openSessionDocument(
  doc: string,
  io: CliIO,
  metadata: Pick<
    ContextMetadata,
    'contextId' | 'sessionType' | 'collaboration' | 'sourcePath' | 'workingDocPath' | 'user' | 'revision'
  >,
  options: {
    sessionId?: string;
    executionMode?: ExecutionMode;
    sessionPool?: SessionPool;
  } = {},
): Promise<OpenedDocument> {
  const { executionMode, sessionPool, sessionId } = options;

  // Host mode: always go through pool (local AND collab)
  if (executionMode === 'host' && sessionPool) {
    const resolvedSessionId = sessionId ?? metadata.contextId;
    return sessionPool.acquire(
      resolvedSessionId,
      {
        sessionType: metadata.sessionType,
        workingDocPath: metadata.workingDocPath ?? doc,
        metadataRevision: metadata.revision,
        user: metadata.user,
        collaboration: metadata.collaboration,
      },
      io,
    );
  }

  // Oneshot mode: open fresh, caller is responsible for dispose
  if (metadata.sessionType === 'collab') {
    if (!metadata.collaboration) {
      throw new CliError('COMMAND_FAILED', 'Session is marked as collaborative but has no collaboration profile.');
    }
    return openCollaborativeDocument(doc, io, metadata.collaboration, { user: metadata.user });
  }

  return openDocument(doc, io, { user: metadata.user });
}

export async function getFileChecksum(path: string): Promise<string> {
  let bytes: Uint8Array;
  try {
    const data = await readFile(path);
    bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    throw new CliError('FILE_READ_ERROR', `Failed to read file checksum: ${path}`, {
      message,
    });
  }

  return createHash('sha256').update(bytes).digest('hex');
}

export type OptionalExportResult = {
  output?: { path: string; byteLength: number };
  warning?: {
    code: string;
    path: string;
    message: string;
  };
};

/**
 * Attempts an optional session export, returning structured success/warning
 * data instead of throwing on failure.
 *
 * @param editor - The editor instance to export from
 * @param io - CLI I/O for diagnostic warnings
 * @param outPath - Optional output path; returns `undefined` when absent
 * @param force - Whether to overwrite an existing file
 * @returns Export result with output or warning metadata, or `undefined` if no path
 */
export async function exportOptionalSessionOutput(
  editor: EditorWithDoc,
  io: CliIO,
  outPath: string | undefined,
  force: boolean,
): Promise<OptionalExportResult | undefined> {
  if (!outPath) return undefined;
  try {
    return { output: await exportToPath(editor, outPath, force) };
  } catch (error) {
    const code = error instanceof CliError ? error.code : 'FILE_WRITE_ERROR';
    const message = error instanceof Error ? error.message : String(error);
    io.warn?.(`[warn] optional export to ${outPath} failed: ${message}\n`);
    return {
      warning: {
        code,
        path: outPath,
        message,
      },
    };
  }
}

export async function exportToPath(
  editor: Editor,
  outputPath: string,
  force = false,
  options: { isFinalDoc?: boolean } = {},
): Promise<FileOutputMeta> {
  const exists = await pathExists(outputPath);
  if (exists && !force) {
    throw new CliError('OUTPUT_EXISTS', `Output path already exists: ${outputPath}`, {
      path: outputPath,
      hint: 'Use --force to overwrite.',
    });
  }

  let exported: unknown;
  try {
    exported = await editor.exportDocument({ isFinalDoc: options.isFinalDoc });
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    throw new CliError('DOCUMENT_EXPORT_FAILED', 'Failed to export document.', {
      message,
    });
  }

  const bytes = await toUint8Array(exported);

  try {
    await writeFile(outputPath, bytes);
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    throw new CliError('FILE_WRITE_ERROR', `Failed to write output file: ${outputPath}`, {
      message,
    });
  }

  return {
    path: outputPath,
    byteLength: bytes.byteLength,
  };
}